ADR-0114: A project is one root folder held by the core

• Status: Accepted
• Date: 2026-06-27
• Deciders: jka
• Decision: no D number

Context

Git operations relied on the core process's working directory, and the file tree and the per-project .rio/ directory needed an anchor. "The project" was an accident of how rio was launched rather than an explicit fact.

Decision

The core holds one canonical project root (rio-core/project.tcl).

• project.open {path} validates a directory, records its normalised absolute path, and emits project.opened, so every view resynchronises through one event.
• project.get returns the root, or an empty string when no project is open.
• rio::project::resolve defines what frontends mean by a path: empty is the root, relative is joined onto the root, absolute is used as given.
• git.* operations default their working directory to the root; fs.list lists relative to it; agent tools and commands are confined to it.
• A workspace is single-root, matching one folder and usually one git repository.

fs.list {?path?} lists one directory per call, dictionary-sorted, following symbolic links for the type, and including dotfiles; hiding them is a frontend choice (ADR-0062). The procedure is named listdir because a procedure called list would shadow Tcl's list inside the namespace.

Consequences

• The project is an explicit, queryable fact, and it lives with the core, so it is correct over a remote core.
• Sessions (ADR-0031), the last-folder pointer (ADR-0088) and project prompts and allow-lists key on it. With no project open, rio still works (ADR-0072).
• Multi-root workspaces are not supported. They could be added later without changing this interface.