docs: add project README and update development documentation

Add comprehensive README.md with installation, usage, architecture, and
contributing sections. Update CLAUDE.md with expanded test commands, CI
verification gate, gotchas, and dev dependency list. Clean up PRD.md
formatting. Add REUSE.toml annotation for test snapshot files.

Author: Sephyi

CLAUDE.md

@@ -70,7 +70,7 @@ Rust, TypeScript, JavaScript, Python, Go
 
 ## File Structure
 
-```
+```bash
 src/
 ├── main.rs              # Entry point
 ├── lib.rs               # Library exports
@@ -107,32 +107,45 @@ src/
 
 - Rust edition 2024, MSRV 1.85
 - License: GPL-3.0-only (REUSE compliant)
-- Dev deps: `tempfile`, `assert_cmd`, `predicates`, `wiremock`
+- Dev deps: `tempfile`, `assert_cmd`, `predicates`, `wiremock`, `insta`, `proptest`
 
 ### REUSE / SPDX Headers
 
 - All files use `reuse annotate` format: blank comment separator between SPDX lines
 - `reuse lint` — verify compliance
 - `reuse annotate --copyright "Sephyi <me@sephy.io>" --license GPL-3.0-only --year 2026 <file>` — add header
-- REUSE.toml `[[annotations]]` — only for files that can't have inline headers (e.g., Cargo.lock)
+- REUSE.toml `[[annotations]]` — for files that can't have inline headers (Cargo.lock, tests/snapshots/**)
 
-### Running Tests (when implemented)
+### Running Tests
 
 ```bash
-cargo test                    # All tests
-cargo test sanitizer          # Specific module
+cargo test                    # All tests (55 tests)
+cargo test --test sanitizer   # Specific integration test file
+cargo test --test safety      # Safety module tests
+cargo test --test context     # ContextBuilder tests
+cargo test --test commit_type # CommitType tests
 cargo test -- --nocapture     # Show println output
 ```
 
+**Important:** `cargo test sanitizer` matches test *names* across all binaries. Use `cargo test --test <name>` to select a specific integration test file.
+
 ### Building
 
 ```bash
 cargo build --release         # Optimized binary
 cargo check                   # Fast syntax check
-cargo clippy                  # Lint checks
+cargo clippy --all-targets -- -D warnings  # Lint (CI requires zero warnings)
 cargo fmt                     # Format code
 ```
 
+### CI Verification Gate
+
+Before pushing, run the full CI check locally:
+
+```bash
+cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test --all-targets
+```
+
 ### Testing Manually
 
 ```bash
@@ -151,3 +164,17 @@ git add some-file.rs
 # Auto-commit
 ./target/release/commitbee --yes
 ```
+
+### Gotchas
+
+- `gix` API: use `repo.workdir()` not `repo.work_dir()` (deprecated)
+- `CommitType::parse()` not `from_str()` — avoids clippy `should_implement_trait` warning
+- Enum variants used only via `CommitType::ALL` const need `#[allow(dead_code)]`
+- `CommitSanitizer::clean_text` has a known bug with overlapping preamble patterns (indexes modified string with original offsets) — documented, not yet fixed
+- Parallel subagents running `cargo fmt` may create unstaged changes — commit formatting separately
+- Secret pattern `sk-[a-zA-Z0-9]{48}` requires exactly 48 chars after `sk-` in test data
+
+### Markdown Conventions
+
+- No `---` horizontal rules before `#` or `##` headers (they provide their own visual separation)
+- Tables must use properly aligned columns with `| --- |` separator rows

PRD.md

@@ -13,8 +13,6 @@ SPDX-License-Identifier: GPL-3.0-only
 
 **Revision 2.1**: Enhancement review integration (2026-02-17) — incorporated evaluation harness, symbol extraction fallback ladder, cancellation contract, streaming trait abstraction, golden test fixtures, output format contracts, hook edge cases, JSON retry logic, and 12 additional refinements from verification review.
 
----
-
 ## 1. Vision
 
 > **"The commit message generator that actually understands your code."**
@@ -35,8 +33,6 @@ CommitBee is a Rust-native CLI tool that uses tree-sitter semantic analysis and
 - **v0.2.0** is a stability release: config format preserved, no breaking CLI changes.
 - **v0.3.0+** may introduce breaking changes (new config system via figment, CLI subcommand restructuring). Migration documentation will accompany any breaking release.
 
----
-
 ## 2. Competitive Landscape
 
 ### 2.1 Market Position
@@ -68,8 +64,6 @@ CommitBee is a Rust-native CLI tool that uses tree-sitter semantic analysis and
 | Custom prompt/instruction files                                | Growing (Copilot, aicommit2)  | Missing       |
 | Unit/integration tests                                         | Non-negotiable for quality.   | Zero tests    |
 
----
-
 ## 3. Architecture Requirements
 
 ### 3.1 Current Architecture Assessment
