From d78fe997dadfcdbfc1215bbb76b7b309271bd1cc Mon Sep 17 00:00:00 2001
From: Ollie Agent <ollie@example.com>
Date: Tue, 4 Aug 2026 19:23:24 +0200
Subject: [PATCH] usage: document path resolution rules

---
 doc/usage.md | 19 +++++++++++++++++++
 1 file changed, 19 insertions(+)

diff --git a/doc/usage.md b/doc/usage.md
index 4509ccb..e9ea1e7 100644
--- a/doc/usage.md
+++ b/doc/usage.md
@@ -77,6 +77,25 @@ o read state       # → session/myproject/agent/default/state
 o readloop statewait
 ```
 
+### Path resolution
+
+Paths are slash-delimited 9P namespace paths. The `o` CLI resolves them based
+on context:
+
+| Path type | Example | Resolves to |
+|---|---|---|
+| Root-level | `o read models` | `models` (no context needed) |
+| Agent file | `o read state` | `session/$session/agent/$agent/state` |
+| Session file | `o read env` | `session/$session/env` |
+| Full path | `o read session/foo/agent/bar/chat` | Used as-is |
+
+Root-level paths (`session/`, `agents`, `models`, `help`, `ctl`, `tools`) and
+absolute paths (starting with `session/`) bypass context resolution entirely.
+Agent-level files (`chat`, `state`, `prompt`, `statewait`, `cfg`, `plan`,
+`log`, `cost`, `offset`, `context`, `systemprompt`) require both `$session`
+and `$agent`. Session-level files (`env`, `ctl`, `id`, `name`, `paused`)
+require only `$session`.
+
 ### Prompt REPL
 
 `o prompt` is an interactive multi-line REPL with readline editing: