1 files changed, 25 insertions, 1 deletions
diff --git a/docs/phase-4.md b/docs/phase-4.md
index af68cca..6c4f9b9 100644
--- a/docs/phase-4.md
+++ b/docs/phase-4.md
@@ -32,7 +32,31 @@ A session persistence system where pantograph saves and resumes conversations. A
 - Custom entry types (for extensions — future phase)
 - Labels, bookmarks, session naming
 - Session export or format migration beyond version 1
-- In-memory-only sessions (every session is persisted)
+- In-memory-only sessions from the CLI (every CLI session is persisted; libpanto embedders can opt out by passing a no-op store)
+
+---
+
+## Library / CLI Boundary
+
+The storage interface lives in libpanto. The default `fs_jsonl` implementation also lives in libpanto. The CLI decides _where_ a session is stored and constructs the store with that path.
+
+### libpanto owns
+
+- The `SessionStore` interface (vtable: append entry, load entries, etc.).
+- An `fs_jsonl` implementation that takes a base directory at construction time and writes the JSONL format defined below.
+- The agent loop's interaction with the store: which events get appended, at what points in a turn.
+
+### CLI owns
+
+- Selecting the base directory: XDG resolution (`$XDG_DATA_HOME` or `~/.local/share`), the `panto/sessions/` subpath, and the per-project `<encoded-cwd>/` grouping.
+- Selecting the session file: new-file-per-invocation by default; `--resume` / `--resume <id>` to pick an existing file.
+- Constructing `fs_jsonl` with the resolved directory and passing it to libpanto.
+
+Other embedders (a TUI, a daemon, a Lua host, a test harness) bring their own directory policy or their own `SessionStore` implementation. A no-op store is a valid choice for embedders that don't want persistence.
+
+### Mid-turn writes
+
+The in-memory `Conversation` is the source of truth during a turn. The store is written between discrete events — never as an inline dependency of streaming. A crash mid-turn loses the in-flight assistant message but never corrupts prior state. (Phase 4 writes per-message; finer-grained streaming-event entries are out of scope.)
 
 ---