From b3f42004cbb8ebab48acd92cbc6bc1db795b33db Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 18 Nov 2025 23:03:59 +0000
Subject: [PATCH 1/2] docs: Add project documentation markdown files

Add comprehensive documentation for development and publishing:
- CLAUDE.md: AI assistant context and instructions
- LOCAL_DEVELOPMENT.md: Detailed local dev setup guide
- LOCAL_DEV_QUICKSTART.md: Quick start reference
- PUBLISHING.md: NPM publishing guide
- PROJECT_STRUCTURE.md: Codebase architecture overview
---
 CLAUDE.md               |  32 +++
 LOCAL_DEVELOPMENT.md    | 540 ++++++++++++++++++++++++++++++++++++++++
 LOCAL_DEV_QUICKSTART.md | 230 +++++++++++++++++
 PROJECT_STRUCTURE.md    | 260 +++++++++++++++++++
 PUBLISHING.md           | 367 +++++++++++++++++++++++++++
 5 files changed, 1429 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 LOCAL_DEVELOPMENT.md
 create mode 100644 LOCAL_DEV_QUICKSTART.md
 create mode 100644 PROJECT_STRUCTURE.md
 create mode 100644 PUBLISHING.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..c950b11
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,32 @@
+# CLAUDE.md
+
+**solid-ag-chat** is a SolidJS library for building chat UIs with AG-UI protocol support and bidirectional tool execution. This is a library (not a ready-to-use UI), providing primitives and hooks for developers to build custom chat interfaces.
+
+## Development Setup
+
+Key commands include `npm run dev` for watch mode (rebuilds on source changes), and `npm run build` for production builds. The main development happens in the `v2/` directory which contains the latest version.
+
+## Architecture Highlights
+
+The library exports hooks and utilities through `v2/src/index.ts`. Components reside in `v2/src/primitives/` with state management in `v2/src/store/`. It builds to ES module and CommonJS formats with peer dependencies on solid-js that consuming applications must provide.
+
+## Version Structure
+
+- **v2 (Current):** Bidirectional tool execution with automatic handler invocation
+- **v1 (Previous):** Official AG-UI protocol support
+- **v0 (Deprecated):** Legacy version with built-in UI components
+
+## State Management & Key Features
+
+The library provides hooks like `useConversation`, `useMessages`, `useToolCalls`, and `useToolExecution` for managing chat state through SolidJS signals and stores. V2 adds tool registration, execution state tracking, and human-in-the-loop patterns.
+
+## Integration & Workflows
+
+The backend expects POST requests with conversation history and returns streaming responses via Server-Sent Events following the AG-UI protocol. For active development across library and consuming apps, the recommended approach uses `npm run dev` (watch mode) alongside `npm link` for local testing without npm publication.
+
+## Key Dependencies
+
+- **@ag-ui/core** & **@ag-ui/client** - Official AG-UI protocol
+- **RxJS** - Reactive streams
+- **fast-json-patch** - JSON Patch for state deltas
+- **solid-js** (peer) - Reactive UI framework
diff --git a/LOCAL_DEVELOPMENT.md b/LOCAL_DEVELOPMENT.md
new file mode 100644
index 0000000..02d69bd
--- /dev/null
+++ b/LOCAL_DEVELOPMENT.md
@@ -0,0 +1,540 @@
+# Local Development - Using @livefire2015/solid-ag-chat Without Publishing to npm
+
+This guide shows how to use @livefire2015/solid-ag-chat in other applications during local development without publishing to npm.
+
+## Table of Contents
+
+- [Method 1: npm link (Recommended)](#method-1-npm-link-recommended)
+- [Method 2: Local File Path](#method-2-local-file-path)
+- [Method 3: Workspace/Monorepo](#method-3-workspacemonorepo)
+- [Method 4: Build and Copy](#method-4-build-and-copy)
+- [Hot Reloading Setup](#hot-reloading-setup)
+- [Troubleshooting](#troubleshooting)
+
+## Method 1: npm link (Recommended)
+
+The `npm link` command creates a symbolic link, making the library available globally and then linking it to your project.
+
+### Step-by-Step
+
+**1. In the solid-ag-chat/v2 directory:**
+
+```bash
+cd /path/to/solid-ag-chat/v2
+
+# Build the library first
+npm run build
+
+# Create a global symlink
+npm link
+```
+
+**2. In your application directory:**
+
+```bash
+cd /path/to/your-app
+
+# Link the @livefire2015/solid-ag-chat package
+npm link @livefire2015/solid-ag-chat
+```
+
+**3. Use it in your app:**
+
+```tsx
+import { ChatProvider, useConversation, useMessages } from '@livefire2015/solid-ag-chat';
+import { createSdkAgent } from '@livefire2015/solid-ag-chat';
+
+const client = createSdkAgent({
+  baseUrl: 'http://localhost:8000',
+});
+
+const App = () => {
+  return (
+    <ChatProvider client={client}>
+      <ChatInterface />
+    </ChatProvider>
+  );
+};
+```
+
+### Advantages
+- Works like a real npm package
+- Easy to set up
+- Can link to multiple projects
+- Changes reflected after rebuild
+
+### Development Workflow
+
+```bash
+# In solid-ag-chat/v2 directory
+# Make changes to source code
+npm run build
+
+# Changes are now available in linked apps
+# Just refresh your app
+```
+
+### Unlinking
+
+When you're done:
+
+```bash
+# In your application
+npm unlink @livefire2015/solid-ag-chat
+
+# In solid-ag-chat/v2 directory
+npm unlink
+```
+
+## Method 2: Local File Path
+
+Install the library directly from the file system.
+
+### Setup
+
+**In your application's package.json:**
+
+```json
+{
+  "dependencies": {
+    "@livefire2015/solid-ag-chat": "file:../solid-ag-chat/v2",
+    "solid-js": "^1.8.0"
+  }
+}
+```
+
+Then install:
+
+```bash
+npm install
+```
+
+### Advantages
+- Simple and straightforward
+- Works with npm/yarn/pnpm
+- No global linking needed
+
+### Disadvantages
+- Copies files (not symlink)
+- Need to reinstall after changes
+
+### Development Workflow
+
+```bash
+# 1. Make changes in solid-ag-chat/v2
+cd /path/to/solid-ag-chat/v2
+npm run build
+
+# 2. Reinstall in your app
+cd /path/to/your-app
+npm install
+```
+
+### Updating
+
+After making changes:
+
+```bash
+# Force reinstall
+npm install --force
+# or
+rm -rf node_modules/@livefire2015/solid-ag-chat
+npm install
+```
+
+## Method 3: Workspace/Monorepo
+
+Best for managing multiple related packages.
+
+### Setup with npm Workspaces
+
+Create a workspace structure:
+
+```
+my-project/
+├── packages/
+│   ├── solid-ag-chat/        # The library
+│   └── my-app/               # Your application
+└── package.json              # Root package.json
+```
+
+**Root package.json:**
+
+```json
+{
+  "name": "my-monorepo",
+  "private": true,
+  "workspaces": [
+    "packages/*"
+  ]
+}
+```
+
+**my-app/package.json:**
+
+```json
+{
+  "name": "my-app",
+  "dependencies": {
+    "@livefire2015/solid-ag-chat": "*",
+    "solid-js": "^1.8.0"
+  }
+}
+```
+
+**Install from root:**
+
+```bash
+# From root directory
+npm install
+```
+
+### Advantages
+- Auto-linked between packages
+- Shared dependencies
+- Easy to manage
+- Professional setup
+
+### Using pnpm Workspaces
+
+**pnpm-workspace.yaml:**
+
+```yaml
+packages:
+  - 'packages/*'
+```
+
+**Root package.json:**
+
+```json
+{
+  "name": "my-monorepo",
+  "private": true
+}
+```
+
+Then:
+
+```bash
+pnpm install
+```
+
+## Method 4: Build and Copy
+
+Manually copy the built library to your project.
+
+### Setup
+
+**1. Build solid-ag-chat:**
+
+```bash
+cd /path/to/solid-ag-chat/v2
+npm run build
+```
+
+**2. Copy to your project:**
+
+```bash
+# Create a local directory for the library
+cd /path/to/your-app
+mkdir -p local-packages/solid-ag-chat
+
+# Copy the built files
+cp -r /path/to/solid-ag-chat/v2/dist local-packages/solid-ag-chat/
+cp /path/to/solid-ag-chat/v2/package.json local-packages/solid-ag-chat/
+```
+
+**3. Install from local directory:**
+
+```json
+{
+  "dependencies": {
+    "@livefire2015/solid-ag-chat": "file:./local-packages/solid-ag-chat"
+  }
+}
+```
+
+### Advantages
+- Full control
+- No symbolic links
+- Can version locally
+
+### Disadvantages
+- Manual process
+- Need to copy after changes
+
+## Hot Reloading Setup
+
+For real-time development without rebuilding.
+
+### Option 1: Watch Mode with npm link
+
+**1. In solid-ag-chat/v2:**
+
+```bash
+cd /path/to/solid-ag-chat/v2
+npm link
+npm run dev  # This runs vite build --watch
+```
+
+**2. In your app:**
+
+```bash
+npm link @livefire2015/solid-ag-chat
+npm run dev
+```
+
+Now changes in solid-ag-chat will automatically rebuild and update in your app!
+
+### Option 2: Direct Source Import (Advanced)
+
+Configure your app to import the source directly (requires matching build setup).
+
+**vite.config.ts in your app:**
+
+```typescript
+import { defineConfig } from 'vite';
+import solidPlugin from 'vite-plugin-solid';
+import path from 'path';
+
+export default defineConfig({
+  plugins: [solidPlugin()],
+  resolve: {
+    alias: {
+      '@livefire2015/solid-ag-chat': path.resolve(__dirname, '../solid-ag-chat/v2/src')
+    }
+  }
+});
+```
+
+**Advantages:**
+- Instant updates
+- No rebuild needed
+- Best developer experience
+
+**Disadvantages:**
+- Complex setup
+- Build configs must match
+
+## Practical Examples
+
+### Example 1: Quick Test Setup
+
+```bash
+# Terminal 1: solid-ag-chat
+cd /path/to/solid-ag-chat/v2
+npm run build
+npm link
+
+# Terminal 2: your app
+cd ~/projects/my-chat-app
+npm link @livefire2015/solid-ag-chat
+npm run dev
+
+# Make changes, rebuild, refresh browser
+```
+
+### Example 2: Active Development
+
+```bash
+# Terminal 1: solid-ag-chat (watch mode)
+cd /path/to/solid-ag-chat/v2
+npm run dev
+
+# Terminal 2: your app
+cd ~/projects/my-chat-app
+npm link @livefire2015/solid-ag-chat
+npm run dev
+
+# Changes auto-rebuild and update!
+```
+
+### Example 3: Monorepo Setup
+
+```bash
+# Create structure
+mkdir my-project
+cd my-project
+
+# Move or clone solid-ag-chat
+mv /path/to/solid-ag-chat ./packages/
+
+# Create app
+mkdir -p packages/my-app
+
+# Setup workspace
+cat > package.json << 'EOF'
+{
+  "name": "my-project",
+  "private": true,
+  "workspaces": ["packages/*"]
+}
+EOF
+
+# Install everything
+npm install
+
+# Now solid-ag-chat is automatically linked!
+cd packages/my-app
+npm run dev
+```
+
+## Troubleshooting
+
+### Issue: "Cannot find module '@livefire2015/solid-ag-chat'"
+
+**Solution:**
+
+```bash
+# Rebuild the library
+cd /path/to/solid-ag-chat/v2
+npm run build
+
+# Relink
+npm link
+
+# In your app
+cd /path/to/your-app
+npm link @livefire2015/solid-ag-chat
+```
+
+### Issue: "Module not found" after linking
+
+**Solution:** Check that the library is built:
+
+```bash
+ls /path/to/solid-ag-chat/v2/dist
+# Should show: index.js, index.d.ts, index.cjs
+```
+
+If empty, run `npm run build`.
+
+### Issue: Changes not reflecting
+
+**Solution:**
+
+```bash
+# 1. Rebuild the library
+cd /path/to/solid-ag-chat/v2
+npm run build
+
+# 2. Hard refresh your app
+# In browser: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)
+
+# 3. Or restart dev server
+cd /path/to/your-app
+# Ctrl+C to stop
+npm run dev
+```
+
+### Issue: Multiple versions of SolidJS
+
+**Solution:** Use peer dependencies and ensure SolidJS is only installed once:
+
+```bash
+# In your app
+npm list solid-js
+
+# Should show only one version
+# If multiple, remove duplicates
+cd /path/to/solid-ag-chat/v2
+npm uninstall solid-js
+```
+
+### Issue: TypeScript can't find types
+
+**Solution:**
+
+```bash
+# Make sure types are built
+cd /path/to/solid-ag-chat/v2
+npm run build
+
+# Check dist folder
+ls dist/index.d.ts  # Should exist
+```
+
+## Best Practices
+
+### 1. Always Build Before Linking
+
+```bash
+cd /path/to/solid-ag-chat/v2
+npm run build
+npm link
+```
+
+### 2. Use Watch Mode for Active Development
+
+```bash
+npm run dev
+```
+
+### 3. Version Your Changes
+
+Even during local development, commit your changes:
+
+```bash
+git commit -m "feat: add new feature"
+```
+
+This helps track what version your app is using.
+
+### 4. Document Local Setup
+
+In your app's README:
+
+```markdown
+## Local Development with @livefire2015/solid-ag-chat
+
+This project uses a local version of @livefire2015/solid-ag-chat:
+
+\`\`\`bash
+cd ../solid-ag-chat/v2
+npm run build
+npm link
+
+cd ../my-app
+npm link @livefire2015/solid-ag-chat
+\`\`\`
+```
+
+## Comparison Table
+
+| Method | Setup | Updates | Hot Reload | Multiple Apps | Complexity |
+|--------|-------|---------|------------|---------------|------------|
+| npm link | Easy | Manual rebuild | With watch | Yes | Low |
+| File path | Easy | Reinstall | No | No | Low |
+| Workspace | Medium | Automatic | No | Yes | Medium |
+| Build/Copy | Manual | Manual | No | No | Low |
+| Direct source | Hard | Instant | Yes | Yes | High |
+
+## Recommended Workflow
+
+**For casual testing:**
+```bash
+npm link  # Quick and easy
+```
+
+**For active development:**
+```bash
+npm run dev  # Automatic rebuilds (watch mode)
+npm link
+```
+
+**For team projects:**
+```bash
+# Use monorepo with workspaces
+# Most professional and maintainable
+```
+
+## When to Publish to npm
+
+Consider publishing when:
+- Library is stable
+- Multiple teams need it
+- You want version control
+- Need semantic versioning
+- Want public distribution
+
+During development, local methods are faster and more flexible!
diff --git a/LOCAL_DEV_QUICKSTART.md b/LOCAL_DEV_QUICKSTART.md
new file mode 100644
index 0000000..99f63c2
--- /dev/null
+++ b/LOCAL_DEV_QUICKSTART.md
@@ -0,0 +1,230 @@
+# Local Development Quick Start
+
+Quick reference for using @livefire2015/solid-ag-chat locally without publishing to npm.
+
+## Quick Start (2 minutes)
+
+### Method 1: npm link (Recommended)
+
+**In solid-ag-chat/v2 directory:**
+```bash
+cd v2
+npm run build
+npm link
+```
+
+**In your app directory:**
+```bash
+npm link @livefire2015/solid-ag-chat
+npm run dev
+```
+
+Done! Your app now uses the local version.
+
+---
+
+## All Methods at a Glance
+
+### 1. npm link (Best for development)
+```bash
+# solid-ag-chat/v2
+npm run build
+npm link
+
+# your-app
+npm link @livefire2015/solid-ag-chat
+```
+
+### 2. File Path (Simple)
+```json
+// your-app/package.json
+{
+  "dependencies": {
+    "@livefire2015/solid-ag-chat": "file:../solid-ag-chat/v2"
+  }
+}
+```
+
+### 3. Monorepo (Professional)
+```
+project/
+├── packages/
+│   ├── solid-ag-chat/
+│   └── your-app/
+└── package.json  (with "workspaces")
+```
+
+---
+
+## Common Commands
+
+### In solid-ag-chat/v2 directory
+
+```bash
+# Build once
+npm run build
+
+# Build and watch for changes
+npm run dev
+
+# Unlink
+npm unlink
+```
+
+### In your app directory
+
+```bash
+# Link solid-ag-chat
+npm link @livefire2015/solid-ag-chat
+
+# Unlink solid-ag-chat
+npm unlink @livefire2015/solid-ag-chat
+
+# Install from npm instead
+npm install @livefire2015/solid-ag-chat
+```
+
+---
+
+## Development Workflow
+
+### Quick Test (No hot reload)
+```bash
+# Terminal 1: solid-ag-chat
+cd v2
+npm run build
+npm link
+
+# Terminal 2: your-app
+npm link @livefire2015/solid-ag-chat
+npm run dev
+
+# Make changes → rebuild → refresh browser
+```
+
+### Active Development (With hot reload)
+```bash
+# Terminal 1: solid-ag-chat
+cd v2
+npm run dev  # watch mode
+
+# Terminal 2: your-app
+npm link @livefire2015/solid-ag-chat
+npm run dev
+
+# Changes auto-rebuild!
+```
+
+---
+
+## Troubleshooting
+
+### "Cannot find module '@livefire2015/solid-ag-chat'"
+```bash
+cd solid-ag-chat/v2
+npm run build
+npm link
+```
+
+### Changes not showing
+```bash
+# Rebuild
+cd solid-ag-chat/v2
+npm run build
+
+# Hard refresh browser: Cmd+Shift+R
+```
+
+### Multiple SolidJS versions
+```bash
+# Remove SolidJS from solid-ag-chat (it's a peer dependency)
+cd solid-ag-chat/v2
+npm uninstall solid-js
+
+# Your app should provide it
+```
+
+---
+
+## File Locations
+
+```bash
+# Your setup might look like:
+~/projects/
+├── solid-ag-chat/v2/     # This library
+└── my-chat-app/          # Your app using it
+
+# Or in a monorepo:
+~/projects/my-monorepo/
+└── packages/
+    ├── solid-ag-chat/
+    └── my-chat-app/
+```
+
+---
+
+## Method Comparison
+
+| Method | Setup Time | Hot Reload | Best For |
+|--------|-----------|------------|----------|
+| npm link | 30 sec | With watch | Most cases |
+| File path | 1 min | No | Simple projects |
+| Monorepo | 5 min | No | Teams |
+
+---
+
+## Real-World Examples
+
+### Example 1: Testing a Bug Fix
+```bash
+# 1. Make changes in solid-ag-chat/v2
+vim src/primitives/useConversation.ts
+
+# 2. Rebuild
+npm run build
+
+# 3. Test in your app (already linked)
+# Just refresh the browser!
+```
+
+### Example 2: Developing New Feature
+```bash
+# Start watch mode
+cd solid-ag-chat/v2
+npm run dev  # Leave this running
+
+# In another terminal
+cd your-app
+npm run dev
+
+# Now edit solid-ag-chat files
+# They'll auto-rebuild and update!
+```
+
+### Example 3: Switching Between Local and npm
+```bash
+# Use local version
+npm link @livefire2015/solid-ag-chat
+
+# Switch back to npm version
+npm unlink @livefire2015/solid-ag-chat
+npm install @livefire2015/solid-ag-chat
+```
+
+---
+
+## Full Documentation
+
+For detailed information, see:
+- [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) - Complete guide
+- [PROJECT_STRUCTURE.md](./PROJECT_STRUCTURE.md) - Codebase overview
+
+---
+
+## Need Help?
+
+**Issue not listed?** Check [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) for:
+- Detailed troubleshooting
+- Advanced configurations
+- Alternative methods
+- Best practices
diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md
new file mode 100644
index 0000000..c190b75
--- /dev/null
+++ b/PROJECT_STRUCTURE.md
@@ -0,0 +1,260 @@
+# Project Structure
+
+Overview of the solid-ag-chat library architecture and codebase organization.
+
+## Directory Structure
+
+```
+solid-ag-chat/
+├── v2/                          # Latest: v2.0.0 - Bidirectional tool execution
+│   ├── src/
+│   │   ├── index.ts             # Main exports
+│   │   ├── types.ts             # Type definitions (AG-UI protocol + extensions)
+│   │   ├── tool-executor.ts     # V2: Tool execution engine
+│   │   ├── primitives/          # SolidJS hooks & components
+│   │   │   ├── ChatProvider.tsx      # Context provider for AG-UI client
+│   │   │   ├── useChat.ts            # Main hook
+│   │   │   ├── useConversation.ts    # Single conversation management
+│   │   │   ├── useConversationList.ts # Multi-conversation list
+│   │   │   ├── useMessages.ts        # Message retrieval
+│   │   │   ├── useStreamingText.ts   # Streaming text accumulation
+│   │   │   ├── useToolCalls.ts       # V2: Tool call tracking
+│   │   │   ├── useToolExecution.ts   # V2: Tool execution state
+│   │   │   └── usePendingTools.ts    # V2: Pending tools queue
+│   │   ├── store/               # State management (low-level)
+│   │   │   ├── state.ts              # ChatState definition
+│   │   │   └── createAgUiStore.ts    # Solid store creation & event handling
+│   │   ├── transport/           # Client implementations
+│   │   │   ├── sdk-agent.ts          # Official AG-UI SDK wrapper
+│   │   │   └── sse.ts                # LEGACY: Custom SSE client
+│   │   └── testing/             # Testing utilities
+│   │       ├── mockClient.ts         # Mock AG-UI client for testing
+│   │       └── scenarios.ts          # Test scenarios
+│   ├── package.json
+│   ├── tsconfig.json
+│   ├── vite.config.ts
+│   └── README.md
+├── v1/                          # v1.0.7 - Official AG-UI protocol support
+├── v0/                          # DEPRECATED - Legacy version
+├── CLAUDE.md                    # AI assistant instructions
+├── LOCAL_DEVELOPMENT.md         # Local development guide
+├── LOCAL_DEV_QUICKSTART.md      # Quick start for local dev
+├── PUBLISHING.md                # NPM publishing guide
+├── PROJECT_STRUCTURE.md         # This file
+└── .gitignore
+```
+
+## Core Components
+
+### Primitives (Hooks)
+
+The library provides SolidJS hooks for building chat interfaces:
+
+| Hook | Purpose |
+|------|---------|
+| `useChat` | Main hook combining conversation and message management |
+| `useConversation` | Single conversation state and actions |
+| `useConversationList` | Multi-conversation list management |
+| `useMessages` | Message retrieval for a conversation |
+| `useStreamingText` | Real-time streaming text accumulation |
+| `useToolCalls` | Tool call tracking (V2) |
+| `useToolExecution` | Tool execution state (V2) |
+| `usePendingTools` | Pending tools queue (V2) |
+
+### Transport Layer
+
+Two client implementations:
+
+1. **SdkAgClient** (`sdk-agent.ts`) - Official AG-UI SDK wrapper (recommended)
+2. **SseAgClient** (`sse.ts`) - Legacy custom SSE client
+
+### State Management
+
+The store follows SolidJS reactive patterns:
+
+```typescript
+interface ChatState {
+  revision: string;                    // Server revision tracking
+  conversations: Record<Id, ConversationDoc>;
+  messages: Record<Id, Message>;
+  attachments: Record<Id, AttachmentDoc>;
+  messagesByConversation: Record<Id, Id[]>;
+  streaming: Record<Id, {text: string}>;
+  toolCallsInProgress: Record<Id, ToolExecution>;
+  activeConversationId?: Id;
+}
+```
+
+## Integration Approaches
+
+### 1. Provider Pattern (Recommended)
+
+Use `ChatProvider` with hooks for full functionality:
+
+```tsx
+import { ChatProvider, useConversation, useMessages } from '@livefire2015/solid-ag-chat';
+import { createSdkAgent } from '@livefire2015/solid-ag-chat';
+
+const client = createSdkAgent({ baseUrl: 'http://localhost:8000' });
+
+const App = () => (
+  <ChatProvider client={client}>
+    <ChatInterface />
+  </ChatProvider>
+);
+```
+
+### 2. Direct Store Access
+
+For full control, use the store directly:
+
+```tsx
+import { createAgUiStore } from '@livefire2015/solid-ag-chat';
+
+const store = createAgUiStore(client);
+// Access store.state and store.actions directly
+```
+
+### 3. With Tool Execution (V2)
+
+Register tools for bidirectional execution:
+
+```tsx
+const tools = [
+  {
+    name: 'get_weather',
+    description: 'Get weather for a location',
+    parameters: { /* JSON Schema */ },
+    handler: async (args) => {
+      return { temperature: 72, conditions: 'sunny' };
+    }
+  }
+];
+
+<ChatProvider client={client} tools={tools}>
+  <ChatInterface />
+</ChatProvider>
+```
+
+## Backend Requirements
+
+The library expects a backend implementing the AG-UI protocol:
+
+### Request Format
+
+```typescript
+POST /agent/run
+{
+  "messages": [
+    { "role": "user", "content": "Hello" },
+    { "role": "assistant", "content": "Hi there!" }
+  ],
+  "context": { /* optional */ },
+  "tools": [ /* tool definitions */ ]
+}
+```
+
+### Response Format
+
+Server-Sent Events stream with AG-UI events:
+
+```
+event: TEXT_MESSAGE_START
+data: {"messageId": "msg_1", "role": "assistant"}
+
+event: TEXT_MESSAGE_CONTENT
+data: {"messageId": "msg_1", "delta": "Hello"}
+
+event: TEXT_MESSAGE_END
+data: {"messageId": "msg_1"}
+```
+
+## Key Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@ag-ui/core` | Official AG-UI protocol types |
+| `@ag-ui/client` | Official HTTP agent (SDK) |
+| `rxjs` | Reactive streams/observables |
+| `fast-json-patch` | JSON Patch for state deltas |
+| `solid-js` (peer) | Reactive UI framework |
+
+## Build Configuration
+
+The library builds with Vite in library mode:
+
+- **ES Module**: `dist/index.js`
+- **CommonJS**: `dist/index.cjs`
+- **TypeScript**: `dist/index.d.ts`
+
+External dependencies (not bundled): solid-js, solid-js/web, fast-json-patch, @ag-ui/core, @ag-ui/client, rxjs
+
+## Version Evolution
+
+| Version | Status | Key Features |
+|---------|--------|--------------|
+| v0 | Deprecated | Full component library with built-in UI |
+| v1 | Previous | Official AG-UI protocol, hooks pattern |
+| v2 | Current | Bidirectional tool execution, enhanced state tracking |
+
+## Development Commands
+
+```bash
+cd v2
+
+# Build for distribution
+npm run build
+
+# Watch mode for development
+npm run dev
+
+# Build JS and declarations
+npm run build:js
+```
+
+## Exported APIs
+
+### Transport Layer
+```typescript
+export { SdkAgClient, createSdkAgent } from './transport/sdk-agent';
+export { SseAgClient } from './transport/sse';
+```
+
+### Primitives
+```typescript
+export { ChatProvider, useChatContext } from './primitives/ChatProvider';
+export { useChat } from './primitives/useChat';
+export { useConversation } from './primitives/useConversation';
+export { useConversationList } from './primitives/useConversationList';
+export { useMessages } from './primitives/useMessages';
+export { useStreamingText } from './primitives/useStreamingText';
+export { useToolCalls } from './primitives/useToolCalls';
+export { useToolExecution } from './primitives/useToolExecution';
+export { usePendingTools } from './primitives/usePendingTools';
+```
+
+### Utilities
+```typescript
+export { createAgUiStore } from './store/createAgUiStore';
+export { ToolExecutor } from './tool-executor';
+export { MockAgClient } from './testing/mockClient';
+export { runBasicScenario } from './testing/scenarios';
+```
+
+## Testing
+
+Testing utilities are provided for unit testing:
+
+```typescript
+import { MockAgClient, runBasicScenario } from '@livefire2015/solid-ag-chat';
+
+const mockClient = new MockAgClient();
+await runBasicScenario(mockClient);
+```
+
+## Next Steps
+
+- See [CLAUDE.md](./CLAUDE.md) for AI assistant context
+- See [LOCAL_DEVELOPMENT.md](./LOCAL_DEVELOPMENT.md) for development setup
+- See [PUBLISHING.md](./PUBLISHING.md) for npm publishing
+- See `v2/README.md` for detailed usage documentation
diff --git a/PUBLISHING.md b/PUBLISHING.md
new file mode 100644
index 0000000..b50d212
--- /dev/null
+++ b/PUBLISHING.md
@@ -0,0 +1,367 @@
+# Publishing to NPM
+
+This guide explains how to publish @livefire2015/solid-ag-chat to npm.
+
+## Prerequisites
+
+Before publishing, ensure you have:
+
+1. npm account (logged in with access to publish)
+2. Access to publish to the `@livefire2015` scope
+3. Clean git working directory
+4. Library built successfully
+
+## Pre-Publication Checklist
+
+Before publishing a new version, complete this checklist:
+
+### 1. Update Package Metadata (if needed)
+
+Edit `v2/package.json` to verify:
+
+```json
+{
+  "name": "@livefire2015/solid-ag-chat",
+  "version": "2.0.0",
+  "author": "livefire2015",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/livefire2015/solid-ag-chat.git"
+  },
+  "bugs": {
+    "url": "https://github.com/livefire2015/solid-ag-chat/issues"
+  },
+  "homepage": "https://github.com/livefire2015/solid-ag-chat#readme"
+}
+```
+
+### 2. Verify Package Contents
+
+Check what will be published:
+
+```bash
+cd v2
+npm pack --dry-run
+```
+
+This shows all files that will be included in the package. Verify that:
+- `dist/` folder is included
+- `README.md` is included
+- Source files (`src/`) are NOT included (they shouldn't be)
+- `node_modules/` is NOT included
+
+### 3. Build the Library
+
+```bash
+cd v2
+npm run build
+```
+
+Verify the build output in `dist/`:
+- `dist/index.js` - ES module
+- `dist/index.cjs` - CommonJS module
+- `dist/index.d.ts` - TypeScript definitions
+
+## Publishing Process
+
+### For First-Time Publication
+
+If this is the first time publishing:
+
+```bash
+# 1. Verify you're logged in
+npm whoami
+
+# 2. Check package name is available
+npm search @livefire2015/solid-ag-chat
+
+# 3. Build the library
+cd v2
+npm run build
+
+# 4. Publish (with public access for scoped packages)
+npm publish --access public
+```
+
+### For Subsequent Releases
+
+#### Option 1: Using npm version (Recommended)
+
+npm automatically updates version, creates git tag, and commits:
+
+```bash
+cd v2
+
+# For patch release (2.0.0 -> 2.0.1) - Bug fixes
+npm version patch
+
+# For minor release (2.0.0 -> 2.1.0) - New features, backward compatible
+npm version minor
+
+# For major release (2.0.0 -> 3.0.0) - Breaking changes
+npm version major
+```
+
+Then build and publish:
+
+```bash
+npm run build
+npm publish
+```
+
+#### Option 2: Manual Version Update
+
+```bash
+# 1. Manually edit version in v2/package.json
+# Change "version": "2.0.0" to "version": "2.1.0"
+
+# 2. Build the library
+npm run build
+
+# 3. Commit the version change
+git add v2/package.json
+git commit -m "Bump version to 2.1.0"
+git tag v2.1.0
+git push && git push --tags
+
+# 4. Publish to npm
+npm publish
+```
+
+## Version Guidelines (Semantic Versioning)
+
+Follow [Semantic Versioning](https://semver.org/):
+
+- **MAJOR** (2.0.0 -> 3.0.0): Breaking changes
+  - Removing exported functions/hooks
+  - Changing hook APIs in incompatible ways
+  - Renaming props or exports
+
+- **MINOR** (2.0.0 -> 2.1.0): New features, backward compatible
+  - Adding new hooks
+  - Adding new props to existing hooks
+  - Adding new utilities
+
+- **PATCH** (2.0.0 -> 2.0.1): Bug fixes, backward compatible
+  - Fixing bugs
+  - Updating documentation
+  - Performance improvements
+
+## Release Workflow
+
+### Complete Release Process
+
+```bash
+# 1. Ensure clean working directory
+git status
+
+# 2. Pull latest changes
+git pull origin main
+
+# 3. Update version (choose one: patch, minor, major)
+cd v2
+npm version minor -m "Release v%s: Add new feature"
+
+# 4. Build the library
+npm run build
+
+# 5. Publish to npm
+npm publish
+
+# 6. Push git changes and tags
+git push && git push --tags
+
+# 7. Create GitHub release (optional but recommended)
+# Go to GitHub -> Releases -> Create new release
+# Use the tag you just created (e.g., v2.1.0)
+# Add release notes describing changes
+```
+
+## Post-Publication
+
+### 1. Verify Package on npm
+
+Visit: https://www.npmjs.com/package/@livefire2015/solid-ag-chat
+
+Check that:
+- Version number is correct
+- README is displaying properly
+- Dependencies are correct
+- File count looks reasonable
+
+### 2. Test Installation
+
+In a separate project, test installing the package:
+
+```bash
+npm install @livefire2015/solid-ag-chat
+# or
+npm install @livefire2015/solid-ag-chat@2.1.0
+```
+
+### 3. Update Documentation
+
+If you have external documentation, update it with:
+- New version number
+- New features
+- Migration guide (for breaking changes)
+
+## Unpublishing (Emergency Only)
+
+**Warning**: Unpublishing can break projects that depend on your package!
+
+You can only unpublish within 72 hours of publishing:
+
+```bash
+# Unpublish a specific version
+npm unpublish @livefire2015/solid-ag-chat@2.0.0
+
+# Unpublish entire package (use with extreme caution!)
+npm unpublish @livefire2015/solid-ag-chat --force
+```
+
+Better alternative: Publish a new patch version with the fix.
+
+## Deprecating Old Versions
+
+If you want to discourage use of an old version:
+
+```bash
+npm deprecate @livefire2015/solid-ag-chat@1.0.0 "Please upgrade to v2 for bidirectional tool execution"
+```
+
+## npm Scripts for Publishing
+
+You can add these helper scripts to `v2/package.json`:
+
+```json
+{
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "version": "npm run build && git add -A dist",
+    "postversion": "git push && git push --tags",
+    "release:patch": "npm version patch && npm publish",
+    "release:minor": "npm version minor && npm publish",
+    "release:major": "npm version major && npm publish"
+  }
+}
+```
+
+Then you can simply run:
+
+```bash
+npm run release:minor
+```
+
+## Troubleshooting
+
+### Error: "You do not have permission to publish"
+
+Make sure you're logged in and have access to the `@livefire2015` scope:
+
+```bash
+npm whoami
+npm access ls-packages
+```
+
+### Error: "Version already exists"
+
+You're trying to publish a version that already exists. Update the version:
+
+```bash
+npm version patch
+```
+
+### Error: "Package name too similar to existing package"
+
+If publishing for the first time, npm might flag similar package names. Contact npm support or choose a different name.
+
+### Files Missing in Published Package
+
+Check your `package.json` `files` array:
+
+```json
+{
+  "files": [
+    "dist",
+    "README.md"
+  ]
+}
+```
+
+## Best Practices
+
+1. **Always build before publishing**: Run `npm run build`
+2. **Use semantic versioning**: Follow MAJOR.MINOR.PATCH correctly
+3. **Write good release notes**: Document what changed in each version
+4. **Keep dependencies updated**: Regularly update peer dependencies
+5. **Test the published package**: Install it in a test project
+6. **Tag releases in git**: Use `git tag` for version tracking
+7. **Create GitHub releases**: Add release notes on GitHub
+
+## Quick Reference
+
+```bash
+# Check login status
+npm whoami
+
+# Dry run to see what will be published
+cd v2
+npm pack --dry-run
+
+# Build
+npm run build
+
+# Publish (first time)
+npm publish --access public
+
+# Update version and publish (subsequent releases)
+npm version patch  # or minor, or major
+npm run build
+npm publish
+
+# Push git changes
+git push && git push --tags
+```
+
+## Example Release
+
+Here's a complete example of publishing version 2.1.0 with new features:
+
+```bash
+# 1. Ensure everything is ready
+cd v2
+git status
+npm run build
+
+# 2. Update version
+npm version minor -m "Release v%s: Add useToolExecution improvements"
+# This creates commit and tag automatically
+
+# 3. Publish
+npm publish
+
+# 4. Push to git
+git push origin main
+git push --tags
+
+# 5. Create GitHub release
+# Go to https://github.com/livefire2015/solid-ag-chat/releases/new
+# Select tag: v2.1.0
+# Title: "v2.1.0 - Tool Execution Improvements"
+# Description:
+# ## New Features
+# - Improved tool execution state tracking
+# - Added new hooks for pending tools
+#
+# ## Breaking Changes
+# None
+#
+# ## Installation
+# ```bash
+# npm install @livefire2015/solid-ag-chat@2.1.0
+# ```
+```
+
+Done! Your package is now published to npm!

From f705701b35f9eb8d643a319f7653b5e960ec70cd Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 19 Nov 2025 00:09:19 +0000
Subject: [PATCH 2/2] docs: Add comprehensive v0, v1, v2 coverage to all
 markdown files

Update all documentation files to include information about all three
versions (v0, v1, v2) of the library:

- CLAUDE.md: Add development commands for each version
- LOCAL_DEVELOPMENT.md: Add version selection table and switching guide
- LOCAL_DEV_QUICKSTART.md: Add version-specific features and link commands
- PUBLISHING.md: Add publishing instructions for each version
- PROJECT_STRUCTURE.md: Expand directory structure and exports for all versions
---
 CLAUDE.md               |  24 +++++++-
 LOCAL_DEVELOPMENT.md    |  60 +++++++++++++++++++
 LOCAL_DEV_QUICKSTART.md |  51 ++++++++++++++++
 PROJECT_STRUCTURE.md    | 129 ++++++++++++++++++++++++++++++++++------
 PUBLISHING.md           |  70 ++++++++++++++++++++++
 5 files changed, 315 insertions(+), 19 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index c950b11..6faab7d 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -4,11 +4,31 @@
 
 ## Development Setup
 
-Key commands include `npm run dev` for watch mode (rebuilds on source changes), and `npm run build` for production builds. The main development happens in the `v2/` directory which contains the latest version.
+The project contains three versions in separate directories:
+
+```bash
+# v2 (Current - Recommended)
+cd v2 && npm run dev    # Watch mode
+cd v2 && npm run build  # Production build
+
+# v1 (Previous)
+cd v1 && npm run dev
+cd v1 && npm run build
+
+# v0 (Deprecated)
+cd v0 && npm run dev
+cd v0 && npm run build
+```
 
 ## Architecture Highlights
 
-The library exports hooks and utilities through `v2/src/index.ts`. Components reside in `v2/src/primitives/` with state management in `v2/src/store/`. It builds to ES module and CommonJS formats with peer dependencies on solid-js that consuming applications must provide.
+Each version has its own architecture:
+
+- **v2**: Exports through `v2/src/index.ts`, primitives in `v2/src/primitives/`, state in `v2/src/store/`
+- **v1**: Exports through `v1/src/index.ts`, similar structure to v2 but without tool execution
+- **v0**: Exports through `v0/src/index.tsx`, includes built-in UI components
+
+All versions build to ES module and CommonJS formats with peer dependencies on solid-js.
 
 ## Version Structure
 
diff --git a/LOCAL_DEVELOPMENT.md b/LOCAL_DEVELOPMENT.md
index 02d69bd..7a9f480 100644
--- a/LOCAL_DEVELOPMENT.md
+++ b/LOCAL_DEVELOPMENT.md
@@ -2,6 +2,18 @@
 
 This guide shows how to use @livefire2015/solid-ag-chat in other applications during local development without publishing to npm.
 
+## Version Selection
+
+The library has three versions available:
+
+| Version | Directory | Status | Use Case |
+|---------|-----------|--------|----------|
+| v2 | `v2/` | **Current** | Bidirectional tool execution (recommended) |
+| v1 | `v1/` | Previous | Official AG-UI protocol support |
+| v0 | `v0/` | Deprecated | Legacy with built-in UI components |
+
+**Note**: Throughout this guide, replace `v2` with `v1` or `v0` if you need to work with those versions.
+
 ## Table of Contents
 
 - [Method 1: npm link (Recommended)](#method-1-npm-link-recommended)
@@ -538,3 +550,51 @@ Consider publishing when:
 - Want public distribution
 
 During development, local methods are faster and more flexible!
+
+## Working with Different Versions
+
+### Linking a Specific Version
+
+```bash
+# For v2 (recommended)
+cd /path/to/solid-ag-chat/v2
+npm run build && npm link
+
+# For v1
+cd /path/to/solid-ag-chat/v1
+npm run build && npm link
+
+# For v0
+cd /path/to/solid-ag-chat/v0
+npm run build && npm link
+```
+
+### Version-Specific Imports
+
+```tsx
+// v2 - Bidirectional tool execution
+import { ChatProvider, useConversation, useToolExecution } from '@livefire2015/solid-ag-chat';
+
+// v1 - AG-UI protocol support
+import { ChatProvider, useConversation, useMessages } from '@livefire2015/solid-ag-chat';
+
+// v0 - Built-in UI components
+import { ChatContainer, MessageList, Composer } from '@livefire2015/solid-ag-chat';
+```
+
+### Switching Between Versions
+
+To switch from one version to another:
+
+```bash
+# Unlink current version
+npm unlink @livefire2015/solid-ag-chat
+
+# Link new version
+cd /path/to/solid-ag-chat/v1  # or v0, v2
+npm run build
+npm link
+
+# In your app
+npm link @livefire2015/solid-ag-chat
+```
diff --git a/LOCAL_DEV_QUICKSTART.md b/LOCAL_DEV_QUICKSTART.md
index 99f63c2..2263c4e 100644
--- a/LOCAL_DEV_QUICKSTART.md
+++ b/LOCAL_DEV_QUICKSTART.md
@@ -2,6 +2,18 @@
 
 Quick reference for using @livefire2015/solid-ag-chat locally without publishing to npm.
 
+## Version Selection
+
+| Version | Directory | Status | Description |
+|---------|-----------|--------|-------------|
+| **v2** | `v2/` | Current | Bidirectional tool execution (recommended) |
+| v1 | `v1/` | Previous | AG-UI protocol support |
+| v0 | `v0/` | Deprecated | Built-in UI components |
+
+**Note**: Examples below use v2. Replace with `v1` or `v0` as needed.
+
+---
+
 ## Quick Start (2 minutes)
 
 ### Method 1: npm link (Recommended)
@@ -213,6 +225,45 @@ npm install @livefire2015/solid-ag-chat
 
 ---
 
+## Working with All Versions
+
+### Quick Link Commands
+
+```bash
+# v2 (Current - Recommended)
+cd solid-ag-chat/v2 && npm run build && npm link
+
+# v1 (Previous)
+cd solid-ag-chat/v1 && npm run build && npm link
+
+# v0 (Deprecated)
+cd solid-ag-chat/v0 && npm run build && npm link
+```
+
+### Version-Specific Features
+
+| Version | Key Exports |
+|---------|-------------|
+| v2 | `useToolExecution`, `useToolCalls`, `usePendingTools` |
+| v1 | `useConversation`, `useMessages`, `useStreamingText` |
+| v0 | `ChatContainer`, `MessageList`, `Composer` |
+
+### Switching Versions
+
+```bash
+# Unlink current
+npm unlink @livefire2015/solid-ag-chat
+
+# Link different version
+cd solid-ag-chat/v1  # or v0, v2
+npm run build && npm link
+
+# In your app
+npm link @livefire2015/solid-ag-chat
+```
+
+---
+
 ## Full Documentation
 
 For detailed information, see:
diff --git a/PROJECT_STRUCTURE.md b/PROJECT_STRUCTURE.md
index c190b75..e34f629 100644
--- a/PROJECT_STRUCTURE.md
+++ b/PROJECT_STRUCTURE.md
@@ -35,7 +35,35 @@ solid-ag-chat/
 │   ├── vite.config.ts
 │   └── README.md
 ├── v1/                          # v1.0.7 - Official AG-UI protocol support
-├── v0/                          # DEPRECATED - Legacy version
+│   ├── src/
+│   │   ├── index.ts             # Main exports
+│   │   ├── types.ts             # Type definitions
+│   │   ├── primitives/          # SolidJS hooks (no tool execution)
+│   │   │   ├── ChatProvider.tsx
+│   │   │   ├── useChat.ts
+│   │   │   ├── useConversation.ts
+│   │   │   ├── useConversationList.ts
+│   │   │   ├── useMessages.ts
+│   │   │   └── useStreamingText.ts
+│   │   ├── store/               # State management
+│   │   └── transport/           # Client implementations
+│   ├── package.json
+│   ├── tsconfig.json
+│   └── vite.config.ts
+├── v0/                          # DEPRECATED - Legacy version with UI
+│   ├── src/
+│   │   ├── index.tsx            # Main exports (note: .tsx)
+│   │   ├── components/          # Built-in UI components
+│   │   │   ├── ChatContainer.tsx
+│   │   │   ├── MessageList.tsx
+│   │   │   ├── Message.tsx
+│   │   │   └── Composer.tsx
+│   │   ├── hooks/               # Chat hooks
+│   │   │   └── useChatStream.ts
+│   │   └── stores/              # Multiple storage modes
+│   ├── package.json
+│   ├── tsconfig.json
+│   └── vite.config.ts
 ├── CLAUDE.md                    # AI assistant instructions
 ├── LOCAL_DEVELOPMENT.md         # Local development guide
 ├── LOCAL_DEV_QUICKSTART.md      # Quick start for local dev
@@ -197,48 +225,115 @@ External dependencies (not bundled): solid-js, solid-js/web, fast-json-patch, @a
 | v1 | Previous | Official AG-UI protocol, hooks pattern |
 | v2 | Current | Bidirectional tool execution, enhanced state tracking |
 
+### v0 Details (Deprecated)
+
+- **Architecture**: Complete UI component library
+- **Key Exports**: `ChatContainer`, `MessageList`, `Message`, `Composer`, `useChatStream`
+- **Storage Modes**: Local, remote, IndexedDB
+- **Use Case**: Quick prototyping with pre-built UI
+
+### v1 Details (Previous)
+
+- **Architecture**: Hooks-based library (no UI components)
+- **Key Exports**: `ChatProvider`, `useConversation`, `useMessages`, `useStreamingText`
+- **Protocol**: Official AG-UI protocol support
+- **Use Case**: Custom UI with AG-UI backend
+
+### v2 Details (Current)
+
+- **Architecture**: Hooks-based with bidirectional tool execution
+- **Key Exports**: All v1 exports + `useToolCalls`, `useToolExecution`, `usePendingTools`
+- **Protocol**: Full AG-UI protocol with tool execution
+- **Use Case**: AI agents with tool calling capabilities
+
 ## Development Commands
 
+### v2 (Recommended)
+
 ```bash
 cd v2
+npm run build      # Build for distribution
+npm run dev        # Watch mode for development
+npm run build:js   # Build JS and declarations
+```
+
+### v1
 
-# Build for distribution
-npm run build
+```bash
+cd v1
+npm run build      # Build for distribution
+npm run dev        # Watch mode for development
+```
 
-# Watch mode for development
-npm run dev
+### v0
 
-# Build JS and declarations
-npm run build:js
+```bash
+cd v0
+npm run build      # Build for distribution
+npm run dev        # Watch mode for development
 ```
 
 ## Exported APIs
 
-### Transport Layer
+### v2 Exports
+
 ```typescript
+// Transport Layer
 export { SdkAgClient, createSdkAgent } from './transport/sdk-agent';
 export { SseAgClient } from './transport/sse';
+
+// Primitives
+export { ChatProvider, useChatContext } from './primitives/ChatProvider';
+export { useChat } from './primitives/useChat';
+export { useConversation } from './primitives/useConversation';
+export { useConversationList } from './primitives/useConversationList';
+export { useMessages } from './primitives/useMessages';
+export { useStreamingText } from './primitives/useStreamingText';
+export { useToolCalls } from './primitives/useToolCalls';          // V2 only
+export { useToolExecution } from './primitives/useToolExecution';  // V2 only
+export { usePendingTools } from './primitives/usePendingTools';    // V2 only
+
+// Utilities
+export { createAgUiStore } from './store/createAgUiStore';
+export { ToolExecutor } from './tool-executor';                    // V2 only
+export { MockAgClient } from './testing/mockClient';
+export { runBasicScenario } from './testing/scenarios';
 ```
 
-### Primitives
+### v1 Exports
+
 ```typescript
+// Transport Layer
+export { SdkAgClient, createSdkAgent } from './transport/sdk-agent';
+export { SseAgClient } from './transport/sse';
+
+// Primitives
 export { ChatProvider, useChatContext } from './primitives/ChatProvider';
 export { useChat } from './primitives/useChat';
 export { useConversation } from './primitives/useConversation';
 export { useConversationList } from './primitives/useConversationList';
 export { useMessages } from './primitives/useMessages';
 export { useStreamingText } from './primitives/useStreamingText';
-export { useToolCalls } from './primitives/useToolCalls';
-export { useToolExecution } from './primitives/useToolExecution';
-export { usePendingTools } from './primitives/usePendingTools';
+
+// Utilities
+export { createAgUiStore } from './store/createAgUiStore';
 ```
 
-### Utilities
+### v0 Exports
+
 ```typescript
-export { createAgUiStore } from './store/createAgUiStore';
-export { ToolExecutor } from './tool-executor';
-export { MockAgClient } from './testing/mockClient';
-export { runBasicScenario } from './testing/scenarios';
+// Components (Pre-built UI)
+export { ChatContainer } from './components/ChatContainer';
+export { MessageList } from './components/MessageList';
+export { Message } from './components/Message';
+export { Composer } from './components/Composer';
+
+// Hooks
+export { useChatStream } from './hooks/useChatStream';
+
+// Stores
+export { createLocalStore } from './stores/local';
+export { createRemoteStore } from './stores/remote';
 ```
 
 ## Testing
diff --git a/PUBLISHING.md b/PUBLISHING.md
index b50d212..ea0100f 100644
--- a/PUBLISHING.md
+++ b/PUBLISHING.md
@@ -2,6 +2,18 @@
 
 This guide explains how to publish @livefire2015/solid-ag-chat to npm.
 
+## Version Overview
+
+The project contains three versions that can be published independently:
+
+| Version | Directory | npm Package Version | Status |
+|---------|-----------|---------------------|--------|
+| v2 | `v2/` | 2.x.x | **Current** (Recommended) |
+| v1 | `v1/` | 1.x.x | Previous |
+| v0 | `v0/` | 0.x.x | Deprecated |
+
+**Note**: Each version directory has its own `package.json` with its own version number.
+
 ## Prerequisites
 
 Before publishing, ensure you have:
@@ -365,3 +377,61 @@ git push --tags
 ```
 
 Done! Your package is now published to npm!
+
+## Publishing Different Versions
+
+### Publishing v2 (Current)
+
+```bash
+cd v2
+npm run build
+npm version minor -m "Release v%s: New feature"
+npm publish
+git push && git push --tags
+```
+
+### Publishing v1 (Previous)
+
+```bash
+cd v1
+npm run build
+npm version patch -m "Release v%s: Bug fix"
+npm publish
+git push && git push --tags
+```
+
+### Publishing v0 (Deprecated)
+
+**Note**: v0 is deprecated. Only publish critical security fixes.
+
+```bash
+cd v0
+npm run build
+npm version patch -m "Release v%s: Security fix"
+npm publish
+git push && git push --tags
+
+# Mark as deprecated
+npm deprecate @livefire2015/solid-ag-chat@0.x.x "Please upgrade to v2"
+```
+
+### Version-Specific Build Outputs
+
+| Version | ES Module | CommonJS | Types |
+|---------|-----------|----------|-------|
+| v2 | `dist/index.js` | `dist/index.cjs` | `dist/index.d.ts` |
+| v1 | `dist/index.js` | `dist/index.cjs` | `dist/index.d.ts` |
+| v0 | `dist/index.js` | `dist/index.cjs` | `dist/index.d.ts` |
+
+### Checking Published Versions
+
+```bash
+# View all published versions
+npm view @livefire2015/solid-ag-chat versions
+
+# View specific version info
+npm view @livefire2015/solid-ag-chat@2.0.0
+
+# Check deprecation status
+npm view @livefire2015/solid-ag-chat deprecated
+```