docs: cut docs to a minimal cache of the code

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -58,7 +58,6 @@ body:
       value: |
         - SumVox version: (run `sumvox --version`)
         - OS: (e.g., macOS 14.1, Ubuntu 22.04)
-        - Rust version: (run `rustc --version`)
         - LLM provider: (e.g., Gemini, Claude)
         - TTS provider: (e.g., Google TTS, macOS say)
     validations:
@@ -70,11 +69,13 @@ body:
       label: Configuration
       description: Please paste your config file (remove API keys!)
       placeholder: |
-        {
-          "version": "1.0.0",
-          "llm": { ... }
-        }
-      render: json
+        [[llm.providers]]
+        name = "google"
+        model = "..."
+
+        [[tts.providers]]
+        name = "macos"
+      render: toml
 
   - type: textarea
     id: logs

.github/ISSUE_TEMPLATE/config.yml

@@ -1,8 +1,5 @@
 blank_issues_enabled: true
 contact_links:
-  - name: Question or Discussion
-    url: https://github.com/musingfox/sumvox/discussions
-    about: Ask questions or discuss ideas
   - name: Documentation
     url: https://github.com/musingfox/sumvox/blob/main/README.md
     about: Read the documentation

.github/PULL_REQUEST_TEMPLATE.md

@@ -1,85 +1,7 @@
 ## Description
 
-<!-- Describe your changes in detail -->
+<!-- What changed and why. Link the issue with "Closes #123". -->
 
-## Type of Change
+## Testing
 
-<!-- Mark the relevant option with an "x" -->
-
-- [ ] Bug fix (non-breaking change which fixes an issue)
-- [ ] New feature (non-breaking change which adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] Documentation update
-- [ ] Performance improvement
-- [ ] Code refactoring
-- [ ] Test addition/update
-
-## Related Issues
-
-<!-- Link to related issues using #issue_number -->
-
-Closes #
-
-## Changes Made
-
-<!-- List the key changes -->
-
--
--
--
-
-## Testing Performed
-
-<!-- Describe the tests you ran -->
-
-- [ ] All existing tests pass (`cargo test`)
-- [ ] Added new tests for changes
-- [ ] Manual testing performed
-- [ ] Tested on macOS
-- [ ] Tested on Linux
-
-### Test Details
-
-<!-- Describe your testing in detail -->
-
-```bash
-# Commands you ran for testing
-cargo test
-cargo run -- ...
-```
-
-## Configuration Changes
-
-<!-- If you modified configuration, show before/after -->
-
-```json
-{
-  "before": "...",
-  "after": "..."
-}
-```
-
-## Checklist
-
-<!-- Mark completed items with an "x" -->
-
-- [ ] My code follows the project's code style (`cargo fmt`)
-- [ ] I have run clippy (`cargo clippy -- -D warnings`)
-- [ ] I have added tests that prove my fix/feature works
-- [ ] I have updated documentation (README, CLAUDE.md, etc.)
-- [ ] My changes generate no new warnings
-- [ ] I have added entries to CHANGELOG.md (if applicable)
-- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/)
-- [ ] All tests pass locally
-
-## Screenshots/Logs
-
-<!-- If applicable, add screenshots or log output -->
-
-```
-Paste relevant logs here
-```
-
-## Additional Context
-
-<!-- Add any other context about the PR here -->
+<!-- `just check` passes. Note the OS you tried it on (macOS / Linux). -->

CHANGELOG.md

@@ -343,6 +343,15 @@ When upgrading to v1.1.0:
 - Homebrew tap: `musingfox/sumvox`
 - Configuration: Edit YAML file directly instead of using environment variables
 
+[Unreleased]: https://github.com/musingfox/sumvox/compare/v1.9.0...HEAD
+[1.9.0]: https://github.com/musingfox/sumvox/releases/tag/v1.9.0
+[1.8.0]: https://github.com/musingfox/sumvox/releases/tag/v1.8.0
+[1.7.1]: https://github.com/musingfox/sumvox/releases/tag/v1.7.1
+[1.7.0]: https://github.com/musingfox/sumvox/releases/tag/v1.7.0
+[1.6.0]: https://github.com/musingfox/sumvox/releases/tag/v1.6.0
+[1.5.1]: https://github.com/musingfox/sumvox/releases/tag/v1.5.1
+[1.5.0]: https://github.com/musingfox/sumvox/releases/tag/v1.5.0
+[1.4.1]: https://github.com/musingfox/sumvox/releases/tag/v1.4.1
 [1.4.0]: https://github.com/musingfox/sumvox/releases/tag/v1.4.0
 [1.3.1]: https://github.com/musingfox/sumvox/releases/tag/v1.3.1
 [1.3.0]: https://github.com/musingfox/sumvox/releases/tag/v1.3.0

CLAUDE.md

@@ -1,165 +1,27 @@
-# Project Configuration
+# SumVox
 
-## Overview
+Rust CLI and Claude Code hook that summarizes AI coding sessions with an LLM and speaks the result.
+Docs are only a cache: the code, `sumvox --help` and `config/recommended.toml` are the source of truth.
 
-**Project**: SumVox
-**Language**: Rust
-**Type**: CLI Tool / Claude Code Hook
-**Purpose**: Intelligent voice notifications for AI coding tools with multi-model LLM support
+## Commands
 
-## Task Management System
+- `just check`: fmt check, clippy `-D warnings`, `cargo test` (hermetic: no network, no audio).
+- `just test-e2e` (`cargo test --test e2e -- --ignored`): real APIs and audio; needs
+  `config/e2e_test.toml` copied from `config/e2e_test.toml.example`.
 
