@asaidimu/utils-workspace 1.0.1 → 2.1.0

package/README.md

@@ -1,13 +1,13 @@
-# @asaidimu/utils-workspace
+# AI Workspace Manager
 
-Content-addressed workspace and conversation management for AI applications. Handles roles, preferences, context, transcripts, and binary blobs with a unified storage model.
+[![npm version](https://img.shields.io/badge/version-0.1.0-blue)](https://www.npmjs.com/package/@asaidimu/utils-workspace)
+[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![build status](https://img.shields.io/badge/build-passing-brightgreen)]()
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)]()
 
-[![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/)
+> TypeScript library for managing AI conversation workspaces — content-addressed blob storage, turn‑based transcripts, role/persona management, and prompt assembly with token budgeting.
 
-## Table of Contents
+## 📖 Table of Contents
 
 - [Overview & Features](#overview--features)
 - [Installation & Setup](#installation--setup)
@@ -20,20 +20,23 @@ 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.
+AI Workspace Core is a modular, offline‑first library designed to power AI‑assisted applications. It provides a complete workspace model where every conversation (session) is a DAG of **turns** (messages), backed by **content‑addressed blob storage** for large files (images, PDFs, etc.) and a flexible **context & preference** system scoped by topics.
 
-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.
+The library separates **pure state updates** (reducer) from **asynchronous persistence** (ContentStore), making it suitable for reactive UIs (React, Vue, Svelte) and server environments alike. It includes built‑in IndexedDB and in‑memory backends, as well as a **PromptBuilder** that assembles prompts respecting token budgets, resolves blob references, and handles preference conflicts.
 
 ### 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
+- **Blob Storage** – Content‑addressed (SHA‑256) storage with reference counting, remote ID mapping, and atomic registration. Supports `IndexedDBBlobStorage` (persistent) and `MemoryBlobStorage` (testing).
+- **Session & Turn DAG** – Each session maintains a directed acyclic graph of turns (messages). Turns can be edited (new version), branched, or deleted (subtree removal). Active chain resolves to a linear transcript.
+- **Role/Persona System** – Define reusable roles (e.g., “Analyst”, “Dev”) with a system persona and default preference IDs.
+- **Topic‑scoped Preferences & Context** – Preferences (user instructions) and context (injected knowledge) are attached to topics. The system resolves effective preferences for a session by merging role defaults with session‑specific overrides and filtering by session topics.
+- **Prompt Builder** – Three‑stage assembly:
+  - **Retrieval & Ranking** – Jaccard similarity + freshness weighting selects relevant context entries.
+  - **Planning** – Token‑aware planner respects budget, drops low‑priority items, and handles blob token estimation.
+  - **Assembly** – Resolves blobs (inline or remote), injects synthetic turns for truncation notices and referential attachments, and outputs a ready‑to‑use `Prompt`.
+- **Reducer Pattern** – Pure `workspaceReducer` produces `DeepPartial<Workspace>` patches for all commands. WorkspaceManager applies side effects and merges async results (e.g., blob SHA‑256).
+- **Multi‑backend Persistence** – Uses `@asaidimu/anansi` Database interface. WorkspaceDatabase adapts it with core schemas (Role, Preference, Context, Session, Turn). Turn DAG is stored as flat documents; the graph is reconstructed in memory.
+- **Offline‑First & Eager/Lazy GC** – Blobs can be evicted eagerly (on refCount → 0) or lazily (via `gc()`). Sessions buffer turns and flush asynchronously.
 
 ---
 
@@ -41,366 +44,324 @@ 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 modern browser (IndexedDB API required for persistent storage)
+- npm, bun, or yarn
 
-### Installation
+### Install
 
 ```bash
 npm install @asaidimu/utils-workspace
-```
-
-or with yarn:
-
-```bash
+# or
+bun add @asaidimu/utils-workspace
+# or
 yarn add @asaidimu/utils-workspace
 ```
 
-### Basic Setup
+### Configuration
+
+The library does not require global configuration. You instantiate backends and stores directly.
 
 ```typescript
-import {
-  IndexedDBStorage,
-  ContentStore,
-  WorkspaceManager,
-  PromptBuilder,
-  MemoryBlobStorage,
-  BlobStore
-    merge,
+import { 
+  createWorkspaceDatabase, 
+  IndexedDBBlobStorage, 
+  ContentStore, 
+  WorkspaceManager 
 } from '@asaidimu/utils-workspace';
+import { createIndexedDBDatabase } from '@asaidimu/utils-database'; // example IDB adapter
 
-// Initialize content storage (IndexedDB for persistence)
-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();
-
-// Create content store with default configuration
-const contentStore = new ContentStore(contentBackend);
-
-// 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: {}
-};
-```
+// 1. Create database (IndexedDB)
+const idb = createIndexedDBDatabase({ dbName: 'my-app', version: 1 });
+const db = createWorkspaceDatabase(idb);
 
----
+// 2. Create blob storage (persistent)
+const blobStorage = new IndexedDBBlobStorage({ dbName: 'my-app-blobs' });
 
-## Usage Documentation
+// 3. ContentStore (caches, blob store, turn tree)
+const contentStore = await ContentStore.create(db, blobStorage);
 
-### Basic Usage
+// 4. WorkspaceManager (dispatches commands)
+const workspaceManager = new WorkspaceManager(contentStore);
+```
 
-Create a role, session, and add a turn:
+### Verification
 
-```typescript
-let indexState = emptyState;
+Run a quick command to ensure everything works:
 
-// 1. Add a role
-const addRoleCmd = {
-  type: 'role:add' as const,
-  timestamp: new Date().toISOString(),
-  payload: {
-    id: 'role-1',
-    name: 'assistant',
-    label: 'Assistant',
-    persona: 'You are a helpful assistant.',
-    preferences: []
-  }
-};
+```typescript
+import { createWorkspace, merge } from '@asaidimu/utils-workspace';
 
-const roleResult = await manager.dispatch(indexState, addRoleCmd);
-if (roleResult.ok) {
-  // Merge the patch into your state
-  indexState = merge(indexState, roleResult.value) ;
-}
+let workspace = createWorkspace({
+    name: "example-project",
+    owner: "user",
+    language: "en"
+}); 
 
-// 2. Create a session
-const createSessionCmd = {
-  type: 'session:create' as const,
+const result = await workspaceManager.dispatch(workspace, {
+  type: 'role:add',
   timestamp: new Date().toISOString(),
-  payload: {
-    id: 'session-1',
-    label: 'My First Conversation',
-    role: 'assistant',
-    topics: ['general'],
-    preferences: []
-  }
-};
+  payload: { name: 'assistant', label: 'Assistant', persona: 'You are helpful.', preferences: [] }
+});
 
-const sessionResult = await manager.dispatch(indexState, createSessionCmd);
-if (sessionResult.ok) {
-  indexState = merge(indexState, sessionResult.value) ;
+if (result.ok) {
+  workspace = merge(workspace, result.value);
+  console.log('Role added:', workspace.index.roles['assistant']);
 }
+```
 
-// 3. Activate the session (enables dirty buffer for performance)
-await manager.activateSession(indexState, 'session-1');
-
-// 4. Add a turn
-const addTurnCmd = {
-  type: 'turn:add' as const,
-  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
-    }
-  }
-};
+---
 
-await manager.dispatch(indexState, addTurnCmd);
-await manager.flush(); // Persist dirty buffer to storage
-```
+## Usage Documentation
 
-### Registering and Using Blobs
+### Basic Example – Create a Session, Add Turns, Build a Prompt
 
 ```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');
+import { 
+  emptyWorkspace, merge, 
+  WorkspaceManager, ContentStore, 
+  MemoryBlobStorage, createWorkspaceDatabase,
+  SessionManager, PromptBuilder 
+} from '@asaidimu/utils-workspace';
+import { createMemoryDatabase } from '@asaidimu/utils-database';
 
-if (blobResult.ok) {
-  const blobRef = blobResult.value;
+async function demo() {
+  // ---- Setup ----
+  const memDb = createMemoryDatabase();
+  const db = createWorkspaceDatabase(memDb);
   
-  // 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
+  const blobStorage = new MemoryBlobStorage();
+
+const contentStore = await ContentStore.create(db, blobStorage);
+  
+  const workspaceManager = new WorkspaceManager(contentStore);
+  const sessionManager = new SessionManager(workspaceManager, contentStore);
+  
+  let workspace = emptyWorkspace();
+  const dispatch = async (cmd: any) => {
+    const r = await workspaceManager.dispatch(workspace, cmd);
+    if (r.ok) workspace = merge(workspace, r.value);
+    else throw new Error(r.error.code);
   };
   
-  await manager.dispatch(indexState, {
-    type: 'turn:add',
-    timestamp: new Date().toISOString(),
-    payload: { sessionId: 'session-1', turn: turnWithBlob }
+  // ---- Seed data ----
+  await dispatch({
+    type: 'role:add', timestamp: new Date().toISOString(),
+    payload: { name: 'analyst', label: 'Analyst', persona: 'You are a financial analyst.', preferences: [] }
+  });
+  await dispatch({
+    type: 'preference:add', timestamp: new Date().toISOString(),
+    payload: { id: 'pref1', content: 'Use KES for currency', topics: ['finance'], timestamp: new Date().toISOString() }
+  });
+  await dispatch({
+    type: 'context:add', timestamp: new Date().toISOString(),
+    payload: { key: 'kb:q4', content: { kind: 'text', value: 'Q4 revenue: KES 4.2M' }, topics: ['finance'], timestamp: new Date().toISOString() }
+  });
+  await dispatch({
+    type: 'session:create', timestamp: new Date().toISOString(),
+    payload: { id: 'session-1', label: 'Earnings Call', role: 'analyst', topics: ['finance'], preferences: ['pref1'] }
   });
-}
-```
-
-### Building Prompts
-
-```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);
+  // ---- Open session, add a turn ----
+  const openResult = await sessionManager.open(workspace, 'session-1');
+  if (!openResult.ok) throw new Error('open failed');
+  const { session } = openResult.value;
   
-  // Build the prompt
-  const builder = new PromptBuilder();
-  const prompt = await builder.build(resolved.value, {
-    resolvedBlobs,
-    tokenBudget: { total: 4000 }
+  const addResult = await session.addTurn(workspace, {
+    id: 'turn-1', version: 0, role: 'user',
+    blocks: [{ type: 'text', text: 'What was the Q4 revenue?' }],
+    timestamp: new Date().toISOString(), parent: null
   });
+  if (addResult.ok) workspace = merge(workspace, addResult.value);
+  await session.flush();
   
-  console.log(prompt.system); // System prompt with persona, preferences, context
-  console.log(prompt.turns);   // Conversation turns with resolved blobs
+  // ---- Resolve effective session & build prompt ----
+  const resolved = await workspaceManager.resolveSession(workspace, 'session-1');
+  if (!resolved.ok) throw new Error('resolve failed');
+  
+  const promptBuilder = new PromptBuilder({ blobResolver: contentStore.getBlobResolver() });
+  const prompt = await promptBuilder.build(resolved.value, {
+    tokenBudget: { total: 4000 },
+    relevanceConfig: { recentMessageWindow: 5 }
+  });
+  
+  console.log(prompt.system.persona);        // "You are a financial analyst."
+  console.log(prompt.system.preferences[0].content); // "Use KES for currency"
+  console.log(prompt.transcript.turns[0].blocks[0].text); // "What was the Q4 revenue?"
+  console.log(prompt.budget.used);            // token count
 }
-```
 
-### Configuration
-
-**ContentStore Configuration**
-
-```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
-});
-```
-
-**BlobStore Configuration**
-
-```typescript
-const blobStore = new BlobStore(backend, {
-  eagerEviction: false  // When false, blobs with refCount 0 persist until gc()
-});
+demo();
 ```
 
-**IndexedDB Configuration**
-
-```typescript
-const contentBackend = new IndexedDBStorage({ dbName: 'custom-db-name' });
-const blobBackend = new IndexedDBBlobStorage({ dbName: 'custom-blob-db' });
-```
-
----
-
-## Project Architecture
+### CLI Commands
 
-### Core Components
+AI Workspace Core is a **library**, not a CLI. However, you can build your own CLI around its commands. The core command types are:
 
-**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.
+| Command Family | Example |
+|----------------|---------|
+| Role | `role:add`, `role:update`, `role:delete` |
+| Preference | `preference:add`, `preference:update`, `preference:delete` |
+| Context | `context:add`, `context:update`, `context:delete` |
+| Session | `session:create`, `session:fork`, `session:delete`, `session:role:switch`, `session:topics:add`, `session:preferences:override` |
+| Turn | `turn:add`, `turn:edit`, `turn:branch`, `turn:delete` |
+| Blob | `blob:register`, `blob:retain`, `blob:release`, `blob:purge`, `blob:record_remote_id` |
 
-**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.
+### API Reference
 
-**WorkspaceManager** — The public facade that coordinates between commands, reducer, and content persistence. Handles side effects (saving to storage) while keeping the reducer pure.
+#### Core Classes
 
-**BlobStore** — Content-addressed blob management with SHA-256 deduplication, reference counting, remote ID tracking, and resolution between inline and remote blob references.
+- **`BlobStore`** – Manages blob registration, ref counting, remote IDs, and resolution. Created internally by `ContentStore`.
+- **`ContentStore`** – High‑level API for all entities (Role, Preference, Context, Session, Turn) and blob operations. Caches records.
+- **`WorkspaceManager`** – Dispatches commands, reduces state, and persists side effects. Entry point for state changes.
+- **`SessionManager`** – Opens/closes live sessions, loads turn DAG, returns `Session` objects.
+- **`Session`** – Live session with methods: `addTurn`, `editTurn`, `branchFrom`, `deleteTurn`, `switchVersionLeft/Right`, `resolve`, `flush`, `dispose`.
+- **`TurnTree`** – Low‑level DAG persistence (append, branch, delete subtree). Used by `Session` via `ContentStore`.
+- **`PromptBuilder`** – Assembles prompts from `EffectiveSession` with token budgeting and blob resolution.
 
-**PromptBuilder** — Transforms an EffectiveSession into a provider-agnostic prompt structure with token budgeting, preference conflict resolution, context ranking, and optional summarization.
+#### Key Types
 
-**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
+- `Workspace` – Contains `id`, `settings`, `project`, and `index` (in‑memory read model).
+- `BlobRef` – Lightweight pointer to a blob (sha256, mediaType, sizeBytes, optional filename).
+- `ResolvedBlob` – Either `{ kind: 'inline', data: Uint8Array }` or `{ kind: 'remote', fileId, providerId }`.
+- `EffectiveSession` – Resolved session with role, preferences, context, transcript, and optional instructions.
+- `Prompt` – Ready to send to an LLM; includes system block, context, transcript turns, budget breakdown, warnings, and conflicts.
 
-### Data Flow
+### Configuration Examples
 
-```
-Command → WorkspaceManager.dispatch()
-    ↓
-WorkspaceReducer (pure patch generation)
-    ↓
-ContentStore (side effects: save roles, preferences, turns, etc.)
-    ↓
-Storage Backend (IndexedDB / Memory)
-```
+#### Customising Token Estimator
 
-For resolution and prompt building:
+```typescript
+const promptBuilder = new PromptBuilder({
+  blobResolver: contentStore.getBlobResolver(),
+  planner: new DefaultTokenPlanner() // or extend
+});
 
+await promptBuilder.build(session, {
+  tokenBudget: {
+    total: 8000,
+    estimator: (text: string) => Math.ceil(text.length / 3), // custom
+    blobTokensPerKB: 0.5
+  }
+});
 ```
-IndexState + SessionId → ContentStore.resolveSession()
-    ↓ (async content loading)
-EffectiveSession → BlobStore.resolveRefs()
-    ↓ (blob resolution)
-PromptBuilder.build()
-    ↓ (token budgeting, summarization)
-Prompt (system, turns, warnings)
-```
-
-### Extension Points
 
-**Custom Storage Backends** — Implement the `ContentStorage` or `BlobStorage` interfaces to support alternative persistence (SQLite, cloud storage, etc.)
+#### Using a Different Context Retriever
 
-**Summarizer** — Inject a custom summarizer into `PromptBuilder` for transcript compression:
+Implement `ContextRetriever` interface:
 
 ```typescript
-interface Summarizer {
-  summarize(transcript: Turn[], tokenBudget: number): Promise<{
-    summary: string;
-    remaining: Turn[];
-  }>;
+class MyRetriever implements ContextRetriever {
+  rank(input: ContextRankingInput): Context[] {
+    // custom logic
+  }
 }
 
-const builder = new PromptBuilder(myCustomSummarizer);
+const promptBuilder = new PromptBuilder({
+  blobResolver: contentStore.getBlobResolver(),
+  retriever: new MyRetriever()
+});
 ```
 
-**Token Estimators** — Override the default text estimator for provider-specific token counting:
+### Common Use Cases
+
+#### 1. Upload an Image and Attach to a Turn
 
 ```typescript
-const prompt = await builder.build(session, {
-  tokenBudget: {
-    total: 8000,
-    estimator: (text) => myProviderTokenCounter.count(text)
-  }
-});
+// Register blob via command (async)
+const registerCmd = {
+  type: 'blob:register',
+  timestamp: new Date().toISOString(),
+  payload: { data: imageUint8Array, mediaType: 'image/png', filename: 'chart.png' }
+};
+const regResult = await workspaceManager.dispatch(workspace, registerCmd);
+if (regResult.ok) workspace = merge(workspace, regResult.value);
+const blobRef = regResult.value.index.blobs[sha256]; // BlobRef
+
+// Add turn referencing the blob
+const turn = {
+  id: crypto.randomUUID(), version: 0, role: 'user',
+  blocks: [{ type: 'image', ref: blobRef, altText: 'Revenue chart' }],
+  timestamp: new Date().toISOString(), parent: null
+};
+await session.addTurn(workspace, turn);
 ```
 
----
+#### 2. Edit a Previous Turn (Versioning)
 
-## Development & Contributing
+```typescript
+const editResult = await session.editTurn(workspace, 'turn-1', [
+  { type: 'text', text: 'Corrected: Q4 revenue was KES 4.5M' }
+]);
+// A new version (1) is created. Session head moves to version 1 of turn-1.
+```
 
-### Development Setup
+#### 3. Branch a Conversation
 
-1. Clone the repository:
-```bash
-git clone https://github.com/asaidimu/utils-workspace.git
-cd utils-workspace
+```typescript
+const branchTurn = {
+  id: crypto.randomUUID(), version: 0, role: 'user',
+  blocks: [{ type: 'text', text: 'Let’s explore a different scenario.' }],
+  timestamp: new Date().toISOString(),
+  parent: { id: 'turn-1', version: 0 } // branch from original version
+};
+await session.branchFrom(workspace, branchTurn);
+// New head points to branchTurn, original chain remains.
 ```
 
-2. Install dependencies:
-```bash
-npm install
-```
+#### 4. Garbage Collect Unreferenced Blobs
 
-3. Build the project:
-```bash
-npm run build
+```typescript
+// lazy eviction (default) – only delete bytes, keep record
+const deletedCount = await contentStore.blobs.gc();
+// full purge – delete bytes AND record
+const purgedCount = await contentStore.blobs.gcFull();
 ```
 
-### Available 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 |
+---
 
-### Testing
+## Project Architecture
 
-The test suite uses Vitest with fake-indexeddb for browser environment simulation. Run tests with:
+### Core Components
 
-```bash
-npm run test
-```
+- **BlobStorage** – Interface for raw bytes + record persistence. Implementations: `IndexedDBBlobStorage`, `MemoryBlobStorage`.
+- **BlobStore** – Adds ref counting, remote ID mapping, and resolution. Maintains in‑memory cache of `BlobRecord`s.
+- **ContentStore** – Owns `TurnTree` and `BlobStore`. Provides high‑level methods for all entities. Caches roles/preferences/context with LRU.
+- **TurnTree** – Flat storage of `Turn` documents (sessionId, id, version). Reconstructs DAG in memory (`buildNodeGraph`). Handles `append`, `replaceVersion`, `branch`, `deleteSubtree`, and head pointer on `SessionMeta`.
+- **Reducer** – Pure function `workspaceReducer(workspace, command) => DeepPartial<Workspace>`. Updates `Index` summaries (roles, preferences, context, sessions, topics, blobs).
+- **WorkspaceManager** – Orchestrates reducer + side effects. Dispatches commands, merges patches, exposes `resolveSession`.
+- **SessionManager** – Opens sessions by loading turn DAG via `TurnTree.buildNodeGraph()`. Returns `Session` object.
+- **Session** – Live DAG with mutable `nodes` and dirty buffer. Provides turn mutations that update memory, buffer, and trigger flushes.
+- **PromptBuilder** – Retrieves relevant context, plans token usage, resolves blob refs, assembles final `Prompt`.
 
-Coverage reports can be generated with:
+### Data Flow
 
-```bash
-npm run test:coverage
+```
+Command → WorkspaceManager.dispatch()
+          ├─ workspaceReducer() → pure patch
+          ├─ handleContentSideEffects() → persist via ContentStore, return extra patch
+          └─ merge patches → return to caller
+
+Session mutations (addTurn, editTurn, etc.):
+          Session (in‑memory nodes + dirtyBuffer)
+          └─ on flush: TurnTree.appendBatch(sessionId, turns, finalHead)
+                └─ updates SessionMeta.head
+                └─ stores Turn documents
+
+Prompt building:
+          EffectiveSession (resolved by ContentStore)
+          └─ PromptBuilder.build()
+                ├─ ContextRetriever.rank()
+                ├─ TokenPlanner.plan()
+                ├─ BlobStore.resolveRefs()
+                └─ PromptAssembler.assemble()
 ```
 
-### 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
-
-### Issue Reporting
+### Extension Points
 
-- **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)
+- **Custom BlobStorage** – Implement `BlobStorage` interface to use S3, OPFS, etc.
+- **Custom ContextRetriever** – Provide alternative relevance algorithms.
+- **Custom TokenPlanner** – Override budget allocation logic.
+- **Summarizer** – Inject summarizer to compress long transcripts before prompt assembly.
 
 ---
 
@@ -408,36 +369,27 @@ npm run test:coverage
 
 ### Troubleshooting
 
-**Q: Blob bytes not found locally error**
-
-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
-
-**Q: IndexedDB open fails with "blocked" error**
+| Problem | Likely cause | Solution |
+|---------|--------------|----------|
+| `Blob bytes not found locally` | Blob evicted but still referenced. | Re‑register the blob or disable eager eviction. |
+| `Database not open. Call open() first.` | Forgot to call `await blobStorage.open()`. | Ensure `open()` is called before any operation. |
+| `Constraint failed: unique index by_session_id_ver` | Duplicate (sessionId, id, version). | Check that `Turn` IDs are unique per session. |
+| `PromptBuilder` fails with `BLOB_ERROR` | Blob resolution failed (remote ID missing or bytes missing). | Verify remote mapping or ensure blob is still present. |
 
-Another browser tab has an open connection to the same database. Close the other tab or wait for it to release the connection.
+### FAQ
 
-**Q: Turn edits not persisting**
+**Q: Can I use this library in a browser without IndexedDB?**  
+A: Yes – use `MemoryBlobStorage` and an in‑memory database adapter. However, data will not persist across page reloads.
 
-Ensure `flush()` is called after batch operations, or configure `flush.maxBufferSize` to auto-flush.
+**Q: How do I export a workspace for backup?**  
+A: Use `IndexedDBBlobStorage.exportAllBytes()` and `ContentStore` methods to dump all records. There is also a `WorkspaceBundle` type for structured export.
 
-**Q: TypeScript errors with custom storage backends**
+**Q: Does the library support streaming large files?**  
+A: Not directly. Blobs are stored as complete `Uint8Array`. For very large files, consider splitting or using a remote storage provider and storing only the remote ID.
 
-Import the interface types and implement all required methods:
-
-```typescript
-import type { ContentStorage, BlobStorage } from '@asaidimu/utils-workspace';
-```
+**Q: Can I use a different LLM provider’s file API?**  
+A: Yes – after uploading a blob to a provider (e.g., Anthropic), call `recordBlobRemoteId(sha256, providerId, fileId)`. The `resolveRef` method will return a remote blob reference for that provider.
 
 ### License
 
-MIT © [Saidimu](https://github.com/asaidimu)
-
-See the [LICENSE](LICENSE) file for details.
-
----
-
-**Related Projects**
-- [@asaidimu/utils-store](https://github.com/asaidimu/utils-store) — Deep merge utilities and store patterns
+[MIT](https://github.com/asaidimu/erp-utils/blob/main/LICENSE) © Saidimu