@asaidimu/utils-workspace 1.0.0 → 2.0.0

package/README.md

@@ -1,13 +1,13 @@
 # @asaidimu/utils-workspace
 
-Content-addressed workspace and conversation management for AI applications. Handles roles, preferences, context, transcripts, and binary blobs with a unified storage model.
+Content-addressed workspace and conversation management for AI applications.
 
 [![npm version](https://img.shields.io/npm/v/@asaidimu/utils-workspace.svg)](https://www.npmjs.com/package/@asaidimu/utils-workspace)
-[![license](https://img.shields.io/npm/l/@asaidimu/utils-workspace.svg)](LICENSE)
-[![build status](https://img.shields.io/github/actions/workflow/status/asaidimu/utils-workspace/ci.yml)](https://github.com/asaidimu/utils-workspace/actions)
-[![typescript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
+[![License](https://img.shields.io/npm/l/@asaidimu/utils-workspace.svg)](https://github.com/asaidimu/erp-utils/blob/main/src/workspace/LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
+[![Vitest](https://img.shields.io/badge/tested%20with-Vitest-6e9f18)](https://vitest.dev/)
 
-## Table of Contents
+## 📚 Table of Contents
 
 - [Overview & Features](#overview--features)
 - [Installation & Setup](#installation--setup)
@@ -20,20 +20,20 @@ Content-addressed workspace and conversation management for AI applications. Han
 
 ## Overview & Features
 
-**@asaidimu/utils-workspace** provides a complete solution for managing conversational state in AI applications. Built on a content-addressed storage model, it handles everything from role definitions and user preferences to session transcripts and binary blobs. The library separates concerns between index state (fast, always in memory) and content storage (asynchronous, backend-agnostic), enabling efficient operation in both browser and Node.js environments.
+`@asaidimu/utils-workspace` is a TypeScript library that powers AI‑assisted workspaces. It provides a complete solution for managing content‑addressed binary blobs, conversation transcripts with branching and editing, workspace state (roles, preferences, context), and token‑aware prompt assembly. The library is built to be **backend‑agnostic** (supports both in‑memory and IndexedDB persistence) and **offline‑first** by default.
 
-The system implements a command-reducer pattern where state mutations are expressed as commands that produce patches. This design enables optimistic UI updates, offline-first operation, and easy persistence snapshots. Blob management uses SHA-256 content addressing for automatic deduplication, ref counting, and remote ID tracking across providers like Anthropic or OpenAI.
+Why this library? Modern AI applications need to handle large binary attachments (images, documents) efficiently, support non‑linear conversations (branching, editing), and respect token budgets when sending prompts to LLMs. `@asaidimu/utils-workspace` solves these challenges with a content‑addressed storage model, a turn DAG, and a pluggable prompt builder.
 
 ### Key Features
 
-- **Content-Addressed Blob Storage** — SHA-256 based deduplication, reference counting, and atomic storage with IndexedDB or memory backends
-- **Turn-Based Transcripts** — Versioned conversation trees with branching, editing, and subtree deletion
-- **Rich Content Blocks** — Support for text, images, documents, tool use, and thinking blocks with token estimation
-- **Preference & Context Management** — Conflict resolution with timestamps, topic-based filtering, and relevance scoring with freshness decay
-- **Prompt Building** — Token budget allocation, transcript summarization, and context ranking that produces provider-agnostic prompts
-- **Multiple Storage Backends** — IndexedDB for browsers, MemoryStorage for testing and server-side use
-- **TypeScript First** — Full type definitions with strict mode compatibility
-- **Offline-Ready** — Dirty buffer management with configurable flush strategies and optimistic updates
+- **Content‑Addressed Blob Storage** – Store blobs by SHA‑256 hash; automatic deduplication and reference counting.
+- **Blob Lifecycle Management** – Ref counting with lazy eviction and explicit garbage collection. Record remote file IDs after upload to providers.
+- **Turn Tree & Session Management** – Maintain conversation trees with parent/child relationships, edits, and branching. Auto‑link parent turns when appending.
+- **Dirty Buffer & Auto‑Flush** – Buffer unsaved turns in memory and flush when a size threshold is reached or on session close.
+- **Token‑Aware Prompt Building** – Build prompts with a pluggable token planner, context retriever (Jaccard similarity + freshness), and summarizer. Allocate budget across instructions, persona, preferences, transcript, and context.
+- **Pluggable Components** – Swap context retriever, token planner, summarizer, and assembler to fit your use case.
+- **Multi‑Backend Support** – `MemoryStorage` / `MemoryBlobStorage` for development/testing, `IndexedDBStorage` / `IndexedDBBlobStorage` for persistent browser storage.
+- **Workspace Commands & Reducer** – Manage index state via a pure reducer; side effects are handled by `WorkspaceManager`.
 
 ---
 
@@ -41,8 +41,8 @@ The system implements a command-reducer pattern where state mutations are expres
 
 ### Prerequisites
 
-- Node.js 18+ (for server-side usage) or modern browser with Web Crypto API support
-- TypeScript 5.0+ (optional, for type safety)
+- Node.js 18+ or a modern browser with IndexedDB support.
+- TypeScript 5.0+ (if using in a TS project).
 
 ### Installation
 
@@ -50,55 +50,37 @@ The system implements a command-reducer pattern where state mutations are expres
 npm install @asaidimu/utils-workspace
 ```
 
-or with yarn:
-
-```bash
-yarn add @asaidimu/utils-workspace
-```
+### Configuration
 
-### Basic Setup
+The library works out of the box with in‑memory storage. For persistence, set up IndexedDB backends:
 
 ```typescript
-import {
-  IndexedDBStorage,
-  ContentStore,
-  WorkspaceManager,
-  PromptBuilder,
-  MemoryBlobStorage,
-  BlobStore
-    merge,
-} from '@asaidimu/utils-workspace';
-
-// Initialize content storage (IndexedDB for persistence)
+import { IndexedDBStorage, IndexedDBBlobStorage, ContentStore, BlobStore, WorkspaceManager } from '@asaidimu/utils-workspace';
+
+// Persistent content storage
 const contentBackend = new IndexedDBStorage({ dbName: 'my-workspace' });
 await contentBackend.open();
 
-// Initialize blob storage (memory for this example, IndexedDB also available)
-const blobBackend = new MemoryBlobStorage();
-const blobStore = new BlobStore(blobBackend);
-await blobStore.init();
+// Persistent blob storage
+const blobBackend = new IndexedDBBlobStorage({ dbName: 'my-workspace-blobs' });
+await blobBackend.open();
 
-// Create content store with default configuration
-const contentStore = new ContentStore(contentBackend);
+// Create stores with custom config
+const contentStore = new ContentStore(contentBackend, {
+  cache: { roles: 10, preferences: 50, contextEntries: 20 },
+  flush: { maxBufferSize: 20, flushIntervalMs: 30000 },
+});
+
+const blobStore = new BlobStore(blobBackend, { eagerEviction: false });
+await blobStore.init();
 
-// Create workspace manager
 const manager = new WorkspaceManager(contentStore);
+```
 
-// Initialize empty index state
-const emptyState = {
-  format: 'aiworkspace/4.0',
-  workspace: {
-    id: 'ws-1',
-    settings: { language: 'en', defaultRole: 'assistant' },
-    project: { name: 'My Project', owner: 'user' },
-    indexes: { sessions: {}, roles: {}, preferences: {}, context: {}, topics: {} }
-  },
-  roles: {},
-  blobs: {},
-  preferences: {},
-  context: {},
-  sessions: {}
-};
+### Verification
+
+```typescript
+console.log(manager instanceof WorkspaceManager); // true
 ```
 
 ---
@@ -107,239 +89,189 @@ const emptyState = {
 
 ### Basic Usage
 
-Create a role, session, and add a turn:
+Create a workspace, add a role, create a session, and append a turn.
 
 ```typescript
-let indexState = emptyState;
+import { emptyIndexState, merge, WorkspaceManager, MemoryStorage, ContentStore } from '@asaidimu/utils-workspace';
+
+let workspace = {
+  id: 'ws-1',
+  settings: { language: 'en', defaultRole: 'assistant' },
+  project: { name: 'My Project', owner: 'me' },
+  index: emptyIndexState(),
+};
+
+const backend = new MemoryStorage();
+const contentStore = new ContentStore(backend);
+const manager = new WorkspaceManager(contentStore);
 
-// 1. Add a role
-const addRoleCmd = {
-  type: 'role:add' as const,
+// Add a role
+const roleCmd = {
+  type: 'role:add',
   timestamp: new Date().toISOString(),
   payload: {
-    id: 'role-1',
+    id: 'r1',
     name: 'assistant',
     label: 'Assistant',
     persona: 'You are a helpful assistant.',
-    preferences: []
-  }
+    preferences: [],
+  },
 };
+const roleResult = await manager.dispatch(workspace, roleCmd);
+if (roleResult.ok) workspace = merge(workspace, roleResult.value);
 
-const roleResult = await manager.dispatch(indexState, addRoleCmd);
-if (roleResult.ok) {
-  // Merge the patch into your state
-  indexState = merge(indexState, roleResult.value) ;
-}
-
-// 2. Create a session
-const createSessionCmd = {
-  type: 'session:create' as const,
+// Create a session
+const sessionCmd = {
+  type: 'session:create',
   timestamp: new Date().toISOString(),
-  payload: {
-    id: 'session-1',
-    label: 'My First Conversation',
-    role: 'assistant',
-    topics: ['general'],
-    preferences: []
-  }
+  payload: { id: 's1', label: 'First Chat', role: 'assistant', topics: [] },
 };
+const sessionResult = await manager.dispatch(workspace, sessionCmd);
+if (sessionResult.ok) workspace = merge(workspace, sessionResult.value);
+```
 
-const sessionResult = await manager.dispatch(indexState, createSessionCmd);
-if (sessionResult.ok) {
-  indexState = merge(indexState, sessionResult.value) ;
-}
+### Session Management (with SessionManager)
+
+`SessionManager` provides a live `Session` object with turn tree operations.
+
+```typescript
+import { SessionManager } from '@asaidimu/utils-workspace';
 
-// 3. Activate the session (enables dirty buffer for performance)
-await manager.activateSession(indexState, 'session-1');
+const sessionManager = new SessionManager(manager, contentStore);
+const openResult = await sessionManager.open(workspace, 's1');
+if (!openResult.ok) throw new Error('Failed to open session');
 
-// 4. Add a turn
-const addTurnCmd = {
-  type: 'turn:add' as const,
+const { session } = openResult.value;
+
+// Add a turn (auto‑links parent to current head)
+const turn = {
+  id: crypto.randomUUID(),
+  version: 0,
+  role: 'user',
+  blocks: [{ type: 'text', text: 'Hello, world!' }],
   timestamp: new Date().toISOString(),
-  payload: {
-    sessionId: 'session-1',
-    turn: {
-      id: 'turn-1',
-      version: 0,
-      role: 'user',
-      blocks: [{ type: 'text', text: 'Hello, how are you?' }],
-      timestamp: new Date().toISOString(),
-      roleSnapshot: 'assistant',
-      parent: null
-    }
-  }
+  parent: null,
 };
+const addResult = await session.addTurn(workspace, turn);
+if (addResult.ok) workspace = merge(workspace, addResult.value);
 
-await manager.dispatch(indexState, addTurnCmd);
-await manager.flush(); // Persist dirty buffer to storage
+// Flush buffered turns to storage
+await session.flush();
+
+// Close session when done
+await sessionManager.close(session);
 ```
 
-### Registering and Using Blobs
+### Blob Registration & Resolution
 
 ```typescript
-// Register a blob (e.g., an image or document)
-const imageData = new TextEncoder().encode('fake-image-data');
-const blobResult = await blobStore.register(imageData, 'image/jpeg', 'photo.jpg');
-
-if (blobResult.ok) {
-  const blobRef = blobResult.value;
-  
-  // Use the blob in a turn
-  const turnWithBlob = {
-    id: 'turn-2',
-    version: 0,
-    role: 'user',
-    blocks: [
-      { type: 'text', text: 'What is in this image?' },
-      { type: 'image', blob: blobRef }
-    ],
-    timestamp: new Date().toISOString(),
-    roleSnapshot: 'assistant',
-    parent: null
-  };
-  
-  await manager.dispatch(indexState, {
-    type: 'turn:add',
-    timestamp: new Date().toISOString(),
-    payload: { sessionId: 'session-1', turn: turnWithBlob }
-  });
-}
-```
+import { BlobStore, MemoryBlobStorage } from '@asaidimu/utils-workspace';
 
-### Building Prompts
+const blobStorage = new MemoryBlobStorage();
+const blobStore = new BlobStore(blobStorage);
+await blobStore.init();
 
-```typescript
-// Resolve the session to get effective preferences, context, and transcript
-const resolved = await manager.resolveSession(indexState, 'session-1');
-
-if (resolved.ok) {
-  // Resolve all blobs in the session
-  const refs = resolved.value.transcript
-    .flatMap(t => t.blocks.filter(b => b.type === 'image' || b.type === 'document'))
-    .map(b => b.blob);
-  
-  const { resolved: resolvedBlobs, errors } = await blobStore.resolveRefs(refs, null);
-  
-  // Build the prompt
-  const builder = new PromptBuilder();
-  const prompt = await builder.build(resolved.value, {
-    resolvedBlobs,
-    tokenBudget: { total: 4000 }
-  });
-  
-  console.log(prompt.system); // System prompt with persona, preferences, context
-  console.log(prompt.turns);   // Conversation turns with resolved blobs
+const data = new TextEncoder().encode('Content of a document');
+const registerResult = await blobStore.register(data, 'text/plain', 'readme.txt');
+if (registerResult.ok) {
+  const blobRef = registerResult.value;
+  // Use blobRef in a turn or context block
+}
+
+// Later, resolve the blob for a prompt
+const resolveResult = await blobStore.resolveRef(blobRef, null);
+if (resolveResult.ok) {
+  const resolved = resolveResult.value;
+  if (resolved.kind === 'inline') {
+    console.log(new TextDecoder().decode(resolved.data));
+  }
 }
 ```
 
-### Configuration
+### Building a Prompt
 
-**ContentStore Configuration**
+`PromptBuilder` assembles a token‑aware prompt from an `EffectiveSession`.
 
 ```typescript
-const contentStore = new ContentStore(backend, {
-  cache: {
-    roles: 10,              // Max roles in LRU cache
-    preferences: 50,        // Max preferences in LRU cache
-    contextEntries: 20,     // Max context entries in LRU cache
-    transcriptWindows: 3    // Max transcript windows in LRU cache
-  },
-  flush: {
-    maxBufferSize: 10,      // Auto-flush after 10 turns
-    flushIntervalMs: 30000  // Auto-flush every 30 seconds
-  },
-  transcriptWindowSize: 20  // Default turns per window
+import { PromptBuilder } from '@asaidimu/utils-workspace';
+
+const builder = new PromptBuilder({
+  blobResolver: blobStore.resolveRefs.bind(blobStore),
 });
-```
 
-**BlobStore Configuration**
+const effective = await manager.resolveSession(workspace, 's1');
+if (!effective.ok) throw new Error('Failed to resolve session');
 
-```typescript
-const blobStore = new BlobStore(backend, {
-  eagerEviction: false  // When false, blobs with refCount 0 persist until gc()
+const prompt = await builder.build(effective.value, {
+  tokenBudget: { total: 4000 },
+  relevanceConfig: { recentMessageWindow: 5, minScore: 0.2 },
+  providerId: 'anthropic', // for remote blobs
 });
-```
-
-**IndexedDB Configuration**
 
-```typescript
-const contentBackend = new IndexedDBStorage({ dbName: 'custom-db-name' });
-const blobBackend = new IndexedDBBlobStorage({ dbName: 'custom-blob-db' });
+console.log(prompt.system.instructions);
+console.log(prompt.transcript.turns);
+console.log(prompt.warnings);
 ```
 
----
-
-## Project Architecture
-
-### Core Components
-
-**IndexState** — The in-memory representation of the workspace. Contains summaries of all entities (roles, preferences, contexts, sessions, blobs) and is designed for fast reads. State mutations produce patches that can be merged optimistically.
+### Common Use Cases
 
-**ContentStore** — Manages asynchronous access to persisted content. Implements LRU caching with pinning for active sessions, dirty buffer management for turns, and maintains the distinction between index state and full content.
+#### 1. Offline‑First Chat Application
 
-**WorkspaceManager** — The public facade that coordinates between commands, reducer, and content persistence. Handles side effects (saving to storage) while keeping the reducer pure.
+- Use `IndexedDBStorage` and `IndexedDBBlobStorage` for persistence.
+- Set `eagerEviction: false` to keep blobs until manually cleaned.
+- Let `ContentStore` auto‑flush when `maxBufferSize` is reached.
+- Call `blobStore.gc()` occasionally to reclaim space.
 
-**BlobStore** — Content-addressed blob management with SHA-256 deduplication, reference counting, remote ID tracking, and resolution between inline and remote blob references.
+#### 2. Multi‑Session Workspace with Topic‑Based Context
 
-**PromptBuilder** — Transforms an EffectiveSession into a provider-agnostic prompt structure with token budgeting, preference conflict resolution, context ranking, and optional summarization.
+- Create context entries with topics.
+- Use `session:topics:add` command to associate topics with a session.
+- `resolveSession` automatically pulls in context entries that match those topics.
 
-**Storage Backends** — Pluggable storage layers:
-- **MemoryStorage** — In-memory implementation for testing
-- **IndexedDBStorage** — Persistent browser storage for content
-- **MemoryBlobStorage** — In-memory blob storage
-- **IndexedDBBlobStorage** — Persistent browser storage for blobs
+#### 3. Branching Conversations
 
-### Data Flow
+- Use `session.branchFrom()` to fork a conversation tree.
+- Each branch maintains its own head pointer.
+- Fork an entire session with the `session:fork` command.
 
-```
-Command → WorkspaceManager.dispatch()
-    ↓
-WorkspaceReducer (pure patch generation)
-    ↓
-ContentStore (side effects: save roles, preferences, turns, etc.)
-    ↓
-Storage Backend (IndexedDB / Memory)
-```
+#### 4. Integrating with AI Providers
 
-For resolution and prompt building:
+- After uploading a blob to a provider (e.g., Anthropic), record the remote ID:
+  ```typescript
+  await blobStore.recordRemoteId(sha256, 'anthropic', 'file_abc123');
+  ```
+- In `PromptBuilder.build`, pass the `providerId` to get remote references instead of inline bytes.
 
-```
-IndexState + SessionId → ContentStore.resolveSession()
-    ↓ (async content loading)
-EffectiveSession → BlobStore.resolveRefs()
-    ↓ (blob resolution)
-PromptBuilder.build()
-    ↓ (token budgeting, summarization)
-Prompt (system, turns, warnings)
-```
+---
 
-### Extension Points
+## Project Architecture
 
-**Custom Storage Backends** — Implement the `ContentStorage` or `BlobStorage` interfaces to support alternative persistence (SQLite, cloud storage, etc.)
+### Core Components
 
-**Summarizer** — Inject a custom summarizer into `PromptBuilder` for transcript compression:
+- **`WorkspaceManager`** – Facade that coordinates the pure reducer, content side effects, and session resolution.
+- **`ContentStore`** – Manages roles, preferences, context, and transcript windows. Handles LRU caching, dirty buffers, and session activation.
+- **`BlobStore`** – Owns the blob registry (ref counts, remote IDs) and SHA‑256 computation. Interacts with a `BlobStorage` backend.
+- **`TurnTree`** – Pure logic for turn chains, subtree deletion, and head management. Used by `ContentStore` and `Session`.
+- **`Session`** – Live object for an open session. Holds the turn DAG and dirty buffer, provides mutation methods (`addTurn`, `editTurn`, `branchFrom`, `deleteTurn`, `switchLeft`/`Right`).
+- **`SessionManager`** – Entry point for opening and closing sessions; loads the turn DAG from storage.
+- **`PromptBuilder`** – Orchestrates context retrieval, token planning, blob resolution, and final assembly.
+- **Storage backends** – `MemoryStorage`, `IndexedDBStorage` (content), `MemoryBlobStorage`, `IndexedDBBlobStorage` (blobs).
 
-```typescript
-interface Summarizer {
-  summarize(transcript: Turn[], tokenBudget: number): Promise<{
-    summary: string;
-    remaining: Turn[];
-  }>;
-}
+### Data Flow
 
-const builder = new PromptBuilder(myCustomSummarizer);
-```
+1. **User action** → `WorkspaceManager.dispatch(command)`.
+2. **Reducer** produces a `DeepPartial<Workspace>` patch and schedules side effects.
+3. **Side effects** write to `ContentStore` (roles, preferences, context, turns via `TurnTree`).
+4. **Session activation** loads the turn DAG via `TurnTree.buildNodeGraph()`.
+5. **Turn mutations** update the in‑memory `Session.nodes` and dirty buffer; auto‑flush writes to storage when buffer size exceeds threshold.
+6. **Prompt building** retrieves an `EffectiveSession` (via `Session.resolve` or `ContentStore.resolveSession`), ranks context, plans token usage, resolves blobs, and assembles the final `Prompt`.
 
-**Token Estimators** — Override the default text estimator for provider-specific token counting:
+### Extension Points
 
-```typescript
-const prompt = await builder.build(session, {
-  tokenBudget: {
-    total: 8000,
-    estimator: (text) => myProviderTokenCounter.count(text)
-  }
-});
-```
+- **`ContextRetriever`** – Replace the default Jaccard‑based retriever with a vector or hybrid approach.
+- **`TokenPlanner`** – Implement custom token estimation (e.g., using tiktoken) and priority strategies.
+- **`Summarizer`** – Hook into an LLM to compress transcripts.
+- **`BlobStorage` / `ContentStorage`** – Add new backends (e.g., S3, SQLite) by implementing the interface.
 
 ---
 
@@ -348,59 +280,51 @@ const prompt = await builder.build(session, {
 ### Development Setup
 
 1. Clone the repository:
-```bash
-git clone https://github.com/asaidimu/utils-workspace.git
-cd utils-workspace
-```
-
+   ```bash
+   git clone https://github.com/asaidimu/erp-utils.git
+   cd erp-utils/src/workspace
+   ```
 2. Install dependencies:
-```bash
-npm install
-```
-
+   ```bash
+   npm install
+   ```
 3. Build the project:
-```bash
-npm run build
-```
+   ```bash
+   npm run build
+   ```
 
-### Available Scripts
+### Scripts
 
-| Script | Description |
-|--------|-------------|
-| `npm run build` | Compile TypeScript to JavaScript |
-| `npm run test` | Run all tests with Vitest |
-| `npm run test:watch` | Run tests in watch mode |
-| `npm run lint` | Run ESLint |
-| `npm run format` | Format code with Prettier |
-| `npm run typecheck` | Run TypeScript type checking |
+| Script               | Description                               |
+|----------------------|-------------------------------------------|
+| `npm test`           | Run tests once (Vitest)                   |
+| `npm run test:watch` | Run tests in watch mode                   |
+| `npm run test:browser` | Run tests in a browser environment     |
 
 ### Testing
 
-The test suite uses Vitest with fake-indexeddb for browser environment simulation. Run tests with:
+The test suite uses `vitest` and `fake-indexeddb/auto` to simulate IndexedDB. Run the tests with:
 
 ```bash
-npm run test
+npm test
 ```
 
-Coverage reports can be generated with:
-
-```bash
-npm run test:coverage
-```
+All core functionality is covered. When contributing, please add tests for new features or bug fixes.
 
 ### Contributing Guidelines
 
-1. **Fork and Branch** — Create a feature branch from `main`
-2. **Write Tests** — Add tests for new functionality or bug fixes
-3. **Update Documentation** — Keep README and JSDoc comments current
-4. **Commit Convention** — Use conventional commits (feat:, fix:, docs:, etc.)
-5. **Submit PR** — Open a pull request with a clear description of changes
+- **Branching**: Use feature branches off `main`.
+- **Commit messages**: Follow conventional commits (e.g., `feat: add new retriever`).
+- **Pull requests**: Ensure tests pass and add new tests for changes.
+- **Code style**: The project uses Prettier and ESLint. Run formatting before committing.
 
 ### Issue Reporting
 
-- **Bug Reports** — Include minimal reproduction, expected vs actual behavior, and environment details
-- **Feature Requests** — Describe use case and expected API
-- **Security Issues** — Email maintainers directly (see package.json for contact)
+Please open an issue on [GitHub](https://github.com/asaidimu/erp-utils/issues) with:
+- A clear description of the problem.
+- Steps to reproduce.
+- Expected and actual behaviour.
+- Version of the library and environment (Node.js / browser).
 
 ---
 
@@ -408,36 +332,30 @@ npm run test:coverage
 
 ### Troubleshooting
 
-**Q: Blob bytes not found locally error**
+| Issue                                      | Solution                                                                                   |
+|--------------------------------------------|--------------------------------------------------------------------------------------------|
+| `Database not open` error                  | Call `open()` on the storage backend before using it.                                      |
+| Blob not found in prompt                   | Ensure the blob is still referenced (refCount > 0) and not evicted. Run `gc()` only when safe. |
+| Turns missing after reload                 | Check that `flush()` was called before deactivation, or that `maxBufferSize` was reached. |
+| Prompt builder returns warnings for blobs  | Verify that the blob is registered and, if remote, that `recordRemoteId` was called.       |
 
-Blobs with refCount 0 are eligible for garbage collection. If you need them later, ensure:
-- `eagerEviction: false` in BlobStore config
-- `gc()` is not called before resolution
-- Register the blob again if it was evicted
+### FAQ
 
-**Q: IndexedDB open fails with "blocked" error**
+**Q: How does blob deduplication work?**  
+A: `BlobStore` computes SHA‑256 of the data. If a blob with the same hash already exists, only the ref count is incremented – bytes are never duplicated.
 
-Another browser tab has an open connection to the same database. Close the other tab or wait for it to release the connection.
+**Q: Can I use this library in a Node.js environment without IndexedDB?**  
+A: Yes. Use `MemoryStorage` and `MemoryBlobStorage` for in‑memory persistence. For long‑term storage, you would need to implement a custom backend (e.g., file system or SQLite).
 
-**Q: Turn edits not persisting**
+**Q: How do I manage token budgets for large transcripts?**  
+A: Use the `summarizer` option in `PromptBuilder` to compress older turns. The default `TokenPlanner` trims from the oldest turns when the budget is exceeded.
 
-Ensure `flush()` is called after batch operations, or configure `flush.maxBufferSize` to auto-flush.
-
-**Q: TypeScript errors with custom storage backends**
-
-Import the interface types and implement all required methods:
-
-```typescript
-import type { ContentStorage, BlobStorage } from '@asaidimu/utils-workspace';
-```
+**Q: What happens if I delete a role that is used by a session?**  
+A: The reducer will reject the command with `INVALID_COMMAND`. You must first switch sessions to a different role or delete the sessions.
 
 ### License
+This project is licensed under the [MIT License](https://github.com/asaidimu/erp-utils/blob/main/LICENSE.md).
 
-MIT © [Saidimu](https://github.com/asaidimu)
-
-See the [LICENSE](LICENSE) file for details.
-
----
+### Acknowledgments
 
-**Related Projects**
-- [@asaidimu/utils-store](https://github.com/asaidimu/utils-store) — Deep merge utilities and store patterns
+Built with inspiration from content‑addressed storage systems (IPFS, git) and conversation tree models. Special thanks to the open‑source community for tools like TypeScript, Vitest, and fake-indexeddb.