diff --git a/doc.go b/doc.go
index b02d930..bc5c6b1 100644
--- a/doc.go
+++ b/doc.go
@@ -2,6 +2,9 @@
 // namespace isolation, quota enforcement, reactive change notifications,
 // workspace journalling, and explicit orphan recovery.
 //
+// Workspace files are created under `.core/state/` and can be recovered with
+// `RecoverOrphans(".core/state")`.
+//
 // Prefer `store.NewConfigured(store.StoreConfig{...})` when constructing a
 // store from an agent-written configuration literal.
 //
diff --git a/workspace.go b/workspace.go
index 3edbf5d..8717013 100644
--- a/workspace.go
+++ b/workspace.go
@@ -32,7 +32,8 @@ FROM workspace_entries`
 
 var defaultWorkspaceStateDirectory = ".core/state"
 
-// Workspace buffers mutable work-in-progress in a temporary database file.
+// Workspace buffers mutable work-in-progress in `.core/state/scroll-session.duckdb`
+// until Commit or Discard removes the file.
 //
 // Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard()`
 type Workspace struct {