# ADR-0031: Sessions and preferences, split by owner, out of tree

- **Status:** Accepted
- **Date:** 2026-07-01
- **Deciders:** jka
- **Decision:** D31

## Context

Launching rio on a project should bring back how the editor looked and which files
were open. ADR-0021 grouped "recent files, window and pane sizes, open tabs" as
session state and sketched storing it in the project's `.rio/` directory. After
ADR-0030 the core may run on another machine, so who owns each piece of that state
matters.

## Decision

The state is split by owner.

- **Preferences** (theme, wrap, dock layout, pane visibility and similar) are pure
  view state. The GUI owns them and writes `$XDG_CONFIG_HOME/rio/prefs.json`. Each
  setting is saved through the single applier that sets it. A missing or corrupt
  file, or a stored value that no longer exists, falls back to defaults.
- **The workspace** (open files in tab order and the active tab) is per project and
  document-related. The core owns it through `workspace.save` and `workspace.get`,
  storing it under `$XDG_DATA_HOME/rio/sessions/<md5-of-root>.json`.
  `workspace.get` drops paths that no longer exist.

Session state is kept out of the project tree. Window geometry and pane pixel
sizes were deferred at first; dock sizes were added to the layout later
(ADR-0035).

## Consequences

- Resume works over a remote core, because the workspace store lives with the core
  and its files.
- Session files never appear in `git status` and cannot be committed by accident.
- Neither store holds a secret.
- Booting the GUI now writes to XDG directories, so every GUI test must redirect
  XDG to a throwaway directory (`rio-gui/tests/sandbox.tcl`).
- ADR-0072 extended the workspace to the no-project case, ADR-0088 remembered the
  last folder, and ADR-0089 added the unfolded tree shape.