diff --git a/.cargo/config.toml b/.cargo/config.toml
new file mode 100644
index 0000000..da885e7
--- /dev/null
+++ b/.cargo/config.toml
@@ -0,0 +1,32 @@
+# Cargo aliases (simpler alternative to cargo-make)
+# Usage: cargo <alias-name>
+# Examples: cargo b (build), cargo r (run), cargo t (test), cargo cl (clippy)
+
+[alias]
+# Build aliases
+b = "build"
+br = "build --release"
+c = "check"
+
+# Run aliases
+r = "run"
+rr = "run --release"
+
+# Test aliases
+t = "test"
+tt = "test -- --nocapture"
+
+# Linting/formatting
+cl = "clippy -- -D warnings"
+f = "fmt"
+fc = "fmt -- --check"
+
+# Clean
+clean-all = "clean"
+
+# Combined tasks (use scripts/pre-commit.sh for combined workflow)
+# Note: Cargo aliases don't support shell operators like &&
+# Run these commands separately:
+#   cargo fmt
+#   cargo clippy -- -D warnings
+#   cargo test
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..7ffbdde
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,39 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+dev-debug.log
+
+# Dependency directories
+node_modules/
+
+# Environment variables
+.env
+
+# Editor directories and files
+.idea
+.vscode
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# OS specific
+.DS_Store
+
+
+# Added by cargo
+
+/target
+
+# Local config files
+.clai.toml
+
+# TaskMaster (local to developer, not tracked in Git)
+.taskmaster/
+
+# Cursor IDE (local to developer, not tracked in Git)
+.cursor/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..e236ae9
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,138 @@
+# Contributing to clai
+
+## Development Setup
+
+### Prerequisites
+
+- Rust 1.70+
+- OpenRouter API key (for testing AI features)
+
+```bash
+git clone https://github.com/Vedaant-Rajoo/clAI.git
+cd clAI
+cargo build
+
+# Install Git hooks (recommended)
+./scripts/install-hooks.sh
+```
+
+### Running
+
+```bash
+cargo run -- "your instruction"
+```
+
+## Project Structure
+
+```
+src/
+├── main.rs          # Entry point
+├── lib.rs           # Library exports
+├── cli/             # Argument parsing
+├── config/          # Configuration loading
+├── context/         # System/directory context gathering
+├── ai/              # AI provider abstraction
+│   └── providers/   # OpenRouter, etc.
+├── safety/          # Dangerous command detection
+└── error/           # Error types and exit codes
+```
+
+## Commands
+
+```bash
+cargo build              # Debug build
+cargo build --release    # Release build
+cargo test               # Run tests
+cargo clippy             # Lint
+cargo fmt                # Format
+cargo bench --features bench  # Run benchmarks
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable             | Description            |
+| -------------------- | ---------------------- |
+| `OPENROUTER_API_KEY` | API key for OpenRouter |
+| `NO_COLOR`           | Disable colored output |
+
+### Config File Locations
+
+1. `./.clai.toml` (project-local, highest priority)
+2. `~/.config/clai/config.toml` (user)
+3. `/etc/clai/config.toml` (system)
+
+### Full Config Example
+
+```toml
+[provider]
+default = "openrouter"
+api-key = "${OPENROUTER_API_KEY}"
+
+[provider.openrouter]
+model = "qwen/qwen3-coder"
+
+[context]
+max-history = 3
+max-files = 10
+
+[safety]
+confirm-dangerous = true
+dangerous-patterns = [
+  "rm -rf",
+  "sudo.*rm",
+  ".*> /dev/sd[a-z]",
+]
+
+[ui]
+interactive = true
+color = "auto"
+```
+
+## Exit Codes
+
+| Code | Meaning                                   |
+| ---- | ----------------------------------------- |
+| 0    | Success                                   |
+| 1    | General error                             |
+| 2    | Usage error                               |
+| 3    | Configuration error                       |
+| 4    | API error                                 |
+| 5    | Safety error (dangerous command rejected) |
+| 130  | Interrupted (Ctrl+C)                      |
+
+## Pull Request Process
+
+1. Fork and create a feature branch
+2. Install Git hooks: `./scripts/install-hooks.sh` (if not already done)
+3. Make changes
+4. The pre-commit hook will automatically run checks before each commit:
+   - Format code with `cargo fmt`
+   - Run `cargo clippy -- -D warnings`
+   - Run `cargo test`
+5. If you need to bypass the hook temporarily: `git commit --no-verify`
+6. Submit PR
+
+### Manual Checks
+
+If you haven't installed the Git hooks, run these commands before committing:
+
+```bash
+./scripts/pre-commit.sh  # Run all checks
+```
+
+Or individually:
+
+```bash
+cargo fmt                      # Format code
+cargo clippy -- -D warnings    # Check lints
+cargo test                     # Run tests
+```
+
+## Code Style
+
+- Follow `cargo fmt` formatting
+- Use `cargo clippy` for lints
+- Write tests for new features
+- Document public APIs
diff --git a/Cargo.lock b/Cargo.lock
new file mode 100644
index 0000000..daee623
--- /dev/null
+++ b/Cargo.lock
@@ -0,0 +1,2654 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "aho-corasick"
+version = "1.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ddd31a130427c27518df266943a5308ed92d4b226cc639f5a8f1002816174301"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "anes"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4b46cbb362ab8752921c97e041f5e366ee6297bd428a31275b9fcf1e380f7299"
+
+[[package]]
+name = "anstream"
+version = "0.6.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "43d5b281e737544384e969a5ccad3f1cdd24b48086a0fc1b2a5262a26b8f4f4a"
+dependencies = [
+ "anstyle",
+ "anstyle-parse",
+ "anstyle-query",
+ "anstyle-wincon",
+ "colorchoice",
+ "is_terminal_polyfill",
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle"
+version = "1.0.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5192cca8006f1fd4f7237516f40fa183bb07f8fbdfedaa0036de5ea9b0b45e78"
+
+[[package]]
+name = "anstyle-parse"
+version = "0.2.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4e7644824f0aa2c7b9384579234ef10eb7efb6a0deb83f9630a49594dd9c15c2"
+dependencies = [
+ "utf8parse",
+]
+
+[[package]]
+name = "anstyle-query"
+version = "1.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anstyle-wincon"
+version = "3.0.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
+dependencies = [
+ "anstyle",
+ "once_cell_polyfill",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "anyhow"
+version = "1.0.100"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a23eb6b1614318a8071c9b2521f36b424b2c83db5eb3a0fead4a6c0809af6e61"
+
+[[package]]
+name = "async-trait"
+version = "0.1.89"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9035ad2d096bed7955a320ee7e2230574d28fd3c3a0f186cbea1ff3c7eed5dbb"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "atomic-waker"
+version = "1.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"
+
+[[package]]
+name = "atty"
+version = "0.2.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d9b39be18770d11421cdb1b9947a45dd3f37e93092cbf377614828a319d5fee8"
+dependencies = [
+ "hermit-abi 0.1.19",
+ "libc",
+ "winapi",
+]
+
+[[package]]
+name = "autocfg"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c08606f8c3cbf4ce6ec8e28fb0014a2c086708fe954eaa885384a6165172e7e8"
+
+[[package]]
+name = "aws-lc-rs"
+version = "1.15.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6a88aab2464f1f25453baa7a07c84c5b7684e274054ba06817f382357f77a288"
+dependencies = [
+ "aws-lc-sys",
+ "zeroize",
+]
+
+[[package]]
+name = "aws-lc-sys"
+version = "0.35.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b45afffdee1e7c9126814751f88dddc747f41d91da16c9551a0f1e8a11e788a1"
+dependencies = [
+ "cc",
+ "cmake",
+ "dunce",
+ "fs_extra",
+]
+
+[[package]]
+name = "base64"
+version = "0.22.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
+
+[[package]]
+name = "bitflags"
+version = "2.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "812e12b5285cc515a9c72a5c1d3b6d46a19dac5acfef5265968c166106e31dd3"
+
+[[package]]
+name = "bumpalo"
+version = "3.19.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5dd9dc738b7a8311c7ade152424974d8115f2cdad61e8dab8dac9f2362298510"
+
+[[package]]
+name = "bytes"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b35204fbdc0b3f4446b89fc1ac2cf84a8a68971995d0bf2e925ec7cd960f9cb3"
+
+[[package]]
+name = "cast"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37b2a672a2cb129a2e41c10b1224bb368f9f37a2b16b612598138befd7b37eb5"
+
+[[package]]
+name = "cc"
+version = "1.2.51"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a0aeaff4ff1a90589618835a598e545176939b97874f7abc7851caa0618f203"
+dependencies = [
+ "find-msvc-tools",
+ "jobserver",
+ "libc",
+ "shlex",
+]
+
+[[package]]
+name = "cesu8"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6d43a04d8753f35258c91f8ec639f792891f748a1edbd759cf1dcea3382ad83c"
+
+[[package]]
+name = "cfg-if"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
+
+[[package]]
+name = "cfg_aliases"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "613afe47fcd5fac7ccf1db93babcb082c5994d996f20b8b159f2ad1658eb5724"
+
+[[package]]
+name = "ciborium"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42e69ffd6f0917f5c029256a24d0161db17cea3997d185db0d35926308770f0e"
+dependencies = [
+ "ciborium-io",
+ "ciborium-ll",
+ "serde",
+]
+
+[[package]]
+name = "ciborium-io"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05afea1e0a06c9be33d539b876f1ce3692f4afea2cb41f740e7743225ed1c757"
+
+[[package]]
+name = "ciborium-ll"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "57663b653d948a338bfb3eeba9bb2fd5fcfaecb9e199e87e1eda4d9e8b240fd9"
+dependencies = [
+ "ciborium-io",
+ "half",
+]
+
+[[package]]
+name = "clai"
+version = "0.1.0"
+dependencies = [
+ "anyhow",
+ "async-trait",
+ "atty",
+ "clap",
+ "criterion",
+ "crossterm",
+ "directories",
+ "once_cell",
+ "owo-colors",
+ "regex",
+ "reqwest",
+ "serde",
+ "serde_json",
+ "signal-hook 0.4.1",
+ "sysinfo",
+ "tempfile",
+ "thiserror 2.0.17",
+ "tokio",
+ "toml",
+ "xdg",
+]
+
+[[package]]
+name = "clap"
+version = "4.5.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c6e6ff9dcd79cff5cd969a17a545d79e84ab086e444102a591e288a8aa3ce394"
+dependencies = [
+ "clap_builder",
+ "clap_derive",
+]
+
+[[package]]
+name = "clap_builder"
+version = "4.5.54"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa42cf4d2b7a41bc8f663a7cab4031ebafa1bf3875705bfaf8466dc60ab52c00"
+dependencies = [
+ "anstream",
+ "anstyle",
+ "clap_lex",
+ "strsim",
+]
+
+[[package]]
+name = "clap_derive"
+version = "4.5.49"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a0b5487afeab2deb2ff4e03a807ad1a03ac532ff5a2cee5d86884440c7f7671"
+dependencies = [
+ "heck",
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "clap_lex"
+version = "0.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a1d728cc89cf3aee9ff92b05e62b19ee65a02b5702cff7d5a377e32c6ae29d8d"
+
+[[package]]
+name = "cmake"
+version = "0.1.57"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75443c44cd6b379beb8c5b45d85d0773baf31cce901fe7bb252f4eff3008ef7d"
+dependencies = [
+ "cc",
+]
+
+[[package]]
+name = "colorchoice"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b05b61dc5112cbb17e4b6cd61790d9845d13888356391624cbe7e41efeac1e75"
+
+[[package]]
+name = "combine"
+version = "4.6.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ba5a308b75df32fe02788e748662718f03fde005016435c444eea572398219fd"
+dependencies = [
+ "bytes",
+ "memchr",
+]
+
+[[package]]
+name = "convert_case"
+version = "0.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "633458d4ef8c78b72454de2d54fd6ab2e60f9e02be22f3c6104cdc8a4e0fceb9"
+dependencies = [
+ "unicode-segmentation",
+]
+
+[[package]]
+name = "core-foundation"
+version = "0.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "core-foundation-sys"
+version = "0.8.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
+
+[[package]]
+name = "criterion"
+version = "0.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2b12d017a929603d80db1831cd3a24082f8137ce19c69e6447f54f5fc8d692f"
+dependencies = [
+ "anes",
+ "cast",
+ "ciborium",
+ "clap",
+ "criterion-plot",
+ "is-terminal",
+ "itertools",
+ "num-traits",
+ "once_cell",
+ "oorandom",
+ "plotters",
+ "rayon",
+ "regex",
+ "serde",
+ "serde_derive",
+ "serde_json",
+ "tinytemplate",
+ "walkdir",
+]
+
+[[package]]
+name = "criterion-plot"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6b50826342786a51a89e2da3a28f1c32b06e387201bc2d19791f622c673706b1"
+dependencies = [
+ "cast",
+ "itertools",
+]
+
+[[package]]
+name = "crossbeam-deque"
+version = "0.8.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dd111b7b7f7d55b72c0a6ae361660ee5853c9af73f70c3c2ef6858b950e2e51"
+dependencies = [
+ "crossbeam-epoch",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-epoch"
+version = "0.9.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5b82ac4a3c2ca9c3460964f020e1402edd5753411d7737aa39c3714ad1b5420e"
+dependencies = [
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "crossbeam-utils"
+version = "0.8.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
+
+[[package]]
+name = "crossterm"
+version = "0.29.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8b9f2e4c67f833b660cdb0a3523065869fb35570177239812ed4c905aeff87b"
+dependencies = [
+ "bitflags",
+ "crossterm_winapi",
+ "derive_more",
+ "document-features",
+ "mio",
+ "parking_lot",
+ "rustix",
+ "signal-hook 0.3.18",
+ "signal-hook-mio",
+ "winapi",
+]
+
+[[package]]
+name = "crossterm_winapi"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "acdd7c62a3665c7f6830a51635d9ac9b23ed385797f70a83bb8bafe9c572ab2b"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "crunchy"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "460fbee9c2c2f33933d720630a6a0bac33ba7053db5344fac858d4b8952d77d5"
+
+[[package]]
+name = "derive_more"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d751e9e49156b02b44f9c1815bcb94b984cdcc4396ecc32521c739452808b134"
+dependencies = [
+ "derive_more-impl",
+]
+
+[[package]]
+name = "derive_more-impl"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "799a97264921d8623a957f6c3b9011f3b5492f557bbb7a5a19b7fa6d06ba8dcb"
+dependencies = [
+ "convert_case",
+ "proc-macro2",
+ "quote",
+ "rustc_version",
+ "syn",
+]
+
+[[package]]
+name = "directories"
+version = "6.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16f5094c54661b38d03bd7e50df373292118db60b585c08a411c6d840017fe7d"
+dependencies = [
+ "dirs-sys",
+]
+
+[[package]]
+name = "dirs-sys"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e01a3366d27ee9890022452ee61b2b63a67e6f13f58900b651ff5665f0bb1fab"
+dependencies = [
+ "libc",
+ "option-ext",
+ "redox_users",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "displaydoc"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "97369cbbc041bc366949bc74d34658d6cda5621039731c6310521892a3a20ae0"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "document-features"
+version = "0.2.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4b8a88685455ed29a21542a33abd9cb6510b6b129abadabdcef0f4c55bc8f61"
+dependencies = [
+ "litrs",
+]
+
+[[package]]
+name = "dunce"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92773504d58c093f6de2459af4af33faa518c13451eb8f2b5698ed3d36e7c813"
+
+[[package]]
+name = "either"
+version = "1.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48c757948c5ede0e46177b7add2e67155f70e33c07fea8284df6576da70b3719"
+
+[[package]]
+name = "equivalent"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "877a4ace8713b0bcf2a4e7eec82529c029f1d0619886d18145fea96c3ffe5c0f"
+
+[[package]]
+name = "errno"
+version = "0.3.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
+dependencies = [
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "fastrand"
+version = "2.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "37909eebbb50d72f9059c3b6d82c0463f2ff062c9e95845c43a6c9c0355411be"
+
+[[package]]
+name = "find-msvc-tools"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "645cbb3a84e60b7531617d5ae4e57f7e27308f6445f5abf653209ea76dec8dff"
+
+[[package]]
+name = "form_urlencoded"
+version = "1.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
+dependencies = [
+ "percent-encoding",
+]
+
+[[package]]
+name = "fs_extra"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42703706b716c37f96a77aea830392ad231f44c9e9a67872fa5548707e11b11c"
+
+[[package]]
+name = "futures-channel"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2dff15bf788c671c1934e366d07e30c1814a8ef514e1af724a602e8a2fbe1b10"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "futures-core"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "05f29059c0c2090612e8d742178b0580d2dc940c837851ad723096f87af6663e"
+
+[[package]]
+name = "futures-task"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f90f7dce0722e95104fcb095585910c0977252f286e354b5e3bd38902cd99988"
+
+[[package]]
+name = "futures-util"
+version = "0.3.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9fa08315bb612088cc391249efdc3bc77536f16c91f6cf495e6fbe85b20a4a81"
+dependencies = [
+ "futures-core",
+ "futures-task",
+ "pin-project-lite",
+ "pin-utils",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "335ff9f135e4384c8150d6f27c6daed433577f86b4750418338c01a1a2528592"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "wasi",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "getrandom"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "libc",
+ "r-efi",
+ "wasip2",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "half"
+version = "2.7.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ea2d84b969582b4b1864a92dc5d27cd2b77b622a8d79306834f1be5ba20d84b"
+dependencies = [
+ "cfg-if",
+ "crunchy",
+ "zerocopy",
+]
+
+[[package]]
+name = "hashbrown"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
+
+[[package]]
+name = "heck"
+version = "0.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
+
+[[package]]
+name = "hermit-abi"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "62b467343b94ba476dcb2500d242dadbb39557df889310ac77c5d99100aaac33"
+dependencies = [
+ "libc",
+]
+
+[[package]]
+name = "hermit-abi"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc0fef456e4baa96da950455cd02c081ca953b141298e41db3fc7e36b1da849c"
+
+[[package]]
+name = "http"
+version = "1.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3ba2a386d7f85a81f119ad7498ebe444d2e22c2af0b86b069416ace48b3311a"
+dependencies = [
+ "bytes",
+ "itoa",
+]
+
+[[package]]
+name = "http-body"
+version = "1.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1efedce1fb8e6913f23e0c92de8e62cd5b772a67e7b3946df930a62566c93184"
+dependencies = [
+ "bytes",
+ "http",
+]
+
+[[package]]
+name = "http-body-util"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b021d93e26becf5dc7e1b75b1bed1fd93124b374ceb73f43d4d4eafec896a64a"
+dependencies = [
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "pin-project-lite",
+]
+
+[[package]]
+name = "httparse"
+version = "1.10.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"
+
+[[package]]
+name = "hyper"
+version = "1.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ab2d4f250c3d7b1c9fcdff1cece94ea4e2dfbec68614f7b87cb205f24ca9d11"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "http",
+ "http-body",
+ "httparse",
+ "itoa",
+ "pin-project-lite",
+ "pin-utils",
+ "smallvec",
+ "tokio",
+ "want",
+]
+
+[[package]]
+name = "hyper-rustls"
+version = "0.27.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e3c93eb611681b207e1fe55d5a71ecf91572ec8a6705cdb6857f7d8d5242cf58"
+dependencies = [
+ "http",
+ "hyper",
+ "hyper-util",
+ "rustls",
+ "rustls-pki-types",
+ "tokio",
+ "tokio-rustls",
+ "tower-service",
+]
+
+[[package]]
+name = "hyper-util"
+version = "0.1.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "727805d60e7938b76b826a6ef209eb70eaa1812794f9424d4a4e2d740662df5f"
+dependencies = [
+ "base64",
+ "bytes",
+ "futures-channel",
+ "futures-core",
+ "futures-util",
+ "http",
+ "http-body",
+ "hyper",
+ "ipnet",
+ "libc",
+ "percent-encoding",
+ "pin-project-lite",
+ "socket2",
+ "tokio",
+ "tower-service",
+ "tracing",
+]
+
+[[package]]
+name = "icu_collections"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4c6b649701667bbe825c3b7e6388cb521c23d88644678e83c0c4d0a621a34b43"
+dependencies = [
+ "displaydoc",
+ "potential_utf",
+ "yoke",
+ "zerofrom",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_locale_core"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "edba7861004dd3714265b4db54a3c390e880ab658fec5f7db895fae2046b5bb6"
+dependencies = [
+ "displaydoc",
+ "litemap",
+ "tinystr",
+ "writeable",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5f6c8828b67bf8908d82127b2054ea1b4427ff0230ee9141c54251934ab1b599"
+dependencies = [
+ "icu_collections",
+ "icu_normalizer_data",
+ "icu_properties",
+ "icu_provider",
+ "smallvec",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_normalizer_data"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7aedcccd01fc5fe81e6b489c15b247b8b0690feb23304303a9e560f37efc560a"
+
+[[package]]
+name = "icu_properties"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "020bfc02fe870ec3a66d93e677ccca0562506e5872c650f893269e08615d74ec"
+dependencies = [
+ "icu_collections",
+ "icu_locale_core",
+ "icu_properties_data",
+ "icu_provider",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "icu_properties_data"
+version = "2.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "616c294cf8d725c6afcd8f55abc17c56464ef6211f9ed59cccffe534129c77af"
+
+[[package]]
+name = "icu_provider"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85962cf0ce02e1e0a629cc34e7ca3e373ce20dda4c4d7294bbd0bf1fdb59e614"
+dependencies = [
+ "displaydoc",
+ "icu_locale_core",
+ "writeable",
+ "yoke",
+ "zerofrom",
+ "zerotrie",
+ "zerovec",
+]
+
+[[package]]
+name = "idna"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
+dependencies = [
+ "idna_adapter",
+ "smallvec",
+ "utf8_iter",
+]
+
+[[package]]
+name = "idna_adapter"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3acae9609540aa318d1bc588455225fb2085b9ed0c4f6bd0d9d5bcd86f1a0344"
+dependencies = [
+ "icu_normalizer",
+ "icu_properties",
+]
+
+[[package]]
+name = "indexmap"
+version = "2.12.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ad4bb2b565bca0645f4d68c5c9af97fba094e9791da685bf83cb5f3ce74acf2"
+dependencies = [
+ "equivalent",
+ "hashbrown",
+]
+
+[[package]]
+name = "ipnet"
+version = "2.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "469fb0b9cefa57e3ef31275ee7cacb78f2fdca44e4765491884a2b119d4eb130"
+
+[[package]]
+name = "iri-string"
+version = "0.7.10"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c91338f0783edbd6195decb37bae672fd3b165faffb89bf7b9e6942f8b1a731a"
+dependencies = [
+ "memchr",
+ "serde",
+]
+
+[[package]]
+name = "is-terminal"
+version = "0.4.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
+dependencies = [
+ "hermit-abi 0.5.2",
+ "libc",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "is_terminal_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"
+
+[[package]]
+name = "itertools"
+version = "0.10.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b0fd2260e829bddf4cb6ea802289de2f86d6a7a690192fbe91b3f46e0f2c8473"
+dependencies = [
+ "either",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92ecc6618181def0457392ccd0ee51198e065e016d1d527a7ac1b6dc7c1f09d2"
+
+[[package]]
+name = "jni"
+version = "0.21.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a87aa2bb7d2af34197c04845522473242e1aa17c12f4935d5856491a7fb8c97"
+dependencies = [
+ "cesu8",
+ "cfg-if",
+ "combine",
+ "jni-sys",
+ "log",
+ "thiserror 1.0.69",
+ "walkdir",
+ "windows-sys 0.45.0",
+]
+
+[[package]]
+name = "jni-sys"
+version = "0.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8eaf4bc02d17cbdd7ff4c7438cafcdf7fb9a4613313ad11b4f8fefe7d3fa0130"
+
+[[package]]
+name = "jobserver"
+version = "0.1.34"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33"
+dependencies = [
+ "getrandom 0.3.4",
+ "libc",
+]
+
+[[package]]
+name = "js-sys"
+version = "0.3.83"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "464a3709c7f55f1f721e5389aa6ea4e3bc6aba669353300af094b29ffbdde1d8"
+dependencies = [
+ "once_cell",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "libc"
+version = "0.2.179"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c5a2d376baa530d1238d133232d15e239abad80d05838b4b59354e5268af431f"
+
+[[package]]
+name = "libredox"
+version = "0.1.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d0b95e02c851351f877147b7deea7b1afb1df71b63aa5f8270716e0c5720616"
+dependencies = [
+ "bitflags",
+ "libc",
+]
+
+[[package]]
+name = "linux-raw-sys"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df1d3c3b53da64cf5760482273a98e575c651a67eec7f77df96b5b642de8f039"
+
+[[package]]
+name = "litemap"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6373607a59f0be73a39b6fe456b8192fcc3585f602af20751600e974dd455e77"
+
+[[package]]
+name = "litrs"
+version = "1.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "11d3d7f243d5c5a8b9bb5d6dd2b1602c0cb0b9db1621bafc7ed66e35ff9fe092"
+
+[[package]]
+name = "lock_api"
+version = "0.4.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "224399e74b87b5f3557511d98dff8b14089b3dadafcab6bb93eab67d3aace965"
+dependencies = [
+ "scopeguard",
+]
+
+[[package]]
+name = "log"
+version = "0.4.29"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e5032e24019045c762d3c0f28f5b6b8bbf38563a65908389bf7978758920897"
+
+[[package]]
+name = "lru-slab"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
+
+[[package]]
+name = "memchr"
+version = "2.7.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f52b00d39961fc5b2736ea853c9cc86238e165017a493d1d5c8eac6bdc4cc273"
+
+[[package]]
+name = "mio"
+version = "1.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a69bcab0ad47271a0234d9422b131806bf3968021e5dc9328caf2d4cd58557fc"
+dependencies = [
+ "libc",
+ "log",
+ "wasi",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "ntapi"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c70f219e21142367c70c0b30c6a9e3a14d55b4d12a204d897fbec83a0363f081"
+dependencies = [
+ "winapi",
+]
+
+[[package]]
+name = "num-traits"
+version = "0.2.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
+dependencies = [
+ "autocfg",
+]
+
+[[package]]
+name = "objc2-core-foundation"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a180dd8642fa45cdb7dd721cd4c11b1cadd4929ce112ebd8b9f5803cc79d536"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "objc2-io-kit"
+version = "0.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "33fafba39597d6dc1fb709123dfa8289d39406734be322956a69f0931c73bb15"
+dependencies = [
+ "libc",
+ "objc2-core-foundation",
+]
+
+[[package]]
+name = "once_cell"
+version = "1.21.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42f5e15c9953c5e4ccceeb2e7382a716482c34515315f7b03532b8b4e8393d2d"
+
+[[package]]
+name = "once_cell_polyfill"
+version = "1.70.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
+
+[[package]]
+name = "oorandom"
+version = "11.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6790f58c7ff633d8771f42965289203411a5e5c68388703c06e14f24770b41e"
+
+[[package]]
+name = "openssl-probe"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9f50d9b3dabb09ecd771ad0aa242ca6894994c130308ca3d7684634df8037391"
+
+[[package]]
+name = "option-ext"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04744f49eae99ab78e0d5c0b603ab218f515ea8cfe5a456d7629ad883a3b6e7d"
+
+[[package]]
+name = "owo-colors"
+version = "4.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c6901729fa79e91a0913333229e9ca5dc725089d1c363b2f4b4760709dc4a52"
+
+[[package]]
+name = "parking_lot"
+version = "0.12.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93857453250e3077bd71ff98b6a65ea6621a19bb0f559a85248955ac12c45a1a"
+dependencies = [
+ "lock_api",
+ "parking_lot_core",
+]
+
+[[package]]
+name = "parking_lot_core"
+version = "0.9.12"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2621685985a2ebf1c516881c026032ac7deafcda1a2c9b7850dc81e3dfcb64c1"
+dependencies = [
+ "cfg-if",
+ "libc",
+ "redox_syscall",
+ "smallvec",
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "percent-encoding"
+version = "2.3.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
+
+[[package]]
+name = "pin-project-lite"
+version = "0.2.16"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b3cff922bd51709b605d9ead9aa71031d81447142d828eb4a6eba76fe619f9b"
+
+[[package]]
+name = "pin-utils"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b870d8c151b6f2fb93e84a13146138f05d02ed11c7e7c54f8826aaaf7c9f184"
+
+[[package]]
+name = "plotters"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5aeb6f403d7a4911efb1e33402027fc44f29b5bf6def3effcc22d7bb75f2b747"
+dependencies = [
+ "num-traits",
+ "plotters-backend",
+ "plotters-svg",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "plotters-backend"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df42e13c12958a16b3f7f4386b9ab1f3e7933914ecea48da7139435263a4172a"
+
+[[package]]
+name = "plotters-svg"
+version = "0.3.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "51bae2ac328883f7acdfea3d66a7c35751187f870bc81f94563733a154d7a670"
+dependencies = [
+ "plotters-backend",
+]
+
+[[package]]
+name = "potential_utf"
+version = "0.1.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b73949432f5e2a09657003c25bca5e19a0e9c84f8058ca374f49e0ebe605af77"
+dependencies = [
+ "zerovec",
+]
+
+[[package]]
+name = "ppv-lite86"
+version = "0.2.21"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85eae3c4ed2f50dcfe72643da4befc30deadb458a9b590d720cde2f2b1e97da9"
+dependencies = [
+ "zerocopy",
+]
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.104"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9695f8df41bb4f3d222c95a67532365f569318332d03d5f3f67f37b20e6ebdf0"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quinn"
+version = "0.11.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9e20a958963c291dc322d98411f541009df2ced7b5a4f2bd52337638cfccf20"
+dependencies = [
+ "bytes",
+ "cfg_aliases",
+ "pin-project-lite",
+ "quinn-proto",
+ "quinn-udp",
+ "rustc-hash",
+ "rustls",
+ "socket2",
+ "thiserror 2.0.17",
+ "tokio",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-proto"
+version = "0.11.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f1906b49b0c3bc04b5fe5d86a77925ae6524a19b816ae38ce1e426255f1d8a31"
+dependencies = [
+ "aws-lc-rs",
+ "bytes",
+ "getrandom 0.3.4",
+ "lru-slab",
+ "rand",
+ "ring",
+ "rustc-hash",
+ "rustls",
+ "rustls-pki-types",
+ "slab",
+ "thiserror 2.0.17",
+ "tinyvec",
+ "tracing",
+ "web-time",
+]
+
+[[package]]
+name = "quinn-udp"
+version = "0.5.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "addec6a0dcad8a8d96a771f815f0eaf55f9d1805756410b39f5fa81332574cbd"
+dependencies = [
+ "cfg_aliases",
+ "libc",
+ "once_cell",
+ "socket2",
+ "tracing",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.42"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "r-efi"
+version = "5.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
+
+[[package]]
+name = "rand"
+version = "0.9.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6db2770f06117d490610c7488547d543617b21bfa07796d7a12f6f1bd53850d1"
+dependencies = [
+ "rand_chacha",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_chacha"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d3022b5f1df60f26e1ffddd6c66e8aa15de382ae63b3a0c1bfc0e4d3e3f325cb"
+dependencies = [
+ "ppv-lite86",
+ "rand_core",
+]
+
+[[package]]
+name = "rand_core"
+version = "0.9.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "99d9a13982dcf210057a8a78572b2217b667c3beacbf3a0d8b454f6f82837d38"
+dependencies = [
+ "getrandom 0.3.4",
+]
+
+[[package]]
+name = "rayon"
+version = "1.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "368f01d005bf8fd9b1206fb6fa653e6c4a81ceb1466406b81792d87c5677a58f"
+dependencies = [
+ "either",
+ "rayon-core",
+]
+
+[[package]]
+name = "rayon-core"
+version = "1.13.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "22e18b0f0062d30d4230b2e85ff77fdfe4326feb054b9783a3460d8435c8ab91"
+dependencies = [
+ "crossbeam-deque",
+ "crossbeam-utils",
+]
+
+[[package]]
+name = "redox_syscall"
+version = "0.5.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ed2bf2547551a7053d6fdfafda3f938979645c44812fbfcda098faae3f1a362d"
+dependencies = [
+ "bitflags",
+]
+
+[[package]]
+name = "redox_users"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4e608c6638b9c18977b00b475ac1f28d14e84b27d8d42f70e0bf1e3dec127ac"
+dependencies = [
+ "getrandom 0.2.16",
+ "libredox",
+ "thiserror 2.0.17",
+]
+
+[[package]]
+name = "regex"
+version = "1.12.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "843bc0191f75f3e22651ae5f1e72939ab2f72a4bc30fa80a066bd66edefc24d4"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5276caf25ac86c8d810222b3dbb938e512c55c6831a10f3e6ed1c93b84041f1c"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-syntax"
+version = "0.8.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a2d987857b319362043e95f5353c0535c1f58eec5336fdfcf626430af7def58"
+
+[[package]]
+name = "reqwest"
+version = "0.13.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "04e9018c9d814e5f30cc16a0f03271aeab3571e609612d9fe78c1aa8d11c2f62"
+dependencies = [
+ "base64",
+ "bytes",
+ "futures-core",
+ "http",
+ "http-body",
+ "http-body-util",
+ "hyper",
+ "hyper-rustls",
+ "hyper-util",
+ "js-sys",
+ "log",
+ "percent-encoding",
+ "pin-project-lite",
+ "quinn",
+ "rustls",
+ "rustls-pki-types",
+ "rustls-platform-verifier",
+ "serde",
+ "serde_json",
+ "sync_wrapper",
+ "tokio",
+ "tokio-rustls",
+ "tower",
+ "tower-http",
+ "tower-service",
+ "url",
+ "wasm-bindgen",
+ "wasm-bindgen-futures",
+ "web-sys",
+]
+
+[[package]]
+name = "ring"
+version = "0.17.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
+dependencies = [
+ "cc",
+ "cfg-if",
+ "getrandom 0.2.16",
+ "libc",
+ "untrusted",
+ "windows-sys 0.52.0",
+]
+
+[[package]]
+name = "rustc-hash"
+version = "2.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "357703d41365b4b27c590e3ed91eabb1b663f07c4c084095e60cbed4362dff0d"
+
+[[package]]
+name = "rustc_version"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cfcb3a22ef46e85b45de6ee7e79d063319ebb6594faafcf1c225ea92ab6e9b92"
+dependencies = [
+ "semver",
+]
+
+[[package]]
+name = "rustix"
+version = "1.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "146c9e247ccc180c1f61615433868c99f3de3ae256a30a43b49f67c2d9171f34"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls"
+version = "0.23.35"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "533f54bc6a7d4f647e46ad909549eda97bf5afc1585190ef692b4286b198bd8f"
+dependencies = [
+ "aws-lc-rs",
+ "once_cell",
+ "rustls-pki-types",
+ "rustls-webpki",
+ "subtle",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-native-certs"
+version = "0.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "612460d5f7bea540c490b2b6395d8e34a953e52b491accd6c86c8164c5932a63"
+dependencies = [
+ "openssl-probe",
+ "rustls-pki-types",
+ "schannel",
+ "security-framework",
+]
+
+[[package]]
+name = "rustls-pki-types"
+version = "1.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21e6f2ab2928ca4291b86736a8bd920a277a399bba1589409d72154ff87c1282"
+dependencies = [
+ "web-time",
+ "zeroize",
+]
+
+[[package]]
+name = "rustls-platform-verifier"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1d99feebc72bae7ab76ba994bb5e121b8d83d910ca40b36e0921f53becc41784"
+dependencies = [
+ "core-foundation",
+ "core-foundation-sys",
+ "jni",
+ "log",
+ "once_cell",
+ "rustls",
+ "rustls-native-certs",
+ "rustls-platform-verifier-android",
+ "rustls-webpki",
+ "security-framework",
+ "security-framework-sys",
+ "webpki-root-certs",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "rustls-platform-verifier-android"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f87165f0995f63a9fbeea62b64d10b4d9d8e78ec6d7d51fb2125fda7bb36788f"
+
+[[package]]
+name = "rustls-webpki"
+version = "0.103.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2ffdfa2f5286e2247234e03f680868ac2815974dc39e00ea15adc445d0aafe52"
+dependencies = [
+ "aws-lc-rs",
+ "ring",
+ "rustls-pki-types",
+ "untrusted",
+]
+
+[[package]]
+name = "rustversion"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
+
+[[package]]
+name = "same-file"
+version = "1.0.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "93fc1dc3aaa9bfed95e02e6eadabb4baf7e3078b0bd1b4d7b6b0b68378900502"
+dependencies = [
+ "winapi-util",
+]
+
+[[package]]
+name = "schannel"
+version = "0.1.28"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "891d81b926048e76efe18581bf793546b4c0eaf8448d72be8de2bbee5fd166e1"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "scopeguard"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
+
+[[package]]
+name = "security-framework"
+version = "3.5.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b3297343eaf830f66ede390ea39da1d462b6b0c1b000f420d0a83f898bbbe6ef"
+dependencies = [
+ "bitflags",
+ "core-foundation",
+ "core-foundation-sys",
+ "libc",
+ "security-framework-sys",
+]
+
+[[package]]
+name = "security-framework-sys"
+version = "2.15.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc1f0cbffaac4852523ce30d8bd3c5cdc873501d96ff467ca09b6767bb8cd5c0"
+dependencies = [
+ "core-foundation-sys",
+ "libc",
+]
+
+[[package]]
+name = "semver"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d767eb0aabc880b29956c35734170f26ed551a859dbd361d140cdbeca61ab1e2"
+
+[[package]]
+name = "serde"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.228"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d540f220d3187173da220f885ab66608367b6574e925011a9353e4badda91d79"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.148"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3084b546a1dd6289475996f182a22aba973866ea8e8b02c51d9f46b1336a22da"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "serde_spanned"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f8bbf91e5a4d6315eee45e704372590b30e260ee83af6639d64557f51b067776"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "shlex"
+version = "1.3.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64"
+
+[[package]]
+name = "signal-hook"
+version = "0.3.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d881a16cf4426aa584979d30bd82cb33429027e42122b169753d6ef1085ed6e2"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook"
+version = "0.4.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a37d01603c37b5466f808de79f845c7116049b0579adb70a6b7d47c1fa3a952"
+dependencies = [
+ "libc",
+ "signal-hook-registry",
+]
+
+[[package]]
+name = "signal-hook-mio"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b75a19a7a740b25bc7944bdee6172368f988763b744e3d4dfe753f6b4ece40cc"
+dependencies = [
+ "libc",
+ "mio",
+ "signal-hook 0.3.18",
+]
+
+[[package]]
+name = "signal-hook-registry"
+version = "1.4.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c4db69cba1110affc0e9f7bcd48bbf87b3f4fc7c61fc9155afd4c469eb3d6c1b"
+dependencies = [
+ "errno",
+ "libc",
+]
+
+[[package]]
+name = "slab"
+version = "0.4.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7a2ae44ef20feb57a68b23d846850f861394c2e02dc425a50098ae8c90267589"
+
+[[package]]
+name = "smallvec"
+version = "1.15.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
+
+[[package]]
+name = "socket2"
+version = "0.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "17129e116933cf371d018bb80ae557e889637989d8638274fb25622827b03881"
+dependencies = [
+ "libc",
+ "windows-sys 0.60.2",
+]
+
+[[package]]
+name = "stable_deref_trait"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"
+
+[[package]]
+name = "strsim"
+version = "0.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"
+
+[[package]]
+name = "subtle"
+version = "2.6.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
+
+[[package]]
+name = "syn"
+version = "2.0.112"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "21f182278bf2d2bcb3c88b1b08a37df029d71ce3d3ae26168e3c653b213b99d4"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "sync_wrapper"
+version = "1.0.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
+dependencies = [
+ "futures-core",
+]
+
+[[package]]
+name = "synstructure"
+version = "0.13.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "728a70f3dbaf5bab7f0c4b1ac8d7ae5ea60a4b5549c8a5914361c99147a709d2"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "sysinfo"
+version = "0.37.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "16607d5caffd1c07ce073528f9ed972d88db15dd44023fa57142963be3feb11f"
+dependencies = [
+ "libc",
+ "memchr",
+ "ntapi",
+ "objc2-core-foundation",
+ "objc2-io-kit",
+ "windows",
+]
+
+[[package]]
+name = "tempfile"
+version = "3.24.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "655da9c7eb6305c55742045d5a8d2037996d61d8de95806335c7c86ce0f82e9c"
+dependencies = [
+ "fastrand",
+ "getrandom 0.3.4",
+ "once_cell",
+ "rustix",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl 1.0.69",
+]
+
+[[package]]
+name = "thiserror"
+version = "2.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f63587ca0f12b72a0600bcba1d40081f830876000bb46dd2337a3051618f4fc8"
+dependencies = [
+ "thiserror-impl 2.0.17",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "2.0.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3ff15c8ecd7de3849db632e14d18d2571fa09dfc5ed93479bc4485c7a517c913"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tinystr"
+version = "0.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "42d3e9c45c09de15d06dd8acf5f4e0e399e85927b7f00711024eb7ae10fa4869"
+dependencies = [
+ "displaydoc",
+ "zerovec",
+]
+
+[[package]]
+name = "tinytemplate"
+version = "1.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "be4d6b5f19ff7664e8c98d03e2139cb510db9b0a60b55f8e8709b689d939b6bc"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "tinyvec"
+version = "1.10.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa5fdc3bce6191a1dbc8c02d5c8bffcf557bafa17c124c5264a458f1b0613fa"
+dependencies = [
+ "tinyvec_macros",
+]
+
+[[package]]
+name = "tinyvec_macros"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
+
+[[package]]
+name = "tokio"
+version = "1.49.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72a2903cd7736441aac9df9d7688bd0ce48edccaadf181c3b90be801e81d3d86"
+dependencies = [
+ "bytes",
+ "libc",
+ "mio",
+ "parking_lot",
+ "pin-project-lite",
+ "signal-hook-registry",
+ "socket2",
+ "tokio-macros",
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "tokio-macros"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "af407857209536a95c8e56f8231ef2c2e2aff839b22e07a1ffcbc617e9db9fa5"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "tokio-rustls"
+version = "0.26.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1729aa945f29d91ba541258c8df89027d5792d85a8841fb65e8bf0f4ede4ef61"
+dependencies = [
+ "rustls",
+ "tokio",
+]
+
+[[package]]
+name = "toml"
+version = "0.9.10+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0825052159284a1a8b4d6c0c86cbc801f2da5afd2b225fa548c72f2e74002f48"
+dependencies = [
+ "indexmap",
+ "serde_core",
+ "serde_spanned",
+ "toml_datetime",
+ "toml_parser",
+ "toml_writer",
+ "winnow",
+]
+
+[[package]]
+name = "toml_datetime"
+version = "0.7.5+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "92e1cfed4a3038bc5a127e35a2d360f145e1f4b971b551a2ba5fd7aedf7e1347"
+dependencies = [
+ "serde_core",
+]
+
+[[package]]
+name = "toml_parser"
+version = "1.0.6+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a3198b4b0a8e11f09dd03e133c0280504d0801269e9afa46362ffde1cbeebf44"
+dependencies = [
+ "winnow",
+]
+
+[[package]]
+name = "toml_writer"
+version = "1.0.6+spec-1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ab16f14aed21ee8bfd8ec22513f7287cd4a91aa92e44edfe2c17ddd004e92607"
+
+[[package]]
+name = "tower"
+version = "0.5.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d039ad9159c98b70ecfd540b2573b97f7f52c3e8d9f8ad57a24b916a536975f9"
+dependencies = [
+ "futures-core",
+ "futures-util",
+ "pin-project-lite",
+ "sync_wrapper",
+ "tokio",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "tower-http"
+version = "0.6.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d4e6559d53cc268e5031cd8429d05415bc4cb4aefc4aa5d6cc35fbf5b924a1f8"
+dependencies = [
+ "bitflags",
+ "bytes",
+ "futures-util",
+ "http",
+ "http-body",
+ "iri-string",
+ "pin-project-lite",
+ "tower",
+ "tower-layer",
+ "tower-service",
+]
+
+[[package]]
+name = "tower-layer"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"
+
+[[package]]
+name = "tower-service"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"
+
+[[package]]
+name = "tracing"
+version = "0.1.44"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"
+dependencies = [
+ "pin-project-lite",
+ "tracing-core",
+]
+
+[[package]]
+name = "tracing-core"
+version = "0.1.36"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"
+dependencies = [
+ "once_cell",
+]
+
+[[package]]
+name = "try-lock"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9312f7c4f6ff9069b165498234ce8be658059c6728633667c526e27dc2cf1df5"
+
+[[package]]
+name = "unicode-segmentation"
+version = "1.12.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f6ccf251212114b54433ec949fd6a7841275f9ada20dddd2f29e9ceea4501493"
+
+[[package]]
+name = "untrusted"
+version = "0.9.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
+
+[[package]]
+name = "url"
+version = "2.5.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "08bc136a29a3d1758e07a9cca267be308aeebf5cfd5a10f3f67ab2097683ef5b"
+dependencies = [
+ "form_urlencoded",
+ "idna",
+ "percent-encoding",
+ "serde",
+]
+
+[[package]]
+name = "utf8_iter"
+version = "1.0.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
+
+[[package]]
+name = "utf8parse"
+version = "0.2.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"
+
+[[package]]
+name = "walkdir"
+version = "2.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29790946404f91d9c5d06f9874efddea1dc06c5efe94541a7d6863108e3a5e4b"
+dependencies = [
+ "same-file",
+ "winapi-util",
+]
+
+[[package]]
+name = "want"
+version = "0.3.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
+dependencies = [
+ "try-lock",
+]
+
+[[package]]
+name = "wasi"
+version = "0.11.1+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
+
+[[package]]
+name = "wasip2"
+version = "1.0.1+wasi-0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0562428422c63773dad2c345a1882263bbf4d65cf3f42e90921f787ef5ad58e7"
+dependencies = [
+ "wit-bindgen",
+]
+
+[[package]]
+name = "wasm-bindgen"
+version = "0.2.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0d759f433fa64a2d763d1340820e46e111a7a5ab75f993d1852d70b03dbb80fd"
+dependencies = [
+ "cfg-if",
+ "once_cell",
+ "rustversion",
+ "wasm-bindgen-macro",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-futures"
+version = "0.4.56"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "836d9622d604feee9e5de25ac10e3ea5f2d65b41eac0d9ce72eb5deae707ce7c"
+dependencies = [
+ "cfg-if",
+ "js-sys",
+ "once_cell",
+ "wasm-bindgen",
+ "web-sys",
+]
+
+[[package]]
+name = "wasm-bindgen-macro"
+version = "0.2.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "48cb0d2638f8baedbc542ed444afc0644a29166f1595371af4fecf8ce1e7eeb3"
+dependencies = [
+ "quote",
+ "wasm-bindgen-macro-support",
+]
+
+[[package]]
+name = "wasm-bindgen-macro-support"
+version = "0.2.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cefb59d5cd5f92d9dcf80e4683949f15ca4b511f4ac0a6e14d4e1ac60c6ecd40"
+dependencies = [
+ "bumpalo",
+ "proc-macro2",
+ "quote",
+ "syn",
+ "wasm-bindgen-shared",
+]
+
+[[package]]
+name = "wasm-bindgen-shared"
+version = "0.2.106"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cbc538057e648b67f72a982e708d485b2efa771e1ac05fec311f9f63e5800db4"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "web-sys"
+version = "0.3.83"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b32828d774c412041098d182a8b38b16ea816958e07cf40eec2bc080ae137ac"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "web-time"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
+dependencies = [
+ "js-sys",
+ "wasm-bindgen",
+]
+
+[[package]]
+name = "webpki-root-certs"
+version = "1.0.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "36a29fc0408b113f68cf32637857ab740edfafdf460c326cd2afaa2d84cc05dc"
+dependencies = [
+ "rustls-pki-types",
+]
+
+[[package]]
+name = "winapi"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"
+dependencies = [
+ "winapi-i686-pc-windows-gnu",
+ "winapi-x86_64-pc-windows-gnu",
+]
+
+[[package]]
+name = "winapi-i686-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"
+
+[[package]]
+name = "winapi-util"
+version = "0.1.11"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
+dependencies = [
+ "windows-sys 0.61.2",
+]
+
+[[package]]
+name = "winapi-x86_64-pc-windows-gnu"
+version = "0.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"
+
+[[package]]
+name = "windows"
+version = "0.61.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9babd3a767a4c1aef6900409f85f5d53ce2544ccdfaa86dad48c91782c6d6893"
+dependencies = [
+ "windows-collections",
+ "windows-core",
+ "windows-future",
+ "windows-link 0.1.3",
+ "windows-numerics",
+]
+
+[[package]]
+name = "windows-collections"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3beeceb5e5cfd9eb1d76b381630e82c4241ccd0d27f1a39ed41b2760b255c5e8"
+dependencies = [
+ "windows-core",
+]
+
+[[package]]
+name = "windows-core"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c0fdd3ddb90610c7638aa2b3a3ab2904fb9e5cdbecc643ddb3647212781c4ae3"
+dependencies = [
+ "windows-implement",
+ "windows-interface",
+ "windows-link 0.1.3",
+ "windows-result",
+ "windows-strings",
+]
+
+[[package]]
+name = "windows-future"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fc6a41e98427b19fe4b73c550f060b59fa592d7d686537eebf9385621bfbad8e"
+dependencies = [
+ "windows-core",
+ "windows-link 0.1.3",
+ "windows-threading",
+]
+
+[[package]]
+name = "windows-implement"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "053e2e040ab57b9dc951b72c264860db7eb3b0200ba345b4e4c3b14f67855ddf"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-interface"
+version = "0.59.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f316c4a2570ba26bbec722032c4099d8c8bc095efccdc15688708623367e358"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "windows-link"
+version = "0.1.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5e6ad25900d524eaabdbbb96d20b4311e1e7ae1699af4fb28c17ae66c80d798a"
+
+[[package]]
+name = "windows-link"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"
+
+[[package]]
+name = "windows-numerics"
+version = "0.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9150af68066c4c5c07ddc0ce30421554771e528bde427614c61038bc2c92c2b1"
+dependencies = [
+ "windows-core",
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows-result"
+version = "0.3.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56f42bd332cc6c8eac5af113fc0c1fd6a8fd2aa08a0119358686e5160d0586c6"
+dependencies = [
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows-strings"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "56e6c93f3a0c3b36176cb1327a4958a0353d5d166c2a35cb268ace15e91d3b57"
+dependencies = [
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.45.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "75283be5efb2831d37ea142365f009c02ec203cd29a3ebecbc093d52315b66d0"
+dependencies = [
+ "windows-targets 0.42.2",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets 0.52.6",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.60.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f2f500e4d28234f72040990ec9d39e3a6b950f9f22d3dba18416c35882612bcb"
+dependencies = [
+ "windows-targets 0.53.5",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.61.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"
+dependencies = [
+ "windows-link 0.2.1",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e5180c00cd44c9b1c88adb3693291f1cd93605ded80c250a75d472756b4d071"
+dependencies = [
+ "windows_aarch64_gnullvm 0.42.2",
+ "windows_aarch64_msvc 0.42.2",
+ "windows_i686_gnu 0.42.2",
+ "windows_i686_msvc 0.42.2",
+ "windows_x86_64_gnu 0.42.2",
+ "windows_x86_64_gnullvm 0.42.2",
+ "windows_x86_64_msvc 0.42.2",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm 0.52.6",
+ "windows_aarch64_msvc 0.52.6",
+ "windows_i686_gnu 0.52.6",
+ "windows_i686_gnullvm 0.52.6",
+ "windows_i686_msvc 0.52.6",
+ "windows_x86_64_gnu 0.52.6",
+ "windows_x86_64_gnullvm 0.52.6",
+ "windows_x86_64_msvc 0.52.6",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.53.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4945f9f551b88e0d65f3db0bc25c33b8acea4d9e41163edf90dcd0b19f9069f3"
+dependencies = [
+ "windows-link 0.2.1",
+ "windows_aarch64_gnullvm 0.53.1",
+ "windows_aarch64_msvc 0.53.1",
+ "windows_i686_gnu 0.53.1",
+ "windows_i686_gnullvm 0.53.1",
+ "windows_i686_msvc 0.53.1",
+ "windows_x86_64_gnu 0.53.1",
+ "windows_x86_64_gnullvm 0.53.1",
+ "windows_x86_64_msvc 0.53.1",
+]
+
+[[package]]
+name = "windows-threading"
+version = "0.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b66463ad2e0ea3bbf808b7f1d371311c80e115c0b71d60efc142cafbcfb057a6"
+dependencies = [
+ "windows-link 0.1.3",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "597a5118570b68bc08d8d59125332c54f1ba9d9adeedeef5b99b02ba2b0698f8"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a9d8416fa8b42f5c947f8482c43e7d89e73a173cead56d044f6a56104a6d1b53"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e08e8864a60f06ef0d0ff4ba04124db8b0fb3be5776a5cd47641e942e58c4d43"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b9d782e804c2f632e395708e99a94275910eb9100b2114651e04744e9b125006"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "c61d927d8da41da96a81f029489353e68739737d3beca43145c8afec9a31a84f"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "960e6da069d81e09becb0ca57a65220ddff016ff2d6af6a223cf372a506593a3"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fa7359d10048f68ab8b09fa71c3daccfb0e9b559aed648a8f95469c27057180c"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "44d840b6ec649f480a41c8d80f9c65108b92d89345dd94027bfe06ac444d1060"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e7ac75179f18232fe9c285163565a57ef8d3c89254a30685b57d83a38d326c2"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8de912b8b8feb55c064867cf047dda097f92d51efad5b491dfb98f6bbb70cb36"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c3842cdd74a865a8066ab39c8a7a473c0778a3f29370b5fd6b4b9aa7df4a499"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "26d41b46a36d453748aedef1486d5c7a85db22e56aff34643984ea85514e94a3"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0ffa179e2d07eee8ad8f57493436566c7cc30ac536a3379fdf008f47f6bb7ae1"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.42.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9aec5da331524158c6d1a4ac0ab1541149c0b9505fde06423b02f5ef0106b9f0"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.53.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d6bbff5f0aada427a1e5a6da5f1f98158182f26556f345ac9e04d36d0ebed650"
+
+[[package]]
+name = "winnow"
+version = "0.7.14"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "5a5364e9d77fcdeeaa6062ced926ee3381faa2ee02d3eb83a5c27a8825540829"
+
+[[package]]
+name = "wit-bindgen"
+version = "0.46.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "f17a85883d4e6d00e8a97c586de764dabcc06133f7f1d55dce5cdc070ad7fe59"
+
+[[package]]
+name = "writeable"
+version = "0.6.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9edde0db4769d2dc68579893f2306b26c6ecfbe0ef499b013d731b7b9247e0b9"
+
+[[package]]
+name = "xdg"
+version = "3.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2fb433233f2df9344722454bc7e96465c9d03bff9d77c248f9e7523fe79585b5"
+
+[[package]]
+name = "yoke"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "72d6e5c6afb84d73944e5cedb052c4680d5657337201555f9f2a16b7406d4954"
+dependencies = [
+ "stable_deref_trait",
+ "yoke-derive",
+ "zerofrom",
+]
+
+[[package]]
+name = "yoke-derive"
+version = "0.8.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b659052874eb698efe5b9e8cf382204678a0086ebf46982b79d6ca3182927e5d"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zerocopy"
+version = "0.8.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fd74ec98b9250adb3ca554bdde269adf631549f51d8a8f8f0a10b50f1cb298c3"
+dependencies = [
+ "zerocopy-derive",
+]
+
+[[package]]
+name = "zerocopy-derive"
+version = "0.8.31"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d8a8d209fdf45cf5138cbb5a506f6b52522a25afccc534d1475dad8e31105c6a"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zerofrom"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "50cc42e0333e05660c3587f3bf9d0478688e15d870fab3346451ce7f8c9fbea5"
+dependencies = [
+ "zerofrom-derive",
+]
+
+[[package]]
+name = "zerofrom-derive"
+version = "0.1.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d71e5d6e06ab090c67b5e44993ec16b72dcbaabc526db883a360057678b48502"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+ "synstructure",
+]
+
+[[package]]
+name = "zeroize"
+version = "1.8.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b97154e67e32c85465826e8bcc1c59429aaaf107c1e4a9e53c8d8ccd5eff88d0"
+
+[[package]]
+name = "zerotrie"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2a59c17a5562d507e4b54960e8569ebee33bee890c70aa3fe7b97e85a9fd7851"
+dependencies = [
+ "displaydoc",
+ "yoke",
+ "zerofrom",
+]
+
+[[package]]
+name = "zerovec"
+version = "0.11.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6c28719294829477f525be0186d13efa9a3c602f7ec202ca9e353d310fb9a002"
+dependencies = [
+ "yoke",
+ "zerofrom",
+ "zerovec-derive",
+]
+
+[[package]]
+name = "zerovec-derive"
+version = "0.11.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "eadce39539ca5cb3985590102671f2567e659fca9666581ad3411d59207951f3"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "zmij"
+version = "1.0.8"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "317f17ff091ac4515f17cc7a190d2769a8c9a96d227de5d64b500b01cda8f2cd"
diff --git a/Cargo.toml b/Cargo.toml
new file mode 100644
index 0000000..0344ebc
--- /dev/null
+++ b/Cargo.toml
@@ -0,0 +1,51 @@
+[package]
+name = "clai"
+version = "0.1.0"
+edition = "2021"
+authors = ["Your Name <you@example.com>"]
+
+[lib]
+name = "clai"
+path = "src/lib.rs"
+
+[[bin]]
+name = "clai"
+path = "src/main.rs"
+
+[dependencies]
+clap = { version = "4.5", features = ["derive"] }
+toml = "0.9"
+serde = { version = "1.0", features = ["derive"] }
+serde_json = "1.0"
+sysinfo = "0.37"
+regex = "1.12"
+signal-hook = "0.4"
+xdg = "3.0"
+directories = "6.0"
+anyhow = "1.0"
+thiserror = "2.0"
+tokio = { version = "1.49", features = ["full"] }
+reqwest = { version = "0.13", features = ["json", "rustls"], default-features = false }
+async-trait = "0.1"
+owo-colors = "4.2"
+atty = "0.2"
+crossterm = "0.29"
+tempfile = "3.10"
+once_cell = "1.20"
+
+[profile.release]
+codegen-units = 1
+lto = true
+panic = "abort"
+opt-level = 3
+strip = true
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[features]
+bench = []
+
+[[bench]]
+name = "startup"
+harness = false
diff --git a/Makefile.toml b/Makefile.toml
new file mode 100644
index 0000000..efeac3e
--- /dev/null
+++ b/Makefile.toml
@@ -0,0 +1,78 @@
+[tasks.default]
+description = "Show available tasks"
+command = "cargo"
+args = ["make", "--list-all-steps"]
+
+[tasks.build]
+description = "Build the project in debug mode"
+command = "cargo"
+args = ["build"]
+
+[tasks.build-release]
+description = "Build the project in release mode"
+command = "cargo"
+args = ["build", "--release"]
+
+[tasks.run]
+description = "Run the application"
+command = "cargo"
+args = ["run", "--"]
+
+[tasks.test]
+description = "Run all tests"
+command = "cargo"
+args = ["test"]
+
+[tasks.check]
+description = "Check the project without building"
+command = "cargo"
+args = ["check"]
+
+[tasks.clippy]
+description = "Run clippy linter"
+command = "cargo"
+args = ["clippy", "--", "-D", "warnings"]
+
+[tasks.fmt]
+description = "Format the code"
+command = "cargo"
+args = ["fmt"]
+
+[tasks.fmt-check]
+description = "Check code formatting"
+command = "cargo"
+args = ["fmt", "--", "--check"]
+
+[tasks.clean]
+description = "Clean build artifacts"
+command = "cargo"
+args = ["clean"]
+
+[tasks.lint]
+description = "Run all linters (clippy + fmt check)"
+dependencies = ["clippy", "fmt-check"]
+
+[tasks.dev]
+description = "Run in development mode with watch (requires cargo-watch)"
+command = "cargo"
+args = ["watch", "-x", "run"]
+
+[tasks.release]
+description = "Build optimized release binary"
+dependencies = ["lint", "test", "build-release"]
+
+[tasks.install]
+description = "Install the binary to cargo bin"
+command = "cargo"
+args = ["install", "--path", "."]
+
+[tasks.cross-build]
+description = "Build for all cross-compilation targets (requires cross)"
+command = "bash"
+args = ["-c", "cross build --release --target x86_64-unknown-linux-musl && cross build --release --target aarch64-unknown-linux-musl"]
+
+[tasks.help]
+description = "Show this help message"
+command = "cargo"
+args = ["make", "--list-all-steps"]
+
diff --git a/README.md b/README.md
index 24d91b7..23f2a6d 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,67 @@
-# clAI
\ No newline at end of file
+# clai
+
+A CLI tool that converts natural language into shell commands using AI.
+
+```bash
+$ clai "find all rust files modified today"
+find . -name "*.rs" -mtime 0
+```
+
+## Installation
+
+Requires Rust 1.70+.
+
+```bash
+git clone https://github.com/Vedaant-Rajoo/clAI.git
+cd clAI
+cargo install --path .
+```
+
+## Setup
+
+1. Get an API key from [OpenRouter](https://openrouter.ai)
+2. Set the environment variable:
+   ```bash
+   export OPENROUTER_API_KEY="your-key-here"
+   ```
+
+## Usage
+
+```bash
+clai "list files by size"
+clai -i "delete old logs"        # interactive mode - confirm before executing
+clai -n "dangerous command"      # dry-run - show without executing
+clai -o 3 "compress images"      # generate 3 options to choose from
+```
+
+### Options
+
+| Flag                | Description                    |
+| ------------------- | ------------------------------ |
+| `-i, --interactive` | Prompt before executing        |
+| `-n, --dry-run`     | Show command without executing |
+| `-o, --options <N>` | Generate N command options     |
+| `-f, --force`       | Skip safety confirmations      |
+| `-q, --quiet`       | Minimal output                 |
+| `-v, --verbose`     | Increase verbosity             |
+
+## Configuration
+
+Create `~/.config/clai/config.toml`:
+
+```toml
+[provider]
+default = "openrouter"
+
+[provider.openrouter]
+model = "qwen/qwen3-coder"
+
+[safety]
+confirm-dangerous = true
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and full configuration options.
+
+## License
+
+MIT
diff --git a/benches/startup.rs b/benches/startup.rs
new file mode 100644
index 0000000..608c614
--- /dev/null
+++ b/benches/startup.rs
@@ -0,0 +1,326 @@
+//! Performance benchmarks for clai startup and critical paths
+//!
+//! Targets:
+//! - Cold startup: <50ms median
+//! - History reading: <100ms for large files
+//!
+//! Run with: `cargo bench --features bench`
+
+use clai::cli::Cli;
+use clai::config::{get_file_config, Config};
+use clai::context::gatherer::gather_context;
+use clai::signals::setup_signal_handlers;
+use criterion::{black_box, criterion_group, criterion_main, Criterion};
+use std::time::Instant;
+
+/// Helper to reset config cache when bench feature is enabled
+#[cfg(feature = "bench")]
+fn reset_cache() {
+    clai::config::cache::reset_config_cache();
+}
+
+#[cfg(not(feature = "bench"))]
+fn reset_cache() {
+    // No-op when bench feature not enabled
+}
+
+/// Benchmark cold startup: parsing args, loading config, and gathering context
+///
+/// This measures the critical path from program start to first context ready.
+/// Target: <50ms median
+fn benchmark_startup(c: &mut Criterion) {
+    let mut group = c.benchmark_group("startup");
+
+    // Set sample size and measurement time for startup benchmarks
+    group.sample_size(100);
+    group.measurement_time(std::time::Duration::from_secs(10));
+
+    // Benchmark: CLI struct creation (not actual parsing - parsing requires process args)
+    group.bench_function("cli_struct_creation", |b| {
+        b.iter(|| {
+            // Creates Cli struct directly - measures struct allocation overhead
+            let _cli = Cli {
+                instruction: black_box("list files".to_string()),
+                model: None,
+                provider: None,
+                quiet: false,
+                verbose: 0,
+                no_color: false,
+                color: clai::cli::ColorChoice::Auto,
+                interactive: false,
+                force: false,
+                dry_run: false,
+                context: None,
+                offline: false,
+                num_options: 3,
+                debug: false,
+                debug_file: None,
+            };
+        });
+    });
+
+    // Benchmark: Config loading (lazy, first access)
+    group.bench_function("load_config_cold", |b| {
+        let cli = Cli {
+            instruction: "test instruction".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: clai::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        b.iter(|| {
+            // Reset cache for each iteration to measure cold load
+            reset_cache();
+            let _config = get_file_config(black_box(&cli));
+        });
+    });
+
+    // Benchmark: Config loading (warm - cached)
+    group.bench_function("load_config_warm", |b| {
+        let cli = Cli {
+            instruction: "test instruction".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: clai::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        // Pre-warm cache
+        let _ = get_file_config(&cli);
+
+        b.iter(|| {
+            let _config = get_file_config(black_box(&cli));
+        });
+    });
+
+    // Benchmark: Config creation from CLI
+    group.bench_function("create_config_from_cli", |b| {
+        b.iter(|| {
+            let cli = Cli {
+                instruction: "test instruction".to_string(),
+                model: None,
+                provider: None,
+                quiet: false,
+                verbose: 0,
+                no_color: false,
+                color: clai::cli::ColorChoice::Auto,
+                interactive: false,
+                force: false,
+                dry_run: false,
+                context: None,
+                offline: false,
+                num_options: 3,
+                debug: false,
+                debug_file: None,
+            };
+
+            let _config = Config::from_cli(black_box(cli));
+        });
+    });
+
+    // Benchmark: Signal handler setup
+    group.bench_function("setup_signal_handlers", |b| {
+        b.iter(|| {
+            let _flag = setup_signal_handlers();
+        });
+    });
+
+    // Benchmark: Context gathering (cold start)
+    group.bench_function("gather_context", |b| {
+        b.iter(|| {
+            // Reset system info cache for cold start measurement
+            // Note: System info cache is internal, so we measure with cache
+            let config = Config {
+                instruction: "test".to_string(),
+                model: None,
+                provider: None,
+                quiet: false,
+                verbose: 0,
+                no_color: false,
+                color: clai::cli::ColorChoice::Auto,
+                interactive: false,
+                force: false,
+                dry_run: false,
+                context: None,
+                offline: false,
+                num_options: 3,
+                debug: false,
+                debug_log_file: None,
+            };
+
+            let _context = gather_context(black_box(&config));
+        });
+    });
+
+    // Benchmark: Full startup path (cold)
+    group.bench_function("full_startup_cold", |b| {
+        b.iter(|| {
+            // Reset caches for true cold start
+            reset_cache();
+
+            let start = Instant::now();
+
+            // 1. Parse args (simulated)
+            let cli = Cli {
+                instruction: "test instruction".to_string(),
+                model: None,
+                provider: None,
+                quiet: false,
+                verbose: 0,
+                no_color: false,
+                color: clai::cli::ColorChoice::Auto,
+                interactive: false,
+                force: false,
+                dry_run: false,
+                context: None,
+                offline: false,
+                num_options: 3,
+                debug: false,
+                debug_file: None,
+            };
+
+            // 2. Setup signal handlers
+            let _interrupt_flag = setup_signal_handlers();
+
+            // 3. Load config (lazy, first access)
+            let _file_config = get_file_config(&cli);
+
+            // 4. Create runtime config
+            let config = Config::from_cli(cli);
+
+            // 5. Gather context (critical path)
+            let _context = gather_context(&config);
+
+            let elapsed = start.elapsed();
+
+            // Assert startup is <50ms (target)
+            // Note: This is informational - criterion will report actual times
+            black_box(elapsed);
+        });
+    });
+
+    // Benchmark: Full startup path (warm - with caches)
+    group.bench_function("full_startup_warm", |b| {
+        // Pre-warm caches
+        let cli = Cli {
+            instruction: "warmup".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: clai::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+        let _ = get_file_config(&cli);
+        let config = Config::from_cli(cli.clone());
+        let _ = gather_context(&config);
+
+        b.iter(|| {
+            let start = Instant::now();
+
+            // 1. Parse args (simulated)
+            let cli = Cli {
+                instruction: "test instruction".to_string(),
+                model: None,
+                provider: None,
+                quiet: false,
+                verbose: 0,
+                no_color: false,
+                color: clai::cli::ColorChoice::Auto,
+                interactive: false,
+                force: false,
+                dry_run: false,
+                context: None,
+                offline: false,
+                num_options: 3,
+                debug: false,
+                debug_file: None,
+            };
+
+            // 2. Setup signal handlers
+            let _interrupt_flag = setup_signal_handlers();
+
+            // 3. Load config (cached)
+            let _file_config = get_file_config(&cli);
+
+            // 4. Create runtime config
+            let config = Config::from_cli(cli);
+
+            // 5. Gather context (cached system info)
+            let _context = gather_context(&config);
+
+            let elapsed = start.elapsed();
+            black_box(elapsed);
+        });
+    });
+
+    group.finish();
+}
+
+/// Benchmark history reading performance
+///
+/// Measures tail read performance for large history files.
+/// Target: <100ms for large files
+fn benchmark_history_reading(c: &mut Criterion) {
+    use std::io::Write;
+    use std::path::PathBuf;
+    use tempfile::NamedTempFile;
+
+    let mut group = c.benchmark_group("history");
+    group.sample_size(50);
+
+    // Create a large history file (1000+ lines)
+    let mut temp_file = NamedTempFile::new().unwrap();
+    let history_path = PathBuf::from(temp_file.path());
+
+    // Write to file using existing handle (avoids Windows exclusive lock issues)
+    {
+        let file = temp_file.as_file_mut();
+        for i in 1..=1000 {
+            writeln!(file, "command_{}", i).unwrap();
+        }
+        file.flush().unwrap();
+    }
+
+    group.bench_function("read_history_tail_1000_lines", |b| {
+        b.iter(|| {
+            let _history =
+                clai::context::history::read_history_tail(black_box(&history_path), black_box(100));
+        });
+    });
+
+    group.finish();
+    // temp_file is dropped here, cleaning up the file
+}
+
+criterion_group!(benches, benchmark_startup, benchmark_history_reading);
+criterion_main!(benches);
diff --git a/examples/test_context.rs b/examples/test_context.rs
new file mode 100644
index 0000000..31ddca8
--- /dev/null
+++ b/examples/test_context.rs
@@ -0,0 +1,106 @@
+// Simple example to test context gathering
+// Run with: cargo run --example test_context
+
+use clai::config::Config;
+use clai::context::gatherer::gather_context;
+
+fn main() {
+    println!("Testing Context Gathering...\n");
+
+    // Create a test config
+    let config = Config {
+        instruction: "test instruction".to_string(),
+        model: None,
+        provider: None,
+        quiet: false,
+        verbose: 0,
+        no_color: false,
+        color: clai::cli::ColorChoice::Auto,
+        interactive: false,
+        force: false,
+        dry_run: false,
+        context: None,
+        offline: false,
+        num_options: 3,
+        debug: false,
+        debug_log_file: None,
+    };
+
+    // Gather context
+    match gather_context(&config) {
+        Ok(json_str) => {
+            println!("✅ Context gathered successfully!\n");
+            println!("=== Context JSON Output ===\n");
+            println!("{}", json_str);
+            println!("\n=== End of Context Output ===\n");
+
+            // Parse and display summary
+            if let Ok(parsed) = serde_json::from_str::<serde_json::Value>(&json_str) {
+                println!("=== Context Summary ===");
+
+                if let Some(system) = parsed.get("system").and_then(|s| s.as_object()) {
+                    println!("System:");
+                    println!(
+                        "  OS: {}",
+                        system.get("os_name").unwrap_or(&serde_json::Value::Null)
+                    );
+                    println!(
+                        "  Shell: {}",
+                        system.get("shell").unwrap_or(&serde_json::Value::Null)
+                    );
+                    println!(
+                        "  Architecture: {}",
+                        system
+                            .get("architecture")
+                            .unwrap_or(&serde_json::Value::Null)
+                    );
+                }
+
+                if let Some(cwd) = parsed.get("cwd").and_then(|c| c.as_str()) {
+                    println!("Current Directory: {}", cwd);
+                }
+
+                if let Some(files) = parsed.get("files").and_then(|f| f.as_array()) {
+                    println!("Files in directory: {}", files.len());
+                    if files.len() > 0 {
+                        println!("  (showing first 5)");
+                        for (i, file) in files.iter().take(5).enumerate() {
+                            if let Some(f) = file.as_str() {
+                                println!("    {}. {}", i + 1, f);
+                            }
+                        }
+                    }
+                }
+
+                if let Some(history) = parsed.get("history").and_then(|h| h.as_array()) {
+                    println!("Shell History: {} commands", history.len());
+                    for (i, cmd) in history.iter().enumerate() {
+                        if let Some(c) = cmd.as_str() {
+                            println!("  {}. {}", i + 1, c);
+                        }
+                    }
+                }
+
+                if let Some(stdin) = parsed.get("stdin") {
+                    if stdin.is_null() {
+                        println!("Stdin: (not piped)");
+                    } else if let Some(s) = stdin.as_str() {
+                        println!("Stdin: {} bytes", s.len());
+                        if s.len() > 0 {
+                            let preview = if s.len() > 50 {
+                                format!("{}...", &s[..50])
+                            } else {
+                                s.to_string()
+                            };
+                            println!("  Preview: {}", preview);
+                        }
+                    }
+                }
+            }
+        }
+        Err(e) => {
+            eprintln!("❌ Failed to gather context: {}", e);
+            std::process::exit(1);
+        }
+    }
+}
diff --git a/scripts/hooks/pre-commit b/scripts/hooks/pre-commit
new file mode 100755
index 0000000..9a617db
--- /dev/null
+++ b/scripts/hooks/pre-commit
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Git pre-commit hook for clai
+# This hook runs automatically before each commit
+
+set -e
+
+echo "Running pre-commit checks..."
+
+echo "1. Formatting code..."
+cargo fmt
+
+echo "2. Running clippy..."
+cargo clippy -- -D warnings
+
+echo "3. Running tests..."
+cargo test
+
+echo "✓ All pre-commit checks passed!"
diff --git a/scripts/install-hooks.sh b/scripts/install-hooks.sh
new file mode 100755
index 0000000..81dbf35
--- /dev/null
+++ b/scripts/install-hooks.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# Install Git hooks for clai
+# Run this script once after cloning the repository
+
+set -e
+
+REPO_ROOT="$(git rev-parse --show-toplevel)"
+HOOKS_DIR="$REPO_ROOT/.git/hooks"
+SCRIPTS_HOOKS_DIR="$REPO_ROOT/scripts/hooks"
+
+echo "Installing Git hooks for clai..."
+
+# Create hooks directory if it doesn't exist
+mkdir -p "$HOOKS_DIR"
+
+# Install pre-commit hook
+if [ -f "$SCRIPTS_HOOKS_DIR/pre-commit" ]; then
+    echo "Installing pre-commit hook..."
+    cp "$SCRIPTS_HOOKS_DIR/pre-commit" "$HOOKS_DIR/pre-commit"
+    chmod +x "$HOOKS_DIR/pre-commit"
+    echo "✓ Pre-commit hook installed"
+else
+    echo "✗ Warning: scripts/hooks/pre-commit not found"
+fi
+
+echo ""
+echo "✓ Git hooks installation complete!"
+echo ""
+echo "The pre-commit hook will now run automatically before each commit."
+echo "It will:"
+echo "  1. Format your code with 'cargo fmt'"
+echo "  2. Run 'cargo clippy' with warnings as errors"
+echo "  3. Run 'cargo test'"
+echo ""
+echo "To bypass the hook temporarily, use: git commit --no-verify"
diff --git a/scripts/lint.sh b/scripts/lint.sh
new file mode 100755
index 0000000..ec18573
--- /dev/null
+++ b/scripts/lint.sh
@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# Linting checks for clai
+# Runs clippy and format checks without making changes
+
+set -e
+
+echo "Running lint checks..."
+
+echo "1. Checking code formatting..."
+cargo fmt -- --check
+
+echo "2. Running clippy..."
+cargo clippy -- -D warnings
+
+echo "✓ All lint checks passed!"
diff --git a/scripts/pre-commit.sh b/scripts/pre-commit.sh
new file mode 100755
index 0000000..b144b79
--- /dev/null
+++ b/scripts/pre-commit.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# Pre-commit checks for clai
+# Run this script before committing to ensure code quality
+
+set -e
+
+echo "Running pre-commit checks..."
+
+echo "1. Formatting code..."
+cargo fmt
+
+echo "2. Running clippy..."
+cargo clippy -- -D warnings
+
+echo "3. Running tests..."
+cargo test
+
+echo "✓ All pre-commit checks passed!"
diff --git a/src/ai/chain.rs b/src/ai/chain.rs
new file mode 100644
index 0000000..d11dd22
--- /dev/null
+++ b/src/ai/chain.rs
@@ -0,0 +1,297 @@
+use crate::ai::provider::Provider;
+use crate::ai::providers::openrouter::OpenRouterProvider;
+use crate::ai::types::{ChatRequest, ChatResponse};
+use crate::config::file::FileConfig;
+use anyhow::Result;
+use std::sync::{Arc, Mutex};
+
+/// Type alias for cached provider instances
+type ProviderCache = Arc<Mutex<Vec<Option<Arc<dyn Provider>>>>>;
+
+/// Provider chain for fallback support
+///
+/// Implements the Provider trait and tries each provider in sequence
+/// until one succeeds. Supports lazy initialization of providers.
+pub struct ProviderChain {
+    /// List of provider names in fallback order
+    providers: Vec<String>,
+    /// Lazy-initialized provider instances (with interior mutability)
+    provider_instances: ProviderCache,
+    /// File config for provider settings
+    config: FileConfig,
+}
+
+impl ProviderChain {
+    /// Create a new provider chain from config
+    ///
+    /// # Arguments
+    /// * `config` - File configuration with provider settings
+    ///
+    /// # Returns
+    /// * `ProviderChain` - New chain instance
+    pub fn new(config: FileConfig) -> Self {
+        // Get fallback chain from config
+        let mut providers = config.provider.fallback.clone();
+
+        // Add default provider to the front if not already in chain
+        let default = config.provider.default.clone();
+        if !providers.contains(&default) {
+            providers.insert(0, default);
+        }
+
+        Self {
+            providers,
+            provider_instances: Arc::new(Mutex::new(Vec::new())),
+            config,
+        }
+    }
+
+    /// Initialize a provider by name
+    ///
+    /// Lazy initialization - creates provider instance on first access.
+    ///
+    /// # Arguments
+    /// * `name` - Provider name (e.g., "openrouter", "ollama")
+    ///
+    /// # Returns
+    /// * `Result<Arc<dyn Provider>>` - Provider instance or error
+    fn init_provider(&self, name: &str) -> Result<Arc<dyn Provider>> {
+        match name {
+            "openrouter" => {
+                // Get API key from config or environment
+                // Priority: 1) api_key in config, 2) api_key_env in config, 3) OPENROUTER_API_KEY env var
+                let openrouter_config = self.config.providers.get("openrouter");
+
+                let api_key = openrouter_config
+                    .and_then(|c| c.api_key.clone())
+                    .or_else(|| {
+                        openrouter_config
+                            .and_then(|c| c.api_key_env.as_ref())
+                            .and_then(|env_var| std::env::var(env_var).ok())
+                    })
+                    .or_else(OpenRouterProvider::api_key_from_env)
+                    .ok_or_else(|| anyhow::anyhow!("OpenRouter API key not found"))?;
+
+                // Get model from config (defaults to KimiK2 if not set)
+                let model = self
+                    .config
+                    .providers
+                    .get("openrouter")
+                    .and_then(|c| c.model.clone());
+
+                let provider = OpenRouterProvider::new(api_key, model);
+                Ok(Arc::new(provider))
+            }
+            _ => anyhow::bail!("Unknown provider: {}", name),
+        }
+    }
+
+    /// Get or initialize a provider by index
+    ///
+    /// # Arguments
+    /// * `index` - Provider index in chain
+    ///
+    /// # Returns
+    /// * `Result<Arc<dyn Provider>>` - Provider instance or error
+    fn get_provider(&self, index: usize) -> Result<Arc<dyn Provider>> {
+        let mut instances = self.provider_instances.lock().unwrap();
+
+        // Check if already initialized
+        if let Some(Some(provider)) = instances.get(index) {
+            return Ok(provider.clone());
+        }
+
+        // Initialize provider
+        let provider_name = self
+            .providers
+            .get(index)
+            .ok_or_else(|| anyhow::anyhow!("Provider index out of bounds"))?;
+
+        let provider = self.init_provider(provider_name)?;
+
+        // Cache the provider
+        if instances.len() <= index {
+            instances.resize(index + 1, None);
+        }
+        instances[index] = Some(provider.clone());
+
+        Ok(provider)
+    }
+
+    /// Parse model string to extract provider and model
+    ///
+    /// Supports formats:
+    /// - "provider/model" (e.g., "openrouter/gpt-4o")
+    /// - "model" (uses default provider)
+    ///
+    /// # Arguments
+    /// * `model_str` - Model string to parse
+    ///
+    /// # Returns
+    /// * `(String, String)` - (provider_name, model_name)
+    pub fn parse_model(&self, model_str: &str) -> (String, String) {
+        if let Some((provider, model)) = model_str.split_once('/') {
+            (provider.to_string(), model.to_string())
+        } else {
+            // Use default provider
+            (self.config.provider.default.clone(), model_str.to_string())
+        }
+    }
+
+    /// Get the list of provider names in fallback order
+    ///
+    /// # Returns
+    /// * `&[String]` - Provider names
+    pub fn providers(&self) -> &[String] {
+        &self.providers
+    }
+}
+
+impl std::fmt::Debug for ProviderChain {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("ProviderChain")
+            .field("providers", &self.providers)
+            .field(
+                "provider_instances",
+                &format!("<{} cached>", self.provider_instances.lock().unwrap().len()),
+            )
+            .field("config", &self.config)
+            .finish()
+    }
+}
+
+#[async_trait::async_trait]
+impl Provider for ProviderChain {
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse> {
+        // Try each provider in sequence
+        let mut last_error = None;
+
+        for (index, provider_name) in self.providers.iter().enumerate() {
+            // Get or initialize provider
+            let provider = match self.get_provider(index) {
+                Ok(p) => p,
+                Err(e) => {
+                    last_error = Some(e);
+                    continue;
+                }
+            };
+
+            // Check if provider is available
+            if !provider.is_available() {
+                last_error = Some(anyhow::anyhow!(
+                    "Provider {} is not available",
+                    provider_name
+                ));
+                continue;
+            }
+
+            // Try to complete request
+            match provider.complete(request.clone()).await {
+                Ok(response) => return Ok(response),
+                Err(e) => {
+                    last_error = Some(anyhow::anyhow!("Provider {} failed: {}", provider_name, e));
+                    // Continue to next provider
+                    continue;
+                }
+            }
+        }
+
+        // All providers failed
+        Err(last_error.unwrap_or_else(|| anyhow::anyhow!("All providers in chain failed")))
+    }
+
+    fn name(&self) -> &str {
+        "provider-chain"
+    }
+
+    fn is_available(&self) -> bool {
+        // Chain is available if at least one provider is available
+        self.providers.iter().any(|name| {
+            // Quick check without full initialization
+            match name.as_str() {
+                "openrouter" => OpenRouterProvider::api_key_from_env().is_some(),
+                _ => false,
+            }
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::file::{
+        ContextConfig, FileConfig, ProviderConfig, ProviderSpecificConfig, SafetyConfig, UiConfig,
+    };
+    use std::collections::HashMap;
+
+    fn create_test_config() -> FileConfig {
+        let mut providers = HashMap::new();
+        providers.insert(
+            "openrouter".to_string(),
+            ProviderSpecificConfig {
+                api_key: None,
+                api_key_env: Some("OPENROUTER_API_KEY".to_string()),
+                model: Some("openai/gpt-4o".to_string()),
+                endpoint: None,
+            },
+        );
+
+        FileConfig {
+            provider: ProviderConfig {
+                default: "openrouter".to_string(),
+                fallback: vec!["openrouter".to_string()],
+            },
+            context: ContextConfig::default(),
+            safety: SafetyConfig::default(),
+            ui: UiConfig::default(),
+            providers,
+        }
+    }
+
+    #[test]
+    fn test_provider_chain_creation() {
+        let config = create_test_config();
+        let chain = ProviderChain::new(config);
+
+        assert_eq!(chain.providers().len(), 1);
+        assert_eq!(chain.providers()[0], "openrouter");
+    }
+
+    // Note: ProviderChain doesn't implement Clone because it uses Arc<Mutex<...>>
+    // This is intentional for thread-safe lazy initialization
+
+    #[test]
+    fn test_parse_model_with_provider() {
+        let config = create_test_config();
+        let chain = ProviderChain::new(config);
+
+        let (provider, model) = chain.parse_model("openrouter/gpt-4o");
+        assert_eq!(provider, "openrouter");
+        assert_eq!(model, "gpt-4o");
+    }
+
+    #[test]
+    fn test_parse_model_without_provider() {
+        let config = create_test_config();
+        let chain = ProviderChain::new(config);
+
+        let (provider, model) = chain.parse_model("gpt-4o");
+        assert_eq!(provider, "openrouter"); // Uses default
+        assert_eq!(model, "gpt-4o");
+    }
+
+    #[test]
+    fn test_provider_chain_fallback_order() {
+        let mut config = create_test_config();
+        config.provider.fallback = vec!["openrouter".to_string(), "ollama".to_string()];
+        config.provider.default = "openrouter".to_string();
+
+        let chain = ProviderChain::new(config);
+        let providers = chain.providers();
+
+        // Should have default first, then fallbacks
+        assert_eq!(providers.len(), 2);
+        assert_eq!(providers[0], "openrouter");
+        assert_eq!(providers[1], "ollama");
+    }
+}
diff --git a/src/ai/handler.rs b/src/ai/handler.rs
new file mode 100644
index 0000000..4ed692e
--- /dev/null
+++ b/src/ai/handler.rs
@@ -0,0 +1,234 @@
+use crate::ai::chain::ProviderChain;
+use crate::ai::prompt::{
+    build_chat_request, build_multi_chat_request, build_prompt, extract_command, extract_commands,
+};
+use crate::ai::provider::Provider;
+use crate::config::{get_file_config, Config};
+use crate::context::gatherer::gather_context;
+use anyhow::{Context, Result};
+
+/// Build context and prompt from configuration
+///
+/// Shared helper that gathers context and builds the prompt string.
+/// Pure function after I/O operations.
+///
+/// # Arguments
+/// * `config` - Runtime configuration
+///
+/// # Returns
+/// * `Result<String>` - Built prompt string or error
+fn build_context_prompt(config: &Config) -> Result<String> {
+    // Gather context
+    let context_json = gather_context(config).context("Failed to gather context")?;
+
+    // Parse context JSON to extract components
+    let context: serde_json::Value =
+        serde_json::from_str(&context_json).context("Failed to parse context JSON")?;
+
+    // Extract components from context
+    let system_context = context
+        .get("system")
+        .map(|s| serde_json::to_string(s).unwrap_or_default())
+        .unwrap_or_default();
+
+    let dir_context = format!(
+        "Current directory: {}\nFiles: {}",
+        context.get("cwd").and_then(|c| c.as_str()).unwrap_or(""),
+        context
+            .get("files")
+            .and_then(|f| f.as_array())
+            .map(|arr| arr.len().to_string())
+            .unwrap_or_else(|| "0".to_string())
+    );
+
+    let history: Vec<String> = context
+        .get("history")
+        .and_then(|h| h.as_array())
+        .map(|arr| {
+            arr.iter()
+                .filter_map(|v| v.as_str().map(|s| s.to_string()))
+                .collect()
+        })
+        .unwrap_or_default();
+
+    let stdin_context = context
+        .get("stdin")
+        .and_then(|s| s.as_str())
+        .filter(|s| !s.is_empty())
+        .map(|s| format!("Stdin input: {}", s));
+
+    // Build prompt
+    let mut prompt = build_prompt(&system_context, &dir_context, &history, &config.instruction);
+
+    // Add stdin context if present
+    if let Some(stdin) = stdin_context {
+        prompt.push_str(&format!("\n\n{}", stdin));
+    }
+
+    Ok(prompt)
+}
+
+/// Create provider chain from configuration
+///
+/// Helper that creates the AI provider chain with proper model parsing.
+///
+/// # Arguments
+/// * `config` - Runtime configuration
+///
+/// # Returns
+/// * `(ProviderChain, Option<String>)` - Provider chain and parsed model
+fn create_provider_chain(config: &Config) -> (ProviderChain, Option<String>) {
+    // Get file config for provider chain
+    let cli = crate::cli::Cli {
+        instruction: config.instruction.clone(),
+        model: config.model.clone(),
+        provider: config.provider.clone(),
+        quiet: config.quiet,
+        verbose: config.verbose,
+        no_color: config.no_color,
+        color: config.color,
+        interactive: config.interactive,
+        force: config.force,
+        dry_run: config.dry_run,
+        context: config.context.clone(),
+        offline: config.offline,
+        num_options: config.num_options,
+        debug: config.debug,
+        debug_file: config
+            .debug_log_file
+            .as_ref()
+            .map(|p| p.to_string_lossy().to_string()),
+    };
+
+    let file_config = get_file_config(&cli).unwrap_or_default();
+
+    // Create provider chain
+    let chain = ProviderChain::new(file_config);
+
+    // Parse model if provided
+    let model = config.model.as_ref().map(|m| {
+        let (provider, model_name) = chain.parse_model(m);
+        if provider == chain.providers()[0] {
+            // Model is for the primary provider
+            model_name
+        } else {
+            // Keep full "provider/model" format
+            m.clone()
+        }
+    });
+
+    (chain, model)
+}
+
+/// Handle AI command generation (single command)
+///
+/// Orchestrates the full flow:
+/// 1. Gather context (system, directory, history, stdin)
+/// 2. Build prompt from context and instruction
+/// 3. Create chat request
+/// 4. Call provider chain
+/// 5. Extract command from response
+///
+/// Pure function after I/O operations - returns immutable String
+///
+/// # Arguments
+/// * `config` - Runtime configuration
+///
+/// # Returns
+/// * `Result<String>` - Generated command or error
+pub async fn generate_command(config: &Config) -> Result<String> {
+    let prompt = build_context_prompt(config)?;
+    let (chain, model) = create_provider_chain(config);
+
+    // Build chat request for single command
+    let request = build_chat_request(prompt, model);
+
+    // Debug output: show the request that will be sent to AI
+    if config.debug {
+        eprintln!("\n=== DEBUG: Request to be sent to AI ===");
+        eprintln!("Model: {:?}", request.model);
+        eprintln!("Temperature: {:?}", request.temperature);
+        eprintln!("Max Tokens: {:?}", request.max_tokens);
+        eprintln!("\nMessages:");
+        for (i, msg) in request.messages.iter().enumerate() {
+            eprintln!("  {}. Role: {:?}", i + 1, msg.role);
+            eprintln!("     Content: {}", msg.content);
+            if i < request.messages.len() - 1 {
+                eprintln!();
+            }
+        }
+        eprintln!("=== END DEBUG ===\n");
+    }
+
+    // Call provider chain
+    let response = chain
+        .complete(request)
+        .await
+        .context("Failed to get response from AI provider")?;
+
+    // Extract command
+    let command = extract_command(&response.content);
+
+    Ok(command)
+}
+
+/// Handle AI command generation (multiple options)
+///
+/// Orchestrates the full flow for generating multiple command alternatives:
+/// 1. Gather context (system, directory, history, stdin)
+/// 2. Build prompt from context and instruction
+/// 3. Create multi-command chat request (requests JSON array response)
+/// 4. Call provider chain
+/// 5. Parse JSON response to extract commands
+///
+/// Falls back to single command extraction if JSON parsing fails.
+///
+/// Pure function after I/O operations - returns immutable Vec<String>
+///
+/// # Arguments
+/// * `config` - Runtime configuration
+///
+/// # Returns
+/// * `Result<Vec<String>>` - Generated commands or error
+pub async fn generate_commands(config: &Config) -> Result<Vec<String>> {
+    let prompt = build_context_prompt(config)?;
+    let (chain, model) = create_provider_chain(config);
+
+    // Build chat request for multiple commands
+    let request = build_multi_chat_request(prompt, config.num_options, model);
+
+    // Debug output: show the request that will be sent to AI
+    if config.debug {
+        eprintln!("\n=== DEBUG: Request to be sent to AI ===");
+        eprintln!("Model: {:?}", request.model);
+        eprintln!("Temperature: {:?}", request.temperature);
+        eprintln!("Max Tokens: {:?}", request.max_tokens);
+        eprintln!("Number of options requested: {}", config.num_options);
+        eprintln!("\nMessages:");
+        for (i, msg) in request.messages.iter().enumerate() {
+            eprintln!("  {}. Role: {:?}", i + 1, msg.role);
+            eprintln!("     Content: {}", msg.content);
+            if i < request.messages.len() - 1 {
+                eprintln!();
+            }
+        }
+        eprintln!("=== END DEBUG ===\n");
+    }
+
+    // Call provider chain
+    let response = chain
+        .complete(request)
+        .await
+        .context("Failed to get response from AI provider")?;
+
+    // Extract commands from JSON response
+    let commands = extract_commands(&response.content)
+        .map_err(|e| anyhow::anyhow!("Failed to parse AI response: {}", e))?;
+
+    // Ensure we have at least one command
+    if commands.is_empty() {
+        return Err(anyhow::anyhow!("AI returned no commands"));
+    }
+
+    Ok(commands)
+}
diff --git a/src/ai/mod.rs b/src/ai/mod.rs
new file mode 100644
index 0000000..7a3283f
--- /dev/null
+++ b/src/ai/mod.rs
@@ -0,0 +1,16 @@
+pub mod chain;
+pub mod handler;
+pub mod prompt;
+pub mod provider;
+pub mod providers;
+pub mod types;
+
+pub use chain::ProviderChain;
+pub use handler::{generate_command, generate_commands};
+pub use prompt::{
+    build_chat_request, build_multi_chat_request, build_prompt, extract_command, extract_commands,
+    CommandsResponse,
+};
+pub use provider::Provider;
+pub use providers::openrouter::OpenRouterProvider;
+pub use types::{ChatMessage, ChatRequest, ChatResponse, Role};
diff --git a/src/ai/prompt.rs b/src/ai/prompt.rs
new file mode 100644
index 0000000..ce39138
--- /dev/null
+++ b/src/ai/prompt.rs
@@ -0,0 +1,478 @@
+use crate::ai::types::{ChatMessage, ChatRequest};
+use once_cell::sync::Lazy;
+use regex::Regex;
+use serde::{Deserialize, Serialize};
+
+/// Response format for multi-command generation
+///
+/// The AI returns a JSON object with a "commands" array
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CommandsResponse {
+    pub commands: Vec<String>,
+}
+
+/// Pre-compiled regex for extracting commands from markdown code fences
+///
+/// Matches:
+/// - ```bash\ncommand\n```
+/// - ```sh\ncommand\n```
+/// - ```shell\ncommand\n```
+/// - ```\ncommand\n```
+///
+/// Uses lazy static initialization for performance
+static COMMAND_EXTRACTION_REGEX: Lazy<Regex> = Lazy::new(|| {
+    // Match code fences with optional language (bash, sh, shell) or no language
+    // The (?s) flag makes . match newlines
+    // Capture group 1 is the command content
+    Regex::new(r"(?s)```(?:bash|sh|shell)?\s*\n(.*?)\n?```")
+        .expect("Failed to compile command extraction regex")
+});
+
+/// Build prompt from system context, directory context, history, and user instruction
+///
+/// Pure function - concatenates context into a structured prompt string.
+/// No side effects.
+///
+/// # Arguments
+/// * `system_context` - System information (JSON string from context gathering)
+/// * `dir_context` - Directory/file context (JSON string)
+/// * `history` - Shell history commands (vector of strings)
+/// * `instruction` - User's natural language instruction
+///
+/// # Returns
+/// * `String` - Complete prompt string
+pub fn build_prompt(
+    system_context: &str,
+    dir_context: &str,
+    history: &[String],
+    instruction: &str,
+) -> String {
+    let mut prompt = String::new();
+
+    // System context
+    prompt.push_str("System Context:\n");
+    prompt.push_str(system_context);
+    prompt.push_str("\n\n");
+
+    // Directory context
+    prompt.push_str("Directory Context:\n");
+    prompt.push_str(dir_context);
+    prompt.push_str("\n\n");
+
+    // Shell history
+    if !history.is_empty() {
+        prompt.push_str("Recent Shell History:\n");
+        for (i, cmd) in history.iter().enumerate() {
+            prompt.push_str(&format!("  {}. {}\n", i + 1, cmd));
+        }
+        prompt.push('\n');
+    }
+
+    // User instruction
+    prompt.push_str("User Instruction: ");
+    prompt.push_str(instruction);
+    prompt.push_str("\n\n");
+
+    // System instruction
+    prompt.push_str("Respond ONLY with the executable command. Do not include markdown code fences, explanations, or any other text. Just the command itself.");
+
+    prompt
+}
+
+/// Extract command from AI response
+///
+/// Strips markdown code fences (```bash, ```sh, ```shell, or just ```)
+/// and trims whitespace. If no code fences are found, returns the full
+/// response trimmed.
+///
+/// Pure function - no side effects
+///
+/// # Arguments
+/// * `response` - AI response text (may contain markdown)
+///
+/// # Returns
+/// * `String` - Extracted command (trimmed, no markdown)
+pub fn extract_command(response: &str) -> String {
+    // Try to extract from code fences
+    if let Some(captures) = COMMAND_EXTRACTION_REGEX.captures(response) {
+        if let Some(command) = captures.get(1) {
+            return command.as_str().trim().to_string();
+        }
+    }
+
+    // Fallback: return full response trimmed
+    response.trim().to_string()
+}
+
+/// Build chat request from prompt (single command)
+///
+/// Creates a ChatRequest with system message and user message.
+///
+/// Pure function - creates immutable request
+///
+/// # Arguments
+/// * `prompt` - Complete prompt string
+/// * `model` - Optional model identifier
+///
+/// # Returns
+/// * `ChatRequest` - Chat completion request
+pub fn build_chat_request(prompt: String, model: Option<String>) -> ChatRequest {
+    let messages = vec![
+        ChatMessage::system(
+            "You are a helpful assistant that converts natural language instructions into executable shell commands. Respond with ONLY the command, no explanations or markdown.".to_string()
+        ),
+        ChatMessage::user(prompt),
+    ];
+
+    let mut request = ChatRequest::new(messages);
+    if let Some(model) = model {
+        request = request.with_model(model);
+    }
+    request
+}
+
+/// Build chat request for multiple command options
+///
+/// Creates a ChatRequest that instructs the AI to return multiple command
+/// alternatives in JSON format.
+///
+/// Pure function - creates immutable request
+///
+/// # Arguments
+/// * `prompt` - Complete prompt string with context
+/// * `num_options` - Number of command options to generate (1-10)
+/// * `model` - Optional model identifier
+///
+/// # Returns
+/// * `ChatRequest` - Chat completion request for multiple commands
+pub fn build_multi_chat_request(
+    prompt: String,
+    num_options: u8,
+    model: Option<String>,
+) -> ChatRequest {
+    let system_prompt = format!(
+        r#"You are a helpful assistant that converts natural language instructions into executable shell commands.
+
+Generate exactly {} different command options that accomplish the user's goal.
+Each command should be a valid, executable shell command.
+Provide alternatives that vary in approach, verbosity, or options used.
+
+IMPORTANT: Respond ONLY with a valid JSON object in this exact format:
+{{"commands": ["command1", "command2", "command3"]}}
+
+Rules:
+- Return exactly {} commands in the "commands" array
+- Each command must be a single string (escape quotes properly)
+- No explanations, comments, or markdown - just the JSON object
+- Commands should be practical alternatives, not duplicates
+- Order from simplest/most common to more advanced/specific"#,
+        num_options, num_options
+    );
+
+    let messages = vec![
+        ChatMessage::system(system_prompt),
+        ChatMessage::user(prompt),
+    ];
+
+    let mut request = ChatRequest::new(messages);
+    if let Some(model) = model {
+        request = request.with_model(model);
+    }
+    request
+}
+
+/// Extract multiple commands from AI response JSON
+///
+/// Parses the AI response which should be a JSON object with a "commands" array.
+/// Handles various edge cases like markdown code fences wrapping JSON.
+///
+/// Pure function - no side effects
+///
+/// # Arguments
+/// * `response` - AI response text (should be JSON)
+///
+/// # Returns
+/// * `Result<Vec<String>, String>` - Extracted commands or error message
+pub fn extract_commands(response: &str) -> Result<Vec<String>, String> {
+    let response = response.trim();
+
+    // Try to extract JSON from markdown code fences if present
+    let json_str = if response.starts_with("```") {
+        // Remove markdown code fences
+        let without_start = response
+            .strip_prefix("```json")
+            .or_else(|| response.strip_prefix("```"))
+            .unwrap_or(response);
+        without_start
+            .strip_suffix("```")
+            .unwrap_or(without_start)
+            .trim()
+    } else {
+        response
+    };
+
+    // Try to parse as CommandsResponse
+    match serde_json::from_str::<CommandsResponse>(json_str) {
+        Ok(parsed) => {
+            if parsed.commands.is_empty() {
+                Err("AI returned empty commands array".to_string())
+            } else {
+                // Filter out empty commands and trim whitespace
+                let commands: Vec<String> = parsed
+                    .commands
+                    .into_iter()
+                    .map(|c| c.trim().to_string())
+                    .filter(|c| !c.is_empty())
+                    .collect();
+
+                if commands.is_empty() {
+                    Err("All commands in AI response were empty".to_string())
+                } else {
+                    Ok(commands)
+                }
+            }
+        }
+        Err(e) => {
+            // Try to extract from array directly (in case AI returns just an array)
+            if let Ok(arr) = serde_json::from_str::<Vec<String>>(json_str) {
+                if arr.is_empty() {
+                    return Err("AI returned empty array".to_string());
+                }
+                return Ok(arr
+                    .into_iter()
+                    .map(|c| c.trim().to_string())
+                    .filter(|c| !c.is_empty())
+                    .collect());
+            }
+
+            // Fallback: try to find JSON object in response
+            if let Some(start) = json_str.find('{') {
+                if let Some(end) = json_str.rfind('}') {
+                    let potential_json = &json_str[start..=end];
+                    if let Ok(parsed) = serde_json::from_str::<CommandsResponse>(potential_json) {
+                        if !parsed.commands.is_empty() {
+                            return Ok(parsed
+                                .commands
+                                .into_iter()
+                                .map(|c| c.trim().to_string())
+                                .filter(|c| !c.is_empty())
+                                .collect());
+                        }
+                    }
+                }
+            }
+
+            // Last fallback: treat entire response as single command
+            let single_cmd = extract_command(response);
+            if !single_cmd.is_empty() {
+                Ok(vec![single_cmd])
+            } else {
+                Err(format!(
+                    "Failed to parse AI response as JSON: {}. Response: {}",
+                    e, response
+                ))
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ai::types::Role;
+
+    #[test]
+    fn test_extract_command_with_bash_fence() {
+        let response = "```bash\nls -la\n```";
+        let command = extract_command(response);
+        assert_eq!(command, "ls -la");
+    }
+
+    #[test]
+    fn test_extract_command_with_sh_fence() {
+        let response = "```sh\ncd /tmp\n```";
+        let command = extract_command(response);
+        assert_eq!(command, "cd /tmp");
+    }
+
+    #[test]
+    fn test_extract_command_with_shell_fence() {
+        let response = "```shell\ngrep -r \"test\" .\n```";
+        let command = extract_command(response);
+        // The regex captures everything between fences, including newlines
+        // So we need to trim to handle the newline after "shell"
+        assert_eq!(command.trim(), "grep -r \"test\" .");
+    }
+
+    #[test]
+    fn test_extract_command_with_no_lang_fence() {
+        let response = "```\nfind . -name '*.rs'\n```";
+        let command = extract_command(response);
+        assert_eq!(command, "find . -name '*.rs'");
+    }
+
+    #[test]
+    fn test_extract_command_multi_line() {
+        let response = "```bash\nfor i in {1..10}; do\n  echo $i\ndone\n```";
+        let command = extract_command(response);
+        assert_eq!(command, "for i in {1..10}; do\n  echo $i\ndone");
+    }
+
+    #[test]
+    fn test_extract_command_no_fence() {
+        let response = "ls -la";
+        let command = extract_command(response);
+        assert_eq!(command, "ls -la");
+    }
+
+    #[test]
+    fn test_extract_command_with_explanation() {
+        let response = "Here's the command:\n```bash\nls -la\n```\nThis will list all files.";
+        let command = extract_command(response);
+        assert_eq!(command, "ls -la");
+    }
+
+    #[test]
+    fn test_extract_command_empty() {
+        let response = "";
+        let command = extract_command(response);
+        assert_eq!(command, "");
+    }
+
+    #[test]
+    fn test_extract_command_whitespace() {
+        let response = "```bash\n  ls -la  \n```";
+        let command = extract_command(response);
+        assert_eq!(command, "ls -la");
+    }
+
+    #[test]
+    fn test_build_prompt() {
+        let system = r#"{"os_name": "Linux"}"#;
+        let dir = r#"{"files": ["file1.txt"]}"#;
+        let history = vec!["ls -la".to_string(), "cd /tmp".to_string()];
+        let instruction = "list python files";
+
+        let prompt = build_prompt(system, dir, &history, instruction);
+
+        assert!(prompt.contains("System Context:"));
+        assert!(prompt.contains("Directory Context:"));
+        assert!(prompt.contains("Recent Shell History:"));
+        assert!(prompt.contains("list python files"));
+        assert!(prompt.contains("Respond ONLY with the executable command"));
+    }
+
+    #[test]
+    fn test_build_prompt_no_history() {
+        let system = r#"{"os_name": "Linux"}"#;
+        let dir = r#"{"files": []}"#;
+        let history = vec![];
+        let instruction = "test";
+
+        let prompt = build_prompt(system, dir, &history, instruction);
+
+        assert!(!prompt.contains("Recent Shell History:"));
+    }
+
+    #[test]
+    fn test_build_chat_request() {
+        let prompt = "test prompt".to_string();
+        let request = build_chat_request(prompt.clone(), Some("gpt-4".to_string()));
+
+        assert_eq!(request.messages.len(), 2);
+        assert_eq!(request.messages[0].role, Role::System);
+        assert_eq!(request.messages[1].role, Role::User);
+        assert_eq!(request.messages[1].content, prompt);
+        assert_eq!(request.model, Some("gpt-4".to_string()));
+    }
+
+    #[test]
+    fn test_build_chat_request_no_model() {
+        let prompt = "test".to_string();
+        let request = build_chat_request(prompt, None);
+
+        // When model is None, it should be None (not set)
+        assert_eq!(request.model, None);
+    }
+
+    #[test]
+    fn test_build_multi_chat_request() {
+        let prompt = "list files".to_string();
+        let request = build_multi_chat_request(prompt.clone(), 3, Some("gpt-4".to_string()));
+
+        assert_eq!(request.messages.len(), 2);
+        assert_eq!(request.messages[0].role, Role::System);
+        assert!(request.messages[0]
+            .content
+            .contains("3 different command options"));
+        assert!(request.messages[0].content.contains("JSON"));
+        assert_eq!(request.messages[1].content, prompt);
+    }
+
+    #[test]
+    fn test_extract_commands_valid_json() {
+        let response = r#"{"commands": ["ls -la", "ls -lah", "ls -l --color"]}"#;
+        let result = extract_commands(response);
+        assert!(result.is_ok());
+        let commands = result.unwrap();
+        assert_eq!(commands.len(), 3);
+        assert_eq!(commands[0], "ls -la");
+        assert_eq!(commands[1], "ls -lah");
+        assert_eq!(commands[2], "ls -l --color");
+    }
+
+    #[test]
+    fn test_extract_commands_with_markdown() {
+        let response = "```json\n{\"commands\": [\"ls -la\", \"ls -lah\"]}\n```";
+        let result = extract_commands(response);
+        assert!(result.is_ok());
+        let commands = result.unwrap();
+        assert_eq!(commands.len(), 2);
+    }
+
+    #[test]
+    fn test_extract_commands_array_only() {
+        let response = r#"["ls -la", "ls -lah"]"#;
+        let result = extract_commands(response);
+        assert!(result.is_ok());
+        let commands = result.unwrap();
+        assert_eq!(commands.len(), 2);
+    }
+
+    #[test]
+    fn test_extract_commands_fallback_single() {
+        // If AI returns plain text, fallback to single command
+        let response = "ls -la";
+        let result = extract_commands(response);
+        assert!(result.is_ok());
+        let commands = result.unwrap();
+        assert_eq!(commands.len(), 1);
+        assert_eq!(commands[0], "ls -la");
+    }
+
+    #[test]
+    fn test_extract_commands_empty_array() {
+        let response = r#"{"commands": []}"#;
+        let result = extract_commands(response);
+        assert!(result.is_err());
+    }
+
+    #[test]
+    fn test_extract_commands_json_in_text() {
+        let response = r#"Here's the response: {"commands": ["ls -la", "dir"]} Hope this helps!"#;
+        let result = extract_commands(response);
+        assert!(result.is_ok());
+        let commands = result.unwrap();
+        assert_eq!(commands.len(), 2);
+    }
+
+    #[test]
+    fn test_extract_commands_trims_whitespace() {
+        let response = r#"{"commands": ["  ls -la  ", "  ls -lah  "]}"#;
+        let result = extract_commands(response);
+        assert!(result.is_ok());
+        let commands = result.unwrap();
+        assert_eq!(commands[0], "ls -la");
+        assert_eq!(commands[1], "ls -lah");
+    }
+}
diff --git a/src/ai/provider.rs b/src/ai/provider.rs
new file mode 100644
index 0000000..e59a313
--- /dev/null
+++ b/src/ai/provider.rs
@@ -0,0 +1,110 @@
+use crate::ai::types::{ChatRequest, ChatResponse};
+use anyhow::Result;
+
+/// Provider trait for AI chat completions
+///
+/// This trait defines the interface for all AI providers.
+/// Implementations must be thread-safe (Send + Sync) to support
+/// concurrent usage.
+///
+/// Uses async-trait to enable async methods in traits.
+#[async_trait::async_trait]
+pub trait Provider: Send + Sync {
+    /// Complete a chat request
+    ///
+    /// Sends a chat completion request to the AI provider and returns
+    /// the generated response.
+    ///
+    /// # Arguments
+    /// * `request` - Chat completion request
+    ///
+    /// # Returns
+    /// * `Result<ChatResponse>` - Generated response or error
+    ///
+    /// # Errors
+    /// Returns an error if:
+    /// - API request fails (network, timeout, etc.)
+    /// - API returns an error response (auth, rate limit, etc.)
+    /// - Response parsing fails
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse>;
+
+    /// Get the provider name
+    ///
+    /// Returns a human-readable name for this provider.
+    ///
+    /// # Returns
+    /// * `&str` - Provider name
+    fn name(&self) -> &str;
+
+    /// Check if the provider is available
+    ///
+    /// Returns true if the provider is configured and available.
+    /// For local providers (e.g., Ollama), this may check if the
+    /// service is running.
+    ///
+    /// # Returns
+    /// * `bool` - True if provider is available
+    fn is_available(&self) -> bool {
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ai::types::ChatMessage;
+
+    /// Mock provider for testing
+    struct MockProvider {
+        name: String,
+        should_fail: bool,
+    }
+
+    #[async_trait::async_trait]
+    impl Provider for MockProvider {
+        async fn complete(&self, _request: ChatRequest) -> Result<ChatResponse> {
+            if self.should_fail {
+                anyhow::bail!("Mock provider failure");
+            }
+            Ok(ChatResponse::new("Mock response".to_string()))
+        }
+
+        fn name(&self) -> &str {
+            &self.name
+        }
+    }
+
+    #[tokio::test]
+    async fn test_provider_trait() {
+        let provider = MockProvider {
+            name: "mock".to_string(),
+            should_fail: false,
+        };
+
+        let request = ChatRequest::new(vec![ChatMessage::user("test".to_string())]);
+        let response = provider.complete(request).await.unwrap();
+
+        assert_eq!(response.content, "Mock response");
+        assert_eq!(provider.name(), "mock");
+        assert!(provider.is_available());
+    }
+
+    #[tokio::test]
+    async fn test_provider_error_handling() {
+        let provider = MockProvider {
+            name: "mock".to_string(),
+            should_fail: true,
+        };
+
+        let request = ChatRequest::new(vec![ChatMessage::user("test".to_string())]);
+        let result = provider.complete(request).await;
+
+        assert!(result.is_err());
+    }
+
+    // Note: Provider trait cannot be used as a trait object (dyn Provider) in stable Rust
+    // because async methods are not object-safe. This is a limitation of async traits.
+    // The trait can still be used with generics (e.g., `impl Provider` or `P: Provider`).
+    // For dynamic dispatch with async, consider using the async-trait crate or
+    // wrapping in a type-erased future.
+}
diff --git a/src/ai/providers/mod.rs b/src/ai/providers/mod.rs
new file mode 100644
index 0000000..f44c9ae
--- /dev/null
+++ b/src/ai/providers/mod.rs
@@ -0,0 +1,3 @@
+pub mod openrouter;
+
+pub use openrouter::OpenRouterProvider;
diff --git a/src/ai/providers/openrouter.rs b/src/ai/providers/openrouter.rs
new file mode 100644
index 0000000..147849d
--- /dev/null
+++ b/src/ai/providers/openrouter.rs
@@ -0,0 +1,386 @@
+use crate::ai::provider::Provider;
+use crate::ai::types::{ChatMessage, ChatRequest, ChatResponse, Role, Usage};
+use crate::logging::FileLogger;
+use anyhow::Result;
+use once_cell::sync::OnceCell;
+use reqwest::Client;
+use serde::{Deserialize, Serialize};
+use std::sync::Arc;
+use std::time::Duration;
+
+/// Global file logger instance (initialized once at startup)
+static FILE_LOGGER: OnceCell<Arc<FileLogger>> = OnceCell::new();
+
+/// Initialize the global file logger
+///
+/// Should be called once at application startup if file logging is enabled.
+pub fn init_file_logger(logger: Arc<FileLogger>) {
+    let _ = FILE_LOGGER.set(logger);
+}
+
+/// Get the global file logger if initialized
+pub fn get_file_logger() -> Option<&'static Arc<FileLogger>> {
+    FILE_LOGGER.get()
+}
+
+/// OpenRouter API endpoint
+const OPENROUTER_API_URL: &str = "https://openrouter.ai/api/v1/chat/completions";
+
+/// Default model for OpenRouter (Qwen3 Coder)
+const DEFAULT_OPENROUTER_MODEL: &str = "qwen/qwen3-coder";
+
+/// OpenRouter provider implementation
+///
+/// Implements the Provider trait for OpenRouter API.
+/// Uses OpenAI-compatible request/response format.
+#[derive(Debug, Clone)]
+pub struct OpenRouterProvider {
+    /// HTTP client for making requests
+    client: Client,
+    /// API key for authentication
+    api_key: String,
+    /// Default model to use if not specified in request
+    default_model: Option<String>,
+}
+
+impl OpenRouterProvider {
+    /// Create a new OpenRouter provider
+    ///
+    /// # Arguments
+    /// * `api_key` - OpenRouter API key
+    /// * `default_model` - Optional default model identifier
+    ///
+    /// # Returns
+    /// * `OpenRouterProvider` - New provider instance
+    pub fn new(api_key: String, default_model: Option<String>) -> Self {
+        let client = Client::builder()
+            .timeout(Duration::from_secs(60))
+            .build()
+            .expect("Failed to create HTTP client");
+
+        Self {
+            client,
+            api_key,
+            default_model,
+        }
+    }
+
+    /// Get API key from environment or config
+    ///
+    /// Checks for OPENROUTER_API_KEY environment variable.
+    ///
+    /// # Returns
+    /// * `Option<String>` - API key if found
+    pub fn api_key_from_env() -> Option<String> {
+        std::env::var("OPENROUTER_API_KEY").ok()
+    }
+
+    /// Convert our ChatMessage to OpenAI format
+    fn to_openai_message(msg: &ChatMessage) -> OpenAIMessage {
+        OpenAIMessage {
+            role: match msg.role {
+                Role::System => "system".to_string(),
+                Role::User => "user".to_string(),
+                Role::Assistant => "assistant".to_string(),
+            },
+            content: msg.content.clone(),
+        }
+    }
+
+    /// Convert OpenAI response to our ChatResponse
+    fn from_openai_response(resp: OpenAIResponse) -> ChatResponse {
+        let content = resp
+            .choices
+            .first()
+            .map(|choice| choice.message.content.clone())
+            .unwrap_or_default();
+
+        let model = resp.model;
+        let usage = resp.usage.map(|u| Usage {
+            prompt_tokens: u.prompt_tokens,
+            completion_tokens: u.completion_tokens,
+            total_tokens: u.total_tokens,
+        });
+
+        let mut response = ChatResponse::new(content).with_model(model);
+        if let Some(usage) = usage {
+            response = response.with_usage(usage);
+        }
+        response
+    }
+
+    /// Make API request with retry logic for rate limits
+    async fn make_request_with_retry(&self, request: OpenAIRequest) -> Result<OpenAIResponse> {
+        let mut retries = 3;
+        let mut delay = Duration::from_secs(1);
+
+        loop {
+            match self.make_request(&request).await {
+                Ok(response) => return Ok(response),
+                Err(e) => {
+                    // Check if it's a rate limit error (429)
+                    if e.to_string().contains("429") && retries > 0 {
+                        retries -= 1;
+                        tokio::time::sleep(delay).await;
+                        delay *= 2; // Exponential backoff
+                        continue;
+                    }
+                    return Err(e);
+                }
+            }
+        }
+    }
+
+    /// Make API request
+    async fn make_request(&self, request: &OpenAIRequest) -> Result<OpenAIResponse> {
+        let response = match self
+            .client
+            .post(OPENROUTER_API_URL)
+            .header("Authorization", format!("Bearer {}", self.api_key))
+            .header("Content-Type", "application/json")
+            .header("HTTP-Referer", "https://github.com/clai") // Optional attribution
+            .header("X-Title", "clai") // Optional app name
+            .json(request)
+            .send()
+            .await
+        {
+            Ok(r) => r,
+            Err(e) => {
+                // Log network error
+                if let Some(logger) = get_file_logger() {
+                    logger.log_error(
+                        "network_error",
+                        &e.to_string(),
+                        Some(serde_json::json!({"url": OPENROUTER_API_URL})),
+                    );
+                }
+                // Network/timeout errors - no status code
+                return Err(anyhow::anyhow!(
+                    "Network error: Failed to send request to OpenRouter: {}",
+                    e
+                )
+                .context("API request failed"));
+            }
+        };
+
+        let status = response.status();
+        if !status.is_success() {
+            let status_code = status.as_u16();
+            let error_text = response.text().await.unwrap_or_default();
+
+            // Log API error
+            if let Some(logger) = get_file_logger() {
+                logger.log_error(
+                    "api_error",
+                    &error_text,
+                    Some(serde_json::json!({
+                        "status_code": status_code,
+                        "model": &request.model
+                    })),
+                );
+            }
+
+            // Distinguish error types for better error messages
+            let error_msg = match status_code {
+                401 | 403 => format!(
+                    "Authentication error ({}): Invalid or missing API key. {}",
+                    status_code, error_text
+                ),
+                429 => format!(
+                    "Rate limit error ({}): Too many requests. {}",
+                    status_code, error_text
+                ),
+                408 | 504 => format!(
+                    "Timeout error ({}): Request timed out. {}",
+                    status_code, error_text
+                ),
+                _ => format!("API error ({}): {}", status_code, error_text),
+            };
+
+            anyhow::bail!("{}", error_msg);
+        }
+
+        let api_response: OpenAIResponse = match response.json::<OpenAIResponse>().await {
+            Ok(r) => r,
+            Err(e) => {
+                // Log parse error
+                if let Some(logger) = get_file_logger() {
+                    logger.log_error(
+                        "parse_error",
+                        &e.to_string(),
+                        Some(serde_json::json!({"model": &request.model})),
+                    );
+                }
+                return Err(anyhow::anyhow!(
+                    "Failed to parse OpenRouter response: {}",
+                    e
+                ));
+            }
+        };
+
+        Ok(api_response)
+    }
+}
+
+#[async_trait::async_trait]
+impl Provider for OpenRouterProvider {
+    async fn complete(&self, request: ChatRequest) -> Result<ChatResponse> {
+        // Determine model to use
+        // Priority: request.model > provider default > global default
+        let model = request
+            .model
+            .clone()
+            .or_else(|| self.default_model.clone())
+            .unwrap_or_else(|| DEFAULT_OPENROUTER_MODEL.to_string());
+
+        // Log the request before sending (with full message content)
+        if let Some(logger) = get_file_logger() {
+            logger.log_request(
+                Some(&model),
+                &request.messages,
+                request.temperature,
+                request.max_tokens,
+            );
+        }
+
+        // Convert messages to OpenAI format
+        let messages: Vec<OpenAIMessage> = request
+            .messages
+            .iter()
+            .map(Self::to_openai_message)
+            .collect();
+
+        // Build OpenAI-compatible request
+        let openai_request = OpenAIRequest {
+            model,
+            messages,
+            temperature: request.temperature,
+            max_tokens: request.max_tokens,
+        };
+
+        // Make request with retry logic
+        let response = self.make_request_with_retry(openai_request).await?;
+
+        // Log the response
+        if let Some(logger) = get_file_logger() {
+            let content = response
+                .choices
+                .first()
+                .map(|c| c.message.content.as_str())
+                .unwrap_or("");
+            let usage = response.usage.as_ref().map(|u| Usage {
+                prompt_tokens: u.prompt_tokens,
+                completion_tokens: u.completion_tokens,
+                total_tokens: u.total_tokens,
+            });
+            logger.log_response(Some(&response.model), 200, content, usage.as_ref());
+        }
+
+        // Convert to our response format
+        Ok(Self::from_openai_response(response))
+    }
+
+    fn name(&self) -> &str {
+        "openrouter"
+    }
+
+    fn is_available(&self) -> bool {
+        !self.api_key.is_empty()
+    }
+}
+
+/// OpenAI-compatible message format
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct OpenAIMessage {
+    role: String,
+    content: String,
+}
+
+/// OpenAI-compatible request format
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct OpenAIRequest {
+    model: String,
+    messages: Vec<OpenAIMessage>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    temperature: Option<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    max_tokens: Option<u32>,
+}
+
+/// OpenAI-compatible response format
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct OpenAIResponse {
+    id: Option<String>,
+    model: String,
+    choices: Vec<Choice>,
+    usage: Option<OpenAIUsage>,
+}
+
+/// Choice in OpenAI response
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct Choice {
+    index: u32,
+    message: OpenAIMessage,
+    finish_reason: Option<String>,
+}
+
+/// Usage in OpenAI response
+#[derive(Debug, Clone, Serialize, Deserialize)]
+struct OpenAIUsage {
+    prompt_tokens: u32,
+    completion_tokens: u32,
+    total_tokens: u32,
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::ai::types::ChatMessage;
+
+    #[test]
+    fn test_openrouter_provider_creation() {
+        let provider = OpenRouterProvider::new("test-key".to_string(), None);
+        assert_eq!(provider.name(), "openrouter");
+        assert!(provider.is_available());
+    }
+
+    #[test]
+    fn test_openrouter_provider_no_api_key() {
+        let provider = OpenRouterProvider::new("".to_string(), None);
+        assert!(!provider.is_available());
+    }
+
+    #[test]
+    fn test_to_openai_message() {
+        let msg = ChatMessage::system("test".to_string());
+        let openai_msg = OpenRouterProvider::to_openai_message(&msg);
+        assert_eq!(openai_msg.role, "system");
+        assert_eq!(openai_msg.content, "test");
+    }
+
+    #[test]
+    fn test_from_openai_response() {
+        let openai_resp = OpenAIResponse {
+            id: Some("test-id".to_string()),
+            model: "gpt-4".to_string(),
+            choices: vec![Choice {
+                index: 0,
+                message: OpenAIMessage {
+                    role: "assistant".to_string(),
+                    content: "Hello, world!".to_string(),
+                },
+                finish_reason: Some("stop".to_string()),
+            }],
+            usage: Some(OpenAIUsage {
+                prompt_tokens: 10,
+                completion_tokens: 5,
+                total_tokens: 15,
+            }),
+        };
+
+        let resp = OpenRouterProvider::from_openai_response(openai_resp);
+        assert_eq!(resp.content, "Hello, world!");
+        assert_eq!(resp.model, Some("gpt-4".to_string()));
+        assert!(resp.usage.is_some());
+    }
+}
diff --git a/src/ai/types.rs b/src/ai/types.rs
new file mode 100644
index 0000000..410c205
--- /dev/null
+++ b/src/ai/types.rs
@@ -0,0 +1,327 @@
+use serde::{Deserialize, Serialize};
+
+/// Chat message role
+///
+/// Represents the role of a message in a chat conversation.
+/// Used for building chat completion requests.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum Role {
+    /// System message - provides context and instructions
+    System,
+    /// User message - user input/instruction
+    User,
+    /// Assistant message - AI response
+    Assistant,
+}
+
+/// Chat message
+///
+/// Immutable message structure for chat completions.
+/// Contains role and content.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ChatMessage {
+    /// Role of the message (system, user, or assistant)
+    pub role: Role,
+    /// Content of the message
+    pub content: String,
+}
+
+impl ChatMessage {
+    /// Create a new chat message
+    ///
+    /// Pure function - creates immutable message
+    ///
+    /// # Arguments
+    /// * `role` - Message role
+    /// * `content` - Message content
+    ///
+    /// # Returns
+    /// * `ChatMessage` - New message instance
+    pub fn new(role: Role, content: String) -> Self {
+        Self { role, content }
+    }
+
+    /// Create a system message
+    ///
+    /// Convenience function for creating system messages
+    ///
+    /// # Arguments
+    /// * `content` - System message content
+    ///
+    /// # Returns
+    /// * `ChatMessage` - System message
+    pub fn system(content: String) -> Self {
+        Self::new(Role::System, content)
+    }
+
+    /// Create a user message
+    ///
+    /// Convenience function for creating user messages
+    ///
+    /// # Arguments
+    /// * `content` - User message content
+    ///
+    /// # Returns
+    /// * `ChatMessage` - User message
+    pub fn user(content: String) -> Self {
+        Self::new(Role::User, content)
+    }
+
+    /// Create an assistant message
+    ///
+    /// Convenience function for creating assistant messages
+    ///
+    /// # Arguments
+    /// * `content` - Assistant message content
+    ///
+    /// # Returns
+    /// * `ChatMessage` - Assistant message
+    pub fn assistant(content: String) -> Self {
+        Self::new(Role::Assistant, content)
+    }
+}
+
+/// Chat completion request
+///
+/// Immutable request structure for AI chat completions.
+/// Contains messages and optional model/provider selection.
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct ChatRequest {
+    /// List of messages in the conversation
+    pub messages: Vec<ChatMessage>,
+    /// Optional model identifier (e.g., "gpt-4", "claude-3-opus")
+    /// If None, provider uses default model
+    pub model: Option<String>,
+    /// Optional temperature for response randomness (0.0 to 2.0)
+    /// If None, provider uses default temperature
+    pub temperature: Option<f64>,
+    /// Optional maximum tokens in response
+    /// If None, provider uses default max_tokens
+    pub max_tokens: Option<u32>,
+}
+
+impl ChatRequest {
+    /// Create a new chat request
+    ///
+    /// Pure function - creates immutable request
+    ///
+    /// # Arguments
+    /// * `messages` - List of chat messages
+    ///
+    /// # Returns
+    /// * `ChatRequest` - New request instance
+    pub fn new(messages: Vec<ChatMessage>) -> Self {
+        Self {
+            messages,
+            model: None,
+            temperature: None,
+            max_tokens: None,
+        }
+    }
+
+    /// Set the model for this request
+    ///
+    /// Returns a new request with the model set.
+    ///
+    /// # Arguments
+    /// * `model` - Model identifier
+    ///
+    /// # Returns
+    /// * `ChatRequest` - New request with model set
+    pub fn with_model(mut self, model: String) -> Self {
+        self.model = Some(model);
+        self
+    }
+
+    /// Set the temperature for this request
+    ///
+    /// Returns a new request with the temperature set.
+    ///
+    /// # Arguments
+    /// * `temperature` - Temperature value (0.0 to 2.0)
+    ///
+    /// # Returns
+    /// * `ChatRequest` - New request with temperature set
+    pub fn with_temperature(mut self, temperature: f64) -> Self {
+        self.temperature = Some(temperature);
+        self
+    }
+
+    /// Set the max tokens for this request
+    ///
+    /// Returns a new request with max_tokens set.
+    ///
+    /// # Arguments
+    /// * `max_tokens` - Maximum tokens in response
+    ///
+    /// # Returns
+    /// * `ChatRequest` - New request with max_tokens set
+    pub fn with_max_tokens(mut self, max_tokens: u32) -> Self {
+        self.max_tokens = Some(max_tokens);
+        self
+    }
+}
+
+/// Chat completion response
+///
+/// Immutable response structure from AI providers.
+/// Contains the generated message content.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct ChatResponse {
+    /// Generated message content
+    pub content: String,
+    /// Optional model used for generation
+    pub model: Option<String>,
+    /// Optional usage statistics (tokens used)
+    pub usage: Option<Usage>,
+}
+
+/// Token usage statistics
+///
+/// Represents token usage for a completion request.
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+pub struct Usage {
+    /// Number of prompt tokens
+    pub prompt_tokens: u32,
+    /// Number of completion tokens
+    pub completion_tokens: u32,
+    /// Total tokens used
+    pub total_tokens: u32,
+}
+
+impl ChatResponse {
+    /// Create a new chat response
+    ///
+    /// Pure function - creates immutable response
+    ///
+    /// # Arguments
+    /// * `content` - Generated message content
+    ///
+    /// # Returns
+    /// * `ChatResponse` - New response instance
+    pub fn new(content: String) -> Self {
+        Self {
+            content,
+            model: None,
+            usage: None,
+        }
+    }
+
+    /// Set the model for this response
+    ///
+    /// Returns a new response with the model set.
+    ///
+    /// # Arguments
+    /// * `model` - Model identifier
+    ///
+    /// # Returns
+    /// * `ChatResponse` - New response with model set
+    pub fn with_model(mut self, model: String) -> Self {
+        self.model = Some(model);
+        self
+    }
+
+    /// Set the usage statistics for this response
+    ///
+    /// Returns a new response with usage set.
+    ///
+    /// # Arguments
+    /// * `usage` - Usage statistics
+    ///
+    /// # Returns
+    /// * `ChatResponse` - New response with usage set
+    pub fn with_usage(mut self, usage: Usage) -> Self {
+        self.usage = Some(usage);
+        self
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_chat_message_creation() {
+        let msg = ChatMessage::system("You are a helpful assistant.".to_string());
+        assert_eq!(msg.role, Role::System);
+        assert_eq!(msg.content, "You are a helpful assistant.");
+
+        let msg = ChatMessage::user("Hello".to_string());
+        assert_eq!(msg.role, Role::User);
+        assert_eq!(msg.content, "Hello");
+    }
+
+    #[test]
+    fn test_chat_request_immutability() {
+        let messages = vec![
+            ChatMessage::system("System".to_string()),
+            ChatMessage::user("User".to_string()),
+        ];
+        let req1 = ChatRequest::new(messages.clone());
+        let req2 = ChatRequest::new(messages);
+
+        // Should be equal (immutable)
+        assert_eq!(req1.messages.len(), req2.messages.len());
+    }
+
+    #[test]
+    fn test_chat_request_builder() {
+        let messages = vec![ChatMessage::user("test".to_string())];
+        let req = ChatRequest::new(messages)
+            .with_model("gpt-4".to_string())
+            .with_temperature(0.7)
+            .with_max_tokens(100);
+
+        assert_eq!(req.model, Some("gpt-4".to_string()));
+        assert_eq!(req.temperature, Some(0.7));
+        assert_eq!(req.max_tokens, Some(100));
+    }
+
+    #[test]
+    fn test_chat_response_creation() {
+        let resp = ChatResponse::new("Hello, world!".to_string());
+        assert_eq!(resp.content, "Hello, world!");
+        assert_eq!(resp.model, None);
+        assert_eq!(resp.usage, None);
+    }
+
+    #[test]
+    fn test_chat_response_builder() {
+        let usage = Usage {
+            prompt_tokens: 10,
+            completion_tokens: 5,
+            total_tokens: 15,
+        };
+        let resp = ChatResponse::new("test".to_string())
+            .with_model("gpt-4".to_string())
+            .with_usage(usage.clone());
+
+        assert_eq!(resp.model, Some("gpt-4".to_string()));
+        assert_eq!(resp.usage, Some(usage));
+    }
+
+    #[test]
+    fn test_role_serialization() {
+        let role = Role::System;
+        let serialized = serde_json::to_string(&role).unwrap();
+        assert_eq!(serialized, "\"system\"");
+
+        let role = Role::User;
+        let serialized = serde_json::to_string(&role).unwrap();
+        assert_eq!(serialized, "\"user\"");
+
+        let role = Role::Assistant;
+        let serialized = serde_json::to_string(&role).unwrap();
+        assert_eq!(serialized, "\"assistant\"");
+    }
+
+    #[test]
+    fn test_chat_message_serialization() {
+        let msg = ChatMessage::system("test".to_string());
+        let serialized = serde_json::to_string(&msg).unwrap();
+        let deserialized: ChatMessage = serde_json::from_str(&serialized).unwrap();
+
+        assert_eq!(msg, deserialized);
+    }
+}
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
new file mode 100644
index 0000000..64f3385
--- /dev/null
+++ b/src/cli/mod.rs
@@ -0,0 +1,87 @@
+use clap::{Parser, ValueEnum};
+
+/// Color mode for output
+#[derive(Debug, Clone, Copy, PartialEq, Eq, ValueEnum)]
+pub enum ColorChoice {
+    /// Auto-detect based on environment
+    Auto,
+    /// Always enable colors
+    Always,
+    /// Never use colors
+    Never,
+}
+
+/// AI-Powered Shell Command Translator
+/// Converts natural language to executable commands
+#[derive(Parser, Debug, Clone)]
+#[command(name = "clai")]
+#[command(version)]
+#[command(about = "AI-powered shell command translator", long_about = None)]
+pub struct Cli {
+    /// Natural language instruction to convert to a command
+    #[arg(required = true)]
+    pub instruction: String,
+
+    /// Override the AI model to use
+    #[arg(short = 'm', long = "model")]
+    pub model: Option<String>,
+
+    /// Override the AI provider to use
+    #[arg(short = 'p', long = "provider")]
+    pub provider: Option<String>,
+
+    /// Suppress non-essential output
+    #[arg(short = 'q', long = "quiet")]
+    pub quiet: bool,
+
+    /// Increase verbosity (can be used multiple times)
+    #[arg(short = 'v', long = "verbose", action = clap::ArgAction::Count)]
+    pub verbose: u8,
+
+    /// Disable colored output (deprecated: use --color=never)
+    #[arg(long = "no-color")]
+    pub no_color: bool,
+
+    /// Control colored output: auto (default), always, or never
+    #[arg(long = "color", default_value = "auto")]
+    pub color: ColorChoice,
+
+    /// Interactive mode: prompt for execute/copy/abort on dangerous commands
+    #[arg(short = 'i', long = "interactive")]
+    pub interactive: bool,
+
+    /// Skip dangerous command confirmation
+    #[arg(short = 'f', long = "force")]
+    pub force: bool,
+
+    /// Show command without execution prompt
+    #[arg(short = 'n', long = "dry-run")]
+    pub dry_run: bool,
+
+    /// Additional context file
+    #[arg(short = 'c', long = "context")]
+    pub context: Option<String>,
+
+    /// Offline mode (fail gracefully if no local model available)
+    #[arg(long = "offline")]
+    pub offline: bool,
+
+    /// Number of command options to generate (default: 3)
+    #[arg(short = 'o', long = "options", default_value = "3")]
+    pub num_options: u8,
+
+    /// Show the prompt that will be sent to the AI (for debugging)
+    #[arg(short = 'd', long = "debug")]
+    pub debug: bool,
+
+    /// Enable debug logging to file (default: ~/.cache/clai/debug.log)
+    #[arg(long = "debug-file", value_name = "PATH", num_args = 0..=1, default_missing_value = "", require_equals = true)]
+    pub debug_file: Option<String>,
+}
+
+/// Pure function to parse CLI arguments into Cli struct
+/// Returns Result with clap::Error on parse failure
+/// No side effects - pure function
+pub fn parse_args() -> Result<Cli, clap::Error> {
+    Cli::try_parse()
+}
diff --git a/src/color/mod.rs b/src/color/mod.rs
new file mode 100644
index 0000000..ef3d1c9
--- /dev/null
+++ b/src/color/mod.rs
@@ -0,0 +1,173 @@
+use crate::config::Config;
+
+/// Color mode enumeration
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ColorMode {
+    /// Auto-detect based on environment and TTY
+    Auto,
+    /// Always enable colors
+    Always,
+    /// Never use colors
+    Never,
+}
+
+impl ColorMode {
+    /// Determine if colors should be enabled based on mode and environment
+    /// Pure function - no side effects
+    pub fn should_use_color(self) -> bool {
+        match self {
+            ColorMode::Always => true,
+            ColorMode::Never => false,
+            ColorMode::Auto => detect_color_auto(),
+        }
+    }
+}
+
+/// Pure function to detect if colors should be enabled automatically
+/// Checks CLICOLOR, NO_COLOR, TERM=dumb, and TTY status
+/// No side effects - pure function
+///
+/// Priority order:
+/// 1. CLICOLOR=0 disables, CLICOLOR=1 enables (GNU standard)
+/// 2. NO_COLOR disables (no-color.org standard)
+/// 3. TERM=dumb disables (POSIX standard)
+/// 4. TTY status (if stderr is a TTY, enable colors)
+pub fn detect_color_auto() -> bool {
+    // Check CLICOLOR environment variable (GNU standard)
+    // CLICOLOR=0 means disable, CLICOLOR=1 means enable, unset means auto
+    if let Ok(clicolor) = std::env::var("CLICOLOR") {
+        match clicolor.as_str() {
+            "0" => return false,
+            "1" => return true,
+            _ => {
+                // Invalid value, fall through to other checks
+            }
+        }
+    }
+
+    // Check NO_COLOR environment variable (no-color.org standard)
+    if std::env::var("NO_COLOR").is_ok() {
+        return false;
+    }
+
+    // Check TERM=dumb (POSIX standard)
+    if let Ok(term) = std::env::var("TERM") {
+        if term == "dumb" {
+            return false;
+        }
+    }
+
+    // Check if stderr is a TTY (for color output)
+    // Use atty crate for reliable TTY detection
+    atty::is(atty::Stream::Stderr)
+}
+
+/// Pure function to determine ColorMode from Config
+/// Takes immutable Config and returns ColorMode
+/// No side effects - pure function
+pub fn color_mode_from_config(config: &Config) -> ColorMode {
+    // --no-color flag takes precedence
+    if config.no_color {
+        return ColorMode::Never;
+    }
+
+    // Map ColorChoice to ColorMode
+    match config.color {
+        crate::cli::ColorChoice::Always => ColorMode::Always,
+        crate::cli::ColorChoice::Never => ColorMode::Never,
+        crate::cli::ColorChoice::Auto => ColorMode::Auto,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_color_mode_always() {
+        assert_eq!(ColorMode::Always.should_use_color(), true);
+    }
+
+    #[test]
+    fn test_color_mode_never() {
+        assert_eq!(ColorMode::Never.should_use_color(), false);
+    }
+
+    #[test]
+    fn test_color_mode_from_config() {
+        let config_no_color = crate::config::Config {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: true,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_log_file: None,
+        };
+
+        let config_with_color = crate::config::Config {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_log_file: None,
+        };
+
+        let config_always = crate::config::Config {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Always,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_log_file: None,
+        };
+
+        assert_eq!(color_mode_from_config(&config_no_color), ColorMode::Never);
+        assert_eq!(color_mode_from_config(&config_with_color), ColorMode::Auto);
+        assert_eq!(color_mode_from_config(&config_always), ColorMode::Always);
+    }
+
+    #[test]
+    fn test_detect_color_auto_clicolor() {
+        // Test CLICOLOR=0 disables
+        std::env::set_var("CLICOLOR", "0");
+        assert_eq!(detect_color_auto(), false);
+        std::env::remove_var("CLICOLOR");
+
+        // Test CLICOLOR=1 enables
+        std::env::set_var("CLICOLOR", "1");
+        // Note: This test may fail if NO_COLOR is set or TERM=dumb
+        // So we just verify it doesn't return false due to CLICOLOR
+        let _result = detect_color_auto();
+        // If other conditions disable color, that's fine
+        // But CLICOLOR=1 should not cause it to be false
+        std::env::remove_var("CLICOLOR");
+    }
+}
diff --git a/src/config/cache.rs b/src/config/cache.rs
new file mode 100644
index 0000000..9cebb80
--- /dev/null
+++ b/src/config/cache.rs
@@ -0,0 +1,127 @@
+use crate::cli::Cli;
+use crate::config::file::FileConfig;
+use crate::config::loader::ConfigLoadError;
+use crate::config::merger::merge_all_configs;
+use once_cell::sync::Lazy;
+use std::sync::Mutex;
+
+/// Global lazy-loaded configuration cache
+///
+/// This is initialized on first access via `get_file_config()`
+/// Thread-safe: uses Mutex for interior mutability during initialization
+static FILE_CONFIG_CACHE: Lazy<Mutex<Option<Result<FileConfig, ConfigLoadError>>>> =
+    Lazy::new(|| Mutex::new(None));
+
+/// Get the merged file configuration (lazy-loaded)
+///
+/// This function triggers config loading on first access:
+/// 1. Checks if config is already loaded
+/// 2. If not, loads and merges configs from files, env vars, and CLI
+/// 3. Caches the result for subsequent calls
+///
+/// Thread-safe: uses Mutex to ensure only one initialization
+///
+/// # Arguments
+/// * `cli` - CLI arguments to merge into config (highest priority)
+///
+/// # Returns
+/// * `Result<FileConfig, ConfigLoadError>` - Merged configuration or error
+pub fn get_file_config(cli: &Cli) -> Result<FileConfig, ConfigLoadError> {
+    let mut cache = FILE_CONFIG_CACHE.lock().unwrap();
+
+    // Check if already loaded
+    if let Some(ref cached_result) = *cache {
+        // Return cloned result (both FileConfig and ConfigLoadError are Clone)
+        return cached_result.clone();
+    }
+
+    // Load and merge configs
+    let result = merge_all_configs(cli);
+
+    // Cache the result
+    *cache = Some(result.clone());
+
+    result
+}
+
+/// Reset the config cache (useful for testing and benchmarking)
+///
+/// This clears the cached config, forcing a reload on next access
+#[cfg(any(test, feature = "bench"))]
+pub fn reset_config_cache() {
+    let mut cache = FILE_CONFIG_CACHE.lock().unwrap();
+    *cache = None;
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::Cli;
+
+    #[test]
+    fn test_lazy_config_loading() {
+        reset_config_cache();
+
+        let cli = Cli {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        // First call should load config
+        let config1 = get_file_config(&cli);
+        assert!(config1.is_ok());
+
+        // Second call should use cached config
+        let config2 = get_file_config(&cli);
+        assert!(config2.is_ok());
+
+        // Both should be equal (same config)
+        assert_eq!(config1.unwrap(), config2.unwrap());
+    }
+
+    #[test]
+    fn test_config_cache_reset() {
+        reset_config_cache();
+
+        let cli = Cli {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        // Load config
+        let _config1 = get_file_config(&cli);
+
+        // Reset cache
+        reset_config_cache();
+
+        // Load again (should reload)
+        let _config2 = get_file_config(&cli);
+        assert!(_config2.is_ok());
+    }
+}
diff --git a/src/config/file.rs b/src/config/file.rs
new file mode 100644
index 0000000..7c67771
--- /dev/null
+++ b/src/config/file.rs
@@ -0,0 +1,266 @@
+use serde::{Deserialize, Serialize};
+use std::collections::HashMap;
+
+/// Configuration structure for TOML file parsing
+/// Represents the complete config file structure with all sections
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct FileConfig {
+    /// Provider configuration section
+    #[serde(default)]
+    pub provider: ProviderConfig,
+
+    /// Context configuration section
+    #[serde(default)]
+    pub context: ContextConfig,
+
+    /// Safety configuration section
+    #[serde(default)]
+    pub safety: SafetyConfig,
+
+    /// UI configuration section
+    #[serde(default)]
+    pub ui: UiConfig,
+
+    /// Provider-specific configurations (e.g., [openrouter], [ollama])
+    #[serde(flatten)]
+    pub providers: HashMap<String, ProviderSpecificConfig>,
+}
+
+/// Provider configuration section
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct ProviderConfig {
+    /// Default provider to use
+    #[serde(default = "default_provider_default")]
+    pub default: String,
+
+    /// Fallback providers in order
+    #[serde(default)]
+    pub fallback: Vec<String>,
+}
+
+/// Provider-specific configuration (e.g., [openrouter], [ollama])
+#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct ProviderSpecificConfig {
+    /// API key directly stored in config (protected by 0600 file permissions)
+    pub api_key: Option<String>,
+
+    /// API key environment variable name (alternative to api_key)
+    pub api_key_env: Option<String>,
+
+    /// Model to use for this provider
+    pub model: Option<String>,
+
+    /// Endpoint URL (for local providers like Ollama)
+    pub endpoint: Option<String>,
+}
+
+/// Context configuration section
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct ContextConfig {
+    /// Maximum number of files to include in context
+    #[serde(default = "default_max_files")]
+    pub max_files: u32,
+
+    /// Maximum number of history commands to include
+    #[serde(default = "default_max_history")]
+    pub max_history: u32,
+
+    /// Whether to redact file paths before sending to API
+    #[serde(default)]
+    pub redact_paths: bool,
+
+    /// Whether to redact usernames before sending to API
+    #[serde(default)]
+    pub redact_username: bool,
+}
+
+/// Safety configuration section
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct SafetyConfig {
+    /// List of dangerous command patterns to detect
+    #[serde(default = "default_dangerous_patterns")]
+    pub dangerous_patterns: Vec<String>,
+
+    /// Whether to confirm dangerous commands interactively
+    #[serde(default = "default_confirm_dangerous")]
+    pub confirm_dangerous: bool,
+}
+
+/// UI configuration section
+#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "kebab-case")]
+pub struct UiConfig {
+    /// Color mode: "auto", "always", or "never"
+    #[serde(default = "default_color")]
+    pub color: String,
+
+    /// Debug log file path (enables file logging when set)
+    #[serde(default)]
+    pub debug_log_file: Option<String>,
+}
+
+// Default value functions for serde defaults
+
+fn default_provider_default() -> String {
+    "openrouter".to_string()
+}
+
+fn default_max_files() -> u32 {
+    10
+}
+
+fn default_max_history() -> u32 {
+    3
+}
+
+fn default_dangerous_patterns() -> Vec<String> {
+    vec![
+        "rm -rf".to_string(),
+        "sudo rm".to_string(),
+        "mkfs".to_string(),
+        "dd if=".to_string(),
+        "> /dev/".to_string(),
+        "format".to_string(),
+    ]
+}
+
+fn default_confirm_dangerous() -> bool {
+    true
+}
+
+fn default_color() -> String {
+    "auto".to_string()
+}
+
+/// Default configuration instance
+/// Pure constant - immutable default values
+impl Default for FileConfig {
+    fn default() -> Self {
+        Self {
+            provider: ProviderConfig {
+                default: default_provider_default(),
+                fallback: Vec::new(),
+            },
+            context: ContextConfig {
+                max_files: default_max_files(),
+                max_history: default_max_history(),
+                redact_paths: false,
+                redact_username: false,
+            },
+            safety: SafetyConfig {
+                dangerous_patterns: default_dangerous_patterns(),
+                confirm_dangerous: default_confirm_dangerous(),
+            },
+            ui: UiConfig {
+                color: default_color(),
+                debug_log_file: None,
+            },
+            providers: HashMap::new(),
+        }
+    }
+}
+
+// Implement Default for nested structs using our default functions
+impl Default for ProviderConfig {
+    fn default() -> Self {
+        Self {
+            default: default_provider_default(),
+            fallback: Vec::new(),
+        }
+    }
+}
+
+impl Default for ContextConfig {
+    fn default() -> Self {
+        Self {
+            max_files: default_max_files(),
+            max_history: default_max_history(),
+            redact_paths: false,
+            redact_username: false,
+        }
+    }
+}
+
+impl Default for SafetyConfig {
+    fn default() -> Self {
+        Self {
+            dangerous_patterns: default_dangerous_patterns(),
+            confirm_dangerous: default_confirm_dangerous(),
+        }
+    }
+}
+
+impl Default for UiConfig {
+    fn default() -> Self {
+        Self {
+            color: default_color(),
+            debug_log_file: None,
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_default_config() {
+        let config = FileConfig::default();
+
+        assert_eq!(config.provider.default, "openrouter");
+        assert_eq!(config.context.max_files, 10);
+        assert_eq!(config.context.max_history, 3);
+        assert_eq!(config.safety.dangerous_patterns.len(), 6);
+        assert_eq!(config.ui.color, "auto");
+        assert_eq!(config.safety.confirm_dangerous, true);
+    }
+
+    #[test]
+    fn test_config_serialize_deserialize() {
+        let config = FileConfig::default();
+
+        // Serialize to TOML
+        let toml_string = toml::to_string(&config).expect("Failed to serialize config");
+
+        // Deserialize back
+        let deserialized: FileConfig =
+            toml::from_str(&toml_string).expect("Failed to deserialize config");
+
+        // Verify values match
+        assert_eq!(config.provider.default, deserialized.provider.default);
+        assert_eq!(config.context.max_files, deserialized.context.max_files);
+        assert_eq!(config.context.max_history, deserialized.context.max_history);
+        assert_eq!(
+            config.safety.dangerous_patterns,
+            deserialized.safety.dangerous_patterns
+        );
+        assert_eq!(config.ui.color, deserialized.ui.color);
+    }
+
+    #[test]
+    fn test_config_clone() {
+        let config1 = FileConfig::default();
+        let config2 = config1.clone();
+
+        // Verify clone creates identical copy
+        assert_eq!(config1, config2);
+    }
+
+    #[test]
+    fn test_dangerous_patterns_default() {
+        let config = FileConfig::default();
+        let patterns = &config.safety.dangerous_patterns;
+
+        assert!(patterns.contains(&"rm -rf".to_string()));
+        assert!(patterns.contains(&"sudo rm".to_string()));
+        assert!(patterns.contains(&"mkfs".to_string()));
+        assert!(patterns.contains(&"dd if=".to_string()));
+        assert!(patterns.contains(&"> /dev/".to_string()));
+        assert!(patterns.contains(&"format".to_string()));
+    }
+}
diff --git a/src/config/loader.rs b/src/config/loader.rs
new file mode 100644
index 0000000..7fda6b7
--- /dev/null
+++ b/src/config/loader.rs
@@ -0,0 +1,322 @@
+use crate::config::file::FileConfig;
+use std::fs;
+use std::path::Path;
+use thiserror::Error;
+
+/// Errors that can occur during config file loading
+#[derive(Debug, Error, Clone)]
+pub enum ConfigLoadError {
+    #[error("Config file not found: {0}")]
+    NotFound(String),
+
+    #[error("Config file has insecure permissions (must be 0600): {0}")]
+    InsecurePermissions(String),
+
+    #[error("Failed to read config file: {0}")]
+    ReadError(String),
+
+    #[error("Failed to parse TOML config: {0}")]
+    ParseError(String),
+
+    #[error("Failed to check file permissions: {0}")]
+    PermissionCheckError(String),
+}
+
+/// Load and parse a config file with security checks
+///
+/// Security requirements:
+/// - File must exist
+/// - File must have 0600 permissions (read/write for owner only)
+/// - File must be valid TOML
+///
+/// Returns parsed FileConfig or ConfigLoadError
+/// Pure function with I/O side effects isolated to file operations
+pub fn load_config_file(path: &Path) -> Result<FileConfig, ConfigLoadError> {
+    // Check if file exists
+    if !path.exists() {
+        return Err(ConfigLoadError::NotFound(path.display().to_string()));
+    }
+
+    // Check file permissions (must be 0600)
+    check_file_permissions(path)?;
+
+    // Read file contents
+    let contents = fs::read_to_string(path).map_err(|e| {
+        ConfigLoadError::ReadError(format!(
+            "Failed to read config file {}: {}",
+            path.display(),
+            e
+        ))
+    })?;
+
+    // Parse TOML
+    let config: FileConfig = toml::from_str(&contents).map_err(|e| {
+        ConfigLoadError::ParseError(format!(
+            "Failed to parse TOML in config file {}: {}",
+            path.display(),
+            e
+        ))
+    })?;
+
+    Ok(config)
+}
+
+/// Check if a file has secure permissions (0600)
+///
+/// On Unix systems, checks that file permissions are exactly 0600
+/// (read/write for owner, no permissions for group/others)
+///
+/// On non-Unix systems, this is a no-op (returns Ok)
+///
+/// Pure function - checks permissions but doesn't modify state
+#[cfg(unix)]
+pub fn check_file_permissions(path: &Path) -> Result<(), ConfigLoadError> {
+    use std::os::unix::fs::PermissionsExt;
+
+    let metadata = fs::metadata(path).map_err(|e| {
+        ConfigLoadError::PermissionCheckError(format!(
+            "Failed to get metadata for {}: {}",
+            path.display(),
+            e
+        ))
+    })?;
+
+    let permissions = metadata.permissions();
+    let mode = permissions.mode();
+
+    // Check if permissions are exactly 0600 (0o600)
+    // This means: owner read/write (6), group none (0), others none (0)
+    if (mode & 0o777) != 0o600 {
+        return Err(ConfigLoadError::InsecurePermissions(format!(
+            "File {} has permissions {:o}, but must be 0600",
+            path.display(),
+            mode & 0o777
+        )));
+    }
+
+    Ok(())
+}
+
+/// Check file permissions on non-Unix systems
+///
+/// On non-Unix systems (Windows, etc.), we don't enforce strict permissions
+/// as the permission model is different. This is a no-op.
+#[cfg(not(unix))]
+pub fn check_file_permissions(_path: &Path) -> Result<(), ConfigLoadError> {
+    // On non-Unix systems, skip permission check
+    // Windows and other systems have different permission models
+    Ok(())
+}
+
+/// Resolve environment variable references in API keys
+///
+/// Supports format: ${VAR_NAME} or $VAR_NAME
+///
+/// Pure function - reads environment but doesn't modify state
+pub fn resolve_env_var_reference(env_ref: &str) -> Option<String> {
+    // Remove ${} or $ wrapper
+    let var_name = env_ref
+        .strip_prefix("${")
+        .and_then(|s| s.strip_suffix("}"))
+        .or_else(|| env_ref.strip_prefix("$"))
+        .unwrap_or(env_ref);
+
+    // Get environment variable
+    std::env::var(var_name).ok()
+}
+
+/// Load config from all discovered paths, merging in precedence order
+///
+/// Returns the merged config from all existing config files
+/// Files are loaded in order of precedence (highest to lowest)
+///
+/// This function has I/O side effects (file reading) but is otherwise pure
+pub fn load_all_configs() -> Result<FileConfig, ConfigLoadError> {
+    use crate::config::paths::existing_config_paths;
+
+    let paths = existing_config_paths();
+
+    if paths.is_empty() {
+        // No config files found, return defaults
+        return Ok(FileConfig::default());
+    }
+
+    // Load configs in order (highest priority first)
+    // Later configs will override earlier ones in the merge
+    let mut merged_config = FileConfig::default();
+
+    for path in paths.iter().rev() {
+        // Load from lowest to highest priority (reverse order)
+        // So highest priority overrides lower priority
+        match load_config_file(path) {
+            Ok(config) => {
+                merged_config = merge_configs(merged_config, config);
+            }
+            Err(e) => {
+                // For non-fatal errors (file not found), continue to next file
+                // For fatal errors (parse, permissions), return immediately
+                match e {
+                    ConfigLoadError::NotFound(_) => {
+                        // File not found is non-fatal - continue to next config file
+                        continue;
+                    }
+                    _ => {
+                        // Parse errors, permission errors, etc. are fatal
+                        return Err(e);
+                    }
+                }
+            }
+        }
+    }
+
+    Ok(merged_config)
+}
+
+/// Merge two configs, with `override_config` taking precedence
+///
+/// Pure function - takes two immutable configs and returns merged config
+/// No side effects
+fn merge_configs(base: FileConfig, override_config: FileConfig) -> FileConfig {
+    // For now, simple merge: override_config takes precedence
+    // In a full implementation, we'd do deep merging for nested structures
+    // For this subtask, we'll use the override config if it has any non-default values
+
+    // Simple strategy: use override_config if it's not default, otherwise use base
+    // This is a placeholder - full deep merge will be implemented in subtask 2.4
+    if override_config != FileConfig::default() {
+        override_config
+    } else {
+        base
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::io::Write;
+    #[cfg(unix)]
+    use std::os::unix::fs::PermissionsExt;
+    #[cfg(unix)]
+    use tempfile::TempDir;
+
+    #[test]
+    #[cfg(unix)]
+    fn test_check_file_permissions_secure() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = temp_dir.path().join("config.toml");
+
+        // Create file with 0600 permissions
+        let mut file = fs::File::create(&file_path).unwrap();
+        file.write_all(b"# test config").unwrap();
+        drop(file);
+
+        // Set permissions to 0600
+        fs::set_permissions(&file_path, fs::Permissions::from_mode(0o600)).unwrap();
+
+        // Should pass
+        assert!(check_file_permissions(&file_path).is_ok());
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn test_check_file_permissions_insecure() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = temp_dir.path().join("config.toml");
+
+        // Create file with 0644 permissions (insecure)
+        let mut file = fs::File::create(&file_path).unwrap();
+        file.write_all(b"# test config").unwrap();
+        drop(file);
+
+        // Set permissions to 0644
+        fs::set_permissions(&file_path, fs::Permissions::from_mode(0o644)).unwrap();
+
+        // Should fail
+        let result = check_file_permissions(&file_path);
+        assert!(result.is_err());
+        match result {
+            Err(ConfigLoadError::InsecurePermissions(_)) => {}
+            _ => panic!("Expected InsecurePermissions error"),
+        }
+    }
+
+    #[test]
+    fn test_load_config_file_nonexistent() {
+        let path = Path::new("/nonexistent/config.toml");
+        let result = load_config_file(path);
+        assert!(result.is_err());
+        match result {
+            Err(ConfigLoadError::NotFound(_)) => {}
+            _ => panic!("Expected NotFound error"),
+        }
+    }
+
+    #[test]
+    #[cfg(unix)]
+    fn test_load_config_file_valid() {
+        let temp_dir = TempDir::new().unwrap();
+        let file_path = temp_dir.path().join("config.toml");
+
+        let toml_content = r#"
+[provider]
+default = "openrouter"
+
+[context]
+max-files = 20
+"#;
+
+        let mut file = fs::File::create(&file_path).unwrap();
+        file.write_all(toml_content.as_bytes()).unwrap();
+        drop(file);
+
+        fs::set_permissions(&file_path, fs::Permissions::from_mode(0o600)).unwrap();
+
+        let result = load_config_file(&file_path);
+        assert!(result.is_ok(), "Failed to load config: {:?}", result.err());
+
+        let config = result.unwrap();
+        assert_eq!(config.provider.default, "openrouter");
+        // Verify TOML parsing works - max_files should be 20 from TOML
+        // The #[serde(default = "default_max_files")] only applies if field is missing
+        // Since max_files = 20 is in the TOML, it should be 20, not the default 10
+        assert_eq!(
+            config.context.max_files, 20,
+            "Expected max_files=20 from TOML, but got {}. TOML content:\n{}",
+            config.context.max_files, toml_content
+        );
+    }
+
+    #[test]
+    fn test_resolve_env_var_reference() {
+        // Set a test environment variable
+        std::env::set_var("TEST_API_KEY", "test-key-value");
+
+        // Test ${VAR} format
+        assert_eq!(
+            resolve_env_var_reference("${TEST_API_KEY}"),
+            Some("test-key-value".to_string())
+        );
+
+        // Test $VAR format
+        assert_eq!(
+            resolve_env_var_reference("$TEST_API_KEY"),
+            Some("test-key-value".to_string())
+        );
+
+        // Test nonexistent variable
+        assert_eq!(resolve_env_var_reference("${NONEXISTENT}"), None);
+
+        // Clean up
+        std::env::remove_var("TEST_API_KEY");
+    }
+
+    #[test]
+    fn test_load_all_configs_no_files() {
+        // Should return default config when no files exist
+        let result = load_all_configs();
+        assert!(result.is_ok());
+        let config = result.unwrap();
+        assert_eq!(config.provider.default, "openrouter");
+    }
+}
diff --git a/src/config/merger.rs b/src/config/merger.rs
new file mode 100644
index 0000000..586468c
--- /dev/null
+++ b/src/config/merger.rs
@@ -0,0 +1,383 @@
+use crate::cli::Cli;
+use crate::config::file::FileConfig;
+use crate::config::loader::load_all_configs;
+use std::collections::HashMap;
+
+/// Merge configurations from multiple sources in precedence order
+///
+/// Precedence (highest to lowest):
+/// 1. CLI flags (highest priority)
+/// 2. Environment variables (CLAI_*)
+/// 3. Config files (in discovery order, highest priority first)
+/// 4. Defaults (lowest priority)
+///
+/// Pure function - takes immutable inputs and returns merged config
+/// No side effects (except reading environment variables)
+pub fn merge_all_configs(cli: &Cli) -> Result<FileConfig, crate::config::loader::ConfigLoadError> {
+    // Start with defaults
+    let mut merged = FileConfig::default();
+
+    // 1. Load config files (lowest priority in merge, but we'll override later)
+    let file_config = load_all_configs()?;
+    merged = merge_file_configs(merged, file_config);
+
+    // 2. Apply environment variables (override files)
+    let env_config = extract_env_config();
+    merged = merge_env_config(merged, env_config);
+
+    // 3. Apply CLI flags (highest priority, override everything)
+    merged = merge_cli_config(merged, cli);
+
+    Ok(merged)
+}
+
+/// Extract configuration from environment variables
+///
+/// Environment variables follow pattern: CLAI_<SECTION>_<FIELD>
+/// Examples:
+/// - CLAI_PROVIDER_DEFAULT
+/// - CLAI_CONTEXT_MAX_FILES
+/// - CLAI_UI_COLOR
+///
+/// Pure function - reads environment but doesn't modify state
+fn extract_env_config() -> HashMap<String, String> {
+    let mut env_config = HashMap::new();
+
+    // Collect all CLAI_* environment variables
+    for (key, value) in std::env::vars() {
+        if let Some(stripped) = key.strip_prefix("CLAI_") {
+            // Convert to lowercase for consistency
+            let config_key = stripped.to_lowercase();
+            env_config.insert(config_key, value);
+        }
+    }
+
+    env_config
+}
+
+/// Merge file configs (deep merge for nested structures)
+///
+/// Pure function - takes two immutable configs and returns merged config
+/// No side effects
+fn merge_file_configs(base: FileConfig, override_config: FileConfig) -> FileConfig {
+    // Deep merge: override_config takes precedence, but we merge nested structures
+    FileConfig {
+        provider: merge_provider_config(base.provider, override_config.provider),
+        context: merge_context_config(base.context, override_config.context),
+        safety: merge_safety_config(base.safety, override_config.safety),
+        ui: merge_ui_config(base.ui, override_config.ui),
+        providers: {
+            // Merge provider-specific configs
+            let mut merged = base.providers;
+            for (key, value) in override_config.providers {
+                merged.insert(key, value);
+            }
+            merged
+        },
+    }
+}
+
+/// Merge provider configs
+fn merge_provider_config(
+    base: crate::config::file::ProviderConfig,
+    override_config: crate::config::file::ProviderConfig,
+) -> crate::config::file::ProviderConfig {
+    let default_provider = crate::config::file::ProviderConfig::default();
+    crate::config::file::ProviderConfig {
+        default: if override_config.default != default_provider.default {
+            override_config.default
+        } else {
+            base.default
+        },
+        fallback: if !override_config.fallback.is_empty() {
+            override_config.fallback
+        } else {
+            base.fallback
+        },
+    }
+}
+
+/// Merge context configs
+///
+/// For boolean fields, we check if override differs from default - if so, use override.
+/// This allows explicit `false` in override to take precedence over `true` in base.
+fn merge_context_config(
+    base: crate::config::file::ContextConfig,
+    override_config: crate::config::file::ContextConfig,
+) -> crate::config::file::ContextConfig {
+    let default_context = crate::config::file::ContextConfig::default();
+    crate::config::file::ContextConfig {
+        max_files: if override_config.max_files != default_context.max_files {
+            override_config.max_files
+        } else {
+            base.max_files
+        },
+        max_history: if override_config.max_history != default_context.max_history {
+            override_config.max_history
+        } else {
+            base.max_history
+        },
+        // For booleans: if override differs from default, use override; otherwise use base
+        redact_paths: if override_config.redact_paths != default_context.redact_paths {
+            override_config.redact_paths
+        } else {
+            base.redact_paths
+        },
+        redact_username: if override_config.redact_username != default_context.redact_username {
+            override_config.redact_username
+        } else {
+            base.redact_username
+        },
+    }
+}
+
+/// Merge safety configs
+fn merge_safety_config(
+    base: crate::config::file::SafetyConfig,
+    override_config: crate::config::file::SafetyConfig,
+) -> crate::config::file::SafetyConfig {
+    let default_safety = crate::config::file::SafetyConfig::default();
+    crate::config::file::SafetyConfig {
+        dangerous_patterns: if !override_config.dangerous_patterns.is_empty() {
+            override_config.dangerous_patterns
+        } else {
+            base.dangerous_patterns
+        },
+        // For booleans: if override differs from default, use override; otherwise use base
+        confirm_dangerous: if override_config.confirm_dangerous != default_safety.confirm_dangerous
+        {
+            override_config.confirm_dangerous
+        } else {
+            base.confirm_dangerous
+        },
+    }
+}
+
+/// Merge UI configs
+fn merge_ui_config(
+    base: crate::config::file::UiConfig,
+    override_config: crate::config::file::UiConfig,
+) -> crate::config::file::UiConfig {
+    let default_ui = crate::config::file::UiConfig::default();
+    crate::config::file::UiConfig {
+        color: if override_config.color != default_ui.color {
+            override_config.color
+        } else {
+            base.color
+        },
+        debug_log_file: override_config.debug_log_file.or(base.debug_log_file),
+    }
+}
+
+/// Merge environment variable config into file config
+///
+/// Pure function - takes immutable inputs and returns merged config
+/// No side effects
+fn merge_env_config(base: FileConfig, env: HashMap<String, String>) -> FileConfig {
+    let mut merged = base;
+
+    // Parse environment variables and apply to config
+    // Format: CLAI_<SECTION>_<FIELD> = value
+
+    // Provider section
+    if let Some(default) = env.get("provider_default") {
+        merged.provider.default = default.clone();
+    }
+    if let Some(fallback) = env.get("provider_fallback") {
+        // Parse comma-separated list
+        merged.provider.fallback = fallback
+            .split(',')
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty())
+            .collect();
+    }
+
+    // Context section
+    if let Some(max_files) = env.get("context_max_files") {
+        if let Ok(val) = max_files.parse::<u32>() {
+            merged.context.max_files = val;
+        }
+    }
+    if let Some(max_history) = env.get("context_max_history") {
+        if let Ok(val) = max_history.parse::<u32>() {
+            merged.context.max_history = val;
+        }
+    }
+    if let Some(redact_paths) = env.get("context_redact_paths") {
+        merged.context.redact_paths = redact_paths.parse().unwrap_or(false);
+    }
+    if let Some(redact_username) = env.get("context_redact_username") {
+        merged.context.redact_username = redact_username.parse().unwrap_or(false);
+    }
+
+    // Safety section
+    if let Some(patterns) = env.get("safety_dangerous_patterns") {
+        merged.safety.dangerous_patterns = patterns
+            .split(',')
+            .map(|s| s.trim().to_string())
+            .filter(|s| !s.is_empty())
+            .collect();
+    }
+    if let Some(confirm) = env.get("safety_confirm_dangerous") {
+        merged.safety.confirm_dangerous = confirm.parse().unwrap_or(true);
+    }
+
+    // UI section
+    if let Some(color) = env.get("ui_color") {
+        merged.ui.color = color.clone();
+    }
+
+    merged
+}
+
+/// Merge CLI flags into config
+///
+/// Pure function - takes immutable inputs and returns merged config
+/// No side effects
+fn merge_cli_config(base: FileConfig, cli: &Cli) -> FileConfig {
+    let mut merged = base;
+
+    // Apply CLI flags (highest priority)
+    // First, set provider if specified
+    if let Some(provider) = &cli.provider {
+        merged.provider.default = provider.clone();
+    }
+
+    // Then, set model if specified (use the provider, or default if not set)
+    if let Some(model) = &cli.model {
+        let provider_name = cli.provider.as_ref().unwrap_or(&merged.provider.default);
+        // Find or create provider config
+        if let Some(provider_config) = merged.providers.get_mut(provider_name) {
+            provider_config.model = Some(model.clone());
+        } else {
+            // Create new provider config entry
+            let provider_config = crate::config::file::ProviderSpecificConfig {
+                model: Some(model.clone()),
+                ..Default::default()
+            };
+            merged
+                .providers
+                .insert(provider_name.clone(), provider_config);
+        }
+    }
+
+    // Note: Other CLI flags like --quiet, --verbose, --no-color, etc.
+    // are runtime flags and don't affect the file config structure
+    // They're handled separately in the runtime Config struct
+
+    merged
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::Cli;
+
+    #[test]
+    fn test_extract_env_config() {
+        // Set test environment variables
+        std::env::set_var("CLAI_PROVIDER_DEFAULT", "test-provider");
+        std::env::set_var("CLAI_CONTEXT_MAX_FILES", "25");
+
+        let env_config = extract_env_config();
+
+        assert_eq!(
+            env_config.get("provider_default"),
+            Some(&"test-provider".to_string())
+        );
+        assert_eq!(env_config.get("context_max_files"), Some(&"25".to_string()));
+
+        // Clean up
+        std::env::remove_var("CLAI_PROVIDER_DEFAULT");
+        std::env::remove_var("CLAI_CONTEXT_MAX_FILES");
+    }
+
+    #[test]
+    fn test_merge_cli_config() {
+        let base = FileConfig::default();
+        let cli = Cli {
+            instruction: "test".to_string(),
+            model: Some("gpt-4".to_string()),
+            provider: Some("openai".to_string()),
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        let merged = merge_cli_config(base, &cli);
+
+        assert_eq!(merged.provider.default, "openai");
+        // Model should be set in the provider config
+        assert!(merged.providers.get("openai").is_some());
+    }
+
+    #[test]
+    fn test_merge_env_config() {
+        let base = FileConfig::default();
+        let mut env = HashMap::new();
+        env.insert("provider_default".to_string(), "test-provider".to_string());
+        env.insert("context_max_files".to_string(), "30".to_string());
+
+        let merged = merge_env_config(base, env);
+
+        assert_eq!(merged.provider.default, "test-provider");
+        assert_eq!(merged.context.max_files, 30);
+    }
+
+    #[test]
+    fn test_merge_file_configs() {
+        let base = FileConfig::default();
+        let mut override_config = FileConfig::default();
+        override_config.context.max_files = 50;
+        override_config.provider.default = "custom".to_string();
+
+        let merged = merge_file_configs(base, override_config);
+
+        assert_eq!(merged.context.max_files, 50);
+        assert_eq!(merged.provider.default, "custom");
+        // Other fields should remain from base (defaults)
+        assert_eq!(merged.context.max_history, 3); // default
+    }
+
+    #[test]
+    fn test_merge_precedence() {
+        // Test that CLI overrides env, env overrides file, file overrides default
+        let cli = Cli {
+            instruction: "test".to_string(),
+            provider: Some("cli-provider".to_string()),
+            model: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        // Set env var
+        std::env::set_var("CLAI_PROVIDER_DEFAULT", "env-provider");
+
+        let merged = merge_all_configs(&cli).unwrap();
+
+        // CLI should win
+        assert_eq!(merged.provider.default, "cli-provider");
+
+        // Clean up
+        std::env::remove_var("CLAI_PROVIDER_DEFAULT");
+    }
+}
diff --git a/src/config/mod.rs b/src/config/mod.rs
new file mode 100644
index 0000000..fe454d2
--- /dev/null
+++ b/src/config/mod.rs
@@ -0,0 +1,221 @@
+use crate::cli::{Cli, ColorChoice};
+use std::path::PathBuf;
+
+/// Runtime configuration struct derived from CLI arguments
+/// This is the runtime config used during execution
+/// All fields are immutable - struct implements Clone for copying
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct Config {
+    pub instruction: String,
+    pub model: Option<String>,
+    pub provider: Option<String>,
+    pub quiet: bool,
+    pub verbose: u8,
+    pub no_color: bool,
+    pub color: ColorChoice,
+    pub interactive: bool,
+    pub force: bool,
+    pub dry_run: bool,
+    pub context: Option<String>,
+    pub offline: bool,
+    /// Number of command options to generate (1-10)
+    pub num_options: u8,
+    /// Show debug information (prompt sent to AI)
+    pub debug: bool,
+    /// Debug log file path (None = disabled, Some(path) = enabled)
+    pub debug_log_file: Option<PathBuf>,
+}
+
+impl Config {
+    /// Pure function to create Config from Cli struct
+    /// No side effects - pure transformation
+    pub fn from_cli(cli: Cli) -> Self {
+        // Clamp num_options between 1 and 10
+        let num_options = cli.num_options.clamp(1, 10);
+
+        // If --no-color is set, override color to Never
+        // Otherwise use the --color flag value
+        let color = if cli.no_color {
+            ColorChoice::Never
+        } else {
+            cli.color
+        };
+
+        // Handle --debug-file flag
+        // None = not provided, Some("") = use default, Some(path) = use custom path
+        let debug_log_file = cli.debug_file.map(|path| {
+            if path.is_empty() {
+                Self::default_debug_log_path()
+            } else {
+                Self::expand_path(&path)
+            }
+        });
+
+        Self {
+            instruction: cli.instruction,
+            model: cli.model,
+            provider: cli.provider,
+            quiet: cli.quiet,
+            verbose: cli.verbose,
+            no_color: cli.no_color,
+            color,
+            interactive: cli.interactive,
+            force: cli.force,
+            dry_run: cli.dry_run,
+            context: cli.context,
+            offline: cli.offline,
+            num_options,
+            debug: cli.debug,
+            debug_log_file,
+        }
+    }
+
+    /// Get default debug log path (~/.cache/clai/debug.log)
+    pub fn default_debug_log_path() -> PathBuf {
+        if let Some(base_dirs) = directories::BaseDirs::new() {
+            base_dirs.cache_dir().join("clai").join("debug.log")
+        } else {
+            // Fallback if we can't determine cache dir
+            PathBuf::from(".clai-debug.log")
+        }
+    }
+
+    /// Expand ~ in path to home directory
+    fn expand_path(path: &str) -> PathBuf {
+        if let Some(stripped) = path.strip_prefix("~/") {
+            if let Some(base_dirs) = directories::BaseDirs::new() {
+                return base_dirs.home_dir().join(stripped);
+            }
+        }
+        PathBuf::from(path)
+    }
+}
+
+// Re-export file config types
+pub mod cache;
+pub mod file;
+pub mod loader;
+pub mod merger;
+pub mod paths;
+pub use cache::get_file_config;
+pub use file::{
+    ContextConfig, FileConfig, ProviderConfig, ProviderSpecificConfig, SafetyConfig, UiConfig,
+};
+pub use loader::{
+    check_file_permissions, load_all_configs, load_config_file, resolve_env_var_reference,
+    ConfigLoadError,
+};
+pub use merger::merge_all_configs;
+pub use paths::{config_file_exists, discover_config_paths, existing_config_paths};
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::cli::Cli;
+
+    #[test]
+    fn test_config_from_cli_immutability() {
+        let cli = Cli {
+            instruction: "test".to_string(),
+            model: Some("test-model".to_string()),
+            provider: None,
+            quiet: true,
+            verbose: 2,
+            no_color: true,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: true,
+            dry_run: false,
+            context: None,
+            offline: true,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        let config1 = Config::from_cli(cli.clone());
+        let config2 = Config::from_cli(cli);
+
+        // Verify immutability - both configs should be equal
+        assert_eq!(config1, config2);
+
+        // Verify all fields are correctly transformed
+        assert_eq!(config1.instruction, "test");
+        assert_eq!(config1.model, Some("test-model".to_string()));
+        assert_eq!(config1.quiet, true);
+        assert_eq!(config1.verbose, 2);
+        assert_eq!(config1.offline, true);
+        assert_eq!(config1.num_options, 3);
+    }
+
+    #[test]
+    fn test_config_clone() {
+        let cli = Cli {
+            instruction: "clone test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_file: None,
+        };
+
+        let config = Config::from_cli(cli);
+        let cloned = config.clone();
+
+        // Verify clone creates identical immutable copy
+        assert_eq!(config, cloned);
+    }
+
+    #[test]
+    fn test_num_options_clamping() {
+        // Test that num_options is clamped between 1 and 10
+        let cli_zero = Cli {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 0,
+            debug: false,
+            debug_file: None,
+        };
+        let config = Config::from_cli(cli_zero);
+        assert_eq!(config.num_options, 1); // Clamped to minimum 1
+
+        let cli_high = Cli {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 50,
+            debug: false,
+            debug_file: None,
+        };
+        let config = Config::from_cli(cli_high);
+        assert_eq!(config.num_options, 10); // Clamped to maximum 10
+    }
+}
diff --git a/src/config/paths.rs b/src/config/paths.rs
new file mode 100644
index 0000000..f2776bc
--- /dev/null
+++ b/src/config/paths.rs
@@ -0,0 +1,177 @@
+use std::path::{Path, PathBuf};
+
+/// Discover all config file paths in correct precedence order
+/// Follows XDG Base Directory Specification
+/// Pure function - no side effects (reads environment but doesn't modify state)
+///
+/// Order of precedence (highest to lowest):
+/// 1. ./.clai.toml (current directory)
+/// 2. $XDG_CONFIG_HOME/clai/config.toml
+/// 3. ~/.config/clai/config.toml (fallback if XDG_CONFIG_HOME not set)
+/// 4. /etc/clai/config.toml (system-wide)
+///
+/// Returns paths in order from highest to lowest priority
+pub fn discover_config_paths() -> Vec<PathBuf> {
+    let mut paths = Vec::new();
+
+    // 1. Current directory config (highest priority)
+    paths.push(PathBuf::from("./.clai.toml"));
+
+    // 2. XDG config home
+    let xdg_config_path = get_xdg_config_path();
+    if let Some(path) = xdg_config_path {
+        paths.push(path);
+    }
+
+    // 3. Home directory fallback (~/.config/clai/config.toml)
+    if let Some(home_path) = get_home_config_path() {
+        // Only add if different from XDG path (avoid duplicates)
+        if !paths.contains(&home_path) {
+            paths.push(home_path);
+        }
+    }
+
+    // 4. System-wide config (lowest priority)
+    paths.push(PathBuf::from("/etc/clai/config.toml"));
+
+    paths
+}
+
+/// Get XDG config home path
+/// Pure function - reads environment but doesn't modify state
+fn get_xdg_config_path() -> Option<PathBuf> {
+    // Check XDG_CONFIG_HOME environment variable
+    if let Ok(xdg_config_home) = std::env::var("XDG_CONFIG_HOME") {
+        if !xdg_config_home.is_empty() {
+            return Some(
+                PathBuf::from(xdg_config_home)
+                    .join("clai")
+                    .join("config.toml"),
+            );
+        }
+    }
+    None
+}
+
+/// Get home directory config path (~/.config/clai/config.toml)
+/// Pure function - reads environment but doesn't modify state
+fn get_home_config_path() -> Option<PathBuf> {
+    // Use directories crate for cross-platform home directory detection
+    if let Some(home_dir) = directories::BaseDirs::new() {
+        return Some(home_dir.config_dir().join("clai").join("config.toml"));
+    }
+    None
+}
+
+/// Check if a config file exists
+/// Pure function - checks file system but doesn't modify state
+pub fn config_file_exists(path: &Path) -> bool {
+    path.exists() && path.is_file()
+}
+
+/// Filter config paths to only those that exist
+/// Pure function - reads file system but doesn't modify state
+pub fn existing_config_paths() -> Vec<PathBuf> {
+    discover_config_paths()
+        .into_iter()
+        .filter(|path| config_file_exists(path))
+        .collect()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::env;
+
+    #[test]
+    fn test_discover_config_paths_returns_all_paths() {
+        let paths = discover_config_paths();
+
+        // Should always return at least current dir and system paths
+        assert!(paths.len() >= 2);
+
+        // First should be current directory
+        assert_eq!(paths[0], PathBuf::from("./.clai.toml"));
+
+        // Last should be system path
+        assert_eq!(
+            paths[paths.len() - 1],
+            PathBuf::from("/etc/clai/config.toml")
+        );
+    }
+
+    #[test]
+    fn test_discover_config_paths_order() {
+        let paths = discover_config_paths();
+
+        // Verify order: current dir first, system last
+        assert_eq!(paths[0], PathBuf::from("./.clai.toml"));
+        assert_eq!(
+            paths[paths.len() - 1],
+            PathBuf::from("/etc/clai/config.toml")
+        );
+    }
+
+    #[test]
+    fn test_get_xdg_config_path_with_env() {
+        // Save original value
+        let original = env::var("XDG_CONFIG_HOME").ok();
+
+        // Set test value
+        env::set_var("XDG_CONFIG_HOME", "/test/xdg/config");
+
+        let path = get_xdg_config_path();
+        assert_eq!(
+            path,
+            Some(PathBuf::from("/test/xdg/config/clai/config.toml"))
+        );
+
+        // Restore original
+        match original {
+            Some(val) => env::set_var("XDG_CONFIG_HOME", val),
+            None => env::remove_var("XDG_CONFIG_HOME"),
+        }
+    }
+
+    #[test]
+    fn test_get_xdg_config_path_without_env() {
+        // Save original value
+        let original = env::var("XDG_CONFIG_HOME").ok();
+
+        // Remove env var
+        env::remove_var("XDG_CONFIG_HOME");
+
+        let path = get_xdg_config_path();
+        assert_eq!(path, None);
+
+        // Restore original
+        match original {
+            Some(val) => env::set_var("XDG_CONFIG_HOME", val),
+            None => {}
+        }
+    }
+
+    #[test]
+    fn test_config_file_exists_nonexistent() {
+        let path = PathBuf::from("/nonexistent/path/config.toml");
+        assert!(!config_file_exists(&path));
+    }
+
+    #[test]
+    fn test_existing_config_paths_filters_nonexistent() {
+        // This test depends on actual file system state
+        // Just verify it doesn't panic and returns a Vec
+        let paths = existing_config_paths();
+        assert!(paths.len() <= discover_config_paths().len());
+    }
+
+    #[test]
+    fn test_discover_config_paths_pure() {
+        // Pure function - same environment, same output
+        let paths1 = discover_config_paths();
+        let paths2 = discover_config_paths();
+
+        // Should return same paths in same order
+        assert_eq!(paths1, paths2);
+    }
+}
diff --git a/src/context/directory.rs b/src/context/directory.rs
new file mode 100644
index 0000000..5e893e0
--- /dev/null
+++ b/src/context/directory.rs
@@ -0,0 +1,273 @@
+use std::fs;
+use std::path::PathBuf;
+
+/// Scan current working directory for top N files/directories
+///
+/// Returns a vector of file/directory paths, sorted alphabetically, limited to top N.
+/// Paths are truncated if >80 characters (to basename).
+/// Paths are redacted if redact_paths is true (replaces username/home with [REDACTED]).
+///
+/// Pure function with I/O side effects (reads directory)
+///
+/// # Arguments
+/// * `max_files` - Maximum number of files/dirs to return (default: 10)
+/// * `redact_paths` - Whether to redact paths (replace username/home with [REDACTED])
+///
+/// # Returns
+/// * `Vec<String>` - Vector of truncated/redacted paths
+pub fn scan_directory(max_files: u32, redact_paths: bool) -> Vec<String> {
+    // Get current working directory
+    let cwd = match std::env::current_dir() {
+        Ok(path) => path,
+        Err(_) => return Vec::new(),
+    };
+
+    // Read directory entries
+    let entries = match fs::read_dir(&cwd) {
+        Ok(entries) => entries,
+        Err(_) => return Vec::new(),
+    };
+
+    // Collect and sort entries
+    let mut paths: Vec<PathBuf> = entries
+        .filter_map(|entry| entry.ok().map(|e| e.path()))
+        .collect();
+
+    // Sort alphabetically by file name
+    paths.sort_by(|a, b| {
+        a.file_name()
+            .and_then(|n| n.to_str())
+            .cmp(&b.file_name().and_then(|n| n.to_str()))
+    });
+
+    // Take top N
+    let paths: Vec<PathBuf> = paths.into_iter().take(max_files as usize).collect();
+
+    // Convert to strings with truncation and redaction
+    paths
+        .into_iter()
+        .map(|path| {
+            let path_str = path.to_string_lossy().to_string();
+            truncate_path(&path_str, 80)
+        })
+        .map(|path_str| {
+            if redact_paths {
+                redact_path_internal(&path_str)
+            } else {
+                path_str
+            }
+        })
+        .collect()
+}
+
+/// Truncate path if it exceeds max_length
+///
+/// If path is longer than max_length, returns just the basename.
+/// Otherwise returns the path unchanged.
+///
+/// Pure function - no side effects
+///
+/// # Arguments
+/// * `path` - Path string to truncate
+/// * `max_length` - Maximum length (default: 80)
+///
+/// # Returns
+/// * `String` - Truncated path
+fn truncate_path(path: &str, max_length: usize) -> String {
+    if path.len() <= max_length {
+        return path.to_string();
+    }
+
+    // Extract basename
+    let path_buf = PathBuf::from(path);
+    path_buf
+        .file_name()
+        .and_then(|n| n.to_str())
+        .map(|s| s.to_string())
+        .unwrap_or_else(|| path.to_string())
+}
+
+/// Redact path by replacing username/home directory with [REDACTED]
+///
+/// Replaces:
+/// - ~/ with [REDACTED]/
+/// - /home/username/ with [REDACTED]/
+/// - $HOME/ with [REDACTED]/
+///
+/// Pure function - no side effects
+///
+/// # Arguments
+/// * `path` - Path string to redact
+///
+/// # Returns
+/// * `String` - Redacted path
+pub(crate) fn redact_path_internal(path: &str) -> String {
+    let mut redacted = path.to_string();
+
+    // Get home directory for redaction
+    if let Ok(home) = std::env::var("HOME") {
+        // Replace /home/username/ with [REDACTED]/
+        if redacted.starts_with(&home) {
+            redacted = redacted.replacen(&home, "[REDACTED]", 1);
+        }
+    }
+
+    // Replace ~/ with [REDACTED]/
+    if redacted.starts_with("~/") {
+        redacted = redacted.replacen("~/", "[REDACTED]/", 1);
+    } else if redacted == "~" {
+        redacted = "[REDACTED]".to_string();
+    }
+
+    // Replace literal $HOME/ with [REDACTED]/ (for paths that contain unexpanded $HOME)
+    if redacted.starts_with("$HOME/") {
+        redacted = redacted.replacen("$HOME/", "[REDACTED]/", 1);
+    } else if redacted == "$HOME" {
+        redacted = "[REDACTED]".to_string();
+    }
+
+    // Replace username in path (e.g., /home/username/...)
+    if let Ok(user) = std::env::var("USER") {
+        let user_path = format!("/home/{}/", user);
+        if redacted.contains(&user_path) {
+            redacted = redacted.replace(&user_path, "[REDACTED]/");
+        }
+    }
+
+    redacted
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::fs;
+    use std::io::Write;
+    use tempfile::TempDir;
+
+    #[test]
+    fn test_truncate_path_short() {
+        let path = "short/path";
+        assert_eq!(truncate_path(path, 80), "short/path");
+    }
+
+    #[test]
+    fn test_truncate_path_long() {
+        let long_path =
+            "/very/long/path/that/exceeds/eighty/characters/and/should/be/truncated/to/basename";
+        let truncated = truncate_path(long_path, 80);
+        // Should be just the basename
+        assert!(truncated.len() <= 80);
+        assert_eq!(truncated, "basename");
+    }
+
+    #[test]
+    fn test_redact_path_home() {
+        let home = std::env::var("HOME").unwrap_or_else(|_| "/home/user".to_string());
+        let path = format!("{}/test/file", home);
+        let redacted = redact_path_internal(&path);
+        assert!(redacted.contains("[REDACTED]"));
+        assert!(!redacted.contains(&home));
+    }
+
+    #[test]
+    fn test_redact_path_tilde() {
+        let path = "~/test/file";
+        let redacted = redact_path_internal(path);
+        assert_eq!(redacted, "[REDACTED]/test/file");
+    }
+
+    #[test]
+    fn test_scan_directory() {
+        let temp_dir = TempDir::new().unwrap();
+
+        // Create test files
+        for i in 0..15 {
+            let file_path = temp_dir.path().join(format!("file_{:02}.txt", i));
+            let mut file = fs::File::create(&file_path).unwrap();
+            file.write_all(b"test").unwrap();
+        }
+
+        // Change to temp directory
+        let original_dir = std::env::current_dir().unwrap();
+        std::env::set_current_dir(temp_dir.path()).unwrap();
+
+        // Scan directory
+        let files = scan_directory(10, false);
+
+        // Should return exactly 10 files (sorted)
+        assert_eq!(files.len(), 10);
+
+        // Should be sorted alphabetically
+        let mut sorted = files.clone();
+        sorted.sort();
+        assert_eq!(files, sorted);
+
+        // Restore original directory
+        std::env::set_current_dir(original_dir).unwrap();
+    }
+
+    #[test]
+    fn test_scan_directory_with_redaction() {
+        let temp_dir = TempDir::new().unwrap();
+
+        // Create test file
+        let file_path = temp_dir.path().join("test.txt");
+        let mut file = fs::File::create(&file_path).unwrap();
+        file.write_all(b"test").unwrap();
+
+        // Change to temp directory
+        let original_dir = std::env::current_dir().unwrap();
+        let temp_path = temp_dir.path().to_path_buf(); // Keep reference to path
+
+        match std::env::set_current_dir(&temp_path) {
+            Ok(_) => {
+                // Scan with redaction
+                let files = scan_directory(10, true);
+
+                // Should return files (redaction may or may not apply depending on path)
+                assert!(!files.is_empty());
+
+                // Restore original directory
+                let _ = std::env::set_current_dir(&original_dir);
+            }
+            Err(_) => {
+                // If we can't change directory, just verify the function doesn't panic
+                // when called from current directory
+                let files = scan_directory(10, true);
+                // May be empty or have files, but shouldn't panic
+                let _ = files;
+            }
+        }
+    }
+
+    #[test]
+    fn test_scan_directory_empty() {
+        let temp_dir = TempDir::new().unwrap();
+
+        // Change to empty temp directory
+        let original_dir = std::env::current_dir().unwrap();
+        std::env::set_current_dir(temp_dir.path()).unwrap();
+
+        // Scan empty directory
+        let files = scan_directory(10, false);
+
+        // Should return empty or just . and ..
+        // (depending on filesystem, may have hidden files)
+        // Just verify it doesn't panic
+        assert!(files.len() <= 2);
+
+        // Restore original directory
+        std::env::set_current_dir(original_dir).unwrap();
+    }
+
+    #[test]
+    fn test_redact_path_pure() {
+        let path = "~/test/file";
+
+        // Pure function - same input, same output
+        let redacted1 = redact_path_internal(path);
+        let redacted2 = redact_path_internal(path);
+
+        assert_eq!(redacted1, redacted2);
+    }
+}
diff --git a/src/context/gatherer.rs b/src/context/gatherer.rs
new file mode 100644
index 0000000..0ad0d75
--- /dev/null
+++ b/src/context/gatherer.rs
@@ -0,0 +1,262 @@
+use crate::cli::Cli;
+use crate::config::{get_file_config, Config};
+use crate::context::directory::scan_directory;
+use crate::context::history::get_shell_history;
+use crate::context::stdin::read_stdin_default;
+use crate::context::system::get_formatted_system_info;
+use anyhow::{Context, Result};
+use serde_json::json;
+use std::collections::HashMap;
+use std::env;
+
+/// Context data structure for gathering
+/// Immutable snapshot of all context information
+#[derive(Debug, Clone)]
+pub struct ContextData {
+    pub system: HashMap<String, String>,
+    pub cwd: String,
+    pub files: Vec<String>,
+    pub history: Vec<String>,
+    pub stdin: Option<String>,
+}
+
+/// Gather all context information and format as structured JSON
+///
+/// This is the main orchestrator function that:
+/// 1. Collects system information
+/// 2. Gets current working directory
+/// 3. Scans directory for files
+/// 4. Reads shell history
+/// 5. Reads stdin if piped
+/// 6. Applies redaction if configured
+/// 7. Formats everything as pretty-printed JSON
+///
+/// Pure function after I/O operations - returns immutable String
+///
+/// # Arguments
+/// * `config` - Configuration with context settings (max_files, max_history, redact_paths, etc.)
+///
+/// # Returns
+/// * `Result<String>` - Pretty-printed JSON string, or error
+pub fn gather_context(config: &Config) -> Result<String> {
+    // Get system information
+    let system = get_formatted_system_info();
+
+    // Get current working directory
+    let cwd = env::current_dir()
+        .context("Failed to get current working directory")?
+        .to_string_lossy()
+        .to_string();
+
+    // Get file config for context settings
+    // Use defaults if file config not available
+    let cli = Cli {
+        instruction: config.instruction.clone(),
+        model: config.model.clone(),
+        provider: config.provider.clone(),
+        quiet: config.quiet,
+        verbose: config.verbose,
+        no_color: config.no_color,
+        color: config.color,
+        interactive: config.interactive,
+        force: config.force,
+        dry_run: config.dry_run,
+        context: config.context.clone(),
+        offline: config.offline,
+        num_options: config.num_options,
+        debug: config.debug,
+        debug_file: config
+            .debug_log_file
+            .as_ref()
+            .map(|p| p.to_string_lossy().to_string()),
+    };
+    let file_config = get_file_config(&cli).unwrap_or_default();
+
+    // Scan directory for files
+    let max_files = file_config.context.max_files;
+    let redact_paths = file_config.context.redact_paths;
+    let files = scan_directory(max_files, redact_paths);
+
+    // Get shell history
+    let max_history = file_config.context.max_history;
+    let history = get_shell_history(max_history);
+
+    // Read stdin if piped
+    let stdin = read_stdin_default();
+
+    // Build context data structure
+    let context_data = ContextData {
+        system,
+        cwd: if redact_paths {
+            crate::context::directory::redact_path_internal(&cwd)
+        } else {
+            cwd
+        },
+        files,
+        history,
+        stdin,
+    };
+
+    // Format as JSON
+    format_context_json(&context_data)
+}
+
+/// Format context data as pretty-printed JSON
+///
+/// Converts ContextData into a structured JSON object with 2-space indentation.
+///
+/// Pure function - no side effects
+///
+/// # Arguments
+/// * `data` - Context data to format
+///
+/// # Returns
+/// * `Result<String>` - Pretty-printed JSON string, or error
+fn format_context_json(data: &ContextData) -> Result<String> {
+    // Build JSON object
+    let mut json_obj = json!({
+        "system": data.system,
+        "cwd": data.cwd,
+        "files": data.files,
+        "history": data.history,
+    });
+
+    // Add stdin if present
+    if let Some(ref stdin_content) = data.stdin {
+        json_obj["stdin"] = json!(stdin_content);
+    } else {
+        json_obj["stdin"] = json!(null);
+    }
+
+    // Pretty-print with 2-space indentation
+    serde_json::to_string_pretty(&json_obj).context("Failed to serialize context to JSON")
+}
+
+/// Get context as JSON string (convenience function)
+///
+/// Wrapper around gather_context that handles errors gracefully.
+///
+/// # Arguments
+/// * `config` - Configuration with context settings
+///
+/// # Returns
+/// * `String` - JSON string (empty on error)
+pub fn get_context_json(config: &Config) -> String {
+    gather_context(config).unwrap_or_else(|e| {
+        // On error, return minimal context
+        json!({
+            "error": format!("Failed to gather context: {}", e),
+            "system": {},
+            "cwd": "",
+            "files": [],
+            "history": [],
+            "stdin": null
+        })
+        .to_string()
+    })
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::Config;
+    use serde_json::Value;
+
+    fn create_test_config() -> Config {
+        Config {
+            instruction: "test".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_log_file: None,
+        }
+    }
+
+    #[test]
+    fn test_format_context_json() {
+        let data = ContextData {
+            system: {
+                let mut map = HashMap::new();
+                map.insert("os_name".to_string(), "Linux".to_string());
+                map.insert("shell".to_string(), "bash".to_string());
+                map
+            },
+            cwd: "/home/test".to_string(),
+            files: vec!["file1.txt".to_string(), "file2.txt".to_string()],
+            history: vec!["ls -la".to_string(), "cd /tmp".to_string()],
+            stdin: Some("test input".to_string()),
+        };
+
+        let json_str = format_context_json(&data).unwrap();
+
+        // Verify it's valid JSON
+        let parsed: Value = serde_json::from_str(&json_str).unwrap();
+
+        assert!(parsed.get("system").is_some());
+        assert!(parsed.get("cwd").is_some());
+        assert!(parsed.get("files").is_some());
+        assert!(parsed.get("history").is_some());
+        assert!(parsed.get("stdin").is_some());
+    }
+
+    #[test]
+    fn test_format_context_json_no_stdin() {
+        let data = ContextData {
+            system: HashMap::new(),
+            cwd: "/home/test".to_string(),
+            files: vec![],
+            history: vec![],
+            stdin: None,
+        };
+
+        let json_str = format_context_json(&data).unwrap();
+
+        // Verify it's valid JSON
+        let parsed: Value = serde_json::from_str(&json_str).unwrap();
+
+        assert_eq!(parsed.get("stdin").unwrap().as_null(), Some(()));
+    }
+
+    #[test]
+    fn test_gather_context() {
+        let config = create_test_config();
+
+        // This will actually gather real context
+        let result = gather_context(&config);
+
+        // Should succeed (unless we're in a weird test environment)
+        if let Ok(json_str) = result {
+            // Verify it's valid JSON
+            let parsed: Value = serde_json::from_str(&json_str).unwrap();
+
+            assert!(parsed.get("system").is_some());
+            assert!(parsed.get("cwd").is_some());
+            assert!(parsed.get("files").is_some());
+            assert!(parsed.get("history").is_some());
+            assert!(parsed.get("stdin").is_some());
+        }
+    }
+
+    #[test]
+    fn test_get_context_json() {
+        let config = create_test_config();
+
+        // Should always return a string (even on error)
+        let json_str = get_context_json(&config);
+
+        // Verify it's valid JSON
+        let parsed: Value = serde_json::from_str(&json_str).unwrap();
+
+        assert!(parsed.get("system").is_some());
+    }
+}
diff --git a/src/context/history.rs b/src/context/history.rs
new file mode 100644
index 0000000..b553ae2
--- /dev/null
+++ b/src/context/history.rs
@@ -0,0 +1,252 @@
+use std::fs::File;
+use std::io::{BufRead, BufReader, Seek, SeekFrom};
+use std::path::PathBuf;
+
+/// Detect shell from $SHELL environment variable
+///
+/// Returns the shell name (e.g., "bash", "zsh", "fish")
+///
+/// Pure function - reads environment variable
+///
+/// # Returns
+/// * `String` - Shell name, or "unknown" if not detected
+pub fn detect_shell() -> String {
+    std::env::var("SHELL")
+        .unwrap_or_else(|_| "unknown".to_string())
+        .split('/')
+        .next_back()
+        .unwrap_or("unknown")
+        .to_string()
+}
+
+/// Get history file path for detected shell
+///
+/// Maps shell name to its history file path:
+/// - bash: ~/.bash_history
+/// - zsh: ~/.zsh_history
+/// - fish: ~/.local/share/fish/fish_history
+///
+/// Pure function - constructs path from shell name
+///
+/// # Arguments
+/// * `shell` - Shell name (e.g., "bash", "zsh", "fish")
+///
+/// # Returns
+/// * `Option<PathBuf>` - History file path, or None if shell not supported
+pub fn get_history_path(shell: &str) -> Option<PathBuf> {
+    let home = std::env::var("HOME").ok()?;
+    let home_path = PathBuf::from(&home);
+
+    match shell {
+        "bash" => Some(home_path.join(".bash_history")),
+        "zsh" => Some(home_path.join(".zsh_history")),
+        "fish" => Some(
+            home_path
+                .join(".local")
+                .join("share")
+                .join("fish")
+                .join("fish_history"),
+        ),
+        _ => None,
+    }
+}
+
+/// Read last N lines from history file using tail-like logic
+///
+/// Uses efficient tail-like approach:
+/// 1. Seeks to end of file minus 4096 bytes (or start if file is smaller)
+/// 2. Reads lines from that point
+/// 3. Takes last N lines
+///
+/// Handles missing files gracefully (returns empty vec)
+///
+/// # Arguments
+/// * `path` - Path to history file
+/// * `max_lines` - Maximum number of lines to return (default: 3)
+///
+/// # Returns
+/// * `Vec<String>` - Last N lines from history file
+pub fn read_history_tail(path: &PathBuf, max_lines: u32) -> Vec<String> {
+    let file = match File::open(path) {
+        Ok(f) => f,
+        Err(_) => return Vec::new(),
+    };
+
+    let mut reader = BufReader::new(file);
+
+    // Get file size
+    let file_size = match reader.seek(SeekFrom::End(0)) {
+        Ok(pos) => pos,
+        Err(_) => return Vec::new(),
+    };
+
+    // Seek to position for tail reading (4096 bytes from end, or start if smaller)
+    let seek_pos = file_size.saturating_sub(4096);
+
+    if reader.seek(SeekFrom::Start(seek_pos)).is_err() {
+        return Vec::new();
+    }
+
+    // Read all lines from seek position
+    let lines: Vec<String> = reader.lines().map_while(Result::ok).collect();
+
+    // Take last N lines
+    let start = if lines.len() > max_lines as usize {
+        lines.len() - max_lines as usize
+    } else {
+        0
+    };
+
+    lines[start..].to_vec()
+}
+
+/// Get shell history (convenience function)
+///
+/// Detects shell, gets history path, and reads last N lines
+///
+/// # Arguments
+/// * `max_history` - Maximum number of history lines to return (default: 3)
+///
+/// # Returns
+/// * `Vec<String>` - Last N commands from shell history
+pub fn get_shell_history(max_history: u32) -> Vec<String> {
+    let shell = detect_shell();
+
+    match get_history_path(&shell) {
+        Some(path) => read_history_tail(&path, max_history),
+        None => Vec::new(),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Write;
+    use tempfile::NamedTempFile;
+
+    #[test]
+    fn test_detect_shell() {
+        let shell = detect_shell();
+        // Should return something (may be "unknown" if $SHELL not set in test)
+        assert!(!shell.is_empty());
+    }
+
+    #[test]
+    fn test_get_history_path_bash() {
+        if let Ok(home) = std::env::var("HOME") {
+            let path = get_history_path("bash");
+            assert!(path.is_some());
+            assert_eq!(path.unwrap(), PathBuf::from(home).join(".bash_history"));
+        }
+    }
+
+    #[test]
+    fn test_get_history_path_zsh() {
+        if let Ok(home) = std::env::var("HOME") {
+            let path = get_history_path("zsh");
+            assert!(path.is_some());
+            assert_eq!(path.unwrap(), PathBuf::from(home).join(".zsh_history"));
+        }
+    }
+
+    #[test]
+    fn test_get_history_path_fish() {
+        if let Ok(home) = std::env::var("HOME") {
+            let path = get_history_path("fish");
+            assert!(path.is_some());
+            let expected = PathBuf::from(home)
+                .join(".local")
+                .join("share")
+                .join("fish")
+                .join("fish_history");
+            assert_eq!(path.unwrap(), expected);
+        }
+    }
+
+    #[test]
+    fn test_get_history_path_unknown() {
+        let path = get_history_path("unknown_shell");
+        assert!(path.is_none());
+    }
+
+    #[test]
+    fn test_read_history_tail_small_file() {
+        // Create temp file with 5 lines
+        let mut temp_file = NamedTempFile::new().unwrap();
+        for i in 1..=5 {
+            writeln!(temp_file, "command_{}", i).unwrap();
+        }
+        temp_file.flush().unwrap();
+
+        let path = temp_file.path().to_path_buf();
+        let lines = read_history_tail(&path, 3);
+
+        // Should return last 3 lines
+        assert_eq!(lines.len(), 3);
+        assert_eq!(lines[0], "command_3");
+        assert_eq!(lines[1], "command_4");
+        assert_eq!(lines[2], "command_5");
+    }
+
+    #[test]
+    fn test_read_history_tail_large_file() {
+        // Create temp file with 20 lines (larger than 4096 bytes when written)
+        let mut temp_file = NamedTempFile::new().unwrap();
+        for i in 1..=20 {
+            writeln!(
+                temp_file,
+                "command_{}_with_some_additional_text_to_make_line_longer",
+                i
+            )
+            .unwrap();
+        }
+        temp_file.flush().unwrap();
+
+        let path = temp_file.path().to_path_buf();
+        let lines = read_history_tail(&path, 3);
+
+        // Should return last 3 lines
+        assert_eq!(lines.len(), 3);
+        assert!(lines[0].contains("command_18"));
+        assert!(lines[1].contains("command_19"));
+        assert!(lines[2].contains("command_20"));
+    }
+
+    #[test]
+    fn test_read_history_tail_missing_file() {
+        let path = PathBuf::from("/nonexistent/history/file");
+        let lines = read_history_tail(&path, 3);
+
+        // Should return empty vec for missing file
+        assert!(lines.is_empty());
+    }
+
+    #[test]
+    fn test_read_history_tail_empty_file() {
+        let temp_file = NamedTempFile::new().unwrap();
+        let path = temp_file.path().to_path_buf();
+        let lines = read_history_tail(&path, 3);
+
+        // Should return empty vec for empty file
+        assert!(lines.is_empty());
+    }
+
+    #[test]
+    fn test_get_shell_history() {
+        // This test depends on actual shell history file
+        // Just verify it doesn't panic and returns a vec
+        let history = get_shell_history(3);
+
+        // Should return a vec (may be empty if history file doesn't exist)
+        let _ = history;
+    }
+
+    #[test]
+    fn test_detect_shell_pure() {
+        // Pure function - same environment, same output
+        let shell1 = detect_shell();
+        let shell2 = detect_shell();
+
+        assert_eq!(shell1, shell2);
+    }
+}
diff --git a/src/context/mod.rs b/src/context/mod.rs
new file mode 100644
index 0000000..50b24e5
--- /dev/null
+++ b/src/context/mod.rs
@@ -0,0 +1,11 @@
+pub mod directory;
+pub mod gatherer;
+pub mod history;
+pub mod stdin;
+pub mod system;
+
+pub use directory::scan_directory;
+pub use gatherer::{gather_context, get_context_json, ContextData};
+pub use history::{detect_shell, get_history_path, get_shell_history, read_history_tail};
+pub use stdin::{is_stdin_piped, read_stdin, read_stdin_default};
+pub use system::{format_system_info, get_formatted_system_info, get_system_info, SystemInfo};
diff --git a/src/context/stdin.rs b/src/context/stdin.rs
new file mode 100644
index 0000000..26feeb7
--- /dev/null
+++ b/src/context/stdin.rs
@@ -0,0 +1,119 @@
+use std::io::{self, Read};
+
+/// Detect if stdin is piped (not a TTY)
+///
+/// Uses atty crate to check if stdin is a terminal.
+/// Returns true if stdin is piped (not a TTY), false otherwise.
+///
+/// Pure function - checks TTY status
+///
+/// # Returns
+/// * `bool` - True if stdin is piped, false if it's a TTY
+pub fn is_stdin_piped() -> bool {
+    !atty::is(atty::Stream::Stdin)
+}
+
+/// Read stdin with configurable byte limit
+///
+/// Reads all available input from stdin up to max_bytes.
+/// If input exceeds max_bytes, it's truncated.
+///
+/// Returns None if stdin is not piped (is a TTY) or if reading fails.
+/// Returns Some("") if stdin is piped but empty.
+/// Returns Some(content) with the read content (possibly truncated).
+///
+/// # Arguments
+/// * `max_bytes` - Maximum number of bytes to read (default: 10KB)
+///
+/// # Returns
+/// * `Option<String>` - None if not piped/error, Some(content) if piped
+pub fn read_stdin(max_bytes: usize) -> Option<String> {
+    // Check if stdin is piped
+    if !is_stdin_piped() {
+        return None;
+    }
+
+    // Read from stdin with limit
+    let mut buffer = vec![0u8; max_bytes];
+    let mut stdin = io::stdin();
+
+    match stdin.read(&mut buffer) {
+        Ok(0) => {
+            // Empty pipe
+            Some(String::new())
+        }
+        Ok(n) => {
+            // Read n bytes, truncate buffer
+            buffer.truncate(n);
+
+            // Convert to string, handling invalid UTF-8 gracefully
+            // Use from_utf8_lossy to handle invalid UTF-8 sequences
+            Some(String::from_utf8_lossy(&buffer).to_string())
+        }
+        Err(_) => {
+            // Error reading stdin
+            None
+        }
+    }
+}
+
+/// Read stdin with default limit (10KB)
+///
+/// Convenience function that calls read_stdin with default 10KB limit.
+///
+/// # Returns
+/// * `Option<String>` - None if not piped/error, Some(content) if piped
+pub fn read_stdin_default() -> Option<String> {
+    const DEFAULT_MAX_BYTES: usize = 10 * 1024; // 10KB
+    read_stdin(DEFAULT_MAX_BYTES)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_is_stdin_piped() {
+        // In test environment, stdin is typically not piped
+        // Just verify function doesn't panic
+        let _ = is_stdin_piped();
+    }
+
+    #[test]
+    fn test_read_stdin_not_piped() {
+        // When stdin is not piped (TTY), should return None
+        // In test environment, stdin is typically not piped
+        // This test verifies the function handles non-piped stdin correctly
+        let result = read_stdin(1024);
+        // May be None (if not piped) or Some (if somehow piped in test)
+        // Just verify it doesn't panic
+        let _ = result;
+    }
+
+    #[test]
+    fn test_read_stdin_empty() {
+        // Test with very small limit to verify empty handling
+        // Note: This test may not work as expected in test environment
+        // where stdin might not be piped
+        let result = read_stdin(1);
+        // Just verify it doesn't panic
+        let _ = result;
+    }
+
+    #[test]
+    fn test_read_stdin_default() {
+        // Test default limit function
+        let result = read_stdin_default();
+        // Just verify it doesn't panic
+        let _ = result;
+    }
+
+    #[test]
+    fn test_is_stdin_piped_pure() {
+        // Pure function - same environment, same output
+        let result1 = is_stdin_piped();
+        let result2 = is_stdin_piped();
+
+        assert_eq!(result1, result2);
+    }
+}
diff --git a/src/context/system.rs b/src/context/system.rs
new file mode 100644
index 0000000..e9a7e60
--- /dev/null
+++ b/src/context/system.rs
@@ -0,0 +1,190 @@
+use once_cell::sync::Lazy;
+use std::collections::HashMap;
+use std::sync::RwLock;
+use sysinfo::System;
+
+/// Cached system information structure
+/// Immutable snapshot of system info, cached per run
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct SystemInfo {
+    pub os_name: String,
+    pub os_version: String,
+    pub architecture: String,
+    pub shell: String,
+    pub user: String,
+    pub total_memory: u64,
+}
+
+/// Global cached system information
+/// Lazy-initialized, thread-safe cache
+static SYSTEM_INFO_CACHE: Lazy<RwLock<Option<SystemInfo>>> = Lazy::new(|| RwLock::new(None));
+
+/// Get system information (cached per run)
+///
+/// This function collects system information on first access and caches it.
+/// Subsequent calls return the cached information.
+///
+/// Pure function after first call - returns cached immutable data
+/// First call has I/O side effects (reading system info)
+///
+/// # Returns
+/// * `SystemInfo` - Immutable system information snapshot
+pub fn get_system_info() -> SystemInfo {
+    // Check cache
+    {
+        let cache = SYSTEM_INFO_CACHE.read().unwrap();
+        if let Some(ref info) = *cache {
+            return info.clone();
+        }
+    }
+
+    // Collect system information
+    let mut system = System::new();
+    system.refresh_all();
+
+    // Extract OS information
+    // sysinfo 0.37: name() and os_version() are associated functions (static methods)
+    let os_name = System::name().unwrap_or_else(|| "Unknown".to_string());
+    let os_version = System::os_version().unwrap_or_else(|| "Unknown".to_string());
+
+    // Get architecture
+    let architecture = std::env::consts::ARCH.to_string();
+
+    // Get shell from environment
+    let shell = std::env::var("SHELL")
+        .unwrap_or_else(|_| "unknown".to_string())
+        .split('/')
+        .next_back()
+        .unwrap_or("unknown")
+        .to_string();
+
+    // Get user from environment
+    let user = std::env::var("USER")
+        .or_else(|_| std::env::var("USERNAME"))
+        .unwrap_or_else(|_| "unknown".to_string());
+
+    // Get total memory
+    let total_memory = system.total_memory();
+
+    let info = SystemInfo {
+        os_name,
+        os_version,
+        architecture,
+        shell,
+        user,
+        total_memory,
+    };
+
+    // Cache the result
+    {
+        let mut cache = SYSTEM_INFO_CACHE.write().unwrap();
+        *cache = Some(info.clone());
+    }
+
+    info
+}
+
+/// Format system information as a structured map for prompt context
+///
+/// Pure function - takes immutable SystemInfo and returns formatted map
+/// No side effects
+///
+/// # Arguments
+/// * `info` - System information to format
+///
+/// # Returns
+/// * `HashMap<String, String>` - Formatted system information
+pub fn format_system_info(info: &SystemInfo) -> HashMap<String, String> {
+    let mut map = HashMap::new();
+
+    map.insert("os_name".to_string(), info.os_name.clone());
+    map.insert("os_version".to_string(), info.os_version.clone());
+    map.insert("architecture".to_string(), info.architecture.clone());
+    map.insert("shell".to_string(), info.shell.clone());
+    map.insert("user".to_string(), info.user.clone());
+    map.insert(
+        "total_memory_mb".to_string(),
+        format!("{}", info.total_memory / 1024 / 1024),
+    );
+
+    map
+}
+
+/// Get formatted system information (convenience function)
+///
+/// Combines get_system_info() and format_system_info()
+///
+/// # Returns
+/// * `HashMap<String, String>` - Formatted system information
+pub fn get_formatted_system_info() -> HashMap<String, String> {
+    let info = get_system_info();
+    format_system_info(&info)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_get_system_info_cached() {
+        // First call should collect info
+        let info1 = get_system_info();
+
+        // Second call should return cached info
+        let info2 = get_system_info();
+
+        // Should be equal (cached)
+        assert_eq!(info1, info2);
+    }
+
+    #[test]
+    fn test_format_system_info() {
+        let info = SystemInfo {
+            os_name: "Linux".to_string(),
+            os_version: "5.15.0".to_string(),
+            architecture: "x86_64".to_string(),
+            shell: "bash".to_string(),
+            user: "testuser".to_string(),
+            total_memory: 8 * 1024 * 1024 * 1024, // 8 GB
+        };
+
+        let formatted = format_system_info(&info);
+
+        assert_eq!(formatted.get("os_name"), Some(&"Linux".to_string()));
+        assert_eq!(formatted.get("os_version"), Some(&"5.15.0".to_string()));
+        assert_eq!(formatted.get("architecture"), Some(&"x86_64".to_string()));
+        assert_eq!(formatted.get("shell"), Some(&"bash".to_string()));
+        assert_eq!(formatted.get("user"), Some(&"testuser".to_string()));
+        assert_eq!(formatted.get("total_memory_mb"), Some(&"8192".to_string()));
+    }
+
+    #[test]
+    fn test_format_system_info_pure() {
+        let info = SystemInfo {
+            os_name: "Test".to_string(),
+            os_version: "1.0".to_string(),
+            architecture: "test".to_string(),
+            shell: "test".to_string(),
+            user: "test".to_string(),
+            total_memory: 1024,
+        };
+
+        // Pure function - same input, same output
+        let formatted1 = format_system_info(&info);
+        let formatted2 = format_system_info(&info);
+
+        assert_eq!(formatted1, formatted2);
+    }
+
+    #[test]
+    fn test_system_info_has_required_fields() {
+        let info = get_system_info();
+
+        // Verify all fields are populated (not empty)
+        assert!(!info.os_name.is_empty());
+        assert!(!info.architecture.is_empty());
+        // shell and user might be "unknown" but should not be empty
+        assert!(!info.shell.is_empty());
+        assert!(!info.user.is_empty());
+    }
+}
diff --git a/src/error/mod.rs b/src/error/mod.rs
new file mode 100644
index 0000000..a31f744
--- /dev/null
+++ b/src/error/mod.rs
@@ -0,0 +1,242 @@
+use crate::ai::providers::openrouter::get_file_logger;
+use thiserror::Error;
+
+/// Comprehensive error enum with specific exit codes per FR-7
+///
+/// Maps to exit codes:
+/// - General = 1 (unexpected errors)
+/// - Usage = 2 (invalid CLI arguments)
+/// - Config = 3 (configuration errors)
+/// - API = 4 (AI provider/network errors)
+/// - Safety = 5 (dangerous command rejected)
+#[derive(Debug, Error)]
+pub enum ClaiError {
+    /// General error (exit code 1)
+    /// Catch-all for unexpected errors
+    #[error("Error: {0}")]
+    General(#[from] anyhow::Error),
+
+    /// Usage error (exit code 2)
+    /// Invalid CLI arguments or missing required parameters
+    #[error("Usage error: {0}")]
+    Usage(String),
+
+    /// Configuration error (exit code 3)
+    /// Missing keys, invalid TOML, file permission issues
+    #[error("Configuration error: {source}")]
+    Config {
+        /// Source error from config loading
+        #[source]
+        source: anyhow::Error,
+    },
+
+    /// API error (exit code 4)
+    /// Network errors, authentication failures, rate limits
+    #[error("API error: {source}")]
+    API {
+        /// Source error from API provider
+        #[source]
+        source: anyhow::Error,
+        /// Optional HTTP status code for API errors
+        status_code: Option<u16>,
+    },
+
+    /// Safety error (exit code 5)
+    /// Dangerous command rejected by user or safety checks
+    #[error("Safety error: {0}")]
+    Safety(String),
+
+    /// Help or version display (exit code 0)
+    /// Used when --help or --version is requested
+    #[error("{0}")]
+    HelpOrVersion(String),
+}
+
+impl ClaiError {
+    /// Get the exit code for this error
+    ///
+    /// Returns the appropriate exit code per FR-7:
+    /// - General = 1
+    /// - Usage = 2
+    /// - Config = 3
+    /// - API = 4
+    /// - Safety = 5
+    pub fn exit_code(&self) -> u8 {
+        match self {
+            ClaiError::General(_) => 1,
+            ClaiError::Usage(_) => 2,
+            ClaiError::Config { .. } => 3,
+            ClaiError::API { .. } => 4,
+            ClaiError::Safety(_) => 5,
+            ClaiError::HelpOrVersion(_) => 0,
+        }
+    }
+
+    /// Print error to stderr with optional backtrace
+    ///
+    /// Respects verbosity level for backtrace display.
+    /// Always prints human-readable error message to stderr.
+    ///
+    /// # Arguments
+    /// * `verbose` - Verbosity level (0=normal, 1+=show backtrace)
+    pub fn print_stderr(&self, verbose: u8) {
+        // Always print the error message
+        eprintln!("{}", self);
+
+        // Show backtrace if verbose >= 1
+        if verbose >= 1 {
+            if let Some(backtrace) = self.backtrace() {
+                eprintln!("\nBacktrace:\n{}", backtrace);
+            }
+        }
+    }
+
+    /// Log error to file logger if enabled
+    ///
+    /// Writes structured error data to the debug log file.
+    pub fn log_to_file(&self) {
+        if let Some(logger) = get_file_logger() {
+            let (event, context) = match self {
+                ClaiError::General(e) => (
+                    "general_error",
+                    serde_json::json!({"message": e.to_string()}),
+                ),
+                ClaiError::Usage(msg) => ("usage_error", serde_json::json!({"message": msg})),
+                ClaiError::Config { source } => (
+                    "config_error",
+                    serde_json::json!({"message": source.to_string()}),
+                ),
+                ClaiError::API {
+                    source,
+                    status_code,
+                } => (
+                    "api_error",
+                    serde_json::json!({
+                        "message": source.to_string(),
+                        "status_code": status_code
+                    }),
+                ),
+                ClaiError::Safety(msg) => ("safety_error", serde_json::json!({"message": msg})),
+                ClaiError::HelpOrVersion(_) => return, // Don't log help/version as errors
+            };
+
+            logger.log_error(event, &self.to_string(), Some(context));
+        }
+    }
+
+    /// Get backtrace if available
+    ///
+    /// Extracts backtrace from anyhow error chain
+    fn backtrace(&self) -> Option<String> {
+        match self {
+            ClaiError::General(err)
+            | ClaiError::Config { source: err }
+            | ClaiError::API { source: err, .. } => {
+                // Try to get backtrace from anyhow error
+                let mut backtrace_str = String::new();
+                let mut current: &dyn std::error::Error = err.as_ref();
+
+                // Build error chain
+                backtrace_str.push_str(&format!("Error: {}\n", current));
+                while let Some(source) = current.source() {
+                    backtrace_str.push_str(&format!("Caused by: {}\n", source));
+                    current = source;
+                }
+
+                if !backtrace_str.is_empty() {
+                    Some(backtrace_str)
+                } else {
+                    None
+                }
+            }
+            _ => None,
+        }
+    }
+}
+
+/// Convert clap::Error to ClaiError
+///
+/// Special handling for help/version which should exit cleanly with code 0
+impl From<clap::Error> for ClaiError {
+    fn from(err: clap::Error) -> Self {
+        use clap::error::ErrorKind;
+
+        // Handle help and version specially - they should return HelpOrVersion variant
+        // The caller (main) is responsible for printing and exiting with code 0
+        match err.kind() {
+            ErrorKind::DisplayHelp | ErrorKind::DisplayVersion => {
+                ClaiError::HelpOrVersion(err.to_string())
+            }
+            _ => ClaiError::Usage(err.to_string()),
+        }
+    }
+}
+
+/// Convert ConfigLoadError to ClaiError::Config
+impl From<crate::config::loader::ConfigLoadError> for ClaiError {
+    fn from(err: crate::config::loader::ConfigLoadError) -> Self {
+        ClaiError::Config {
+            source: anyhow::Error::from(err),
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_exit_codes() {
+        assert_eq!(ClaiError::General(anyhow::anyhow!("test")).exit_code(), 1);
+        assert_eq!(ClaiError::Usage("test".to_string()).exit_code(), 2);
+        assert_eq!(
+            ClaiError::Config {
+                source: anyhow::anyhow!("test")
+            }
+            .exit_code(),
+            3
+        );
+        assert_eq!(
+            ClaiError::API {
+                source: anyhow::anyhow!("test"),
+                status_code: None
+            }
+            .exit_code(),
+            4
+        );
+        assert_eq!(ClaiError::Safety("test".to_string()).exit_code(), 5);
+        assert_eq!(
+            ClaiError::HelpOrVersion("help message".to_string()).exit_code(),
+            0
+        );
+    }
+
+    #[test]
+    fn test_error_display() {
+        let err = ClaiError::Usage("Missing required argument".to_string());
+        let display = format!("{}", err);
+        assert!(display.contains("Usage error"));
+        assert!(display.contains("Missing required argument"));
+    }
+
+    #[test]
+    fn test_clap_error_conversion() {
+        use clap::Parser;
+        // Try to parse with missing required argument
+        let cli = crate::cli::Cli::try_parse_from(["clai"]);
+        if let Err(clap_err) = cli {
+            let clai_err = ClaiError::from(clap_err);
+            assert_eq!(clai_err.exit_code(), 2);
+        } else {
+            panic!("Expected clap error for missing argument");
+        }
+    }
+
+    #[test]
+    fn test_config_error_conversion() {
+        use crate::config::loader::ConfigLoadError;
+        let config_err = ConfigLoadError::NotFound("/nonexistent".to_string());
+        let clai_err: ClaiError = config_err.into();
+        assert_eq!(clai_err.exit_code(), 3);
+    }
+}
diff --git a/src/lib.rs b/src/lib.rs
new file mode 100644
index 0000000..1adc5e1
--- /dev/null
+++ b/src/lib.rs
@@ -0,0 +1,32 @@
+//! clai - AI-Powered Shell Command Translator
+//!
+//! A shell-native AI command translator that converts natural language to
+//! executable commands. Follows Unix philosophy: simple, composable, privacy-respecting.
+
+pub mod ai;
+pub mod cli;
+pub mod color;
+pub mod config;
+pub mod context;
+pub mod error;
+pub mod locale;
+pub mod logging;
+pub mod output;
+pub mod safety;
+pub mod signals;
+
+// Re-export AI handler for convenience
+pub use ai::handler::generate_command;
+
+// Re-export commonly used types for convenience
+pub use cli::{parse_args, Cli};
+pub use color::{color_mode_from_config, detect_color_auto, ColorMode};
+pub use config::Config;
+pub use error::ClaiError;
+pub use locale::{get_language_code, get_locale, is_c_locale};
+pub use logging::{LogLevel, Logger};
+pub use output::{format_config_debug, format_output, print_command};
+pub use signals::{
+    is_interactive, is_piped, is_stderr_tty, is_stdin_tty, is_stdout_tty, setup_signal_handlers,
+    ExitCode,
+};
diff --git a/src/locale/mod.rs b/src/locale/mod.rs
new file mode 100644
index 0000000..fbf38db
--- /dev/null
+++ b/src/locale/mod.rs
@@ -0,0 +1,91 @@
+//! Locale detection and formatting utilities
+//!
+//! Provides locale-aware formatting for dates, numbers, and messages.
+//! Detects locale from LANG environment variable.
+
+/// Get the current locale from environment
+///
+/// Returns the locale string (e.g., "en_US.UTF-8", "C", "fr_FR")
+/// Defaults to "en_US" if LANG is not set.
+///
+/// Pure function - no side effects
+pub fn get_locale() -> String {
+    std::env::var("LANG").unwrap_or_else(|_| "en_US".to_string())
+}
+
+/// Get the locale language code (e.g., "en", "fr", "de")
+///
+/// Extracts the language part from locale string.
+/// Examples:
+/// - "en_US.UTF-8" -> "en"
+/// - "fr_FR" -> "fr"
+/// - "C" -> "C"
+///
+/// Pure function - no side effects
+pub fn get_language_code() -> String {
+    let locale = get_locale();
+
+    // Extract language code (first part before underscore or dot)
+    locale
+        .split('_')
+        .next()
+        .unwrap_or(&locale)
+        .split('.')
+        .next()
+        .unwrap_or(&locale)
+        .to_string()
+}
+
+/// Check if locale is set to C (POSIX locale)
+///
+/// The C locale typically means no locale-specific formatting.
+///
+/// Pure function - no side effects
+pub fn is_c_locale() -> bool {
+    let locale = get_locale();
+    locale == "C" || locale == "POSIX"
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_get_language_code() {
+        // Test various locale formats
+        std::env::set_var("LANG", "en_US.UTF-8");
+        assert_eq!(get_language_code(), "en");
+        std::env::remove_var("LANG");
+
+        std::env::set_var("LANG", "fr_FR");
+        assert_eq!(get_language_code(), "fr");
+        std::env::remove_var("LANG");
+
+        std::env::set_var("LANG", "C");
+        assert_eq!(get_language_code(), "C");
+        std::env::remove_var("LANG");
+    }
+
+    #[test]
+    fn test_is_c_locale() {
+        std::env::set_var("LANG", "C");
+        assert_eq!(is_c_locale(), true);
+        std::env::remove_var("LANG");
+
+        std::env::set_var("LANG", "POSIX");
+        assert_eq!(is_c_locale(), true);
+        std::env::remove_var("LANG");
+
+        std::env::set_var("LANG", "en_US.UTF-8");
+        assert_eq!(is_c_locale(), false);
+        std::env::remove_var("LANG");
+    }
+
+    #[test]
+    fn test_get_locale_default() {
+        // Remove LANG to test default
+        std::env::remove_var("LANG");
+        let locale = get_locale();
+        assert_eq!(locale, "en_US");
+    }
+}
diff --git a/src/logging/file_logger.rs b/src/logging/file_logger.rs
new file mode 100644
index 0000000..13eb521
--- /dev/null
+++ b/src/logging/file_logger.rs
@@ -0,0 +1,278 @@
+//! File-based debug logger for clai
+//!
+//! Provides opt-in file logging for debugging and troubleshooting.
+//! Writes structured JSON Lines format for easy parsing.
+
+use super::LogLevel;
+use anyhow::Result;
+use serde::Serialize;
+use std::fs::{File, OpenOptions};
+use std::io::{BufWriter, Write};
+use std::path::PathBuf;
+use std::sync::Mutex;
+use std::time::{SystemTime, UNIX_EPOCH};
+
+/// Maximum log file size before truncation (10 MB)
+const MAX_LOG_SIZE: u64 = 10 * 1024 * 1024;
+
+/// File-based debug logger
+///
+/// Writes structured JSON log entries to a file.
+/// Thread-safe via interior mutability with Mutex.
+pub struct FileLogger {
+    writer: Mutex<BufWriter<File>>,
+    path: PathBuf,
+}
+
+/// Log entry structure for JSON serialization
+#[derive(Debug, Serialize)]
+struct LogEntry<'a> {
+    ts: String,
+    level: &'a str,
+    event: &'a str,
+    #[serde(flatten)]
+    data: serde_json::Value,
+}
+
+impl FileLogger {
+    /// Create a new file logger
+    ///
+    /// Creates parent directories if needed.
+    /// Truncates file if it exceeds MAX_LOG_SIZE.
+    pub fn new(path: PathBuf) -> Result<Self> {
+        // Create parent directories
+        if let Some(parent) = path.parent() {
+            std::fs::create_dir_all(parent)?;
+        }
+
+        // Check file size and truncate if needed
+        if path.exists() {
+            let metadata = std::fs::metadata(&path)?;
+            if metadata.len() > MAX_LOG_SIZE {
+                // Truncate by removing and recreating
+                std::fs::remove_file(&path)?;
+            }
+        }
+
+        // Open file in append mode
+        let file = OpenOptions::new().create(true).append(true).open(&path)?;
+
+        let writer = BufWriter::new(file);
+
+        Ok(Self {
+            writer: Mutex::new(writer),
+            path,
+        })
+    }
+
+    /// Get the log file path
+    pub fn path(&self) -> &PathBuf {
+        &self.path
+    }
+
+    /// Log an event with structured data
+    pub fn log(&self, level: LogLevel, event: &str, data: serde_json::Value) {
+        let entry = LogEntry {
+            ts: iso8601_timestamp(),
+            level: level_str(level),
+            event,
+            data,
+        };
+
+        if let Ok(json) = serde_json::to_string(&entry) {
+            if let Ok(mut guard) = self.writer.lock() {
+                let _ = writeln!(guard, "{}", json);
+                let _ = guard.flush();
+            }
+        }
+    }
+
+    /// Log AI request with full message content
+    pub fn log_request(
+        &self,
+        model: Option<&str>,
+        messages: &[crate::ai::types::ChatMessage],
+        temperature: Option<f64>,
+        max_tokens: Option<u32>,
+    ) {
+        let messages_data: Vec<serde_json::Value> = messages
+            .iter()
+            .map(|m| {
+                serde_json::json!({
+                    "role": format!("{:?}", m.role).to_lowercase(),
+                    "content": m.content
+                })
+            })
+            .collect();
+
+        self.log(
+            LogLevel::Debug,
+            "ai_request",
+            serde_json::json!({
+                "model": model,
+                "messages": messages_data,
+                "temperature": temperature,
+                "max_tokens": max_tokens
+            }),
+        );
+    }
+
+    /// Log AI response
+    pub fn log_response(
+        &self,
+        model: Option<&str>,
+        status: u16,
+        content: &str,
+        usage: Option<&crate::ai::types::Usage>,
+    ) {
+        self.log(
+            LogLevel::Debug,
+            "ai_response",
+            serde_json::json!({
+                "model": model,
+                "status": status,
+                "content": content,
+                "usage": usage.map(|u| serde_json::json!({
+                    "prompt_tokens": u.prompt_tokens,
+                    "completion_tokens": u.completion_tokens,
+                    "total_tokens": u.total_tokens
+                }))
+            }),
+        );
+    }
+
+    /// Log error with context
+    pub fn log_error(&self, event: &str, error: &str, context: Option<serde_json::Value>) {
+        let mut data = serde_json::json!({
+            "error": error
+        });
+
+        if let Some(ctx) = context {
+            if let serde_json::Value::Object(ref mut map) = data {
+                if let serde_json::Value::Object(ctx_map) = ctx {
+                    map.extend(ctx_map);
+                }
+            }
+        }
+
+        self.log(LogLevel::Error, event, data);
+    }
+}
+
+/// Generate ISO 8601 timestamp without external dependencies
+fn iso8601_timestamp() -> String {
+    let duration = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default();
+
+    let total_secs = duration.as_secs();
+    let millis = duration.subsec_millis();
+
+    // Calculate date/time components (UTC)
+    let days_since_epoch = total_secs / 86400;
+    let secs_today = total_secs % 86400;
+
+    let hours = secs_today / 3600;
+    let minutes = (secs_today % 3600) / 60;
+    let seconds = secs_today % 60;
+
+    // Calculate year, month, day from days since 1970-01-01
+    let (year, month, day) = days_to_ymd(days_since_epoch);
+
+    format!(
+        "{:04}-{:02}-{:02}T{:02}:{:02}:{:02}.{:03}Z",
+        year, month, day, hours, minutes, seconds, millis
+    )
+}
+
+/// Convert days since Unix epoch to year, month, day
+fn days_to_ymd(days: u64) -> (i32, u32, u32) {
+    // Algorithm based on Howard Hinnant's date algorithms
+    let z = days as i64 + 719468;
+    let era = if z >= 0 { z } else { z - 146096 } / 146097;
+    let doe = (z - era * 146097) as u32;
+    let yoe = (doe - doe / 1460 + doe / 36524 - doe / 146096) / 365;
+    let y = yoe as i64 + era * 400;
+    let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
+    let mp = (5 * doy + 2) / 153;
+    let d = doy - (153 * mp + 2) / 5 + 1;
+    let m = if mp < 10 { mp + 3 } else { mp - 9 };
+    let y = if m <= 2 { y + 1 } else { y };
+
+    (y as i32, m, d)
+}
+
+/// Convert LogLevel to string for JSON output
+fn level_str(level: LogLevel) -> &'static str {
+    match level {
+        LogLevel::Error => "ERROR",
+        LogLevel::Warning => "WARN",
+        LogLevel::Info => "INFO",
+        LogLevel::Debug => "DEBUG",
+        LogLevel::Trace => "TRACE",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::tempdir;
+
+    #[test]
+    fn test_file_logger_creation() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("test.log");
+
+        let logger = FileLogger::new(path.clone()).unwrap();
+        logger.log(
+            LogLevel::Info,
+            "test_event",
+            serde_json::json!({"key": "value"}),
+        );
+
+        let contents = std::fs::read_to_string(&path).unwrap();
+        assert!(contents.contains("test_event"));
+        assert!(contents.contains("INFO"));
+        assert!(contents.contains("key"));
+        assert!(contents.contains("value"));
+    }
+
+    #[test]
+    fn test_iso8601_timestamp_format() {
+        let ts = iso8601_timestamp();
+        // Should match pattern: YYYY-MM-DDTHH:MM:SS.mmmZ
+        assert!(ts.ends_with('Z'));
+        assert!(ts.contains('T'));
+        assert_eq!(ts.len(), 24); // 2024-01-05T10:30:00.123Z
+    }
+
+    #[test]
+    fn test_log_error() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("error.log");
+
+        let logger = FileLogger::new(path.clone()).unwrap();
+        logger.log_error(
+            "test_error",
+            "Something went wrong",
+            Some(serde_json::json!({"status": 500})),
+        );
+
+        let contents = std::fs::read_to_string(&path).unwrap();
+        assert!(contents.contains("ERROR"));
+        assert!(contents.contains("test_error"));
+        assert!(contents.contains("Something went wrong"));
+        assert!(contents.contains("500"));
+    }
+
+    #[test]
+    fn test_creates_parent_directories() {
+        let dir = tempdir().unwrap();
+        let path = dir.path().join("nested").join("dir").join("test.log");
+
+        let logger = FileLogger::new(path.clone()).unwrap();
+        logger.log(LogLevel::Debug, "test", serde_json::json!({}));
+
+        assert!(path.exists());
+    }
+}
diff --git a/src/logging/mod.rs b/src/logging/mod.rs
new file mode 100644
index 0000000..b8e9db7
--- /dev/null
+++ b/src/logging/mod.rs
@@ -0,0 +1,190 @@
+use crate::color::{color_mode_from_config, ColorMode};
+use crate::config::Config;
+
+pub mod file_logger;
+pub use file_logger::FileLogger;
+
+/// Log level enumeration
+#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
+pub enum LogLevel {
+    /// Error messages only
+    Error,
+    /// Warning messages (default)
+    Warning,
+    /// Informational messages
+    Info,
+    /// Debug messages
+    Debug,
+    /// Trace messages (most verbose)
+    Trace,
+}
+
+impl LogLevel {
+    /// Get log level from verbosity count
+    /// Pure function - no side effects
+    pub fn from_verbose_count(count: u8) -> Self {
+        match count {
+            0 => LogLevel::Warning, // Default
+            1 => LogLevel::Info,
+            2 => LogLevel::Debug,
+            _ => LogLevel::Trace,
+        }
+    }
+
+    /// Get log level considering quiet flag
+    /// Pure function - no side effects
+    pub fn from_config(config: &Config) -> Self {
+        if config.quiet {
+            LogLevel::Error
+        } else {
+            Self::from_verbose_count(config.verbose)
+        }
+    }
+}
+
+/// Pure function to format log message
+/// Takes log level, message, and color mode, returns formatted string
+/// No side effects - pure function
+pub fn format_log(level: LogLevel, message: &str, color_mode: ColorMode) -> String {
+    let use_color = color_mode.should_use_color();
+
+    if use_color {
+        match level {
+            LogLevel::Error => format!("{} {}", colorize("ERROR", "red"), message),
+            LogLevel::Warning => format!("{} {}", colorize("WARN", "yellow"), message),
+            LogLevel::Info => format!("{} {}", colorize("INFO", "blue"), message),
+            LogLevel::Debug => format!("{} {}", colorize("DEBUG", "cyan"), message),
+            LogLevel::Trace => format!("{} {}", colorize("TRACE", "magenta"), message),
+        }
+    } else {
+        // No color - just prefix with level
+        match level {
+            LogLevel::Error => format!("ERROR: {}", message),
+            LogLevel::Warning => format!("WARN: {}", message),
+            LogLevel::Info => format!("INFO: {}", message),
+            LogLevel::Debug => format!("DEBUG: {}", message),
+            LogLevel::Trace => format!("TRACE: {}", message),
+        }
+    }
+}
+
+/// Pure function to colorize text (returns ANSI codes)
+/// No side effects - pure function
+fn colorize(text: &str, color: &str) -> String {
+    use owo_colors::OwoColorize;
+
+    match color {
+        "red" => text.red().to_string(),
+        "yellow" => text.yellow().to_string(),
+        "blue" => text.blue().to_string(),
+        "cyan" => text.cyan().to_string(),
+        "magenta" => text.magenta().to_string(),
+        _ => text.to_string(),
+    }
+}
+
+/// Logger struct for managing logging state
+#[derive(Debug, Clone)]
+pub struct Logger {
+    level: LogLevel,
+    color_mode: ColorMode,
+}
+
+impl Logger {
+    /// Create new Logger from Config
+    /// Pure function - no side effects
+    pub fn from_config(config: &Config) -> Self {
+        Self {
+            level: LogLevel::from_config(config),
+            color_mode: color_mode_from_config(config),
+        }
+    }
+
+    /// Check if a log level should be displayed
+    /// Pure function - no side effects
+    pub fn should_log(&self, level: LogLevel) -> bool {
+        level <= self.level
+    }
+
+    /// Format a log message (pure function)
+    /// No side effects - returns formatted string
+    pub fn format_message(&self, level: LogLevel, message: &str) -> String {
+        format_log(level, message, self.color_mode)
+    }
+
+    /// Log to stderr (side effect - but isolated)
+    /// This is the only function with side effects in this module
+    pub fn log(&self, level: LogLevel, message: &str) {
+        if self.should_log(level) {
+            eprintln!("{}", self.format_message(level, message));
+        }
+    }
+
+    /// Convenience methods
+    pub fn error(&self, message: &str) {
+        self.log(LogLevel::Error, message);
+    }
+
+    pub fn warn(&self, message: &str) {
+        self.log(LogLevel::Warning, message);
+    }
+
+    pub fn info(&self, message: &str) {
+        self.log(LogLevel::Info, message);
+    }
+
+    pub fn debug(&self, message: &str) {
+        self.log(LogLevel::Debug, message);
+    }
+
+    pub fn trace(&self, message: &str) {
+        self.log(LogLevel::Trace, message);
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_log_level_from_verbose_count() {
+        assert_eq!(LogLevel::from_verbose_count(0), LogLevel::Warning);
+        assert_eq!(LogLevel::from_verbose_count(1), LogLevel::Info);
+        assert_eq!(LogLevel::from_verbose_count(2), LogLevel::Debug);
+        assert_eq!(LogLevel::from_verbose_count(3), LogLevel::Trace);
+    }
+
+    #[test]
+    fn test_log_level_ordering() {
+        assert!(LogLevel::Error < LogLevel::Warning);
+        assert!(LogLevel::Warning < LogLevel::Info);
+        assert!(LogLevel::Info < LogLevel::Debug);
+        assert!(LogLevel::Debug < LogLevel::Trace);
+    }
+
+    #[test]
+    fn test_format_log_pure() {
+        let message = "test message";
+        let formatted1 = format_log(LogLevel::Error, message, ColorMode::Never);
+        let formatted2 = format_log(LogLevel::Error, message, ColorMode::Never);
+
+        // Pure function - same input, same output
+        assert_eq!(formatted1, formatted2);
+        assert!(formatted1.contains("ERROR"));
+        assert!(formatted1.contains(message));
+    }
+
+    #[test]
+    fn test_logger_should_log() {
+        let logger = Logger {
+            level: LogLevel::Info,
+            color_mode: ColorMode::Never,
+        };
+
+        assert!(logger.should_log(LogLevel::Error));
+        assert!(logger.should_log(LogLevel::Warning));
+        assert!(logger.should_log(LogLevel::Info));
+        assert!(!logger.should_log(LogLevel::Debug));
+        assert!(!logger.should_log(LogLevel::Trace));
+    }
+}
diff --git a/src/main.rs b/src/main.rs
new file mode 100644
index 0000000..cc3e2fe
--- /dev/null
+++ b/src/main.rs
@@ -0,0 +1,358 @@
+use clai::ai::handler::{generate_command, generate_commands};
+use clai::ai::providers::openrouter::init_file_logger;
+use clai::cli::parse_args;
+use clai::config::{get_file_config, Config};
+use clai::error::ClaiError;
+use clai::logging::{FileLogger, Logger};
+use clai::output::print_command;
+use clai::safety::{
+    execute_command, handle_dangerous_confirmation, is_dangerous_command, prompt_command_action,
+    should_prompt, CommandAction, Decision,
+};
+use clai::signals::{is_interactive, is_interrupted, setup_signal_handlers, ExitCode};
+use regex::Regex;
+use std::process;
+use std::sync::Arc;
+
+/// Main entry point - orchestrates pure function composition
+/// I/O side effects are isolated to this function
+/// Signal handling and exit codes follow UNIX conventions
+///
+/// Uses Result-based error handling with ClaiError for proper exit codes
+#[tokio::main]
+async fn main() {
+    // Setup signal handlers early (SIGINT, SIGTERM, SIGPIPE)
+    let interrupt_flag = setup_signal_handlers();
+
+    // Check for interruption before starting
+    if is_interrupted(&interrupt_flag) {
+        process::exit(ExitCode::Interrupted.as_i32());
+    }
+
+    // Function composition: parse_args() |> build_config() |> handle_cli()
+    let result = run_main(&interrupt_flag).await;
+
+    // Check for interruption before handling result
+    if is_interrupted(&interrupt_flag) {
+        process::exit(ExitCode::Interrupted.as_i32());
+    }
+
+    // Handle result and exit with appropriate code
+    match result {
+        Ok(()) => process::exit(ExitCode::Success.as_i32()),
+        Err(ClaiError::HelpOrVersion(msg)) => {
+            // Help/version requested - print to stdout and exit cleanly
+            print!("{}", msg);
+            process::exit(0);
+        }
+        Err(err) => {
+            // Log error to file if file logging is enabled
+            err.log_to_file();
+
+            // Get verbosity level from parsed CLI args
+            // Parse args again just to get verbosity (lightweight operation)
+            let verbose = parse_args().map(|cli| cli.verbose).unwrap_or(0);
+
+            // Print error to stderr with optional backtrace
+            err.print_stderr(verbose);
+            process::exit(err.exit_code() as i32);
+        }
+    }
+}
+
+/// Extract HTTP status code from error message
+///
+/// Looks for patterns like "(401)", "(429)", etc. in error messages
+/// Returns the status code if found, None otherwise
+fn extract_status_code(error_msg: &str) -> Option<u16> {
+    // Pattern: "(401)", "(429)", etc.
+    static STATUS_CODE_RE: once_cell::sync::Lazy<Regex> =
+        once_cell::sync::Lazy::new(|| Regex::new(r"\((\d{3})\)").unwrap());
+
+    STATUS_CODE_RE
+        .captures(error_msg)
+        .and_then(|caps| caps.get(1))
+        .and_then(|m| m.as_str().parse::<u16>().ok())
+}
+
+/// Core main logic with Result-based error handling
+///
+/// Returns Result<(), ClaiError> for proper error propagation
+async fn run_main(interrupt_flag: &Arc<std::sync::atomic::AtomicBool>) -> Result<(), ClaiError> {
+    // Parse CLI arguments - convert clap::Error to ClaiError::Usage
+    let cli = parse_args().map_err(ClaiError::from)?;
+
+    // Check for offline mode first
+    if cli.offline {
+        return Err(ClaiError::General(anyhow::anyhow!(
+            "Offline mode is not yet supported. Please remove --offline flag or configure a local provider (e.g., Ollama)."
+        )));
+    }
+
+    // Load file config (lazy-loaded, cached after first access)
+    // Missing config files are non-fatal (use defaults)
+    // Parse/permission errors are fatal (exit code 3)
+    let (file_config, was_config_missing) = match get_file_config(&cli) {
+        Ok(config) => (config, false),
+        Err(e) => {
+            // Check if it's a non-fatal error (file not found)
+            match &e {
+                clai::config::loader::ConfigLoadError::NotFound(_) => {
+                    // Missing config file is non-fatal - use defaults
+                    (clai::config::FileConfig::default(), true)
+                }
+                _ => {
+                    // Parse errors, permission errors, etc. are fatal
+                    // Convert to ClaiError::Config (exit code 3)
+                    return Err(ClaiError::from(e));
+                }
+            }
+        }
+    };
+
+    // Create runtime config from CLI (CLI flags take precedence over file config)
+    let config = Config::from_cli(cli);
+
+    // Initialize file logger if enabled
+    if let Some(ref log_path) = config.debug_log_file {
+        match FileLogger::new(log_path.clone()) {
+            Ok(logger) => {
+                init_file_logger(Arc::new(logger));
+                if config.verbose >= 1 {
+                    eprintln!("Debug logging enabled: {}", log_path.display());
+                }
+            }
+            Err(e) => {
+                // Non-fatal: warn but continue
+                eprintln!("Warning: Could not initialize debug log: {}", e);
+            }
+        }
+    }
+
+    // Log missing config file info if verbose
+    if was_config_missing && config.verbose >= 1 {
+        eprintln!("Info: No config file found, using defaults");
+    }
+
+    // Handle CLI logic - convert errors appropriately
+    handle_cli(config, file_config, interrupt_flag).await?;
+
+    Ok(())
+}
+
+/// Async function to handle CLI logic
+/// Takes immutable Config and returns Result<(), ClaiError>
+/// Side effects (I/O) are isolated to this function
+/// Strict stdout/stderr separation: stdout = commands only, stderr = logs/warnings
+/// Checks for signal interruption during execution
+/// Integrates safety checks for dangerous commands
+///
+/// Converts errors to appropriate ClaiError variants:
+/// - AI/API errors -> ClaiError::API
+/// - Safety rejections -> ClaiError::Safety
+/// - I/O errors -> ClaiError::General
+async fn handle_cli(
+    config: Config,
+    file_config: clai::config::FileConfig,
+    interrupt_flag: &Arc<std::sync::atomic::AtomicBool>,
+) -> Result<(), ClaiError> {
+    // Check for interruption before processing
+    if is_interrupted(interrupt_flag) {
+        return Err(ClaiError::General(anyhow::anyhow!("Interrupted by signal")));
+    }
+
+    // Create logger from config (handles verbosity and color detection)
+    let logger = Logger::from_config(&config);
+
+    // Debug output to stderr only (respects quiet/verbose flags)
+    if config.verbose >= 2 {
+        logger.debug(&format!("Parsed config: {:?}", config));
+    } else if config.verbose >= 1 {
+        logger.info(&format!("Parsed config: {:?}", config));
+    }
+
+    // Check for interruption after logging
+    if is_interrupted(interrupt_flag) {
+        return Err(ClaiError::General(anyhow::anyhow!("Interrupted by signal")));
+    }
+
+    // Generate commands using AI
+    // Use multi-command generation if num_options > 1 and interactive mode
+    let commands_result = if config.num_options > 1 && config.interactive {
+        generate_commands(&config).await
+    } else {
+        // Single command mode - wrap in vec for uniform handling
+        generate_command(&config).await.map(|cmd| vec![cmd])
+    };
+
+    // Generate commands - convert AI errors to ClaiError::API
+    // Extract HTTP status code from error message if available
+    let commands = commands_result.map_err(|e| {
+        let error_str = e.to_string();
+        let status_code = extract_status_code(&error_str);
+
+        ClaiError::API {
+            source: e.context("Failed to generate command from AI provider"),
+            status_code,
+        }
+    })?;
+
+    // Check for interruption before output
+    if is_interrupted(interrupt_flag) {
+        return Err(ClaiError::General(anyhow::anyhow!("Interrupted by signal")));
+    }
+
+    // Process commands
+    // Get first command for non-interactive modes
+    let first_command = commands.first().cloned().unwrap_or_default();
+
+    // Handle --dry-run flag: always print and exit (bypass safety checks)
+    if config.dry_run {
+        // Main output to stdout ONLY (clean for piping)
+        // For dry-run, output all commands (one per line)
+        // Use print_command for proper piped handling
+        for (i, cmd) in commands.iter().enumerate() {
+            if i > 0 {
+                // Add newline between commands when multiple
+                println!();
+            }
+            print_command(cmd).map_err(|e| {
+                ClaiError::General(
+                    anyhow::Error::from(e).context("Failed to write command to stdout"),
+                )
+            })?;
+        }
+        // Ensure final newline for dry-run (user-friendly)
+        if !commands.is_empty() {
+            println!();
+        }
+        return Ok(());
+    }
+
+    // Check if first command is dangerous (for safety flow)
+    let is_dangerous = is_dangerous_command(&first_command, &file_config);
+
+    // Check if we're in interactive mode (TTY + interactive flag)
+    let is_interactive_mode = config.interactive && is_interactive();
+
+    // Handle dangerous commands
+    if is_dangerous {
+        // Check if we should prompt (TTY + config enabled + not forced)
+        let should_prompt_user = should_prompt(
+            &clai::cli::Cli {
+                instruction: config.instruction.clone(),
+                model: config.model.clone(),
+                provider: config.provider.clone(),
+                quiet: config.quiet,
+                verbose: config.verbose,
+                no_color: config.no_color,
+                color: config.color,
+                interactive: config.interactive,
+                force: config.force,
+                dry_run: config.dry_run,
+                context: config.context.clone(),
+                offline: config.offline,
+                num_options: config.num_options,
+                debug: config.debug,
+                debug_file: config
+                    .debug_log_file
+                    .as_ref()
+                    .map(|p| p.to_string_lossy().to_string()),
+            },
+            &file_config,
+        );
+
+        if should_prompt_user {
+            // Prompt user for confirmation (dangerous command)
+            // Use first command for dangerous prompt (safety takes priority)
+            match handle_dangerous_confirmation(&first_command, &config) {
+                Ok(Decision::Execute) => {
+                    // User chose to execute - print to stdout
+                    print_command(&first_command).map_err(|e| {
+                        ClaiError::General(
+                            anyhow::Error::from(e).context("Failed to write command to stdout"),
+                        )
+                    })?;
+                    Ok(())
+                }
+                Ok(Decision::Copy) => {
+                    // User chose to copy - print to stdout (clipboard support can be added later)
+                    print_command(&first_command).map_err(|e| {
+                        ClaiError::General(
+                            anyhow::Error::from(e).context("Failed to write command to stdout"),
+                        )
+                    })?;
+                    Ok(())
+                }
+                Ok(Decision::Abort) => {
+                    // User chose to abort - return Safety error
+                    Err(ClaiError::Safety("Command rejected by user".to_string()))
+                }
+                Err(e) => {
+                    // Error during confirmation (e.g., EOF) - default to abort
+                    Err(ClaiError::Safety(format!(
+                        "Error during confirmation: {}. Command rejected.",
+                        e
+                    )))
+                }
+            }
+        } else {
+            // Not prompting (piped, force, or config disabled) - print to stdout
+            // Following UNIX philosophy: when piped, output goes to stdout
+            print_command(&first_command).map_err(|e| {
+                ClaiError::General(
+                    anyhow::Error::from(e).context("Failed to write command to stdout"),
+                )
+            })?;
+            Ok(())
+        }
+    } else if is_interactive_mode {
+        // Safe command(s) in interactive mode - prompt for action with Tab cycling
+        match prompt_command_action(&commands, &config) {
+            Ok((CommandAction::Execute, selected_command)) => {
+                // User pressed Enter - execute the selected command
+                let exit_code = execute_command(&selected_command).map_err(|e| {
+                    ClaiError::General(anyhow::Error::msg(e).context("Failed to execute command"))
+                })?;
+
+                if exit_code == 0 {
+                    Ok(())
+                } else {
+                    Err(ClaiError::General(anyhow::anyhow!(
+                        "Command exited with code {}",
+                        exit_code
+                    )))
+                }
+            }
+            Ok((CommandAction::Output, selected_command)) => {
+                // User chose to output - print to stdout (they can edit/run manually)
+                print_command(&selected_command).map_err(|e| {
+                    ClaiError::General(
+                        anyhow::Error::from(e).context("Failed to write command to stdout"),
+                    )
+                })?;
+                Ok(())
+            }
+            Ok((CommandAction::Abort, _)) => {
+                // User chose to abort (Ctrl+C or Esc)
+                Err(ClaiError::Safety("Command rejected by user".to_string()))
+            }
+            Err(e) => {
+                // Error during prompt (e.g., not TTY) - default to output first
+                eprintln!("Warning: {}. Outputting command.", e);
+                print_command(&first_command).map_err(|e| {
+                    ClaiError::General(
+                        anyhow::Error::from(e).context("Failed to write command to stdout"),
+                    )
+                })?;
+                Ok(())
+            }
+        }
+    } else {
+        // Command is safe and not interactive - print first command to stdout
+        print_command(&first_command).map_err(|e| {
+            ClaiError::General(anyhow::Error::from(e).context("Failed to write command to stdout"))
+        })?;
+        Ok(())
+    }
+}
diff --git a/src/output/mod.rs b/src/output/mod.rs
new file mode 100644
index 0000000..fb96648
--- /dev/null
+++ b/src/output/mod.rs
@@ -0,0 +1,108 @@
+use crate::config::Config;
+use crate::signals::is_stdout_tty;
+use std::io::{self, Write};
+
+/// Pure function to format output message
+/// Takes immutable Config and returns formatted string
+/// No side effects - pure function
+pub fn format_output(config: &Config) -> String {
+    format!("Command would be generated for: {}", config.instruction)
+}
+
+/// Print command to stdout with proper piped handling
+///
+/// If stdout is piped (not a TTY), prints without trailing newline.
+/// If stdout is a TTY, prints with trailing newline.
+///
+/// This follows UNIX philosophy: piped output should be clean for further processing.
+///
+/// # Arguments
+/// * `command` - The command string to print
+///
+/// # Side Effects
+/// * Writes to stdout (this is the only function with side effects in this module)
+pub fn print_command(command: &str) -> io::Result<()> {
+    let is_piped = !is_stdout_tty();
+
+    if is_piped {
+        // Piped output: no newline (clean for further processing)
+        print!("{}", command.trim());
+        io::stdout().flush()
+    } else {
+        // TTY output: with newline (user-friendly)
+        println!("{}", command.trim());
+        Ok(())
+    }
+}
+
+/// Pure function to format debug/config output
+/// Returns formatted string representation of config
+/// No side effects - pure function
+pub fn format_config_debug(config: &Config) -> String {
+    format!("Parsed config: {:?}", config)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_format_output_pure() {
+        let config = Config {
+            instruction: "test instruction".to_string(),
+            model: None,
+            provider: None,
+            quiet: false,
+            verbose: 0,
+            no_color: false,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_log_file: None,
+        };
+
+        let output = format_output(&config);
+        assert_eq!(output, "Command would be generated for: test instruction");
+
+        // Verify pure function - same input, same output
+        let output2 = format_output(&config);
+        assert_eq!(output, output2);
+    }
+
+    #[test]
+    fn test_format_config_debug_pure() {
+        let config = Config {
+            instruction: "debug test".to_string(),
+            model: Some("model".to_string()),
+            provider: None,
+            quiet: true,
+            verbose: 1,
+            no_color: true,
+            color: crate::cli::ColorChoice::Auto,
+            interactive: false,
+            force: false,
+            dry_run: false,
+            context: None,
+            offline: false,
+            num_options: 3,
+            debug: false,
+            debug_log_file: None,
+        };
+
+        let debug = format_config_debug(&config);
+        assert!(debug.contains("debug test"));
+        assert!(debug.contains("model"));
+
+        // Verify pure function - same input, same output
+        let debug2 = format_config_debug(&config);
+        assert_eq!(debug, debug2);
+    }
+
+    // Note: print_command tests would require mocking stdout/TTY state
+    // which is complex. Integration tests are better suited for this.
+}
diff --git a/src/safety/confirmation.rs b/src/safety/confirmation.rs
new file mode 100644
index 0000000..8e8cea0
--- /dev/null
+++ b/src/safety/confirmation.rs
@@ -0,0 +1,208 @@
+use crate::config::Config;
+use crate::signals::is_stderr_tty;
+use owo_colors::OwoColorize;
+use std::io::{self, Write};
+
+/// User decision for dangerous command handling
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum Decision {
+    /// Execute the command
+    Execute,
+    /// Copy the command to clipboard (or just output it)
+    Copy,
+    /// Abort and don't execute
+    Abort,
+}
+
+/// Error types for confirmation handling
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ConfirmationError {
+    /// EOF or pipe closed (stdin not available)
+    Eof,
+    /// Invalid input (not E, C, or A)
+    InvalidInput(String),
+    /// I/O error reading from stdin
+    IoError(String),
+}
+
+impl std::fmt::Display for ConfirmationError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            ConfirmationError::Eof => write!(f, "EOF: stdin closed or piped"),
+            ConfirmationError::InvalidInput(input) => {
+                write!(f, "Invalid input: '{}'. Expected E, C, or A", input.trim())
+            }
+            ConfirmationError::IoError(msg) => write!(f, "I/O error: {}", msg),
+        }
+    }
+}
+
+impl std::error::Error for ConfirmationError {}
+
+/// Handle dangerous command confirmation prompt
+///
+/// Displays a colored warning on stderr and prompts the user for confirmation.
+/// Returns the user's decision: Execute, Copy, or Abort.
+///
+/// # Arguments
+/// * `command` - The dangerous command that was detected
+/// * `config` - Runtime configuration (for color settings)
+///
+/// # Returns
+/// * `Result<Decision, ConfirmationError>` - User's decision or error
+///
+/// # Behavior
+/// - Prints warning to stderr (not stdout, following UNIX philosophy)
+/// - Prompts: `[E]xecute/[C]opy/[A]bort?`
+/// - Reads single character (case-insensitive)
+/// - Handles EOF/pipe gracefully (returns Abort)
+/// - Respects color settings from config
+///
+/// # Examples
+/// ```no_run
+/// use clai::safety::confirmation::{handle_dangerous_confirmation, Decision};
+/// use clai::config::Config;
+/// use clai::cli::{Cli, ColorChoice};
+///
+/// // Config is constructed from CLI arguments
+/// let cli = Cli {
+///     instruction: "delete temp files".to_string(),
+///     model: None,
+///     provider: None,
+///     quiet: false,
+///     verbose: 0,
+///     no_color: false,
+///     color: ColorChoice::Auto,
+///     interactive: true,
+///     force: false,
+///     dry_run: false,
+///     context: None,
+///     offline: false,
+///     num_options: 3,
+///     debug: false,
+///     debug_file: None,
+/// };
+/// let config = Config::from_cli(cli);
+///
+/// match handle_dangerous_confirmation("rm -rf /tmp/*", &config) {
+///     Ok(Decision::Execute) => println!("Executing..."),
+///     Ok(Decision::Copy) => println!("Copying..."),
+///     Ok(Decision::Abort) => println!("Aborted"),
+///     Err(e) => eprintln!("Error: {}", e),
+/// }
+/// ```
+pub fn handle_dangerous_confirmation(
+    command: &str,
+    config: &Config,
+) -> Result<Decision, ConfirmationError> {
+    // Check if stderr is a TTY (for colored output)
+    let use_color = !config.no_color && is_stderr_tty();
+
+    // Print warning to stderr (not stdout - following UNIX philosophy)
+    let warning_text = format!("⚠️  DANGEROUS: {}", command);
+    if use_color {
+        eprintln!("{}", warning_text.yellow().bold());
+    } else {
+        eprintln!("{}", warning_text);
+    }
+
+    // Print prompt to stderr
+    let prompt = "[E]xecute/[C]opy/[A]bort? ";
+    eprint!("{}", prompt);
+
+    // Flush stderr to ensure prompt is visible
+    if let Err(e) = io::stderr().flush() {
+        return Err(ConfirmationError::IoError(format!(
+            "Failed to flush stderr: {}",
+            e
+        )));
+    }
+
+    // Read user input from stdin
+    let mut input = String::new();
+    match io::stdin().read_line(&mut input) {
+        Ok(0) => {
+            // EOF - stdin closed or piped
+            // Return Abort as safe default
+            eprintln!(); // Newline for clean output
+            Ok(Decision::Abort)
+        }
+        Ok(_) => {
+            // Parse input (trim whitespace, take first character, case-insensitive)
+            let trimmed = input.trim();
+            if trimmed.is_empty() {
+                // Empty input - default to Abort
+                Ok(Decision::Abort)
+            } else {
+                match trimmed
+                    .chars()
+                    .next()
+                    .unwrap()
+                    .to_uppercase()
+                    .next()
+                    .unwrap()
+                {
+                    'E' => Ok(Decision::Execute),
+                    'C' => Ok(Decision::Copy),
+                    'A' => Ok(Decision::Abort),
+                    _ => Err(ConfirmationError::InvalidInput(input.trim().to_string())),
+                }
+            }
+        }
+        Err(e) => {
+            // I/O error reading stdin
+            Err(ConfirmationError::IoError(format!(
+                "Failed to read from stdin: {}",
+                e
+            )))
+        }
+    }
+}
+
+/// Format decision as string for display
+///
+/// Pure function for converting Decision to string representation.
+///
+/// # Arguments
+/// * `decision` - The decision to format
+///
+/// # Returns
+/// * `&'static str` - String representation
+pub fn format_decision(decision: Decision) -> &'static str {
+    match decision {
+        Decision::Execute => "Execute",
+        Decision::Copy => "Copy",
+        Decision::Abort => "Abort",
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_format_decision() {
+        assert_eq!(format_decision(Decision::Execute), "Execute");
+        assert_eq!(format_decision(Decision::Copy), "Copy");
+        assert_eq!(format_decision(Decision::Abort), "Abort");
+    }
+
+    #[test]
+    fn test_confirmation_error_display() {
+        let eof = ConfirmationError::Eof;
+        assert!(eof.to_string().contains("EOF"));
+
+        let invalid = ConfirmationError::InvalidInput("X".to_string());
+        assert!(invalid.to_string().contains("Invalid input"));
+        assert!(invalid.to_string().contains("X"));
+
+        let io_err = ConfirmationError::IoError("test error".to_string());
+        assert!(io_err.to_string().contains("I/O error"));
+        assert!(io_err.to_string().contains("test error"));
+    }
+
+    // Note: Integration tests for handle_dangerous_confirmation would require
+    // mocking stdin, which is complex. These are better suited for manual testing
+    // or using a testing framework that can mock stdin/stdout/stderr.
+    // The function is tested manually during development.
+}
diff --git a/src/safety/detector.rs b/src/safety/detector.rs
new file mode 100644
index 0000000..7945d33
--- /dev/null
+++ b/src/safety/detector.rs
@@ -0,0 +1,229 @@
+use crate::config::file::FileConfig;
+use crate::safety::patterns::get_dangerous_regexes;
+use regex::Regex;
+
+/// Check if a command matches any dangerous pattern
+///
+/// Pure function - no side effects, thread-safe.
+/// Checks the command against all compiled dangerous regex patterns.
+///
+/// # Arguments
+/// * `command` - The command string to check
+/// * `config` - File configuration containing dangerous patterns
+///
+/// # Returns
+/// * `bool` - `true` if command matches any dangerous pattern, `false` otherwise
+///
+/// # Examples
+/// ```
+/// use clai::config::file::FileConfig;
+/// use clai::safety::detector::is_dangerous_command;
+///
+/// let config = FileConfig::default();
+/// assert!(is_dangerous_command("rm -rf /", &config));
+/// assert!(!is_dangerous_command("ls -la", &config));
+/// ```
+pub fn is_dangerous_command(command: &str, config: &FileConfig) -> bool {
+    // Get compiled regexes (lazy-initialized, cached)
+    let regexes = match get_dangerous_regexes(config) {
+        Ok(regexes) => regexes,
+        Err(_) => {
+            // If regex compilation failed, fail safe - don't allow command
+            // This is a safety measure: if we can't check, we should be cautious
+            return true;
+        }
+    };
+
+    // Check if command matches any pattern
+    regexes.iter().any(|regex| regex.is_match(command))
+}
+
+/// Check if a command matches any dangerous pattern (with explicit regexes)
+///
+/// Lower-level function that takes pre-compiled regexes directly.
+/// Useful for testing or when you already have compiled regexes.
+///
+/// # Arguments
+/// * `command` - The command string to check
+/// * `regexes` - Slice of compiled regex patterns
+///
+/// # Returns
+/// * `bool` - `true` if command matches any pattern, `false` otherwise
+///
+/// # Examples
+/// ```
+/// use regex::Regex;
+/// use clai::safety::detector::is_dangerous_command_with_regexes;
+///
+/// let regexes = vec![
+///     Regex::new(r"rm\s+-rf\s+/").unwrap(),
+/// ];
+/// assert!(is_dangerous_command_with_regexes("rm -rf /", &regexes));
+/// assert!(!is_dangerous_command_with_regexes("ls -la", &regexes));
+/// ```
+pub fn is_dangerous_command_with_regexes(command: &str, regexes: &[Regex]) -> bool {
+    regexes.iter().any(|regex| regex.is_match(command))
+}
+
+/// Get the first matching dangerous pattern (for logging/debugging)
+///
+/// Returns the index and pattern string of the first matching regex.
+/// Useful for verbose logging to show which pattern matched.
+///
+/// # Arguments
+/// * `command` - The command string to check
+/// * `config` - File configuration containing dangerous patterns
+///
+/// # Returns
+/// * `Option<(usize, String)>` - Index and pattern string if match found, `None` otherwise
+pub fn get_matching_pattern(command: &str, config: &FileConfig) -> Option<(usize, String)> {
+    let regexes = get_dangerous_regexes(config).ok()?;
+
+    for (index, regex) in regexes.iter().enumerate() {
+        if regex.is_match(command) {
+            // Get the original pattern from config (for display)
+            let pattern = config
+                .safety
+                .dangerous_patterns
+                .get(index)
+                .cloned()
+                .unwrap_or_else(|| format!("pattern_{}", index));
+            return Some((index, pattern));
+        }
+    }
+
+    None
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::file::FileConfig;
+    use crate::safety::patterns::compile_dangerous_regexes;
+    use regex::Regex;
+
+    // Helper to check if command is dangerous using freshly compiled regexes
+    // (avoids OnceLock cache issues in tests)
+    fn is_dangerous_fresh(command: &str, config: &FileConfig) -> bool {
+        let regexes = compile_dangerous_regexes(config).unwrap();
+        is_dangerous_command_with_regexes(command, &regexes)
+    }
+
+    #[test]
+    fn test_safe_commands_return_false() {
+        let config = FileConfig::default();
+
+        assert!(!is_dangerous_fresh("ls -la", &config));
+        assert!(!is_dangerous_fresh("cd /tmp", &config));
+        assert!(!is_dangerous_fresh("echo hello", &config));
+        assert!(!is_dangerous_fresh("git status", &config));
+        assert!(!is_dangerous_fresh("cargo build", &config));
+    }
+
+    #[test]
+    fn test_dangerous_commands_return_true() {
+        let config = FileConfig::default();
+
+        assert!(is_dangerous_fresh("rm -rf /", &config));
+        assert!(is_dangerous_fresh("sudo rm -rf /", &config));
+        assert!(is_dangerous_fresh("dd if=/dev/zero of=/dev/sda", &config));
+    }
+
+    #[test]
+    fn test_empty_command_returns_false() {
+        let config = FileConfig::default();
+
+        assert!(!is_dangerous_fresh("", &config));
+        assert!(!is_dangerous_fresh("   ", &config));
+    }
+
+    #[test]
+    fn test_is_dangerous_command_with_regexes() {
+        let regexes = vec![
+            Regex::new(r"rm\s+-rf").unwrap(),
+            Regex::new(r"dd\s+if=").unwrap(),
+        ];
+
+        assert!(is_dangerous_command_with_regexes("rm -rf /", &regexes));
+        assert!(is_dangerous_command_with_regexes(
+            "dd if=/dev/zero",
+            &regexes
+        ));
+        assert!(!is_dangerous_command_with_regexes("ls -la", &regexes));
+    }
+
+    #[test]
+    fn test_get_matching_pattern() {
+        // Test get_matching_pattern with default config
+        let config = FileConfig::default();
+
+        // Test rm -rf / matches and returns pattern info
+        let result = get_matching_pattern("rm -rf /", &config);
+        assert!(result.is_some());
+        let (index, _pattern) = result.unwrap();
+        // Verify we got a valid match (index >= 0)
+        assert!(index < config.safety.dangerous_patterns.len());
+
+        // Test dd if= matches
+        let result = get_matching_pattern("dd if=/dev/zero of=/dev/sda", &config);
+        assert!(result.is_some());
+
+        // Test safe command returns None
+        let result = get_matching_pattern("ls -la", &config);
+        assert!(result.is_none());
+    }
+
+    #[test]
+    fn test_regex_matching_indices() {
+        // Test that regex matching returns correct indices
+        let regexes = vec![
+            Regex::new(r"rm\s+-rf").unwrap(),
+            Regex::new(r"dd\s+if=").unwrap(),
+        ];
+
+        // Test rm -rf matches first pattern (index 0)
+        let matched = regexes
+            .iter()
+            .enumerate()
+            .find(|(_, r)| r.is_match("rm -rf /"));
+        assert!(matched.is_some());
+        assert_eq!(matched.unwrap().0, 0);
+
+        // Test dd if= matches second pattern (index 1)
+        let matched = regexes
+            .iter()
+            .enumerate()
+            .find(|(_, r)| r.is_match("dd if=/dev/zero"));
+        assert!(matched.is_some());
+        assert_eq!(matched.unwrap().0, 1);
+    }
+
+    #[test]
+    fn test_compile_dangerous_regexes_no_match() {
+        // Verify that compiled regexes correctly identify safe commands
+        let config = FileConfig::default();
+        let regexes = compile_dangerous_regexes(&config).unwrap();
+
+        // Safe command should not match any pattern
+        let matched = regexes.iter().any(|r| r.is_match("ls -la"));
+        assert!(!matched);
+    }
+
+    #[test]
+    fn test_whitespace_handling() {
+        // Use explicit regex that handles leading/trailing whitespace
+        let regexes = vec![Regex::new(r"rm\s+-rf\s+/").unwrap()];
+
+        // Standard spacing works
+        assert!(is_dangerous_command_with_regexes("rm -rf /", &regexes));
+
+        // Multiple spaces between args works (because \s+ matches multiple)
+        assert!(is_dangerous_command_with_regexes("rm   -rf   /", &regexes));
+
+        // Note: Leading whitespace requires trimming or pattern adjustment
+        // The pattern "rm\s+-rf\s+/" doesn't match "  rm -rf /" because
+        // the pattern expects to start with "rm", not whitespace
+        let trimmed = "  rm -rf /  ".trim();
+        assert!(is_dangerous_command_with_regexes(trimmed, &regexes));
+    }
+}
diff --git a/src/safety/interactive.rs b/src/safety/interactive.rs
new file mode 100644
index 0000000..91214f6
--- /dev/null
+++ b/src/safety/interactive.rs
@@ -0,0 +1,301 @@
+use crate::config::Config;
+use crate::signals::is_stderr_tty;
+use crossterm::cursor::{MoveToColumn, MoveUp};
+use crossterm::event::{self, Event, KeyCode, KeyEvent, KeyEventKind};
+use crossterm::terminal::{disable_raw_mode, enable_raw_mode, Clear, ClearType};
+use crossterm::ExecutableCommand;
+use owo_colors::OwoColorize;
+use std::io::{self, Write};
+
+/// User action for command handling
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum CommandAction {
+    /// Execute the command directly
+    Execute,
+    /// Output the command (for user to edit/run manually)
+    Output,
+    /// Abort and don't do anything
+    Abort,
+}
+
+/// Error types for interactive command handling
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum InteractiveError {
+    /// EOF or pipe closed (stdin not available)
+    Eof,
+    /// I/O error reading from terminal
+    IoError(String),
+    /// Terminal not available (not a TTY)
+    NotTty,
+    /// No commands provided
+    NoCommands,
+}
+
+impl std::fmt::Display for InteractiveError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        match self {
+            InteractiveError::Eof => write!(f, "EOF: stdin closed or piped"),
+            InteractiveError::IoError(msg) => write!(f, "I/O error: {}", msg),
+            InteractiveError::NotTty => {
+                write!(f, "Not a TTY: interactive mode requires a terminal")
+            }
+            InteractiveError::NoCommands => write!(f, "No commands provided"),
+        }
+    }
+}
+
+impl std::error::Error for InteractiveError {}
+
+/// Prompt user to select from command options with Tab cycling
+///
+/// Shows the generated command(s) and prompts for action:
+/// - Tab: Cycle to next command option (inline replacement)
+/// - Enter: Execute the currently selected command
+/// - Ctrl+C or Esc: Abort
+///
+/// Uses crossterm for raw mode terminal input to read single keypresses.
+///
+/// # Arguments
+/// * `commands` - Slice of command options (at least one required)
+/// * `config` - Runtime configuration (for color settings)
+///
+/// # Returns
+/// * `Result<(CommandAction, String), InteractiveError>` - User's action and selected command
+///
+/// # Behavior
+/// - Prints command to stderr (not stdout, following UNIX philosophy)
+/// - Tab cycles through options, replacing the command inline
+/// - Shows indicator `[1/3]` when multiple options exist
+/// - Enter executes the currently selected command
+/// - Handles EOF/pipe gracefully (returns Output with first command)
+/// - Respects color settings from config
+///
+/// # Examples
+/// ```ignore
+/// use clai::safety::interactive::{prompt_command_action, CommandAction};
+/// use clai::config::Config;
+///
+/// let commands = vec!["ls -la".to_string(), "ls -lah".to_string()];
+/// match prompt_command_action(&commands, &config) {
+///     Ok((CommandAction::Execute, cmd)) => println!("Executing: {}", cmd),
+///     Ok((CommandAction::Output, cmd)) => println!("{}", cmd),
+///     Ok((CommandAction::Abort, _)) => println!("Aborted"),
+///     Err(e) => eprintln!("Error: {}", e),
+/// }
+/// ```
+pub fn prompt_command_action(
+    commands: &[String],
+    config: &Config,
+) -> Result<(CommandAction, String), InteractiveError> {
+    // Validate input
+    if commands.is_empty() {
+        return Err(InteractiveError::NoCommands);
+    }
+
+    // Check if stderr is a TTY (required for interactive mode)
+    if !is_stderr_tty() {
+        // Not a TTY - default to output first command (safe for piping)
+        return Ok((CommandAction::Output, commands[0].clone()));
+    }
+
+    let use_color = !config.no_color;
+    let total = commands.len();
+    let mut selected_index: usize = 0;
+
+    // Get stderr for crossterm commands
+    let mut stderr = io::stderr();
+
+    // Build the prompt text (used for redraw)
+    let prompt = if total > 1 {
+        "Press Tab to cycle, Enter to execute, or Ctrl+C to cancel: "
+    } else {
+        "Press Enter to execute, or Ctrl+C to cancel: "
+    };
+
+    // Helper to format command text
+    let format_command = |cmd: &str, idx: usize| -> String {
+        if total > 1 {
+            format!("Command [{}/{}]: {}", idx + 1, total, cmd)
+        } else {
+            format!("Command: {}", cmd)
+        }
+    };
+
+    // Display initial command and prompt
+    let initial_text = format_command(&commands[selected_index], selected_index);
+    if use_color {
+        eprintln!("{}", initial_text.cyan());
+    } else {
+        eprintln!("{}", initial_text);
+    }
+    eprint!("{}", prompt);
+    stderr
+        .flush()
+        .map_err(|e| InteractiveError::IoError(format!("Failed to flush: {}", e)))?;
+
+    // Enable raw mode to read single keypresses
+    enable_raw_mode()
+        .map_err(|e| InteractiveError::IoError(format!("Failed to enable raw mode: {}", e)))?;
+
+    // Read keypresses in a loop
+    let result = loop {
+        match event::read() {
+            Ok(Event::Key(KeyEvent {
+                code,
+                modifiers,
+                kind: KeyEventKind::Press,
+                ..
+            })) => {
+                // Check for Ctrl+C first
+                if modifiers.contains(crossterm::event::KeyModifiers::CONTROL)
+                    && code == KeyCode::Char('c')
+                {
+                    break Ok((CommandAction::Abort, String::new()));
+                }
+
+                // Handle other keys
+                match code {
+                    KeyCode::Tab => {
+                        // Cycle to next command
+                        selected_index = (selected_index + 1) % total;
+
+                        // Use crossterm commands to update display:
+                        // 1. Move up one line (to the command line)
+                        // 2. Move to column 0
+                        // 3. Clear the entire line
+                        // 4. Print new command
+                        // 5. Move to next line
+                        // 6. Clear prompt line
+                        // 7. Reprint prompt
+
+                        let _ = stderr.execute(MoveUp(1));
+                        let _ = stderr.execute(MoveToColumn(0));
+                        let _ = stderr.execute(Clear(ClearType::CurrentLine));
+
+                        let cmd_text = format_command(&commands[selected_index], selected_index);
+                        if use_color {
+                            eprintln!("{}", cmd_text.cyan());
+                        } else {
+                            eprintln!("{}", cmd_text);
+                        }
+
+                        // Clear current line (prompt line) and reprint
+                        let _ = stderr.execute(MoveToColumn(0));
+                        let _ = stderr.execute(Clear(ClearType::CurrentLine));
+                        eprint!("{}", prompt);
+                        let _ = stderr.flush();
+
+                        continue;
+                    }
+                    KeyCode::Enter => {
+                        break Ok((CommandAction::Execute, commands[selected_index].clone()));
+                    }
+                    KeyCode::Esc => {
+                        break Ok((CommandAction::Abort, String::new()));
+                    }
+                    _ => {
+                        // Ignore other keys, keep waiting
+                        continue;
+                    }
+                }
+            }
+            Ok(_) => {
+                // Ignore non-key events
+                continue;
+            }
+            Err(e) => {
+                break Err(InteractiveError::IoError(format!(
+                    "Failed to read keypress: {}",
+                    e
+                )));
+            }
+        }
+    };
+
+    // Disable raw mode
+    if let Err(e) = disable_raw_mode() {
+        eprintln!("\nWarning: Failed to disable raw mode: {}", e);
+    }
+
+    // Print newline for clean output
+    eprintln!();
+
+    result
+}
+
+/// Execute a command directly using std::process::Command
+///
+/// Spawns the command as a child process and waits for it to complete.
+/// Returns the exit code of the command.
+///
+/// # Arguments
+/// * `command` - The command to execute (will be parsed by shell)
+///
+/// # Returns
+/// * `Result<i32, String>` - Exit code of command or error message
+pub fn execute_command(command: &str) -> Result<i32, String> {
+    use std::process::Command;
+
+    // Platform-specific shell execution
+    #[cfg(windows)]
+    let status = Command::new("cmd")
+        .args(["/C", command])
+        .status()
+        .map_err(|e| format!("Failed to execute command: {}", e))?;
+
+    #[cfg(not(windows))]
+    let status = {
+        // Detect shell from environment, fallback to /bin/sh
+        let shell = std::env::var("SHELL").unwrap_or_else(|_| "/bin/sh".to_string());
+        Command::new(&shell)
+            .arg("-c")
+            .arg(command)
+            .status()
+            .map_err(|e| format!("Failed to execute command: {}", e))?
+    };
+
+    Ok(status.code().unwrap_or(1))
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_execute_command_simple() {
+        // Test executing a simple command
+        let result = execute_command("echo test");
+        // Should succeed (exit code 0)
+        assert!(result.is_ok());
+        assert_eq!(result.unwrap(), 0);
+    }
+
+    #[test]
+    fn test_execute_command_failure() {
+        // Test executing a failing command
+        let result = execute_command("false");
+        // Should return non-zero exit code
+        assert!(result.is_ok());
+        assert_ne!(result.unwrap(), 0);
+    }
+
+    #[test]
+    fn test_empty_commands_returns_error() {
+        use clap::Parser;
+        let cli = crate::cli::Cli::parse_from(["clai", "test instruction"]);
+        let config = crate::config::Config::from_cli(cli);
+
+        let commands: Vec<String> = vec![];
+        let result = prompt_command_action(&commands, &config);
+
+        assert!(result.is_err());
+        match result {
+            Err(InteractiveError::NoCommands) => (),
+            _ => panic!("Expected NoCommands error"),
+        }
+    }
+
+    // Note: Integration tests for prompt_command_action with TTY interaction
+    // would require a TTY and user interaction, which is complex to test automatically.
+    // These are better suited for manual testing.
+}
diff --git a/src/safety/mod.rs b/src/safety/mod.rs
new file mode 100644
index 0000000..0121548
--- /dev/null
+++ b/src/safety/mod.rs
@@ -0,0 +1,13 @@
+pub mod confirmation;
+pub mod detector;
+pub mod interactive;
+pub mod patterns;
+pub mod prompt;
+
+pub use confirmation::{
+    format_decision, handle_dangerous_confirmation, ConfirmationError, Decision,
+};
+pub use detector::{get_matching_pattern, is_dangerous_command, is_dangerous_command_with_regexes};
+pub use interactive::{execute_command, prompt_command_action, CommandAction, InteractiveError};
+pub use patterns::{compile_dangerous_regexes, get_dangerous_regexes};
+pub use prompt::{is_interactive_mode, is_piped_output, should_prompt};
diff --git a/src/safety/patterns.rs b/src/safety/patterns.rs
new file mode 100644
index 0000000..ab3cb7c
--- /dev/null
+++ b/src/safety/patterns.rs
@@ -0,0 +1,187 @@
+use crate::config::file::FileConfig;
+use anyhow::{Context, Result};
+use regex::Regex;
+use std::sync::OnceLock;
+
+/// Cached compiled dangerous pattern regexes
+///
+/// Thread-safe lazy initialization using OnceLock.
+/// Compiled once on first access, reused for all subsequent checks.
+static DANGEROUS_REGEXES: OnceLock<Result<Vec<Regex>, String>> = OnceLock::new();
+
+/// Default dangerous command patterns
+///
+/// These are safe defaults that catch common destructive commands.
+/// Users can override via config file.
+fn default_dangerous_patterns() -> Vec<String> {
+    vec![
+        r"rm\s+-rf\s+/".to_string(),             // rm -rf /
+        r"rm\s+-rf\s+/\s*$".to_string(),         // rm -rf / (end of line)
+        r"dd\s+if=/dev/zero".to_string(),        // dd if=/dev/zero
+        r"mkfs\.\w+\s+/dev/".to_string(),        // mkfs.* /dev/
+        r"sudo\s+rm\s+-rf\s+/".to_string(),      // sudo rm -rf /
+        r">\s*/dev/".to_string(),                // > /dev/
+        r"format\s+[c-z]:".to_string(),          // format C: (Windows)
+        r"del\s+/f\s+/s\s+[c-z]:\\".to_string(), // del /f /s C:\ (Windows)
+    ]
+}
+
+/// Compile dangerous pattern regexes from config
+///
+/// Pure function that compiles regex patterns from config.
+/// Uses lazy static caching - compiled once, reused forever.
+///
+/// # Arguments
+/// * `config` - File configuration containing dangerous patterns
+///
+/// # Returns
+/// * `Result<Vec<Regex>>` - Compiled regex patterns or error
+///
+/// # Errors
+/// * Returns error if any pattern fails to compile as valid regex
+pub fn compile_dangerous_regexes(config: &FileConfig) -> Result<Vec<Regex>> {
+    // Get patterns from config or use defaults
+    let patterns = if config.safety.dangerous_patterns.is_empty() {
+        default_dangerous_patterns()
+    } else {
+        config.safety.dangerous_patterns.clone()
+    };
+
+    // Compile each pattern
+    let mut regexes = Vec::with_capacity(patterns.len());
+
+    for (index, pattern) in patterns.iter().enumerate() {
+        match Regex::new(pattern) {
+            Ok(regex) => regexes.push(regex),
+            Err(e) => {
+                // Log error to stderr but continue with other patterns
+                eprintln!(
+                    "Warning: Invalid dangerous pattern at index {}: '{}' - {}",
+                    index, pattern, e
+                );
+                // Return error for invalid regex (fail fast for safety)
+                return Err(anyhow::anyhow!(
+                    "Failed to compile dangerous pattern '{}' at index {}: {}",
+                    pattern,
+                    index,
+                    e
+                ))
+                .context("Invalid regex pattern in dangerous_patterns config");
+            }
+        }
+    }
+
+    Ok(regexes)
+}
+
+/// Get or compile dangerous regexes (lazy initialization)
+///
+/// Thread-safe function that compiles regexes once on first access.
+/// Subsequent calls return the cached compiled regexes.
+///
+/// # Arguments
+/// * `config` - File configuration
+///
+/// # Returns
+/// * `Result<&[Regex]>` - Reference to compiled regexes
+pub fn get_dangerous_regexes(config: &FileConfig) -> Result<&'static [Regex]> {
+    DANGEROUS_REGEXES
+        .get_or_init(|| match compile_dangerous_regexes(config) {
+            Ok(regexes) => Ok(regexes),
+            Err(e) => Err(e.to_string()),
+        })
+        .as_ref()
+        .map_err(|e| anyhow::anyhow!("Failed to compile dangerous patterns: {}", e))
+        .map(|regexes| regexes.as_slice())
+}
+
+/// Reset dangerous regex cache (for testing only)
+///
+/// # Safety
+/// This function is only intended for testing.
+/// It clears the cache, allowing tests to use different configs.
+#[cfg(test)]
+pub fn reset_regex_cache() {
+    // OnceLock doesn't have a reset method, so we can't actually reset it
+    // This is a no-op, but documents the intent for testing
+    // In practice, tests should use different configs or test compile_dangerous_regexes directly
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::file::FileConfig;
+
+    #[test]
+    fn test_default_patterns_compile() {
+        let config = FileConfig::default();
+        let regexes = compile_dangerous_regexes(&config).unwrap();
+        assert!(!regexes.is_empty());
+    }
+
+    #[test]
+    fn test_default_patterns_match_rm_rf() {
+        let config = FileConfig::default();
+        let regexes = compile_dangerous_regexes(&config).unwrap();
+
+        // Test that default patterns match dangerous commands
+        assert!(regexes.iter().any(|r| r.is_match("rm -rf /")));
+        assert!(regexes.iter().any(|r| r.is_match("sudo rm -rf /")));
+        assert!(regexes
+            .iter()
+            .any(|r| r.is_match("dd if=/dev/zero of=/dev/sda")));
+    }
+
+    #[test]
+    fn test_custom_patterns() {
+        let mut config = FileConfig::default();
+        config.safety.dangerous_patterns = vec![
+            r"dangerous\s+command".to_string(),
+            r"test\s+pattern".to_string(),
+        ];
+
+        let regexes = compile_dangerous_regexes(&config).unwrap();
+        assert_eq!(regexes.len(), 2);
+        assert!(regexes.iter().any(|r| r.is_match("dangerous command")));
+        assert!(regexes.iter().any(|r| r.is_match("test pattern")));
+    }
+
+    #[test]
+    fn test_invalid_regex_returns_error() {
+        let mut config = FileConfig::default();
+        config.safety.dangerous_patterns = vec![
+            r"valid\s+pattern".to_string(),
+            r"[invalid regex".to_string(), // Unclosed bracket
+        ];
+
+        let result = compile_dangerous_regexes(&config);
+        assert!(result.is_err());
+        let error_msg = result.unwrap_err().to_string();
+        // Error message should mention the pattern or compilation failure
+        assert!(
+            error_msg.contains("Failed to compile") || error_msg.contains("Invalid regex pattern")
+        );
+    }
+
+    #[test]
+    fn test_empty_patterns_uses_defaults() {
+        let mut config = FileConfig::default();
+        config.safety.dangerous_patterns = vec![];
+
+        // Empty vec should use defaults
+        let regexes = compile_dangerous_regexes(&config).unwrap();
+        assert!(!regexes.is_empty()); // Should have default patterns
+    }
+
+    #[test]
+    fn test_safe_commands_dont_match() {
+        let config = FileConfig::default();
+        let regexes = compile_dangerous_regexes(&config).unwrap();
+
+        // Safe commands should not match
+        assert!(!regexes.iter().any(|r| r.is_match("ls -la")));
+        assert!(!regexes.iter().any(|r| r.is_match("cd /tmp")));
+        assert!(!regexes.iter().any(|r| r.is_match("echo hello")));
+        assert!(!regexes.iter().any(|r| r.is_match("git status")));
+    }
+}
diff --git a/src/safety/prompt.rs b/src/safety/prompt.rs
new file mode 100644
index 0000000..560b99a
--- /dev/null
+++ b/src/safety/prompt.rs
@@ -0,0 +1,150 @@
+use crate::cli::Cli;
+use crate::config::file::FileConfig;
+use crate::signals::{is_stdin_tty, is_stdout_tty};
+
+/// Determine if we should prompt the user for dangerous command confirmation
+///
+/// Pure function that checks all conditions for interactive prompting:
+/// - Must be in a TTY (stdin and stdout)
+/// - Config must have confirm_dangerous enabled
+/// - CLI must not have --force flag
+///
+/// # Arguments
+/// * `cli` - CLI arguments
+/// * `config` - File configuration
+///
+/// # Returns
+/// * `bool` - `true` if we should prompt, `false` otherwise
+///
+/// # Examples
+/// ```ignore
+/// use clap::Parser;
+/// use clai::cli::Cli;
+/// use clai::config::file::FileConfig;
+/// use clai::safety::prompt::should_prompt;
+///
+/// // Cli is a clap-derived struct; construct via parse_from.
+/// // See crate::cli::Cli for full field definitions.
+/// let cli = Cli::parse_from(&["clai", "your instruction here"]);
+/// let config = FileConfig::default();
+/// // Result depends on TTY state
+/// let result = should_prompt(&cli, &config);
+/// ```
+pub fn should_prompt(cli: &Cli, config: &FileConfig) -> bool {
+    // Check if we're in a TTY (both stdin and stdout)
+    let is_tty = is_stdin_tty() && is_stdout_tty();
+
+    // Check config setting
+    let confirm_enabled = config.safety.confirm_dangerous;
+
+    // Check if --force flag is set (bypasses prompting)
+    let force_bypass = cli.force;
+
+    // Should prompt if: TTY && confirm enabled && not forced
+    is_tty && confirm_enabled && !force_bypass
+}
+
+/// Check if we're in interactive mode (TTY)
+///
+/// Pure function that checks if both stdin and stdout are TTYs.
+///
+/// # Returns
+/// * `bool` - `true` if interactive (TTY), `false` if piped
+pub fn is_interactive_mode() -> bool {
+    is_stdin_tty() && is_stdout_tty()
+}
+
+/// Check if output is piped (not a TTY)
+///
+/// Pure function that checks if stdout is not a TTY.
+///
+/// # Returns
+/// * `bool` - `true` if piped, `false` if TTY
+pub fn is_piped_output() -> bool {
+    !is_stdout_tty()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::config::file::FileConfig;
+    use clap::Parser;
+
+    fn create_test_cli(force: bool) -> crate::cli::Cli {
+        // Create a minimal Cli for testing
+        if force {
+            crate::cli::Cli::parse_from(&["clai", "--force", "test instruction"])
+        } else {
+            crate::cli::Cli::parse_from(&["clai", "test instruction"])
+        }
+    }
+
+    #[test]
+    fn test_should_prompt_requires_tty() {
+        let cli = create_test_cli(false);
+        let mut config = FileConfig::default();
+        config.safety.confirm_dangerous = true;
+
+        // Result depends on actual TTY state, but logic is correct
+        let result = should_prompt(&cli, &config);
+        // If we're in a TTY, should prompt; if piped, should not
+        // This test verifies the logic, not the TTY state
+        assert_eq!(
+            result,
+            is_interactive_mode() && config.safety.confirm_dangerous && !cli.force
+        );
+    }
+
+    #[test]
+    fn test_should_prompt_respects_force_flag() {
+        let cli_forced = create_test_cli(true);
+        let cli_not_forced = create_test_cli(false);
+        let mut config = FileConfig::default();
+        config.safety.confirm_dangerous = true;
+
+        let result_forced = should_prompt(&cli_forced, &config);
+        let result_not_forced = should_prompt(&cli_not_forced, &config);
+
+        // Force should always disable prompting
+        assert!(!result_forced);
+        // Not forced should respect other conditions
+        assert_eq!(
+            result_not_forced,
+            is_interactive_mode() && config.safety.confirm_dangerous
+        );
+    }
+
+    #[test]
+    fn test_should_prompt_respects_config() {
+        let cli = create_test_cli(false);
+        let mut config_enabled = FileConfig::default();
+        config_enabled.safety.confirm_dangerous = true;
+
+        let mut config_disabled = FileConfig::default();
+        config_disabled.safety.confirm_dangerous = false;
+
+        let result_enabled = should_prompt(&cli, &config_enabled);
+        let result_disabled = should_prompt(&cli, &config_disabled);
+
+        // If disabled, should never prompt
+        assert!(!result_disabled);
+        // If enabled, depends on TTY and force
+        assert_eq!(result_enabled, is_interactive_mode() && !cli.force);
+    }
+
+    #[test]
+    fn test_is_interactive_mode() {
+        // This test verifies the function works (actual value depends on test environment)
+        let result = is_interactive_mode();
+        // Should be consistent with should_prompt logic
+        assert_eq!(result, is_stdin_tty() && is_stdout_tty());
+    }
+
+    #[test]
+    fn test_is_piped_output() {
+        // This test verifies the function works (actual value depends on test environment)
+        let result = is_piped_output();
+        // Should be opposite of stdout TTY
+        assert_eq!(result, !is_stdout_tty());
+    }
+}
diff --git a/src/signals/mod.rs b/src/signals/mod.rs
new file mode 100644
index 0000000..ce4acc1
--- /dev/null
+++ b/src/signals/mod.rs
@@ -0,0 +1,132 @@
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::Arc;
+
+/// Exit codes following UNIX conventions
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum ExitCode {
+    /// Success (0)
+    Success = 0,
+    /// Invalid arguments (2)
+    InvalidArgs = 2,
+    /// Command interrupted by SIGINT (130)
+    Interrupted = 130,
+    /// General error (1)
+    GeneralError = 1,
+    /// User aborted dangerous command (5)
+    Aborted = 5,
+}
+
+impl ExitCode {
+    /// Convert to i32 for process::exit()
+    pub fn as_i32(self) -> i32 {
+        self as i32
+    }
+}
+
+/// Initialize signal handlers
+/// Sets up handlers for SIGINT, SIGTERM, and SIGPIPE
+/// Returns an Arc<AtomicBool> that can be checked for interruption
+pub fn setup_signal_handlers() -> Arc<AtomicBool> {
+    let interrupted = Arc::new(AtomicBool::new(false));
+
+    // Handle SIGINT (Ctrl+C) - exit with code 130
+    {
+        let flag = Arc::clone(&interrupted);
+        signal_hook::flag::register(signal_hook::consts::SIGINT, flag.clone())
+            .expect("Failed to register SIGINT handler");
+    }
+
+    // Handle SIGTERM - clean shutdown
+    {
+        let flag = Arc::clone(&interrupted);
+        signal_hook::flag::register(signal_hook::consts::SIGTERM, flag.clone())
+            .expect("Failed to register SIGTERM handler");
+    }
+
+    // Handle SIGPIPE - silently ignore (common for pipe operations)
+    // SIGPIPE is automatically ignored in Rust by default on Unix systems
+    // On Windows, broken pipes are handled via errors, not signals
+    // No explicit handler needed - Rust's default behavior is correct
+
+    interrupted
+}
+
+/// Check if the process was interrupted by a signal
+/// Pure function - reads atomic state
+pub fn is_interrupted(flag: &Arc<AtomicBool>) -> bool {
+    flag.load(Ordering::Relaxed)
+}
+
+/// Check if stdout is a TTY (for interactive behavior detection)
+/// Pure function - no side effects
+pub fn is_stdout_tty() -> bool {
+    atty::is(atty::Stream::Stdout)
+}
+
+/// Check if stdin is a TTY (for interactive behavior detection)
+/// Pure function - no side effects
+pub fn is_stdin_tty() -> bool {
+    atty::is(atty::Stream::Stdin)
+}
+
+/// Check if stderr is a TTY (for color output)
+/// Pure function - no side effects
+pub fn is_stderr_tty() -> bool {
+    atty::is(atty::Stream::Stderr)
+}
+
+/// Determine if the process is running in interactive mode
+/// Interactive = both stdin and stdout are TTYs
+/// Pure function - no side effects
+pub fn is_interactive() -> bool {
+    is_stdin_tty() && is_stdout_tty()
+}
+
+/// Determine if output is being piped
+/// Piped = stdout is not a TTY
+/// Pure function - no side effects
+pub fn is_piped() -> bool {
+    !is_stdout_tty()
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_exit_code_values() {
+        assert_eq!(ExitCode::Success.as_i32(), 0);
+        assert_eq!(ExitCode::InvalidArgs.as_i32(), 2);
+        assert_eq!(ExitCode::Interrupted.as_i32(), 130);
+        assert_eq!(ExitCode::GeneralError.as_i32(), 1);
+        assert_eq!(ExitCode::Aborted.as_i32(), 5);
+    }
+
+    #[test]
+    fn test_tty_detection_pure() {
+        // These are pure functions - they should return consistent results
+        // in the same environment
+        let result1 = is_stdout_tty();
+        let result2 = is_stdout_tty();
+        assert_eq!(result1, result2, "TTY detection should be consistent");
+    }
+
+    #[test]
+    fn test_is_interactive_pure() {
+        // Pure function - same input (environment), same output
+        let result1 = is_interactive();
+        let result2 = is_interactive();
+        assert_eq!(
+            result1, result2,
+            "Interactive detection should be consistent"
+        );
+    }
+
+    #[test]
+    fn test_is_piped_pure() {
+        // Pure function - same input (environment), same output
+        let result1 = is_piped();
+        let result2 = is_piped();
+        assert_eq!(result1, result2, "Pipe detection should be consistent");
+    }
+}
diff --git a/test_config.sh b/test_config.sh
new file mode 100755
index 0000000..eff42c5
--- /dev/null
+++ b/test_config.sh
@@ -0,0 +1,156 @@
+#!/bin/bash
+# Test script for clai configuration system
+
+set -e
+
+# Get the directory where this script is located
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+echo "=== Testing clai Configuration System ==="
+echo ""
+
+# Colors for output
+GREEN='\033[0;32m'
+RED='\033[0;31m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Test counter
+TESTS_PASSED=0
+TESTS_FAILED=0
+
+test_result() {
+    if [ $? -eq 0 ]; then
+        echo -e "${GREEN}✓${NC} $1"
+        ((TESTS_PASSED++))
+    else
+        echo -e "${RED}✗${NC} $1"
+        ((TESTS_FAILED++))
+    fi
+}
+
+# Test 1: Default config (no files, no env, no CLI flags)
+echo "Test 1: Default configuration"
+OUTPUT=$(cd "$SCRIPT_DIR" && cargo r -- "test" 2>&1)
+test_result "Default config loads successfully"
+
+# Test 2: CLI flag override (--provider)
+echo ""
+echo "Test 2: CLI flag override (--provider)"
+OUTPUT=$(cd "$SCRIPT_DIR" && cargo r -- --provider "test-provider" "test" 2>&1)
+test_result "CLI --provider flag works"
+
+# Test 3: CLI flag override (--model)
+echo ""
+echo "Test 3: CLI flag override (--model)"
+OUTPUT=$(cd "$SCRIPT_DIR" && cargo r -- --model "gpt-4" "test" 2>&1)
+test_result "CLI --model flag works"
+
+# Test 4: Environment variable override
+echo ""
+echo "Test 4: Environment variable override"
+OUTPUT=$(cd "$SCRIPT_DIR" && CLAI_PROVIDER_DEFAULT="env-provider" cargo r -- "test" 2>&1)
+test_result "Environment variable CLAI_PROVIDER_DEFAULT works"
+
+# Test 5: Config file loading (current directory)
+echo ""
+echo "Test 5: Config file in current directory"
+cd "$SCRIPT_DIR"
+cat > .clai.toml << 'EOF'
+[provider]
+default = "file-provider"
+
+[context]
+max-files = 25
+EOF
+chmod 600 .clai.toml 2>/dev/null || true
+OUTPUT=$(cargo r -- "test" 2>&1)
+test_result "Config file .clai.toml loads successfully"
+rm -f .clai.toml
+
+# Test 6: XDG config path
+echo ""
+echo "Test 6: XDG config directory"
+mkdir -p ~/.config/clai 2>/dev/null || true
+cat > ~/.config/clai/config.toml << 'EOF'
+[provider]
+default = "xdg-provider"
+
+[context]
+max-history = 5
+EOF
+chmod 600 ~/.config/clai/config.toml 2>/dev/null || true
+OUTPUT=$(cd "$SCRIPT_DIR" && cargo r -- "test" 2>&1)
+test_result "XDG config file loads successfully"
+rm -f ~/.config/clai/config.toml 2>/dev/null || true
+
+# Test 7: Precedence test (CLI > env > file)
+echo ""
+echo "Test 7: Precedence order (CLI > env > file)"
+cd "$SCRIPT_DIR"
+cat > .clai.toml << 'EOF'
+[provider]
+default = "file-provider"
+EOF
+chmod 600 .clai.toml 2>/dev/null || true
+OUTPUT=$(CLAI_PROVIDER_DEFAULT="env-provider" cargo r -- --provider "cli-provider" "test" 2>&1)
+# CLI should win, so we expect it to work
+test_result "CLI overrides env and file (precedence)"
+rm -f .clai.toml
+
+# Test 8: Permission check (should fail with 644)
+echo ""
+echo "Test 8: Permission check (insecure permissions)"
+cd "$SCRIPT_DIR"
+cat > .clai.toml << 'EOF'
+[provider]
+default = "test"
+EOF
+chmod 644 .clai.toml 2>/dev/null || true
+OUTPUT=$(cargo r -- "test" 2>&1 2>&1)
+# Should show warning about insecure permissions
+if echo "$OUTPUT" | grep -q "InsecurePermissions\|insecure\|permission"; then
+    test_result "Permission check rejects 644 permissions"
+else
+    echo -e "${YELLOW}⚠${NC} Permission check (may not work on all systems)"
+fi
+rm -f .clai.toml
+
+# Test 9: Lazy loading (should only load once)
+echo ""
+echo "Test 9: Lazy loading (config cached after first access)"
+OUTPUT=$(cd "$SCRIPT_DIR" && cargo r -- "test" 2>&1)
+test_result "Lazy loading works (no errors on multiple calls)"
+
+# Test 10: Invalid TOML (should handle gracefully)
+echo ""
+echo "Test 10: Invalid TOML handling"
+cd "$SCRIPT_DIR"
+cat > .clai.toml << 'EOF'
+[provider
+default = "invalid"
+EOF
+chmod 600 .clai.toml 2>/dev/null || true
+OUTPUT=$(cargo r -- "test" 2>&1)
+# Should show warning but continue
+if echo "$OUTPUT" | grep -q "Warning\|ParseError\|Failed to parse"; then
+    test_result "Invalid TOML handled gracefully"
+else
+    test_result "Invalid TOML handled gracefully (no crash)"
+fi
+rm -f .clai.toml
+
+# Summary
+echo ""
+echo "=== Test Summary ==="
+echo -e "${GREEN}Passed: ${TESTS_PASSED}${NC}"
+echo -e "${RED}Failed: ${TESTS_FAILED}${NC}"
+echo ""
+
+if [ $TESTS_FAILED -eq 0 ]; then
+    echo -e "${GREEN}All tests passed!${NC}"
+    exit 0
+else
+    echo -e "${RED}Some tests failed.${NC}"
+    exit 1
+fi
diff --git a/test_openrouter.sh b/test_openrouter.sh
new file mode 100755
index 0000000..8732e1b
--- /dev/null
+++ b/test_openrouter.sh
@@ -0,0 +1,72 @@
+#!/bin/bash
+# Test script for OpenRouter integration
+# This script tests that clai can gather context and communicate with OpenRouter
+
+set -e
+
+echo "=== Testing OpenRouter Integration ==="
+echo ""
+
+# Check if API key is set
+if [ -z "$OPENROUTER_API_KEY" ]; then
+    echo "⚠️  Warning: OPENROUTER_API_KEY environment variable is not set"
+    echo "   Set it with: export OPENROUTER_API_KEY='your-key-here'"
+    echo ""
+    echo "   You can get an API key from: https://openrouter.ai/keys"
+    echo ""
+    read -p "Continue anyway? (y/N) " -n 1 -r
+    echo
+    if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+        exit 1
+    fi
+fi
+
+echo "1. Testing basic command generation..."
+echo "   Command: 'list files in current directory'"
+echo ""
+
+COMMAND=$(cargo run --quiet -- "list files in current directory" 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ]; then
+    echo "✅ Success! Generated command:"
+    echo "   $COMMAND"
+    echo ""
+    echo "   To execute: $COMMAND"
+else
+    echo "❌ Failed with exit code: $EXIT_CODE"
+    echo "   Error output:"
+    echo "$COMMAND" | grep -i error || echo "$COMMAND"
+    exit 1
+fi
+
+echo ""
+echo "2. Testing with verbose output..."
+echo "   Command: 'show git status'"
+echo ""
+
+VERBOSE_OUTPUT=$(cargo run --quiet -- -v "show git status" 2>&1)
+echo "$VERBOSE_OUTPUT" | head -20
+
+echo ""
+echo "3. Testing context gathering (should see system info in verbose mode)..."
+echo "   Command: 'find all rust files'"
+echo ""
+
+CONTEXT_TEST=$(cargo run --quiet -- -vv "find all rust files" 2>&1)
+echo "$CONTEXT_TEST" | grep -i "system\|context\|directory" | head -5 || echo "   (Context info may be in stderr)"
+
+echo ""
+echo "=== Test Summary ==="
+echo "✅ Basic command generation: Working"
+echo "✅ OpenRouter integration: Working"
+echo ""
+echo "To test manually:"
+echo "  cargo run -- 'your instruction here'"
+echo ""
+echo "To see verbose output:"
+echo "  cargo run -- -v 'your instruction here'"
+echo ""
+echo "To see debug output:"
+echo "  cargo run -- -vv 'your instruction here'"
+
diff --git a/tests/cli_tests.rs b/tests/cli_tests.rs
new file mode 100644
index 0000000..27ab686
--- /dev/null
+++ b/tests/cli_tests.rs
@@ -0,0 +1,75 @@
+use std::process::Command;
+
+fn run_clai(args: &[&str]) -> (String, String, i32) {
+    // Use CARGO_BIN_EXE_clai which is set by cargo test to the correct binary path
+    let binary_path = env!("CARGO_BIN_EXE_clai");
+
+    let output = Command::new(binary_path)
+        .args(args)
+        .output()
+        .expect("Failed to execute clai");
+
+    let stdout = String::from_utf8_lossy(&output.stdout).to_string();
+    let stderr = String::from_utf8_lossy(&output.stderr).to_string();
+    let exit_code = output.status.code().unwrap_or(-1);
+
+    (stdout, stderr, exit_code)
+}
+
+#[test]
+fn test_missing_instruction_returns_exit_2() {
+    let (_stdout, _stderr, exit_code) = run_clai(&[]);
+    assert_eq!(
+        exit_code, 2,
+        "Missing INSTRUCTION should return exit code 2"
+    );
+}
+
+#[test]
+fn test_invalid_flag_returns_exit_2() {
+    let (_stdout, _stderr, exit_code) = run_clai(&["--invalid-flag", "test"]);
+    assert_eq!(exit_code, 2, "Invalid flag should return exit code 2");
+}
+
+#[test]
+fn test_help_output() {
+    let (stdout, _stderr, exit_code) = run_clai(&["--help"]);
+    assert_eq!(exit_code, 0, "Help should return exit code 0");
+    assert!(
+        stdout.contains("Usage:"),
+        "Help should contain usage information"
+    );
+    assert!(stdout.contains("clai"), "Help should contain binary name");
+}
+
+#[test]
+fn test_version_output() {
+    let (stdout, _stderr, exit_code) = run_clai(&["--version"]);
+    assert_eq!(exit_code, 0, "Version should return exit code 0");
+    assert!(
+        stdout.contains("clai"),
+        "Version should contain binary name"
+    );
+    assert!(
+        stdout.contains("0.1.0"),
+        "Version should contain version number"
+    );
+}
+
+#[test]
+fn test_offline_not_supported() {
+    // --offline is not yet implemented and should return an error
+    let (_stdout, stderr, exit_code) = run_clai(&["--offline", "test"]);
+    assert_eq!(
+        exit_code, 1,
+        "Offline mode should return exit code 1 (not supported)"
+    );
+    assert!(
+        stderr.contains("Offline mode is not yet supported"),
+        "Should show offline not supported message"
+    );
+}
+
+// Note: Integration tests that require actual API calls or network access
+// are not reliable in CI environments. The unit tests in src/ cover the
+// error handling paths. These integration tests focus on CLI argument parsing.
diff --git a/tests/test_context_gathering.rs b/tests/test_context_gathering.rs
new file mode 100644
index 0000000..177efb3
--- /dev/null
+++ b/tests/test_context_gathering.rs
@@ -0,0 +1,82 @@
+use clai::config::Config;
+use clai::context::gatherer::gather_context;
+
+#[test]
+fn test_context_gathering_integration() {
+    // Create a test config
+    let config = Config {
+        instruction: "test instruction".to_string(),
+        model: None,
+        provider: None,
+        quiet: false,
+        verbose: 0,
+        no_color: false,
+        color: clai::cli::ColorChoice::Auto,
+        interactive: false,
+        force: false,
+        dry_run: false,
+        context: None,
+        offline: false,
+        num_options: 3,
+        debug: false,
+        debug_log_file: None,
+    };
+
+    // Gather context
+    match gather_context(&config) {
+        Ok(json_str) => {
+            println!("\n=== Context Gathering Test Output ===\n");
+            println!("{}", json_str);
+            println!("\n=== End of Context Output ===\n");
+
+            // Verify it's valid JSON
+            let parsed: serde_json::Value =
+                serde_json::from_str(&json_str).expect("Context should be valid JSON");
+
+            // Verify required fields exist
+            assert!(
+                parsed.get("system").is_some(),
+                "System info should be present"
+            );
+            assert!(parsed.get("cwd").is_some(), "CWD should be present");
+            assert!(parsed.get("files").is_some(), "Files should be present");
+            assert!(parsed.get("history").is_some(), "History should be present");
+            assert!(
+                parsed.get("stdin").is_some(),
+                "Stdin field should be present"
+            );
+
+            // Verify system info has expected fields
+            let system = parsed.get("system").unwrap().as_object().unwrap();
+            assert!(system.contains_key("os_name"), "System should have os_name");
+            assert!(system.contains_key("shell"), "System should have shell");
+            assert!(
+                system.contains_key("architecture"),
+                "System should have architecture"
+            );
+
+            // Verify cwd is a string
+            assert!(
+                parsed.get("cwd").unwrap().is_string(),
+                "CWD should be a string"
+            );
+
+            // Verify files is an array
+            assert!(
+                parsed.get("files").unwrap().is_array(),
+                "Files should be an array"
+            );
+
+            // Verify history is an array
+            assert!(
+                parsed.get("history").unwrap().is_array(),
+                "History should be an array"
+            );
+
+            println!("✅ All context gathering tests passed!");
+        }
+        Err(e) => {
+            panic!("Failed to gather context: {}", e);
+        }
+    }
+}