-**System**: Local
-**Location**: `.agents/tasks/`
+## Gotchas
 
-## Development Environment
+- `config/e2e_test.toml` is gitignored but holds real keys: never force-add it, and stage files
+  by name rather than `git add -A` (a renamed copy is not ignored).
+- No hard-coded provider, model or voice identities in runtime code. Config is the single source;
+  CLI flags only select a configured entry.
+- `llvm-cov --branch` segfaults on the `async_trait` provider files (`src/llm/`, `src/tts/`):
+  exclude them from branch coverage.
+- All playback goes through `src/audio/player.rs`; the summarize-then-speak flow lives in
+  `src/pipeline.rs`, shared by `say`, `sum`, `json` and the hooks.
+- `src/notify_log.rs` (muted flag, `history.log`, `now_playing`) is the contract with the menu bar
+  app in `menubar/`; change both together.
 
-### Build & Run
+## Pointers
 
-```bash
-# Development build
-cargo build
-
-# Release build (optimized)
-cargo build --release
-
-# Run with debug logging
-RUST_LOG=debug cargo run
-
-# Run tests
-cargo test
-
-# Run with specific input
-echo '{"session_id":"test",...}' | cargo run
-```
-
-### Configuration
-
-- **Main config**: `~/.config/sumvox/config.toml`
-- **Hook script**: `.claude/hooks/run_sumvox_hook.sh`
-- **Binary location**: `target/release/sumvox`
-- **Example config**: `config/recommended.toml`
-
-### Environment Variables
-
-```bash
-# Logging (optional)
-export RUST_LOG=info  # or debug, trace
-```
-
-**Note:** API keys are configured in `~/.config/sumvox/config.toml`, not as environment variables.
-
-## Testing
-
-```bash
-# Run all tests
-cargo test
-
-# Run tests with output
-cargo test -- --nocapture
-
-# Run specific test
-cargo test test_name
-
-# Run tests in specific module
-cargo test llm::
-cargo test tts::
-```
-
-## CLI Commands
-
-```bash
-# Initialize config
-sumvox init
-
-# Direct TTS
-sumvox say "Hello world"
-
-# Summarize text
-sumvox sum "Long text to summarize..."
-
-# Test with specific providers
-sumvox say "Test" --tts macos --voice Daniel
-```
-
-## Architecture
-
-### Key Modules
-
-- `src/main.rs` - Entry point, hook orchestration
-- `src/config.rs` - Configuration loading/saving
-- `src/transcript.rs` - Claude Code transcript parsing
-- `src/llm/` - Multi-provider LLM support (Gemini, Anthropic, OpenAI, xAI Grok, Ollama)
-- `src/tts/` - Text-to-Speech engines (macOS say, espeak-ng, piper, Google TTS, Google Cloud TTS, xAI TTS, OpenAI TTS, ElevenLabs)
-- `src/audio/` - Playback: `player.rs` is the single choke point (afplay on macOS, probed CLI player elsewhere)
-- `src/pipeline.rs` - Shared summarize → speak flow used by `say`/`sum`/`json` and the hook handlers
-- `src/provider_factory.rs` - Provider creation with fallback chain
-- `src/notify_log.rs` - Mute flag, history log and now_playing file shared with the menu bar app
-
-### Configuration Format
-
-See `~/.config/sumvox/config.toml`:
-
-- LLM providers array with fallback chain
-- TTS providers array with fallback chain
-- Summarization settings (turns, prompt_template)
-- Hook-specific configurations (notification_filter, tts_provider overrides)
-
-## Project Structure
-
-```
-sumvox/
-├── src/
-│   ├── main.rs           # Entry point
-│   ├── cli.rs            # CLI parsing
-│   ├── config.rs         # Configuration loading/saving
-│   ├── transcript.rs     # Transcript parsing
-│   ├── error.rs          # Error types
-│   ├── queue.rs          # Serializes concurrent hook invocations
-│   ├── notify_log.rs     # History log + mute flag for the menu bar app
-│   ├── hooks/            # Hook handlers
-│   ├── pipeline.rs       # Shared summarize → speak flow
-│   ├── llm/              # LLM providers
-│   ├── tts/              # TTS engines
-│   ├── audio/            # Playback (player.rs, file.rs, normalize.rs, wav_header.rs)
-│   └── provider_factory.rs
-├── menubar/
-│   └── SumVoxMenu.swift  # Optional macOS status bar app (just menubar)
-├── config/
-│   └── recommended.toml  # Example configuration with comments
-├── .github/
-│   ├── workflows/        # CI/CD
-│   └── ISSUE_TEMPLATE/   # Issue templates
-├── homebrew/
-│   └── sumvox.rb         # Homebrew formula
-├── Cargo.toml
-├── README.md
-├── QUICKSTART.md
-├── CHANGELOG.md
-├── CONTRIBUTING.md
-└── LICENSE
-```
-
-## Release Process
-
-See the "Release Process" section in [CONTRIBUTING.md](CONTRIBUTING.md) for detailed release steps.
-
-Quick version:
-
-```bash
-# Using justfile
-just release 1.0.0
-
-# Or manually
-git tag -a v1.0.0 -m "Release v1.0.0"
-git push origin v1.0.0
-```
-
-## Recommended Configuration
-
-See `config/recommended.toml` for the Gemini-based setup:
-
-- Google Gemini for LLM (tested and optimized)
-- macOS TTS for notifications (fast and free)
-- Google TTS for summaries (high quality)
-- TOML format with inline comments for easy customization
+Contributor workflow: CONTRIBUTING.md. Agent task state: `.agents/README.md`.