phase 1 done

2 files changed, 27 insertions, 1 deletions

diff --git a/docs/phase-1.md b/docs/phase-1.md
index 8acaf42..6b149aa 100644
--- a/docs/phase-1.md
+++ b/docs/phase-1.md
@@ -1,5 +1,7 @@
 # Phase 1: libpanto — Minimal Chat Library
 
+**Status: complete.** Streaming chat works end-to-end against OpenAI-compatible APIs; conversation history persists across turns; thinking blocks (`reasoning_content` / `reasoning`) are streamed; `reasoning_effort` is configurable. Open questions resolved: thinking support implemented; mid-stream errors propagate via Zig errors; connections are one-per-turn intentionally (uniform reentry into each turn); long-conversation memory deferred to a later phase. Session persistence is phase 4.
+
 ## Goal
 
 A Zig library that can hold a streaming conversation with an LLM via an OpenAI-compatible API. No tools, no extensions — just chat. Includes a minimal CLI for live testing.
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.)
 
 ---