docs(ax): fix misleading store usage examples

Co-Authored-By: Virgil <virgil@lethean.io>

scope.go

@@ -22,7 +22,7 @@ type QuotaConfig struct {
 	MaxGroups int
 }
 
-// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; if err := scopedStore.Set("config", "colour", "blue"); err != nil { return }`
+// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; if err := scopedStore.Set("colour", "blue"); err != nil { return }; if err := scopedStore.SetIn("config", "language", "en-GB"); err != nil { return }`
 type ScopedStore struct {
 	backingStore *Store
 	namespace    string
@@ -54,7 +54,7 @@ func (scopedStore *ScopedStore) resolvedStore(operation string) (*Store, error)
 	return scopedStore.backingStore, nil
 }
 
-// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a")`
+// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }`
 func NewScoped(storeInstance *Store, namespace string) *ScopedStore {
 	if storeInstance == nil {
 		return nil
@@ -99,7 +99,7 @@ func (scopedStore *ScopedStore) trimNamespacePrefix(groupName string) string {
 	return core.TrimPrefix(groupName, scopedStore.namespacePrefix())
 }
 
-// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; namespace := scopedStore.Namespace(); fmt.Println(namespace)`
+// Usage example: `scopedStore := store.NewScoped(storeInstance, "tenant-a"); if scopedStore == nil { return }; fmt.Println(scopedStore.Namespace())`
 func (scopedStore *ScopedStore) Namespace() string {
 	if scopedStore == nil {
 		return ""

store.go

@@ -13,12 +13,10 @@ import (
 	_ "modernc.org/sqlite"
 )
 
-// NotFoundError is returned when Get cannot find a live key.
-// Usage example: `if core.Is(err, store.NotFoundError) { return }`
+// Usage example: `if core.Is(err, store.NotFoundError) { fmt.Println("config/colour is missing") }`
 var NotFoundError = core.E("store", "not found", nil)
 
-// QuotaExceededError is returned when a scoped write would exceed quota.
-// Usage example: `if core.Is(err, store.QuotaExceededError) { return }`
+// Usage example: `if core.Is(err, store.QuotaExceededError) { fmt.Println("tenant-a is at quota") }`
 var QuotaExceededError = core.E("store", "quota exceeded", nil)
 
 const (
@@ -737,8 +735,9 @@ func (storeInstance *Store) PurgeExpired() (int64, error) {
 	return removedRows, nil
 }
 
-// New(":memory:") starts a background goroutine that calls PurgeExpired every
-// 60 seconds until Close stops the store.
+// New(":memory:", store.WithPurgeInterval(20*time.Millisecond)) starts a
+// background goroutine that calls PurgeExpired on that interval until Close
+// stops the store.
 func (storeInstance *Store) startBackgroundPurge() {
 	if storeInstance == nil {
 		return

workspace.go

@@ -35,7 +35,7 @@ var defaultWorkspaceStateDirectory = ".core/state"
 // 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()`
+// 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 {
 	name         string
 	backingStore *Store
@@ -63,9 +63,10 @@ func (workspace *Workspace) DatabasePath() string {
 	return workspace.databasePath
 }
 
-// Usage example: `if err := workspace.Close(); err != nil { return }`
-// Close releases the workspace database handle but keeps the on-disk file so a
+// Close leaves `.core/state/scroll-session-2026-03-30.duckdb` on disk so a
 // later store instance can recover it as an orphan.
+//
+// Usage example: `if err := workspace.Close(); err != nil { return }; orphans := storeInstance.RecoverOrphans(".core/state"); _ = orphans`
 func (workspace *Workspace) Close() error {
 	return workspace.closeWithoutRemovingFiles()
 }
@@ -97,9 +98,10 @@ func (workspace *Workspace) ensureReady(operation string) error {
 	return nil
 }
 
-// Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30")`
-// The workspace database file lives at `.core/state/scroll-session-2026-03-30.duckdb`
-// and is removed when the workspace is committed or discarded.
+// NewWorkspace creates `.core/state/scroll-session-2026-03-30.duckdb` and
+// removes it when the workspace is committed or discarded.
+//
+// Usage example: `workspace, err := storeInstance.NewWorkspace("scroll-session-2026-03-30"); if err != nil { return }; defer workspace.Discard()`
 func (storeInstance *Store) NewWorkspace(name string) (*Workspace, error) {
 	if err := storeInstance.ensureReady("store.NewWorkspace"); err != nil {
 		return nil, err
@@ -206,9 +208,11 @@ func workspaceNameFromPath(stateDirectory, databasePath string) string {
 	return core.TrimSuffix(relativePath, ".duckdb")
 }
 
-// RecoverOrphans(".core/state/") returns orphaned workspaces such as
-// `scroll-session.duckdb` so callers can inspect Aggregate() and then Discard().
-// Usage example: `orphans := storeInstance.RecoverOrphans(".core/state/")`
+// RecoverOrphans(".core/state") returns orphaned workspaces such as
+// `scroll-session-2026-03-30.duckdb` so callers can inspect Aggregate() and
+// choose Commit() or Discard().
+//
+// Usage example: `orphans := storeInstance.RecoverOrphans(".core/state"); for _, orphanWorkspace := range orphans { fmt.Println(orphanWorkspace.Name(), orphanWorkspace.Aggregate()) }`
 func (storeInstance *Store) RecoverOrphans(stateDirectory string) []*Workspace {
 	if storeInstance == nil {
 		return nil
@@ -292,7 +296,8 @@ func (workspace *Workspace) Aggregate() map[string]any {
 
 // Commit writes one journal point for the workspace and upserts the summary
 // row in `workspace:NAME`.
-// Usage example: `result := workspace.Commit()`
+//
+// Usage example: `result := workspace.Commit(); if !result.OK { return }; fmt.Println(result.Value)`
 func (workspace *Workspace) Commit() core.Result {
 	if err := workspace.ensureReady("store.Workspace.Commit"); err != nil {
 		return core.Result{Value: err, OK: false}