diff --git a/README.md b/README.md
index 7995d71..70a738e 100644
--- a/README.md
+++ b/README.md
@@ -185,6 +185,11 @@ o read state      # → session/mysession/agent/myagent/state
 o prompt          # REPL for session/mysession/agent/myagent
 ```
 
+Paths resolve based on context — agent files (`state`, `chat`, `prompt`, etc.)
+use `$session` + `$agent`, session files (`env`, `ctl`, `name`) use just
+`$session`, root paths (`models`, `agents`, `help`) need no context. Full
+paths starting with `session/` bypass resolution entirely.
+
 ### `o tui`: an agent terminal in 20 lines of tmux
 
 `o tui` composes `o tail` and `o prompt` into a single tmux layout — no