diff --git a/docs/apps-architecture/00-vision.md b/docs/apps-architecture/00-vision.md
new file mode 100644
index 0000000..ab4cdb5
--- /dev/null
+++ b/docs/apps-architecture/00-vision.md
@@ -0,0 +1,258 @@
+# Iris Apps: Vision Document
+
+## The Problem
+
+Today's software development is fractured:
+
+1. **IDEs are separate from runtime** - You write code in VS Code, but your app runs elsewhere. Context switching kills flow.
+
+2. **AI assistants are disconnected** - AI can help write code, but it can't truly interact with your running application. It suggests; it doesn't collaborate.
+
+3. **Extensions are second-class** - VS Code extensions can't really "do" things in your application. They're limited to IDE chrome, not application logic.
+
+4. **Mobile is an afterthought** - Most development tools barely work on tablets, let alone phones. Yet mobile is where users spend their time.
+
+5. **UI and logic are entangled** - Building an app means maintaining separate frontend and backend codebases, build systems, and deployment pipelines.
+
+## The Vision
+
+**Iris Apps** is a new paradigm where:
+
+> *The application you're building runs inside the tool you're using to build it, the UI is defined by your server code, and an AI agent can interact with everything.*
+
+### Core Principles
+
+#### 1. Server-Defined Rendering (SDR)
+
+The breakthrough insight: **UI is just data**.
+
+Instead of maintaining a separate frontend codebase, your server returns a component tree that the client renders. Change your server code, and the UI updates instantly.
+
+```typescript
+// Your entire app - server AND UI - in one file
+export default defineApp({
+  state: {
+    query: state(''),
+    results: state<Row[]>([]),
+  },
+
+  tools: [
+    defineTool({
+      name: 'run_query',
+      description: 'Execute a SQL query',
+      parameters: z.object({ sql: z.string() }),
+      execute: async ({ sql }, ctx) => {
+        const rows = await db.query(sql);
+        ctx.state.results.set(rows);
+        return { rowCount: rows.length };
+      },
+    }),
+  ],
+
+  ui: (ctx) => (
+    Stack({ padding: 16, gap: 12 }, [
+      Heading({}, 'Database Explorer'),
+      Input({
+        value: ctx.state.query,
+        onChangeText: ctx.state.query.set,
+        placeholder: 'SELECT * FROM ...',
+      }),
+      Button({ onPress: () => ctx.runTool('run_query', { sql: ctx.state.query }) },
+        'Execute'
+      ),
+      ctx.state.results.length > 0 && DataTable({ data: ctx.state.results }),
+    ])
+  ),
+});
+```
+
+No separate frontend. No build step for UI. No bundler configuration. Just describe what you want, and it renders—on web AND mobile.
+
+#### 2. Self-Hosted Development
+
+You build Iris Apps inside Iris. The app runs as a tab alongside your code. Edit your server file, see the UI update instantly.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ IRIS                                                        │
+├─────────────┬───────────────────────────────────────────────┤
+│ Files       │  [server.ts] [▶ My App]                       │
+│             │  ┌─────────────────────────────────────────┐ │
+│ ├─ app.json │  │                                         │ │
+│ └─ server.ts│  │     Your app running live here          │ │
+│             │  │                                         │ │
+│             │  │     Edit code on left                   │ │
+│             │  │     See changes instantly on right      │ │
+│             │  │                                         │ │
+│             │  └─────────────────────────────────────────┘ │
+└─────────────┴───────────────────────────────────────────────┘
+```
+
+Notice: there's no `ui/` folder. No Vite. No React build. The UI IS the server code.
+
+#### 3. AI-Native Architecture
+
+Apps expose **tools** that AI agents can use. The agent doesn't just help you write code; it can *use* your app to accomplish tasks.
+
+```typescript
+// The AI agent can now:
+// 1. Understand what your app does (from tool descriptions)
+// 2. Actually use it ("Run a query to find all users")
+// 3. See and interpret the results
+// 4. Help users interact with YOUR app
+```
+
+#### 4. True Mobile-First
+
+Because UI is rendered from component definitions, the same app works natively on mobile:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                                                              │
+│   WEB                          MOBILE (React Native)        │
+│                                                              │
+│   Stack({ padding: 16 })   →   <View style={padding: 16}>  │
+│   Text({ size: 'lg' })     →   <Text style={fontSize: 18}> │
+│   Button({ onPress })      →   <Pressable onPress>         │
+│   Input({ value })         →   <TextInput value>           │
+│                                                              │
+│   Same code. Native components. No WebView.                 │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+#### 5. Graceful Degradation
+
+During development, code breaks. That's normal. Iris Apps are resilient:
+
+- **Server error?** Show the error with stack trace and source link
+- **Invalid UI tree?** Render what's valid, highlight what's broken
+- **Tool fails?** Return error state, don't crash the app
+
+The development experience should feel like pair programming with a safety net.
+
+#### 6. Universal Runtime
+
+An Iris App runs in three modes from the same codebase:
+
+| Mode | Context | Use Case |
+|------|---------|----------|
+| **Development** | Inside Iris IDE | Building the app |
+| **Installed** | In any Iris project | Using the app as a tool |
+| **Standalone** | Independent server | Production deployment |
+
+Write once. Run everywhere. Not as a compromise, but as a feature.
+
+## What This Enables
+
+### For Individual Developers
+- Build custom tools in a single file
+- See changes instantly—no build step
+- AI can use your tools immediately
+- Works on your phone and tablet
+
+### For Teams
+- Share internal tools as installable apps
+- Consistent UI via shared component library
+- AI agents get team-specific capabilities
+- Same app works on all devices
+
+### For the Ecosystem
+- Apps are tiny (just server code)
+- Easy to review, audit, and trust
+- Component library evolves independently
+- Mobile and web parity by default
+
+## Why Server-Defined Rendering?
+
+The traditional approach:
+
+```
+Server Code  →  API  →  Frontend Code  →  Build  →  Bundle  →  Browser
+     │                       │               │          │
+     └─── Two codebases ─────┘               └── Slow ──┘
+```
+
+The SDR approach:
+
+```
+Server Code  →  Component Tree  →  Render
+     │               │               │
+     └── One file ───┴── Instant ────┘
+```
+
+**Benefits:**
+- **Instant updates** - No build step, no bundling
+- **Single source of truth** - UI logic lives with business logic
+- **Mobile parity** - Same components render natively
+- **Smaller apps** - No frontend bundle to ship
+- **AI-friendly** - UI is introspectable data
+
+**Trade-offs:**
+- Limited to the component library (by design)
+- Can't use arbitrary npm packages in UI (but can in server)
+- Less flexibility for highly custom UIs
+
+For the 90% of apps that are forms, lists, and data displays, SDR is dramatically simpler. For the 10% that need full control, we provide an escape hatch.
+
+## The Escape Hatch
+
+Some apps genuinely need full React control:
+- 3D visualization (Three.js)
+- Rich text editors (ProseMirror, TipTap)
+- Canvas-based drawing
+- Complex animations
+
+For these, apps can opt into **Custom UI Mode**:
+
+```json
+{
+  "ui": {
+    "mode": "custom",
+    "entry": "ui/index.html"
+  }
+}
+```
+
+Custom UI runs in a sandboxed context with a bridge to the server. It's more work to build but provides full flexibility when needed.
+
+## Success Metrics
+
+We'll know we've succeeded when:
+
+1. **Most apps are single-file** - No separate UI codebase needed
+
+2. **Mobile works automatically** - Apps built on desktop work on phones
+
+3. **AI agents use apps naturally** - Tool invocation feels seamless
+
+4. **Instant feedback** - Edit → See change is under 100ms
+
+5. **Errors don't break flow** - Every error has a recovery path
+
+## What We're Not Building
+
+To stay focused, we explicitly exclude:
+
+- **A general-purpose IDE** - Iris is for Iris Apps
+- **A no-code platform** - This is for developers who write code
+- **Arbitrary React apps** - SDR is the primary path; custom UI is the escape hatch
+- **A web-only solution** - Mobile parity is a requirement
+
+## The Name
+
+**Iris** - The messenger goddess, the rainbow bridge between worlds.
+
+We're building the bridge between:
+- Server and UI (SDR)
+- Development and runtime
+- Human intent and machine execution
+- Desktop and mobile
+
+**Iris Apps** - Applications that see, understand, and respond.
+
+---
+
+*"The best way to predict the future is to invent it." — Alan Kay*
+
+*We're not predicting. We're building.*
diff --git a/docs/apps-architecture/01-architecture.md b/docs/apps-architecture/01-architecture.md
new file mode 100644
index 0000000..ab5eb65
--- /dev/null
+++ b/docs/apps-architecture/01-architecture.md
@@ -0,0 +1,675 @@
+# Iris Apps: System Architecture
+
+## Overview
+
+Iris Apps use **Server-Defined Rendering (SDR)** as the primary UI approach. The server defines the UI as a component tree, and the client renders it using a shared component library. This enables instant updates, mobile parity, and dramatically simpler app development.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              IRIS PLATFORM                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌────────────────┐  ┌────────────────┐  ┌────────────────┐            │
+│  │   App Manager  │  │  Tool Registry │  │ Service Runner │            │
+│  │                │  │                │  │                │            │
+│  │  • Discovery   │  │  • AI tools    │  │  • Background  │            │
+│  │  • Lifecycle   │  │  • App tools   │  │  • Health      │            │
+│  │  • Hot reload  │  │  • Permissions │  │  • Logging     │            │
+│  └───────┬────────┘  └───────┬────────┘  └───────┬────────┘            │
+│          │                   │                   │                      │
+│          └───────────────────┼───────────────────┘                      │
+│                              │                                          │
+│                    ┌─────────▼─────────┐                               │
+│                    │    App Runtime    │                               │
+│                    │                   │                               │
+│                    │  • State mgmt     │                               │
+│                    │  • UI generation  │◄──── SDR: UI is data          │
+│                    │  • Tool exec      │                               │
+│                    │  • Event bridge   │                               │
+│                    └─────────┬─────────┘                               │
+│                              │                                          │
+│          ┌───────────────────┼───────────────────┐                      │
+│          │                   │                   │                      │
+│  ┌───────▼────────┐  ┌───────▼────────┐  ┌──────▼───────┐             │
+│  │   SDR Client   │  │   AI Agent     │  │   Protocol   │             │
+│  │   (Renderer)   │  │  Integration   │  │    Layer     │             │
+│  │                │  │                │  │              │             │
+│  │  • Component   │  │  • Tool calls  │  │  • WebSocket │             │
+│  │    registry    │  │  • Context     │  │  • State sync│             │
+│  │  • Web + RN    │  │  • Results     │  │  • Events    │             │
+│  └────────────────┘  └────────────────┘  └──────────────┘             │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## SDR Architecture
+
+### How Server-Defined Rendering Works
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          SDR DATA FLOW                                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   SERVER                              CLIENT                            │
+│   (Bun)                               (Web / React Native)              │
+│                                                                          │
+│   ┌──────────────────┐               ┌──────────────────┐              │
+│   │                  │               │                  │              │
+│   │   App State      │───────────────│   State Store    │              │
+│   │   { count: 5 }   │   WebSocket   │   { count: 5 }   │              │
+│   │                  │               │                  │              │
+│   └────────┬─────────┘               └────────┬─────────┘              │
+│            │                                  │                         │
+│            ▼                                  ▼                         │
+│   ┌──────────────────┐               ┌──────────────────┐              │
+│   │                  │               │                  │              │
+│   │   ui(ctx)        │───────────────│   SDR Renderer   │              │
+│   │   returns tree   │  Component    │   renders tree   │              │
+│   │                  │  Tree (JSON)  │                  │              │
+│   └──────────────────┘               └────────┬─────────┘              │
+│                                               │                         │
+│            Component Tree:                    ▼                         │
+│            {                         ┌──────────────────┐              │
+│              type: 'Stack',          │                  │              │
+│              props: { gap: 12 },     │   Native UI      │              │
+│              children: [             │   (React / RN)   │              │
+│                {                     │                  │              │
+│                  type: 'Text',       └──────────────────┘              │
+│                  props: { size: 'xl' },                                │
+│                  children: ['Count: 5']                                │
+│                },                                                       │
+│                {                                                        │
+│                  type: 'Button',                                       │
+│                  props: { onPress: { $action: 'increment' } },         │
+│                  children: ['+1']                                      │
+│                }                                                        │
+│              ]                                                          │
+│            }                                                            │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Component Tree Model
+
+The UI is represented as a JSON-serializable tree:
+
+```typescript
+// Component node in the tree
+interface ComponentNode {
+  $: 'component';
+  type: string;              // Component name from registry
+  key?: string;              // React key for reconciliation
+  props: Record<string, PropValue>;
+  children?: UINode[];
+}
+
+// Different node types
+type UINode =
+  | ComponentNode            // { $: 'component', type: 'Button', ... }
+  | string                   // Plain text
+  | number                   // Numbers render as text
+  | boolean                  // true/false (false = don't render)
+  | null                     // Don't render
+  | UINode[];                // Fragment (array of nodes)
+
+// Props can be values or special objects
+type PropValue =
+  | string | number | boolean | null
+  | PropValue[]
+  | { [key: string]: PropValue }
+  | ActionRef                // { $action: 'toolName', args?: {...} }
+  | StateRef                 // { $state: 'stateName' }
+  | StyleValue;              // { $style: {...} }
+```
+
+### Client-Side Rendering
+
+The SDR client renders the tree using a component registry:
+
+```typescript
+// Component registry maps type names to React components
+const ComponentRegistry = {
+  // Layout
+  'Stack': StackComponent,
+  'Row': RowComponent,
+  'Box': BoxComponent,
+  'ScrollView': ScrollViewComponent,
+
+  // Typography
+  'Text': TextComponent,
+  'Heading': HeadingComponent,
+  'Code': CodeComponent,
+
+  // Forms
+  'Button': ButtonComponent,
+  'Input': InputComponent,
+  'TextArea': TextAreaComponent,
+  'Select': SelectComponent,
+  'Checkbox': CheckboxComponent,
+  'Switch': SwitchComponent,
+
+  // Data Display
+  'DataTable': DataTableComponent,
+  'List': ListComponent,
+  'Card': CardComponent,
+
+  // Feedback
+  'Alert': AlertComponent,
+  'Spinner': SpinnerComponent,
+  'Progress': ProgressComponent,
+
+  // ...100+ more components
+};
+
+// Renderer walks the tree and creates React elements
+function renderNode(node: UINode): React.ReactNode {
+  if (node === null || node === false) return null;
+  if (typeof node === 'string' || typeof node === 'number') return node;
+  if (Array.isArray(node)) return node.map(renderNode);
+
+  const Component = ComponentRegistry[node.type];
+  if (!Component) {
+    return <UnknownComponent type={node.type} />;
+  }
+
+  const props = resolveProps(node.props);
+  const children = node.children?.map(renderNode);
+
+  return <Component key={node.key} {...props}>{children}</Component>;
+}
+```
+
+## Subsystem Details
+
+### 1. App Manager
+
+The App Manager handles discovery, loading, and lifecycle of apps.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       APP MANAGER                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Discovery          Loading           Lifecycle              │
+│  ┌──────────┐      ┌──────────┐      ┌──────────┐          │
+│  │ Scan for │      │ Validate │      │ Activate │          │
+│  │ app.json │─────▶│ manifest │─────▶│ runtime  │          │
+│  └──────────┘      │ + code   │      │          │          │
+│                    └──────────┘      └──────────┘          │
+│                                             │                │
+│  ┌──────────┐      ┌──────────┐            │                │
+│  │ Watch    │      │ Hot      │◀───────────┘                │
+│  │ files    │─────▶│ reload   │                             │
+│  └──────────┘      └──────────┘                             │
+│                                                              │
+│  For SDR apps:                                              │
+│  • No separate UI build needed                              │
+│  • File change → re-run ui() → push new tree               │
+│  • State preserved across reloads                           │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Key Data Structures:**
+
+```typescript
+interface ManagedApp {
+  // Identity
+  id: string;
+  manifest: AppManifest;
+  projectId: string;
+
+  // Paths
+  rootPath: string;
+  serverPath: string;
+
+  // Runtime state
+  status: AppStatus;
+  runtime: AppRuntime;
+
+  // UI mode
+  uiMode: 'sdr' | 'custom';
+
+  // For SDR: current UI tree
+  currentUI?: UINode;
+
+  // For custom UI: sandbox info
+  customUI?: {
+    entry: string;
+    devPort?: number;
+  };
+
+  // Hot reload
+  watcher: FSWatcher;
+}
+```
+
+### 2. App Runtime
+
+The runtime executes app code and manages the UI generation.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       APP RUNTIME                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                    Server Module                      │   │
+│  │                                                       │   │
+│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐        │   │
+│  │  │   State   │  │   Tools   │  │   UI fn   │        │   │
+│  │  │           │  │           │  │           │        │   │
+│  │  │ Reactive  │  │ AI-       │  │ Returns   │        │   │
+│  │  │ values    │  │ callable  │  │ tree      │        │   │
+│  │  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘        │   │
+│  │        │              │              │               │   │
+│  │        └──────────────┼──────────────┘               │   │
+│  │                       │                               │   │
+│  └───────────────────────┼───────────────────────────────┘   │
+│                          │                                    │
+│                  ┌───────▼───────┐                           │
+│                  │  UI Generator │                           │
+│                  │               │                           │
+│                  │  • Run ui(ctx)│                           │
+│                  │  • Diff trees │                           │
+│                  │  • Push delta │                           │
+│                  └───────┬───────┘                           │
+│                          │                                    │
+│            ┌─────────────┼─────────────┐                     │
+│            │             │             │                     │
+│    ┌───────▼───────┐ ┌───▼───┐ ┌───────▼───────┐           │
+│    │  State Sync   │ │ Tools │ │  Persistence  │           │
+│    │  (WebSocket)  │ │       │ │  (optional)   │           │
+│    └───────────────┘ └───────┘ └───────────────┘           │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**UI Generation Flow:**
+
+```typescript
+class AppRuntime {
+  private ui: UINode | null = null;
+
+  // Called when state changes or on reload
+  async regenerateUI(): Promise<void> {
+    // Create context with current state
+    const ctx = this.createUIContext();
+
+    // Run the UI function
+    const newUI = await this.module.ui(ctx);
+
+    // Validate the tree
+    const validated = validateUITree(newUI);
+
+    // Diff against current
+    const delta = diffTrees(this.ui, validated);
+
+    // Store new tree
+    this.ui = validated;
+
+    // Push delta to connected clients
+    this.broadcast({ type: 'ui:update', delta });
+  }
+
+  private createUIContext(): UIContext {
+    return {
+      state: this.createStateProxy(),
+      runTool: (name, args) => this.executeTool(name, args),
+      // ... other context methods
+    };
+  }
+}
+```
+
+### 3. Component Registry
+
+The component registry maps type strings to actual React components.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    COMPONENT REGISTRY                        │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                    @iris/ui-kit                       │   │
+│  │                                                       │   │
+│  │  LAYOUT          FORMS           DATA DISPLAY        │   │
+│  │  ────────        ─────           ────────────        │   │
+│  │  Stack           Button          DataTable           │   │
+│  │  Row             Input           List                │   │
+│  │  Box             TextArea        Card                │   │
+│  │  ScrollView      Select          Badge               │   │
+│  │  Divider         Checkbox        Avatar              │   │
+│  │                  Switch          Image               │   │
+│  │  TYPOGRAPHY      Radio           Code                │   │
+│  │  ──────────      Slider                              │   │
+│  │  Text            DatePicker      FEEDBACK            │   │
+│  │  Heading                         ────────            │   │
+│  │  Paragraph       NAVIGATION      Alert               │   │
+│  │  Label           ──────────      Toast               │   │
+│  │  Code            Tabs            Spinner             │   │
+│  │  Link            Menu            Progress            │   │
+│  │                  Breadcrumb      Skeleton            │   │
+│  │  OVERLAYS        Link                                │   │
+│  │  ────────                        SPECIALIZED         │   │
+│  │  Dialog          ICONS           ───────────         │   │
+│  │  Sheet           ─────           CodeEditor          │   │
+│  │  Tooltip         Icon            Terminal            │   │
+│  │  Popover         (lucide)        FileTree            │   │
+│  │                                  DiffViewer          │   │
+│  │                                  Markdown            │   │
+│  │                                                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Web: React components with Tailwind/CSS                    │
+│  Mobile: React Native components with StyleSheet            │
+│  Same API, platform-native rendering                        │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Cross-Platform Implementation:**
+
+```typescript
+// @iris/ui-kit/src/Button.tsx (web)
+export function Button({ onPress, variant, size, children, ...props }) {
+  return (
+    <button
+      onClick={onPress}
+      className={cn(buttonVariants({ variant, size }))}
+      {...props}
+    >
+      {children}
+    </button>
+  );
+}
+
+// @iris/ui-kit/src/Button.native.tsx (React Native)
+export function Button({ onPress, variant, size, children, ...props }) {
+  return (
+    <Pressable
+      onPress={onPress}
+      style={[styles.base, styles[variant], styles[size]]}
+      {...props}
+    >
+      <Text style={styles.text}>{children}</Text>
+    </Pressable>
+  );
+}
+
+// Same import, different implementation per platform
+```
+
+### 4. Tool Registry
+
+Tools are the primary way AI agents interact with apps.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      TOOL REGISTRY                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                    Tool Index                         │   │
+│  │                                                       │   │
+│  │  BUILTIN TOOLS (Iris Core)                           │   │
+│  │  ├─ read_file         Read file contents             │   │
+│  │  ├─ write_file        Write file contents            │   │
+│  │  ├─ bash              Execute shell command          │   │
+│  │  └─ ...                                              │   │
+│  │                                                       │   │
+│  │  APP TOOLS (from Iris Apps)                          │   │
+│  │  ├─ app:database-explorer/query                      │   │
+│  │  ├─ app:database-explorer/list_tables                │   │
+│  │  ├─ app:api-tester/send_request                      │   │
+│  │  └─ ...                                              │   │
+│  │                                                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Tool Execution Flow:                                       │
+│  1. AI requests tool call                                   │
+│  2. Registry finds tool by name                             │
+│  3. Permission check                                        │
+│  4. Execute tool with context                               │
+│  5. Tool updates app state (triggers UI regeneration)       │
+│  6. Return result to AI                                     │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 5. SDR Client
+
+The client receives UI trees and renders them.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        SDR CLIENT                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                    Connection                         │   │
+│  │                                                       │   │
+│  │  WebSocket to Iris server                            │   │
+│  │  ├─ Receive: ui:sync, ui:update, state:update        │   │
+│  │  └─ Send: action, state:set                          │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                    Renderer                           │   │
+│  │                                                       │   │
+│  │  ┌──────────┐   ┌──────────┐   ┌──────────┐        │   │
+│  │  │ Receive  │──▶│ Validate │──▶│  Render  │        │   │
+│  │  │   tree   │   │   tree   │   │   tree   │        │   │
+│  │  └──────────┘   └──────────┘   └────┬─────┘        │   │
+│  │                                      │              │   │
+│  │                                      ▼              │   │
+│  │                              ┌──────────────┐       │   │
+│  │                              │  React /     │       │   │
+│  │                              │  React Native│       │   │
+│  │                              └──────────────┘       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                 Action Handler                        │   │
+│  │                                                       │   │
+│  │  When user interacts (button press, input change):   │   │
+│  │  1. Serialize action: { $action: 'increment' }       │   │
+│  │  2. Send to server via WebSocket                     │   │
+│  │  3. Server executes tool/updates state               │   │
+│  │  4. Server pushes new UI tree                        │   │
+│  │  5. Client re-renders                                │   │
+│  │                                                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Data Flow
+
+### State Change → UI Update
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│   User      │     │   Server    │     │   Client    │
+│  (or AI)    │     │             │     │             │
+└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+       │                   │                   │
+       │  Tool call:       │                   │
+       │  increment()      │                   │
+       │──────────────────▶│                   │
+       │                   │                   │
+       │                   │  Update state     │
+       │                   │  count = count + 1│
+       │                   │                   │
+       │                   │  Re-run ui(ctx)   │
+       │                   │                   │
+       │                   │  UI tree update   │
+       │                   │──────────────────▶│
+       │                   │                   │
+       │                   │                   │  Re-render
+       │                   │                   │
+       │  Result           │                   │
+       │◀──────────────────│                   │
+       │                   │                   │
+```
+
+### Hot Reload Flow
+
+```
+┌─────────────┐     ┌─────────────┐     ┌─────────────┐
+│  File Edit  │     │   Server    │     │   Client    │
+│             │     │             │     │             │
+└──────┬──────┘     └──────┬──────┘     └──────┬──────┘
+       │                   │                   │
+       │  server.ts saved  │                   │
+       │──────────────────▶│                   │
+       │                   │                   │
+       │                   │  Snapshot state   │
+       │                   │                   │
+       │                   │  Reload module    │
+       │                   │  (Bun hot reload) │
+       │                   │                   │
+       │                   │  Restore state    │
+       │                   │                   │
+       │                   │  Re-run ui(ctx)   │
+       │                   │                   │
+       │                   │  Push new tree    │
+       │                   │──────────────────▶│
+       │                   │                   │
+       │                   │                   │  Re-render
+       │                   │                   │  (instant)
+       │                   │                   │
+```
+
+## Custom UI Mode (Escape Hatch)
+
+For apps that need full React control:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     CUSTOM UI MODE                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  App opts in via manifest:                                  │
+│  {                                                           │
+│    "ui": {                                                   │
+│      "mode": "custom",                                       │
+│      "entry": "ui/index.html"                               │
+│    }                                                         │
+│  }                                                           │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                    Web Platform                       │   │
+│  │                                                       │   │
+│  │  Options:                                            │   │
+│  │  • Shadow DOM (same context, style isolation)        │   │
+│  │  • iframe (full isolation, security sandbox)         │   │
+│  │                                                       │   │
+│  │  Communication via postMessage bridge                │   │
+│  │                                                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                   Mobile Platform                     │   │
+│  │                                                       │   │
+│  │  WebView with bridge to React Native                 │   │
+│  │  (Acknowledged limitation - not native)              │   │
+│  │                                                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Trade-offs vs SDR:                                         │
+│  ✗ Requires separate build system (Vite)                   │
+│  ✗ Slower hot reload                                        │
+│  ✗ Mobile uses WebView, not native                         │
+│  ✓ Full control over UI                                     │
+│  ✓ Can use any npm packages                                 │
+│  ✓ Complex visualizations possible                          │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Deployment Architecture
+
+### Standalone Mode
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                     STANDALONE APP                           │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │                  @iris/runtime                        │   │
+│  │                                                       │   │
+│  │  Minimal runtime that provides:                      │   │
+│  │  • App loading and execution                         │   │
+│  │  • State management                                  │   │
+│  │  • WebSocket server for SDR clients                  │   │
+│  │  • HTTP API for tool invocation                      │   │
+│  │  • Optional: static file serving for web client      │   │
+│  │                                                       │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Deployment options:                                        │
+│  • Server + Web client (serve from same process)           │
+│  • Server + Mobile app (connect via WebSocket)             │
+│  • API-only (tools accessible via REST)                    │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Technology Choices
+
+| Component | Technology | Rationale |
+|-----------|------------|-----------|
+| **Backend Runtime** | Bun | Fast startup, native TS, hot reload |
+| **Component Library** | React + React Native | Cross-platform, ecosystem |
+| **State Management** | Custom signals | Simple, serializable, reactive |
+| **Communication** | WebSocket | Real-time, bidirectional |
+| **Schema Validation** | Zod | Runtime validation, TS inference |
+| **Styling (Web)** | Tailwind CSS | Utility-first, consistent |
+| **Styling (Mobile)** | StyleSheet | Native performance |
+
+## Security Boundaries
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SECURITY ZONES                            │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  ZONE 1: Iris Core (Trusted)                        │   │
+│  │                                                       │   │
+│  │  • Full system access                                │   │
+│  │  • Manages all apps                                  │   │
+│  │  • Controls permissions                              │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  ZONE 2: App Server (Permission-gated)              │   │
+│  │                                                       │   │
+│  │  • Declared permissions only                         │   │
+│  │  • Scoped file access                                │   │
+│  │  • Scoped network access                             │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │  ZONE 3: SDR Client (Data-only)                     │   │
+│  │                                                       │   │
+│  │  • Only renders data from server                     │   │
+│  │  • No direct system access                           │   │
+│  │  • Components are from trusted registry              │   │
+│  └─────────────────────────────────────────────────────┘   │
+│                                                              │
+│  Note: SDR simplifies security!                             │
+│  • No arbitrary JS execution on client                     │
+│  • No need for iframe sandbox                              │
+│  • All logic runs on server (controlled environment)       │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+*Next: [02-app-model.md](./02-app-model.md) - Detailed app model and lifecycle*
diff --git a/docs/apps-architecture/02-app-model.md b/docs/apps-architecture/02-app-model.md
new file mode 100644
index 0000000..22f4b31
--- /dev/null
+++ b/docs/apps-architecture/02-app-model.md
@@ -0,0 +1,670 @@
+# Iris Apps: App Model & Lifecycle
+
+## The App Model
+
+An Iris App is a single-file application that combines:
+
+1. **State** - Reactive values that drive the UI
+2. **Tools** - Functions exposed to AI agents and the UI
+3. **UI** - A function that returns a component tree (SDR)
+4. **Services** - Optional background processes
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                       IRIS APP                               │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │                     Manifest                          │  │
+│  │                    (app.json)                         │  │
+│  │                                                        │  │
+│  │  • Identity (name, version, description)              │  │
+│  │  • Capabilities (tools, services)                     │  │
+│  │  • Requirements (permissions)                         │  │
+│  │  • UI mode (sdr or custom)                            │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                              │
+│  ┌──────────────────────────────────────────────────────┐  │
+│  │                   Server Module                       │  │
+│  │                   (server.ts)                         │  │
+│  │                                                        │  │
+│  │  export default defineApp({                           │  │
+│  │    state: { ... },      // Reactive state             │  │
+│  │    tools: [ ... ],      // AI-callable functions      │  │
+│  │    ui: (ctx) => ...,    // SDR UI function            │  │
+│  │    services: { ... },   // Background services        │  │
+│  │    onActivate: ...,     // Lifecycle hooks            │  │
+│  │  })                                                   │  │
+│  │                                                        │  │
+│  └──────────────────────────────────────────────────────┘  │
+│                                                              │
+│  For most apps: NO SEPARATE UI FOLDER                       │
+│  The ui() function IS the UI                                │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## App Structure
+
+### Minimal App (Single File)
+
+```
+my-app/
+├── app.json        # Manifest
+└── server.ts       # Everything else
+```
+
+### App with Assets
+
+```
+my-app/
+├── app.json        # Manifest
+├── server.ts       # App logic + UI
+└── assets/         # Static files (optional)
+    ├── icon.png
+    └── data.json
+```
+
+### App with Custom UI (Escape Hatch)
+
+```
+my-app/
+├── app.json        # Manifest with ui.mode: "custom"
+├── server.ts       # Tools, state, services
+└── ui/             # Full React app
+    ├── index.html
+    ├── vite.config.ts
+    └── src/
+        └── App.tsx
+```
+
+## Manifest Schema
+
+### SDR App (Default)
+
+```json
+{
+  "$schema": "https://iris.dev/schemas/app.json",
+
+  "name": "database-explorer",
+  "displayName": "Database Explorer",
+  "version": "1.0.0",
+  "description": "Browse and query SQLite databases",
+  "icon": "database",
+
+  "server": "server.ts",
+
+  "tools": [
+    {
+      "name": "query",
+      "description": "Execute a SQL query against the database"
+    },
+    {
+      "name": "list_tables",
+      "description": "List all tables in the database"
+    }
+  ],
+
+  "permissions": [
+    "filesystem:read:$PROJECT",
+    "ai:chat"
+  ]
+}
+```
+
+### Custom UI App
+
+```json
+{
+  "name": "3d-visualizer",
+  "displayName": "3D Visualizer",
+  "version": "1.0.0",
+
+  "server": "server.ts",
+
+  "ui": {
+    "mode": "custom",
+    "entry": "ui/index.html",
+    "devPort": 5174
+  },
+
+  "tools": [...],
+  "permissions": [...]
+}
+```
+
+### Manifest Fields
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `name` | Yes | Unique identifier (lowercase, hyphens) |
+| `displayName` | Yes | Human-readable name |
+| `version` | Yes | Semver version |
+| `description` | No | Brief description |
+| `icon` | No | Icon name (from Lucide icons) |
+| `server` | Yes | Path to server module |
+| `ui` | No | Custom UI config (omit for SDR) |
+| `ui.mode` | No | `"sdr"` (default) or `"custom"` |
+| `ui.entry` | Only for custom | Path to UI entry point |
+| `tools` | No | Tools exposed to AI agent |
+| `services` | No | Background services |
+| `permissions` | Yes | Required permissions |
+
+## Complete App Example
+
+```typescript
+// server.ts
+import { defineApp, defineTool, state } from '@iris/app-sdk';
+import { Stack, Heading, Input, Button, DataTable, Text, Alert } from '@iris/ui';
+import { z } from 'zod';
+
+export default defineApp({
+  // Reactive state
+  state: {
+    query: state('SELECT * FROM users LIMIT 10'),
+    results: state<any[]>([]),
+    error: state<string | null>(null),
+    isLoading: state(false),
+  },
+
+  // Tools exposed to AI agent
+  tools: [
+    defineTool({
+      name: 'query',
+      description: 'Execute a SQL query against the database',
+      parameters: z.object({
+        sql: z.string().describe('The SQL query to execute'),
+      }),
+      execute: async ({ sql }, ctx) => {
+        ctx.state.isLoading.set(true);
+        ctx.state.error.set(null);
+        ctx.state.query.set(sql);
+
+        try {
+          const db = await ctx.getService('database');
+          const results = await db.query(sql);
+          ctx.state.results.set(results);
+          return { success: true, rowCount: results.length };
+        } catch (e) {
+          ctx.state.error.set(e.message);
+          return { success: false, error: e.message };
+        } finally {
+          ctx.state.isLoading.set(false);
+        }
+      },
+    }),
+
+    defineTool({
+      name: 'list_tables',
+      description: 'List all tables in the database',
+      parameters: z.object({}),
+      execute: async (_, ctx) => {
+        const db = await ctx.getService('database');
+        const tables = await db.query(
+          "SELECT name FROM sqlite_master WHERE type='table'"
+        );
+        return { tables: tables.map(t => t.name) };
+      },
+    }),
+  ],
+
+  // Services
+  services: {
+    database: {
+      start: async (ctx) => {
+        const dbPath = await ctx.getConfig('databasePath');
+        return new Database(dbPath);
+      },
+      stop: async (db) => {
+        await db.close();
+      },
+      autoStart: true,
+    },
+  },
+
+  // UI function - returns component tree
+  ui: (ctx) => {
+    const { query, results, error, isLoading } = ctx.state;
+
+    return Stack({ padding: 16, gap: 16 }, [
+      // Header
+      Heading({ level: 1 }, 'Database Explorer'),
+
+      // Query input
+      Stack({ gap: 8 }, [
+        Input({
+          value: query,
+          onChangeText: query.set,
+          placeholder: 'Enter SQL query...',
+          multiline: true,
+          rows: 3,
+        }),
+        Button({
+          onPress: () => ctx.runTool('query', { sql: query.get() }),
+          disabled: isLoading,
+        }, isLoading ? 'Running...' : 'Execute Query'),
+      ]),
+
+      // Error display
+      error && Alert({ variant: 'error' }, error),
+
+      // Results table
+      results.length > 0 && DataTable({
+        data: results,
+        columns: Object.keys(results[0] || {}),
+      }),
+
+      // Empty state
+      results.length === 0 && !error && !isLoading &&
+        Text({ color: 'muted' }, 'Run a query to see results'),
+    ]);
+  },
+
+  // Lifecycle
+  onActivate: async (ctx) => {
+    ctx.log.info('Database Explorer activated');
+  },
+});
+```
+
+## SDR UI Model
+
+### Component Functions
+
+UI is built with component functions that return component nodes:
+
+```typescript
+// Component function signature
+function ComponentName(props: Props, children?: Children): ComponentNode
+
+// Examples
+Heading({ level: 1 }, 'Hello World')
+Button({ onPress: handler, variant: 'primary' }, 'Click Me')
+Stack({ gap: 8, padding: 16 }, [child1, child2, child3])
+```
+
+### Component Node Structure
+
+```typescript
+// What the component function returns
+interface ComponentNode {
+  $: 'component';
+  type: string;              // 'Button', 'Stack', etc.
+  props: Record<string, PropValue>;
+  children?: UINode[];
+}
+
+// Example
+Heading({ level: 1 }, 'Hello')
+// Returns:
+{
+  $: 'component',
+  type: 'Heading',
+  props: { level: 1 },
+  children: ['Hello']
+}
+```
+
+### Conditional Rendering
+
+```typescript
+// Using && for conditional
+error && Alert({ variant: 'error' }, error)
+
+// Using ternary
+isLoading ? Spinner({}) : Button({}, 'Submit')
+
+// Filtering arrays
+items.filter(item => item.visible).map(item => Card({}, item.name))
+```
+
+### Lists and Keys
+
+```typescript
+// Map over data with keys
+items.map(item =>
+  Card({ key: item.id }, [
+    Text({ weight: 'bold' }, item.title),
+    Text({ color: 'muted' }, item.description),
+  ])
+)
+```
+
+### Event Handlers
+
+```typescript
+// Direct state update
+Input({
+  value: ctx.state.query,
+  onChangeText: ctx.state.query.set,
+})
+
+// Tool call
+Button({
+  onPress: () => ctx.runTool('submit', { data: ctx.state.form.get() }),
+}, 'Submit')
+
+// Custom handler
+Button({
+  onPress: { $action: 'increment', args: { amount: 5 } },
+}, '+5')
+```
+
+### State References
+
+```typescript
+// Reading state in UI
+Text({}, `Count: ${ctx.state.count}`)
+
+// The ctx.state.count is reactive - UI updates when it changes
+```
+
+## State Model
+
+### State Types
+
+```typescript
+import { state, computed, query } from '@iris/app-sdk';
+
+// Primitive state - simple reactive value
+const count = state(0);
+const name = state('');
+const items = state<Item[]>([]);
+
+// Computed state - derived from other state
+const doubled = computed((get) => get(count) * 2);
+const filtered = computed((get) =>
+  get(items).filter(i => i.active)
+);
+
+// Query state - async data with caching
+const users = query(async (ctx) => {
+  const response = await ctx.fetch('/api/users');
+  return response.json();
+}, {
+  staleTime: 60_000,  // Fresh for 1 minute
+});
+```
+
+### State Operations
+
+```typescript
+// Get current value
+const current = count.get();
+
+// Set new value
+count.set(5);
+
+// Update based on previous
+count.update(n => n + 1);
+
+// For arrays
+items.update(list => [...list, newItem]);
+items.update(list => list.filter(i => i.id !== id));
+
+// Subscribe to changes (rarely needed - UI auto-subscribes)
+const unsubscribe = count.subscribe(value => {
+  console.log('Count changed:', value);
+});
+```
+
+### State in UI Context
+
+```typescript
+ui: (ctx) => {
+  // Access state values (reactive)
+  const { count, items } = ctx.state;
+
+  // Use in UI
+  return Stack({}, [
+    Text({}, `Count: ${count}`),
+    Text({}, `Items: ${items.length}`),
+
+    // Update state
+    Button({ onPress: () => count.update(n => n + 1) }, '+1'),
+  ]);
+}
+```
+
+## Tool Model
+
+### Tool Definition
+
+```typescript
+defineTool({
+  // Required
+  name: 'query',
+  description: 'Execute a SQL query',
+  parameters: z.object({
+    sql: z.string().describe('SQL query to execute'),
+    params: z.array(z.unknown()).optional(),
+  }),
+  execute: async (args, ctx) => {
+    // Implementation
+    return { success: true, data: results };
+  },
+
+  // Optional
+  examples: [
+    {
+      description: 'Get all users',
+      input: { sql: 'SELECT * FROM users' },
+    },
+  ],
+})
+```
+
+### Tool Context
+
+```typescript
+interface ToolContext {
+  // App identity
+  appId: string;
+  projectId: string;
+
+  // State access
+  state: StateMap;
+
+  // Services
+  getService<T>(name: string): Promise<T>;
+
+  // Platform access
+  iris: {
+    ai: { chat, embed };
+    fs: { read, write, list };
+    tools: { call };
+  };
+
+  // Logging
+  log: Logger;
+}
+```
+
+### Calling Tools from UI
+
+```typescript
+ui: (ctx) => {
+  return Button({
+    onPress: async () => {
+      const result = await ctx.runTool('query', {
+        sql: ctx.state.query.get()
+      });
+      if (!result.success) {
+        ctx.state.error.set(result.error);
+      }
+    }
+  }, 'Run Query');
+}
+```
+
+## Service Model
+
+### Internal Service
+
+```typescript
+services: {
+  database: {
+    start: async (ctx) => {
+      const config = await ctx.getConfig('database');
+      const db = new Database(config.path);
+      return db;
+    },
+    stop: async (db) => {
+      await db.close();
+    },
+    autoStart: true,
+  },
+}
+
+// Usage in tools
+const db = await ctx.getService('database');
+```
+
+### Process Service
+
+```typescript
+services: {
+  'dev-server': {
+    type: 'process',
+    command: 'npm',
+    args: ['run', 'dev'],
+    cwd: './server',
+    env: { PORT: '3001' },
+    autoStart: false,
+  },
+}
+```
+
+## App Lifecycle
+
+### State Machine
+
+```
+                    ┌─────────────┐
+                    │  DISCOVERED │
+                    └──────┬──────┘
+                           │ load()
+                           ▼
+                    ┌─────────────┐
+                    │   LOADING   │
+                    └──────┬──────┘
+                           │
+                      ┌────┴────┐
+                      ▼         ▼
+               ┌─────────┐ ┌─────────┐
+               │  ERROR  │ │  LOADED │
+               └─────────┘ └────┬────┘
+                                │ activate()
+                                ▼
+                         ┌─────────────┐
+                         │   ACTIVE    │◄──── Hot reload
+                         └──────┬──────┘      (re-run ui())
+                                │
+                           deactivate()
+                                │
+                                ▼
+                         ┌─────────────┐
+                         │   STOPPED   │
+                         └─────────────┘
+```
+
+### Lifecycle Hooks
+
+```typescript
+export default defineApp({
+  // Called when app becomes active
+  onActivate: async (ctx) => {
+    await ctx.startService('database');
+    ctx.log.info('App activated');
+  },
+
+  // Called when app is deactivated
+  onDeactivate: async (ctx) => {
+    await ctx.stopService('database');
+    ctx.log.info('App deactivated');
+  },
+
+  // Called on hot reload (state is preserved)
+  onReload: async (ctx, previousState) => {
+    ctx.log.info('App reloaded');
+  },
+
+  // Called when an error occurs
+  onError: async (ctx, error) => {
+    ctx.log.error('App error:', error);
+    ctx.state.lastError.set(error.message);
+    return true; // Error handled
+  },
+});
+```
+
+## Configuration
+
+### Config Schema in Manifest
+
+```json
+{
+  "configuration": {
+    "properties": {
+      "databasePath": {
+        "type": "string",
+        "description": "Path to SQLite database file",
+        "default": "./data.db"
+      },
+      "maxResults": {
+        "type": "number",
+        "default": 100
+      }
+    }
+  }
+}
+```
+
+### Accessing Config
+
+```typescript
+// In tools or lifecycle hooks
+const dbPath = await ctx.getConfig('databasePath');
+await ctx.setConfig('maxResults', 50);
+
+// Watch for changes
+ctx.onConfigChange('databasePath', async (newPath) => {
+  await ctx.restartService('database');
+});
+```
+
+## Permission Model
+
+### Permission Declaration
+
+```json
+{
+  "permissions": [
+    "filesystem:read:$PROJECT",
+    "filesystem:write:$APP/data",
+    "network:localhost",
+    "ai:chat"
+  ]
+}
+```
+
+### Permission Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `$PROJECT` | Current project directory |
+| `$APP` | App's directory |
+| `$DATA` | App's data directory |
+| Domain pattern | e.g., `*.example.com` |
+
+### Permission Categories
+
+- `filesystem:read`, `filesystem:write` - File access
+- `network:*`, `network:localhost` - Network access
+- `ai:chat`, `ai:embed` - AI model access
+- `iris:tools` - Call other Iris tools
+- `process:spawn` - Run shell commands
+
+---
+
+*Next: [03-sdk-design.md](./03-sdk-design.md) - SDK API design*
diff --git a/docs/apps-architecture/03-sdk-design.md b/docs/apps-architecture/03-sdk-design.md
new file mode 100644
index 0000000..7f7c352
--- /dev/null
+++ b/docs/apps-architecture/03-sdk-design.md
@@ -0,0 +1,708 @@
+# Iris Apps: SDK Design
+
+## Overview
+
+The Iris App SDK enables developers to build apps with Server-Defined Rendering. The SDK is intentionally simple—most apps are a single file.
+
+```
+@iris/app-sdk
+├── defineApp()       Define an app
+├── defineTool()      Define a tool
+├── state()           Create reactive state
+├── computed()        Create derived state
+├── query()           Create async query state
+└── ...
+
+@iris/ui
+├── Stack, Row, Box   Layout components
+├── Text, Heading     Typography
+├── Button, Input     Form elements
+├── DataTable, List   Data display
+└── 100+ components   Full UI kit
+```
+
+## Quick Start
+
+```typescript
+// server.ts - A complete Iris App
+import { defineApp, defineTool, state } from '@iris/app-sdk';
+import { Stack, Text, Button } from '@iris/ui';
+import { z } from 'zod';
+
+export default defineApp({
+  state: {
+    count: state(0),
+  },
+
+  tools: [
+    defineTool({
+      name: 'increment',
+      description: 'Increment the counter',
+      parameters: z.object({
+        amount: z.number().default(1),
+      }),
+      execute: async ({ amount }, ctx) => {
+        ctx.state.count.update(n => n + amount);
+        return { newValue: ctx.state.count.get() };
+      },
+    }),
+  ],
+
+  ui: (ctx) => (
+    Stack({ padding: 24, gap: 16, align: 'center' }, [
+      Text({ size: '4xl', weight: 'bold' }, ctx.state.count),
+      Button({
+        onPress: () => ctx.state.count.update(n => n + 1),
+        size: 'lg',
+      }, '+1'),
+    ])
+  ),
+});
+```
+
+## Core API
+
+### defineApp()
+
+Creates an app definition:
+
+```typescript
+import { defineApp } from '@iris/app-sdk';
+
+export default defineApp({
+  // Reactive state (optional)
+  state: {
+    count: state(0),
+    items: state<Item[]>([]),
+  },
+
+  // Computed values (optional)
+  computed: {
+    total: computed((get) => get('items').reduce((sum, i) => sum + i.price, 0)),
+  },
+
+  // Async queries (optional)
+  queries: {
+    users: query(async (ctx) => {
+      return ctx.fetch('/api/users').then(r => r.json());
+    }),
+  },
+
+  // Tools for AI and UI (optional)
+  tools: [
+    defineTool({ ... }),
+  ],
+
+  // Background services (optional)
+  services: {
+    database: { ... },
+  },
+
+  // UI function - returns component tree
+  ui: (ctx) => {
+    return Stack({}, [...]);
+  },
+
+  // Lifecycle hooks (optional)
+  onActivate: async (ctx) => { ... },
+  onDeactivate: async (ctx) => { ... },
+  onReload: async (ctx) => { ... },
+  onError: async (ctx, error) => { ... },
+});
+```
+
+### defineTool()
+
+Creates a tool that AI agents and the UI can call:
+
+```typescript
+import { defineTool } from '@iris/app-sdk';
+import { z } from 'zod';
+
+const queryTool = defineTool({
+  // Required
+  name: 'query',
+  description: 'Execute a SQL query against the database',
+  parameters: z.object({
+    sql: z.string().describe('The SQL query'),
+    limit: z.number().optional().default(100),
+  }),
+  execute: async (args, ctx) => {
+    const db = await ctx.getService('database');
+    const results = await db.query(args.sql, args.limit);
+    ctx.state.lastQuery.set(args.sql);
+    ctx.state.results.set(results);
+    return { rowCount: results.length, rows: results };
+  },
+
+  // Optional
+  examples: [
+    { description: 'Get all users', input: { sql: 'SELECT * FROM users' } },
+  ],
+});
+```
+
+### state()
+
+Creates reactive state:
+
+```typescript
+import { state } from '@iris/app-sdk';
+
+// Primitive values
+const count = state(0);
+const name = state('');
+const isActive = state(false);
+
+// Complex values
+const items = state<Item[]>([]);
+const user = state<User | null>(null);
+const form = state({ name: '', email: '' });
+
+// With options
+const history = state<string[]>([], {
+  persist: true,           // Save to disk
+  persistKey: 'history',   // Custom key
+  maxLength: 100,          // Limit array length
+});
+```
+
+**State Operations:**
+
+```typescript
+// Read
+const value = count.get();
+
+// Write
+count.set(5);
+
+// Update
+count.update(n => n + 1);
+items.update(list => [...list, newItem]);
+items.update(list => list.filter(i => i.id !== targetId));
+
+// In UI context, state is reactive
+ui: (ctx) => {
+  // This auto-updates when count changes
+  return Text({}, `Count: ${ctx.state.count}`);
+}
+```
+
+### computed()
+
+Creates derived state:
+
+```typescript
+import { computed } from '@iris/app-sdk';
+
+// Simple computation
+const doubled = computed((get) => get('count') * 2);
+
+// Derived from multiple states
+const summary = computed((get) => {
+  const items = get('items');
+  const filter = get('filter');
+  return items
+    .filter(i => i.name.includes(filter))
+    .map(i => i.name)
+    .join(', ');
+});
+
+// Async computed (becomes a query)
+const filteredUsers = computed(async (get, ctx) => {
+  const filter = get('filter');
+  const users = await ctx.queries.users.get();
+  return users.filter(u => u.name.includes(filter));
+});
+```
+
+### query()
+
+Creates async data with caching:
+
+```typescript
+import { query } from '@iris/app-sdk';
+
+const users = query(
+  async (ctx) => {
+    const response = await ctx.fetch('/api/users');
+    return response.json();
+  },
+  {
+    staleTime: 60_000,      // Fresh for 1 minute
+    cacheTime: 300_000,     // Keep in cache for 5 minutes
+    refetchOnMount: true,   // Refetch when app opens
+    retry: 3,               // Retry failed requests
+  }
+);
+
+// Usage
+const data = users.get();        // Current data (may be undefined)
+await users.load();              // Force load
+users.invalidate();              // Clear cache
+const isLoading = users.loading; // Loading state
+const error = users.error;       // Error state
+```
+
+## UI Components (@iris/ui)
+
+### Layout Components
+
+```typescript
+import { Stack, Row, Box, ScrollView, Divider } from '@iris/ui';
+
+// Vertical stack
+Stack({ gap: 8, padding: 16 }, [
+  child1,
+  child2,
+])
+
+// Horizontal row
+Row({ gap: 8, justify: 'space-between' }, [
+  left,
+  right,
+])
+
+// Generic container
+Box({ padding: 16, background: 'muted', rounded: 'lg' }, content)
+
+// Scrollable area
+ScrollView({ maxHeight: 400 }, longContent)
+
+// Separator
+Divider({ orientation: 'horizontal' })
+```
+
+### Typography
+
+```typescript
+import { Text, Heading, Code, Link } from '@iris/ui';
+
+// Basic text
+Text({}, 'Hello world')
+Text({ size: 'lg', weight: 'bold', color: 'primary' }, 'Important')
+
+// Headings
+Heading({ level: 1 }, 'Page Title')
+Heading({ level: 2 }, 'Section')
+
+// Code
+Code({ language: 'typescript' }, 'const x = 1')
+
+// Links
+Link({ href: '/other-page' }, 'Click here')
+```
+
+### Form Elements
+
+```typescript
+import { Button, Input, TextArea, Select, Checkbox, Switch } from '@iris/ui';
+
+// Button
+Button({ onPress: handler, variant: 'primary', size: 'lg' }, 'Submit')
+Button({ onPress: handler, disabled: true }, 'Disabled')
+
+// Text input
+Input({
+  value: ctx.state.name,
+  onChangeText: ctx.state.name.set,
+  placeholder: 'Enter name...',
+})
+
+// Number input
+Input({
+  type: 'number',
+  value: ctx.state.amount,
+  onChangeText: v => ctx.state.amount.set(Number(v)),
+})
+
+// Text area
+TextArea({
+  value: ctx.state.description,
+  onChangeText: ctx.state.description.set,
+  rows: 4,
+})
+
+// Select dropdown
+Select({
+  value: ctx.state.category,
+  onValueChange: ctx.state.category.set,
+  options: [
+    { label: 'Option 1', value: 'opt1' },
+    { label: 'Option 2', value: 'opt2' },
+  ],
+})
+
+// Checkbox
+Checkbox({
+  checked: ctx.state.agreed,
+  onCheckedChange: ctx.state.agreed.set,
+  label: 'I agree to terms',
+})
+
+// Switch/toggle
+Switch({
+  checked: ctx.state.enabled,
+  onCheckedChange: ctx.state.enabled.set,
+})
+```
+
+### Data Display
+
+```typescript
+import { DataTable, List, Card, Badge, Avatar } from '@iris/ui';
+
+// Data table
+DataTable({
+  data: ctx.state.users,
+  columns: [
+    { key: 'name', header: 'Name' },
+    { key: 'email', header: 'Email' },
+    { key: 'role', header: 'Role', render: (role) => Badge({}, role) },
+  ],
+  onRowClick: (row) => ctx.state.selected.set(row.id),
+})
+
+// List
+List({
+  data: ctx.state.items,
+  renderItem: (item) => (
+    Row({ gap: 8 }, [
+      Avatar({ src: item.avatar }),
+      Text({}, item.name),
+    ])
+  ),
+})
+
+// Card
+Card({ padding: 16 }, [
+  Heading({ level: 3 }, 'Card Title'),
+  Text({}, 'Card content'),
+])
+
+// Badge
+Badge({ variant: 'success' }, 'Active')
+Badge({ variant: 'error' }, 'Failed')
+```
+
+### Feedback
+
+```typescript
+import { Alert, Spinner, Progress, Toast } from '@iris/ui';
+
+// Alert
+Alert({ variant: 'info', title: 'Note' }, 'This is informational')
+Alert({ variant: 'error' }, 'Something went wrong')
+
+// Loading spinner
+Spinner({ size: 'lg' })
+
+// Progress bar
+Progress({ value: 0.7, max: 1 })
+
+// Toast (triggered via context)
+ctx.toast({ message: 'Saved!', variant: 'success' })
+```
+
+### Overlays
+
+```typescript
+import { Dialog, Sheet, Tooltip, Popover } from '@iris/ui';
+
+// Dialog
+Dialog({
+  open: ctx.state.dialogOpen,
+  onOpenChange: ctx.state.dialogOpen.set,
+  title: 'Confirm',
+}, [
+  Text({}, 'Are you sure?'),
+  Row({ gap: 8, justify: 'end' }, [
+    Button({ onPress: () => ctx.state.dialogOpen.set(false) }, 'Cancel'),
+    Button({ onPress: handleConfirm, variant: 'primary' }, 'Confirm'),
+  ]),
+])
+
+// Tooltip
+Tooltip({ content: 'More information' },
+  Button({}, 'Hover me')
+)
+```
+
+### Icons
+
+```typescript
+import { Icon } from '@iris/ui';
+
+// Uses Lucide icons
+Icon({ name: 'database', size: 24 })
+Icon({ name: 'check', color: 'green' })
+Icon({ name: 'x', color: 'red' })
+```
+
+### Specialized Components
+
+```typescript
+import { CodeEditor, Terminal, FileTree, Markdown } from '@iris/ui';
+
+// Code editor
+CodeEditor({
+  value: ctx.state.code,
+  onChange: ctx.state.code.set,
+  language: 'typescript',
+  theme: 'dark',
+})
+
+// Terminal output
+Terminal({
+  lines: ctx.state.logs,
+  autoScroll: true,
+})
+
+// File tree
+FileTree({
+  files: ctx.state.files,
+  onSelect: (path) => ctx.state.selectedFile.set(path),
+})
+
+// Markdown renderer
+Markdown({}, ctx.state.readme)
+```
+
+## UI Context
+
+The `ui` function receives a context with everything needed:
+
+```typescript
+ui: (ctx) => {
+  // State access
+  const { count, items, user } = ctx.state;
+
+  // Computed values
+  const { total, filteredItems } = ctx.computed;
+
+  // Query data
+  const users = ctx.queries.users;
+
+  // Run tools
+  const handleSubmit = () => ctx.runTool('submit', { data: form.get() });
+
+  // Access Iris platform (if permitted)
+  const handleAI = async () => {
+    const response = await ctx.iris.ai.chat([
+      { role: 'user', content: 'Summarize this' }
+    ]);
+  };
+
+  // Show notifications
+  ctx.toast({ message: 'Saved!', variant: 'success' });
+
+  // Theme info
+  const { theme, isDark } = ctx.theme;
+
+  // App info
+  const { appId, projectId } = ctx.app;
+
+  return Stack({}, [...]);
+}
+```
+
+## Platform Access
+
+Apps can access Iris platform features through the context:
+
+### AI Access
+
+```typescript
+// Requires: "ai:chat" permission
+const response = await ctx.iris.ai.chat([
+  { role: 'system', content: 'You are a helpful assistant' },
+  { role: 'user', content: userQuestion },
+], {
+  model: 'claude-sonnet',
+  maxTokens: 1000,
+});
+
+// Requires: "ai:embed" permission
+const embeddings = await ctx.iris.ai.embed(['text1', 'text2']);
+```
+
+### File System
+
+```typescript
+// Requires: "filesystem:read:$PROJECT" permission
+const content = await ctx.iris.fs.read('src/index.ts');
+const files = await ctx.iris.fs.list('src');
+const exists = await ctx.iris.fs.exists('package.json');
+
+// Requires: "filesystem:write:$APP/data" permission
+await ctx.iris.fs.write('data/output.json', JSON.stringify(data));
+```
+
+### Other Tools
+
+```typescript
+// Requires: "iris:tools" permission
+const result = await ctx.iris.tools.call('bash', {
+  command: 'npm run build',
+});
+```
+
+### Navigation
+
+```typescript
+// Requires: "iris:navigation" permission (usually implicit)
+ctx.iris.navigate('/files/src/index.ts');
+ctx.iris.openTab({ type: 'file', path: 'src/index.ts' });
+```
+
+## Type Safety
+
+The SDK provides full TypeScript support:
+
+```typescript
+// Types are inferred from state definitions
+const count = state(0);              // StateHandle<number>
+const items = state<Item[]>([]);     // StateHandle<Item[]>
+
+// Tool parameters are validated at runtime AND compile time
+defineTool({
+  parameters: z.object({
+    id: z.string(),
+    count: z.number(),
+  }),
+  execute: async (args, ctx) => {
+    // args is typed as { id: string; count: number }
+    args.id;    // string
+    args.count; // number
+  },
+});
+
+// Component props are typed
+Button({
+  onPress: () => {},  // required
+  variant: 'primary', // 'primary' | 'secondary' | 'ghost' | ...
+  size: 'lg',         // 'sm' | 'md' | 'lg'
+  disabled: false,    // boolean
+}, 'Click');
+```
+
+## Custom UI Mode
+
+For apps that need full React control, opt into custom UI mode:
+
+```json
+{
+  "ui": {
+    "mode": "custom",
+    "entry": "ui/index.html"
+  }
+}
+```
+
+Then create a full React app in `ui/`:
+
+```typescript
+// ui/src/App.tsx
+import { useIrisApp, IrisAppProvider } from '@iris/app-sdk/react';
+
+function App() {
+  return (
+    <IrisAppProvider>
+      <CustomUI />
+    </IrisAppProvider>
+  );
+}
+
+function CustomUI() {
+  const { state, runTool, iris } = useIrisApp();
+
+  // Full React control
+  return (
+    <div>
+      <ThreeJSVisualization data={state.data} />
+      <button onClick={() => runTool('refresh')}>
+        Refresh
+      </button>
+    </div>
+  );
+}
+```
+
+**Custom UI Hooks:**
+
+```typescript
+import {
+  useIrisApp,      // Full app context
+  useAppState,     // Single state value
+  useRunTool,      // Tool execution
+  useIrisAI,       // AI access
+  useIrisFS,       // File system
+} from '@iris/app-sdk/react';
+
+function MyComponent() {
+  const [count, setCount] = useAppState('count');
+  const runTool = useRunTool();
+  const ai = useIrisAI();
+
+  // Use like regular React hooks
+}
+```
+
+## Error Handling
+
+### In Tools
+
+```typescript
+defineTool({
+  execute: async (args, ctx) => {
+    try {
+      const result = await riskyOperation(args);
+      return { success: true, data: result };
+    } catch (error) {
+      // Return error - don't throw
+      return { success: false, error: error.message };
+    }
+  },
+});
+```
+
+### In UI
+
+```typescript
+ui: (ctx) => {
+  const { error, isLoading, data } = ctx.state;
+
+  // Handle error states in UI
+  if (error) {
+    return Alert({ variant: 'error' }, error);
+  }
+
+  if (isLoading) {
+    return Stack({ align: 'center', padding: 24 }, [
+      Spinner({}),
+      Text({}, 'Loading...'),
+    ]);
+  }
+
+  return DataTable({ data });
+}
+```
+
+### Global Error Handler
+
+```typescript
+export default defineApp({
+  onError: async (ctx, error) => {
+    ctx.log.error('App error:', error);
+    ctx.state.lastError.set(error.message);
+
+    // Return true to indicate error was handled
+    // Return false or throw to propagate
+    return true;
+  },
+});
+```
+
+---
+
+*Next: [04-security-model.md](./04-security-model.md) - Security and permissions*
diff --git a/docs/apps-architecture/04-security-model.md b/docs/apps-architecture/04-security-model.md
new file mode 100644
index 0000000..87e7502
--- /dev/null
+++ b/docs/apps-architecture/04-security-model.md
@@ -0,0 +1,441 @@
+# Iris Apps: Security Model
+
+## Overview
+
+SDR (Server-Defined Rendering) dramatically simplifies security compared to traditional approaches. Because UI is rendered from a trusted component registry—not arbitrary JavaScript—we eliminate an entire class of client-side vulnerabilities.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                    SDR SECURITY ADVANTAGE                                │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  TRADITIONAL (iframe/JS)              SDR APPROACH                      │
+│                                                                          │
+│  ┌─────────────────────┐             ┌─────────────────────┐           │
+│  │  Untrusted JS       │             │  Component Tree     │           │
+│  │  Can do anything    │             │  (JSON data)        │           │
+│  │  XSS, data theft    │             │  Can only render    │           │
+│  │  Needs sandbox      │             │  trusted components │           │
+│  └─────────────────────┘             └─────────────────────┘           │
+│           │                                    │                        │
+│           ▼                                    ▼                        │
+│  ┌─────────────────────┐             ┌─────────────────────┐           │
+│  │  iframe sandbox     │             │  Direct render      │           │
+│  │  CSP headers        │             │  No sandbox needed  │           │
+│  │  postMessage only   │             │  Same context       │           │
+│  │  Performance cost   │             │  Fast & simple      │           │
+│  └─────────────────────┘             └─────────────────────┘           │
+│                                                                          │
+│  SDR: The UI can only do what the component registry allows             │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Security Zones
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         SECURITY ZONES                                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │  ZONE 1: Iris Core (Trusted)                                     │   │
+│  │                                                                   │   │
+│  │  • Full system access                                            │   │
+│  │  • Permission enforcement                                        │   │
+│  │  • App lifecycle management                                      │   │
+│  │  • API credentials storage                                       │   │
+│  │                                                                   │   │
+│  │  Access: Only Iris core code                                     │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │  ZONE 2: App Server (Permission-Gated)                           │   │
+│  │                                                                   │   │
+│  │  • App's server.ts code runs here                                │   │
+│  │  • Has declared permissions only                                 │   │
+│  │  • All platform access checked at runtime                        │   │
+│  │  • Can access state, tools, services                             │   │
+│  │                                                                   │   │
+│  │  Access: Via ctx.iris.* with permission checks                   │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+│  ┌─────────────────────────────────────────────────────────────────┐   │
+│  │  ZONE 3: SDR Renderer (Data-Only)                                │   │
+│  │                                                                   │   │
+│  │  • Receives JSON component trees                                 │   │
+│  │  • Renders using trusted @iris/ui components                     │   │
+│  │  • Cannot execute arbitrary code                                 │   │
+│  │  • Actions sent back to server for execution                     │   │
+│  │                                                                   │   │
+│  │  Access: Read-only rendering of data                             │   │
+│  └─────────────────────────────────────────────────────────────────┘   │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Permission System
+
+### Permission Declaration
+
+Apps declare required permissions in `app.json`:
+
+```json
+{
+  "permissions": [
+    "filesystem:read:$PROJECT",
+    "filesystem:write:$APP/data",
+    "network:api.example.com",
+    "ai:chat"
+  ]
+}
+```
+
+### Permission Categories
+
+| Category | Examples | Risk Level |
+|----------|----------|------------|
+| **filesystem** | `filesystem:read:$PROJECT` | Medium-High |
+| **network** | `network:localhost`, `network:*.api.com` | Medium |
+| **ai** | `ai:chat`, `ai:embed` | Medium (cost) |
+| **iris** | `iris:tools`, `iris:navigation` | Low-High |
+| **process** | `process:spawn:$APP` | High |
+
+### Permission Scopes
+
+| Scope | Resolves To |
+|-------|-------------|
+| `$PROJECT` | Current project directory |
+| `$APP` | App's own directory |
+| `$DATA` | App's data directory |
+| `$CONFIG` | App's config directory |
+| Domain glob | e.g., `*.example.com` |
+
+### Permission Reference
+
+#### Filesystem
+
+```
+filesystem:read              # Read any file (DANGEROUS)
+filesystem:read:$PROJECT     # Read within project only
+filesystem:read:$APP         # Read within app directory
+filesystem:write             # Write any file (DANGEROUS)
+filesystem:write:$PROJECT    # Write within project
+filesystem:write:$APP        # Write within app directory
+filesystem:write:$APP/data   # Write to specific subdirectory
+```
+
+#### Network
+
+```
+network:*                    # Any network access
+network:localhost            # Localhost only
+network:example.com          # Specific domain
+network:*.example.com        # Domain with subdomains
+```
+
+#### AI
+
+```
+ai:chat                      # Use chat completions
+ai:chat:limited              # Rate-limited chat
+ai:embed                     # Use embeddings
+```
+
+#### Iris Platform
+
+```
+iris:tools                   # Call built-in tools
+iris:tools:read              # Read-only tools only
+iris:navigation              # Navigate UI
+iris:notifications           # Show notifications
+iris:apps                    # Cross-app communication
+```
+
+#### Process
+
+```
+process:spawn                # Run any command (DANGEROUS)
+process:spawn:$APP           # Run commands in app dir only
+process:env                  # Access env variables
+process:env:PUBLIC_*         # Only PUBLIC_* vars
+```
+
+### Permission Enforcement
+
+```typescript
+// Every platform access checks permissions at runtime
+async function read(path: string, ctx: AppContext): Promise<string> {
+  const resolvedPath = resolvePath(path, ctx);
+  const permission = `filesystem:read:${resolvedPath}`;
+
+  if (!ctx.permissions.check(permission)) {
+    throw new PermissionDeniedError(permission);
+  }
+
+  return Bun.file(resolvedPath).text();
+}
+```
+
+## Trust Levels
+
+Apps have different trust levels based on their source:
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           TRUST LEVELS                                   │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  LEVEL 3: Development App (Highest Trust)                               │
+│  ├── Source: App being developed in current project                     │
+│  ├── Trust: User is the developer                                       │
+│  ├── Permissions: Can request any, granted interactively                │
+│  └── All source code visible                                            │
+│                                                                          │
+│  LEVEL 2: Verified App                                                   │
+│  ├── Source: Iris App Registry, verified publisher                      │
+│  ├── Trust: Signed by known entity                                      │
+│  ├── Permissions: Declared, approved at install                         │
+│  └── Automated security scanning                                        │
+│                                                                          │
+│  LEVEL 1: Community App                                                  │
+│  ├── Source: Iris App Registry, unverified                              │
+│  ├── Trust: User accepts risk                                           │
+│  ├── Permissions: Restricted by default                                 │
+│  └── Warning shown at install                                           │
+│                                                                          │
+│  LEVEL 0: Unknown App (Lowest Trust)                                    │
+│  ├── Source: Unknown URL or path                                        │
+│  ├── Trust: None                                                        │
+│  ├── Permissions: Minimal only                                          │
+│  └── Explicit user approval required                                    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## SDR Security Benefits
+
+### No Client-Side Code Execution
+
+Traditional apps run arbitrary JavaScript. SDR apps can only:
+
+1. Render components from the trusted registry
+2. Send actions back to the server
+3. Display data provided by the server
+
+```typescript
+// This UI tree is just data - no code runs on the client
+{
+  type: 'Button',
+  props: {
+    onPress: { $action: 'delete', args: { id: '123' } }
+  },
+  children: ['Delete']
+}
+
+// The client renders a Button component
+// When pressed, it sends { action: 'delete', args: { id: '123' } } to server
+// Server decides whether to execute based on permissions
+```
+
+### Actions Are Validated
+
+Every action from the UI goes through the server:
+
+```typescript
+// Client sends action
+{ action: 'delete', args: { id: '123' } }
+
+// Server validates and executes
+async function handleAction(action: Action, ctx: AppContext) {
+  // Check if action exists
+  const tool = ctx.tools.get(action.name);
+  if (!tool) {
+    throw new Error(`Unknown action: ${action.name}`);
+  }
+
+  // Validate arguments
+  const parsed = tool.parameters.safeParse(action.args);
+  if (!parsed.success) {
+    throw new ValidationError(parsed.error);
+  }
+
+  // Execute with permission checks
+  return tool.execute(parsed.data, ctx);
+}
+```
+
+### Component Registry is Trusted
+
+The `@iris/ui` component registry is:
+- Maintained by Iris team
+- Audited for security
+- Cannot execute arbitrary code
+- Cannot access system resources directly
+
+```typescript
+// Components can only do what they're designed to do
+function Button({ onPress, children }) {
+  return (
+    <button
+      onClick={() => {
+        // onPress is NOT a function - it's an action descriptor
+        // { $action: 'name', args: {...} }
+        // We send it to the server, not execute it locally
+        sendActionToServer(onPress);
+      }}
+    >
+      {children}
+    </button>
+  );
+}
+```
+
+## Custom UI Security
+
+When apps opt into custom UI mode, additional security measures apply:
+
+### Sandboxing Options
+
+```typescript
+// App manifest
+{
+  "ui": {
+    "mode": "custom",
+    "entry": "ui/index.html",
+    "sandbox": "strict"  // or "relaxed"
+  }
+}
+```
+
+**Strict (default):**
+- Shadow DOM isolation
+- CSP headers restricting scripts/styles
+- No direct DOM access to parent
+
+**Relaxed:**
+- Same React context as Iris
+- Shared state directly accessible
+- Trust the app developer
+
+### Bridge Security
+
+Custom UI communicates via a bridge:
+
+```typescript
+// All messages validated
+class SecureBridge {
+  handleMessage(message: unknown) {
+    // Validate structure
+    const validated = BridgeMessageSchema.parse(message);
+
+    // Check permissions for requested action
+    if (validated.type === 'iris:action') {
+      this.checkPermission(validated.action);
+    }
+
+    // Rate limit
+    if (!this.rateLimiter.allow()) {
+      throw new RateLimitError();
+    }
+
+    // Process message
+    this.process(validated);
+  }
+}
+```
+
+## Audit Logging
+
+All sensitive operations are logged:
+
+```typescript
+interface AuditEvent {
+  timestamp: number;
+  appId: string;
+  action: string;
+  target?: string;
+  allowed: boolean;
+  result?: 'success' | 'error';
+}
+
+// Example log
+{
+  timestamp: 1705234567890,
+  appId: 'database-explorer',
+  action: 'filesystem:read',
+  target: '/project/data.db',
+  allowed: true,
+  result: 'success'
+}
+```
+
+### Audit UI
+
+Users can review what apps have accessed:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  Audit Log: database-explorer                                    │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  Today                                                          │
+│  ───────                                                        │
+│  10:32  ✓ filesystem:read   /project/data.db                   │
+│  10:32  ✓ ai:chat           3 messages                         │
+│  10:31  ✓ filesystem:read   /project/schema.sql                │
+│                                                                  │
+│  Yesterday                                                      │
+│  ─────────                                                      │
+│  15:45  ✗ filesystem:read   /etc/passwd (DENIED)               │
+│  15:44  ✓ network:fetch     api.example.com/users              │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Rate Limiting
+
+Prevent resource abuse:
+
+```typescript
+const rateLimits = {
+  'ai:chat': { requests: 100, window: '1h' },
+  'filesystem:read': { requests: 1000, window: '1m' },
+  'network:fetch': { requests: 100, window: '1m' },
+};
+```
+
+## Development Mode Security
+
+During development, apps get relaxed security:
+
+```typescript
+const developmentDefaults = {
+  // Implicit permissions (no declaration needed)
+  implicit: [
+    'filesystem:read:$PROJECT',
+    'filesystem:write:$PROJECT',
+    'network:localhost',
+    'iris:navigation',
+    'iris:notifications',
+  ],
+
+  // Prompted interactively
+  prompted: [
+    'network:*',
+    'ai:*',
+    'process:spawn',
+  ],
+
+  // Always denied
+  denied: [
+    'filesystem:read:/',
+    'process:env:*_SECRET',
+    'process:env:*_KEY',
+  ],
+};
+```
+
+---
+
+*Next: [05-resilience.md](./05-resilience.md) - Error handling and recovery*
diff --git a/docs/apps-architecture/05-resilience.md b/docs/apps-architecture/05-resilience.md
new file mode 100644
index 0000000..999f93c
--- /dev/null
+++ b/docs/apps-architecture/05-resilience.md
@@ -0,0 +1,362 @@
+# Iris Apps: Resilience & Error Handling
+
+## Philosophy
+
+> **Broken code is normal. Broken experiences are not.**
+
+During development, apps will constantly be in broken states. SDR makes error handling simpler because all logic runs on the server—we have full control over error recovery.
+
+## Error Categories
+
+| Category | Example | Handling |
+|----------|---------|----------|
+| **Server Load** | Syntax error in server.ts | Show error overlay, wait for fix |
+| **Server Runtime** | Tool throws exception | Catch, show error in UI, don't crash |
+| **UI Generation** | ui() returns invalid tree | Render valid parts, highlight broken |
+| **Action Execution** | User action fails | Return error result, show message |
+
+## SDR Error Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         SDR ERROR HANDLING                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│   1. Server Error (server.ts won't load)                                │
+│      ┌────────────────────────────────────────────────────────┐        │
+│      │  Show full error overlay:                               │        │
+│      │  • Syntax error message                                 │        │
+│      │  • File + line number                                   │        │
+│      │  • "Open in Editor" button                              │        │
+│      │  • Auto-reload when file changes                        │        │
+│      └────────────────────────────────────────────────────────┘        │
+│                                                                          │
+│   2. UI Generation Error (ui() throws)                                  │
+│      ┌────────────────────────────────────────────────────────┐        │
+│      │  Show last valid UI + error banner:                     │        │
+│      │  • Error message at top                                 │        │
+│      │  • Stack trace in details                               │        │
+│      │  • App still partially usable                           │        │
+│      └────────────────────────────────────────────────────────┘        │
+│                                                                          │
+│   3. Invalid UI Tree (ui() returns bad data)                            │
+│      ┌────────────────────────────────────────────────────────┐        │
+│      │  Validate tree, render valid parts:                     │        │
+│      │  • Unknown components → show placeholder                │        │
+│      │  • Invalid props → use defaults                         │        │
+│      │  • Show warnings in dev tools                           │        │
+│      └────────────────────────────────────────────────────────┘        │
+│                                                                          │
+│   4. Action Error (tool execution fails)                                │
+│      ┌────────────────────────────────────────────────────────┐        │
+│      │  Return error to UI, let app handle:                    │        │
+│      │  • { success: false, error: "message" }                 │        │
+│      │  • App shows error via Alert component                  │        │
+│      │  • No crash, no white screen                            │        │
+│      └────────────────────────────────────────────────────────┘        │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## Server Load Errors
+
+When server.ts fails to load (syntax error, missing import, etc.):
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  ⚠️ App Error: database-explorer                                 │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  SyntaxError: Unexpected token '}' at line 42                   │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────┐    │
+│  │  40 │   const result = await db.query(sql);            │    │
+│  │  41 │   return { success: true, data: result           │    │
+│  │  42 │   }  // ← Missing comma before this line         │    │
+│  │  43 │ });                                              │    │
+│  └────────────────────────────────────────────────────────┘    │
+│                                                                  │
+│  server.ts:42:3                                                 │
+│                                                                  │
+│  [Open in Editor]  [Retry]                                      │
+│                                                                  │
+│  Watching for changes...                                        │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Behavior:**
+- App shows error overlay instead of UI
+- File watcher active—auto-retries on save
+- User can click to open file at error location
+
+## UI Generation Errors
+
+When ui() throws during rendering:
+
+```typescript
+// This will throw
+ui: (ctx) => {
+  const user = ctx.state.user.get();
+  return Stack({}, [
+    Text({}, user.name),  // Error if user is null!
+  ]);
+}
+```
+
+**Error Display:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  ⚠️ UI Error                                        [Dismiss]   │
+│  TypeError: Cannot read property 'name' of null                 │
+│  at ui (server.ts:45)                                          │
+└─────────────────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────────┐
+│                                                                  │
+│  [Last valid UI rendered here]                                  │
+│                                                                  │
+│  User can still interact with existing UI                       │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Fix in Code:**
+
+```typescript
+ui: (ctx) => {
+  const user = ctx.state.user.get();
+
+  // Guard against null
+  if (!user) {
+    return Stack({ padding: 24 }, [
+      Text({}, 'Please select a user'),
+    ]);
+  }
+
+  return Stack({}, [
+    Text({}, user.name),
+  ]);
+}
+```
+
+## Invalid UI Tree
+
+When ui() returns invalid data:
+
+```typescript
+// Returns unknown component
+ui: (ctx) => {
+  return Stack({}, [
+    MyCustomThing({ data: 'test' }),  // Not in registry!
+  ]);
+}
+```
+
+**Rendered:**
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  [Valid Stack renders]                                          │
+│                                                                  │
+│  ┌────────────────────────────────────────────────────────┐    │
+│  │  ⚠️ Unknown component: MyCustomThing                    │    │
+│  │  This component is not in the @iris/ui registry        │    │
+│  └────────────────────────────────────────────────────────┘    │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+**Console Warning:**
+```
+[Iris] Unknown component "MyCustomThing" at path root.children[0]
+Available components: Stack, Row, Text, Button, ...
+```
+
+## Action Execution Errors
+
+Tools should return errors, not throw:
+
+```typescript
+// GOOD: Return error state
+defineTool({
+  name: 'query',
+  execute: async (args, ctx) => {
+    try {
+      const result = await db.query(args.sql);
+      return { success: true, data: result };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  },
+});
+
+// Handle in UI
+ui: (ctx) => {
+  const { error, results } = ctx.state;
+
+  return Stack({}, [
+    // Show error if present
+    error && Alert({ variant: 'error' }, error),
+
+    // Results
+    results && DataTable({ data: results }),
+  ]);
+}
+```
+
+## Hot Reload Resilience
+
+When code changes, state is preserved:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                      HOT RELOAD FLOW                             │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  1. File change detected                                        │
+│                                                                  │
+│  2. Snapshot current state                                      │
+│     { count: 5, items: [...], selectedId: 'abc' }              │
+│                                                                  │
+│  3. Unload old module                                           │
+│                                                                  │
+│  4. Load new module                                             │
+│     ├── Success → Continue                                      │
+│     └── Error → Show overlay, keep old module running           │
+│                                                                  │
+│  5. Restore state                                               │
+│     ├── State exists in new module → Restore                   │
+│     └── State removed → Drop (with warning)                     │
+│                                                                  │
+│  6. Re-run ui() with restored state                             │
+│                                                                  │
+│  7. Push new UI to client                                       │
+│     (Client sees instant update, state preserved)               │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### State Migration
+
+If state shape changes:
+
+```typescript
+export default defineApp({
+  state: {
+    // Renamed from 'count' to 'counter'
+    counter: state(0),
+  },
+
+  onReload: async (ctx, previousState) => {
+    // Migrate state
+    if ('count' in previousState) {
+      ctx.state.counter.set(previousState.count);
+    }
+  },
+});
+```
+
+## Global Error Handler
+
+Catch errors at the app level:
+
+```typescript
+export default defineApp({
+  onError: async (ctx, error) => {
+    // Log error
+    ctx.log.error('App error:', error);
+
+    // Update UI state
+    ctx.state.lastError.set(error.message);
+
+    // Return true = error handled, don't propagate
+    // Return false = propagate to Iris error overlay
+    return true;
+  },
+});
+```
+
+## Service Resilience
+
+Services restart automatically on failure:
+
+```typescript
+services: {
+  database: {
+    start: async (ctx) => {
+      return new Database(ctx.getConfig('dbPath'));
+    },
+    stop: async (db) => {
+      await db.close();
+    },
+
+    // Restart on crash
+    restartOnCrash: true,
+    maxRestarts: 5,
+    restartDelay: 1000,  // Exponential backoff base
+
+    // Health check
+    healthCheck: async (db) => {
+      await db.query('SELECT 1');
+      return true;
+    },
+    healthInterval: 30000,
+  },
+}
+```
+
+## Error Display Components
+
+Use built-in components for error states:
+
+```typescript
+import { Alert, Spinner, Stack, Text, Button } from '@iris/ui';
+
+ui: (ctx) => {
+  const { isLoading, error, data } = ctx.state;
+
+  // Loading state
+  if (isLoading) {
+    return Stack({ align: 'center', justify: 'center', minHeight: 200 }, [
+      Spinner({ size: 'lg' }),
+      Text({ color: 'muted' }, 'Loading...'),
+    ]);
+  }
+
+  // Error state
+  if (error) {
+    return Stack({ padding: 16, gap: 12 }, [
+      Alert({ variant: 'error', title: 'Error' }, error),
+      Button({
+        onPress: () => ctx.runTool('retry'),
+        variant: 'outline',
+      }, 'Retry'),
+    ]);
+  }
+
+  // Success state
+  return DataTable({ data });
+}
+```
+
+## Console Logging
+
+Apps can log to the Iris console:
+
+```typescript
+// In tools or lifecycle
+ctx.log.debug('Debug info');
+ctx.log.info('Something happened');
+ctx.log.warn('Warning');
+ctx.log.error('Error occurred', error);
+
+// Logs appear in:
+// 1. Iris console panel
+// 2. Server terminal
+// 3. Browser dev tools (in dev mode)
+```
+
+---
+
+*Next: [06-protocol.md](./06-protocol.md) - Communication protocols*
diff --git a/docs/apps-architecture/06-protocol.md b/docs/apps-architecture/06-protocol.md
new file mode 100644
index 0000000..ff6f5f5
--- /dev/null
+++ b/docs/apps-architecture/06-protocol.md
@@ -0,0 +1,636 @@
+# Iris Apps: Communication Protocols
+
+## Overview
+
+With Server-Defined Rendering (SDR), communication is simpler than traditional approaches. The server sends UI trees; the client renders them. Actions flow back to the server.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                     COMMUNICATION CHANNELS                               │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  ┌──────────┐         ┌──────────┐         ┌──────────┐                │
+│  │  Iris    │◄───────►│   App    │◄───────►│  SDR     │                │
+│  │  Core    │   WS    │  Server  │   WS    │ Renderer │                │
+│  └──────────┘         └──────────┘         └──────────┘                │
+│       │                    │                    │                       │
+│       │                    │                    │                       │
+│       ▼                    ▼                    ▼                       │
+│  ┌──────────┐         ┌──────────┐         ┌──────────┐                │
+│  │  Other   │         │ External │         │  User    │                │
+│  │  Apps    │         │ Services │         │ Actions  │                │
+│  └──────────┘         └──────────┘         └──────────┘                │
+│                                                                          │
+│  Primary Flow:                                                          │
+│  1. App server generates ui() → Component tree                         │
+│  2. Tree sent via WebSocket → Client                                   │
+│  3. SDR Renderer maps tree → Native components                         │
+│  4. User actions → Server → State change → New tree                    │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+## SDR Protocol (Server ↔ Client)
+
+### Message Format
+
+All messages use a simple JSON envelope:
+
+```typescript
+interface SDRMessage {
+  // Message identity
+  id: string;
+  type: SDRMessageType;
+
+  // Payload
+  payload: unknown;
+
+  // Metadata
+  timestamp: number;
+  correlationId?: string;  // Links request/response
+}
+
+type SDRMessageType =
+  // UI synchronization
+  | 'ui:sync'        // Full UI tree (on connect, after reload)
+  | 'ui:patch'       // Partial UI update (optimized)
+
+  // State
+  | 'state:sync'     // Full state sync
+  | 'state:update'   // Single state update
+
+  // Actions (from client)
+  | 'action:call'    // User triggered action
+  | 'action:result'  // Action result
+
+  // Lifecycle
+  | 'app:ready'      // App initialized
+  | 'app:reload'     // Hot reload triggered
+  | 'app:error'      // App error occurred
+
+  // Input events
+  | 'input:change'   // Form input changed
+  | 'input:submit'   // Form submitted
+;
+```
+
+### UI Sync Flow
+
+The primary communication pattern:
+
+```
+┌──────────┐                              ┌──────────┐
+│   App    │                              │   SDR    │
+│  Server  │                              │ Renderer │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │  UI:SYNC (on connect)                   │
+     │  {                                      │
+     │    type: "ui:sync",                     │
+     │    payload: {                           │
+     │      tree: {                            │
+     │        $: "component",                  │
+     │        type: "Stack",                   │
+     │        props: { padding: 16 },          │
+     │        children: [                      │
+     │          { type: "Text", ... },         │
+     │          { type: "Button", ... }        │
+     │        ]                                │
+     │      },                                 │
+     │      state: {                           │
+     │        count: 0,                        │
+     │        items: []                        │
+     │      }                                  │
+     │    }                                    │
+     │  }                                      │
+     │────────────────────────────────────────►│
+     │                                         │
+     │                                         │  Render tree
+     │                                         │  using registry
+     │                                         │
+```
+
+### Action Flow
+
+When user interacts with the UI:
+
+```
+┌──────────┐                              ┌──────────┐
+│   App    │                              │   SDR    │
+│  Server  │                              │ Renderer │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │                            User clicks  │
+     │                            Button       │
+     │                                         │
+     │  ACTION:CALL                            │
+     │  {                                      │
+     │    type: "action:call",                 │
+     │    id: "act-123",                       │
+     │    payload: {                           │
+     │      action: "increment",               │
+     │      args: { amount: 1 }                │
+     │    }                                    │
+     │  }                                      │
+     │◄────────────────────────────────────────│
+     │                                         │
+     │  Execute tool                           │
+     │  Update state                           │
+     │  Re-run ui()                            │
+     │                                         │
+     │  UI:SYNC (new tree)                     │
+     │  {                                      │
+     │    payload: {                           │
+     │      tree: { ... },                     │
+     │      state: { count: 1 }                │
+     │    }                                    │
+     │  }                                      │
+     │────────────────────────────────────────►│
+     │                                         │
+     │                                         │  Diff & update
+     │                                         │
+```
+
+### State Updates (Optimistic)
+
+For responsive UIs, state can update optimistically:
+
+```
+┌──────────┐                              ┌──────────┐
+│   App    │                              │   SDR    │
+│  Server  │                              │ Renderer │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │                            User types   │
+     │                            in Input     │
+     │                                         │
+     │  INPUT:CHANGE                           │
+     │  {                                      │
+     │    type: "input:change",                │
+     │    payload: {                           │
+     │      path: "query",                     │
+     │      value: "SELECT *"                  │
+     │    }                                    │
+     │  }                                      │
+     │◄────────────────────────────────────────│
+     │                                         │
+     │  STATE:UPDATE (confirmation)            │
+     │  {                                      │
+     │    type: "state:update",                │
+     │    payload: {                           │
+     │      key: "query",                      │
+     │      value: "SELECT *"                  │
+     │    }                                    │
+     │  }                                      │
+     │────────────────────────────────────────►│
+     │                                         │
+     │  (UI already shows value - no flicker)  │
+     │                                         │
+```
+
+### Component Tree Structure
+
+The UI tree is a JSON representation of components:
+
+```typescript
+interface ComponentNode {
+  // Marker for component nodes
+  $: 'component';
+
+  // Component type (from registry)
+  type: string;
+
+  // Props passed to component
+  props: Record<string, PropValue>;
+
+  // Children (text, nodes, or mixed)
+  children?: UIChild[];
+
+  // Unique key for list diffing
+  key?: string;
+}
+
+type UIChild = string | number | boolean | null | ComponentNode;
+
+type PropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | PropValue[]
+  | { [key: string]: PropValue }
+  | ActionDescriptor;
+
+interface ActionDescriptor {
+  $action: string;      // Tool/action name
+  args?: unknown;       // Arguments
+  optimistic?: unknown; // Optimistic state update
+}
+```
+
+Example tree:
+
+```json
+{
+  "$": "component",
+  "type": "Stack",
+  "props": { "padding": 16, "gap": 12 },
+  "children": [
+    {
+      "$": "component",
+      "type": "Text",
+      "props": { "size": "2xl", "weight": "bold" },
+      "children": ["Counter: 5"]
+    },
+    {
+      "$": "component",
+      "type": "Button",
+      "props": {
+        "variant": "primary",
+        "onPress": { "$action": "increment", "args": { "amount": 1 } }
+      },
+      "children": ["+1"]
+    }
+  ]
+}
+```
+
+## Internal RPC Protocol (Iris ↔ App Server)
+
+For Iris platform access (AI, filesystem, tools):
+
+```typescript
+interface RPCMessage {
+  id: string;
+  type: 'request' | 'response' | 'event';
+
+  // For requests
+  method?: string;
+  params?: unknown;
+
+  // For responses
+  result?: unknown;
+  error?: RPCError;
+
+  // For events
+  event?: string;
+  data?: unknown;
+
+  correlationId?: string;
+  timestamp: number;
+}
+```
+
+### Method Namespaces
+
+```
+iris:*             Iris platform access
+  iris:ai:chat
+  iris:ai:embed
+  iris:fs:read
+  iris:fs:write
+  iris:fs:list
+  iris:tools:call
+  iris:navigate
+  iris:notify
+
+lifecycle:*        App lifecycle
+  lifecycle:activate
+  lifecycle:deactivate
+  lifecycle:reload
+
+service:*          Service management
+  service:start
+  service:stop
+  service:status
+
+config:*           Configuration
+  config:get
+  config:set
+```
+
+### Example: AI Chat Call
+
+```
+┌──────────┐                              ┌──────────┐
+│   App    │                              │   Iris   │
+│  Server  │                              │   Core   │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │  REQUEST                                │
+     │  {                                      │
+     │    id: "rpc-456",                       │
+     │    type: "request",                     │
+     │    method: "iris:ai:chat",              │
+     │    params: {                            │
+     │      messages: [                        │
+     │        { role: "user", content: "..." } │
+     │      ],                                 │
+     │      model: "claude-sonnet"             │
+     │    }                                    │
+     │  }                                      │
+     │────────────────────────────────────────►│
+     │                                         │
+     │                         Check permission│
+     │                         Execute AI call │
+     │                                         │
+     │  RESPONSE                               │
+     │  {                                      │
+     │    type: "response",                    │
+     │    correlationId: "rpc-456",            │
+     │    result: {                            │
+     │      content: "Here's the answer...",   │
+     │      usage: { tokens: 150 }             │
+     │    }                                    │
+     │  }                                      │
+     │◄────────────────────────────────────────│
+     │                                         │
+```
+
+## Custom UI Bridge Protocol (iframe mode)
+
+For apps using custom UI mode (the escape hatch), communication uses postMessage:
+
+```typescript
+interface BridgeMessage {
+  protocol: 'iris-bridge';
+  version: 1;
+  type: BridgeMessageType;
+  id?: string;
+  payload: unknown;
+}
+
+type BridgeMessageType =
+  | 'init'          // Shell → iframe: Initialize
+  | 'ready'         // iframe → Shell: Ready
+  | 'state:sync'    // Shell → iframe: State sync
+  | 'state:update'  // Shell → iframe: State change
+  | 'state:set'     // iframe → Shell: Set state
+  | 'action:call'   // iframe → Shell: Call tool
+  | 'action:result' // Shell → iframe: Tool result
+  | 'theme:change'  // Shell → iframe: Theme changed
+;
+```
+
+### Bridge Initialization
+
+```
+┌──────────┐                              ┌──────────┐
+│  Shell   │                              │  iframe  │
+│ (parent) │                              │  (app)   │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │  INIT                                   │
+     │  {                                      │
+     │    type: "init",                        │
+     │    payload: {                           │
+     │      appId: "my-app",                   │
+     │      projectId: "proj-123",             │
+     │      state: { count: 0 },               │
+     │      theme: "dark",                     │
+     │      config: { ... }                    │
+     │    }                                    │
+     │  }                                      │
+     │────────────────────────────────────────►│
+     │                                         │
+     │                                         │  Initialize
+     │                                         │  React app
+     │                                         │
+     │  READY                                  │
+     │◄────────────────────────────────────────│
+     │                                         │
+```
+
+### Security for Bridge
+
+```typescript
+class SecureBridge {
+  private allowedOrigin: string;
+
+  constructor(iframe: HTMLIFrameElement) {
+    this.allowedOrigin = new URL(iframe.src).origin;
+    window.addEventListener('message', this.handleMessage);
+  }
+
+  private handleMessage = (event: MessageEvent) => {
+    // Verify origin
+    if (event.origin !== this.allowedOrigin) {
+      console.warn('Rejected message from:', event.origin);
+      return;
+    }
+
+    // Validate message structure
+    if (!this.isValidBridgeMessage(event.data)) {
+      return;
+    }
+
+    this.process(event.data);
+  };
+
+  send(message: BridgeMessage): void {
+    this.iframe.contentWindow?.postMessage(
+      { protocol: 'iris-bridge', version: 1, ...message },
+      this.allowedOrigin
+    );
+  }
+}
+```
+
+## Hot Reload Protocol
+
+### Server Module Reload (SDR)
+
+```
+┌──────────┐     ┌──────────┐     ┌──────────┐
+│  Bun FS  │     │   App    │     │   SDR    │
+│  Watcher │     │  Server  │     │ Renderer │
+└────┬─────┘     └────┬─────┘     └────┬─────┘
+     │                │                │
+     │  File change   │                │
+     │───────────────►│                │
+     │                │                │
+     │                │  1. Snapshot   │
+     │                │     state      │
+     │                │                │
+     │                │  2. Unload     │
+     │                │     module     │
+     │                │                │
+     │                │  3. Load new   │
+     │                │     module     │
+     │                │                │
+     │                │  4. Restore    │
+     │                │     state      │
+     │                │                │
+     │                │  5. Run ui()   │
+     │                │                │
+     │                │  UI:SYNC       │
+     │                │───────────────►│
+     │                │                │
+     │                │                │  Re-render
+     │                │                │  (instant!)
+     │                │                │
+```
+
+### State Migration
+
+If state shape changes during hot reload:
+
+```typescript
+export default defineApp({
+  state: {
+    // Renamed from 'count' to 'counter'
+    counter: state(0),
+  },
+
+  onReload: async (ctx, previousState) => {
+    // Migrate old state
+    if ('count' in previousState) {
+      ctx.state.counter.set(previousState.count);
+    }
+  },
+});
+```
+
+## WebSocket Connection Management
+
+### Connection States
+
+```typescript
+type ConnectionState =
+  | 'connecting'
+  | 'connected'
+  | 'disconnected'
+  | 'reconnecting';
+
+class AppConnection {
+  private state: ConnectionState = 'disconnected';
+  private reconnectAttempts = 0;
+
+  connect(): void {
+    this.state = 'connecting';
+    this.ws = new WebSocket(this.url);
+
+    this.ws.onopen = () => {
+      this.state = 'connected';
+      this.reconnectAttempts = 0;
+      this.requestFullSync();
+    };
+
+    this.ws.onclose = (event) => {
+      if (event.code !== 1000) {
+        this.scheduleReconnect();
+      }
+    };
+  }
+
+  private scheduleReconnect(): void {
+    this.state = 'reconnecting';
+    const delay = Math.min(
+      1000 * Math.pow(2, this.reconnectAttempts),
+      30000
+    );
+    setTimeout(() => this.connect(), delay);
+    this.reconnectAttempts++;
+  }
+}
+```
+
+### Heartbeat
+
+```
+┌──────────┐                              ┌──────────┐
+│  Client  │                              │  Server  │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │  PING (every 30s)                       │
+     │  { type: "ping" }                       │
+     │────────────────────────────────────────►│
+     │                                         │
+     │  PONG                                   │
+     │  { type: "pong" }                       │
+     │◄────────────────────────────────────────│
+     │                                         │
+```
+
+## Error Protocol
+
+### Error Message Format
+
+```typescript
+interface ErrorMessage {
+  type: 'app:error';
+  payload: {
+    category: 'server_load' | 'ui_generation' | 'action' | 'runtime';
+    message: string;
+    stack?: string;
+    file?: string;
+    line?: number;
+    column?: number;
+    recoverable: boolean;
+    timestamp: number;
+  };
+}
+```
+
+### Error Flow
+
+```
+┌──────────┐                              ┌──────────┐
+│   App    │                              │   SDR    │
+│  Server  │                              │ Renderer │
+└────┬─────┘                              └────┬─────┘
+     │                                         │
+     │  ui() throws error                      │
+     │                                         │
+     │  APP:ERROR                              │
+     │  {                                      │
+     │    type: "app:error",                   │
+     │    payload: {                           │
+     │      category: "ui_generation",         │
+     │      message: "Cannot read 'name'...",  │
+     │      file: "server.ts",                 │
+     │      line: 45,                          │
+     │      recoverable: true                  │
+     │    }                                    │
+     │  }                                      │
+     │────────────────────────────────────────►│
+     │                                         │
+     │                                         │  Show error
+     │                                         │  overlay with
+     │                                         │  last valid UI
+     │                                         │
+```
+
+## Rate Limiting
+
+To prevent abuse, certain operations are rate-limited:
+
+```typescript
+const rateLimits: Record<string, RateLimit> = {
+  'iris:ai:chat': { requests: 100, window: '1h' },
+  'iris:fs:read': { requests: 1000, window: '1m' },
+  'iris:fs:write': { requests: 100, window: '1m' },
+  'ui:sync': { requests: 60, window: '1s' },  // Max 60 FPS
+};
+```
+
+Rate limit errors return:
+
+```typescript
+{
+  type: 'response',
+  error: {
+    code: -32008,
+    message: 'Rate limit exceeded',
+    data: {
+      limit: 100,
+      window: '1h',
+      resetAt: 1705234567890
+    }
+  }
+}
+```
+
+---
+
+*Next: [07-implementation-roadmap.md](./07-implementation-roadmap.md) - Implementation phases and milestones*
diff --git a/docs/apps-architecture/07-implementation-roadmap.md b/docs/apps-architecture/07-implementation-roadmap.md
new file mode 100644
index 0000000..f5ee8a6
--- /dev/null
+++ b/docs/apps-architecture/07-implementation-roadmap.md
@@ -0,0 +1,852 @@
+# Iris Apps: Implementation Roadmap
+
+## Overview
+
+This roadmap outlines a phased approach to implementing the Iris Apps system with Server-Defined Rendering (SDR). SDR simplifies the architecture significantly—most phases are smaller than they would be with an iframe-based approach.
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                       IMPLEMENTATION PHASES                              │
+├─────────────────────────────────────────────────────────────────────────┤
+│                                                                          │
+│  Phase 1: Foundation                                                     │
+│  ├── App manifest & loader                                              │
+│  ├── Basic app lifecycle                                                │
+│  └── SDR component registry                                             │
+│         │                                                                │
+│         ▼                                                                │
+│  Phase 2: SDR Core                                                       │
+│  ├── ui() function execution                                            │
+│  ├── Component tree rendering                                           │
+│  └── Action handlers                                                    │
+│         │                                                                │
+│         ▼                                                                │
+│  Phase 3: State & Tools                                                  │
+│  ├── Reactive state management                                          │
+│  ├── Tool registration & execution                                      │
+│  └── Hot reload with state preservation                                 │
+│         │                                                                │
+│         ▼                                                                │
+│  Phase 4: SDK & DX                                                       │
+│  ├── @iris/app-sdk package                                              │
+│  ├── @iris/ui component library                                         │
+│  └── Development tooling                                                │
+│         │                                                                │
+│         ▼                                                                │
+│  Phase 5: Platform Integration                                           │
+│  ├── Iris AI access                                                     │
+│  ├── Filesystem access                                                  │
+│  └── Permission system (VS Code-like)                                   │
+│         │                                                                │
+│         ▼                                                                │
+│  Phase 6: Production & Custom UI                                         │
+│  ├── Custom UI mode (iframe escape hatch)                               │
+│  ├── Mobile support (React Native)                                      │
+│  └── Standalone runtime & distribution                                  │
+│                                                                          │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 1: Foundation
+
+### Objective
+Get a basic app structure and component registry in place.
+
+### Deliverables
+
+#### 1.1 App Manifest Schema
+```typescript
+// src/apps/manifest.ts
+import { z } from 'zod';
+
+export const AppManifestSchema = z.object({
+  name: z.string().regex(/^[a-z0-9-]+$/),
+  displayName: z.string(),
+  version: z.string(),
+  description: z.string().optional(),
+  icon: z.string().optional(),
+
+  server: z.string().default('server.ts'),
+
+  // Optional: Custom UI mode (escape hatch)
+  ui: z.object({
+    mode: z.enum(['sdr', 'custom']).default('sdr'),
+    entry: z.string().optional(),  // For custom mode
+  }).optional(),
+
+  tools: z.array(z.object({
+    name: z.string(),
+    description: z.string(),
+  })).default([]),
+
+  permissions: z.array(z.string()).default([]),
+});
+
+export type AppManifest = z.infer<typeof AppManifestSchema>;
+```
+
+#### 1.2 Component Registry
+```typescript
+// src/apps/sdr/registry.ts
+import { Stack, Row, Text, Button, Input, ... } from '@iris/ui';
+
+export const componentRegistry: Record<string, ComponentType> = {
+  // Layout
+  Stack,
+  Row,
+  Box,
+  ScrollView,
+  Divider,
+
+  // Typography
+  Text,
+  Heading,
+  Code,
+  Link,
+
+  // Form
+  Button,
+  Input,
+  TextArea,
+  Select,
+  Checkbox,
+  Switch,
+
+  // Data display
+  DataTable,
+  List,
+  Card,
+  Badge,
+
+  // Feedback
+  Alert,
+  Spinner,
+  Progress,
+
+  // More...
+};
+
+export function getComponent(type: string): ComponentType | undefined {
+  return componentRegistry[type];
+}
+```
+
+#### 1.3 App Manager
+```typescript
+// src/apps/manager.ts
+export class AppManager {
+  private apps = new Map<string, ManagedApp>();
+
+  async discover(projectPath: string): Promise<DiscoveredApp[]> {
+    // Find app.json files in project
+  }
+
+  async load(appPath: string): Promise<ManagedApp> {
+    // Load manifest, validate, create runtime
+  }
+
+  async activate(appId: string): Promise<void> {
+    // Start app, run onActivate
+  }
+
+  get(appId: string): ManagedApp | undefined {
+    return this.apps.get(appId);
+  }
+}
+```
+
+#### 1.4 App Tab Type
+```typescript
+// webui/src/lib/tabs.ts
+interface AppTabData {
+  type: 'app';
+  projectId: string;
+  appId: string;
+  appName: string;
+}
+```
+
+### Milestone Criteria
+- [ ] Can create `app.json` in a project
+- [ ] Iris discovers app and shows in sidebar
+- [ ] Component registry has core components
+- [ ] Basic app lifecycle (load, activate, deactivate)
+
+---
+
+## Phase 2: SDR Core
+
+### Objective
+Implement the SDR rendering engine that turns ui() output into React components.
+
+### Deliverables
+
+#### 2.1 App Runtime (Server Side)
+```typescript
+// src/apps/runtime.ts
+export class AppRuntime {
+  private module: AppModule;
+  private context: AppContext;
+
+  async initialize(modulePath: string): Promise<void> {
+    this.module = await import(modulePath);
+    this.context = this.createContext();
+  }
+
+  generateUI(): ComponentTree {
+    // Call the app's ui() function
+    return this.module.default.ui(this.context);
+  }
+
+  handleAction(action: string, args: unknown): Promise<unknown> {
+    // Execute tool or state update
+  }
+}
+```
+
+#### 2.2 SDR Renderer (Client Side)
+```typescript
+// webui/src/components/apps/SDRRenderer.tsx
+import { componentRegistry } from '@iris/ui';
+
+interface SDRRendererProps {
+  tree: ComponentTree;
+  onAction: (action: string, args: unknown) => void;
+}
+
+export function SDRRenderer({ tree, onAction }: SDRRendererProps) {
+  return renderNode(tree, onAction);
+}
+
+function renderNode(node: UINode, onAction: ActionHandler): ReactNode {
+  // Primitive values
+  if (typeof node === 'string' || typeof node === 'number') {
+    return node;
+  }
+
+  if (node === null || node === undefined || node === false) {
+    return null;
+  }
+
+  // Component node
+  if (node.$ === 'component') {
+    const Component = componentRegistry[node.type];
+
+    if (!Component) {
+      return <UnknownComponent type={node.type} />;
+    }
+
+    // Transform action props
+    const props = transformProps(node.props, onAction);
+
+    // Render children
+    const children = node.children?.map((child, i) =>
+      renderNode(child, onAction)
+    );
+
+    return <Component key={node.key} {...props}>{children}</Component>;
+  }
+
+  return null;
+}
+```
+
+#### 2.3 Action Handler
+```typescript
+// webui/src/components/apps/AppHost.tsx
+export function AppHost({ app }: { app: AppInfo }) {
+  const [tree, setTree] = useState<ComponentTree | null>(null);
+  const ws = useWebSocket(app.wsUrl);
+
+  useEffect(() => {
+    ws.on('ui:sync', (payload) => {
+      setTree(payload.tree);
+    });
+  }, [ws]);
+
+  const handleAction = useCallback(async (action: string, args: unknown) => {
+    ws.send({
+      type: 'action:call',
+      payload: { action, args }
+    });
+  }, [ws]);
+
+  if (!tree) {
+    return <AppLoading />;
+  }
+
+  return <SDRRenderer tree={tree} onAction={handleAction} />;
+}
+```
+
+### Milestone Criteria
+- [ ] ui() function executes on server
+- [ ] Component tree renders in browser
+- [ ] Button clicks trigger actions
+- [ ] State changes cause UI re-render
+
+---
+
+## Phase 3: State & Tools
+
+### Objective
+Implement reactive state and tool system with hot reload.
+
+### Deliverables
+
+#### 3.1 Reactive State
+```typescript
+// src/apps/state.ts
+export function state<T>(initial: T, options?: StateOptions): StateHandle<T> {
+  let value = initial;
+  const listeners = new Set<Listener<T>>();
+
+  return {
+    get: () => value,
+    set: (newValue: T) => {
+      value = newValue;
+      listeners.forEach(l => l(value));
+    },
+    update: (updater: (prev: T) => T) => {
+      value = updater(value);
+      listeners.forEach(l => l(value));
+    },
+    subscribe: (listener: Listener<T>) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+  };
+}
+```
+
+#### 3.2 Tool Execution
+```typescript
+// src/apps/tools.ts
+export class ToolExecutor {
+  constructor(private runtime: AppRuntime) {}
+
+  async execute(name: string, args: unknown): Promise<ToolResult> {
+    const tool = this.runtime.tools.get(name);
+    if (!tool) {
+      return { success: false, error: `Unknown tool: ${name}` };
+    }
+
+    // Validate arguments
+    const parsed = tool.parameters.safeParse(args);
+    if (!parsed.success) {
+      return { success: false, error: formatZodError(parsed.error) };
+    }
+
+    // Execute
+    try {
+      const result = await tool.execute(parsed.data, this.runtime.context);
+      return { success: true, data: result };
+    } catch (error) {
+      return { success: false, error: error.message };
+    }
+  }
+}
+```
+
+#### 3.3 Hot Reload
+```typescript
+// src/apps/hot-reload.ts
+export class HotReloadManager {
+  async handleFileChange(appPath: string): Promise<void> {
+    const runtime = this.appManager.getRuntime(appPath);
+    if (!runtime) return;
+
+    // 1. Snapshot current state
+    const stateSnapshot = runtime.snapshotState();
+
+    // 2. Unload module (Bun cache invalidation)
+    delete require.cache[require.resolve(appPath)];
+
+    // 3. Reload module
+    try {
+      await runtime.reload();
+
+      // 4. Restore state
+      runtime.restoreState(stateSnapshot);
+
+      // 5. Re-run ui() and push to clients
+      const tree = runtime.generateUI();
+      runtime.broadcast({ type: 'ui:sync', payload: { tree } });
+
+    } catch (error) {
+      // Send error to client, keep old module running
+      runtime.broadcast({
+        type: 'app:error',
+        payload: {
+          category: 'server_load',
+          message: error.message,
+          recoverable: true,
+        }
+      });
+    }
+  }
+}
+```
+
+### Milestone Criteria
+- [ ] State persists across interactions
+- [ ] Tools can be defined and called
+- [ ] File changes trigger instant UI updates
+- [ ] State preserved across hot reloads
+- [ ] Errors show overlay, don't crash
+
+---
+
+## Phase 4: SDK & Developer Experience
+
+### Objective
+Create polished SDK packages for app development.
+
+### Deliverables
+
+#### 4.1 @iris/app-sdk Package
+```
+packages/app-sdk/
+├── package.json
+├── src/
+│   ├── index.ts          # Main exports
+│   ├── app.ts            # defineApp
+│   ├── tool.ts           # defineTool
+│   ├── state.ts          # state, computed, query
+│   └── context.ts        # Type definitions
+└── tsconfig.json
+```
+
+```typescript
+// packages/app-sdk/src/index.ts
+export { defineApp } from './app';
+export { defineTool } from './tool';
+export { state, computed, query } from './state';
+export type {
+  AppContext,
+  ToolContext,
+  StateHandle,
+  AppDefinition,
+} from './context';
+```
+
+#### 4.2 @iris/ui Package
+```
+packages/ui/
+├── package.json
+├── src/
+│   ├── index.ts          # All component exports
+│   ├── registry.ts       # Component registry
+│   ├── components/
+│   │   ├── layout/       # Stack, Row, Box, etc.
+│   │   ├── typography/   # Text, Heading, Code
+│   │   ├── form/         # Button, Input, Select
+│   │   ├── data/         # DataTable, List, Card
+│   │   └── feedback/     # Alert, Spinner, Progress
+│   └── native/           # React Native variants
+└── tsconfig.json
+```
+
+```typescript
+// packages/ui/src/index.ts
+// Layout
+export { Stack, Row, Box, ScrollView, Divider } from './components/layout';
+
+// Typography
+export { Text, Heading, Code, Link } from './components/typography';
+
+// Form
+export { Button, Input, TextArea, Select, Checkbox, Switch } from './components/form';
+
+// Data
+export { DataTable, List, Card, Badge, Avatar } from './components/data';
+
+// Feedback
+export { Alert, Spinner, Progress, Toast } from './components/feedback';
+
+// Specialized
+export { CodeEditor, Terminal, FileTree, Markdown } from './components/specialized';
+```
+
+#### 4.3 CLI Commands
+```bash
+# Create new app
+iris app create my-app
+
+# Start development with hot reload
+iris app dev
+
+# Validate app
+iris app validate
+```
+
+### Milestone Criteria
+- [ ] SDK packages published (npm or local)
+- [ ] Apps can import from @iris/app-sdk and @iris/ui
+- [ ] Full TypeScript support with autocomplete
+- [ ] CLI commands work
+
+---
+
+## Phase 5: Platform Integration
+
+### Objective
+Enable apps to access Iris platform features with appropriate permissions.
+
+### Deliverables
+
+#### 5.1 Iris Context
+```typescript
+// Extension to AppContext
+interface IrisContext {
+  ai: {
+    chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse>;
+    embed(text: string | string[]): Promise<number[][]>;
+  };
+
+  fs: {
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    list(path: string): Promise<FileInfo[]>;
+  };
+
+  tools: {
+    call(name: string, args: unknown): Promise<ToolResult>;
+  };
+
+  navigate(path: string): void;
+  notify(message: string, options?: NotifyOptions): void;
+}
+```
+
+#### 5.2 Permission System (VS Code-like)
+
+Like VS Code extensions, permissions are declared and trusted at install/development time:
+
+```typescript
+// src/apps/permissions.ts
+export class PermissionManager {
+  private granted: Set<string>;
+
+  constructor(manifest: AppManifest, trustLevel: TrustLevel) {
+    this.granted = new Set(manifest.permissions);
+
+    // Development apps: automatically trust project permissions
+    if (trustLevel === 'development') {
+      this.granted.add('filesystem:read:$PROJECT');
+      this.granted.add('filesystem:write:$PROJECT');
+      this.granted.add('network:localhost');
+    }
+  }
+
+  check(permission: string): boolean {
+    // Exact match
+    if (this.granted.has(permission)) return true;
+
+    // Wildcard/scope matching
+    for (const granted of this.granted) {
+      if (this.matches(granted, permission)) return true;
+    }
+
+    return false;
+  }
+}
+
+// Trust levels (similar to VS Code workspace trust)
+type TrustLevel = 'development' | 'installed' | 'untrusted';
+```
+
+#### 5.3 AI Integration
+```typescript
+// src/apps/platform/ai.ts
+export class AppAIProvider {
+  constructor(
+    private appId: string,
+    private permissions: PermissionManager
+  ) {}
+
+  async chat(messages: Message[], options?: ChatOptions): Promise<ChatResponse> {
+    if (!this.permissions.check('ai:chat')) {
+      throw new Error('Permission denied: ai:chat');
+    }
+
+    return this.aiService.chat(messages, {
+      ...options,
+      metadata: { appId: this.appId },
+    });
+  }
+}
+```
+
+#### 5.4 Filesystem Integration
+```typescript
+// src/apps/platform/fs.ts
+export class AppFSProvider {
+  constructor(
+    private permissions: PermissionManager,
+    private projectPath: string
+  ) {}
+
+  async read(path: string): Promise<string> {
+    const resolved = this.resolvePath(path);
+
+    if (!this.permissions.check(`filesystem:read:${this.getScope(resolved)}`)) {
+      throw new Error(`Permission denied: filesystem:read:${resolved}`);
+    }
+
+    return Bun.file(resolved).text();
+  }
+
+  private resolvePath(path: string): string {
+    // Handle $PROJECT, $APP, etc.
+    // Prevent path traversal
+  }
+}
+```
+
+### Milestone Criteria
+- [ ] Apps can call AI models (with permission)
+- [ ] Apps can read/write files (within permitted scope)
+- [ ] Permission violations throw clear errors
+- [ ] Development apps have sensible defaults
+
+---
+
+## Phase 6: Production & Custom UI
+
+### Objective
+Add escape hatches, mobile support, and production features.
+
+### Deliverables
+
+#### 6.1 Custom UI Mode (iframe)
+For apps that need full React control (3D, canvas, complex interactions):
+
+```json
+{
+  "name": "3d-visualizer",
+  "ui": {
+    "mode": "custom",
+    "entry": "ui/index.html"
+  }
+}
+```
+
+```tsx
+// webui/src/components/apps/CustomAppHost.tsx
+export function CustomAppHost({ app }: { app: AppInfo }) {
+  const bridge = useBridge(app);
+
+  return (
+    <iframe
+      src={app.uiUrl}
+      sandbox="allow-scripts allow-same-origin"
+      onLoad={() => bridge.init()}
+    />
+  );
+}
+```
+
+#### 6.2 Mobile Support (React Native)
+
+The SDR approach enables native mobile apps:
+
+```typescript
+// packages/ui/src/native/registry.ts
+import { View, Text, Pressable, ... } from 'react-native';
+
+// Same interface, native implementation
+export const nativeRegistry: Record<string, ComponentType> = {
+  Stack: ({ children, gap, padding, ...props }) => (
+    <View style={{ gap, padding, flexDirection: 'column' }} {...props}>
+      {children}
+    </View>
+  ),
+  Button: ({ onPress, children, variant }) => (
+    <Pressable onPress={onPress} style={buttonStyles[variant]}>
+      <Text>{children}</Text>
+    </Pressable>
+  ),
+  // ... same components, native rendering
+};
+```
+
+#### 6.3 Standalone Runtime
+```typescript
+// packages/app-sdk/src/standalone/index.ts
+export async function createStandaloneServer(options: StandaloneOptions) {
+  const app = await loadApp(options.appPath);
+
+  // Create minimal Iris context (no full IDE)
+  const ctx = createStandaloneContext({
+    ai: options.ai,  // Optional AI provider
+    fs: options.fs,  // Scoped filesystem
+  });
+
+  // Create HTTP server
+  const server = Bun.serve({
+    port: options.port,
+    fetch: async (req) => {
+      // Serve UI
+      if (req.url === '/') {
+        return new Response(renderToString(app.ui(ctx)), {
+          headers: { 'Content-Type': 'text/html' },
+        });
+      }
+
+      // Handle tool calls
+      if (req.url.startsWith('/api/')) {
+        return handleToolCall(req, app, ctx);
+      }
+    },
+    websocket: {
+      // Real-time updates
+    },
+  });
+
+  return server;
+}
+```
+
+#### 6.4 App Distribution
+```typescript
+// App registry for sharing
+interface AppRegistry {
+  publish(app: BuiltApp): Promise<void>;
+  search(query: string): Promise<AppInfo[]>;
+  install(projectId: string, appId: string): Promise<void>;
+}
+```
+
+### Milestone Criteria
+- [ ] Custom UI apps work in iframe
+- [ ] Component registry works on React Native
+- [ ] Apps can run standalone outside Iris
+- [ ] Apps can be packaged and shared
+
+---
+
+## Technical Dependencies
+
+### Per-Phase Dependencies
+
+```
+Phase 1: Foundation
+├── Zod (validation)
+├── Bun (module loading)
+└── Existing Iris infrastructure
+
+Phase 2: SDR Core
+├── Phase 1 complete
+├── React 19
+└── WebSocket infrastructure
+
+Phase 3: State & Tools
+├── Phase 2 complete
+├── Bun file watcher
+└── Existing tool patterns
+
+Phase 4: SDK & DX
+├── Phase 3 complete
+├── TypeScript 5
+└── Package publishing setup
+
+Phase 5: Platform Integration
+├── Phase 4 complete
+├── Existing Iris AI service
+└── Existing Iris filesystem
+
+Phase 6: Production
+├── Phase 5 complete
+├── React Native (optional)
+└── Distribution infrastructure
+```
+
+### New Packages
+
+| Package | Phase | Description |
+|---------|-------|-------------|
+| `@iris/app-sdk` | 4 | Core SDK for building apps |
+| `@iris/ui` | 4 | Cross-platform component library |
+| `@iris/app-sdk/standalone` | 6 | Standalone runtime |
+
+### Core Files to Create/Modify
+
+| Location | Phase | Purpose |
+|----------|-------|---------|
+| `src/apps/` | 1-3 | App management, runtime, state |
+| `packages/app-sdk/` | 4 | SDK package |
+| `packages/ui/` | 4 | UI component library |
+| `webui/src/components/apps/` | 2 | SDR renderer, app host |
+
+---
+
+## Risk Mitigation
+
+### Technical Risks
+
+| Risk | Mitigation |
+|------|------------|
+| Hot reload state corruption | Comprehensive testing, state validation |
+| Performance with complex UIs | Tree diffing, virtualization for lists |
+| Mobile compatibility | Test early, use proven RN patterns |
+| Custom UI security | iframe sandbox, origin validation |
+
+### Product Risks
+
+| Risk | Mitigation |
+|------|------------|
+| SDK too complex | Keep simple cases simple, progressive disclosure |
+| Breaking changes | Semantic versioning, migration guides |
+| Limited component set | Prioritize common needs, custom UI escape hatch |
+
+---
+
+## Success Metrics
+
+| Phase | Key Metric |
+|-------|------------|
+| Phase 1 | App discovered and appears in sidebar |
+| Phase 2 | "Hello World" renders via SDR |
+| Phase 3 | Counter app with hot reload works |
+| Phase 4 | External dev can build app with SDK |
+| Phase 5 | App uses AI to process data |
+| Phase 6 | App runs standalone on phone |
+
+---
+
+## Getting Started
+
+### Immediate Next Steps
+
+1. **Create directory structure**
+   ```bash
+   mkdir -p src/apps/{manager,runtime,sdr}
+   mkdir -p packages/{app-sdk,ui}/src
+   mkdir -p webui/src/components/apps
+   ```
+
+2. **Define manifest schema** (Phase 1.1)
+
+3. **Build component registry** (Phase 1.2)
+
+4. **Create SDRRenderer component** (Phase 2.2)
+
+5. **Wire up WebSocket** (Phase 2.3)
+
+### First Demo Target
+
+A counter app that:
+- Lives in `my-project/apps/counter/`
+- Has `app.json` + `server.ts`
+- Shows counter in Iris tab
+- +1 button works
+- Hot reloads on file save
+
+This proves SDR works before adding complexity.
+
+---
+
+*This roadmap is a living document. Update as we learn and iterate.*
diff --git a/docs/apps-architecture/README.md b/docs/apps-architecture/README.md
new file mode 100644
index 0000000..4caff09
--- /dev/null
+++ b/docs/apps-architecture/README.md
@@ -0,0 +1,234 @@
+# Iris Apps Architecture
+
+> **Building the future of AI-integrated application development**
+
+This documentation describes the architecture for **Iris Apps** — a revolutionary system where applications are developed inside the Iris IDE, expose tools to AI agents, run with full error resilience during development, and can be deployed standalone or shared with others.
+
+## Quick Links
+
+| Document | Description |
+|----------|-------------|
+| [00-vision.md](./00-vision.md) | The vision, philosophy, and "why" behind Iris Apps |
+| [01-architecture.md](./01-architecture.md) | System architecture with Server-Defined Rendering |
+| [02-app-model.md](./02-app-model.md) | App structure, lifecycle, and single-file apps |
+| [03-sdk-design.md](./03-sdk-design.md) | SDK APIs: defineApp, state, tools, @iris/ui |
+| [04-security-model.md](./04-security-model.md) | Permissions and SDR security benefits |
+| [05-resilience.md](./05-resilience.md) | Error handling and development experience |
+| [06-protocol.md](./06-protocol.md) | Communication protocols (SDR & bridge) |
+| [07-implementation-roadmap.md](./07-implementation-roadmap.md) | Phased implementation plan |
+
+## Core Concepts
+
+### What is an Iris App?
+
+An Iris App is a single-file application that:
+
+1. **Runs inside Iris** — As a tab in your project, with instant hot reload
+2. **Exposes tools to AI** — The agent can interact with your app's functionality
+3. **Handles errors gracefully** — Broken code shows helpful errors, not crashes
+4. **Can run standalone** — Deploy independently with `@iris/runtime`
+5. **Works everywhere** — Same code runs on web and mobile (React Native)
+
+### Server-Defined Rendering (SDR)
+
+Most Iris Apps use SDR — the server defines what the UI looks like using a simple component tree:
+
+```typescript
+// server.ts - A complete Iris App
+import { defineApp, state } from '@iris/app-sdk';
+import { Stack, Text, Button } from '@iris/ui';
+
+export default defineApp({
+  state: {
+    count: state(0),
+  },
+
+  ui: (ctx) => (
+    Stack({ padding: 24, gap: 16 }, [
+      Text({ size: '4xl' }, ctx.state.count),
+      Button({
+        onPress: () => ctx.state.count.update(n => n + 1),
+      }, '+1'),
+    ])
+  ),
+});
+```
+
+**Why SDR?**
+- **Single file** — No separate frontend build, no React boilerplate
+- **Instant hot reload** — Change code, see results immediately
+- **Mobile native** — Same code renders natively on phones
+- **Secure by default** — UI is just data, not executable code
+- **AI-friendly** — Simple enough for AI to generate and modify
+
+### The Two Modes
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    IRIS APP MODES                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  SDR MODE (Default)                                              │
+│  • Single server.ts file                                        │
+│  • ui() function returns component tree                         │
+│  • Rendered by @iris/ui component registry                      │
+│  • Best for: Most apps, data tools, dashboards                  │
+│                                                                  │
+│  CUSTOM UI MODE (Escape Hatch)                                   │
+│  • Full React app in ui/ folder                                 │
+│  • Runs in sandboxed iframe                                     │
+│  • Bridge protocol for state/tools                              │
+│  • Best for: 3D, canvas, complex interactions                   │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### App Structure
+
+**SDR App (most apps):**
+```
+my-app/
+├── app.json        # Manifest
+└── server.ts       # Everything: state, tools, UI
+```
+
+**Custom UI App (escape hatch):**
+```
+my-app/
+├── app.json        # Manifest with ui.mode: "custom"
+├── server.ts       # State, tools, services
+└── ui/             # Full React app
+    ├── index.html
+    └── src/App.tsx
+```
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     DATA FLOW (SDR)                              │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  SERVER                              CLIENT                      │
+│                                                                  │
+│  ┌─────────────┐                    ┌─────────────┐             │
+│  │  App State  │                    │ State Store │             │
+│  │  count: 5   │◄──── WebSocket ───►│  count: 5   │             │
+│  └──────┬──────┘                    └──────┬──────┘             │
+│         │                                  │                     │
+│         ▼                                  ▼                     │
+│  ┌─────────────┐                    ┌─────────────┐             │
+│  │   ui(ctx)   │    Component Tree  │SDR Renderer │             │
+│  │   returns   │──────────────────►│   renders   │             │
+│  │   tree      │    (JSON data)     │   React     │             │
+│  └─────────────┘                    └──────┬──────┘             │
+│                                            │                     │
+│                                            ▼                     │
+│                                     ┌─────────────┐             │
+│                                     │  Native UI  │             │
+│                                     │  (Web/RN)   │             │
+│                                     └─────────────┘             │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## Key Principles
+
+1. **Single-file simplicity** — Most apps are just `app.json` + `server.ts`
+2. **AI-native** — Tools are first-class citizens, easily callable by agents
+3. **Resilient by default** — Errors are informative, not fatal
+4. **Cross-platform** — Same code runs on web, iOS, Android
+5. **Security through simplicity** — SDR means no arbitrary code execution
+
+## Security Model
+
+Like VS Code extensions, Iris Apps are trusted based on their source:
+
+- **Development apps** — Full project access (you're the developer)
+- **Installed apps** — Declared permissions, approved at install
+- **Untrusted apps** — Minimal permissions, explicit approval required
+
+SDR provides additional security: the UI is just data rendered by trusted components, not arbitrary JavaScript that could steal data or cause harm.
+
+See [04-security-model.md](./04-security-model.md) for details.
+
+## Implementation Status
+
+| Phase | Status | Description |
+|-------|--------|-------------|
+| Phase 1: Foundation | 📋 Planned | Manifest, loader, component registry |
+| Phase 2: SDR Core | 📋 Planned | ui() execution, rendering |
+| Phase 3: State & Tools | 📋 Planned | Reactive state, hot reload |
+| Phase 4: SDK & DX | 📋 Planned | @iris/app-sdk, @iris/ui |
+| Phase 5: Platform Integration | 📋 Planned | AI, filesystem, permissions |
+| Phase 6: Production | 📋 Planned | Custom UI, mobile, standalone |
+
+See [07-implementation-roadmap.md](./07-implementation-roadmap.md) for the detailed plan.
+
+## Example App
+
+A database explorer that lets you browse and query SQLite databases:
+
+```typescript
+// server.ts
+import { defineApp, defineTool, state } from '@iris/app-sdk';
+import { Stack, Input, Button, DataTable, Alert } from '@iris/ui';
+import { z } from 'zod';
+
+export default defineApp({
+  state: {
+    query: state('SELECT * FROM users LIMIT 10'),
+    results: state<any[]>([]),
+    error: state<string | null>(null),
+  },
+
+  tools: [
+    defineTool({
+      name: 'query',
+      description: 'Execute a SQL query',
+      parameters: z.object({ sql: z.string() }),
+      execute: async ({ sql }, ctx) => {
+        try {
+          const db = await ctx.getService('database');
+          const results = await db.query(sql);
+          ctx.state.results.set(results);
+          ctx.state.error.set(null);
+          return { rowCount: results.length };
+        } catch (e) {
+          ctx.state.error.set(e.message);
+          return { error: e.message };
+        }
+      },
+    }),
+  ],
+
+  ui: (ctx) => (
+    Stack({ padding: 16, gap: 16 }, [
+      Input({
+        value: ctx.state.query,
+        onChangeText: ctx.state.query.set,
+        multiline: true,
+      }),
+      Button({
+        onPress: () => ctx.runTool('query', { sql: ctx.state.query.get() }),
+      }, 'Run Query'),
+      ctx.state.error.get() && Alert({ variant: 'error' }, ctx.state.error),
+      DataTable({ data: ctx.state.results }),
+    ])
+  ),
+});
+```
+
+## Getting Involved
+
+This architecture is designed to be:
+
+- **Reviewable** — Read through the docs and provide feedback
+- **Iterative** — We'll refine as we learn
+- **Extensible** — Designed to accommodate future needs
+
+Questions? Ideas? Open an issue or discuss in the team channel.
+
+---
+
+*"The best way to predict the future is to invent it." — Alan Kay*
diff --git a/examples/counter-app/app.json b/examples/counter-app/app.json
new file mode 100644
index 0000000..b1556d9
--- /dev/null
+++ b/examples/counter-app/app.json
@@ -0,0 +1,27 @@
+{
+  "name": "counter",
+  "displayName": "Counter",
+  "version": "0.1.0",
+  "description": "A simple counter app demonstrating Iris Apps with SDR",
+  "icon": "🔢",
+  "server": "server.ts",
+  "tools": [
+    {
+      "name": "increment",
+      "description": "Increment the counter by a specified amount"
+    },
+    {
+      "name": "decrement",
+      "description": "Decrement the counter by a specified amount"
+    },
+    {
+      "name": "reset",
+      "description": "Reset the counter to zero"
+    },
+    {
+      "name": "set",
+      "description": "Set the counter to a specific value"
+    }
+  ],
+  "permissions": []
+}
diff --git a/examples/counter-app/server.ts b/examples/counter-app/server.ts
new file mode 100644
index 0000000..6045d69
--- /dev/null
+++ b/examples/counter-app/server.ts
@@ -0,0 +1,284 @@
+/**
+ * Counter App
+ *
+ * A simple counter demonstrating Iris Apps with Server-Defined Rendering.
+ * This app shows:
+ * - State management with state()
+ * - Tool definitions for AI integration
+ * - UI generation with @iris/ui components
+ * - Hot reload support
+ */
+
+// Note: In a real app, these would be imported from packages
+// import { defineApp, defineTool, state } from '@iris/app-sdk';
+// import { Stack, Row, Text, Button, Card, Badge } from '@iris/ui';
+
+import { z } from "zod";
+
+// ============================================================================
+// Inline SDK (until packages are properly set up)
+// ============================================================================
+
+type Listener<T> = (value: T) => void;
+
+interface StateHandle<T> {
+  get(): T;
+  set(value: T): void;
+  update(updater: (prev: T) => T): void;
+  subscribe(listener: Listener<T>): () => void;
+  toJSON(): T;
+}
+
+function state<T>(initial: T): StateHandle<T> {
+  let value = initial;
+  const listeners = new Set<Listener<T>>();
+
+  return {
+    get: () => value,
+    set: (newValue: T) => {
+      if (Object.is(value, newValue)) return;
+      value = newValue;
+      listeners.forEach((l) => l(value));
+    },
+    update: (updater: (prev: T) => T) => {
+      const newValue = updater(value);
+      if (Object.is(value, newValue)) return;
+      value = newValue;
+      listeners.forEach((l) => l(value));
+    },
+    subscribe: (listener: Listener<T>) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    toJSON: () => value,
+  };
+}
+
+// Component helpers
+interface ComponentNode {
+  $: "component";
+  type: string;
+  props: Record<string, unknown>;
+  children?: unknown[];
+  key?: string;
+}
+
+function component(type: string, props: Record<string, unknown> = {}, children?: unknown[]): ComponentNode {
+  return { $: "component", type, props, children };
+}
+
+// Simple component functions
+const Stack = (props: Record<string, unknown>, children?: unknown[]) =>
+  component("Stack", props, children);
+const Row = (props: Record<string, unknown>, children?: unknown[]) =>
+  component("Row", props, children);
+const Text = (props: Record<string, unknown>, children?: unknown) =>
+  component("Text", props, Array.isArray(children) ? children : [children]);
+const Button = (props: Record<string, unknown>, children?: unknown) =>
+  component("Button", props, Array.isArray(children) ? children : [children]);
+const Card = (props: Record<string, unknown>, children?: unknown[]) =>
+  component("Card", props, children);
+const Badge = (props: Record<string, unknown>, children?: unknown) =>
+  component("Badge", props, Array.isArray(children) ? children : [children]);
+const Divider = (props: Record<string, unknown> = {}) =>
+  component("Divider", props);
+
+// ============================================================================
+// App Definition
+// ============================================================================
+
+interface AppContext {
+  state: {
+    count: StateHandle<number>;
+    history: StateHandle<string[]>;
+  };
+  runTool: (name: string, args?: unknown) => Promise<unknown>;
+  iris: unknown;
+}
+
+// State factories
+const appState = {
+  count: () => state(0),
+  history: () => state<string[]>([]),
+};
+
+// Tools
+const tools = [
+  {
+    name: "increment",
+    description: "Increment the counter by a specified amount",
+    parameters: z.object({
+      amount: z.number().default(1).describe("Amount to increment by"),
+    }),
+    execute: async (args: { amount: number }, ctx: AppContext) => {
+      const oldValue = ctx.state.count.get();
+      ctx.state.count.update((n) => n + args.amount);
+      ctx.state.history.update((h) => [
+        ...h.slice(-9),
+        `+${args.amount} (${oldValue} → ${ctx.state.count.get()})`,
+      ]);
+      return { previousValue: oldValue, newValue: ctx.state.count.get() };
+    },
+  },
+  {
+    name: "decrement",
+    description: "Decrement the counter by a specified amount",
+    parameters: z.object({
+      amount: z.number().default(1).describe("Amount to decrement by"),
+    }),
+    execute: async (args: { amount: number }, ctx: AppContext) => {
+      const oldValue = ctx.state.count.get();
+      ctx.state.count.update((n) => n - args.amount);
+      ctx.state.history.update((h) => [
+        ...h.slice(-9),
+        `-${args.amount} (${oldValue} → ${ctx.state.count.get()})`,
+      ]);
+      return { previousValue: oldValue, newValue: ctx.state.count.get() };
+    },
+  },
+  {
+    name: "reset",
+    description: "Reset the counter to zero",
+    parameters: z.object({}),
+    execute: async (_args: unknown, ctx: AppContext) => {
+      const oldValue = ctx.state.count.get();
+      ctx.state.count.set(0);
+      ctx.state.history.update((h) => [
+        ...h.slice(-9),
+        `reset (${oldValue} → 0)`,
+      ]);
+      return { previousValue: oldValue, newValue: 0 };
+    },
+  },
+  {
+    name: "set",
+    description: "Set the counter to a specific value",
+    parameters: z.object({
+      value: z.number().describe("Value to set the counter to"),
+    }),
+    execute: async (args: { value: number }, ctx: AppContext) => {
+      const oldValue = ctx.state.count.get();
+      ctx.state.count.set(args.value);
+      ctx.state.history.update((h) => [
+        ...h.slice(-9),
+        `set ${args.value} (${oldValue} → ${args.value})`,
+      ]);
+      return { previousValue: oldValue, newValue: args.value };
+    },
+  },
+];
+
+// UI Generator
+function ui(ctx: AppContext): ComponentNode {
+  const count = ctx.state.count.get();
+  const history = ctx.state.history.get();
+
+  return Stack({ padding: 24, gap: 24 }, [
+    // Header
+    Row({ justify: "between", align: "center" }, [
+      Text({ size: "2xl", weight: "bold" }, "Counter App"),
+      Badge({ variant: count >= 0 ? "success" : "error" }, `${count >= 0 ? "+" : ""}${count}`),
+    ]),
+
+    Divider({}),
+
+    // Counter display
+    Card({ padding: 32 }, [
+      Stack({ align: "center", gap: 16 }, [
+        Text(
+          {
+            size: "4xl",
+            weight: "bold",
+            color: count >= 0 ? "var(--success-color, #28a745)" : "var(--danger-color, #dc3545)",
+          },
+          String(count)
+        ),
+        Row({ gap: 12 }, [
+          Button(
+            {
+              variant: "primary",
+              size: "lg",
+              onPress: { $action: "decrement", args: { amount: 1 } },
+            },
+            "−1"
+          ),
+          Button(
+            {
+              variant: "primary",
+              size: "lg",
+              onPress: { $action: "increment", args: { amount: 1 } },
+            },
+            "+1"
+          ),
+        ]),
+        Row({ gap: 8 }, [
+          Button(
+            {
+              variant: "outline",
+              onPress: { $action: "decrement", args: { amount: 10 } },
+            },
+            "−10"
+          ),
+          Button(
+            {
+              variant: "outline",
+              onPress: { $action: "increment", args: { amount: 10 } },
+            },
+            "+10"
+          ),
+          Button(
+            {
+              variant: "ghost",
+              onPress: { $action: "reset", args: {} },
+            },
+            "Reset"
+          ),
+        ]),
+      ]),
+    ]),
+
+    // History
+    history.length > 0 &&
+      Stack({ gap: 8 }, [
+        Text({ size: "sm", weight: "medium", color: "#888" }, "History"),
+        ...history.map((entry, i) =>
+          Text({ key: String(i), size: "xs", mono: true, color: "#666" }, entry)
+        ),
+      ]),
+
+    // AI hint
+    Card({ padding: 16 }, [
+      Stack({ gap: 8 }, [
+        Text({ size: "sm", weight: "medium" }, "🤖 AI Tools Available"),
+        Text(
+          { size: "xs", color: "#666" },
+          "This app exposes tools that AI agents can use: increment, decrement, reset, set"
+        ),
+      ]),
+    ]),
+  ]);
+}
+
+// Lifecycle hooks
+async function onActivate(ctx: AppContext) {
+  console.log("[Counter] App activated");
+}
+
+async function onDeactivate(ctx: AppContext) {
+  console.log("[Counter] App deactivated");
+}
+
+async function onReload(ctx: AppContext, previousState: Record<string, unknown>) {
+  console.log("[Counter] App reloaded, restoring state:", previousState);
+  // State is auto-restored, but we could do custom migration here
+}
+
+// Export the app definition
+export default {
+  state: appState,
+  tools,
+  ui,
+  onActivate,
+  onDeactivate,
+  onReload,
+};
diff --git a/packages/app-sdk/package.json b/packages/app-sdk/package.json
new file mode 100644
index 0000000..78b2c46
--- /dev/null
+++ b/packages/app-sdk/package.json
@@ -0,0 +1,27 @@
+{
+  "name": "@iris/app-sdk",
+  "version": "0.1.0",
+  "description": "SDK for building Iris Apps with Server-Defined Rendering",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "keywords": [
+    "iris",
+    "app",
+    "sdk",
+    "sdr",
+    "server-defined-rendering"
+  ],
+  "peerDependencies": {
+    "zod": "^3.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}
diff --git a/packages/app-sdk/src/index.ts b/packages/app-sdk/src/index.ts
new file mode 100644
index 0000000..a7a596d
--- /dev/null
+++ b/packages/app-sdk/src/index.ts
@@ -0,0 +1,106 @@
+/**
+ * @iris/app-sdk
+ *
+ * SDK for building Iris Apps with Server-Defined Rendering.
+ *
+ * @example
+ * ```typescript
+ * import { defineApp, defineTool, state } from '@iris/app-sdk';
+ * import { Stack, Text, Button } from '@iris/ui';
+ *
+ * export default defineApp({
+ *   state: {
+ *     count: state(0),
+ *   },
+ *
+ *   tools: [
+ *     defineTool({
+ *       name: 'increment',
+ *       description: 'Increment the counter',
+ *       parameters: z.object({ amount: z.number().default(1) }),
+ *       execute: async ({ amount }, ctx) => {
+ *         ctx.state.count.update(n => n + amount);
+ *         return { newCount: ctx.state.count.get() };
+ *       },
+ *     }),
+ *   ],
+ *
+ *   ui: (ctx) => Stack({ padding: 24 }, [
+ *     Text({ size: '4xl' }, ctx.state.count.get()),
+ *     Button({
+ *       onPress: { $action: 'increment', args: { amount: 1 } },
+ *     }, '+1'),
+ *   ]),
+ * });
+ * ```
+ */
+
+// Re-export state primitives
+export { state, computed, query, list } from "./state.ts";
+export type { QueryState, ListState } from "./state.ts";
+
+// Re-export types
+export type {
+  AppDefinition,
+  AppContext,
+  AppToolDefinition,
+  IrisPlatformContext,
+  StateHandle,
+  UITree,
+  ComponentNode,
+  UIChild,
+  ActionDescriptor,
+} from "../../../src/apps/types.ts";
+
+import type { AppDefinition, AppToolDefinition } from "../../../src/apps/types.ts";
+import { z } from "zod";
+
+/**
+ * Define an Iris App
+ *
+ * This is the main entry point for creating an app. The returned definition
+ * is used by the Iris runtime to manage the app's lifecycle.
+ */
+export function defineApp(definition: AppDefinition): AppDefinition {
+  return definition;
+}
+
+/**
+ * Define a tool that can be called by AI agents
+ *
+ * Tools are exposed to the Iris AI system and can be invoked
+ * by the agent to interact with your app's functionality.
+ */
+export function defineTool<TParams extends z.ZodType>(config: {
+  name: string;
+  description: string;
+  parameters: TParams;
+  execute: (
+    args: z.infer<TParams>,
+    ctx: import("../../../src/apps/types.ts").AppContext
+  ) => Promise<unknown>;
+}): AppToolDefinition {
+  return {
+    name: config.name,
+    description: config.description,
+    parameters: config.parameters,
+    execute: config.execute as (args: unknown, ctx: import("../../../src/apps/types.ts").AppContext) => Promise<unknown>,
+  };
+}
+
+/**
+ * Create an action descriptor for event handlers
+ *
+ * Use this to specify what tool should be called when a UI event occurs.
+ */
+export function action(
+  toolName: string,
+  args?: unknown,
+  options?: { optimistic?: Record<string, unknown> }
+): import("../../../src/apps/types.ts").ActionDescriptor {
+  return {
+    $action: toolName,
+    args,
+    optimistic: options?.optimistic,
+  };
+}
diff --git a/packages/app-sdk/src/state.ts b/packages/app-sdk/src/state.ts
new file mode 100644
index 0000000..97699aa
--- /dev/null
+++ b/packages/app-sdk/src/state.ts
@@ -0,0 +1,196 @@
+/**
+ * @iris/app-sdk - State Primitives
+ *
+ * Reactive state management for Iris Apps.
+ * These primitives track state and trigger UI updates when changed.
+ */
+
+import type { StateHandle } from "../../../src/apps/types.ts";
+
+type Listener<T> = (value: T) => void;
+
+/**
+ * Create a reactive state value
+ *
+ * @example
+ * ```typescript
+ * const count = state(0);
+ * count.get();        // 0
+ * count.set(5);       // value is now 5
+ * count.update(n => n + 1);  // value is now 6
+ * ```
+ */
+export function state<T>(initial: T): StateHandle<T> {
+  let value = initial;
+  const listeners = new Set<Listener<T>>();
+
+  return {
+    get: () => value,
+
+    set: (newValue: T) => {
+      if (Object.is(value, newValue)) return; // Skip if unchanged
+      value = newValue;
+      listeners.forEach((l) => l(value));
+    },
+
+    update: (updater: (prev: T) => T) => {
+      const newValue = updater(value);
+      if (Object.is(value, newValue)) return;
+      value = newValue;
+      listeners.forEach((l) => l(value));
+    },
+
+    subscribe: (listener: Listener<T>) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    toJSON: () => value,
+  };
+}
+
+/**
+ * Create a computed value derived from other state
+ *
+ * @example
+ * ```typescript
+ * const count = state(5);
+ * const doubled = computed(() => count.get() * 2);
+ * doubled.get(); // 10
+ * ```
+ */
+export function computed<T>(
+  compute: () => T,
+  deps: Array<StateHandle<unknown>>
+): StateHandle<T> {
+  let cachedValue = compute();
+  const listeners = new Set<Listener<T>>();
+
+  // Subscribe to dependencies
+  const unsubscribers = deps.map((dep) =>
+    dep.subscribe(() => {
+      const newValue = compute();
+      if (Object.is(cachedValue, newValue)) return;
+      cachedValue = newValue;
+      listeners.forEach((l) => l(cachedValue));
+    })
+  );
+
+  return {
+    get: () => cachedValue,
+
+    set: () => {
+      throw new Error("Cannot set a computed value");
+    },
+
+    update: () => {
+      throw new Error("Cannot update a computed value");
+    },
+
+    subscribe: (listener: Listener<T>) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    toJSON: () => cachedValue,
+  };
+}
+
+/**
+ * Create an async query state
+ *
+ * @example
+ * ```typescript
+ * const users = query(async () => {
+ *   const response = await fetch('/api/users');
+ *   return response.json();
+ * });
+ *
+ * // In UI:
+ * users.loading ? Spinner() : UserList({ data: users.data })
+ * ```
+ */
+export interface QueryState<T> {
+  data: T | null;
+  loading: boolean;
+  error: string | null;
+  refetch: () => Promise<void>;
+}
+
+export function query<T>(
+  fetcher: () => Promise<T>,
+  options: { autoFetch?: boolean } = {}
+): StateHandle<QueryState<T>> {
+  const { autoFetch = true } = options;
+
+  const queryState: QueryState<T> = {
+    data: null,
+    loading: autoFetch,
+    error: null,
+    refetch: async () => {
+      handle.update((s) => ({ ...s, loading: true, error: null }));
+      try {
+        const data = await fetcher();
+        handle.update((s) => ({ ...s, data, loading: false }));
+      } catch (error) {
+        handle.update((s) => ({
+          ...s,
+          error: error instanceof Error ? error.message : String(error),
+          loading: false,
+        }));
+      }
+    },
+  };
+
+  const handle = state(queryState);
+
+  // Auto-fetch on creation
+  if (autoFetch) {
+    queryState.refetch();
+  }
+
+  return handle;
+}
+
+/**
+ * Create a list state with helper methods
+ *
+ * @example
+ * ```typescript
+ * const items = list<Todo>([]);
+ * items.push({ id: 1, text: 'Hello' });
+ * items.remove(item => item.id === 1);
+ * ```
+ */
+export interface ListState<T> extends StateHandle<T[]> {
+  push: (item: T) => void;
+  remove: (predicate: (item: T) => boolean) => void;
+  updateItem: (predicate: (item: T) => boolean, updater: (item: T) => T) => void;
+  clear: () => void;
+}
+
+export function list<T>(initial: T[] = []): ListState<T> {
+  const handle = state<T[]>(initial);
+
+  return {
+    ...handle,
+
+    push: (item: T) => {
+      handle.update((items) => [...items, item]);
+    },
+
+    remove: (predicate: (item: T) => boolean) => {
+      handle.update((items) => items.filter((item) => !predicate(item)));
+    },
+
+    updateItem: (predicate: (item: T) => boolean, updater: (item: T) => T) => {
+      handle.update((items) =>
+        items.map((item) => (predicate(item) ? updater(item) : item))
+      );
+    },
+
+    clear: () => {
+      handle.set([]);
+    },
+  };
+}
diff --git a/packages/ui/package.json b/packages/ui/package.json
new file mode 100644
index 0000000..7556653
--- /dev/null
+++ b/packages/ui/package.json
@@ -0,0 +1,26 @@
+{
+  "name": "@iris/ui",
+  "version": "0.1.0",
+  "description": "Cross-platform component library for Iris Apps",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts",
+      "types": "./src/index.ts"
+    }
+  },
+  "keywords": [
+    "iris",
+    "ui",
+    "components",
+    "sdr",
+    "server-defined-rendering",
+    "react",
+    "react-native"
+  ],
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}
diff --git a/packages/ui/src/components.ts b/packages/ui/src/components.ts
new file mode 100644
index 0000000..bc9de84
--- /dev/null
+++ b/packages/ui/src/components.ts
@@ -0,0 +1,498 @@
+/**
+ * @iris/ui - Component Functions
+ *
+ * Server-side component functions that return SDR component nodes.
+ * These are called by the app's ui() function to build the UI tree.
+ *
+ * Usage:
+ * ```typescript
+ * import { Stack, Text, Button } from '@iris/ui';
+ *
+ * ui: (ctx) => Stack({ padding: 16 }, [
+ *   Text({ size: 'lg' }, 'Hello World'),
+ *   Button({ onPress: () => ctx.runTool('greet') }, 'Greet'),
+ * ])
+ * ```
+ */
+
+import type { ComponentNode, UIChild, PropValue, ActionDescriptor } from "../../../src/apps/types.ts";
+
+// ============================================================================
+// Component Builder Helper
+// ============================================================================
+
+function component(
+  type: string,
+  props: Record<string, PropValue> = {},
+  children?: UIChild[]
+): ComponentNode {
+  return {
+    $: "component",
+    type,
+    props,
+    children,
+  };
+}
+
+// Helper to handle children that can be a single item or array
+function normalizeChildren(children?: UIChild | UIChild[]): UIChild[] | undefined {
+  if (children === undefined || children === null) return undefined;
+  if (Array.isArray(children)) return children;
+  return [children];
+}
+
+// ============================================================================
+// Layout Components
+// ============================================================================
+
+export interface StackProps {
+  gap?: number;
+  padding?: number;
+  paddingX?: number;
+  paddingY?: number;
+  align?: "start" | "center" | "end" | "stretch";
+  justify?: "start" | "center" | "end" | "between" | "around";
+  flex?: number;
+  key?: string;
+}
+
+/**
+ * Vertical stack layout
+ */
+export function Stack(props: StackProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Stack", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface RowProps {
+  gap?: number;
+  padding?: number;
+  paddingX?: number;
+  paddingY?: number;
+  align?: "start" | "center" | "end" | "stretch";
+  justify?: "start" | "center" | "end" | "between" | "around";
+  wrap?: boolean;
+  flex?: number;
+  key?: string;
+}
+
+/**
+ * Horizontal row layout
+ */
+export function Row(props: RowProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Row", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface BoxProps {
+  padding?: number;
+  paddingX?: number;
+  paddingY?: number;
+  margin?: number;
+  marginX?: number;
+  marginY?: number;
+  flex?: number;
+  width?: number | string;
+  height?: number | string;
+  backgroundColor?: string;
+  borderRadius?: number;
+  border?: string;
+  key?: string;
+}
+
+/**
+ * Generic container box
+ */
+export function Box(props: BoxProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Box", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface ScrollViewProps {
+  horizontal?: boolean;
+  flex?: number;
+  key?: string;
+}
+
+/**
+ * Scrollable container
+ */
+export function ScrollView(props: ScrollViewProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("ScrollView", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+/**
+ * Visual divider line
+ */
+export function Divider(props: { margin?: number; key?: string } = {}): ComponentNode {
+  return component("Divider", props);
+}
+
+// ============================================================================
+// Typography Components
+// ============================================================================
+
+export interface TextProps {
+  size?: "xs" | "sm" | "base" | "lg" | "xl" | "2xl" | "3xl" | "4xl";
+  weight?: "normal" | "medium" | "semibold" | "bold";
+  color?: string;
+  align?: "left" | "center" | "right";
+  italic?: boolean;
+  mono?: boolean;
+  key?: string;
+}
+
+/**
+ * Text content
+ */
+export function Text(props: TextProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Text", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface HeadingProps {
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  color?: string;
+  key?: string;
+}
+
+/**
+ * Heading text (h1-h6)
+ */
+export function Heading(props: HeadingProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Heading", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface CodeProps {
+  language?: string;
+  inline?: boolean;
+  key?: string;
+}
+
+/**
+ * Code display (inline or block)
+ */
+export function Code(props: CodeProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Code", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface LinkProps {
+  href: string;
+  external?: boolean;
+  key?: string;
+}
+
+/**
+ * Hyperlink
+ */
+export function Link(props: LinkProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Link", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+// ============================================================================
+// Form Components
+// ============================================================================
+
+export interface ButtonProps {
+  variant?: "primary" | "secondary" | "outline" | "ghost" | "danger";
+  size?: "sm" | "md" | "lg";
+  disabled?: boolean;
+  loading?: boolean;
+  onPress?: ActionDescriptor | (() => void);
+  key?: string;
+}
+
+/**
+ * Clickable button
+ */
+export function Button(props: ButtonProps, children?: UIChild | UIChild[]): ComponentNode {
+  // Convert function to action descriptor if needed
+  const resolvedProps = { ...props };
+  if (typeof props.onPress === "function") {
+    // This will be serialized; the actual function can't be sent
+    // The runtime handles this case specially
+    resolvedProps.onPress = { $action: "__callback__" } as ActionDescriptor;
+  }
+  return component("Button", resolvedProps as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface InputProps {
+  value?: string;
+  placeholder?: string;
+  type?: "text" | "password" | "email" | "number" | "search";
+  disabled?: boolean;
+  multiline?: boolean;
+  rows?: number;
+  onChangeText?: ActionDescriptor | ((text: string) => void);
+  onSubmit?: ActionDescriptor | (() => void);
+  key?: string;
+}
+
+/**
+ * Text input field
+ */
+export function Input(props: InputProps): ComponentNode {
+  return component("Input", props as Record<string, PropValue>);
+}
+
+export interface TextAreaProps {
+  value?: string;
+  placeholder?: string;
+  disabled?: boolean;
+  rows?: number;
+  onChangeText?: ActionDescriptor | ((text: string) => void);
+  key?: string;
+}
+
+/**
+ * Multi-line text input
+ */
+export function TextArea(props: TextAreaProps): ComponentNode {
+  return component("TextArea", props as Record<string, PropValue>);
+}
+
+export interface SelectProps {
+  value?: string;
+  options: Array<{ value: string; label: string }>;
+  placeholder?: string;
+  disabled?: boolean;
+  onChange?: ActionDescriptor | ((value: string) => void);
+  key?: string;
+}
+
+/**
+ * Dropdown select
+ */
+export function Select(props: SelectProps): ComponentNode {
+  return component("Select", props as Record<string, PropValue>);
+}
+
+export interface CheckboxProps {
+  checked?: boolean;
+  label?: string;
+  disabled?: boolean;
+  onChange?: ActionDescriptor | ((checked: boolean) => void);
+  key?: string;
+}
+
+/**
+ * Checkbox input
+ */
+export function Checkbox(props: CheckboxProps): ComponentNode {
+  return component("Checkbox", props as Record<string, PropValue>);
+}
+
+export interface SwitchProps {
+  value?: boolean;
+  disabled?: boolean;
+  onChange?: ActionDescriptor | ((value: boolean) => void);
+  key?: string;
+}
+
+/**
+ * Toggle switch
+ */
+export function Switch(props: SwitchProps): ComponentNode {
+  return component("Switch", props as Record<string, PropValue>);
+}
+
+// ============================================================================
+// Data Display Components
+// ============================================================================
+
+export interface DataTableProps {
+  data: Array<Record<string, unknown>>;
+  columns?: Array<{
+    key: string;
+    label: string;
+    width?: number | string;
+  }>;
+  onRowPress?: ActionDescriptor | ((row: Record<string, unknown>) => void);
+  key?: string;
+}
+
+/**
+ * Data table for displaying tabular data
+ */
+export function DataTable(props: DataTableProps): ComponentNode {
+  return component("DataTable", props as Record<string, PropValue>);
+}
+
+export interface ListProps {
+  data: unknown[];
+  renderItem: (item: unknown, index: number) => ComponentNode;
+  keyExtractor?: (item: unknown, index: number) => string;
+  key?: string;
+}
+
+/**
+ * List component for rendering arrays
+ */
+export function List(props: ListProps): ComponentNode {
+  // Pre-render items server-side
+  const children = props.data.map((item, index) => {
+    const node = props.renderItem(item, index);
+    node.key = props.keyExtractor?.(item, index) ?? String(index);
+    return node;
+  });
+
+  return component("List", { key: props.key }, children);
+}
+
+export interface CardProps {
+  padding?: number;
+  elevation?: number;
+  onPress?: ActionDescriptor | (() => void);
+  key?: string;
+}
+
+/**
+ * Card container with elevation
+ */
+export function Card(props: CardProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Card", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface BadgeProps {
+  variant?: "default" | "success" | "warning" | "error" | "info";
+  key?: string;
+}
+
+/**
+ * Small badge/tag
+ */
+export function Badge(props: BadgeProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Badge", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface AvatarProps {
+  src?: string;
+  name?: string;
+  size?: "sm" | "md" | "lg";
+  key?: string;
+}
+
+/**
+ * User avatar
+ */
+export function Avatar(props: AvatarProps): ComponentNode {
+  return component("Avatar", props as Record<string, PropValue>);
+}
+
+// ============================================================================
+// Feedback Components
+// ============================================================================
+
+export interface AlertProps {
+  variant?: "info" | "success" | "warning" | "error";
+  title?: string;
+  dismissible?: boolean;
+  onDismiss?: ActionDescriptor | (() => void);
+  key?: string;
+}
+
+/**
+ * Alert message box
+ */
+export function Alert(props: AlertProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Alert", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface SpinnerProps {
+  size?: "sm" | "md" | "lg";
+  key?: string;
+}
+
+/**
+ * Loading spinner
+ */
+export function Spinner(props: SpinnerProps = {}): ComponentNode {
+  return component("Spinner", props);
+}
+
+export interface ProgressProps {
+  value: number; // 0-100
+  showLabel?: boolean;
+  key?: string;
+}
+
+/**
+ * Progress bar
+ */
+export function Progress(props: ProgressProps): ComponentNode {
+  return component("Progress", props as Record<string, PropValue>);
+}
+
+// ============================================================================
+// Specialized Components
+// ============================================================================
+
+export interface CodeEditorProps {
+  value?: string;
+  language?: string;
+  readOnly?: boolean;
+  lineNumbers?: boolean;
+  onChange?: ActionDescriptor | ((value: string) => void);
+  key?: string;
+}
+
+/**
+ * Code editor component
+ */
+export function CodeEditor(props: CodeEditorProps): ComponentNode {
+  return component("CodeEditor", props as Record<string, PropValue>);
+}
+
+export interface TerminalProps {
+  processId?: string;
+  readOnly?: boolean;
+  key?: string;
+}
+
+/**
+ * Terminal emulator display
+ */
+export function Terminal(props: TerminalProps): ComponentNode {
+  return component("Terminal", props as Record<string, PropValue>);
+}
+
+export interface MarkdownProps {
+  key?: string;
+}
+
+/**
+ * Markdown renderer
+ */
+export function Markdown(props: MarkdownProps, children?: UIChild | UIChild[]): ComponentNode {
+  return component("Markdown", props as Record<string, PropValue>, normalizeChildren(children));
+}
+
+export interface FileTreeProps {
+  path: string;
+  onSelect?: ActionDescriptor | ((path: string) => void);
+  key?: string;
+}
+
+/**
+ * File tree browser
+ */
+export function FileTree(props: FileTreeProps): ComponentNode {
+  return component("FileTree", props as Record<string, PropValue>);
+}
+
+// ============================================================================
+// Conditional & Utility
+// ============================================================================
+
+/**
+ * Conditional rendering helper
+ */
+export function Show(
+  condition: boolean,
+  children: UIChild | UIChild[]
+): UIChild[] | null {
+  return condition ? normalizeChildren(children) ?? null : null;
+}
+
+/**
+ * Fragment for grouping without wrapper
+ */
+export function Fragment(children: UIChild | UIChild[]): UIChild[] {
+  return normalizeChildren(children) ?? [];
+}
diff --git a/packages/ui/src/index.ts b/packages/ui/src/index.ts
new file mode 100644
index 0000000..d522b8b
--- /dev/null
+++ b/packages/ui/src/index.ts
@@ -0,0 +1,63 @@
+/**
+ * @iris/ui
+ *
+ * Cross-platform component library for Iris Apps.
+ * These functions return SDR component nodes that are rendered
+ * by the Iris runtime on both web and mobile.
+ *
+ * @example
+ * ```typescript
+ * import { Stack, Text, Button, Input } from '@iris/ui';
+ *
+ * Stack({ padding: 16, gap: 12 }, [
+ *   Text({ size: 'lg' }, 'Hello World'),
+ *   Input({ placeholder: 'Enter text...' }),
+ *   Button({ variant: 'primary' }, 'Submit'),
+ * ])
+ * ```
+ */
+
+// Layout components
+export { Stack, Row, Box, ScrollView, Divider } from "./components.ts";
+export type { StackProps, RowProps, BoxProps, ScrollViewProps } from "./components.ts";
+
+// Typography components
+export { Text, Heading, Code, Link } from "./components.ts";
+export type { TextProps, HeadingProps, CodeProps, LinkProps } from "./components.ts";
+
+// Form components
+export { Button, Input, TextArea, Select, Checkbox, Switch } from "./components.ts";
+export type {
+  ButtonProps,
+  InputProps,
+  TextAreaProps,
+  SelectProps,
+  CheckboxProps,
+  SwitchProps,
+} from "./components.ts";
+
+// Data display components
+export { DataTable, List, Card, Badge, Avatar } from "./components.ts";
+export type {
+  DataTableProps,
+  ListProps,
+  CardProps,
+  BadgeProps,
+  AvatarProps,
+} from "./components.ts";
+
+// Feedback components
+export { Alert, Spinner, Progress } from "./components.ts";
+export type { AlertProps, SpinnerProps, ProgressProps } from "./components.ts";
+
+// Specialized components
+export { CodeEditor, Terminal, Markdown, FileTree } from "./components.ts";
+export type {
+  CodeEditorProps,
+  TerminalProps,
+  MarkdownProps,
+  FileTreeProps,
+} from "./components.ts";
+
+// Utility components
+export { Show, Fragment } from "./components.ts";
diff --git a/src/apps/hot-reload.ts b/src/apps/hot-reload.ts
new file mode 100644
index 0000000..0abb854
--- /dev/null
+++ b/src/apps/hot-reload.ts
@@ -0,0 +1,187 @@
+/**
+ * Hot Reload Manager
+ *
+ * Manages file watching and hot reloading for Iris Apps.
+ * Features:
+ * - Debounced file watching (avoids multiple reloads on rapid saves)
+ * - State preservation across reloads
+ * - Graceful error handling
+ */
+
+import { watch, type FSWatcher } from "fs";
+import type { AppManager } from "./manager/index.ts";
+
+interface PendingReload {
+  timeout: Timer;
+  files: Set<string>;
+}
+
+/**
+ * Hot reload configuration
+ */
+export interface HotReloadConfig {
+  /** Debounce delay in ms (default: 100) */
+  debounceMs?: number;
+  /** File extensions to watch (default: .ts, .tsx, .json) */
+  extensions?: string[];
+  /** Ignore patterns */
+  ignore?: RegExp[];
+}
+
+const DEFAULT_CONFIG: Required<HotReloadConfig> = {
+  debounceMs: 100,
+  extensions: [".ts", ".tsx", ".json"],
+  ignore: [/node_modules/, /\.git/, /\.iris\/logs/],
+};
+
+/**
+ * Hot Reload Manager
+ */
+export class HotReloadManager {
+  private manager: AppManager;
+  private config: Required<HotReloadConfig>;
+  private watchers = new Map<string, FSWatcher>();
+  private pending = new Map<string, PendingReload>();
+
+  constructor(manager: AppManager, config: HotReloadConfig = {}) {
+    this.manager = manager;
+    this.config = { ...DEFAULT_CONFIG, ...config };
+  }
+
+  /**
+   * Start watching an app for changes
+   */
+  watch(appId: string, appPath: string): void {
+    if (this.watchers.has(appId)) {
+      return; // Already watching
+    }
+
+    console.log(`[HotReload] Watching ${appPath} for changes`);
+
+    const watcher = watch(
+      appPath,
+      { recursive: true },
+      (eventType, filename) => {
+        if (!filename) return;
+        this.handleFileChange(appId, filename);
+      }
+    );
+
+    this.watchers.set(appId, watcher);
+  }
+
+  /**
+   * Stop watching an app
+   */
+  unwatch(appId: string): void {
+    const watcher = this.watchers.get(appId);
+    if (watcher) {
+      watcher.close();
+      this.watchers.delete(appId);
+    }
+
+    // Cancel any pending reload
+    const pending = this.pending.get(appId);
+    if (pending) {
+      clearTimeout(pending.timeout);
+      this.pending.delete(appId);
+    }
+
+    console.log(`[HotReload] Stopped watching app ${appId}`);
+  }
+
+  /**
+   * Stop all watchers
+   */
+  dispose(): void {
+    for (const appId of this.watchers.keys()) {
+      this.unwatch(appId);
+    }
+  }
+
+  /**
+   * Handle a file change event
+   */
+  private handleFileChange(appId: string, filename: string): void {
+    // Check extension
+    const hasValidExtension = this.config.extensions.some((ext) =>
+      filename.endsWith(ext)
+    );
+    if (!hasValidExtension) {
+      return;
+    }
+
+    // Check ignore patterns
+    const isIgnored = this.config.ignore.some((pattern) =>
+      pattern.test(filename)
+    );
+    if (isIgnored) {
+      return;
+    }
+
+    console.log(`[HotReload] File changed: ${filename}`);
+
+    // Debounce: accumulate changes and reload once
+    let pending = this.pending.get(appId);
+    if (pending) {
+      // Add to existing pending reload
+      pending.files.add(filename);
+      clearTimeout(pending.timeout);
+    } else {
+      // Create new pending reload
+      pending = {
+        timeout: null as unknown as Timer,
+        files: new Set([filename]),
+      };
+      this.pending.set(appId, pending);
+    }
+
+    // Schedule reload
+    pending.timeout = setTimeout(() => {
+      this.executeReload(appId);
+    }, this.config.debounceMs);
+  }
+
+  /**
+   * Execute the reload
+   */
+  private async executeReload(appId: string): Promise<void> {
+    const pending = this.pending.get(appId);
+    if (!pending) return;
+
+    const files = Array.from(pending.files);
+    this.pending.delete(appId);
+
+    console.log(
+      `[HotReload] Reloading ${appId} (${files.length} file(s) changed)`
+    );
+
+    try {
+      await this.manager.hotReload(appId);
+      console.log(`[HotReload] Successfully reloaded ${appId}`);
+    } catch (error) {
+      console.error(`[HotReload] Failed to reload ${appId}:`, error);
+      // Error is already handled by the manager (sent to UI)
+    }
+  }
+}
+
+/**
+ * Simple debounce utility
+ */
+export function debounce<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  ms: number
+): (...args: Parameters<T>) => void {
+  let timeout: Timer | null = null;
+
+  return (...args: Parameters<T>) => {
+    if (timeout) {
+      clearTimeout(timeout);
+    }
+    timeout = setTimeout(() => {
+      fn(...args);
+      timeout = null;
+    }, ms);
+  };
+}
diff --git a/src/apps/index.ts b/src/apps/index.ts
new file mode 100644
index 0000000..5bb51ed
--- /dev/null
+++ b/src/apps/index.ts
@@ -0,0 +1,19 @@
+/**
+ * Iris Apps System
+ *
+ * Modular app system with Server-Defined Rendering (SDR).
+ * Apps are single-file TypeScript modules that run in Iris and expose
+ * tools to AI agents.
+ */
+
+// Types
+export * from "./types.ts";
+
+// Manager
+export { AppManager, getAppManager, disposeAppManager } from "./manager/index.ts";
+
+// Runtime
+export { AppRuntime } from "./runtime/index.ts";
+
+// Hot Reload
+export { HotReloadManager, debounce } from "./hot-reload.ts";
diff --git a/src/apps/manager/index.ts b/src/apps/manager/index.ts
new file mode 100644
index 0000000..0aeac6a
--- /dev/null
+++ b/src/apps/manager/index.ts
@@ -0,0 +1,334 @@
+/**
+ * App Manager
+ *
+ * Discovers, loads, and manages Iris Apps within a project.
+ * Handles app lifecycle: discover → load → activate → deactivate → unload
+ */
+
+import type {
+  AppManifest,
+  ManagedApp,
+  DiscoveredApp,
+  AppStatus,
+  TrustLevel,
+  AppError,
+} from "../types.ts";
+import { AppManifestSchema } from "../types.ts";
+import { AppRuntime } from "../runtime/index.ts";
+import { HotReloadManager } from "../hot-reload.ts";
+
+/**
+ * App Manager - singleton per project
+ */
+export class AppManager {
+  private apps = new Map<string, ManagedApp>();
+  private runtimes = new Map<string, AppRuntime>();
+  private hotReload: HotReloadManager;
+  private projectId: string;
+  private projectPath: string;
+
+  constructor(projectId: string, projectPath: string) {
+    this.projectId = projectId;
+    this.projectPath = projectPath;
+    this.hotReload = new HotReloadManager(this, {
+      debounceMs: 150, // Wait 150ms after last change
+    });
+  }
+
+  /**
+   * Discover all apps in the project
+   * Looks for app.json files in standard locations
+   */
+  async discover(): Promise<DiscoveredApp[]> {
+    const discovered: DiscoveredApp[] = [];
+    const searchPaths = [
+      `${this.projectPath}/apps`,
+      `${this.projectPath}/.iris/apps`,
+    ];
+
+    for (const searchPath of searchPaths) {
+      try {
+        const entries = await this.listDirectory(searchPath);
+        for (const entry of entries) {
+          if (!entry.isDirectory) continue;
+
+          const appPath = `${searchPath}/${entry.name}`;
+          const manifestPath = `${appPath}/app.json`;
+
+          try {
+            const manifest = await this.loadManifest(manifestPath);
+            discovered.push({
+              path: appPath,
+              manifest,
+              trustLevel: this.determineTrustLevel(appPath),
+            });
+          } catch {
+            // Not a valid app, skip
+          }
+        }
+      } catch {
+        // Directory doesn't exist, skip
+      }
+    }
+
+    return discovered;
+  }
+
+  /**
+   * Load an app by path
+   */
+  async load(appPath: string): Promise<ManagedApp> {
+    const id = this.generateAppId(appPath);
+
+    // Check if already loaded
+    if (this.apps.has(id)) {
+      return this.apps.get(id)!;
+    }
+
+    // Load manifest
+    const manifestPath = `${appPath}/app.json`;
+    const manifest = await this.loadManifest(manifestPath);
+
+    // Create managed app
+    const app: ManagedApp = {
+      id,
+      path: appPath,
+      manifest,
+      status: "loading",
+      trustLevel: this.determineTrustLevel(appPath),
+      projectId: this.projectId,
+    };
+
+    this.apps.set(id, app);
+
+    // Create runtime
+    try {
+      const runtime = new AppRuntime(app, this.projectPath);
+      await runtime.initialize();
+      this.runtimes.set(id, runtime);
+      app.status = "ready";
+    } catch (error) {
+      app.status = "error";
+      app.error = this.createError("server_load", error);
+    }
+
+    return app;
+  }
+
+  /**
+   * Activate an app (start running it)
+   */
+  async activate(appId: string): Promise<void> {
+    const app = this.apps.get(appId);
+    if (!app) {
+      throw new Error(`App not found: ${appId}`);
+    }
+
+    if (app.status !== "ready") {
+      throw new Error(`App not ready: ${appId} (status: ${app.status})`);
+    }
+
+    const runtime = this.runtimes.get(appId);
+    if (!runtime) {
+      throw new Error(`Runtime not found: ${appId}`);
+    }
+
+    try {
+      await runtime.activate();
+      app.status = "active";
+
+      // Start file watching for hot reload
+      this.startWatching(app);
+    } catch (error) {
+      app.status = "error";
+      app.error = this.createError("server_load", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Deactivate an app
+   */
+  async deactivate(appId: string): Promise<void> {
+    const app = this.apps.get(appId);
+    if (!app) return;
+
+    const runtime = this.runtimes.get(appId);
+    if (runtime) {
+      await runtime.deactivate();
+    }
+
+    this.stopWatching(appId);
+    app.status = "ready";
+  }
+
+  /**
+   * Unload an app completely
+   */
+  async unload(appId: string): Promise<void> {
+    await this.deactivate(appId);
+
+    const runtime = this.runtimes.get(appId);
+    if (runtime) {
+      await runtime.dispose();
+      this.runtimes.delete(appId);
+    }
+
+    this.apps.delete(appId);
+  }
+
+  /**
+   * Get a managed app by ID
+   */
+  get(appId: string): ManagedApp | undefined {
+    return this.apps.get(appId);
+  }
+
+  /**
+   * Get runtime for an app
+   */
+  getRuntime(appId: string): AppRuntime | undefined {
+    return this.runtimes.get(appId);
+  }
+
+  /**
+   * Get all managed apps
+   */
+  getAll(): ManagedApp[] {
+    return Array.from(this.apps.values());
+  }
+
+  /**
+   * Get active apps
+   */
+  getActive(): ManagedApp[] {
+    return this.getAll().filter((app) => app.status === "active");
+  }
+
+  /**
+   * Hot reload an app
+   */
+  async hotReload(appId: string): Promise<void> {
+    const app = this.apps.get(appId);
+    const runtime = this.runtimes.get(appId);
+
+    if (!app || !runtime) {
+      throw new Error(`App not found: ${appId}`);
+    }
+
+    try {
+      await runtime.reload();
+      app.error = undefined;
+    } catch (error) {
+      app.error = this.createError("server_load", error);
+      // Don't change status - keep showing last valid UI with error overlay
+    }
+  }
+
+  /**
+   * Cleanup all apps
+   */
+  async dispose(): Promise<void> {
+    for (const appId of this.apps.keys()) {
+      await this.unload(appId);
+    }
+  }
+
+  // ============================================================================
+  // Private Helpers
+  // ============================================================================
+
+  private generateAppId(appPath: string): string {
+    // Use relative path from project as ID
+    const relativePath = appPath.replace(this.projectPath, "").replace(/^\//, "");
+    return `app:${relativePath.replace(/\//g, ":")}`;
+  }
+
+  private async loadManifest(path: string): Promise<AppManifest> {
+    const file = Bun.file(path);
+    const content = await file.text();
+    const json = JSON.parse(content);
+    return AppManifestSchema.parse(json);
+  }
+
+  private async listDirectory(
+    path: string
+  ): Promise<Array<{ name: string; isDirectory: boolean }>> {
+    const glob = new Bun.Glob("*");
+    const entries: Array<{ name: string; isDirectory: boolean }> = [];
+
+    for await (const entry of glob.scan({ cwd: path, onlyFiles: false })) {
+      const stat = await Bun.file(`${path}/${entry}`).exists();
+      // TODO: Proper directory detection
+      entries.push({
+        name: entry,
+        isDirectory: !entry.includes("."),
+      });
+    }
+
+    return entries;
+  }
+
+  private determineTrustLevel(appPath: string): TrustLevel {
+    // Apps in the current project are development apps
+    if (appPath.startsWith(this.projectPath)) {
+      return "development";
+    }
+
+    // TODO: Check for installed apps from registry
+    // TODO: Check for signature verification
+
+    return "untrusted";
+  }
+
+  private createError(category: AppError["category"], error: unknown): AppError {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+
+    // TODO: Parse stack trace for file/line info
+
+    return {
+      category,
+      message,
+      stack,
+      recoverable: true,
+    };
+  }
+
+  private startWatching(app: ManagedApp): void {
+    this.hotReload.watch(app.id, app.path);
+  }
+
+  private stopWatching(appId: string): void {
+    this.hotReload.unwatch(appId);
+  }
+}
+
+// ============================================================================
+// Manager Registry (per project)
+// ============================================================================
+
+const managers = new Map<string, AppManager>();
+
+/**
+ * Get or create an AppManager for a project
+ */
+export function getAppManager(projectId: string, projectPath: string): AppManager {
+  let manager = managers.get(projectId);
+  if (!manager) {
+    manager = new AppManager(projectId, projectPath);
+    managers.set(projectId, manager);
+  }
+  return manager;
+}
+
+/**
+ * Dispose manager for a project
+ */
+export async function disposeAppManager(projectId: string): Promise<void> {
+  const manager = managers.get(projectId);
+  if (manager) {
+    await manager.dispose();
+    managers.delete(projectId);
+  }
+}
diff --git a/src/apps/runtime/index.ts b/src/apps/runtime/index.ts
new file mode 100644
index 0000000..26559a8
--- /dev/null
+++ b/src/apps/runtime/index.ts
@@ -0,0 +1,405 @@
+/**
+ * App Runtime
+ *
+ * Executes app code, manages state, and generates UI trees.
+ * Handles hot reloading with state preservation.
+ */
+
+import type {
+  ManagedApp,
+  AppDefinition,
+  AppContext,
+  AppToolDefinition,
+  UITree,
+  StateHandle,
+  IrisPlatformContext,
+  SDRMessage,
+  UISyncPayload,
+  AppErrorPayload,
+} from "../types.ts";
+import { generateId } from "../../utils/id.ts";
+
+type Listener = (message: SDRMessage) => void;
+
+/**
+ * App Runtime - manages a single app instance
+ */
+export class AppRuntime {
+  private app: ManagedApp;
+  private projectPath: string;
+  private definition: AppDefinition | null = null;
+  private state: Record<string, StateHandle<unknown>> = {};
+  private tools: Map<string, AppToolDefinition> = new Map();
+  private listeners: Set<Listener> = new Set();
+  private stateUnsubscribers: Array<() => void> = [];
+
+  constructor(app: ManagedApp, projectPath: string) {
+    this.app = app;
+    this.projectPath = projectPath;
+  }
+
+  /**
+   * Initialize the runtime - load the app module
+   */
+  async initialize(): Promise<void> {
+    const modulePath = `${this.app.path}/${this.app.manifest.server}`;
+    await this.loadModule(modulePath);
+  }
+
+  /**
+   * Activate the app - call onActivate hook
+   */
+  async activate(): Promise<void> {
+    if (!this.definition) {
+      throw new Error("App not initialized");
+    }
+
+    const ctx = this.createContext();
+
+    if (this.definition.onActivate) {
+      await this.definition.onActivate(ctx);
+    }
+
+    // Subscribe to state changes
+    this.subscribeToState();
+
+    // Send initial UI
+    this.broadcastUI();
+  }
+
+  /**
+   * Deactivate the app
+   */
+  async deactivate(): Promise<void> {
+    // Unsubscribe from state
+    this.stateUnsubscribers.forEach((unsub) => unsub());
+    this.stateUnsubscribers = [];
+
+    if (this.definition?.onDeactivate) {
+      const ctx = this.createContext();
+      await this.definition.onDeactivate(ctx);
+    }
+  }
+
+  /**
+   * Hot reload the app with state preservation
+   */
+  async reload(): Promise<void> {
+    // 1. Snapshot current state
+    const stateSnapshot = this.snapshotState();
+
+    // 2. Unsubscribe from state changes
+    this.stateUnsubscribers.forEach((unsub) => unsub());
+    this.stateUnsubscribers = [];
+
+    // 3. Clear module cache (Bun-specific)
+    const modulePath = `${this.app.path}/${this.app.manifest.server}`;
+    this.clearModuleCache(modulePath);
+
+    // 4. Reload module
+    await this.loadModule(modulePath);
+
+    // 5. Restore state
+    this.restoreState(stateSnapshot);
+
+    // 6. Call onReload hook
+    if (this.definition?.onReload) {
+      const ctx = this.createContext();
+      await this.definition.onReload(ctx, stateSnapshot);
+    }
+
+    // 7. Re-subscribe to state
+    this.subscribeToState();
+
+    // 8. Broadcast new UI
+    this.broadcastUI();
+
+    // 9. Notify clients of reload
+    this.broadcast({
+      id: generateId(),
+      type: "app:reload",
+      payload: {},
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Generate current UI tree
+   */
+  generateUI(): UITree {
+    if (!this.definition) {
+      return null;
+    }
+
+    try {
+      const ctx = this.createContext();
+      return this.definition.ui(ctx);
+    } catch (error) {
+      this.broadcastError("ui_generation", error);
+      return null;
+    }
+  }
+
+  /**
+   * Execute an action (tool call from UI)
+   */
+  async executeAction(action: string, args?: unknown): Promise<unknown> {
+    const tool = this.tools.get(action);
+
+    if (!tool) {
+      // Check if it's a state setter
+      if (action.startsWith("state:")) {
+        const stateName = action.slice(6);
+        const stateHandle = this.state[stateName];
+        if (stateHandle) {
+          stateHandle.set(args);
+          return;
+        }
+      }
+
+      throw new Error(`Unknown action: ${action}`);
+    }
+
+    // Validate args if tool has parameters
+    // TODO: Add Zod validation
+
+    try {
+      const ctx = this.createContext();
+      return await tool.execute(args, ctx);
+    } catch (error) {
+      this.broadcastError("action", error);
+      throw error;
+    }
+  }
+
+  /**
+   * Subscribe to runtime messages (for WebSocket bridge)
+   */
+  subscribe(listener: Listener): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  }
+
+  /**
+   * Get all tools for AI integration
+   */
+  getTools(): AppToolDefinition[] {
+    return Array.from(this.tools.values());
+  }
+
+  /**
+   * Dispose of the runtime
+   */
+  async dispose(): Promise<void> {
+    await this.deactivate();
+    this.listeners.clear();
+    this.tools.clear();
+    this.state = {};
+    this.definition = null;
+  }
+
+  // ============================================================================
+  // Private Implementation
+  // ============================================================================
+
+  private async loadModule(modulePath: string): Promise<void> {
+    try {
+      // Dynamic import with cache busting for hot reload
+      const moduleUrl = `file://${modulePath}?t=${Date.now()}`;
+      const module = await import(moduleUrl);
+
+      // Get the default export (app definition)
+      this.definition = module.default as AppDefinition;
+
+      // Initialize state
+      this.initializeState();
+
+      // Register tools
+      this.registerTools();
+    } catch (error) {
+      throw new Error(`Failed to load app module: ${error}`);
+    }
+  }
+
+  private clearModuleCache(modulePath: string): void {
+    // Bun doesn't have require.cache like Node
+    // The cache busting query string handles this
+    // TODO: Investigate Bun.Transpiler for proper module invalidation
+  }
+
+  private initializeState(): void {
+    if (!this.definition?.state) {
+      this.state = {};
+      return;
+    }
+
+    this.state = {};
+    for (const [key, factory] of Object.entries(this.definition.state)) {
+      this.state[key] = factory();
+    }
+  }
+
+  private registerTools(): void {
+    this.tools.clear();
+
+    if (!this.definition?.tools) return;
+
+    for (const tool of this.definition.tools) {
+      this.tools.set(tool.name, tool);
+    }
+  }
+
+  private subscribeToState(): void {
+    // Subscribe to all state changes to trigger UI updates
+    for (const [key, handle] of Object.entries(this.state)) {
+      const unsub = handle.subscribe(() => {
+        this.broadcastUI();
+      });
+      this.stateUnsubscribers.push(unsub);
+    }
+  }
+
+  private snapshotState(): Record<string, unknown> {
+    const snapshot: Record<string, unknown> = {};
+    for (const [key, handle] of Object.entries(this.state)) {
+      snapshot[key] = handle.toJSON();
+    }
+    return snapshot;
+  }
+
+  private restoreState(snapshot: Record<string, unknown>): void {
+    for (const [key, value] of Object.entries(snapshot)) {
+      const handle = this.state[key];
+      if (handle) {
+        handle.set(value);
+      }
+    }
+  }
+
+  private createContext(): AppContext {
+    return {
+      state: this.state,
+      runTool: (name, args) => this.executeAction(name, args),
+      iris: this.createIrisContext(),
+    };
+  }
+
+  private createIrisContext(): IrisPlatformContext {
+    // TODO: Implement actual platform integration
+    // For now, return stubs that log and throw
+
+    return {
+      ai: {
+        chat: async (messages, options) => {
+          // TODO: Connect to Iris AI service
+          console.log("[IrisApp] AI chat called:", { messages, options });
+          throw new Error("AI not yet implemented");
+        },
+      },
+
+      fs: {
+        read: async (path) => {
+          // TODO: Scoped file reading
+          const fullPath = this.resolvePath(path);
+          const file = Bun.file(fullPath);
+          return file.text();
+        },
+
+        write: async (path, content) => {
+          // TODO: Scoped file writing with permission check
+          const fullPath = this.resolvePath(path);
+          await Bun.write(fullPath, content);
+        },
+
+        list: async (path) => {
+          // TODO: Scoped directory listing
+          const fullPath = this.resolvePath(path);
+          const glob = new Bun.Glob("*");
+          const entries: Array<{ name: string; isDirectory: boolean }> = [];
+
+          for await (const entry of glob.scan({ cwd: fullPath, onlyFiles: false })) {
+            entries.push({
+              name: entry,
+              isDirectory: !entry.includes("."), // TODO: Proper detection
+            });
+          }
+
+          return entries;
+        },
+      },
+
+      navigate: (path) => {
+        // TODO: Send navigation event to Iris
+        console.log("[IrisApp] Navigate:", path);
+      },
+
+      notify: (message, options) => {
+        // TODO: Send notification to Iris
+        console.log("[IrisApp] Notify:", message, options);
+      },
+
+      project: {
+        id: this.app.projectId,
+        path: this.projectPath,
+        name: this.projectPath.split("/").pop() || "unknown",
+      },
+    };
+  }
+
+  private resolvePath(path: string): string {
+    // Handle special prefixes
+    if (path.startsWith("$PROJECT/")) {
+      return `${this.projectPath}/${path.slice(9)}`;
+    }
+    if (path.startsWith("$APP/")) {
+      return `${this.app.path}/${path.slice(5)}`;
+    }
+
+    // Relative paths are relative to project
+    if (!path.startsWith("/")) {
+      return `${this.projectPath}/${path}`;
+    }
+
+    // TODO: Validate path doesn't escape sandbox
+    return path;
+  }
+
+  private broadcast(message: SDRMessage): void {
+    this.listeners.forEach((listener) => listener(message));
+  }
+
+  private broadcastUI(): void {
+    const tree = this.generateUI();
+    const state = this.snapshotState();
+
+    const payload: UISyncPayload = { tree, state };
+
+    this.broadcast({
+      id: generateId(),
+      type: "ui:sync",
+      payload,
+      timestamp: Date.now(),
+    });
+  }
+
+  private broadcastError(category: AppErrorPayload["category"], error: unknown): void {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack : undefined;
+
+    // TODO: Parse stack for file/line info
+
+    const payload: AppErrorPayload = {
+      category,
+      message,
+      stack,
+      recoverable: true,
+    };
+
+    this.broadcast({
+      id: generateId(),
+      type: "app:error",
+      payload,
+      timestamp: Date.now(),
+    });
+  }
+}
diff --git a/src/apps/types.ts b/src/apps/types.ts
new file mode 100644
index 0000000..68fff44
--- /dev/null
+++ b/src/apps/types.ts
@@ -0,0 +1,357 @@
+/**
+ * Iris Apps Type Definitions
+ *
+ * Core types for the Iris Apps system with Server-Defined Rendering (SDR).
+ * Apps are single-file TypeScript modules that define state, tools, and UI.
+ */
+
+import { z } from "zod";
+
+// ============================================================================
+// App Manifest Schema
+// ============================================================================
+
+/**
+ * App manifest schema (app.json)
+ * Defines metadata, permissions, and configuration for an Iris App.
+ */
+export const AppManifestSchema = z.object({
+  // Identity
+  name: z
+    .string()
+    .regex(/^[a-z0-9-]+$/, "Name must be lowercase alphanumeric with dashes"),
+  displayName: z.string(),
+  version: z.string().default("0.1.0"),
+  description: z.string().optional(),
+  icon: z.string().optional(), // Emoji or icon name
+
+  // Entry points
+  server: z.string().default("server.ts"),
+
+  // UI mode (SDR is default, custom is escape hatch)
+  ui: z
+    .object({
+      mode: z.enum(["sdr", "custom"]).default("sdr"),
+      entry: z.string().optional(), // For custom mode: ui/index.html
+    })
+    .default({ mode: "sdr" }),
+
+  // Tools exposed to AI agents
+  tools: z
+    .array(
+      z.object({
+        name: z.string(),
+        description: z.string(),
+      })
+    )
+    .default([]),
+
+  // Permissions required
+  permissions: z.array(z.string()).default([]),
+
+  // Services to run in background
+  services: z
+    .array(
+      z.object({
+        name: z.string(),
+        command: z.string(),
+        autoStart: z.boolean().default(false),
+      })
+    )
+    .default([]),
+});
+
+export type AppManifest = z.infer<typeof AppManifestSchema>;
+
+// ============================================================================
+// SDR Component Tree Types
+// ============================================================================
+
+/**
+ * Action descriptor for event handlers
+ * Serialized in the component tree as { $action: "toolName", args: {...} }
+ */
+export interface ActionDescriptor {
+  $action: string;
+  args?: unknown;
+  optimistic?: Record<string, unknown>; // Optimistic state updates
+}
+
+/**
+ * Primitive prop values
+ */
+export type PropValue =
+  | string
+  | number
+  | boolean
+  | null
+  | undefined
+  | PropValue[]
+  | { [key: string]: PropValue }
+  | ActionDescriptor;
+
+/**
+ * Component node in the SDR tree
+ */
+export interface ComponentNode {
+  /** Marker to identify component nodes */
+  $: "component";
+  /** Component type from registry (e.g., "Stack", "Button") */
+  type: string;
+  /** Props passed to the component */
+  props: Record<string, PropValue>;
+  /** Child nodes */
+  children?: UIChild[];
+  /** Unique key for list rendering */
+  key?: string;
+}
+
+/**
+ * Child element in the UI tree
+ */
+export type UIChild = string | number | boolean | null | undefined | ComponentNode;
+
+/**
+ * Root UI tree returned by app's ui() function
+ */
+export type UITree = ComponentNode | null;
+
+// ============================================================================
+// App State Types
+// ============================================================================
+
+/**
+ * State handle for reactive state management
+ */
+export interface StateHandle<T> {
+  /** Get current value */
+  get(): T;
+  /** Set new value */
+  set(value: T): void;
+  /** Update with function */
+  update(updater: (prev: T) => T): void;
+  /** Subscribe to changes */
+  subscribe(listener: (value: T) => void): () => void;
+  /** Snapshot for serialization */
+  toJSON(): T;
+}
+
+/**
+ * State definition in app
+ */
+export type StateDefinition = Record<string, StateHandle<unknown>>;
+
+// ============================================================================
+// App Context Types
+// ============================================================================
+
+/**
+ * Context provided to app's ui() function and tools
+ */
+export interface AppContext {
+  /** App's reactive state */
+  state: Record<string, StateHandle<unknown>>;
+
+  /** Run a tool by name */
+  runTool(name: string, args?: unknown): Promise<unknown>;
+
+  /** Access to Iris platform */
+  iris: IrisPlatformContext;
+}
+
+/**
+ * Iris platform access (AI, filesystem, etc.)
+ */
+export interface IrisPlatformContext {
+  /** AI model access */
+  ai: {
+    chat(
+      messages: Array<{ role: "user" | "assistant" | "system"; content: string }>,
+      options?: { model?: string }
+    ): Promise<{ content: string }>;
+  };
+
+  /** Filesystem access (scoped to project) */
+  fs: {
+    read(path: string): Promise<string>;
+    write(path: string, content: string): Promise<void>;
+    list(path: string): Promise<Array<{ name: string; isDirectory: boolean }>>;
+  };
+
+  /** Navigate to a route in Iris */
+  navigate(path: string): void;
+
+  /** Show a notification */
+  notify(message: string, options?: { type?: "info" | "success" | "error" }): void;
+
+  /** Project info */
+  project: {
+    id: string;
+    path: string;
+    name: string;
+  };
+}
+
+// ============================================================================
+// App Definition Types
+// ============================================================================
+
+/**
+ * Tool definition within an app
+ */
+export interface AppToolDefinition {
+  name: string;
+  description: string;
+  parameters: z.ZodType<unknown>;
+  execute: (args: unknown, ctx: AppContext) => Promise<unknown>;
+}
+
+/**
+ * App definition returned by defineApp()
+ */
+export interface AppDefinition {
+  /** Initial state factories */
+  state?: Record<string, () => StateHandle<unknown>>;
+
+  /** Tools exposed to AI */
+  tools?: AppToolDefinition[];
+
+  /** UI generator function */
+  ui: (ctx: AppContext) => UITree;
+
+  /** Lifecycle hooks */
+  onActivate?: (ctx: AppContext) => Promise<void> | void;
+  onDeactivate?: (ctx: AppContext) => Promise<void> | void;
+  onReload?: (ctx: AppContext, previousState: Record<string, unknown>) => Promise<void> | void;
+
+  /** Services configuration */
+  services?: Array<{
+    name: string;
+    start: (ctx: AppContext) => Promise<void> | void;
+    stop: (ctx: AppContext) => Promise<void> | void;
+  }>;
+}
+
+// ============================================================================
+// App Runtime Types
+// ============================================================================
+
+/**
+ * Trust level for security model
+ */
+export type TrustLevel = "development" | "installed" | "untrusted";
+
+/**
+ * App status in the runtime
+ */
+export type AppStatus =
+  | "discovered"
+  | "loading"
+  | "ready"
+  | "active"
+  | "error"
+  | "unloading";
+
+/**
+ * Managed app instance
+ */
+export interface ManagedApp {
+  /** Unique ID (derived from path) */
+  id: string;
+  /** Absolute path to app directory */
+  path: string;
+  /** Parsed manifest */
+  manifest: AppManifest;
+  /** Current status */
+  status: AppStatus;
+  /** Trust level */
+  trustLevel: TrustLevel;
+  /** Error if status is 'error' */
+  error?: AppError;
+  /** Project ID this app belongs to */
+  projectId: string;
+}
+
+/**
+ * App error information
+ */
+export interface AppError {
+  category: "manifest" | "server_load" | "ui_generation" | "action" | "service";
+  message: string;
+  stack?: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  recoverable: boolean;
+}
+
+// ============================================================================
+// SDR Protocol Messages
+// ============================================================================
+
+/**
+ * SDR message types for client-server communication
+ */
+export type SDRMessageType =
+  | "ui:sync" // Full UI tree sync
+  | "ui:patch" // Partial update (future optimization)
+  | "state:sync" // Full state sync
+  | "state:update" // Single state update
+  | "action:call" // User action from client
+  | "action:result" // Action result
+  | "app:ready" // App initialized
+  | "app:reload" // Hot reload triggered
+  | "app:error"; // App error
+
+/**
+ * SDR message envelope
+ */
+export interface SDRMessage {
+  id: string;
+  type: SDRMessageType;
+  payload: unknown;
+  timestamp: number;
+  correlationId?: string;
+}
+
+/**
+ * UI sync payload
+ */
+export interface UISyncPayload {
+  tree: UITree;
+  state: Record<string, unknown>;
+}
+
+/**
+ * Action call payload (from client)
+ */
+export interface ActionCallPayload {
+  action: string;
+  args?: unknown;
+}
+
+/**
+ * App error payload
+ */
+export interface AppErrorPayload {
+  category: AppError["category"];
+  message: string;
+  stack?: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  recoverable: boolean;
+}
+
+// ============================================================================
+// Discovered App (before loading)
+// ============================================================================
+
+export interface DiscoveredApp {
+  /** Path to app directory */
+  path: string;
+  /** Parsed manifest */
+  manifest: AppManifest;
+  /** Trust level based on source */
+  trustLevel: TrustLevel;
+}
diff --git a/src/server/app.ts b/src/server/app.ts
index 8903766..82add3e 100644
--- a/src/server/app.ts
+++ b/src/server/app.ts
@@ -15,7 +15,7 @@
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { handleError, logger, requestId } from "./middleware/index.ts";
-import { health, auth, credentials, sessions, messages, agents, projects, tools, sessionTodos, todos, projectMissions, missions, projectTasks, tasks, projectProcesses, processes, projectServices, services, files } from "./routes/index.ts";
+import { health, auth, credentials, sessions, messages, agents, projects, tools, sessionTodos, todos, projectMissions, missions, projectTasks, tasks, projectProcesses, processes, projectServices, services, files, projectApps, apps } from "./routes/index.ts";
 import { createWebSocketHandler } from "../websocket/index.ts";
 
 /**
@@ -71,6 +71,8 @@ export function createApp() {
   app.route("/api/projects", projectServices); // Project-scoped service routes
   app.route("/api/services", services); // Individual service routes
   app.route("/api/projects", files); // Project-scoped file routes
+  app.route("/api/projects", projectApps); // Project-scoped app routes
+  app.route("/api/apps", apps); // Individual app routes
 
   // WebSocket endpoint
   // See: docs/implementation-plan/05-realtime-communication.md
diff --git a/src/server/routes/apps.ts b/src/server/routes/apps.ts
new file mode 100644
index 0000000..a33e009
--- /dev/null
+++ b/src/server/routes/apps.ts
@@ -0,0 +1,272 @@
+/**
+ * Apps API Routes
+ *
+ * REST API endpoints for managing Iris Apps within projects.
+ * Apps are discovered, loaded, and managed per-project.
+ *
+ * Project-scoped endpoints:
+ * - GET /api/projects/:projectId/apps - List apps in project
+ * - GET /api/projects/:projectId/apps/:appId - Get app details
+ * - POST /api/projects/:projectId/apps/:appId/activate - Activate app
+ * - POST /api/projects/:projectId/apps/:appId/deactivate - Deactivate app
+ * - POST /api/projects/:projectId/apps/:appId/reload - Hot reload app
+ *
+ * See: docs/apps-architecture/07-implementation-roadmap.md
+ */
+
+import { Hono } from "hono";
+import { z } from "zod";
+import { DatabaseManager } from "@/database/index.ts";
+import { ValidationError } from "@/utils/errors.ts";
+import { getAppManager, type ManagedApp } from "@/apps/index.ts";
+
+// ============================================
+// PROJECT-SCOPED ROUTES
+// ============================================
+
+const projectApps = new Hono();
+
+/**
+ * Helper to get project path from database
+ */
+function getProjectPath(projectId: string): string {
+  const db = DatabaseManager.getRootDb();
+  const project = db
+    .prepare("SELECT path FROM projects WHERE id = ?")
+    .get(projectId) as { path: string } | undefined;
+
+  if (!project) {
+    throw new ValidationError("Project not found");
+  }
+
+  return project.path;
+}
+
+/**
+ * Format app for API response
+ */
+function formatApp(app: ManagedApp) {
+  return {
+    id: app.id,
+    name: app.manifest.name,
+    displayName: app.manifest.displayName,
+    description: app.manifest.description,
+    icon: app.manifest.icon,
+    version: app.manifest.version,
+    status: app.status,
+    trustLevel: app.trustLevel,
+    path: app.path,
+    tools: app.manifest.tools,
+    error: app.error,
+  };
+}
+
+/**
+ * GET /api/projects/:projectId/apps
+ * List all apps in a project (discovers and returns)
+ */
+projectApps.get("/:projectId/apps", async (c) => {
+  const projectId = c.req.param("projectId");
+  const projectPath = getProjectPath(projectId);
+
+  const manager = getAppManager(projectId, projectPath);
+
+  // Discover apps in project
+  const discovered = await manager.discover();
+
+  // Load any newly discovered apps
+  for (const app of discovered) {
+    try {
+      await manager.load(app.path);
+    } catch (error) {
+      console.error(`[Apps] Failed to load app at ${app.path}:`, error);
+    }
+  }
+
+  // Return all managed apps
+  const apps = manager.getAll().map(formatApp);
+
+  return c.json({
+    data: apps,
+    meta: {
+      total: apps.length,
+    },
+  });
+});
+
+/**
+ * GET /api/projects/:projectId/apps/:appId
+ * Get details of a specific app
+ */
+projectApps.get("/:projectId/apps/:appId", async (c) => {
+  const projectId = c.req.param("projectId");
+  const appId = c.req.param("appId");
+  const projectPath = getProjectPath(projectId);
+
+  const manager = getAppManager(projectId, projectPath);
+  const app = manager.get(appId);
+
+  if (!app) {
+    throw new ValidationError("App not found");
+  }
+
+  // Get runtime info if available
+  const runtime = manager.getRuntime(appId);
+  const tools = runtime?.getTools() ?? [];
+
+  return c.json({
+    data: {
+      ...formatApp(app),
+      tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+      })),
+    },
+  });
+});
+
+/**
+ * POST /api/projects/:projectId/apps/:appId/activate
+ * Activate an app (start running it)
+ */
+projectApps.post("/:projectId/apps/:appId/activate", async (c) => {
+  const projectId = c.req.param("projectId");
+  const appId = c.req.param("appId");
+  const projectPath = getProjectPath(projectId);
+
+  const manager = getAppManager(projectId, projectPath);
+  const app = manager.get(appId);
+
+  if (!app) {
+    throw new ValidationError("App not found");
+  }
+
+  await manager.activate(appId);
+
+  return c.json({
+    data: formatApp(manager.get(appId)!),
+  });
+});
+
+/**
+ * POST /api/projects/:projectId/apps/:appId/deactivate
+ * Deactivate an app
+ */
+projectApps.post("/:projectId/apps/:appId/deactivate", async (c) => {
+  const projectId = c.req.param("projectId");
+  const appId = c.req.param("appId");
+  const projectPath = getProjectPath(projectId);
+
+  const manager = getAppManager(projectId, projectPath);
+  const app = manager.get(appId);
+
+  if (!app) {
+    throw new ValidationError("App not found");
+  }
+
+  await manager.deactivate(appId);
+
+  return c.json({
+    data: formatApp(manager.get(appId)!),
+  });
+});
+
+/**
+ * POST /api/projects/:projectId/apps/:appId/reload
+ * Hot reload an app
+ */
+projectApps.post("/:projectId/apps/:appId/reload", async (c) => {
+  const projectId = c.req.param("projectId");
+  const appId = c.req.param("appId");
+  const projectPath = getProjectPath(projectId);
+
+  const manager = getAppManager(projectId, projectPath);
+  const app = manager.get(appId);
+
+  if (!app) {
+    throw new ValidationError("App not found");
+  }
+
+  await manager.hotReload(appId);
+
+  return c.json({
+    data: formatApp(manager.get(appId)!),
+  });
+});
+
+/**
+ * POST /api/projects/:projectId/apps/:appId/action
+ * Execute an action on an app (tool call)
+ */
+const ActionSchema = z.object({
+  action: z.string(),
+  args: z.unknown().optional(),
+});
+
+projectApps.post("/:projectId/apps/:appId/action", async (c) => {
+  const projectId = c.req.param("projectId");
+  const appId = c.req.param("appId");
+  const projectPath = getProjectPath(projectId);
+  const body = await c.req.json();
+
+  const result = ActionSchema.safeParse(body);
+  if (!result.success) {
+    throw new ValidationError("Invalid action request");
+  }
+
+  const manager = getAppManager(projectId, projectPath);
+  const runtime = manager.getRuntime(appId);
+
+  if (!runtime) {
+    throw new ValidationError("App not active");
+  }
+
+  const actionResult = await runtime.executeAction(
+    result.data.action,
+    result.data.args
+  );
+
+  return c.json({
+    data: actionResult,
+  });
+});
+
+/**
+ * GET /api/projects/:projectId/apps/:appId/ui
+ * Get current UI tree for an app
+ */
+projectApps.get("/:projectId/apps/:appId/ui", async (c) => {
+  const projectId = c.req.param("projectId");
+  const appId = c.req.param("appId");
+  const projectPath = getProjectPath(projectId);
+
+  const manager = getAppManager(projectId, projectPath);
+  const runtime = manager.getRuntime(appId);
+
+  if (!runtime) {
+    throw new ValidationError("App not active");
+  }
+
+  const tree = runtime.generateUI();
+
+  return c.json({
+    data: {
+      tree,
+    },
+  });
+});
+
+// ============================================
+// INDIVIDUAL APP ROUTES (future use)
+// ============================================
+
+const apps = new Hono();
+
+// Placeholder for future global app operations
+apps.get("/", async (c) => {
+  return c.json({
+    message: "Use project-scoped routes: /api/projects/:projectId/apps",
+  });
+});
+
+export { projectApps, apps };
diff --git a/src/server/routes/index.ts b/src/server/routes/index.ts
index b6ecb52..5581857 100644
--- a/src/server/routes/index.ts
+++ b/src/server/routes/index.ts
@@ -11,3 +11,4 @@ export { sessionTasks as sessionTodos, tasks as todos, projectTasks, tasks } fro
 export { projectProcesses, processes } from "./processes.ts";
 export { projectServices, services } from "./services.ts";
 export { default as files } from "./files.ts";
+export { projectApps, apps } from "./apps.ts";
diff --git a/src/websocket/handlers/apps.ts b/src/websocket/handlers/apps.ts
new file mode 100644
index 0000000..06b35f4
--- /dev/null
+++ b/src/websocket/handlers/apps.ts
@@ -0,0 +1,245 @@
+/**
+ * App WebSocket Handlers
+ *
+ * Handles WebSocket messages for Iris Apps.
+ * Supports real-time UI synchronization and action execution.
+ *
+ * Request types:
+ * - app.subscribe: Subscribe to app UI updates
+ * - app.unsubscribe: Unsubscribe from app updates
+ * - app.action: Execute an action on an app
+ * - app.activate: Activate an app
+ * - app.deactivate: Deactivate an app
+ */
+
+import type { WSData } from "../connections.ts";
+import { RoomManager } from "../rooms.ts";
+import { createEvent } from "../protocol.ts";
+import { ConnectionManager } from "../connections.ts";
+import { getAppManager } from "@/apps/index.ts";
+import { DatabaseManager } from "@/database/index.ts";
+
+/**
+ * Get the room name for an app
+ */
+export function getAppRoom(projectId: string, appId: string): string {
+  return `app:${projectId}:${appId}`;
+}
+
+/**
+ * Get project path from database
+ */
+function getProjectPath(projectId: string): string | null {
+  try {
+    const db = DatabaseManager.getRootDb();
+    const project = db
+      .prepare("SELECT path FROM projects WHERE id = ?")
+      .get(projectId) as { path: string } | undefined;
+    return project?.path ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * App WebSocket handlers
+ */
+export const AppHandlers = {
+  /**
+   * Subscribe to app UI updates
+   */
+  async subscribe(
+    payload: { appId: string },
+    userData: WSData
+  ): Promise<{ subscribed: boolean; ui?: unknown }> {
+    const { appId } = payload;
+    const { projectId, connectionId } = userData;
+
+    const projectPath = getProjectPath(projectId);
+    if (!projectPath) {
+      throw new Error("Project not found");
+    }
+
+    const manager = getAppManager(projectId, projectPath);
+    const app = manager.get(appId);
+
+    if (!app) {
+      throw new Error("App not found");
+    }
+
+    // Join the app room
+    const room = getAppRoom(projectId, appId);
+    RoomManager.join(room, connectionId);
+
+    // Get current UI if app is active
+    const runtime = manager.getRuntime(appId);
+    let ui = null;
+
+    if (runtime) {
+      ui = runtime.generateUI();
+
+      // Subscribe to runtime updates
+      runtime.subscribe((message) => {
+        // Broadcast to all subscribers in the room
+        broadcastToRoom(room, message.type, message.payload);
+      });
+    }
+
+    return {
+      subscribed: true,
+      ui,
+    };
+  },
+
+  /**
+   * Unsubscribe from app UI updates
+   */
+  async unsubscribe(
+    payload: { appId: string },
+    userData: WSData
+  ): Promise<{ unsubscribed: boolean }> {
+    const { appId } = payload;
+    const { projectId, connectionId } = userData;
+
+    const room = getAppRoom(projectId, appId);
+    RoomManager.leave(room, connectionId);
+
+    return { unsubscribed: true };
+  },
+
+  /**
+   * Execute an action on an app
+   */
+  async action(
+    payload: { appId: string; action: string; args?: unknown },
+    userData: WSData
+  ): Promise<unknown> {
+    const { appId, action, args } = payload;
+    const { projectId } = userData;
+
+    const projectPath = getProjectPath(projectId);
+    if (!projectPath) {
+      throw new Error("Project not found");
+    }
+
+    const manager = getAppManager(projectId, projectPath);
+    const runtime = manager.getRuntime(appId);
+
+    if (!runtime) {
+      throw new Error("App not active");
+    }
+
+    // Execute the action
+    const result = await runtime.executeAction(action, args);
+
+    return result;
+  },
+
+  /**
+   * Activate an app
+   */
+  async activate(
+    payload: { appId: string },
+    userData: WSData
+  ): Promise<{ status: string }> {
+    const { appId } = payload;
+    const { projectId, connectionId } = userData;
+
+    const projectPath = getProjectPath(projectId);
+    if (!projectPath) {
+      throw new Error("Project not found");
+    }
+
+    const manager = getAppManager(projectId, projectPath);
+    const app = manager.get(appId);
+
+    if (!app) {
+      throw new Error("App not found");
+    }
+
+    await manager.activate(appId);
+
+    // Auto-subscribe the activating connection
+    const room = getAppRoom(projectId, appId);
+    RoomManager.join(room, connectionId);
+
+    // Set up broadcast for this app
+    const runtime = manager.getRuntime(appId);
+    if (runtime) {
+      runtime.subscribe((message) => {
+        broadcastToRoom(room, message.type, message.payload);
+      });
+    }
+
+    return { status: "active" };
+  },
+
+  /**
+   * Deactivate an app
+   */
+  async deactivate(
+    payload: { appId: string },
+    userData: WSData
+  ): Promise<{ status: string }> {
+    const { appId } = payload;
+    const { projectId } = userData;
+
+    const projectPath = getProjectPath(projectId);
+    if (!projectPath) {
+      throw new Error("Project not found");
+    }
+
+    const manager = getAppManager(projectId, projectPath);
+    await manager.deactivate(appId);
+
+    // Notify all subscribers
+    const room = getAppRoom(projectId, appId);
+    broadcastToRoom(room, "app.deactivated", { appId });
+
+    return { status: "deactivated" };
+  },
+
+  /**
+   * Request hot reload
+   */
+  async reload(
+    payload: { appId: string },
+    userData: WSData
+  ): Promise<{ status: string }> {
+    const { appId } = payload;
+    const { projectId } = userData;
+
+    const projectPath = getProjectPath(projectId);
+    if (!projectPath) {
+      throw new Error("Project not found");
+    }
+
+    const manager = getAppManager(projectId, projectPath);
+    await manager.hotReload(appId);
+
+    return { status: "reloaded" };
+  },
+};
+
+/**
+ * Broadcast a message to all connections in a room
+ */
+function broadcastToRoom(room: string, type: string, payload: unknown): void {
+  const connectionIds = RoomManager.getMembers(room);
+
+  for (const connectionId of connectionIds) {
+    const info = ConnectionManager.get(connectionId);
+    if (info?.ws) {
+      try {
+        info.ws.send(
+          JSON.stringify({
+            type: `app.${type}`,
+            payload,
+          })
+        );
+      } catch (error) {
+        console.error(`[Apps] Failed to send to ${connectionId}:`, error);
+      }
+    }
+  }
+}
diff --git a/src/websocket/handlers/index.ts b/src/websocket/handlers/index.ts
index 14ee517..646b5e5 100644
--- a/src/websocket/handlers/index.ts
+++ b/src/websocket/handlers/index.ts
@@ -12,6 +12,7 @@ import { MessageHandlers } from "./messages.ts";
 import { ToolHandlers } from "./tools.ts";
 import { SubscriptionHandlers } from "./subscriptions.ts";
 import { ProcessHandlers } from "./processes.ts";
+import { AppHandlers } from "./apps.ts";
 
 /**
  * Handler function type
@@ -46,6 +47,14 @@ const handlers: Record<RequestType, Handler> = {
   "process.resize": ProcessHandlers.resize,
   "process.kill": ProcessHandlers.kill,
 
+  // App handlers
+  "app.subscribe": AppHandlers.subscribe,
+  "app.unsubscribe": AppHandlers.unsubscribe,
+  "app.action": AppHandlers.action,
+  "app.activate": AppHandlers.activate,
+  "app.deactivate": AppHandlers.deactivate,
+  "app.reload": AppHandlers.reload,
+
   // Ping handler
   ping: async () => ({ pong: Date.now() }),
 };
@@ -72,3 +81,4 @@ export { MessageHandlers } from "./messages.ts";
 export { ToolHandlers, registerPendingApproval, removePendingApproval } from "./tools.ts";
 export { SubscriptionHandlers } from "./subscriptions.ts";
 export { ProcessHandlers } from "./processes.ts";
+export { AppHandlers, getAppRoom } from "./apps.ts";
diff --git a/src/websocket/index.ts b/src/websocket/index.ts
index 438ebc9..b1e151a 100644
--- a/src/websocket/index.ts
+++ b/src/websocket/index.ts
@@ -48,6 +48,7 @@ export {
   removePendingApproval,
 } from "./handlers/tools.ts";
 export { SubscriptionHandlers } from "./handlers/subscriptions.ts";
+export { AppHandlers, getAppRoom } from "./handlers/apps.ts";
 
 // Event bus bridge
 export {
diff --git a/src/websocket/protocol.ts b/src/websocket/protocol.ts
index 5f9a427..b79d7d0 100644
--- a/src/websocket/protocol.ts
+++ b/src/websocket/protocol.ts
@@ -44,6 +44,14 @@ export const RequestType = z.enum([
   "process.resize",
   "process.kill",
 
+  // App operations
+  "app.subscribe",
+  "app.unsubscribe",
+  "app.action",
+  "app.activate",
+  "app.deactivate",
+  "app.reload",
+
   // Ping/pong
   "ping",
 ]);
@@ -128,6 +136,36 @@ export const ProcessKillPayload = z.object({
   id: z.string(),
 });
 
+// ============================================================================
+// App Payloads
+// ============================================================================
+
+export const AppSubscribePayload = z.object({
+  appId: z.string(),
+});
+
+export const AppUnsubscribePayload = z.object({
+  appId: z.string(),
+});
+
+export const AppActionPayload = z.object({
+  appId: z.string(),
+  action: z.string(),
+  args: z.unknown().optional(),
+});
+
+export const AppActivatePayload = z.object({
+  appId: z.string(),
+});
+
+export const AppDeactivatePayload = z.object({
+  appId: z.string(),
+});
+
+export const AppReloadPayload = z.object({
+  appId: z.string(),
+});
+
 // ============================================================================
 // Request Message
 // ============================================================================
@@ -230,6 +268,15 @@ export const EventType = z.enum([
   "process.output",
   "process.exited",
   "process.killed",
+
+  // App events
+  "app.ui.sync",
+  "app.ui.patch",
+  "app.state.update",
+  "app.error",
+  "app.reloaded",
+  "app.activated",
+  "app.deactivated",
 ]);
 
 export type EventType = z.infer<typeof EventType>;
diff --git a/webui/src/components/apps/AppHost.tsx b/webui/src/components/apps/AppHost.tsx
new file mode 100644
index 0000000..4671702
--- /dev/null
+++ b/webui/src/components/apps/AppHost.tsx
@@ -0,0 +1,376 @@
+/**
+ * App Host
+ *
+ * Hosts an Iris App, managing the WebSocket connection for real-time
+ * UI updates and action handling.
+ */
+
+import React, { useEffect, useState, useCallback, useRef } from "react";
+import { SDRRenderer } from "./SDRRenderer";
+
+// Types
+interface ComponentNode {
+  $: "component";
+  type: string;
+  props: Record<string, unknown>;
+  children?: unknown[];
+  key?: string;
+}
+
+interface UISyncPayload {
+  tree: ComponentNode | null;
+  state: Record<string, unknown>;
+}
+
+interface AppErrorPayload {
+  category: string;
+  message: string;
+  stack?: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  recoverable: boolean;
+}
+
+interface SDRMessage {
+  id: string;
+  type: string;
+  payload: unknown;
+  timestamp: number;
+}
+
+interface AppHostProps {
+  /** App ID */
+  appId: string;
+  /** Project ID */
+  projectId: string;
+  /** WebSocket URL for the app */
+  wsUrl?: string;
+}
+
+type ConnectionStatus = "connecting" | "connected" | "disconnected" | "error";
+
+/**
+ * App Host Component
+ *
+ * Manages connection to an Iris App and renders its UI.
+ */
+export function AppHost({ appId, projectId, wsUrl }: AppHostProps) {
+  const [tree, setTree] = useState<ComponentNode | null>(null);
+  const [state, setState] = useState<Record<string, unknown>>({});
+  const [error, setError] = useState<AppErrorPayload | null>(null);
+  const [status, setStatus] = useState<ConnectionStatus>("connecting");
+  const [lastValidTree, setLastValidTree] = useState<ComponentNode | null>(null);
+
+  const wsRef = useRef<WebSocket | null>(null);
+  const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
+  const reconnectAttempts = useRef(0);
+
+  // Connect to the app's WebSocket
+  useEffect(() => {
+    const url = wsUrl || `/api/apps/${projectId}/${appId}/ws`;
+
+    function connect() {
+      setStatus("connecting");
+
+      // TODO: Use actual WebSocket URL
+      // For now, we'll simulate the connection
+      console.log(`[AppHost] Connecting to ${url}`);
+
+      // Simulate connection for development
+      // In production, this would be:
+      // const ws = new WebSocket(url);
+
+      // Mock successful connection
+      setTimeout(() => {
+        setStatus("connected");
+        reconnectAttempts.current = 0;
+
+        // TODO: Remove mock data - this simulates receiving initial UI
+        // In production, this comes from the WebSocket
+      }, 500);
+    }
+
+    connect();
+
+    return () => {
+      if (wsRef.current) {
+        wsRef.current.close();
+      }
+      if (reconnectTimeoutRef.current) {
+        clearTimeout(reconnectTimeoutRef.current);
+      }
+    };
+  }, [appId, projectId, wsUrl]);
+
+  // Handle incoming messages
+  const handleMessage = useCallback((message: SDRMessage) => {
+    switch (message.type) {
+      case "ui:sync": {
+        const payload = message.payload as UISyncPayload;
+        setTree(payload.tree);
+        setState(payload.state);
+        setError(null);
+
+        // Store last valid tree for error recovery
+        if (payload.tree) {
+          setLastValidTree(payload.tree);
+        }
+        break;
+      }
+
+      case "app:error": {
+        const payload = message.payload as AppErrorPayload;
+        setError(payload);
+        // Keep showing last valid UI with error overlay
+        break;
+      }
+
+      case "app:reload": {
+        // App was hot-reloaded, UI sync will follow
+        console.log("[AppHost] App reloaded");
+        break;
+      }
+
+      case "state:update": {
+        // Partial state update
+        const { key, value } = message.payload as { key: string; value: unknown };
+        setState((prev) => ({ ...prev, [key]: value }));
+        break;
+      }
+
+      default:
+        console.warn("[AppHost] Unknown message type:", message.type);
+    }
+  }, []);
+
+  // Send action to the server
+  const handleAction = useCallback(
+    (action: string, args?: unknown) => {
+      console.log("[AppHost] Action:", action, args);
+
+      // TODO: Send via WebSocket
+      // wsRef.current?.send(JSON.stringify({
+      //   type: "action:call",
+      //   payload: { action, args },
+      //   id: generateId(),
+      //   timestamp: Date.now(),
+      // }));
+
+      // For now, simulate action handling
+      // This would normally go to the server and come back via ui:sync
+    },
+    []
+  );
+
+  // Render loading state
+  if (status === "connecting") {
+    return (
+      <div style={styles.container}>
+        <div style={styles.loading}>
+          <div style={styles.spinner} />
+          <p>Connecting to app...</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Render error state (connection error)
+  if (status === "error") {
+    return (
+      <div style={styles.container}>
+        <div style={styles.errorContainer}>
+          <h3>Connection Error</h3>
+          <p>Failed to connect to the app. Retrying...</p>
+        </div>
+      </div>
+    );
+  }
+
+  // Render app UI
+  const displayTree = tree || lastValidTree;
+
+  return (
+    <div style={styles.container}>
+      {/* Error overlay */}
+      {error && (
+        <div style={styles.errorOverlay}>
+          <div style={styles.errorContent}>
+            <div style={styles.errorHeader}>
+              <span style={styles.errorBadge}>{error.category}</span>
+              <h3 style={styles.errorTitle}>Error in app</h3>
+            </div>
+            <p style={styles.errorMessage}>{error.message}</p>
+            {error.file && (
+              <p style={styles.errorLocation}>
+                {error.file}
+                {error.line && `:${error.line}`}
+                {error.column && `:${error.column}`}
+              </p>
+            )}
+            {error.stack && (
+              <pre style={styles.errorStack}>{error.stack}</pre>
+            )}
+            <button
+              style={styles.errorButton}
+              onClick={() => {
+                // TODO: Open file in editor
+                console.log("Open in editor:", error.file);
+              }}
+            >
+              Open in Editor
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* App content */}
+      {displayTree ? (
+        <SDRRenderer tree={displayTree} onAction={handleAction} state={state} />
+      ) : (
+        <div style={styles.empty}>
+          <p>App loaded but no UI returned</p>
+          <p style={{ fontSize: 12, color: "#888" }}>
+            Make sure your app's ui() function returns a component tree
+          </p>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// Styles
+const styles: Record<string, React.CSSProperties> = {
+  container: {
+    position: "relative",
+    width: "100%",
+    height: "100%",
+    overflow: "auto",
+  },
+
+  loading: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    height: "100%",
+    gap: 16,
+    color: "#666",
+  },
+
+  spinner: {
+    width: 32,
+    height: 32,
+    border: "3px solid #e5e5e5",
+    borderTopColor: "#0066cc",
+    borderRadius: "50%",
+    animation: "spin 1s linear infinite",
+  },
+
+  empty: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    height: "100%",
+    color: "#888",
+    textAlign: "center",
+    padding: 24,
+  },
+
+  errorContainer: {
+    display: "flex",
+    flexDirection: "column",
+    alignItems: "center",
+    justifyContent: "center",
+    height: "100%",
+    color: "#dc3545",
+    textAlign: "center",
+    padding: 24,
+  },
+
+  errorOverlay: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    backgroundColor: "rgba(220, 53, 69, 0.95)",
+    color: "white",
+    padding: 16,
+    zIndex: 1000,
+    boxShadow: "0 4px 12px rgba(0,0,0,0.2)",
+  },
+
+  errorContent: {
+    maxWidth: 600,
+    margin: "0 auto",
+  },
+
+  errorHeader: {
+    display: "flex",
+    alignItems: "center",
+    gap: 12,
+    marginBottom: 12,
+  },
+
+  errorBadge: {
+    backgroundColor: "rgba(255,255,255,0.2)",
+    padding: "2px 8px",
+    borderRadius: 4,
+    fontSize: 12,
+    textTransform: "uppercase",
+  },
+
+  errorTitle: {
+    margin: 0,
+    fontSize: 18,
+  },
+
+  errorMessage: {
+    fontSize: 14,
+    margin: "0 0 8px 0",
+    fontWeight: 500,
+  },
+
+  errorLocation: {
+    fontSize: 12,
+    margin: "0 0 12px 0",
+    fontFamily: "monospace",
+    opacity: 0.9,
+  },
+
+  errorStack: {
+    fontSize: 11,
+    fontFamily: "monospace",
+    backgroundColor: "rgba(0,0,0,0.2)",
+    padding: 12,
+    borderRadius: 4,
+    overflow: "auto",
+    maxHeight: 150,
+    whiteSpace: "pre-wrap",
+    margin: "0 0 12px 0",
+  },
+
+  errorButton: {
+    backgroundColor: "white",
+    color: "#dc3545",
+    border: "none",
+    padding: "8px 16px",
+    borderRadius: 4,
+    fontWeight: 500,
+    cursor: "pointer",
+  },
+};
+
+// Add keyframe animation via a style tag
+if (typeof document !== "undefined") {
+  const styleSheet = document.createElement("style");
+  styleSheet.textContent = `
+    @keyframes spin {
+      to { transform: rotate(360deg); }
+    }
+  `;
+  document.head.appendChild(styleSheet);
+}
+
+export default AppHost;
diff --git a/webui/src/components/apps/SDRRenderer.tsx b/webui/src/components/apps/SDRRenderer.tsx
new file mode 100644
index 0000000..e9dcde4
--- /dev/null
+++ b/webui/src/components/apps/SDRRenderer.tsx
@@ -0,0 +1,799 @@
+/**
+ * SDR Renderer
+ *
+ * Renders Server-Defined Rendering component trees into React components.
+ * This is the client-side counterpart to the @iris/ui server-side functions.
+ */
+
+import React from "react";
+import type { ReactNode } from "react";
+
+// Types from the apps system
+interface ComponentNode {
+  $: "component";
+  type: string;
+  props: Record<string, unknown>;
+  children?: UIChild[];
+  key?: string;
+}
+
+type UIChild = string | number | boolean | null | undefined | ComponentNode;
+
+interface ActionDescriptor {
+  $action: string;
+  args?: unknown;
+}
+
+interface SDRRendererProps {
+  tree: ComponentNode | null;
+  onAction: (action: string, args?: unknown) => void;
+  state?: Record<string, unknown>;
+}
+
+// ============================================================================
+// Component Registry
+// ============================================================================
+
+// Map of component type names to React components
+const componentRegistry: Record<
+  string,
+  React.ComponentType<{ children?: ReactNode; [key: string]: unknown }>
+> = {};
+
+/**
+ * Register a component in the SDR registry
+ */
+export function registerComponent(
+  name: string,
+  component: React.ComponentType<{ children?: ReactNode; [key: string]: unknown }>
+): void {
+  componentRegistry[name] = component;
+}
+
+/**
+ * Get a component from the registry
+ */
+export function getComponent(name: string): React.ComponentType<{ children?: ReactNode; [key: string]: unknown }> | undefined {
+  return componentRegistry[name];
+}
+
+// ============================================================================
+// Built-in Components
+// ============================================================================
+
+// Layout Components
+registerComponent("Stack", ({ children, gap, padding, paddingX, paddingY, align, justify, flex, ...rest }) => (
+  <div
+    style={{
+      display: "flex",
+      flexDirection: "column",
+      gap: gap as number,
+      padding: padding as number,
+      paddingLeft: paddingX as number,
+      paddingRight: paddingX as number,
+      paddingTop: paddingY as number,
+      paddingBottom: paddingY as number,
+      alignItems: mapAlign(align as string),
+      justifyContent: mapJustify(justify as string),
+      flex: flex as number,
+    }}
+    {...rest}
+  >
+    {children}
+  </div>
+));
+
+registerComponent("Row", ({ children, gap, padding, paddingX, paddingY, align, justify, wrap, flex, ...rest }) => (
+  <div
+    style={{
+      display: "flex",
+      flexDirection: "row",
+      gap: gap as number,
+      padding: padding as number,
+      paddingLeft: paddingX as number,
+      paddingRight: paddingX as number,
+      paddingTop: paddingY as number,
+      paddingBottom: paddingY as number,
+      alignItems: mapAlign(align as string),
+      justifyContent: mapJustify(justify as string),
+      flexWrap: wrap ? "wrap" : undefined,
+      flex: flex as number,
+    }}
+    {...rest}
+  >
+    {children}
+  </div>
+));
+
+registerComponent("Box", ({ children, padding, paddingX, paddingY, margin, marginX, marginY, flex, width, height, backgroundColor, borderRadius, border, ...rest }) => (
+  <div
+    style={{
+      padding: padding as number,
+      paddingLeft: paddingX as number,
+      paddingRight: paddingX as number,
+      paddingTop: paddingY as number,
+      paddingBottom: paddingY as number,
+      margin: margin as number,
+      marginLeft: marginX as number,
+      marginRight: marginX as number,
+      marginTop: marginY as number,
+      marginBottom: marginY as number,
+      flex: flex as number,
+      width: width as string | number,
+      height: height as string | number,
+      backgroundColor: backgroundColor as string,
+      borderRadius: borderRadius as number,
+      border: border as string,
+    }}
+    {...rest}
+  >
+    {children}
+  </div>
+));
+
+registerComponent("ScrollView", ({ children, horizontal, flex, ...rest }) => (
+  <div
+    style={{
+      overflow: "auto",
+      overflowX: horizontal ? "auto" : undefined,
+      overflowY: horizontal ? undefined : "auto",
+      flex: flex as number,
+    }}
+    {...rest}
+  >
+    {children}
+  </div>
+));
+
+registerComponent("Divider", ({ margin }) => (
+  <hr
+    style={{
+      border: "none",
+      borderTop: "1px solid var(--border-color, #e5e5e5)",
+      margin: `${margin ?? 8}px 0`,
+    }}
+  />
+));
+
+// Typography Components
+registerComponent("Text", ({ children, size, weight, color, align, italic, mono, ...rest }) => (
+  <span
+    style={{
+      fontSize: mapFontSize(size as string),
+      fontWeight: mapFontWeight(weight as string),
+      color: color as string,
+      textAlign: align as "left" | "center" | "right",
+      fontStyle: italic ? "italic" : undefined,
+      fontFamily: mono ? "monospace" : undefined,
+    }}
+    {...rest}
+  >
+    {children}
+  </span>
+));
+
+registerComponent("Heading", ({ children, level = 2, color, ...rest }) => {
+  const Tag = `h${level}` as keyof JSX.IntrinsicElements;
+  return (
+    <Tag style={{ color: color as string, margin: "0 0 0.5em 0" }} {...rest}>
+      {children}
+    </Tag>
+  );
+});
+
+registerComponent("Code", ({ children, language, inline, ...rest }) => {
+  if (inline) {
+    return (
+      <code
+        style={{
+          fontFamily: "monospace",
+          backgroundColor: "var(--code-bg, #f5f5f5)",
+          padding: "2px 6px",
+          borderRadius: 4,
+        }}
+        {...rest}
+      >
+        {children}
+      </code>
+    );
+  }
+  return (
+    <pre
+      style={{
+        fontFamily: "monospace",
+        backgroundColor: "var(--code-bg, #1e1e1e)",
+        color: "var(--code-color, #d4d4d4)",
+        padding: 16,
+        borderRadius: 8,
+        overflow: "auto",
+      }}
+      {...rest}
+    >
+      <code>{children}</code>
+    </pre>
+  );
+});
+
+registerComponent("Link", ({ children, href, external, ...rest }) => (
+  <a
+    href={href as string}
+    target={external ? "_blank" : undefined}
+    rel={external ? "noopener noreferrer" : undefined}
+    style={{ color: "var(--link-color, #0066cc)" }}
+    {...rest}
+  >
+    {children}
+  </a>
+));
+
+// Form Components
+registerComponent("Button", ({ children, variant = "primary", size = "md", disabled, loading, onPress, ...rest }) => (
+  <button
+    disabled={disabled as boolean || loading as boolean}
+    style={{
+      padding: size === "sm" ? "4px 12px" : size === "lg" ? "12px 24px" : "8px 16px",
+      fontSize: size === "sm" ? 12 : size === "lg" ? 16 : 14,
+      borderRadius: 6,
+      border: variant === "outline" ? "1px solid currentColor" : "none",
+      backgroundColor:
+        variant === "primary" ? "var(--primary-color, #0066cc)" :
+        variant === "danger" ? "var(--danger-color, #dc3545)" :
+        variant === "ghost" || variant === "outline" ? "transparent" :
+        "var(--secondary-color, #6c757d)",
+      color: variant === "ghost" || variant === "outline" ? "inherit" : "white",
+      cursor: disabled ? "not-allowed" : "pointer",
+      opacity: disabled ? 0.5 : 1,
+    }}
+    {...rest}
+  >
+    {loading ? "..." : children}
+  </button>
+));
+
+registerComponent("Input", ({ value, placeholder, type = "text", disabled, multiline, rows, onChangeText, onSubmit, ...rest }) => {
+  if (multiline) {
+    return (
+      <textarea
+        value={value as string}
+        placeholder={placeholder as string}
+        disabled={disabled as boolean}
+        rows={rows as number || 3}
+        style={{
+          padding: 8,
+          borderRadius: 6,
+          border: "1px solid var(--border-color, #ccc)",
+          fontFamily: "inherit",
+          fontSize: 14,
+          resize: "vertical",
+        }}
+        {...rest}
+      />
+    );
+  }
+  return (
+    <input
+      type={type as string}
+      value={value as string}
+      placeholder={placeholder as string}
+      disabled={disabled as boolean}
+      style={{
+        padding: 8,
+        borderRadius: 6,
+        border: "1px solid var(--border-color, #ccc)",
+        fontSize: 14,
+      }}
+      {...rest}
+    />
+  );
+});
+
+registerComponent("TextArea", ({ value, placeholder, disabled, rows, ...rest }) => (
+  <textarea
+    value={value as string}
+    placeholder={placeholder as string}
+    disabled={disabled as boolean}
+    rows={rows as number || 3}
+    style={{
+      padding: 8,
+      borderRadius: 6,
+      border: "1px solid var(--border-color, #ccc)",
+      fontFamily: "inherit",
+      fontSize: 14,
+      resize: "vertical",
+    }}
+    {...rest}
+  />
+));
+
+registerComponent("Select", ({ value, options, placeholder, disabled, onChange, ...rest }) => (
+  <select
+    value={value as string}
+    disabled={disabled as boolean}
+    style={{
+      padding: 8,
+      borderRadius: 6,
+      border: "1px solid var(--border-color, #ccc)",
+      fontSize: 14,
+    }}
+    {...rest}
+  >
+    {placeholder && <option value="">{placeholder}</option>}
+    {(options as Array<{ value: string; label: string }>)?.map((opt) => (
+      <option key={opt.value} value={opt.value}>
+        {opt.label}
+      </option>
+    ))}
+  </select>
+));
+
+registerComponent("Checkbox", ({ checked, label, disabled, onChange, ...rest }) => (
+  <label style={{ display: "flex", alignItems: "center", gap: 8, cursor: disabled ? "not-allowed" : "pointer" }}>
+    <input
+      type="checkbox"
+      checked={checked as boolean}
+      disabled={disabled as boolean}
+      {...rest}
+    />
+    {label}
+  </label>
+));
+
+registerComponent("Switch", ({ value, disabled, onChange, ...rest }) => (
+  <button
+    role="switch"
+    aria-checked={value as boolean}
+    disabled={disabled as boolean}
+    style={{
+      width: 44,
+      height: 24,
+      borderRadius: 12,
+      border: "none",
+      backgroundColor: value ? "var(--primary-color, #0066cc)" : "var(--border-color, #ccc)",
+      position: "relative",
+      cursor: disabled ? "not-allowed" : "pointer",
+    }}
+    {...rest}
+  >
+    <span
+      style={{
+        position: "absolute",
+        top: 2,
+        left: value ? 22 : 2,
+        width: 20,
+        height: 20,
+        borderRadius: 10,
+        backgroundColor: "white",
+        transition: "left 0.2s",
+      }}
+    />
+  </button>
+));
+
+// Data Display Components
+registerComponent("DataTable", ({ data, columns, onRowPress, ...rest }) => {
+  const tableData = data as Array<Record<string, unknown>>;
+  const tableColumns = columns as Array<{ key: string; label: string; width?: number | string }> ||
+    (tableData[0] ? Object.keys(tableData[0]).map((key) => ({ key, label: key })) : []);
+
+  return (
+    <table style={{ width: "100%", borderCollapse: "collapse" }} {...rest}>
+      <thead>
+        <tr>
+          {tableColumns.map((col) => (
+            <th
+              key={col.key}
+              style={{
+                textAlign: "left",
+                padding: 8,
+                borderBottom: "2px solid var(--border-color, #e5e5e5)",
+                width: col.width,
+              }}
+            >
+              {col.label}
+            </th>
+          ))}
+        </tr>
+      </thead>
+      <tbody>
+        {tableData.map((row, i) => (
+          <tr key={i} style={{ cursor: onRowPress ? "pointer" : undefined }}>
+            {tableColumns.map((col) => (
+              <td
+                key={col.key}
+                style={{
+                  padding: 8,
+                  borderBottom: "1px solid var(--border-color, #e5e5e5)",
+                }}
+              >
+                {String(row[col.key] ?? "")}
+              </td>
+            ))}
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+});
+
+registerComponent("List", ({ children }) => <div>{children}</div>);
+
+registerComponent("Card", ({ children, padding = 16, elevation = 1, onPress, ...rest }) => (
+  <div
+    style={{
+      padding: padding as number,
+      borderRadius: 8,
+      backgroundColor: "var(--card-bg, white)",
+      boxShadow: `0 ${elevation}px ${(elevation as number) * 2}px rgba(0,0,0,0.1)`,
+      cursor: onPress ? "pointer" : undefined,
+    }}
+    {...rest}
+  >
+    {children}
+  </div>
+));
+
+registerComponent("Badge", ({ children, variant = "default", ...rest }) => {
+  const colors: Record<string, { bg: string; text: string }> = {
+    default: { bg: "#e5e5e5", text: "#333" },
+    success: { bg: "#d4edda", text: "#155724" },
+    warning: { bg: "#fff3cd", text: "#856404" },
+    error: { bg: "#f8d7da", text: "#721c24" },
+    info: { bg: "#d1ecf1", text: "#0c5460" },
+  };
+  const style = colors[variant as string] || colors.default;
+
+  return (
+    <span
+      style={{
+        display: "inline-block",
+        padding: "2px 8px",
+        borderRadius: 4,
+        fontSize: 12,
+        fontWeight: 500,
+        backgroundColor: style.bg,
+        color: style.text,
+      }}
+      {...rest}
+    >
+      {children}
+    </span>
+  );
+});
+
+registerComponent("Avatar", ({ src, name, size = "md", ...rest }) => {
+  const sizes = { sm: 32, md: 40, lg: 56 };
+  const px = sizes[size as keyof typeof sizes] || 40;
+
+  return (
+    <div
+      style={{
+        width: px,
+        height: px,
+        borderRadius: "50%",
+        backgroundColor: "var(--primary-color, #0066cc)",
+        color: "white",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: "center",
+        fontSize: px * 0.4,
+        fontWeight: 500,
+        overflow: "hidden",
+      }}
+      {...rest}
+    >
+      {src ? (
+        <img src={src as string} alt={name as string} style={{ width: "100%", height: "100%", objectFit: "cover" }} />
+      ) : (
+        (name as string)?.[0]?.toUpperCase() || "?"
+      )}
+    </div>
+  );
+});
+
+// Feedback Components
+registerComponent("Alert", ({ children, variant = "info", title, dismissible, onDismiss, ...rest }) => {
+  const colors: Record<string, { bg: string; border: string; text: string }> = {
+    info: { bg: "#d1ecf1", border: "#bee5eb", text: "#0c5460" },
+    success: { bg: "#d4edda", border: "#c3e6cb", text: "#155724" },
+    warning: { bg: "#fff3cd", border: "#ffeeba", text: "#856404" },
+    error: { bg: "#f8d7da", border: "#f5c6cb", text: "#721c24" },
+  };
+  const style = colors[variant as string] || colors.info;
+
+  return (
+    <div
+      style={{
+        padding: 12,
+        borderRadius: 6,
+        border: `1px solid ${style.border}`,
+        backgroundColor: style.bg,
+        color: style.text,
+        position: "relative",
+      }}
+      {...rest}
+    >
+      {title && <div style={{ fontWeight: 600, marginBottom: 4 }}>{title}</div>}
+      {children}
+      {dismissible && (
+        <button
+          style={{
+            position: "absolute",
+            top: 8,
+            right: 8,
+            background: "none",
+            border: "none",
+            cursor: "pointer",
+            fontSize: 16,
+          }}
+        >
+          ×
+        </button>
+      )}
+    </div>
+  );
+});
+
+registerComponent("Spinner", ({ size = "md" }) => {
+  const sizes = { sm: 16, md: 24, lg: 32 };
+  const px = sizes[size as keyof typeof sizes] || 24;
+
+  return (
+    <div
+      style={{
+        width: px,
+        height: px,
+        border: `2px solid var(--border-color, #e5e5e5)`,
+        borderTopColor: "var(--primary-color, #0066cc)",
+        borderRadius: "50%",
+        animation: "spin 1s linear infinite",
+      }}
+    />
+  );
+});
+
+registerComponent("Progress", ({ value, showLabel, ...rest }) => (
+  <div style={{ width: "100%" }} {...rest}>
+    <div
+      style={{
+        height: 8,
+        backgroundColor: "var(--border-color, #e5e5e5)",
+        borderRadius: 4,
+        overflow: "hidden",
+      }}
+    >
+      <div
+        style={{
+          width: `${Math.min(100, Math.max(0, value as number))}%`,
+          height: "100%",
+          backgroundColor: "var(--primary-color, #0066cc)",
+          transition: "width 0.3s",
+        }}
+      />
+    </div>
+    {showLabel && (
+      <div style={{ fontSize: 12, marginTop: 4, textAlign: "center" }}>
+        {Math.round(value as number)}%
+      </div>
+    )}
+  </div>
+));
+
+// Specialized Components (stubs - TODO: implement properly)
+registerComponent("CodeEditor", ({ value, language, readOnly, lineNumbers, onChange, ...rest }) => (
+  <textarea
+    value={value as string}
+    readOnly={readOnly as boolean}
+    style={{
+      width: "100%",
+      minHeight: 200,
+      fontFamily: "monospace",
+      padding: 12,
+      backgroundColor: "#1e1e1e",
+      color: "#d4d4d4",
+      border: "none",
+      borderRadius: 8,
+    }}
+    {...rest}
+  />
+));
+
+registerComponent("Terminal", ({ processId, readOnly, ...rest }) => (
+  <div
+    style={{
+      backgroundColor: "#1e1e1e",
+      color: "#d4d4d4",
+      fontFamily: "monospace",
+      padding: 12,
+      borderRadius: 8,
+      minHeight: 200,
+    }}
+    {...rest}
+  >
+    {/* TODO: Connect to actual terminal */}
+    Terminal (process: {processId || "none"})
+  </div>
+));
+
+registerComponent("Markdown", ({ children, ...rest }) => (
+  <div {...rest}>
+    {/* TODO: Proper markdown rendering */}
+    {children}
+  </div>
+));
+
+registerComponent("FileTree", ({ path, onSelect, ...rest }) => (
+  <div {...rest}>
+    {/* TODO: Implement file tree */}
+    FileTree: {path}
+  </div>
+));
+
+// ============================================================================
+// Style Helpers
+// ============================================================================
+
+function mapAlign(align?: string): string | undefined {
+  const map: Record<string, string> = {
+    start: "flex-start",
+    center: "center",
+    end: "flex-end",
+    stretch: "stretch",
+  };
+  return align ? map[align] : undefined;
+}
+
+function mapJustify(justify?: string): string | undefined {
+  const map: Record<string, string> = {
+    start: "flex-start",
+    center: "center",
+    end: "flex-end",
+    between: "space-between",
+    around: "space-around",
+  };
+  return justify ? map[justify] : undefined;
+}
+
+function mapFontSize(size?: string): string | undefined {
+  const map: Record<string, string> = {
+    xs: "10px",
+    sm: "12px",
+    base: "14px",
+    lg: "16px",
+    xl: "20px",
+    "2xl": "24px",
+    "3xl": "30px",
+    "4xl": "36px",
+  };
+  return size ? map[size] : undefined;
+}
+
+function mapFontWeight(weight?: string): number | undefined {
+  const map: Record<string, number> = {
+    normal: 400,
+    medium: 500,
+    semibold: 600,
+    bold: 700,
+  };
+  return weight ? map[weight] : undefined;
+}
+
+// ============================================================================
+// Main Renderer
+// ============================================================================
+
+/**
+ * Render a component node tree
+ */
+function renderNode(
+  node: UIChild,
+  onAction: (action: string, args?: unknown) => void,
+  index?: number
+): ReactNode {
+  // Primitives
+  if (typeof node === "string" || typeof node === "number") {
+    return node;
+  }
+
+  if (node === null || node === undefined || node === false || node === true) {
+    return null;
+  }
+
+  // Component node
+  if (typeof node === "object" && "$" in node && node.$ === "component") {
+    const Component = componentRegistry[node.type];
+
+    if (!Component) {
+      return (
+        <div
+          key={node.key ?? index}
+          style={{
+            padding: 8,
+            backgroundColor: "#fff3cd",
+            color: "#856404",
+            borderRadius: 4,
+          }}
+        >
+          Unknown component: {node.type}
+        </div>
+      );
+    }
+
+    // Transform props - convert action descriptors to handlers
+    const transformedProps: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(node.props)) {
+      if (isActionDescriptor(value)) {
+        // Convert action descriptor to onClick/onChange handler
+        if (key === "onPress") {
+          transformedProps.onClick = () => onAction(value.$action, value.args);
+        } else if (key === "onChangeText") {
+          transformedProps.onChange = (e: React.ChangeEvent<HTMLInputElement | HTMLTextAreaElement>) =>
+            onAction(value.$action, e.target.value);
+        } else if (key === "onChange") {
+          transformedProps.onChange = (e: React.ChangeEvent<HTMLInputElement | HTMLSelectElement>) => {
+            const target = e.target;
+            const newValue = target.type === "checkbox" ? (target as HTMLInputElement).checked : target.value;
+            onAction(value.$action, newValue);
+          };
+        } else {
+          transformedProps[key] = () => onAction(value.$action, value.args);
+        }
+      } else {
+        transformedProps[key] = value;
+      }
+    }
+
+    // Render children
+    const children = node.children?.map((child, i) => renderNode(child, onAction, i));
+
+    return (
+      <Component key={node.key ?? index} {...transformedProps}>
+        {children}
+      </Component>
+    );
+  }
+
+  return null;
+}
+
+function isActionDescriptor(value: unknown): value is ActionDescriptor {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "$action" in value &&
+    typeof (value as ActionDescriptor).$action === "string"
+  );
+}
+
+/**
+ * SDR Renderer Component
+ *
+ * Takes a server-generated component tree and renders it as React components.
+ */
+export function SDRRenderer({ tree, onAction, state }: SDRRendererProps): ReactNode {
+  if (!tree) {
+    return null;
+  }
+
+  return renderNode(tree, onAction);
+}
+
+/**
+ * Unknown component fallback
+ */
+function UnknownComponent({ type }: { type: string }): ReactNode {
+  return (
+    <div
+      style={{
+        padding: 8,
+        backgroundColor: "#fff3cd",
+        color: "#856404",
+        borderRadius: 4,
+        margin: 4,
+      }}
+    >
+      Unknown component: {type}
+    </div>
+  );
+}
+
+export default SDRRenderer;
diff --git a/webui/src/components/apps/index.ts b/webui/src/components/apps/index.ts
new file mode 100644
index 0000000..6a79953
--- /dev/null
+++ b/webui/src/components/apps/index.ts
@@ -0,0 +1,8 @@
+/**
+ * Iris Apps Components
+ *
+ * React components for hosting and rendering Iris Apps.
+ */
+
+export { SDRRenderer, registerComponent, getComponent } from "./SDRRenderer";
+export { AppHost } from "./AppHost";