Configuration and Filesystem Paths

Forge is local-first and should follow XDG conventions on Linux.

Proposed paths

Use environment helpers rather than scattering path construction through packages.

$XDG_CONFIG_HOME/forge/        user/application configuration
$XDG_DATA_HOME/forge/          SQLite DB, raw logs, managed worktrees/artifacts
$XDG_STATE_HOME/forge/         durable runtime state if needed beyond DB
$XDG_CACHE_HOME/forge/         disposable caches

Fallback to the standard ~/.config, ~/.local/share, ~/.local/state, and ~/.cache locations when XDG variables are not set.

Example data layout:

data/
├── forge.db
├── runs/<run-id>/raw.jsonl
└── worktrees/<project-id>/<task-id>/

Configuration precedence

Keep precedence small and explicit when implemented. A reasonable eventual order is:

built-in defaults
  < user config
  < project Forge config (trusted and scoped)
  < per-run settings

Provider-native global/repo configuration remains owned by the provider/user. Forge does not silently write it.

Secrets

Prefer using provider-native authentication rather than duplicating tokens into Forge. If Forge later needs secrets of its own, add a deliberate secure-storage design rather than casually adding secret strings to config JSON/SQLite.