diff --git a/README.md b/README.md
index b48a297f..cf50e6d7 100644
--- a/README.md
+++ b/README.md
@@ -455,6 +455,8 @@ export CBM_CACHE_DIR=~/my-projects/cbm-data
 
 Map additional file extensions to supported languages via JSON config files. Useful for framework-specific extensions like `.blade.php` (Laravel) or `.mjs` (ES modules).
 
+Need the full config-file reference? See [docs/CONFIGURATION.md](docs/CONFIGURATION.md).
+
 **Per-project** (in your repo root):
 ```json
 // .codebase-memory.json
diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
new file mode 100644
index 00000000..bccc6b27
--- /dev/null
+++ b/docs/CONFIGURATION.md
@@ -0,0 +1,129 @@
+# Configuration Reference
+
+This page documents the configuration files that `codebase-memory-mcp` reads or writes today.
+
+## At a Glance
+
+| Purpose | Path | Format | Notes |
+|---|---|---|---|
+| Global custom extension mapping | `$XDG_CONFIG_HOME/codebase-memory-mcp/config.json` | JSON | Falls back to `~/.config/codebase-memory-mcp/config.json` when `XDG_CONFIG_HOME` is unset. |
+| Per-project custom extension mapping | `{repo_root}/.codebase-memory.json` | JSON | Overrides conflicting global `extra_extensions` entries. |
+| CLI-managed runtime settings | `${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/_config.db` | SQLite | Written by `codebase-memory-mcp config set/reset`. |
+| UI settings | `${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json` | JSON | Stores `ui_enabled` and `ui_port`. |
+
+## 1. Custom File Extension Mapping
+
+Two optional JSON files let you map additional file extensions to built-in languages.
+
+### Global config
+
+Default path:
+
+```text
+$XDG_CONFIG_HOME/codebase-memory-mcp/config.json
+```
+
+Fallback when `XDG_CONFIG_HOME` is unset:
+
+```text
+~/.config/codebase-memory-mcp/config.json
+```
+
+### Per-project config
+
+Place this file in the repository root:
+
+```text
+.codebase-memory.json
+```
+
+### Format
+
+```json
+{
+  "extra_extensions": {
+    ".blade.php": "php",
+    ".mjs": "javascript",
+    ".twig": "html"
+  }
+}
+```
+
+Notes:
+
+- Extension keys must include the leading dot.
+- Language names are case-insensitive.
+- Unknown language names are skipped.
+- Missing files are ignored.
+- If the same extension appears in both files, the per-project file wins.
+
+## 2. CLI-Managed Runtime Settings
+
+The `config` subcommand stores runtime settings in a small SQLite database:
+
+```text
+${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/_config.db
+```
+
+Inspect or change values with the CLI:
+
+```bash
+codebase-memory-mcp config list
+codebase-memory-mcp config get auto_index
+codebase-memory-mcp config set auto_index true
+codebase-memory-mcp config set auto_index_limit 50000
+codebase-memory-mcp config reset auto_index
+```
+
+Current keys:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `auto_index` | `false` | Automatically index new projects when an MCP session starts. |
+| `auto_index_limit` | `50000` | Maximum file count allowed for automatic indexing of a new project. |
+
+## 3. UI Settings
+
+The optional built-in graph UI stores its settings in:
+
+```text
+${CBM_CACHE_DIR:-~/.cache/codebase-memory-mcp}/config.json
+```
+
+Current format:
+
+```json
+{
+  "ui_enabled": false,
+  "ui_port": 9749
+}
+```
+
+Notes:
+
+- If the UI-enabled binary has embedded assets and no UI config file exists yet, the UI auto-enables on first run.
+- `CBM_CACHE_DIR` changes both the UI config location and the runtime settings database location.
+
+## 4. Environment Variables
+
+These environment variables affect runtime behavior:
+
+| Variable | Default | Description |
+|---|---|---|
+| `CBM_CACHE_DIR` | `~/.cache/codebase-memory-mcp` | Override the cache directory used for indexes, `_config.db`, and UI `config.json`. |
+| `CBM_DIAGNOSTICS` | `false` | Enable periodic diagnostics output to `/tmp/cbm-diagnostics-<pid>.json`. |
+| `CBM_DOWNLOAD_URL` | GitHub releases | Override the update download URL. |
+| `CBM_LOG_LEVEL` | `info` | Set stderr log level to `debug`, `info`, `warn`, `error`, or `none` (or `0`-`4`). |
+| `CBM_WORKERS` | auto-detected | Override the indexing worker count. |
+
+## 5. Agent and Editor Integration Files
+
+The `install` command can also write MCP entries and instruction blocks into agent/editor config files such as Claude Code, Codex, Gemini, VS Code, Cursor, Zed, and others.
+
+Those target paths vary by tool and platform, so the easiest way to inspect the exact files for your machine is:
+
+```bash
+codebase-memory-mcp install --dry-run
+```
+
+That prints the specific config files the installer would modify without writing anything.