@rool-dev/client 0.6.5 → 0.6.6-dev.3e5f7f7

package/README.md

@@ -6,12 +6,48 @@ Rool Spaces enables you to build applications where AI operates on a structured
 
 Use Rool to programmatically instruct agents to generate content, research topics, or reorganize data. The client manages authentication, real-time synchronization, and media storage, supporting both single-user and multi-user workflows.
 
+**Core primitives:**
+- **Objects** — Key-value records with any fields you define
+- **Relations** — Directional links between objects (e.g., `earth` → `orbits` → `sun`)
+- **AI operations** — Create, update, or query objects using natural language and `{{placeholders}}`
+
+See [Patterns & Examples](#patterns--examples) for what you can build.
+
 ## Installation
 
 ```bash
 npm install @rool-dev/client
 ```
 
+## Configuration
+
+```typescript
+import { RoolClient } from '@rool-dev/client';
+
+const client = new RoolClient({
+  baseUrl: 'https://api.dev.rool.dev',
+});
+```
+
+### RoolClientConfig
+
+```typescript
+interface RoolClientConfig {
+  baseUrl: string;           // Base URL (e.g., 'https://api.dev.rool.dev')
+  graphqlUrl?: string;       // Override GraphQL endpoint (default: {baseUrl}/graphql)
+  mediaUrl?: string;         // Override media endpoint (default: {baseUrl}/media)
+  authUrl?: string;          // Override auth endpoint (default: {baseUrl}/auth)
+  authProvider?: AuthProvider; // Optional, defaults to browser auth
+}
+```
+
+### Base URLs
+
+| Environment | URL |
+|-------------|-----|
+| Development | `https://api.dev.rool.dev` |
+| Production | `https://api.rool.dev` |
+
 ## Quick Start
 
 ```typescript
@@ -23,7 +59,7 @@ const client = new RoolClient({
 });
 
 // Process auth callbacks if we are returning from the login page
-client.initialize(); 
+client.initialize();
 
 if (!client.isAuthenticated()) {
   client.login();  // Redirects to auth page
@@ -44,7 +80,7 @@ space.on('linked', ({ sourceId, relation, targetId, source }) => {
   console.log('New link:', sourceId, '->', targetId, `[${relation}]`, 'from', source);
 });
 
-// Create objects with AI-generated content. 
+// Create objects with AI-generated content.
 // Field names are yours to define — only 'id' is reserved.
 const { object: sun } = await space.createObject({
   data: {
@@ -79,31 +115,158 @@ await space.redo(); // The link is back ...
 space.close();
 ```
 
-## Configuration
+## Core Concepts
+
+### Objects & Relations
+
+**Objects** are plain key-value records. The `id` field is reserved; everything else is application-defined.
 
 ```typescript
-interface RoolClientConfig {
-  baseUrl: string;           // Base URL (e.g., 'https://api.dev.rool.dev')
-  graphqlUrl?: string;       // Override GraphQL endpoint (default: {baseUrl}/graphql)
-  mediaUrl?: string;         // Override media endpoint (default: {baseUrl}/media)
-  authUrl?: string;          // Override auth endpoint (default: {baseUrl}/auth)
-  authProvider?: AuthProvider; // Optional, defaults to browser auth
+{ id: 'abc123', type: 'article', title: 'Hello World', status: 'draft' }
+```
+
+**Relations** connect objects directionally through named links. Each relation name represents a multi-valued reference set on the source object.
+
+```typescript
+await space.link(earth.id, 'orbits', sun.id);
+// Reads as: "earth.orbits includes sun"
+
+const orbited = space.getChildren(earth.id, 'orbits');  // [sun] - what earth links TO
+const orbiters = space.getParents(sun.id, 'orbits');    // [earth] - what links TO sun
+```
+
+Relations are indexed and idempotent — creating the same link twice has no effect.
+
+**Notes:**
+- Relation names are application-defined strings
+- Relations are not stored in object data fields
+- Only relations created via `link()` participate in traversal (`getParents`, `getChildren`) and indexing
+- Storing object IDs inside regular object fields is possible, but those references are opaque to the system
+
+### AI Placeholder Pattern
+
+Use `{{description}}` in field values to have AI generate content:
+
+```typescript
+// Create with AI-generated content
+await space.createObject({
+  data: {
+    type: 'article',
+    headline: '{{catchy headline about coffee}}',
+    body: '{{informative paragraph}}'
+  },
+  prompt: 'Write about specialty coffee brewing'
+});
+
+// Update existing content with AI
+await space.updateObject('abc123', {
+  prompt: 'Make the body shorter and more casual'
+});
+
+// Add new AI-generated field to existing object
+await space.updateObject('abc123', {
+  data: { summary: '{{one-sentence summary}}' }
+});
+```
+
+When resolving placeholders, the agent has access to the full object data and the surrounding space context (except for `_`-prefixed fields). Placeholders are instructions, not templates, and do not need to repeat information already present in other fields.
+
+Placeholders are resolved by the AI during the mutation and replaced with concrete values. The `{{...}}` syntax is never stored — it only guides the agent while creating or updating the object.
+
+### Checkpoints & Undo/Redo
+
+Undo/redo works on **checkpoints**, not individual operations. Call `checkpoint()` before making changes to create a restore point.
+
+```typescript
+// Create a checkpoint before user action
+await space.checkpoint('Delete object');
+await space.deleteObjects([objectId]);
+
+// User can now undo back to the checkpoint
+if (await space.canUndo()) {
+  await space.undo(); // Restores the deleted object
+}
+
+// Redo reapplies the undone action
+if (await space.canRedo()) {
+  await space.redo(); // Deletes the object again
 }
 ```
 
-### Base URLs
+Without a checkpoint, `undo()` has nothing to restore to. Undo always restores the space to the last checkpoint, regardless of how many changes were made since.
 
-| Environment | URL |
-|-------------|-----|
-| Development | `https://api.dev.rool.dev` |
-| Production | `https://api.rool.dev` |
+In collaborative scenarios, conflicting changes (modified by others since your checkpoint) are silently skipped.
 
-### Auth Providers
+### Hidden Fields
 
-**Browser (default)** — No configuration needed. Uses localStorage for tokens, redirects to login page.
+Fields starting with `_` (e.g., `_ui`, `_cache`) are hidden from AI but otherwise behave like normal fields — they sync in real-time, persist to the server, support undo/redo, and are visible to all users of the Space. Use them for UI state, positions, or other data the AI shouldn't see or modify:
 
 ```typescript
-const client = new RoolClient({ baseUrl: 'https://api.dev.rool.dev' });
+await space.createObject({
+  data: {
+    title: 'My Article',
+    author: "John Doe",
+    _ui: { x: 100, y: 200, collapsed: false }
+  }
+});
+```
+
+### Real-time Sync
+
+Events fire for both local and remote changes. The `source` field indicates origin:
+
+- `local_user` — This client made the change
+- `remote_user` — Another user/client made the change
+- `remote_agent` — AI agent made the change
+- `system` — Resync after error
+
+```typescript
+// All UI updates happen in one place, regardless of change source
+space.on('objectUpdated', ({ objectId, object, source }) => {
+  renderObject(objectId, object);
+  if (source === 'remote_agent') {
+    doLayout(); // AI might have added content
+  }
+});
+
+// Caller just makes the change - event handler does the UI work
+space.updateObject(objectId, { prompt: 'expand this' });
+```
+
+### Custom Object IDs
+
+By default, `createObject` generates a 6-character alphanumeric ID. Provide your own via `data.id`:
+
+```typescript
+await space.createObject({ data: { id: 'article-42', title: 'The Meaning of Life' } });
+```
+
+**Why use custom IDs?**
+- **Fire-and-forget creation** — Know the ID immediately without awaiting the response. You can create an object and link to it in parallel; the sync happens in the background.
+- **Meaningful IDs** — Use domain-specific IDs like `user-123` or `doc-abc` for easier debugging and external references.
+
+```typescript
+// Fire-and-forget: create and link without waiting
+const id = RoolClient.generateId();
+space.createObject({ data: { id, type: 'note', text: '{{expand this idea}}' } });
+space.link(parentId, 'hasNote', id);  // Can link immediately
+```
+
+**Constraints:**
+- Must contain only alphanumeric characters, hyphens (`-`), and underscores (`_`)
+- Must be unique within the space (throws if ID exists)
+- Cannot be changed after creation (immutable)
+
+Use `RoolClient.generateId()` when you need an ID before calling `createObject` but don't need it to be meaningful — it gives you a valid random ID without writing your own generator.
+
+## Authentication
+
+### Browser (Default)
+
+No configuration needed. Uses localStorage for tokens, redirects to login page.
+
+```typescript
+const client = new RoolClient({ baseUrl: 'https://api.rool.dev' });
 client.initialize(); // Process auth callbacks if this is a callback from the auth page
 
 if (!client.isAuthenticated()) {
@@ -111,13 +274,15 @@ if (!client.isAuthenticated()) {
 }
 ```
 
-**Node.js** — For CLI tools and scripts. Stores credentials in `~/.config/rool/`, opens browser for login.
+### Node.js
+
+For CLI tools and scripts. Stores credentials in `~/.config/rool/`, opens browser for login.
 
 ```typescript
 import { NodeAuthProvider } from '@rool-dev/client/node';
 
 const client = new RoolClient({
-  baseUrl: 'https://api.dev.rool.dev',
+  baseUrl: 'https://api.rool.dev',
   authProvider: new NodeAuthProvider()
 });
 
@@ -126,128 +291,172 @@ if (!client.isAuthenticated()) {
 }
 ```
 
-**Custom** — Implement the `AuthProvider` interface for full control.
+### Auth Methods
+
+| Method | Description |
+|--------|-------------|
+| `initialize(): boolean` | **Call on app startup if running in browser.** Processes auth callback from URL, sets up token refresh. |
+| `login(): void` | Redirect to login page |
+| `logout(): void` | Clear tokens and state |
+| `isAuthenticated(): boolean` | Check auth status |
+| `getToken(): Promise<string \| undefined>` | Get current access token |
+| `getAuthUser(): AuthUser` | Get auth identity from JWT (`{ email, name }`) |
+
+## AI Agent
+
+The `prompt()` method is the primary way to invoke the AI agent. The agent has editor-level capabilities — it can create, modify, delete, link, and research — but cannot see or modify `_`-prefixed fields.
 
 ```typescript
-const client = new RoolClient({
-  baseUrl: 'https://api.dev.rool.dev',
-  authProvider: {
-    initialize: () => false,
-    getToken: async () => myStore.getAccessToken(),
-    getUser: () => ({ email: 'user@example.com', name: 'User' }),
-    isAuthenticated: () => myStore.hasValidToken(),
-    login: async () => { /* your login flow */ },
-    logout: () => myStore.clear(),
-  }
-});
+const { message, objects } = await space.prompt(
+  "Create a topic node for the solar system, then child nodes for each planet."
+);
+console.log(`AI: ${message}`);
+console.log(`Modified ${objects.length} objects:`, objects);
 ```
 
----
+Use `checkpoint()` before prompting to make operations undoable.
 
-## Interaction History and AI Context
+### Method Signature
 
-Each `RoolSpace` instance has a `conversationId` that tracks interaction history for that space. The history records all meaningful interactions (prompts, object changes, links) as self-contained entries, each capturing the request and its result. History is stored in the space data itself and syncs in real-time to all clients.
+```typescript
+prompt(text: string, options?: PromptOptions): Promise<{ message: string; objects: RoolObject[] }>
+```
 
-AI operations (`prompt`, `createObject`, `updateObject`, `findObjects`) automatically receive:
+Returns a message (the AI's response) and the list of objects that were created or modified.
 
-- **Interaction history** — Previous interactions and their results from this conversation
-- **Recently modified objects** — Objects created or changed during this conversation
-- **Selected objects** — Objects passed via `objectIds` are given primary focus
+### Options
 
-This context flows automatically — no configuration needed. The AI sees enough history to maintain coherent interactions while respecting the `_`-prefixed field hiding rules.
+| Option | Description |
+|--------|-------------|
+| `objectIds` | Limit context to specific objects |
+| `responseSchema` | Request structured JSON instead of text summary |
+| `effort` | Effort level: `'QUICK'`, `'STANDARD'` (default), `'REASONING'`, or `'RESEARCH'` |
+| `ephemeral` | If true, don't record in conversation history (useful for tab completion) |
 
-### Accessing Interaction History
+### Effort Levels
 
-Interaction history is stored in the space and accessible via the Space API:
+| Level | Description |
+|-------|-------------|
+| `QUICK` | Fast responses, read-only. Cannot create/update objects or links. Use for questions. |
+| `STANDARD` | Default behavior with full capabilities. |
+| `REASONING` | Extended reasoning for complex tasks. |
+| `RESEARCH` | Pre-analysis and context gathering (reserved for future use). |
+
+### Examples
 
 ```typescript
-// Get interactions for the current conversationId
-const interactions = space.getInteractions();
-// Returns: Interaction[]
+// Reorganize and link existing objects
+const { objects } = await space.prompt(
+  "Group these notes by topic and create a parent node for each group."
+);
 
-// Get interactions for a specific conversation ID
-const interactions = space.getInteractionsById('other-conversation-id');
-// Returns: Interaction[]
+// Work with specific objects
+const result = await space.prompt(
+  "Summarize these articles",
+  { objectIds: ['article-1', 'article-2'] }
+);
 
-// List all conversation IDs that have interactions
-const conversationIds = space.getConversationIds();
-// Returns: string[]
-```
+// Quick question without mutations
+const { message } = await space.prompt(
+  "What topics are covered?",
+  { effort: 'QUICK' }
+);
 
-Each entry is a self-contained interaction record:
-```typescript
-interface Interaction {
-  timestamp: number;
-  userId: string;                // Who performed this interaction
-  userName?: string | null;      // Display name at time of interaction
-  operation: 'prompt' | 'createObject' | 'updateObject' | 'link' | 'unlink' | 'deleteObjects';
-  input: string;                 // What the user did: prompt text or action description
-  output: string;                // Result: AI response or confirmation message
-  ai: boolean;                   // Whether AI was invoked (vs synthetic confirmation)
-  modifiedObjectIds: string[];   // Objects affected by this interaction
-}
+// Complex analysis with extended reasoning
+await space.prompt(
+  "Analyze relationships and reorganize",
+  { effort: 'REASONING' }
+);
 ```
 
-The `ai` field distinguishes AI-generated responses from synthetic confirmations:
-- `ai: true` — AI processed this operation (prompt, or createObject/updateObject with placeholders)
-- `ai: false` — System confirmation only (e.g., "Linked X to Y", "Created object abc123")
-
-### Interaction History Events
+### Structured Responses
 
-Listen for history updates:
+Use `responseSchema` to get structured JSON instead of a text message:
 
 ```typescript
-space.on('interactionsUpdated', ({ conversationId, source }) => {
-  // Interaction history changed - refresh if needed
-  const interactions = space.getInteractions();
-  renderInteractions(interactions);
+const { message } = await space.prompt("Categorize these items", {
+  objectIds: ['item-1', 'item-2', 'item-3'],
+  responseSchema: {
+    type: 'object',
+    properties: {
+      categories: {
+        type: 'array',
+        items: { type: 'string' }
+      },
+      summary: { type: 'string' }
+    }
+  }
 });
+
+const result = JSON.parse(message);
+console.log(result.categories, result.summary);
 ```
 
-### Conversation Isolation
+### Context Flow
 
-By default, each call to `openSpace()` or `createSpace()` generates a new `conversationId`. This means:
-- Opening a space twice gives you two independent AI conversation histories
-- Closing and reopening a space starts fresh
+AI operations automatically receive context:
+- **Interaction history** — Previous interactions and their results from this conversation
+- **Recently modified objects** — Objects created or changed recently
+- **Selected objects** — Objects passed via `objectIds` are given primary focus
 
-### Resuming Conversations
+This context flows automatically — no configuration needed. The AI sees enough history to maintain coherent interactions while respecting the `_`-prefixed field hiding rules.
 
-Pass a `conversationId` to continue a previous conversation:
+## Collaboration
+
+### Adding Users to a Space
+
+To add a user to a space, you need their user ID. Use `searchUser()` to find them by email:
 
 ```typescript
-// First conversation - save the conversationId
-const space = await client.openSpace('abc123');
-const savedConversationId = space.conversationId;
-space.close();
+// Find the user by email
+const user = await client.searchUser('colleague@example.com');
+if (!user) {
+  throw new Error('User not found');
+}
 
-// Later - resume the same conversation
-const resumedSpace = await client.openSpace('abc123', { conversationId: savedConversationId });
-// AI now has access to conversation history from before
+// Add them to the space
+await space.addUser(user.id, 'editor');
 ```
 
-**Use cases:**
-- **Page refresh** — Store `conversationId` in localStorage to maintain context across reloads
-- **Multiple conversations** — Maintain and switch between different conversation contexts with the same space
-- **Collaborative conversations** — Share a `conversationId` between users to enable shared AI conversation history
-
-**Tip:** Use the user's id as `conversationId` to share context across tabs/devices, or a fixed string like `'shared'` to share context across all users.
+### Roles
 
-Note: Interaction history is truncated to the most recent 50 entries to manage space size.
+| Role | Capabilities |
+|------|--------------|
+| `owner` | Full control, can delete space and manage users |
+| `editor` | Can create, modify, delete objects and links |
+| `viewer` | Read-only access |
 
----
+### Space Collaboration Methods
 
-## RoolClient API
+| Method | Description |
+|--------|-------------|
+| `listUsers(): Promise<SpaceMember[]>` | List users with access |
+| `addUser(userId, role): Promise<void>` | Add user to space |
+| `removeUser(userId): Promise<void>` | Remove user from space |
 
-### Authentication
+### Client User Methods
 
 | Method | Description |
 |--------|-------------|
-| `initialize(): boolean` | **Call on app startup if running in browser.** Processes auth callback from URL, sets up token refresh. |
-| `login(): void` | Redirect to login page |
-| `logout(): void` | Clear tokens and state |
-| `isAuthenticated(): boolean` | Check auth status |
-| `getToken(): Promise<string \| undefined>` | Get current access token |
-| `getAuthUser(): AuthUser` | Get auth identity from JWT (`{ email, name }`) |
+| `getCurrentUser(): Promise<CurrentUser>` | Get current Rool user (id, email, name, plan, credits, storage) |
+| `searchUser(email): Promise<UserResult \| null>` | Find user by exact email address (no partial matching) |
+
+### Real-time Collaboration
+
+When multiple users have a space open, changes sync in real-time. The `source` field in events tells you who made the change:
+
+```typescript
+space.on('objectUpdated', ({ objectId, object, source }) => {
+  if (source === 'remote_user') {
+    // Another user made this change
+    showCollaboratorActivity(object);
+  }
+});
+```
+
+See [Real-time Sync](#real-time-sync) for more on event sources.
+
+## RoolClient API
 
 ### Space Lifecycle
 
@@ -256,14 +465,7 @@ Note: Interaction history is truncated to the most recent 50 entries to manage s
 | `listSpaces(): Promise<RoolSpaceInfo[]>` | List available spaces |
 | `openSpace(id, options?): Promise<RoolSpace>` | Open a space for editing. Options: `{ conversationId?: string }` |
 | `createSpace(name?, options?): Promise<RoolSpace>` | Create a new space. Options: `{ conversationId?: string }` |
-| `deleteSpace(id): Promise<void>` | Delete a space |
-
-### Current User
-
-| Method | Description |
-|--------|-------------|
-| `getCurrentUser(): Promise<CurrentUser>` | Get current Rool user (id, email, name, plan, credits, storage) |
-| `searchUser(email): Promise<UserResult \| null>` | Search user by email (returns id, email, name) |
+| `deleteSpace(id): Promise<void>` | Permanently delete a space (cannot be undone) |
 
 ### User Storage
 
@@ -293,10 +495,11 @@ client.setUserStorage('sidebar', { collapsed: true, width: 280 });
 // Delete a key
 client.setUserStorage('theme', null);
 
-// React to changes (from this tab, other tabs, or other devices)
+// The cache may be stale from a previous session — listen for updates
+// to apply fresh values once sync completes (or when other tabs/devices change values)
 client.on('userStorageChanged', ({ key, value, source }) => {
+  // source: 'local' (this client) or 'remote' (server/other client)
   if (key === 'theme') applyTheme(value as string);
-  console.log(`Storage updated from ${source}`); // 'local' or 'remote'
 });
 ```
 
@@ -320,8 +523,6 @@ client.on('connectionStateChanged', (state: 'connected' | 'disconnected' | 'reco
 client.on('error', (error: Error, context?: string) => void)
 ```
 
----
-
 ## RoolSpace API
 
 Spaces are first-class objects with built-in undo/redo, event emission, and real-time sync.
@@ -334,57 +535,15 @@ Spaces are first-class objects with built-in undo/redo, event emission, and real
 | `name: string` | Space name |
 | `role: RoolUserRole` | User's role (`'owner' \| 'editor' \| 'viewer'`) |
 | `userId: string` | Current user's ID |
-| `conversationId: string` | ID for interaction history (tracks AI context) |
-| `isReadOnly(): boolean` | True if viewer role |
-
-### Conversation Access
-
-| Method | Description |
-|--------|-------------|
-| `getInteractions(): Interaction[]` | Get interactions for the current conversationId |
-| `getInteractionsById(id): Interaction[]` | Get interactions for a specific conversation ID |
-| `getConversationIds(): string[]` | List all conversation IDs that have interactions |
-| `clearInteractions(conversationId?): Promise<void>` | Clear interaction history. Defaults to current conversation. |
-
-### Lifecycle
-
-| Method | Description |
-|--------|-------------|
-| `close(): void` | Clean up resources and stop receiving updates |
-| `rename(newName): Promise<void>` | Rename the space |
-
-### Undo/Redo
-
-| Method | Description |
-|--------|-------------|
-| `checkpoint(label?): Promise<string>` | Call before mutations. Saves current state for undo. |
-| `canUndo(): Promise<boolean>` | Check if undo available |
-| `canRedo(): Promise<boolean>` | Check if redo available |
-| `undo(): Promise<boolean>` | Undo to previous checkpoint |
-| `redo(): Promise<boolean>` | Redo undone action |
-| `clearHistory(): Promise<void>` | Clear undo/redo stack |
-
-Call `checkpoint()` before making changes to create a restore point. Without a checkpoint, `undo()` has nothing to restore to.
-
-Undo always restores the space to the last checkpoint, regardless of how many changes were made since.
-
-In collaborative scenarios, conflicting changes (modified by others since checkpoint) are silently skipped.
-
-```typescript
-// Create a checkpoint before user action
-await space.checkpoint('Delete object');
-await space.deleteObjects([objectId]);
-
-// User can now undo back to the checkpoint
-if (await space.canUndo()) {
-  await space.undo(); // Restores the deleted object
-}
+| `conversationId: string` | ID for interaction history (tracks AI context) |
+| `isReadOnly(): boolean` | True if viewer role |
 
-// Redo reapplies the undone action
-if (await space.canRedo()) {
-  await space.redo(); // Deletes the object again
-}
-```
+### Lifecycle
+
+| Method | Description |
+|--------|-------------|
+| `close(): void` | Clean up resources and stop receiving updates |
+| `rename(newName): Promise<void>` | Rename the space |
 
 ### Object Operations
 
@@ -392,8 +551,7 @@ Objects are plain key/value records. `id` is the only reserved field; everything
 
 | Method | Description |
 |--------|-------------|
-| `getObject(objectId): RoolObject` | Get object data. Throws if not found. |
-| `getObjectOrUndefined(objectId): RoolObject \| undefined` | Get object data, or undefined if not found. |
+| `getObject(objectId): RoolObject \| undefined` | Get object data, or undefined if not found. |
 | `findObjects(options): Promise<{ objects, message }>` | Find objects using structured filters and natural language. Server-side execution with AI. |
 | `getObjectIds(): string[]` | Get all object IDs in the space. |
 | `createObject(options): Promise<{ object, message }>` | Create a new object. Returns the object (with AI-filled content) and message. |
@@ -424,28 +582,28 @@ Find objects using structured filters, semantic matching, and natural language.
 
 ```typescript
 // Exact field matching (no AI needed)
-const { objects } = await space.findObjects({ 
-  where: { type: 'article', status: 'published' } 
+const { objects } = await space.findObjects({
+  where: { type: 'article', status: 'published' }
 });
 
 // Pure natural language query (AI interprets)
-const { objects, message } = await space.findObjects({ 
-  prompt: 'articles about space exploration published this year' 
+const { objects, message } = await space.findObjects({
+  prompt: 'articles about space exploration published this year'
 });
 
 // Semantic field matching with {{...}} placeholders
-const { objects } = await space.findObjects({ 
-  where: { 
+const { objects } = await space.findObjects({
+  where: {
     type: 'product',
     category: '{{something edible}}'  // AI interprets this
   }
 });
 
 // Combined: structured + semantic + natural language
-const { objects } = await space.findObjects({ 
-  where: { 
+const { objects } = await space.findObjects({
+  where: {
     type: 'article',
-    topic: '{{related to climate}}' 
+    topic: '{{related to climate}}'
   },
   prompt: 'that discuss solutions positively',
   limit: 10
@@ -454,71 +612,8 @@ const { objects } = await space.findObjects({
 
 The AI has access to the full object graph context (except `_`-prefixed fields) when evaluating queries. The returned `message` explains why objects matched the criteria.
 
-#### Underscore-Prefixed Fields
-
-Fields starting with `_` (e.g., `_ui`, `_cache`) are hidden from AI but otherwise behave like normal fields — they sync in real-time, persist to the server, support undo/redo, and are visible to all users of the Space. Use them for UI state, positions, or other data the AI shouldn't see or modify:
-
-```typescript
-await space.createObject({
-  data: {
-    title: 'My Article',
-    author: "John Doe",
-    _ui: { x: 100, y: 200, collapsed: false }
-  }
-});
-```
-
-#### Custom Object IDs
-
-By default, `createObject` generates a 6-character alphanumeric ID. Provide your own via `data.id`:
-
-```typescript
-await space.createObject({ data: { id: 'article-42', title: 'The Meaning of Life' } });
-```
-
-**Constraints:**
-- Must contain only alphanumeric characters, hyphens (`-`), and underscores (`_`)
-- Must be unique within the space (throws if ID exists)
-- Cannot be changed after creation (immutable)
-
-If generating your own IDs, use `RoolClient.generateId()` for efficient, guaranteed-valid IDs.
-
-#### AI Placeholder Pattern
-
-Use `{{description}}` in field values to have AI generate content:
-
-```typescript
-// Create with AI-generated content
-await space.createObject({
-  data: {
-    type: 'article',
-    headline: '{{catchy headline about coffee}}',
-    body: '{{informative paragraph}}'
-  },
-  prompt: 'Write about specialty coffee brewing'
-});
-
-// Update existing content with AI
-await space.updateObject('abc123', {
-  prompt: 'Make the body shorter and more casual'
-});
-
-// Add new AI-generated field to existing object
-await space.updateObject('abc123', {
-  data: { summary: '{{one-sentence summary}}' }
-});
-```
-
-When resolving placeholders, the agent has access to the full object data and the surrounding space context (except for `_`-prefixed fields). Placeholders are instructions, not templates, and do not need to repeat information already present in other fields.
-
-AI-generated placeholders are resolved during the mutation and replaced with concrete values. The {{...}} syntax is not stored — it is only used to guide the agent while creating or updating the object.
-
 ### Relations
 
-Relations connect objects directionally through named relations on the source object. Each relation name represents a multi-valued reference set on the source.
-
-Internally, relations are indexed and idempotent. Creating the same relation twice has no effect and produces no duplicates.
-
 | Method | Description |
 |--------|-------------|
 | `link(sourceId, relation, targetId): Promise<void>` | Add target to the named relation on source. Reads as "source.relation includes target". |
@@ -551,89 +646,28 @@ const planets = space.getChildren(sun.id, 'hasPlanet');
 const stars = space.getParents(earth.id, 'orbits');
 ```
 
-**Notes:**
-- Relation names are application-defined strings
-- Relations are not stored in object data fields
-- Only relations created via `link()` participate in traversal (`getParents`, `getChildren`) and indexing
-- Storing object IDs inside regular object fields is allowed, but those references are opaque to the system
-
-### Space Metadata
-
-Store arbitrary data alongside the Space without it being part of the graph content (e.g., viewport state, user preferences).
-
-| Method | Description |
-|--------|-------------|
-| `setMetadata(key, value): void` | Set space-level metadata |
-| `getMetadata(key): unknown` | Get metadata value |
-| `getAllMetadata(): Record<string, unknown>` | Get all metadata |
-
-### Import/Export
-
-Export space data as JSON-LD for backup, portability, or migration:
-
-| Method | Description |
-|--------|-------------|
-| `export(): JsonLdDocument` | Export all objects and relations as JSON-LD |
-| `import(data): Promise<void>` | Import JSON-LD into empty space |
-
-**Export:**
-```typescript
-const jsonld = space.export();
-// Save to file, send to API, etc.
-const json = JSON.stringify(jsonld, null, 2);
-```
-
-**Import:**
-```typescript
-// Space must be empty
-const newSpace = await client.createSpace('Imported Data');
-await newSpace.import(jsonld);
-```
-
-The JSON-LD format follows W3C standards and can be processed by standard JSON-LD tools. Objects are exported with their data and relations; space metadata and interaction history are not included.
-
-### AI Agent
+### Undo/Redo
 
 | Method | Description |
 |--------|-------------|
-| `prompt(prompt, options?): Promise<{ message: string; objects: RoolObject[] }>` | Invoke the AI agent to manipulate the space. Returns a message and the list of objects that were created or modified. |
-
-The agent has editor-level capabilities — it can create, modify, delete, link, and research — but cannot modify `_`-prefixed fields. Use `checkpoint()` before prompting to make operations undoable.
-
-| Option | Description |
-|--------|-------------|
-| `objectIds` | Limit context to specific objects |
-| `responseSchema` | Request structured JSON instead of text summary |
-| `effort` | Effort level: `'QUICK'`, `'STANDARD'` (default), `'REASONING'`, or `'RESEARCH'` |
-| `ephemeral` | If true, don't record in conversation history (useful for tab completion) |
-
-**Effort levels:**
-- `QUICK` — Fast responses, read-only (cannot create/update objects or links)
-- `STANDARD` — Default behavior with full capabilities
-- `REASONING` — Extended reasoning for complex tasks
-- `RESEARCH` — Pre-analysis and context gathering (reserved for future use)
-
-```typescript
-const { message, objects } = await space.prompt("Create a topic node for the solar system, then child nodes for each planet.");
-console.log(`AI: ${message}`);
-console.log(`Modified ${objects.length} objects:`, objects);
-
-const result = await space.prompt("Summarize these articles", { objectIds: ['article-1', 'article-2'] });
+| `checkpoint(label?): Promise<string>` | Call before mutations. Saves current state for undo. |
+| `canUndo(): Promise<boolean>` | Check if undo available |
+| `canRedo(): Promise<boolean>` | Check if redo available |
+| `undo(): Promise<boolean>` | Undo to previous checkpoint |
+| `redo(): Promise<boolean>` | Redo undone action |
+| `clearHistory(): Promise<void>` | Clear undo/redo stack |
 
-// Quick question without mutations
-const { message } = await space.prompt("What topics are covered?", { effort: 'QUICK' });
+See [Checkpoints & Undo/Redo](#checkpoints--undoredo) for semantics.
 
-// Complex analysis with extended reasoning
-await space.prompt("Analyze relationships and reorganize", { effort: 'REASONING' });
-```
+### Space Metadata
 
-### Collaboration
+Store arbitrary data alongside the Space without it being part of the graph content (e.g., viewport state, user preferences).
 
 | Method | Description |
 |--------|-------------|
-| `listUsers(): Promise<SpaceMember[]>` | List users with access |
-| `addUser(userId, role): Promise<void>` | Add user to space |
-| `removeUser(userId): Promise<void>` | Remove user from space |
+| `setMetadata(key, value): void` | Set space-level metadata |
+| `getMetadata(key): unknown` | Get metadata value, or undefined if key not set |
+| `getAllMetadata(): Record<string, unknown>` | Get all metadata |
 
 ### Media
 
@@ -664,6 +698,46 @@ if (response.contentType.startsWith('image/')) {
 }
 ```
 
+### Import/Export
+
+Export space data as JSON-LD for backup, portability, or migration:
+
+| Method | Description |
+|--------|-------------|
+| `export(): JsonLdDocument` | Export all objects and relations as JSON-LD |
+| `import(data): Promise<void>` | Import JSON-LD into empty space |
+| `exportArchive(): Promise<Blob>` | Export objects, relations, and media as a zip archive |
+| `importArchive(archive): Promise<void>` | Import from a zip archive into empty space |
+
+**Export (data only):**
+```typescript
+const jsonld = space.export();
+const json = JSON.stringify(jsonld, null, 2);
+```
+
+**Export (with media):**
+```typescript
+const archive = await space.exportArchive();
+// Save as .zip file
+const url = URL.createObjectURL(archive);
+```
+
+**Import (data only):**
+```typescript
+// Space must be empty
+const newSpace = await client.createSpace('Imported Data');
+await newSpace.import(jsonld);
+```
+
+**Import (with media):**
+```typescript
+// Space must be empty
+const newSpace = await client.createSpace('Imported Data');
+await newSpace.importArchive(archiveBlob);
+```
+
+The JSON-LD format follows W3C standards. The archive format bundles `data.json` (JSON-LD with media URLs rewritten to relative paths) and a `media/` folder containing the actual files. Space metadata and interaction history are not included in either format.
+
 ### Space Events
 
 Semantic events describe what changed. Events fire for both local changes and remote changes.
@@ -697,20 +771,6 @@ space.on('reset', ({ source }) => void)
 space.on('syncError', (error: Error) => void)
 ```
 
-**Usage pattern:**
-```typescript
-// All UI updates happen in one place, regardless of change source
-space.on('objectUpdated', ({ objectId, object, source }) => {
-  renderObject(objectId, object);
-  if (source === 'remote_agent') {
-    doLayout(); // AI might have added content
-  }
-});
-
-// Caller just makes the change - event handler does the UI work
-space.updateObject(objectId, { prompt: 'expand this' });
-```
-
 ### Error Handling
 
 AI operations may fail due to rate limiting or other transient errors. Check `error.message` for user-friendly error text:
@@ -733,8 +793,94 @@ try {
 |--------|-------------|
 | `getData(): RoolSpaceData` | Get full space data (internal format) |
 
+## Interaction History
+
+Each `RoolSpace` instance has a `conversationId` that tracks interaction history for that space. The history records all meaningful interactions (prompts, object changes, links) as self-contained entries, each capturing the request and its result. History is stored in the space data itself and syncs in real-time to all clients.
+
+### What the AI Receives
+
+AI operations (`prompt`, `createObject`, `updateObject`, `findObjects`) automatically receive:
+
+- **Interaction history** — Previous interactions and their results from this conversation
+- **Recently modified objects** — Objects in the space recently created or changed
+- **Selected objects** — Objects passed via `objectIds` are given primary focus
+
+This context flows automatically — no configuration needed. The AI sees enough history to maintain coherent interactions while respecting the `_`-prefixed field hiding rules.
+
+### Accessing History
+
+```typescript
+// Get interactions for the current conversationId
+const interactions = space.getInteractions();
+// Returns: Interaction[]
+
+// Get interactions for a specific conversation ID
+const interactions = space.getInteractionsById('other-conversation-id');
+// Returns: Interaction[]
+
+// List all conversation IDs that have interactions
+const conversationIds = space.getConversationIds();
+// Returns: string[]
+```
+
+### Conversation Access Methods
+
+| Method | Description |
+|--------|-------------|
+| `getInteractions(): Interaction[]` | Get interactions for the current conversationId |
+| `getInteractionsById(id): Interaction[]` | Get interactions for a specific conversation ID |
+| `getConversationIds(): string[]` | List all conversation IDs that have interactions |
+| `clearInteractions(conversationId?): Promise<void>` | Clear interaction history. Defaults to current conversation. |
+
+### Listening for Updates
+
+```typescript
+space.on('interactionsUpdated', ({ conversationId, source }) => {
+  // Interaction history changed - refresh if needed
+  const interactions = space.getInteractions();
+  renderInteractions(interactions);
+});
+```
+
+### Conversation Isolation
+
+By default, each call to `openSpace()` or `createSpace()` generates a new `conversationId`. This means:
+- Opening a space twice gives you two independent AI conversation histories
+- Closing and reopening a space starts fresh
+
+### Resuming Conversations
+
+Pass a `conversationId` to continue a previous conversation:
+
+```typescript
+// First conversation - save the conversationId
+const space = await client.openSpace('abc123');
+const savedConversationId = space.conversationId;
+space.close();
+
+// Later - resume the same conversation
+const resumedSpace = await client.openSpace('abc123', { conversationId: savedConversationId });
+// AI now has access to conversation history from before
+```
+
+**Use cases:**
+- **Page refresh** — Store `conversationId` in localStorage to maintain context across reloads
+- **Multiple conversations** — Maintain and switch between different conversation contexts with the same space
+- **Collaborative conversations** — Share a `conversationId` between users to enable shared AI conversation history
+
+**Tip:** Use the user's id as `conversationId` to share context across tabs/devices, or a fixed string like `'shared'` to share context across all users.
+
+Note: Interaction history is truncated to the most recent 50 entries to manage space size.
+
+### The ai Field
+
+The `ai` field in interactions distinguishes AI-generated responses from synthetic confirmations:
+- `ai: true` — AI processed this operation (prompt, or createObject/updateObject with placeholders)
+- `ai: false` — System confirmation only (e.g., "Linked X to Y", "Created object abc123")
+
+### Tool Calls
 
----
+The `toolCalls` array captures what the AI agent did during execution. Use it to build responsive UIs that show progress while the agent works — the `interactionsUpdated` event fires as each tool completes, letting you display status updates or hints in real-time.
 
 ## Data Types
 
@@ -762,6 +908,7 @@ interface RoolObjectEntry {
   data: RoolObject;                 // The actual object data
   modifiedAt?: number;              // Timestamp of last modification
   modifiedBy?: string;              // User ID who last modified
+  modifiedByName?: string | null;   // Display name at time of modification
 }
 ```
 
@@ -788,11 +935,6 @@ interface Interaction {
 }
 ```
 
-The `toolCalls` array captures what the AI agent did during execution. This provides:
-- **Real-time feedback**: Clients receive updates as tools execute (via `interactionsUpdated` event)
-- **Agent memory**: The AI sees its previous tool usage when continuing a conversation
-- **Debugging**: Inspect what tools were called and their results
-
 ### Info Types
 
 ```typescript
@@ -820,9 +962,7 @@ interface PromptOptions {
 }
 ```
 
----
-
-## What Can You Build With a Space?
+## Patterns & Examples
 
 A Rool Space is a persistent, shared world model. Applications project different interaction patterns onto the same core primitives:
 
@@ -877,4 +1017,4 @@ Below are a few representative patterns.
 
 This client is intended for use with the Rool platform and requires an account. Access is currently by invitation.
 
-Proprietary - © Lightpost One. All rights reserved.
+Proprietary — © Lightpost One. All rights reserved.