guanghu/docs/adr/0145-xdg-backed-app-config-path.md

type, id, title, status, date

type	id	title	status	date
ADR	0145	XDG-backed app config path	active	2026-06-27

Context

Tolaria stores installation-local state such as settings, registered workspaces, window state, AI workspace session metadata, and local AI provider secrets outside the vault. The product rule is still that vault-shaped content belongs in the vault, while machine- and installation-specific preferences stay in app config.

Users also want this app config to be portable through dotfile backup workflows. The existing implementation documented ~/.config/com.tolaria.app, but the Rust path resolver used the platform config directory directly and duplicated that decision in settings and vault-list code. That made $XDG_CONFIG_HOME support unclear and increased the risk that new app config files would pick a different path.

Decision

Tolaria resolves app-owned config files through one Rust helper that follows the XDG config location on Unix platforms and keeps the platform config directory as a read fallback.

All app-owned config JSON remains under the com.tolaria.app namespace:

${XDG_CONFIG_HOME:-$HOME/.config}/com.tolaria.app/settings.json
${XDG_CONFIG_HOME:-$HOME/.config}/com.tolaria.app/vaults.json
${XDG_CONFIG_HOME:-$HOME/.config}/com.tolaria.app/window-state.json
${XDG_CONFIG_HOME:-$HOME/.config}/com.tolaria.app/ai-provider-secrets.json

If XDG_CONFIG_HOME is missing on Unix platforms, Tolaria uses $HOME/.config. If XDG_CONFIG_HOME is relative, Tolaria ignores it and falls back to the next valid config root. Windows keeps using the platform config directory unless the user sets an absolute XDG_CONFIG_HOME.

Reads check the preferred Tolaria namespace first, then the legacy com.laputa.app namespace, and then the previous platform config directory when it differs from the XDG location. Writes always go to the Tolaria namespace under the preferred config root. The helper lives in src-tauri/src/app_config.rs, and app config consumers should call it instead of joining their own config root.

Options considered

• Use the XDG config home on Unix and preserve platform read fallback (chosen): makes dotfile-backed config explicit without changing the JSON file formats or stranding existing platform-config installs.
• Always force ~/.config on every platform: maximizes visible dotfile portability, but ignores OS conventions for users who have not opted into XDG config.
• Keep per-module path helpers: preserves the status quo, but makes future config files easy to place inconsistently.
• Move installation-local state into the vault: would sync more data, but would mix device preferences, credentials, and window state into user content.

Consequences

• Users can back up Tolaria's app config JSON alongside other dotfile-managed tools.
• Existing installs keep working because reads still check com.laputa.app and the previous platform config directory when no preferred XDG/Tolaria file exists.
• Relative XDG_CONFIG_HOME values are ignored so Tolaria does not write config relative to an arbitrary process working directory.
• New app-owned config files should use the shared Rust helper and document whether they are safe to back up. Secrets stay outside vaults and worktrees, but users who back up their XDG directory need to treat those files as sensitive.