diff --git a/doc.go b/doc.go
index 5a5232d..dde961c 100644
--- a/doc.go
+++ b/doc.go
@@ -1,5 +1,6 @@
 // Package store provides SQLite-backed storage for grouped entries, TTL expiry,
-// namespace isolation, quota enforcement, and reactive change notifications.
+// namespace isolation, quota enforcement, reactive change notifications, and
+// workspace journalling.
 //
 // Usage example:
 //
@@ -61,5 +62,35 @@
 //			}
 //			fmt.Println(groupName)
 //		}
+//
+//		workspace, err := storeInstance.NewWorkspace("scroll-session")
+//		if err != nil {
+//			return
+//		}
+//		defer workspace.Discard()
+//
+//		if err := workspace.Put("like", map[string]any{"user": "@alice"}); err != nil {
+//			return
+//		}
+//		if err := workspace.Put("profile_match", map[string]any{"user": "@charlie"}); err != nil {
+//			return
+//		}
+//		if result := workspace.Commit(); !result.OK {
+//			return
+//		}
+//
+//		journalResult := storeInstance.QueryJournal(`from(bucket: "events") |> range(start: -24h)`)
+//		if !journalResult.OK {
+//			return
+//		}
+//
+//		archiveResult := storeInstance.Compact(store.CompactOptions{
+//			Before: time.Now().Add(-30 * 24 * time.Hour),
+//			Output: "/tmp/archive",
+//			Format: "gzip",
+//		})
+//		if !archiveResult.OK {
+//			return
+//		}
 //	}
 package store
diff --git a/workspace.go b/workspace.go
index ac1f8b8..bf4d1aa 100644
--- a/workspace.go
+++ b/workspace.go
@@ -32,8 +32,7 @@ FROM workspace_entries`
 
 var defaultWorkspaceStateDirectory = ".core/state"
 
-// Workspace accumulates mutable work-in-progress entries before they are
-// committed to the durable store journal.
+// Workspace is a temporary SQLite buffer for a named unit of work.
 // Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard()`
 type Workspace struct {
 	name          string
@@ -46,7 +45,7 @@ type Workspace struct {
 	closed    bool
 }
 
-// NewWorkspace creates a workspace state file under `.core/state/`.
+// NewWorkspace creates a temporary SQLite state file under `.core/state/`.
 // Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30")`
 func (storeInstance *Store) NewWorkspace(name string) (*Workspace, error) {
 	validation := core.ValidateName(name)