diff --git a/AGENT_ARCHITECTURE.md b/AGENT_ARCHITECTURE.md
new file mode 100644
index 0000000000..a320eb1fba
--- /dev/null
+++ b/AGENT_ARCHITECTURE.md
@@ -0,0 +1,2371 @@
+# Bolt.new Agent Architecture - Complete Technical Guide
+
+## Table of Contents
+1. [Overview](#overview)
+2. [Core Concepts](#core-concepts)
+3. [Architecture Diagram](#architecture-diagram)
+4. [System Components](#system-components)
+5. [Execution Flow](#execution-flow)
+6. [State Management](#state-management)
+7. [UI Components](#ui-components)
+8. [Code Examples](#code-examples)
+9. [Key Files Reference](#key-files-reference)
+10. [Advanced Topics](#advanced-topics)
+
+---
+
+## Overview
+
+### What is the "Agent" in Bolt.new?
+
+Bolt.new implements a **parser-driven autonomous execution system** where Claude AI acts as a code-generating agent. The "autonomous feel" comes from the fact that once Claude responds with instructions, the system automatically:
+
+1. Parses XML-wrapped actions from Claude's streaming response
+2. Executes file operations and shell commands sequentially
+3. Updates the UI in real-time to show progress
+4. Syncs changes to a browser-based Node.js environment (WebContainer)
+
+**Key Insight**: The agent is not a separate entity - it's Claude AI responding with specially formatted XML that triggers automated execution through a sophisticated parser and runner system.
+
+---
+
+## Core Concepts
+
+### 1. Artifacts
+
+An **artifact** represents a complete project or solution generated by Claude.
+
+```typescript
+interface BoltArtifactData {
+  id: string;        // Unique identifier (e.g., "react-todo-app")
+  title: string;     // Human-readable title (e.g., "React Todo Application")
+}
+```
+
+**Purpose**: Container for a collection of actions that together build an application.
+
+### 2. Actions
+
+An **action** is a single atomic operation that modifies the WebContainer environment.
+
+```typescript
+type ActionType = 'file' | 'shell';
+
+interface FileAction {
+  type: 'file';
+  filePath: string;  // e.g., "src/App.tsx"
+  content: string;   // Full file contents
+}
+
+interface ShellAction {
+  type: 'shell';
+  content: string;   // e.g., "npm install react"
+}
+
+type BoltAction = FileAction | ShellAction;
+```
+
+### 3. Action States
+
+Actions progress through a lifecycle:
+
+```typescript
+type ActionStatus =
+  | 'pending'    // Queued but not started
+  | 'running'    // Currently executing
+  | 'complete'   // Successfully finished
+  | 'failed'     // Execution error
+  | 'aborted';   // User cancelled
+```
+
+### 4. WebContainer
+
+A **browser-based Node.js runtime** that provides:
+- Virtual file system
+- Shell command execution
+- Package manager (npm/pnpm)
+- Dev server capabilities
+- Network access
+
+**Constraints**:
+- No native binaries
+- No Python pip (only Pyodide)
+- Limited system-level operations
+- All in-browser execution
+
+---
+
+## Architecture Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                           USER INTERACTION                          │
+│                    (Chat Input + Send Message)                      │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                        CHAT.CLIENT.TSX                              │
+│                  (useChat hook from ai/react)                       │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 ▼ HTTP POST
+┌─────────────────────────────────────────────────────────────────────┐
+│                       API ROUTE: /api/chat                          │
+│                   (app/routes/api.chat.ts)                          │
+│                                                                      │
+│  • Validates request                                                │
+│  • Extracts conversation history                                    │
+│  • Calls stream-text.ts                                             │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                      STREAM-TEXT.TS                                 │
+│              (app/lib/.server/llm/stream-text.ts)                   │
+│                                                                      │
+│  • Loads system prompt from prompts.ts                              │
+│  • Builds conversation context (file contents + history)            │
+│  • Calls Anthropic Claude API                                       │
+│  • Streams response back                                            │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 ▼ Streaming Response
+┌─────────────────────────────────────────────────────────────────────┐
+│                      CLAUDE API RESPONSE                            │
+│                                                                      │
+│  Example Response:                                                  │
+│  ┌─────────────────────────────────────────────────────┐           │
+│  │ I'll create a React app for you.                    │           │
+│  │                                                      │           │
+│  │ <boltArtifact id="app" title="React App">           │           │
+│  │   <boltAction type="file" filePath="package.json">  │           │
+│  │     { "name": "app", ... }                          │           │
+│  │   </boltAction>                                     │           │
+│  │   <boltAction type="shell">                         │           │
+│  │     npm install                                     │           │
+│  │   </boltAction>                                     │           │
+│  │ </boltArtifact>                                     │           │
+│  └─────────────────────────────────────────────────────┘           │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 ▼ Chunked Stream
+┌─────────────────────────────────────────────────────────────────────┐
+│                    STREAMING MESSAGE PARSER                         │
+│              (app/lib/runtime/message-parser.ts)                    │
+│                                                                      │
+│  • Parses incremental XML chunks                                    │
+│  • Extracts <boltArtifact> tags                                     │
+│  • Extracts <boltAction> tags                                       │
+│  • Fires callbacks on open/close tags                               │
+│                                                                      │
+│  Callbacks:                                                          │
+│    onArtifactOpen(data)  ────────────┐                             │
+│    onArtifactClose()     ────────────┤                             │
+│    onActionOpen(data)    ────────────┤                             │
+│    onActionClose(data)   ────────────┤                             │
+└──────────────────────────────────────┼──────────────────────────────┘
+                                       │
+                                       ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                       WORKBENCH STORE                               │
+│                  (app/lib/stores/workbench.ts)                      │
+│                                                                      │
+│  State Management (Nanostores):                                     │
+│  ┌────────────────────────────────────────────────────┐            │
+│  │ artifacts: Map<messageId, ArtifactState>           │            │
+│  │   ├─ id: string                                    │            │
+│  │   ├─ title: string                                 │            │
+│  │   ├─ closed: boolean                               │            │
+│  │   └─ runner: ActionRunner ◄─────┐                 │            │
+│  │                                   │                 │            │
+│  │ showWorkbench: boolean            │                 │            │
+│  │ currentView: 'code' | 'preview'   │                 │            │
+│  │ unsavedFiles: Set<string>         │                 │            │
+│  └────────────────────────────────────┼────────────────┘            │
+│                                       │                              │
+│  Methods:                             │                              │
+│    addArtifact() ─────────────────────┤                             │
+│    addAction() ───────────────────────┤                             │
+│    runAction() ───────────────────────┤                             │
+└───────────────────────────────────────┼──────────────────────────────┘
+                                        │
+                                        ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         ACTION RUNNER                               │
+│                 (app/lib/runtime/action-runner.ts)                  │
+│                                                                      │
+│  Manages sequential execution:                                      │
+│  ┌────────────────────────────────────────────────────┐            │
+│  │  Actions Queue: [Action1, Action2, Action3, ...]   │            │
+│  │                     ▼                               │            │
+│  │              #currentExecutionPromise               │            │
+│  │                     │                               │            │
+│  │         ┌───────────┴───────────┐                  │            │
+│  │         ▼                       ▼                   │            │
+│  │  #runFileAction()      #runShellAction()           │            │
+│  │         │                       │                   │            │
+│  │         └───────────┬───────────┘                  │            │
+│  │                     ▼                               │            │
+│  │              Update Action State                    │            │
+│  │         (pending → running → complete)              │            │
+│  └────────────────────────────────────────────────────┘            │
+│                                                                      │
+│  Key Methods:                                                        │
+│    • addAction(data): Registers action with AbortController         │
+│    • runAction(data): Queues and executes action                    │
+│    • #executeAction(): Routes to file or shell executor             │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                    ┌────────────┴────────────┐
+                    ▼                         ▼
+┌──────────────────────────┐    ┌──────────────────────────┐
+│   FILE ACTION EXECUTION  │    │  SHELL ACTION EXECUTION  │
+│                          │    │                          │
+│  webcontainer.fs         │    │  webcontainer.spawn()    │
+│    .writeFile(           │    │    ('jsh', ['-c', cmd])  │
+│      filePath,           │    │                          │
+│      content             │    │  • Captures stdout       │
+│    )                     │    │  • Captures stderr       │
+│                          │    │  • Monitors exit code    │
+└────────────┬─────────────┘    └────────────┬─────────────┘
+             │                               │
+             └───────────┬───────────────────┘
+                         ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│                         WEBCONTAINER                                │
+│                  (Browser-based Node.js)                            │
+│                                                                      │
+│  • Virtual File System (in-memory)                                  │
+│  • Shell (jsh - JavaScript shell)                                   │
+│  • npm/pnpm package managers                                        │
+│  • Dev servers (Vite, webpack, etc.)                                │
+│  • Network access                                                   │
+└────────────────────────────────┬────────────────────────────────────┘
+                                 │
+                                 ▼ File System Changes
+┌─────────────────────────────────────────────────────────────────────┐
+│                          UI UPDATES                                 │
+│                                                                      │
+│  Left Side (Chat):                Right Side (Workbench):           │
+│  ┌────────────────────┐          ┌──────────────────────┐          │
+│  │ Artifact Component │          │ Code Editor          │          │
+│  │  • Title           │          │  • File Tree         │          │
+│  │  • Action List     │          │  • Monaco Editor     │          │
+│  │    ⟳ Running       │          │  • Live Sync         │          │
+│  │    ✓ Complete      │          │                      │          │
+│  │    ○ Pending       │          │ Preview Panel        │          │
+│  │    ✗ Failed        │          │  • iframe            │          │
+│  │                    │          │  • Live Reload       │          │
+│  └────────────────────┘          └──────────────────────┘          │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## System Components
+
+### 1. StreamingMessageParser
+
+**Location**: `app/lib/runtime/message-parser.ts` (286 lines)
+
+**Purpose**: Incrementally parse streaming XML responses from Claude to extract artifacts and actions.
+
+**Key Features**:
+- Handles chunked/partial XML across multiple stream packets
+- State machine for tag parsing
+- Callback-based architecture for real-time processing
+- Supports nested tags and attributes
+
+**Class Structure**:
+
+```typescript
+class StreamingMessageParser {
+  private _text: string = '';
+  private _currentAction: Partial<BoltAction> | null = null;
+  private _currentArtifact: Partial<BoltArtifactData> | null = null;
+
+  constructor(options: {
+    callbacks: {
+      onArtifactOpen?: (data: BoltArtifactData) => void;
+      onArtifactClose?: () => void;
+      onActionOpen?: (data: Partial<BoltAction>) => void;
+      onActionClose?: (data: BoltAction) => void;
+    };
+  });
+
+  parse(chunk: string): void;
+  // Incrementally processes text, firing callbacks when complete tags detected
+}
+```
+
+**Example Usage**:
+
+```typescript
+const parser = new StreamingMessageParser({
+  callbacks: {
+    onArtifactOpen: (data) => {
+      console.log('Artifact started:', data.id, data.title);
+    },
+    onActionClose: (action) => {
+      if (action.type === 'file') {
+        console.log('File action:', action.filePath);
+      } else {
+        console.log('Shell action:', action.content);
+      }
+    }
+  }
+});
+
+// As chunks arrive from API:
+streamReader.on('data', (chunk) => {
+  parser.parse(chunk);
+});
+```
+
+**Parsing Algorithm**:
+
+1. Accumulate text in `_text` buffer
+2. Search for `<boltArtifact>`, `<boltAction>` tags
+3. Extract attributes using regex
+4. Track opening/closing tags with stack
+5. Fire callbacks when tags close (content is complete)
+6. Handle escape sequences and special characters
+
+---
+
+### 2. ActionRunner
+
+**Location**: `app/lib/runtime/action-runner.ts` (186 lines)
+
+**Purpose**: Execute file and shell actions sequentially in WebContainer with state tracking.
+
+**Key Features**:
+- Sequential execution queue (prevents race conditions)
+- AbortController support for cancellation
+- State tracking (pending → running → complete/failed)
+- Error handling and logging
+
+**Class Structure**:
+
+```typescript
+class ActionRunner {
+  #webcontainer: Promise<WebContainer>;
+  #currentExecutionPromise: Promise<void> = Promise.resolve();
+  runtimeLogger: () => ILogger;
+
+  actions: MapStore<Record<string, ActionState>>;
+
+  constructor(
+    webcontainerPromise: Promise<WebContainer>,
+    runtimeLogger: () => ILogger
+  );
+
+  addAction(data: ActionCallbackData): void;
+  // Registers action in 'pending' state with AbortController
+
+  runAction(data: ActionCallbackData): void;
+  // Queues action for execution
+
+  #executeAction(actionId: string): Promise<void>;
+  // Routes to #runFileAction or #runShellAction
+
+  #runFileAction(action: ActionState): Promise<void>;
+  // Writes file to WebContainer filesystem
+
+  #runShellAction(action: ActionState): Promise<void>;
+  // Spawns shell process in WebContainer
+}
+```
+
+**Action State Interface**:
+
+```typescript
+interface ActionState {
+  action: BoltAction;
+  status: ActionStatus;
+  abort: () => void;  // Triggers AbortController
+  executed: boolean;
+  abortSignal: AbortSignal;
+}
+```
+
+**Execution Flow**:
+
+```typescript
+// 1. Add action (called from parser callback)
+actionRunner.addAction({
+  messageId: 'msg-123',
+  actionId: 'action-456',
+  action: {
+    type: 'file',
+    filePath: 'src/App.tsx',
+    content: 'export default function App() { ... }'
+  }
+});
+
+// 2. Run action (called immediately after add)
+actionRunner.runAction({
+  messageId: 'msg-123',
+  actionId: 'action-456',
+  action: { /* same action */ }
+});
+
+// Internal execution:
+// - Queued via #currentExecutionPromise.then(...)
+// - Status updated to 'running'
+// - File written or shell command executed
+// - Status updated to 'complete' or 'failed'
+```
+
+**File Action Execution**:
+
+```typescript
+async #runFileAction(action: ActionState): Promise<void> {
+  const { filePath, content } = action.action as FileAction;
+
+  try {
+    const webcontainer = await this.#webcontainer;
+
+    // Ensure directory exists
+    const dirname = path.dirname(filePath);
+    await webcontainer.fs.mkdir(dirname, { recursive: true });
+
+    // Write file
+    await webcontainer.fs.writeFile(filePath, content);
+
+    // Update state
+    this.#updateAction(action.id, { status: 'complete' });
+  } catch (error) {
+    this.#updateAction(action.id, { status: 'failed' });
+    throw error;
+  }
+}
+```
+
+**Shell Action Execution**:
+
+```typescript
+async #runShellAction(action: ActionState): Promise<void> {
+  const { content: command } = action.action as ShellAction;
+
+  try {
+    const webcontainer = await this.#webcontainer;
+
+    // Spawn shell process
+    const process = await webcontainer.spawn('jsh', ['-c', command], {
+      signal: action.abortSignal
+    });
+
+    // Capture output
+    process.output.pipeTo(new WritableStream({
+      write(data) {
+        console.log('Shell output:', data);
+      }
+    }));
+
+    // Wait for exit
+    const exitCode = await process.exit;
+
+    if (exitCode === 0) {
+      this.#updateAction(action.id, { status: 'complete' });
+    } else {
+      this.#updateAction(action.id, { status: 'failed' });
+    }
+  } catch (error) {
+    this.#updateAction(action.id, { status: 'failed' });
+    throw error;
+  }
+}
+```
+
+---
+
+### 3. Workbench Store
+
+**Location**: `app/lib/stores/workbench.ts` (277 lines)
+
+**Purpose**: Central state management for artifacts, actions, files, and UI state.
+
+**Technology**: Nanostores (lightweight reactive state library)
+
+**Store Types**:
+
+```typescript
+// Map store: artifacts by message ID
+const artifacts = map<Record<string, ArtifactState>>({});
+
+interface ArtifactState {
+  id: string;              // Artifact ID from Claude
+  title: string;           // Human-readable title
+  closed: boolean;         // Whether </boltArtifact> received
+  runner: ActionRunner;    // Dedicated action executor
+}
+
+// Atom stores: single values
+const showWorkbench = atom<boolean>(false);
+const currentView = atom<'code' | 'preview'>('code');
+const unsavedFiles = atom<Set<string>>(new Set());
+
+// File state
+const files = atom<FileMap>(new Map());
+const selectedFile = atom<string | undefined>(undefined);
+```
+
+**Key Methods**:
+
+```typescript
+// Add new artifact (creates ActionRunner)
+function addArtifact(data: { messageId: string; artifactId: string; title: string }) {
+  const runner = new ActionRunner(webcontainerPromise, runtimeLogger);
+
+  artifacts.setKey(data.messageId, {
+    id: data.artifactId,
+    title: data.title,
+    closed: false,
+    runner
+  });
+
+  showWorkbench.set(true); // Open right panel
+}
+
+// Add action to artifact's runner
+function addAction(data: ActionCallbackData) {
+  const artifact = artifacts.get()[data.messageId];
+  if (artifact) {
+    artifact.runner.addAction(data);
+  }
+}
+
+// Execute action
+function runAction(data: ActionCallbackData) {
+  const artifact = artifacts.get()[data.messageId];
+  if (artifact) {
+    artifact.runner.runAction(data);
+  }
+}
+
+// Track file changes
+function setCurrentDocumentContent(filePath: string, content: string) {
+  const originalContent = files.get().get(filePath)?.content;
+
+  if (originalContent !== undefined && originalContent !== content) {
+    unsavedFiles.set(new Set([...unsavedFiles.get(), filePath]));
+  }
+}
+
+// Save file
+async function saveFile(filePath: string) {
+  const webcontainer = await webcontainerPromise;
+  const content = currentDocument.get()?.value;
+
+  if (content) {
+    await webcontainer.fs.writeFile(filePath, content);
+
+    const newUnsaved = new Set(unsavedFiles.get());
+    newUnsaved.delete(filePath);
+    unsavedFiles.set(newUnsaved);
+  }
+}
+```
+
+**Reactive Updates**:
+
+```typescript
+// Components subscribe to store updates
+import { useStore } from '@nanostores/react';
+
+function MyComponent() {
+  const currentArtifacts = useStore(artifacts);
+  const isWorkbenchVisible = useStore(showWorkbench);
+
+  return (
+    <div>
+      {Object.values(currentArtifacts).map(artifact => (
+        <div key={artifact.id}>{artifact.title}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+### 4. System Prompt
+
+**Location**: `app/lib/.server/llm/prompts.ts` (279 lines)
+
+**Purpose**: Instruct Claude on how to format responses with `<boltArtifact>` and `<boltAction>` tags.
+
+**Key Instructions to Claude**:
+
+```markdown
+# System Prompt Excerpts
+
+## Response Format
+
+You are Bolt, an AI assistant and expert web developer. When writing code, always use this format:
+
+<boltArtifact id="unique-id" title="Project Title">
+  <boltAction type="file" filePath="path/to/file.ts">
+    // File contents here
+  </boltAction>
+
+  <boltAction type="shell">
+    npm install package-name
+  </boltAction>
+</boltArtifact>
+
+## Rules
+
+1. ALWAYS wrap complete solutions in <boltArtifact> tags
+2. Each file must be in a separate <boltAction type="file"> tag
+3. Each shell command in a separate <boltAction type="shell"> tag
+4. Create files BEFORE running commands that depend on them
+5. Use two-space indentation
+6. For package.json, always include necessary scripts
+7. Think holistically - include all dependencies (HTML, CSS, JS)
+
+## WebContainer Constraints
+
+The code runs in a browser-based Node.js environment with limitations:
+
+- ❌ No native binaries (Python C extensions, node-gyp)
+- ❌ No pip (use Pyodide for Python)
+- ❌ No system commands (apt-get, brew, etc.)
+- ✅ npm/pnpm work perfectly
+- ✅ All pure JavaScript packages work
+- ✅ Frontend frameworks (React, Vue, Svelte, etc.)
+- ✅ Dev servers (Vite, webpack-dev-server, etc.)
+
+## Example Response
+
+User: "Create a React todo app"
+
+Claude Response:
+I'll create a React todo application with Vite.
+
+<boltArtifact id="react-todo" title="React Todo App">
+  <boltAction type="file" filePath="package.json">
+    {
+      "name": "todo-app",
+      "private": true,
+      "version": "0.0.0",
+      "type": "module",
+      "scripts": {
+        "dev": "vite",
+        "build": "vite build"
+      },
+      "dependencies": {
+        "react": "^18.2.0",
+        "react-dom": "^18.2.0"
+      },
+      "devDependencies": {
+        "@vitejs/plugin-react": "^4.0.0",
+        "vite": "^4.3.0"
+      }
+    }
+  </boltAction>
+
+  <boltAction type="shell">
+    npm install
+  </boltAction>
+
+  <boltAction type="file" filePath="index.html">
+    <!DOCTYPE html>
+    <html lang="en">
+      <head>
+        <meta charset="UTF-8" />
+        <title>Todo App</title>
+      </head>
+      <body>
+        <div id="root"></div>
+        <script type="module" src="/src/main.jsx"></script>
+      </body>
+    </html>
+  </boltAction>
+
+  <boltAction type="file" filePath="src/main.jsx">
+    import React from 'react'
+    import ReactDOM from 'react-dom/client'
+    import App from './App'
+
+    ReactDOM.createRoot(document.getElementById('root')).render(
+      <React.StrictMode>
+        <App />
+      </React.StrictMode>,
+    )
+  </boltAction>
+
+  <boltAction type="file" filePath="src/App.jsx">
+    import { useState } from 'react'
+
+    export default function App() {
+      const [todos, setTodos] = useState([])
+      const [input, setInput] = useState('')
+
+      const addTodo = () => {
+        if (input.trim()) {
+          setTodos([...todos, { id: Date.now(), text: input, done: false }])
+          setInput('')
+        }
+      }
+
+      return (
+        <div style={{ padding: '20px' }}>
+          <h1>Todo List</h1>
+          <input
+            value={input}
+            onChange={(e) => setInput(e.target.value)}
+            onKeyPress={(e) => e.key === 'Enter' && addTodo()}
+          />
+          <button onClick={addTodo}>Add</button>
+          <ul>
+            {todos.map(todo => (
+              <li key={todo.id}>{todo.text}</li>
+            ))}
+          </ul>
+        </div>
+      )
+    }
+  </boltAction>
+
+  <boltAction type="shell">
+    npm run dev
+  </boltAction>
+</boltArtifact>
+```
+
+**What the Prompt Achieves**:
+1. Claude knows to wrap everything in `<boltArtifact>` tags
+2. Each file is in its own `<boltAction type="file">` tag
+3. Shell commands are in `<boltAction type="shell">` tags
+4. Files are created BEFORE `npm install` and `npm run dev`
+5. The system automatically parses and executes these actions
+
+---
+
+## Execution Flow
+
+### Detailed Step-by-Step Flow
+
+#### Phase 1: User Input → API Request
+
+```typescript
+// 1. User types message in chat
+// 2. Chat.client.tsx handles submission
+
+import { useChat } from 'ai/react';
+
+function Chat() {
+  const { messages, input, handleSubmit, handleInputChange } = useChat({
+    api: '/api/chat',
+    onResponse: (response) => {
+      // Response streaming starts
+    }
+  });
+
+  return (
+    <form onSubmit={handleSubmit}>
+      <input value={input} onChange={handleInputChange} />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+#### Phase 2: API Route → Claude API
+
+```typescript
+// app/routes/api.chat.ts
+
+export async function POST({ request }: ActionFunctionArgs) {
+  const { messages } = await request.json();
+
+  // Get unsaved files to send as context
+  const fileModifications = workbenchStore.getFileModifications();
+
+  // Call stream-text with conversation history
+  return streamText(messages, env, fileModifications);
+}
+```
+
+#### Phase 3: Stream Processing
+
+```typescript
+// app/lib/.server/llm/stream-text.ts
+
+export async function streamText(
+  messages: Message[],
+  env: Env,
+  fileModifications?: FileMap
+) {
+  // 1. Build system prompt
+  const systemPrompt = getSystemPrompt();
+
+  // 2. Add file modifications to context
+  const enhancedMessages = [...messages];
+  if (fileModifications && fileModifications.size > 0) {
+    enhancedMessages.push({
+      role: 'user',
+      content: `Modified files:\n${Array.from(fileModifications.entries())
+        .map(([path, content]) => `File: ${path}\n${content}`)
+        .join('\n\n')}`
+    });
+  }
+
+  // 3. Call Claude API
+  const anthropic = createAnthropic({ apiKey: env.ANTHROPIC_API_KEY });
+
+  const result = streamText({
+    model: anthropic('claude-3-5-sonnet-20240620'),
+    system: systemPrompt,
+    messages: enhancedMessages,
+    maxTokens: 8192
+  });
+
+  // 4. Return streaming response
+  return result.toDataStreamResponse();
+}
+```
+
+#### Phase 4: Parser Integration
+
+```typescript
+// app/lib/hooks/useMessageParser.ts
+
+export function useMessageParser() {
+  const parser = useRef<StreamingMessageParser>();
+
+  useEffect(() => {
+    parser.current = new StreamingMessageParser({
+      callbacks: {
+        onArtifactOpen: (data) => {
+          // Add artifact to store
+          workbenchStore.addArtifact({
+            messageId: currentMessageId,
+            artifactId: data.id,
+            title: data.title
+          });
+        },
+
+        onArtifactClose: () => {
+          // Mark artifact as closed
+          workbenchStore.closeArtifact(currentMessageId);
+        },
+
+        onActionOpen: (data) => {
+          // For file actions, add immediately
+          if (data.type === 'file') {
+            workbenchStore.addAction({
+              messageId: currentMessageId,
+              actionId: generateId(),
+              action: data as BoltAction
+            });
+          }
+        },
+
+        onActionClose: (data) => {
+          // For shell actions, add when complete
+          // For file actions, run the action
+          const actionId = generateId();
+
+          if (data.type === 'shell') {
+            workbenchStore.addAction({
+              messageId: currentMessageId,
+              actionId,
+              action: data
+            });
+          }
+
+          workbenchStore.runAction({
+            messageId: currentMessageId,
+            actionId,
+            action: data
+          });
+        }
+      }
+    });
+  }, []);
+
+  const parseChunk = useCallback((chunk: string) => {
+    parser.current?.parse(chunk);
+  }, []);
+
+  return { parseChunk };
+}
+```
+
+#### Phase 5: Action Execution
+
+```typescript
+// Sequential execution in ActionRunner
+
+runAction(data: ActionCallbackData) {
+  const { messageId, actionId, action } = data;
+
+  // Queue execution (waits for previous to complete)
+  this.#currentExecutionPromise = this.#currentExecutionPromise
+    .then(() => this.#executeAction(actionId))
+    .catch((error) => {
+      this.runtimeLogger().error('Action failed:', error);
+    });
+}
+
+async #executeAction(actionId: string): Promise<void> {
+  const action = this.actions.get()[actionId];
+
+  if (!action || action.executed) {
+    return;
+  }
+
+  // Mark as running
+  this.#updateAction(actionId, { status: 'running' });
+
+  try {
+    // Execute based on type
+    if (action.action.type === 'file') {
+      await this.#runFileAction(action);
+    } else {
+      await this.#runShellAction(action);
+    }
+
+    // Mark as complete
+    this.#updateAction(actionId, {
+      status: 'complete',
+      executed: true
+    });
+  } catch (error) {
+    this.#updateAction(actionId, {
+      status: 'failed',
+      executed: true
+    });
+  }
+}
+```
+
+---
+
+## State Management
+
+### Nanostores Architecture
+
+Bolt.new uses **Nanostores**, a tiny (~300 bytes) state management library with atomic stores.
+
+#### Store Types
+
+```typescript
+// Atom: Single value
+import { atom } from 'nanostores';
+
+const counter = atom(0);
+counter.set(1);
+console.log(counter.get()); // 1
+
+// Map: Object with keys
+import { map } from 'nanostores';
+
+const user = map({ name: 'Alice', age: 30 });
+user.setKey('age', 31);
+console.log(user.get().age); // 31
+
+// Computed: Derived value
+import { computed } from 'nanostores';
+
+const doubled = computed(counter, value => value * 2);
+console.log(doubled.get()); // 2
+```
+
+#### Workbench Store Structure
+
+```typescript
+// app/lib/stores/workbench.ts
+
+// Artifacts (map of message ID to artifact state)
+export const artifacts = map<Record<string, ArtifactState>>({});
+
+// UI visibility
+export const showWorkbench = atom<boolean>(false);
+export const currentView = atom<'code' | 'preview'>('code');
+
+// File management
+export const files = atom<FileMap>(new Map());
+export const selectedFile = atom<string | undefined>(undefined);
+export const unsavedFiles = atom<Set<string>>(new Set());
+
+// Terminal
+export const showTerminal = atom(false);
+```
+
+#### React Integration
+
+```tsx
+import { useStore } from '@nanostores/react';
+import { artifacts, showWorkbench } from '~/lib/stores/workbench';
+
+function ArtifactList() {
+  // Automatically re-renders when store changes
+  const currentArtifacts = useStore(artifacts);
+  const isVisible = useStore(showWorkbench);
+
+  if (!isVisible) {
+    return null;
+  }
+
+  return (
+    <div>
+      {Object.values(currentArtifacts).map(artifact => (
+        <ArtifactCard key={artifact.id} artifact={artifact} />
+      ))}
+    </div>
+  );
+}
+```
+
+---
+
+## UI Components
+
+### 1. Artifact Component
+
+**Location**: `app/components/chat/Artifact.tsx`
+
+**Purpose**: Display artifact metadata and action list within chat messages.
+
+```tsx
+interface ArtifactProps {
+  messageId: string;
+}
+
+export function Artifact({ messageId }: ArtifactProps) {
+  const artifact = useStore(artifacts)[messageId];
+  const actions = useStore(artifact?.runner.actions);
+
+  const [isExpanded, setIsExpanded] = useState(true);
+
+  return (
+    <div className="artifact">
+      <div className="artifact-header">
+        <h3>{artifact.title}</h3>
+        <button onClick={() => setIsExpanded(!isExpanded)}>
+          {isExpanded ? '▼' : '▶'}
+        </button>
+      </div>
+
+      {isExpanded && (
+        <div className="actions-list">
+          {Object.values(actions).map(action => (
+            <ActionItem key={action.id} action={action} />
+          ))}
+        </div>
+      )}
+
+      <button onClick={() => showWorkbench.set(true)}>
+        Open Workbench
+      </button>
+    </div>
+  );
+}
+```
+
+**Action Status Indicators**:
+
+```tsx
+function ActionItem({ action }: { action: ActionState }) {
+  const statusIcon = {
+    pending: '○',
+    running: '⟳',
+    complete: '✓',
+    failed: '✗',
+    aborted: '✗'
+  }[action.status];
+
+  return (
+    <div className={`action-item action-${action.status}`}>
+      <span className="status-icon">{statusIcon}</span>
+
+      {action.action.type === 'file' ? (
+        <span>Create {action.action.filePath}</span>
+      ) : (
+        <>
+          <span>Run command</span>
+          <code>{action.action.content}</code>
+        </>
+      )}
+
+      {action.status === 'running' && (
+        <button onClick={action.abort}>Cancel</button>
+      )}
+    </div>
+  );
+}
+```
+
+### 2. Workbench Panel
+
+**Location**: `app/components/workbench/Workbench.client.tsx`
+
+**Purpose**: Right-side panel with code editor and preview.
+
+```tsx
+export function Workbench() {
+  const isVisible = useStore(showWorkbench);
+  const view = useStore(currentView);
+
+  if (!isVisible) {
+    return null;
+  }
+
+  return (
+    <div className="workbench-panel">
+      {/* Header with view toggle */}
+      <WorkbenchHeader />
+
+      {/* View switcher */}
+      <div className="view-controls">
+        <button
+          className={view === 'code' ? 'active' : ''}
+          onClick={() => currentView.set('code')}
+        >
+          Code
+        </button>
+        <button
+          className={view === 'preview' ? 'active' : ''}
+          onClick={() => currentView.set('preview')}
+        >
+          Preview
+        </button>
+      </div>
+
+      {/* Main content area */}
+      <div className="workbench-content">
+        {view === 'code' ? (
+          <>
+            <FileTree />
+            <CodeEditor />
+          </>
+        ) : (
+          <Preview />
+        )}
+      </div>
+
+      {/* Terminal (toggleable) */}
+      <Terminal />
+    </div>
+  );
+}
+```
+
+**File Tree Component**:
+
+```tsx
+function FileTree() {
+  const fileList = useStore(files);
+  const selected = useStore(selectedFile);
+
+  return (
+    <div className="file-tree">
+      {Array.from(fileList.entries()).map(([path, file]) => (
+        <button
+          key={path}
+          className={path === selected ? 'selected' : ''}
+          onClick={() => selectedFile.set(path)}
+        >
+          {path}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+**Code Editor Component** (Monaco Editor):
+
+```tsx
+import Editor from '@monaco-editor/react';
+
+function CodeEditor() {
+  const file = useStore(selectedFile);
+  const fileContent = useStore(files).get(file);
+
+  return (
+    <Editor
+      path={file}
+      language={getLanguage(file)}
+      value={fileContent?.content || ''}
+      onChange={(value) => {
+        if (file && value !== undefined) {
+          workbenchStore.setCurrentDocumentContent(file, value);
+        }
+      }}
+      options={{
+        minimap: { enabled: false },
+        fontSize: 14,
+        lineNumbers: 'on',
+        theme: 'vs-dark'
+      }}
+    />
+  );
+}
+```
+
+**Preview Component** (iframe):
+
+```tsx
+function Preview() {
+  const [url, setUrl] = useState<string>('');
+
+  useEffect(() => {
+    webcontainerPromise.then(async (container) => {
+      // Listen for server ready event
+      container.on('server-ready', (port, url) => {
+        setUrl(url);
+      });
+    });
+  }, []);
+
+  return (
+    <iframe
+      src={url}
+      title="Preview"
+      style={{ width: '100%', height: '100%', border: 'none' }}
+    />
+  );
+}
+```
+
+---
+
+## Code Examples
+
+### Example 1: Complete Request Flow
+
+```typescript
+// 1. User sends message
+const userMessage = "Create a React app with routing";
+
+// 2. API receives request
+POST /api/chat
+Body: { messages: [{ role: 'user', content: userMessage }] }
+
+// 3. Claude responds with streaming XML
+Response Stream:
+"I'll create a React app with React Router.\n\n"
+"<boltArtifact id=\"react-router-app\" title=\"React Router App\">\n"
+"  <boltAction type=\"file\" filePath=\"package.json\">\n"
+"    { \"name\": \"router-app\", ... }\n"
+"  </boltAction>\n"
+...
+
+// 4. Parser extracts actions as they stream in
+parser.parse(chunk1); // Detects <boltArtifact> opening
+parser.parse(chunk2); // Detects <boltAction> opening
+parser.parse(chunk3); // Accumulates file content
+parser.parse(chunk4); // Detects </boltAction>, fires onActionClose
+parser.parse(chunk5); // Next action...
+
+// 5. Actions execute sequentially
+// Action 1: Write package.json (status: pending → running → complete)
+// Action 2: Run npm install (status: pending → running → complete)
+// Action 3: Write src/App.jsx (status: pending → running → complete)
+// ...
+
+// 6. UI updates in real-time
+// - Artifact component shows action list with live status
+// - Workbench panel opens with file tree
+// - Monaco editor shows file contents
+// - Preview iframe loads dev server
+```
+
+### Example 2: Custom Parser Implementation
+
+```typescript
+// Create a parser with custom logging
+
+const parser = new StreamingMessageParser({
+  callbacks: {
+    onArtifactOpen: (data) => {
+      console.log(`[ARTIFACT OPEN] ${data.id}: ${data.title}`);
+
+      // Add to store
+      workbenchStore.addArtifact({
+        messageId: 'msg-123',
+        artifactId: data.id,
+        title: data.title
+      });
+    },
+
+    onArtifactClose: () => {
+      console.log('[ARTIFACT CLOSE]');
+    },
+
+    onActionOpen: (data) => {
+      console.log(`[ACTION OPEN] ${data.type}`);
+
+      if (data.type === 'file') {
+        console.log(`  File: ${data.filePath}`);
+      }
+    },
+
+    onActionClose: (data) => {
+      console.log(`[ACTION CLOSE] ${data.type}`);
+
+      const actionId = `action-${Date.now()}`;
+
+      // Add action
+      workbenchStore.addAction({
+        messageId: 'msg-123',
+        actionId,
+        action: data
+      });
+
+      // Run action
+      workbenchStore.runAction({
+        messageId: 'msg-123',
+        actionId,
+        action: data
+      });
+    }
+  }
+});
+
+// Simulate streaming response
+const response = `
+I'll help you with that.
+
+<boltArtifact id="test" title="Test Project">
+  <boltAction type="file" filePath="index.js">
+    console.log('Hello');
+  </boltAction>
+  <boltAction type="shell">
+    node index.js
+  </boltAction>
+</boltArtifact>
+`;
+
+// Parse in chunks (simulating network streaming)
+const chunkSize = 20;
+for (let i = 0; i < response.length; i += chunkSize) {
+  const chunk = response.slice(i, i + chunkSize);
+  parser.parse(chunk);
+}
+
+// Output:
+// [ARTIFACT OPEN] test: Test Project
+// [ACTION OPEN] file
+//   File: index.js
+// [ACTION CLOSE] file
+// [ACTION OPEN] shell
+// [ACTION CLOSE] shell
+// [ARTIFACT CLOSE]
+```
+
+### Example 3: Manual Action Execution
+
+```typescript
+// Create ActionRunner manually
+const webcontainer = await WebContainer.boot();
+const logger = () => console;
+
+const runner = new ActionRunner(
+  Promise.resolve(webcontainer),
+  logger
+);
+
+// Add and run file action
+const fileActionId = 'file-1';
+runner.addAction({
+  messageId: 'msg-1',
+  actionId: fileActionId,
+  action: {
+    type: 'file',
+    filePath: 'test.txt',
+    content: 'Hello World'
+  }
+});
+
+runner.runAction({
+  messageId: 'msg-1',
+  actionId: fileActionId,
+  action: {
+    type: 'file',
+    filePath: 'test.txt',
+    content: 'Hello World'
+  }
+});
+
+// Subscribe to action state changes
+runner.actions.subscribe((actions) => {
+  const action = actions[fileActionId];
+  console.log(`Action status: ${action.status}`);
+});
+
+// Output:
+// Action status: pending
+// Action status: running
+// Action status: complete
+
+// Verify file was written
+const content = await webcontainer.fs.readFile('test.txt', 'utf-8');
+console.log(content); // "Hello World"
+```
+
+---
+
+## Key Files Reference
+
+### Core Runtime Files
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `app/lib/runtime/action-runner.ts` | 186 | Execute file/shell actions in WebContainer |
+| `app/lib/runtime/message-parser.ts` | 286 | Parse streaming XML from Claude |
+| `app/lib/hooks/useMessageParser.ts` | 67 | React hook connecting parser to stores |
+
+### State Management
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `app/lib/stores/workbench.ts` | 277 | Artifacts, files, UI state |
+| `app/lib/stores/chat.ts` | 45 | Chat session state |
+| `app/lib/stores/settings.ts` | 32 | User preferences |
+| `app/lib/stores/theme.ts` | 28 | Theme state |
+
+### LLM Integration
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `app/lib/.server/llm/stream-text.ts` | 178 | Claude API streaming |
+| `app/lib/.server/llm/prompts.ts` | 279 | System prompt definition |
+| `app/lib/.server/llm/model.ts` | 24 | Model configuration |
+
+### UI Components - Chat
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `app/components/chat/Chat.client.tsx` | 235 | Main chat interface |
+| `app/components/chat/Messages.client.tsx` | 98 | Message list renderer |
+| `app/components/chat/AssistantMessage.tsx` | 56 | Assistant message display |
+| `app/components/chat/UserMessage.tsx` | 34 | User message display |
+| `app/components/chat/Artifact.tsx` | 214 | Artifact & action display |
+| `app/components/chat/Markdown.tsx` | 75 | Markdown renderer |
+
+### UI Components - Workbench
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `app/components/workbench/Workbench.client.tsx` | 188 | Main workbench panel |
+| `app/components/workbench/FileTree.tsx` | 142 | File tree navigator |
+| `app/components/workbench/CodeEditor.tsx` | 89 | Monaco editor wrapper |
+| `app/components/workbench/Preview.tsx` | 67 | iframe preview panel |
+| `app/components/workbench/Terminal.tsx` | 124 | Terminal emulator |
+
+### Type Definitions
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `app/types/actions.ts` | 19 | Action type definitions |
+| `app/types/artifact.ts` | 12 | Artifact type definitions |
+| `app/types/message.ts` | 24 | Message type definitions |
+
+### API Routes
+
+| File | Lines | Purpose |
+|------|-------|---------|
+| `app/routes/api.chat.ts` | 60 | Chat API endpoint |
+| `app/routes/_index.tsx` | 45 | Home page route |
+
+---
+
+## Advanced Topics
+
+### 1. Handling Streaming Chunks
+
+The parser must handle incomplete XML tags across chunks:
+
+```typescript
+// Chunk 1: "<boltAction type=\"fi"
+// Chunk 2: "le\" filePath=\"inde"
+// Chunk 3: "x.js\">\nconsole.log"
+// Chunk 4: "('test')\n</boltAction>"
+
+class StreamingMessageParser {
+  private _text: string = '';
+
+  parse(chunk: string): void {
+    // Accumulate text
+    this._text += chunk;
+
+    // Try to find complete tags
+    this._processText();
+  }
+
+  private _processText(): void {
+    // Look for opening tags
+    const artifactMatch = this._text.match(
+      /<boltArtifact\s+id="([^"]+)"\s+title="([^"]+)">/
+    );
+
+    if (artifactMatch) {
+      const [fullMatch, id, title] = artifactMatch;
+
+      // Fire callback
+      this._callbacks.onArtifactOpen?.({ id, title });
+
+      // Remove processed text
+      this._text = this._text.slice(fullMatch.length);
+    }
+
+    // Look for closing tags
+    if (this._text.includes('</boltAction>')) {
+      const closeIndex = this._text.indexOf('</boltAction>');
+      const content = this._text.slice(0, closeIndex);
+
+      // Fire callback with complete action
+      this._callbacks.onActionClose?.(this._currentAction);
+
+      // Remove processed text
+      this._text = this._text.slice(closeIndex + '</boltAction>'.length);
+    }
+  }
+}
+```
+
+### 2. Abort Controller Pattern
+
+Actions can be cancelled mid-execution:
+
+```typescript
+class ActionRunner {
+  addAction(data: ActionCallbackData): void {
+    const abortController = new AbortController();
+
+    this.actions.setKey(data.actionId, {
+      action: data.action,
+      status: 'pending',
+      executed: false,
+      abortSignal: abortController.signal,
+      abort: () => {
+        abortController.abort();
+        this.#updateAction(data.actionId, {
+          status: 'aborted',
+          executed: true
+        });
+      }
+    });
+  }
+
+  async #runShellAction(action: ActionState): Promise<void> {
+    const webcontainer = await this.#webcontainer;
+
+    // Pass abort signal to spawn
+    const process = await webcontainer.spawn('jsh', ['-c', action.action.content], {
+      signal: action.abortSignal  // <-- Abort support
+    });
+
+    // If aborted, process terminates automatically
+    const exitCode = await process.exit;
+
+    if (exitCode !== 0) {
+      throw new Error(`Command failed with exit code ${exitCode}`);
+    }
+  }
+}
+
+// In UI:
+function ActionItem({ action }: { action: ActionState }) {
+  return (
+    <div>
+      {action.status === 'running' && (
+        <button onClick={action.abort}>Cancel</button>
+      )}
+    </div>
+  );
+}
+```
+
+### 3. File System Watching
+
+WebContainer supports file watching for live reload:
+
+```typescript
+async function watchFileSystem() {
+  const webcontainer = await webcontainerPromise;
+
+  // Watch for file changes
+  webcontainer.fs.watch('/', { recursive: true }, (event, filename) => {
+    console.log(`File ${event}: ${filename}`);
+
+    if (event === 'change') {
+      // Reload preview
+      previewUrl.set(previewUrl.get() + '?reload=' + Date.now());
+    }
+  });
+}
+```
+
+### 4. Token Limit Handling
+
+When Claude hits token limits, the system requests continuation:
+
+```typescript
+// app/lib/.server/llm/stream-text.ts
+
+const MAX_TOKENS = 8192;
+const MAX_RESPONSE_SEGMENTS = 2;
+
+async function streamText(messages: Message[]) {
+  let segmentCount = 0;
+  let fullResponse = '';
+
+  while (segmentCount < MAX_RESPONSE_SEGMENTS) {
+    const result = await anthropic.streamText({
+      model: 'claude-3-5-sonnet-20240620',
+      messages,
+      maxTokens: MAX_TOKENS
+    });
+
+    for await (const chunk of result.textStream) {
+      fullResponse += chunk;
+      yield chunk;
+    }
+
+    // Check if response was truncated
+    if (result.finishReason === 'length') {
+      // Add continuation prompt
+      messages.push({
+        role: 'assistant',
+        content: fullResponse
+      });
+      messages.push({
+        role: 'user',
+        content: 'Continue from where you left off.'
+      });
+
+      segmentCount++;
+      fullResponse = '';
+    } else {
+      break;  // Response complete
+    }
+  }
+}
+```
+
+### 5. Error Recovery
+
+The system handles various error scenarios:
+
+```typescript
+// Network errors
+try {
+  const result = await fetch('/api/chat', {
+    method: 'POST',
+    body: JSON.stringify({ messages })
+  });
+
+  if (!result.ok) {
+    throw new Error(`HTTP ${result.status}: ${result.statusText}`);
+  }
+} catch (error) {
+  if (error instanceof TypeError && error.message.includes('fetch')) {
+    // Network error - show retry UI
+    showError('Network error. Please check your connection.');
+  } else {
+    // Other error
+    showError(error.message);
+  }
+}
+
+// Action execution errors
+async #runFileAction(action: ActionState): Promise<void> {
+  try {
+    const webcontainer = await this.#webcontainer;
+    await webcontainer.fs.writeFile(
+      action.action.filePath,
+      action.action.content
+    );
+
+    this.#updateAction(action.id, { status: 'complete' });
+  } catch (error) {
+    // Log error details
+    this.runtimeLogger().error('File write failed:', {
+      filePath: action.action.filePath,
+      error: error.message
+    });
+
+    // Update UI
+    this.#updateAction(action.id, {
+      status: 'failed',
+      error: error.message
+    });
+  }
+}
+
+// WebContainer boot errors
+async function bootWebContainer() {
+  try {
+    const container = await WebContainer.boot({
+      workdirName: 'project'
+    });
+
+    return container;
+  } catch (error) {
+    // WebContainer failed to boot
+    if (error.message.includes('SharedArrayBuffer')) {
+      showError(
+        'WebContainer requires Cross-Origin Isolation. ' +
+        'Please ensure your server sends the correct headers.'
+      );
+    } else {
+      showError('Failed to initialize WebContainer: ' + error.message);
+    }
+
+    throw error;
+  }
+}
+```
+
+### 6. Context Management
+
+Bolt maintains conversation context across messages:
+
+```typescript
+// app/lib/.server/llm/stream-text.ts
+
+export async function streamText(
+  messages: Message[],
+  env: Env,
+  fileModifications?: FileMap
+) {
+  // Build context from file modifications
+  let contextMessage = '';
+
+  if (fileModifications && fileModifications.size > 0) {
+    contextMessage += '\n\nCurrent file contents:\n\n';
+
+    for (const [filePath, fileData] of fileModifications.entries()) {
+      contextMessage += `### ${filePath}\n\`\`\`\n${fileData.content}\n\`\`\`\n\n`;
+    }
+  }
+
+  // Add context to latest user message
+  const enhancedMessages = [...messages];
+  const lastMessage = enhancedMessages[enhancedMessages.length - 1];
+
+  if (lastMessage.role === 'user') {
+    lastMessage.content += contextMessage;
+  }
+
+  // Call Claude with full context
+  return anthropic.streamText({
+    model: 'claude-3-5-sonnet-20240620',
+    system: getSystemPrompt(),
+    messages: enhancedMessages
+  });
+}
+```
+
+---
+
+## File Modification & Change Tracking
+
+### The Critical Question: How Does Editing Work?
+
+While new file creation via `<boltAction>` is straightforward, **editing existing files** involves a sophisticated tracking system that enables Claude to understand what changed without re-reading entire projects.
+
+### Key Insight
+
+**File creation and file editing use the same WebContainer API** (`writeFile`), but the **tracking layer** distinguishes between them to intelligently send only modifications back to Claude.
+
+---
+
+### 1. Two Types of File Operations
+
+| Operation | Source | Tracking | Sent to Claude |
+|-----------|--------|----------|----------------|
+| **New File Creation** | Claude's `<boltAction>` | Not tracked | No |
+| **File Editing** | User typing in editor | Tracked in `#modifiedFiles` | Yes (as diffs) |
+
+---
+
+### 2. File Modification Tracking System
+
+**Location**: `app/lib/stores/files.ts`
+
+**Data Structures**:
+
+```typescript
+class FilesStore {
+  // Stores ORIGINAL content when file is first edited and saved
+  #modifiedFiles: Map<string, string> = new Map();
+
+  // Current file content (synced with WebContainer)
+  files: MapStore<FileMap> = map({});
+
+  // Files with unsaved changes in editor
+  unsavedFiles: WritableAtom<Set<string>> = atom(new Set());
+}
+```
+
+**The Flow**:
+
+```
+1. User opens file in editor
+   → content: "console.log('Hello')"
+
+2. User types changes
+   → onChange event fires (debounced 150ms)
+   → setCurrentDocumentContent()
+   → added to unsavedFiles Set
+
+3. User saves (Ctrl+S)
+   → saveFile() called
+   → ORIGINAL content stored: #modifiedFiles.set("app.js", "console.log('Hello')")
+   → NEW content written: webcontainer.fs.writeFile("app.js", "console.log('Hi')")
+   → removed from unsavedFiles Set
+
+4. User sends message to Claude
+   → getFileModifications() generates diff
+   → diff sent as context: "@@ -1 +1 @@ -console.log('Hello') +console.log('Hi')"
+   → resetAllFileModifications() clears tracking
+```
+
+---
+
+### 3. Unsaved Changes Management
+
+**Location**: `app/lib/stores/workbench.ts`
+
+```typescript
+setCurrentDocumentContent(newContent: string) {
+  const filePath = this.currentDocument.get()?.filePath;
+  const originalContent = this.#filesStore.getFile(filePath)?.content;
+
+  // Detect if content changed from what's in WebContainer
+  const unsavedChanges = originalContent !== undefined &&
+                         originalContent !== newContent;
+
+  // Update editor state
+  this.#editorStore.updateFile(filePath, newContent);
+
+  // Track unsaved status
+  const newUnsavedFiles = new Set(this.unsavedFiles.get());
+  if (unsavedChanges) {
+    newUnsavedFiles.add(filePath);
+  } else {
+    newUnsavedFiles.delete(filePath);
+  }
+  this.unsavedFiles.set(newUnsavedFiles);
+}
+```
+
+**UI Indicators**:
+
+```tsx
+// Files with unsaved changes show a dot indicator
+{Array.from(unsavedFiles).map(filePath => (
+  <div className="file-item">
+    <span>{filePath}</span>
+    <span className="unsaved-indicator">●</span>
+  </div>
+))}
+```
+
+---
+
+### 4. Sending Modifications to Claude
+
+**Critical Flow** (`app/components/chat/Chat.client.tsx`):
+
+```typescript
+const sendMessage = async (_event: React.UIEvent, messageInput?: string) => {
+  const _input = messageInput || input;
+
+  // Step 1: Save all unsaved files first
+  await workbenchStore.saveAllFiles();
+
+  // Step 2: Get modifications since last message
+  const fileModifications = workbenchStore.getFileModifications();
+
+  if (fileModifications !== undefined) {
+    // Step 3: Convert to HTML format for Claude
+    const diff = fileModificationsToHTML(fileModifications);
+
+    // Step 4: Prepend diff to user message
+    append({
+      role: 'user',
+      content: `${diff}\n\n${_input}`
+    });
+
+    // Step 5: Clear tracking (don't resend same changes)
+    workbenchStore.resetAllFileModifications();
+  } else {
+    // No modifications - send message as-is
+    append({ role: 'user', content: _input });
+  }
+};
+```
+
+**Example Context Sent to Claude**:
+
+```html
+<bolt_file_modifications>
+  <diff path="/home/project/src/App.tsx">
+    @@ -12,7 +12,10 @@
+     function App() {
+       const [count, setCount] = useState(0);
+
+    -  return <div>Count: {count}</div>;
+    +  return (
+    +    <div>
+    +      <h1>Counter</h1>
+    +      <p>Count: {count}</p>
+    +    </div>
+    +  );
+     }
+  </diff>
+
+  <file path="/home/project/package.json">
+    {
+      "name": "my-app",
+      "version": "1.0.0"
+    }
+  </file>
+</bolt_file_modifications>
+
+Now add a reset button to the counter
+```
+
+---
+
+### 5. Smart Diff Calculation
+
+**Location**: `app/utils/diff.ts`
+
+```typescript
+export function computeFileModifications(
+  files: FileMap,
+  modifiedFiles: Map<string, string>
+) {
+  const modifications: FileModifications = {};
+  let hasModifiedFiles = false;
+
+  for (const [filePath, originalContent] of modifiedFiles) {
+    const file = files[filePath];
+
+    if (file?.type !== 'file') continue;
+
+    // Generate unified diff (Git-style)
+    const unifiedDiff = diffFiles(
+      filePath,
+      originalContent,
+      file.content
+    );
+
+    if (!unifiedDiff) {
+      // Files are identical - skip
+      continue;
+    }
+
+    hasModifiedFiles = true;
+
+    // Smart choice: use diff if smaller, otherwise full file
+    if (unifiedDiff.length > file.content.length) {
+      // Diff is larger than file - send full content
+      modifications[filePath] = {
+        type: 'file',
+        content: file.content
+      };
+    } else {
+      // Diff is smaller - send diff
+      modifications[filePath] = {
+        type: 'diff',
+        content: unifiedDiff
+      };
+    }
+  }
+
+  return hasModifiedFiles ? modifications : undefined;
+}
+```
+
+**Unified Diff Format** (GNU standard):
+
+```diff
+@@ -2,7 +2,10 @@
+  return a + b;
+ }
+
+-console.log('Hello, World!');
++console.log('Hello, Bolt!');
++
+ function greet() {
+-  return 'Greetings!';
++  return 'Greetings!!';
+ }
++
++console.log('The End');
+```
+
+**Benefits**:
+- Saves tokens (diffs are usually smaller than full files)
+- Claude understands Git-style diffs natively
+- Only sends what changed, not entire codebase
+
+---
+
+### 6. Monaco Editor Synchronization
+
+**Editor Change Detection** (`app/components/editor/codemirror/CodeMirrorEditor.tsx`):
+
+```typescript
+useEffect(() => {
+  const onUpdate = debounce((update: EditorUpdate) => {
+    onChangeRef.current?.(update);
+  }, 150); // Debounce typing events
+
+  const view = new EditorView({
+    parent: containerRef.current!,
+    dispatchTransactions(transactions) {
+      view.update(transactions);
+
+      // Check if document or selection changed
+      if (transactions.some(t => t.docChanged)) {
+        onUpdate({
+          selection: view.state.selection,
+          content: view.state.doc.toString()
+        });
+      }
+    }
+  });
+
+  return () => view.destroy();
+}, []);
+```
+
+**Workbench Integration**:
+
+```tsx
+// app/components/workbench/Workbench.client.tsx
+
+const onEditorChange = useCallback<OnEditorChange>((update) => {
+  workbenchStore.setCurrentDocumentContent(update.content);
+}, []);
+
+const onFileSave = useCallback(() => {
+  workbenchStore.saveCurrentDocument();
+}, []);
+
+<CodeMirrorEditor
+  onChange={onEditorChange}  // Fires on every keystroke (debounced)
+  onSave={onFileSave}        // Fires on Ctrl+S
+  doc={editorDocument}
+/>
+```
+
+---
+
+### 7. WebContainer File System Watching
+
+**Location**: `app/lib/stores/files.ts`
+
+```typescript
+async #init() {
+  const webcontainer = await this.#webcontainer;
+
+  // Watch for ALL file system changes
+  webcontainer.internal.watchPaths(
+    {
+      include: [`${WORK_DIR}/**`],
+      exclude: ['**/node_modules/**', '.git/**'],
+      includeContent: true  // Get file contents, not just paths
+    },
+    bufferWatchEvents(100, this.#processEventBuffer.bind(this))
+  );
+}
+
+#processEventBuffer(events: Array<[events: PathWatcherEvent[]]>) {
+  const watchEvents = events.flat(2);
+
+  for (const { type, path, buffer } of watchEvents) {
+    switch (type) {
+      case 'add_file':
+        this.#size++;
+        const content = this.#decodeFileContent(buffer);
+        this.files.setKey(path, { type: 'file', content });
+        break;
+
+      case 'change':
+        const newContent = this.#decodeFileContent(buffer);
+        this.files.setKey(path, { type: 'file', content: newContent });
+        break;
+
+      case 'remove_file':
+        this.#size--;
+        this.files.setKey(path, undefined);
+        break;
+    }
+  }
+}
+```
+
+**Synchronization Flow**:
+
+```
+User types in editor → onChange (debounced 150ms) →
+setCurrentDocumentContent() → EditorStore.documents updated →
+User presses Ctrl+S → saveFile() →
+webcontainer.fs.writeFile() →
+WebContainer emits 'change' event →
+watchPaths callback fires →
+#processEventBuffer() →
+files.setKey() updates store →
+UI re-renders with new content ✓
+```
+
+---
+
+### 8. File Save Implementation
+
+**Location**: `app/lib/stores/files.ts`
+
+```typescript
+async saveFile(filePath: string, content: string) {
+  const webcontainer = await this.#webcontainer;
+  const relativePath = nodePath.relative(webcontainer.workdir, filePath);
+
+  // Get current content before overwriting
+  const oldContent = this.getFile(filePath)?.content;
+
+  // Store original content for diffing (ONLY if not already tracked)
+  if (!this.#modifiedFiles.has(filePath)) {
+    this.#modifiedFiles.set(filePath, oldContent);
+  }
+
+  try {
+    // Write to WebContainer
+    await webcontainer.fs.writeFile(relativePath, content);
+
+    // Update in-memory state
+    this.files.setKey(filePath, {
+      type: 'file',
+      content,
+      isBinary: false
+    });
+
+    this.#logger.info(`File saved: ${filePath}`);
+  } catch (error) {
+    this.#logger.error(`Failed to save file: ${filePath}`, error);
+    throw error;
+  }
+}
+```
+
+**Key Behavior**:
+- Original content captured on **first save** after last Claude message
+- Subsequent saves to same file **don't update** `#modifiedFiles` entry
+- This preserves the baseline for diffing
+
+---
+
+### 9. Resetting File Modifications
+
+**After sending message to Claude**:
+
+```typescript
+// app/lib/stores/workbench.ts
+
+resetAllFileModifications() {
+  this.#filesStore.resetModifiedFiles();
+}
+
+// app/lib/stores/files.ts
+
+resetModifiedFiles() {
+  this.#modifiedFiles.clear();
+}
+```
+
+**Why Reset?**
+- Prevents sending same diffs twice
+- Establishes new baseline after each Claude response
+- User edits after Claude's response become new modifications
+
+---
+
+### 10. Complete Edit Workflow Example
+
+**Scenario**: User asks Claude to create a React app, then edits it.
+
+```typescript
+// STEP 1: Claude creates initial files
+<boltArtifact id="app" title="React App">
+  <boltAction type="file" filePath="src/App.jsx">
+    export default function App() {
+      return <div>Hello</div>;
+    }
+  </boltAction>
+</boltArtifact>
+
+// Action executes:
+webcontainer.fs.writeFile("src/App.jsx", content);
+// #modifiedFiles is EMPTY (file not tracked)
+
+// STEP 2: User opens App.jsx in editor
+// - Content loads from files store
+// - Monaco editor displays content
+
+// STEP 3: User edits file
+// - Types: return <div>Hello World</div>;
+// - onChange fires → setCurrentDocumentContent()
+// - App.jsx added to unsavedFiles Set
+// - Dot indicator appears next to filename
+
+// STEP 4: User saves (Ctrl+S)
+saveFile("src/App.jsx", newContent);
+// #modifiedFiles.set("src/App.jsx", "export default function...")
+// WebContainer writes new content
+// App.jsx removed from unsavedFiles Set
+
+// STEP 5: User sends message "Make it blue"
+await saveAllFiles();  // Ensure everything saved
+const mods = getFileModifications();
+// mods = {
+//   "src/App.jsx": {
+//     type: "diff",
+//     content: "@@ -2 +2 @@ -return <div>Hello</div>; +return <div>Hello World</div>;"
+//   }
+// }
+
+append({
+  role: 'user',
+  content: `
+    <bolt_file_modifications>
+      <diff path="src/App.jsx">
+        @@ -2 +2 @@
+        -return <div>Hello</div>;
+        +return <div>Hello World</div>;
+      </diff>
+    </bolt_file_modifications>
+
+    Make it blue
+  `
+});
+
+resetAllFileModifications();  // Clear tracking
+
+// STEP 6: Claude responds with new <boltAction>
+<boltAction type="file" filePath="src/App.jsx">
+  export default function App() {
+    return <div style={{ color: 'blue' }}>Hello World</div>;
+  }
+</boltAction>
+
+// File overwritten in WebContainer
+// Editor reloads with new content
+// #modifiedFiles is EMPTY again (reset after last message)
+```
+
+---
+
+### 11. Key Differences: Creation vs Editing
+
+| Aspect | New File Creation | File Editing |
+|--------|-------------------|--------------|
+| **Triggered By** | Claude's `<boltAction>` | User typing in editor |
+| **API Call** | `webcontainer.fs.writeFile()` | `webcontainer.fs.writeFile()` |
+| **Tracked in `#modifiedFiles`** | ❌ No | ✅ Yes (on save) |
+| **Sent Back to Claude** | ❌ No | ✅ Yes (as diff or full content) |
+| **Appears in `unsavedFiles`** | ❌ No | ✅ Yes (until saved) |
+| **Diff Calculated** | ❌ N/A | ✅ Yes (against original) |
+| **Baseline Established** | Immediately | On first save after Claude message |
+
+---
+
+### 12. Binary File Handling
+
+```typescript
+// Files like images, PDFs are detected
+const isBinary = isBinaryFile(buffer);  // Uses 'istextorbinary' npm package
+
+if (isBinary) {
+  this.files.setKey(filePath, {
+    type: 'file',
+    content: '',  // Empty string (not displayable)
+    isBinary: true
+  });
+}
+```
+
+**Result**:
+- Binary files don't open in editor
+- Not included in modifications sent to Claude
+- Still tracked in file tree
+
+---
+
+### 13. Hot Module Reload (HMR) Persistence
+
+```typescript
+// Persist state across HMR reloads during development
+#modifiedFiles: Map<string, string> =
+  import.meta.hot?.data.modifiedFiles ?? new Map();
+
+files: MapStore<FileMap> =
+  import.meta.hot?.data.files ?? map({});
+
+if (import.meta.hot) {
+  import.meta.hot.data.files = this.files;
+  import.meta.hot.data.modifiedFiles = this.#modifiedFiles;
+}
+```
+
+**Benefit**: Developer experience - file state survives code hot-reloads.
+
+---
+
+### Summary: The Modification System
+
+Bolt.new implements a **dual-tracking system**:
+
+1. **`unsavedFiles`**: Tracks editor changes not yet written to WebContainer
+2. **`#modifiedFiles`**: Tracks saved changes not yet sent to Claude
+
+This enables:
+- **Context-aware AI**: Claude knows exactly what changed without re-reading entire projects
+- **Token efficiency**: Only diffs are sent, not full files
+- **User control**: Users can edit freely; changes only sent when they message Claude
+- **Baseline management**: System resets tracking after each Claude response
+
+The system uses the **same file operation** (`writeFile`) for both creation and editing, but the **tracking layer** intelligently distinguishes between them to provide Claude with the perfect amount of context.
+
+---
+
+## Summary
+
+The Bolt.new agent architecture is a **parser-driven autonomous execution system** that creates an illusion of an AI agent building applications. The key components are:
+
+1. **StreamingMessageParser**: Extracts XML-wrapped instructions from Claude's streaming response
+2. **ActionRunner**: Executes file and shell operations sequentially in WebContainer
+3. **Workbench Store**: Manages state with reactive Nanostores
+4. **UI Components**: Display real-time progress and allow user interaction
+5. **WebContainer**: Provides browser-based Node.js runtime for code execution
+
+**The Magic**: Claude is instructed via system prompt to format all solutions as XML with `<boltArtifact>` and `<boltAction>` tags. The application parses this XML as it streams in and automatically executes the actions, creating the autonomous "agent" experience.
+
+**Key Innovation**: No separate agent framework needed - it's pure prompt engineering + streaming parser + sequential execution engine.
+
+---
+
+## Additional Resources
+
+- **WebContainer Docs**: https://webcontainers.io/
+- **Nanostores Docs**: https://github.com/nanostores/nanostores
+- **Claude API Docs**: https://docs.anthropic.com/
+- **Remix Framework**: https://remix.run/ (the app framework used)
+- **Monaco Editor**: https://microsoft.github.io/monaco-editor/
+
+---
+
+*Document created: 2025-11-05*
+*Bolt.new Version: Based on codebase analysis*
\ No newline at end of file