update docs

Author: kan-bayashi

CLAUDE.md

@@ -11,6 +11,7 @@ SVT (Simple Viewer in Terminal) - A terminal-based image viewer with sxiv-like k
 - Terminal Backend: crossterm
 - Image Processing: image crate
 - CLI: clap (derive)
+- Config: serde + toml + dirs
 
 ## Project Structure
 
@@ -22,6 +23,7 @@ svt/
 ├── src/
 │   ├── main.rs    # Entry point, CLI parsing, event loop
 │   ├── app.rs     # App state, navigation, cache orchestration
+│   ├── config.rs  # Config loading (file + env, priority: env > file > default)
 │   ├── fit.rs     # Fit mode (Normal/Fit)
 │   ├── kgp.rs     # Kitty Graphics Protocol helpers (encode/place/erase)
 │   ├── sender.rs  # TerminalWriter (single stdout writer, status priority, cancel)
@@ -40,27 +42,15 @@ cargo clippy         # Lint
 
 ## Keybindings
 
-- `q` - Quit
-- `j` / `Space` / `l` - Next image
-- `k` / `Backspace` / `h` - Previous image
-- `g` - First image
-- `G` - Last image
-- `f` - Toggle fit
-- `r` - Reload (clear cache)
-- Counts supported (e.g. `5j`, `10G`)
-
-## Environment Variables
-
-- `SVT_NAV_LATCH_MS` - Navigation latch (ms) before drawing images (default: 150)
-- `SVT_RENDER_CACHE_SIZE` - Client-side render cache size (encoded images in memory, default: 100)
-- `SVT_TMUX_KITTY_MAX_PIXELS` - Max pixels for tmux+kitty in `Normal` mode (default: 2000000)
-- `SVT_FORCE_ALT_SCREEN` - Force alternate screen mode
-- `SVT_NO_ALT_SCREEN` - Disable alternate screen mode
-- `SVT_DEBUG` - Enable debug info in status bar
-- `SVT_TRACE_WORKER` - Write worker timing logs to `/tmp/svt_worker.log`
-- `SVT_KGP_NO_COMPRESS` - Disable zlib compression for KGP transmission
-- `SVT_COMPRESS_LEVEL` - Zlib compression level 0-9 (default: 6, higher = smaller but slower)
-- `SVT_PREFETCH_COUNT` - Number of images to prefetch ahead/behind (default: 5)
+See [README.md](README.md#keybindings).
+
+## Configuration
+
+Settings: `~/.config/svt/config.toml` or environment variables (`SVT_*`).
+
+**Priority:** Environment variables > Config file > Defaults
+
+See [README.md](README.md#configuration) for all options.
 
 ## Coding Conventions
 
@@ -69,29 +59,13 @@ cargo clippy         # Lint
 - Keep functions small and focused
 - Write tests for public functions
 
-### Critical Invariants
-
-- **stdout is written by `TerminalWriter` only** (`src/sender.rs`)
-- **Image output must be chunked at safe boundaries**
-  - KGP chunk boundaries for transmit (`encode_chunks`)
-  - per-row boundaries for placement/erase (`place_rows` / `erase_rows`)
-- **Navigation must stay responsive**
-  - cancel in-flight image output on navigation (only when not transmitting)
-  - avoid blocking the main loop on decode/encode or stdout I/O
-- **Single KGP ID per process**
-  - `delete_by_id` before each transmit to clear terminal-side cache
-  - prevents "wrong image" and "blank screen" issues
-- **Transmit must complete once started**
-  - skip cancellation during active transmission (`is_transmitting()`)
-  - ensures terminal receives complete image data
-
-## Architecture Notes
+## Architecture & Invariants
 
-- See `docs/architecture.md`.
+See [docs/architecture.md](docs/architecture.md).
 
 ## Contributing
 
-See `CONTRIBUTING.md`.
+See [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## References
 

CONTRIBUTING.md

@@ -2,55 +2,50 @@
 
 Thanks for contributing to `svt`.
 
-## Quick start
+## Quick Start
 
 ```bash
 cargo build
 cargo test
-cargo clippy --all-targets --all-features
+cargo clippy
+cargo fmt --check
 ```
 
-## Project layout
+## Project Layout
 
-- `src/main.rs`: CLI + event loop
-- `src/app.rs`: app state, cache orchestration
-- `src/worker.rs`: image decode/resize/encode (thread)
-- `src/sender.rs`: `TerminalWriter` (single stdout writer, status priority, cancel)
-- `src/kgp.rs`: Kitty Graphics Protocol helpers
-- `docs/architecture.md`: system overview
+See [CLAUDE.md](CLAUDE.md#project-structure).
 
-## Invariants (please keep)
+## Architecture & Invariants
 
-- stdout must be written by **`TerminalWriter` only** (`src/sender.rs`)
-- image output must be chunked at safe boundaries
-  - KGP chunk boundaries for transmit (`encode_chunks`)
-  - per-row boundaries for placement/erase (`place_rows` / `erase_rows`)
-- navigation must stay responsive
-  - cancel in-flight image output on navigation
-  - avoid blocking the main loop on decode/encode or stdout I/O
+See [docs/architecture.md](docs/architecture.md).
 
-## Environment variables (developer)
+## Configuration
 
-| Env | Description |
-|-----|-------------|
-| `SVT_TRACE_WORKER=1` | Write worker timing logs to `/tmp/svt_worker.log` |
-| `SVT_DEBUG=1` | Add debug info to status bar |
+See [README.md](README.md#configuration).
 
-## Tips
+For debugging:
 
-- If you change terminal escape handling, test with a large image and rapid navigation to verify cancellation.
-- If tests print escape sequences, ensure the writer treats stdout as non-TTY during tests.
+| Config | Env | Description |
+|--------|-----|-------------|
+| `debug` | `SVT_DEBUG` | Show debug info in status bar |
+| `trace_worker` | `SVT_TRACE_WORKER` | Write timing logs to `/tmp/svt_worker.log` |
+
+## Testing Tips
+
+- Test with large images and rapid navigation to verify cancellation behavior.
+- Tests should not write escape sequences to stdout.
 
 ## Release
 
-Push a tag like `v0.1.0` to build and attach binaries to a GitHub Release:
+Push a tag to trigger GitHub Actions release:
 
 ```bash
-git tag v0.1.0
-git push origin v0.1.0
+git tag v25.12.3
+git push origin v25.12.3
 ```
 
-Current workflow targets:
+**Versioning:** `YY.MM.PATCH` (e.g., `25.12.2` = December 2025, patch 2)
 
+**Targets:**
 - macOS (Apple Silicon): `aarch64-apple-darwin`
-- Linux: `x86_64-unknown-linux-gnu`
+- Linux (x86_64): `x86_64-unknown-linux-gnu`

docs/architecture.md

@@ -5,9 +5,10 @@ The core goal is: keep navigation/status updates responsive even when image rend
 
 ## High-level pipeline
 
-There are three concurrent “lanes”:
+There are three concurrent "lanes":
 
 1. **Main thread** (`src/main.rs`)
+   - Loads configuration (`src/config.rs`).
    - Reads key events.
    - Updates application state.
    - Decides when to request rendering.
@@ -78,7 +79,42 @@ This approach:
 `svt` uses a **client-side render cache** only:
 
 - **Render cache** (`render_cache` in `App`): Stores decoded/resized/encoded image data.
-- Size controlled by `SVT_RENDER_CACHE_SIZE` (default: 15).
+- Size controlled by `render_cache_size` config (default: 100).
 - LRU eviction when cache is full.
 
 The terminal-side cache is **not** relied upon. Each transmit starts with `delete_by_id` to ensure a clean slate. This trades some bandwidth for simplicity and correctness.
+
+## Configuration
+
+Settings are loaded at startup by `Config::load()` (`src/config.rs`):
+
+1. Load from `~/.config/svt/config.toml` (if exists).
+2. Override with environment variables (`SVT_*`).
+3. Apply defaults for missing values.
+
+**Priority:** Environment variables > Config file > Defaults
+
+The `Config` struct is passed to `App` and propagated to worker requests as needed.
+
+## Invariants
+
+These invariants must be preserved when modifying the codebase:
+
+1. **stdout via `TerminalWriter` only** (`src/sender.rs`)
+   - No other component may write to stdout directly.
+
+2. **Image output chunked at safe boundaries**
+   - KGP chunk boundaries for transmit (`encode_chunks`)
+   - Per-row boundaries for placement/erase (`place_rows` / `erase_rows`)
+
+3. **Navigation stays responsive**
+   - Cancel in-flight image output on navigation (except during transmit)
+   - Avoid blocking the main loop on decode/encode or stdout I/O
+
+4. **Single KGP ID per process**
+   - `delete_by_id` before each transmit to clear terminal-side cache
+   - Prevents "wrong image" and "blank screen" issues
+
+5. **Transmit must complete once started**
+   - Skip cancellation during active transmission (`is_transmitting()`)
+   - Ensures terminal receives complete image data