feat(config): XDG base directories and persistent UI preferences

AGENTS.md

@@ -68,8 +68,8 @@ Large-diff work is a separate evaluation track, not part of the default live-rep
 - **VCR caching** — record/replay LLM calls for deterministic CI
 - **LLM-as-judge** — evaluator that scores analysis quality across 5 criteria
 - **Eval suite** — 5 synthetic fixture codebases, deterministic scoring, 0.89 avg score
-- **Config** — `.diffcore.toml` with entrypoint globs, layer names, ignore patterns, LLM settings, refinement settings
-- **Logging** — `tracing` + `tracing-subscriber` behind `diffcore-core`'s `logging` feature; `RUST_LOG` sets the filter (default `info`), `DIFFCORE_LOG_FORMAT=json` switches to line-delimited JSON, `DIFFCORE_LOG_FILE` redirects to a file (the desktop app falls back to `~/.diffcore/desktop.log` when stderr is not a terminal, since GUI bundles discard it). Backend activity logs on the `activity` target, IR cache on `ir_cache`. `log`-crate call sites bridge in automatically.
+- **Config** — `.diffcore.toml` with entrypoint globs, layer names, ignore patterns, LLM settings, refinement settings; per-user config/cache/state resolved via XDG base dirs in `diffcore-core`'s `paths` module (`$XDG_CONFIG_HOME/diffcore/config.toml`, with `~/.diffcore/config.toml` as a read-only legacy fallback). Theme and panel preferences live in a separate `ui.toml` (`UiConfig`) so high-frequency UI writes never race the credential-bearing `config.toml`; review comments are user data and live under `$XDG_DATA_HOME/diffcore/comments/` with a read-fallback to the pre-XDG location
+- **Logging** — `tracing` + `tracing-subscriber` behind `diffcore-core`'s `logging` feature; `RUST_LOG` sets the filter (default `info`), `DIFFCORE_LOG_FORMAT=json` switches to line-delimited JSON, `DIFFCORE_LOG_FILE` redirects to a file (the desktop app falls back to `$XDG_STATE_HOME/diffcore/desktop.log` when stderr is not a terminal, since GUI bundles discard it). Backend activity logs on the `activity` target, IR cache on `ir_cache`. `log`-crate call sites bridge in automatically.
 
 ## Tests
 

README.md

@@ -148,9 +148,14 @@ The app auto-discovers git branches, worktrees, and push status on launch. Enter
 
 Diffcore now splits configuration into:
 
-- `~/.diffcore/config.toml` for shared LLM/onboarding settings across all repos
+- `$XDG_CONFIG_HOME/diffcore/config.toml` (defaults to `~/.config/diffcore/config.toml`)
+  for shared LLM/onboarding settings across all repos
 - `.diffcore.toml` in the repo root for project-specific analysis settings
 
+Every other path — UI preferences, comments, caches, logs — is listed in
+[docs/file-locations.md](docs/file-locations.md), along with the migration
+notes for pre-XDG installs.
+
 New users can usually skip API keys entirely: the desktop app auto-detects `codex` and `claude`, and will use those subscriptions when available.
 
 Example global config:
@@ -197,8 +202,8 @@ uncertainty = 0.20
 
 When using direct API providers (`anthropic`, `openai`, `gemini`), Diffcore checks for API keys in this order:
 
-1. `key_cmd` in `~/.diffcore/config.toml` or `.diffcore.toml`
-2. `key` in `~/.diffcore/config.toml` or `.diffcore.toml`
+1. `key_cmd` in `~/.config/diffcore/config.toml` or `.diffcore.toml`
+2. `key` in `~/.config/diffcore/config.toml` or `.diffcore.toml`
 3. `DIFFCORE_API_KEY`
 4. Provider specific env var: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `GEMINI_API_KEY`
 
@@ -220,7 +225,8 @@ DIFFCORE_LOG_FORMAT=json diffcore analyze --base main 2> analyze.log.jsonl
 
 Launched from a terminal the desktop app logs there like the others; launched
 from Finder or a `.desktop` entry — where stderr is discarded — it falls back to
-`~/.diffcore/desktop.log`. `DIFFCORE_LOG_FILE` overrides the path for any binary.
+`~/.local/state/diffcore/desktop.log`. `DIFFCORE_LOG_FILE` overrides the path
+for any binary.
 
 ## Architecture
 

crates/diffcore-core/src/cache.rs

@@ -114,20 +114,14 @@ pub fn clear_cache(workdir: &Path) -> std::io::Result<()> {
     Ok(())
 }
 
-// ── Global refinement cache (~/.diffcore/cache/refinements/) ──
+// ── Global refinement cache ($XDG_CACHE_HOME/diffcore/refinements/) ──
 
 /// Resolve the global refinement cache directory.
+/// Respects `DIFFCORE_REFINEMENT_CACHE_DIR` for testing.
 fn refinement_cache_dir() -> Option<PathBuf> {
     std::env::var_os("DIFFCORE_REFINEMENT_CACHE_DIR")
         .map(PathBuf::from)
-        .or_else(|| {
-            std::env::var_os("HOME").map(|home| {
-                PathBuf::from(home)
-                    .join(".diffcore")
-                    .join("cache")
-                    .join("refinements")
-            })
-        })
+        .or_else(|| crate::paths::cache_dir().map(|dir| dir.join("refinements")))
 }
 
 /// Load a cached refinement result for the given analysis cache key.