@@ -203,8 +197,6 @@ pub struct App {
 
 `generate_stream()` is required for all providers in P1 scope (FR-011, FR-012, FR-013). Providers that do not support streaming should implement `generate_stream()` by wrapping `generate()` as a single-element stream.
 
----
-
 ## 4. Feature Requirements
 
 ### 4.1 P0 — Critical (v0.2.0: Stability & Correctness)
@@ -490,8 +482,6 @@ These are bugs, panics, and missing foundations that must be fixed before any ne
 - **What**: Analyze existing commit history to match the project's commit style.
 - **Rationale**: GitHub Copilot does this. Would allow commitbee to adapt to any project's conventions.
 
----
-
 ## 5. Security Requirements
 
 ### SR-001: Secret Scanning (Enhanced)
@@ -529,8 +519,6 @@ These are bugs, panics, and missing foundations that must be fixed before any ne
 - `cargo deny` for license compliance
 - Minimize dependency tree (remove unused crates)
 
----
-
 ## 6. Performance Requirements
 
 ### PR-001: Startup Time
@@ -582,8 +570,6 @@ These are bugs, panics, and missing foundations that must be fixed before any ne
 - Git commit is only called after the user confirms the complete message. No intermediate state is written to the repository.
 - Temp files (if any) are cleaned up via RAII (`Drop` impl or `tempfile` crate auto-cleanup).
 
----
-
 ## 7. UX Requirements
 
 ### UX-001: Error Messages
@@ -665,8 +651,6 @@ Exact output behavior for key flags:
 - **`--show-prompt`**: Prints the full LLM prompt to stderr (system prompt + user prompt). API keys and secret patterns are **redacted** (replaced with `[REDACTED]`). Does not call the LLM. Exit code 0.
 - **Default (interactive)**: Displays the generated message and a confirm/edit/cancel prompt on stderr. On confirm, commits and prints the commit hash to stdout.
 
----
-
 ## 8. Testing Requirements
 
 ### TR-001: Unit Tests
@@ -759,8 +743,6 @@ A developer-facing command (`commitbee eval`) that runs the full pipeline agains
 
 `cargo fuzz` targets for the diff parser, sanitizer, and secret scanner. Priority: P2 — implement after the unit test suite (TR-001) and property tests (TR-004) are stable. Fuzz targets should be added to `fuzz/` directory following standard `cargo-fuzz` conventions.
 
----
-
 ## 9. Distribution Requirements
 
 ### DR-001: cargo install
@@ -797,8 +779,6 @@ codegen-units = 1
 opt-level = "z"  # or "s" — benchmark both
 ```
 
----
-
 ## 10. Prompt Engineering Requirements
 
 ### PE-001: System Prompt
@@ -842,8 +822,6 @@ opt-level = "z"  # or "s" — benchmark both
 - If the retry also fails, fall back to heuristic extraction: infer commit type from the diff header and file categories, extract the first coherent sentence as the commit message description.
 - Never retry more than once (avoid infinite loops with models that consistently produce invalid output).
 
----
-
 ## 11. Phased Roadmap
 
 ### Phase 1: Stability (v0.2.0)
@@ -908,8 +886,6 @@ opt-level = "z"  # or "s" — benchmark both
 - FR-057: Additional language support (feature-gated)
 - FR-058: Learning from commit history
 
----
-
 ## 12. Success Metrics
 
 | Metric                                | Target                              | How to Measure                                               |
@@ -923,8 +899,6 @@ opt-level = "z"  # or "s" — benchmark both
 | Secret leak rate                      | 0 (no secrets sent to cloud LLMs)   | Integration tests with known secret patterns                 |
 | MSRV                                  | Rust 1.85 (edition 2024)            | CI matrix build (stable + 1.85)                              |
 
----
-
 ## 13. Non-Goals (Explicit Scope Exclusions)
 
 - **GUI/TUI application** — CommitBee is CLI-first. Editor integration happens via MCP server mode, not a built-in UI.
@@ -934,8 +908,6 @@ opt-level = "z"  # or "s" — benchmark both
 - **Non-git VCS** — Jujutsu/Mercurial support is not a priority. Git covers > 95% of the market.
 - **Shell snippet detection** — Commit messages are never executed by git; shell injection via commit message content is not a real attack vector. Standard sanitization (FR-001, FR-007) is sufficient.
 
----
-
 ## Appendix A: Competitive Feature Matrix
 
 | Feature               | commitbee | opencommit | aicommits | aicommit2 | rusty-commit | cocogitto |
@@ -955,8 +927,6 @@ opt-level = "z"  # or "s" — benchmark both
 | **Version bumping**   | Future    | No         | No        | No        | No           | Yes       |
 | **Monorepo**          | Future    | No         | No        | No        | No           | Yes       |
 
----
-
 ## Appendix B: Research Sources
 
 This PRD was informed by: