1 files changed, 17 insertions, 0 deletions
diff --git a/README.md b/README.md
index 7011723..efb9b0c 100644
--- a/README.md
+++ b/README.md
@@ -31,3 +31,20 @@ It has got improved capabilities for Go code understanding (for example, create
 ## Tmux Status Line
 
 See the [tmux integration guide](docs/tmux.md) for details on configuring the status line.
+
+## File Locations
+
+hexai follows the XDG Base Directory Specification:
+
+- **Configuration:** `~/.config/hexai/config.toml` (or `$XDG_CONFIG_HOME/hexai/`)
+  - Global settings, provider credentials, and preferences
+  - Project-specific: `.hexaiconfig.toml` at repository root
+- **Cache:** `~/.cache/hexai/` (or `$XDG_CACHE_HOME/hexai/`)
+  - `stats.json` - LLM usage tracking (regenerable)
+  - `stats.lock` - File lock for stats access
+- **State & Logs:** `~/.local/state/hexai/` (or `$XDG_STATE_HOME/hexai/`)
+  - `tmux-edit-history.jsonl` - History of text submitted via tmux popup
+  - `hexai-lsp.log` - LSP server debug logs
+  - `hexai-tmux-edit.log` - Tmux edit debug logs
+- **Temporary Files:** `/tmp/` (OS temp directory)
+  - `hexai-*.md` - Temporary editor workspaces (auto-deleted)