Problem #
Trawler currently resolves its graph directory in this order:
TRAWLER_GRAPH_DIR%APPDATA%\trawler\graph- relative
trawler-graph
The final fallback means macOS and Linux can create a graph under the process working directory—including inside the source checkout. Users must know to set an environment variable, and launching from different directories can silently produce different graphs.
Desired behavior #
- Preserve
TRAWLER_GRAPH_DIRas the highest-precedence explicit override. - Otherwise use the platform's native per-user data location:
- Windows:
%APPDATA%\trawler\graph - macOS:
~/Library/Application Support/trawler/graph - Linux:
$XDG_DATA_HOME/trawler/graph, falling back to~/.local/share/trawler/graph
- Windows:
- Never create the default graph relative to the current working directory.
- Handle an existing legacy
./trawler-graphconservatively: detect it and give the user an explicit migration/open choice rather than silently moving or abandoning data. - Make the resolved graph location visible in diagnostics.
- Cover path precedence and platform fallbacks with deterministic tests.
Out of scope #
- Graph picker / recent-graph UI
- Syncing graphs between devices
- Development scratch graphs; the Nix preview workflow handles those separately
Source #
Originally raised by Ariel M. (@byarielm.fyi) in the UserInput discussion. The thread distinguishes safe cross-platform defaults from a future graph-picker UX, which should remain a separate issue.
Spec-shaping decision: use compatibility-first legacy handling. When only a recognized
./trawler-graphexists, Trawler will keep opening it and emit an actionable warning naming the preferred native path. When distinct native and legacy graphs both exist, startup will refuse to guess and require an explicitTRAWLER_GRAPH_DIR. No graph is copied or moved automatically, and graph-picker UX remains a separate issue. This supersedes the issue draft's earlier suggestion of an explicit startup chooser; the OpenSpec packet was reviewed and approved before implementation.