diff --git a/README.md b/README.md
index 26d5d7e..6e0c0c3 100644
--- a/README.md
+++ b/README.md
@@ -47,6 +47,21 @@ Rename in place (no network lookups):
 mov-renamarr --input /path/to/in --rename-in-place --no-lookup
 ```
 
+## Usage :keyboard:
+```
+mov-renamarr --input <dir> --output <dir> [flags]
+```
+
+Common flags:
+- `--move` or `--rename-in-place` (default is copy)
+- `--provider auto|tmdb|omdb|both`
+- `--no-lookup` (skip external lookups)
+- `--report [path]` and `--report-format text|json|csv`
+- `--sidecars` (copy/move subtitle/nfo/etc files)
+- `--quality-tags resolution,codec,source`
+- `--min-score 0-100` (match threshold)
+- `--jobs auto|N` and `--net-jobs auto|N`
+
 ## Configuration :gear:
 Default config location:
 `$XDG_CONFIG_HOME/mov-renamarr/config.toml` (fallback `~/.config/mov-renamarr/config.toml`)
@@ -68,6 +83,7 @@ Key options (TOML):
 - `sidecars = false` (copy/move sidecars when true)
 
 CLI flags override config, and env vars override config as well.
+Full reference: `docs/CONFIG.md`
 
 ## Providers :globe_with_meridians:
 - **TMDb**: preferred when available. Supports API key or read-access bearer token.
diff --git a/docs/CONFIG.md b/docs/CONFIG.md
new file mode 100644
index 0000000..7fff760
--- /dev/null
+++ b/docs/CONFIG.md
@@ -0,0 +1,98 @@
+# Configuration Reference
+
+This document describes all supported options in `config.toml`.
+
+## Locations
+- Config: `$XDG_CONFIG_HOME/mov-renamarr/config.toml` (fallback `~/.config/mov-renamarr/config.toml`)
+- Cache: `$XDG_CACHE_HOME/mov-renamarr/cache.db` (fallback `~/.cache/mov-renamarr/cache.db`)
+
+The app creates a commented default config on first run if none exists.
+
+## Precedence
+1) Built-in defaults  
+2) Config file  
+3) Environment variables  
+4) CLI flags
+
+## Minimal example
+```toml
+provider = "auto"
+api_key_tmdb = "YOUR_TMDB_KEY_OR_READ_ACCESS_TOKEN"
+quality_tags = ["resolution"]
+
+[llm]
+mode = "off"
+```
+
+## Providers
+```toml
+provider = "auto" # auto|tmdb|omdb|both
+api_key_tmdb = "..."   # TMDb API key or Read Access Token (Bearer)
+api_key_omdb = "..."   # OMDb API key
+```
+
+## Cache
+```toml
+cache_path = "/home/user/.cache/mov-renamarr/cache.db"
+cache_ttl_days = 30
+refresh_cache = false
+```
+
+## Reporting and sidecars
+```toml
+report_format = "text" # text|json|csv
+sidecar_notes = false  # write per-file notes for skipped/failed
+sidecars = false       # move/copy sidecar files (srt, nfo, etc)
+```
+
+## Matching and naming
+```toml
+min_score = 80         # 0-100 match threshold
+include_id = false     # include tmdb/imdb id in filenames
+no_lookup = false      # skip external providers (filename/LLM only)
+```
+
+## Quality tags
+```toml
+quality_tags = ["resolution"]          # list
+# or
+quality_tags = "resolution,codec"      # comma-separated string
+```
+Supported tags: `resolution`, `codec`, `source`, `all`, `none`.
+
+## Output safety
+```toml
+overwrite = false      # replace existing files
+suffix = false         # add " (1)", " (2)" on collision
+```
+
+## Console
+```toml
+color = "auto"         # auto|always|never
+```
+
+## Concurrency
+```toml
+jobs = "auto"          # auto or integer
+net_jobs = "auto"      # auto or integer
+```
+
+## LLM (Ollama)
+```toml
+[llm]
+mode = "off"           # off|parse|assist
+endpoint = "http://localhost:11434"
+model = "Qwen2.5:latest"
+timeout_seconds = 30
+max_tokens = 256
+```
+
+## Provider base URLs (for testing)
+```toml
+tmdb_base_url = "https://api.themoviedb.org/3"
+omdb_base_url = "https://www.omdbapi.com"
+```
+
+## Environment variables
+All config settings can be overridden with environment variables using the
+`MOV_RENAMARR_` prefix (e.g., `MOV_RENAMARR_TMDB_API_KEY`).