From fd6f1fe80a3ea5fa81e4826ae10f36005d267ff8 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Sat, 4 Apr 2026 17:05:51 +0000
Subject: [PATCH] docs(store): sharpen agent-facing examples

Co-Authored-By: Virgil <virgil@lethean.io>
---
 compact.go   | 6 +++---
 workspace.go | 3 ++-
 2 files changed, 5 insertions(+), 4 deletions(-)

diff --git a/compact.go b/compact.go
index b229dc5..bcb3cb4 100644
--- a/compact.go
+++ b/compact.go
@@ -14,7 +14,7 @@ var defaultArchiveOutputDirectory = ".core/archive/"
 // CompactOptions archives completed journal rows before a cutoff time to a
 // compressed JSONL file.
 //
-// Usage example: `options := store.CompactOptions{Before: time.Now().Add(-90 * 24 * time.Hour), Output: "/tmp/archive", Format: "gzip"}`
+// Usage example: `options := store.CompactOptions{Before: time.Date(2026, 3, 30, 0, 0, 0, 0, time.UTC), Output: "/tmp/archive", Format: "gzip"}`
 // The default output directory is `.core/archive/`; the default format is
 // `gzip`, and `zstd` is also supported.
 type CompactOptions struct {
@@ -26,7 +26,7 @@ type CompactOptions struct {
 	Format string
 }
 
-// Usage example: `normalisedOptions := (store.CompactOptions{Before: time.Now().Add(-30 * 24 * time.Hour)}).Normalised()`
+// Usage example: `normalisedOptions := (store.CompactOptions{Before: time.Date(2026, 3, 30, 0, 0, 0, 0, time.UTC)}).Normalised()`
 func (compactOptions CompactOptions) Normalised() CompactOptions {
 	if compactOptions.Output == "" {
 		compactOptions.Output = defaultArchiveOutputDirectory
@@ -37,7 +37,7 @@ func (compactOptions CompactOptions) Normalised() CompactOptions {
 	return compactOptions
 }
 
-// Usage example: `if err := (store.CompactOptions{Before: time.Now().Add(-30 * 24 * time.Hour), Format: "gzip"}).Validate(); err != nil { return }`
+// Usage example: `if err := (store.CompactOptions{Before: time.Date(2026, 3, 30, 0, 0, 0, 0, time.UTC), Format: "gzip"}).Validate(); err != nil { return }`
 func (compactOptions CompactOptions) Validate() error {
 	switch compactOptions.Format {
 	case "", "gzip", "zstd":
diff --git a/workspace.go b/workspace.go
index cdb47bb..c99ae2f 100644
--- a/workspace.go
+++ b/workspace.go
@@ -34,7 +34,7 @@ FROM workspace_entries`
 var defaultWorkspaceStateDirectory = ".core/state/"
 
 // Workspace keeps mutable work-in-progress in a SQLite file such as
-// `.core/state/scroll-session.duckdb` until Commit or Discard removes it.
+// `.core/state/scroll-session.duckdb` until Commit() or Discard() removes it.
 //
 // Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard(); _ = workspace.Put("like", map[string]any{"user": "@alice"})`
 type Workspace struct {
@@ -68,6 +68,7 @@ func (workspace *Workspace) DatabasePath() string {
 // Close keeps the workspace file on disk so `RecoverOrphans(".core/state/")`
 // can reopen it later.
 //
+// Usage example: `if err := workspace.Close(); err != nil { return }`
 // Usage example: `if err := workspace.Close(); err != nil { return }; orphans := storeInstance.RecoverOrphans(".core/state"); _ = orphans`
 func (workspace *Workspace) Close() error {
 	return workspace.closeWithoutRemovingFiles()