@positronic/template-new-project 0.0.76 → 0.0.78

package/template/docs/brain-dsl-guide.md

@@ -12,7 +12,7 @@ The Brain DSL provides a fluent, type-safe API for building stateful AI workflow
 
 The brain function provides full type safety through its fluent API. State types are automatically inferred as you build your brain, and options can be validated at runtime using schemas.
 
-For runtime options validation, use the `withOptionsSchema` method with a Zod schema:
+For runtime options validation, use the `withOptions` method with a Zod schema:
 
 ```typescript
 import { z } from 'zod';
@@ -23,7 +23,7 @@ const optionsSchema = z.object({
 });
 
 const myBrain = brain('My Brain')
-  .withOptionsSchema(optionsSchema)
+  .withOptions(optionsSchema)
   .step('Process', ({ options }) => {
     // options is fully typed based on the schema
     if (options.verbose) {
@@ -81,39 +81,33 @@ brain('AI Education Assistant')
     context: 'We are creating an educational example',
   }))
   .prompt('Generate explanation', {
-    template: ({ topic, context }) =>
+    message: ({ state: { topic, context } }) =>
       `<%= '${context}' %>. Please provide a brief, beginner-friendly explanation of <%= '${topic}' %>.`,
-    outputSchema: {
-      schema: z.object({
-        explanation: z.string().describe('A clear explanation of the topic'),
-        keyPoints: z.array(z.string()).describe('3-5 key points about the topic'),
-        difficulty: z.enum(['beginner', 'intermediate', 'advanced']).describe('The difficulty level'),
-      }),
-      name: 'topicExplanation' as const,
-    },
+    outputSchema: z.object({
+      explanation: z.string().describe('A clear explanation of the topic'),
+      keyPoints: z.array(z.string()).describe('3-5 key points about the topic'),
+      difficulty: z.enum(['beginner', 'intermediate', 'advanced']).describe('The difficulty level'),
+    }),
   })
   .step('Format output', ({ state }) => ({
     ...state,
     formattedOutput: {
       topic: state.topic,
-      explanation: state.topicExplanation.explanation || '',
-      summary: `This explanation covers <%= '${state.topicExplanation.keyPoints?.length || 0}' %> key points at a <%= '${state.topicExplanation.difficulty || \'unknown\'}' %> level.`,
-      points: state.topicExplanation.keyPoints || [],
+      explanation: state.explanation || '',
+      summary: `This explanation covers <%= '${state.keyPoints?.length || 0}' %> key points at a <%= '${state.difficulty || \'unknown\'}' %> level.`,
+      points: state.keyPoints || [],
     },
   }))
   .prompt(
     'Generate follow-up questions',
     {
-      template: ({ formattedOutput }) =>
+      message: ({ state: { formattedOutput } }) =>
         `Based on this explanation about <%= '${formattedOutput.topic}' %>: "<%= '${formattedOutput.explanation}' %>"
-        
+
         Generate 3 thoughtful follow-up questions that a student might ask.`,
-      outputSchema: {
-        schema: z.object({
-          questions: z.array(z.string()).length(3).describe('Three follow-up questions'),
-        }),
-        name: 'followUpQuestions' as const,
-      },
+      outputSchema: z.object({
+        questions: z.array(z.string()).length(3).describe('Three follow-up questions'),
+      }),
     },
     // Optional: Transform the response before merging with state
     ({ state, response }) => ({
@@ -128,10 +122,11 @@ brain('AI Education Assistant')
 ```
 
 Key points about prompt steps:
-- The `template` function receives the current state and resources, returning the prompt string
-- Templates can be async to load resources: `async (state, resources) => { ... }`
+- The `message` function receives the current state and resources, returning the prompt string
+- The `message` function can be async to load resources: `async ({ state, resources }) => { ... }`
 - `outputSchema` defines the structure using Zod schemas
-- The `name` property determines where the response is stored in state
+- The schema result is spread directly onto state (`{ ...state, ...result }`)
+- To namespace, wrap your schema in a parent key (e.g., `z.object({ plan: z.object({ ... }) })`)
 - You can optionally provide a transform function as the third parameter
 - Type inference works throughout - TypeScript knows about your schema types
 
@@ -147,23 +142,17 @@ const smartModel = createAnthropicClient({ model: 'claude-sonnet-4-5-20250929' }
 
 brain('Multi-Model Brain')
   .prompt('Quick summary', {
-    template: ({ document }) => `Summarize this briefly: <%= '${document}' %>`,
-    outputSchema: {
-      schema: z.object({ summary: z.string() }),
-      name: 'quickSummary' as const,
-    },
+    message: ({ state: { document } }) => `Summarize this briefly: <%= '${document}' %>`,
+    outputSchema: z.object({ summary: z.string() }),
     client: fastModel,  // Use a fast, cheap model for summarization
   })
   .prompt('Deep analysis', {
-    template: ({ quickSummary }) =>
-      `Analyze the implications of this summary: <%= '${quickSummary.summary}' %>`,
-    outputSchema: {
-      schema: z.object({
-        insights: z.array(z.string()),
-        risks: z.array(z.string()),
-      }),
-      name: 'analysis' as const,
-    },
+    message: ({ state: { summary } }) =>
+      `Analyze the implications of this summary: <%= '${summary}' %>`,
+    outputSchema: z.object({
+      insights: z.array(z.string()),
+      risks: z.array(z.string()),
+    }),
     client: smartModel,  // Use a more capable model for analysis
   });
 ```
@@ -181,17 +170,13 @@ const subBrain = brain('Sub Process').step('Transform', ({ state }) => ({
 
 const mainBrain = brain('Main Process')
   .step('Prepare', () => ({ value: 10 }))
-  .brain(
-    'Run Sub Process',
-    subBrain,
-    ({ state, brainState }) => ({
-      ...state,
-      processed: brainState.result,
-    }),
-    (state) => ({ input: state.value }) // Initial state for sub-brain
-  );
+  .brain('Run Sub Process', subBrain, {
+    initialState: ({ state }) => ({ input: state.value }),
+  });
 ```
 
+The inner brain's final state is spread directly onto the outer state (e.g., `state.result` will be `20`). `initialState` is optional (defaults to `{}`) and can be a static object or a function receiving `{ state, options, ...plugins }`. To namespace, design the inner brain to return its results under a single key.
+
 ## Guard Clauses
 
 Use `.guard()` to short-circuit a brain when a condition isn't met. If the predicate returns `true`, execution continues normally. If it returns `false`, all remaining steps are skipped and the brain completes with the current state.
@@ -204,9 +189,8 @@ brain('email-checker')
   })
   .guard(({ state }) => state.emails.some(e => e.important))
   // everything below only runs if guard passes
-  .ui('Review emails', { ... })
-  .step('Notify and wait', ...)
-  .step('Handle response', ...);
+  .page('Review emails', (ctx) => ({ ..., formSchema: ... }))
+  // form data auto-merges onto state
 ```
 
 Key points:
@@ -237,11 +221,11 @@ Each step receives these parameters:
 - `client` - AI client for generating structured objects
 - `resources` - Loaded resources (files, documents, etc.)
 - `options` - Runtime options passed to the brain
-- `response` - Webhook response data (available after `.wait()` completes)
-- `page` - Generated page object (available after `.ui()` step)
 - `pages` - Pages service for HTML page management
 - `env` - Runtime environment containing `origin` (base URL) and `secrets` (typed secrets object)
-- Custom services (if configured with `.withServices()` or `createBrain()`)
+- Custom plugin-provided values (if configured with `.withPlugin()` or `createBrain()`)
+
+> **Note**: `response` is only available inside `.handle()` callbacks after `.wait()`. For `.page()` with `formSchema`, the response is spread directly onto state. See [Page Steps](#page-steps) and [Webhooks](#webhooks) for details.
 
 ## Configuration Methods
 
@@ -251,7 +235,7 @@ Options provide runtime configuration for your brains, allowing different behavi
 
 #### Typing Options
 
-To use options in your brain, define a Zod schema with `withOptionsSchema`:
+To use options in your brain, define a Zod schema with `withOptions`:
 
 ```typescript
 import { z } from 'zod';
@@ -263,9 +247,9 @@ const notificationSchema = z.object({
   includeTimestamp: z.boolean().default(true)
 });
 
-// Use withOptionsSchema to add runtime validation
+// Use withOptions to add runtime validation
 const notificationBrain = brain('Notification Brain')
-  .withOptionsSchema(notificationSchema)
+  .withOptions(notificationSchema)
   .step('Send Alert', async ({ state, options, slack }) => {
     // TypeScript knows the exact shape of options from the schema
     const message = options.includeTimestamp 
@@ -304,7 +288,7 @@ px brain run my-brain -o "webhook=https://example.com/api?key=value"
 
 Options are passed as simple key=value pairs and are available as strings in your brain.
 
-#### Options vs Services vs Initial State
+#### Options vs Plugins vs Initial State
 
 Understanding when to use each:
 
@@ -313,8 +297,8 @@ Understanding when to use each:
   - Don't change during execution
   - Examples: `slackChannel`, `apiEndpoint`, `debugMode`
 
-- **Services**: External dependencies and side effects (clients, loggers, databases)
-  - Configure once with `.withServices()`
+- **Plugins**: External dependencies and side effects (clients, loggers, databases)
+  - Configure once with `.withPlugin()` or `createBrain()`
   - Available in all steps
   - Not serializable
   - Examples: `slackClient`, `database`, `logger`
@@ -336,11 +320,9 @@ const notificationSchema = z.object({
 });
 
 const notificationBrain = brain('Smart Notifier')
-  .withOptionsSchema(notificationSchema)
-  .withServices({ 
-    slack: slackClient,
-    email: emailClient 
-  })
+  .withOptions(notificationSchema)
+  .withPlugin(slack)
+  .withPlugin(email)
   .step('Process Alert', ({ state, options }) => ({
     ...state,
     formattedMessage: options.includeDetails === 'true'
@@ -383,20 +365,16 @@ expect(mockSlack.post).toHaveBeenCalledWith('#test-channel', expect.any(String))
 expect(mockEmail.send).toHaveBeenCalled(); // High priority triggers email
 ```
 
-### Service Injection
+### Plugin Injection
 
-The `withServices` method provides dependency injection for your brains, making external services available throughout the workflow while maintaining testability.
+The `withPlugin` method provides dependency injection for your brains, making plugin-provided values available throughout the workflow while maintaining testability.
 
 #### Basic Usage
 
 ```typescript
-interface MyServices {
-  logger: Logger;
-  database: Database;
-}
-
-const brainWithServices = brain('Service Brain')
-  .withServices<MyServices>({ logger, database })
+const brainWithPlugins = brain('Plugin Brain')
+  .withPlugin(logger)
+  .withPlugin(database)
   .step('Log and Save', async ({ state, logger, database }) => {
     logger.info('Processing state');
     await database.save(state);
@@ -404,9 +382,9 @@ const brainWithServices = brain('Service Brain')
   });
 ```
 
-#### Where Services Are Available
+#### Where Plugin Values Are Available
 
-Services are destructured alongside other parameters in:
+Plugin-provided values are destructured alongside other parameters in:
 
 1. **Step Actions**:
 ```typescript
@@ -419,49 +397,28 @@ Services are destructured alongside other parameters in:
 2. **Prompt Reduce Functions**:
 ```typescript
 .prompt('Generate', {
-  template: (state) => 'Generate something',
-  outputSchema: { schema, name: 'result' as const }
+  message: ({ state }) => 'Generate something',
+  outputSchema: schema,
 }, async ({ state, response, logger, database }) => {
   logger.info('Saving AI response');
-  await database.save({ ...state, result: response });
+  await database.save({ ...state, ...response });
   return state;
 })
 ```
 
-3. **Nested Brain Reducers**:
+3. **Nested Brain Config**:
 ```typescript
-.brain('Run Sub-Brain', subBrain, ({ state, brainState, logger }) => {
-  logger.info('Sub-brain completed');
-  return { ...state, subResult: brainState };
-})
+.brain('Run Sub-Brain', subBrain)
 ```
 
 #### Real-World Example
 
 ```typescript
-// Define service interfaces
-interface Services {
-  api: {
-    fetchData: (id: string) => Promise<Data>;
-    submitResult: (result: any) => Promise<void>;
-  };
-  cache: {
-    get: (key: string) => Promise<any>;
-    set: (key: string, value: any) => Promise<void>;
-  };
-  metrics: {
-    track: (event: string, properties?: any) => void;
-    time: (label: string) => () => void;
-  };
-}
-
-// Create a brain with multiple services
+// Create a brain with multiple plugins
 const analysisBrain = brain('Data Analysis')
-  .withServices<Services>({
-    api: apiClient,
-    cache: redisClient,
-    metrics: analyticsClient
-  })
+  .withPlugin(api)
+  .withPlugin(cache)
+  .withPlugin(metrics)
   .step('Start Timing', ({ metrics }) => {
     const endTimer = metrics.time('analysis_duration');
     return { startTime: Date.now(), endTimer };
@@ -477,27 +434,26 @@ const analysisBrain = brain('Data Analysis')
     return { ...state, data };
   })
   .prompt('Analyze Data', {
-    template: ({ data }) => `Analyze this data: <%= '${JSON.stringify(data)}' %>`,
-    outputSchema: {
-      schema: z.object({
-        insights: z.array(z.string()),
-        confidence: z.number()
-      }),
-      name: 'analysis' as const
-    }
+    message: ({ state: { data } }) => `Analyze this data: <%= '${JSON.stringify(data)}' %>`,
+    outputSchema: z.object({
+      insights: z.array(z.string()),
+      confidence: z.number()
+    }),
   })
   .step('Save Results', async ({ state, api, cache, metrics }) => {
+    const { insights, confidence } = state;
+
     // Save to cache for next time
-    await cache.set('analysis_result', state.analysis);
+    await cache.set('analysis_result', { insights, confidence });
 
     // Submit to API
-    await api.submitResult(state.analysis);
+    await api.submitResult({ insights, confidence });
 
     // Track completion
     state.endTimer(); // End the timer
     metrics.track('analysis_complete', {
-      insights_count: state.analysis.insights.length,
-      confidence: state.analysis.confidence,
+      insights_count: insights.length,
+      confidence,
       from_cache: state.fromCache
     });
 
@@ -505,9 +461,9 @@ const analysisBrain = brain('Data Analysis')
   });
 ```
 
-#### Testing with Services
+#### Testing with Plugins
 
-Services make testing easier by allowing you to inject mocks:
+Plugins make testing easier by allowing you to inject mocks:
 
 ```typescript
 // In your test file
@@ -524,7 +480,8 @@ const mockDatabase = {
 };
 
 const testBrain = brain('Test Brain')
-  .withServices({ logger: mockLogger, database: mockDatabase })
+  .withPlugin(mockLoggerPlugin)
+  .withPlugin(mockDatabasePlugin)
   .step('Do Something', async ({ logger, database }) => {
     logger.info('Fetching data');
     const data = await database.find('123');
@@ -536,7 +493,7 @@ const result = await runBrainTest(testBrain, {
   client: createMockClient()
 });
 
-// Verify service calls
+// Verify plugin calls
 expect(mockLogger.info).toHaveBeenCalledWith('Fetching data');
 expect(mockDatabase.find).toHaveBeenCalledWith('123');
 expect(result.finalState.data).toEqual({ id: '123', name: 'Test' });
@@ -544,57 +501,61 @@ expect(result.finalState.data).toEqual({ id: '123', name: 'Test' });
 
 #### Important Notes
 
-- Call `withServices` before defining any steps
-- Services are typed - TypeScript knows exactly which services are available
-- Services are not serialized - they're for side effects and external interactions
-- Each brain instance maintains its own service references
+- Call `withPlugin` before defining any steps
+- Plugin-provided values are typed - TypeScript knows exactly which values are available
+- Plugin values are not serialized - they're for side effects and external interactions
+- Each brain instance maintains its own plugin references
 
-### Tool Configuration with `withTools()`
+### Tool-Calling Prompt Loops
 
-The `withTools()` method registers tools that can be used by agent steps:
+Use `.prompt()` with a `loop` property to run an LLM with tools. The LLM calls tools iteratively until it calls the auto-generated `done` tool:
 
 ```typescript
 import { z } from 'zod';
+import { generatePage, waitForWebhook } from '@positronic/core';
 
-const brainWithTools = brain('Tool Brain')
-  .withTools({
-    fetchData: {
-      description: 'Fetch data from an external API',
-      inputSchema: z.object({
-        endpoint: z.string(),
-        params: z.record(z.string()).optional()
-      }),
-      execute: async ({ endpoint, params }) => {
-        const url = new URL(endpoint);
-        if (params) {
-          Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+brain('Tool Brain')
+  .prompt('Fetch and Save', () => ({
+    system: 'You can fetch and save data.',
+    message: 'Fetch user data and save the summary.',
+    outputSchema: z.object({ summary: z.string() }),
+    loop: {
+      tools: {
+        fetchData: {
+          description: 'Fetch data from an external API',
+          inputSchema: z.object({
+            endpoint: z.string(),
+            params: z.record(z.string()).optional()
+          }),
+          execute: async ({ endpoint, params }) => {
+            const url = new URL(endpoint);
+            if (params) {
+              Object.entries(params).forEach(([k, v]) => url.searchParams.set(k, v));
+            }
+            const response = await fetch(url);
+            return response.json();
+          }
+        },
+        saveToDatabase: {
+          description: 'Save data to the database',
+          inputSchema: z.object({
+            table: z.string(),
+            data: z.any()
+          }),
+          execute: async ({ table, data }) => {
+            return { success: true, id: 'generated-id' };
+          }
         }
-        const response = await fetch(url);
-        return response.json();
-      }
+      },
     },
-    saveToDatabase: {
-      description: 'Save data to the database',
-      inputSchema: z.object({
-        table: z.string(),
-        data: z.any()
-      }),
-      execute: async ({ table, data }) => {
-        // Database save logic
-        return { success: true, id: 'generated-id' };
-      }
-    }
-  })
-  .brain('Data Agent', {
-    system: 'You can fetch and save data.',
-    prompt: 'Fetch user data and save the summary.'
-    // Tools defined with withTools() are automatically available
-  });
+  }));
 ```
 
+Tools are explicit on each `.prompt()` — there's no global tool registration.
+
 ### Component Configuration with `withComponents()`
 
-The `withComponents()` method registers custom UI components for use in `.ui()` steps:
+The `withComponents()` method registers custom UI components for use in `.page()` steps:
 
 ```typescript
 const brainWithComponents = brain('Custom UI Brain')
@@ -629,17 +590,17 @@ const brainWithComponents = brain('Custom UI Brain')
       }
     }
   })
-  .ui('Dashboard', {
-    template: (state) => `
+  .page('Dashboard', ({ state }) => ({
+    prompt: `
       Create a dashboard using CustomCard components to display:
       - User name: <%= '${state.userName}' %>
       - Account status: <%= '${state.status}' %>
       Use DataTable to show recent activity.
     `,
-    responseSchema: z.object({
+    formSchema: z.object({
       acknowledged: z.boolean()
-    })
-  });
+    }),
+  }));
 ```
 
 ### Typed Store with `withStore()`
@@ -714,9 +675,9 @@ await store.has('key');     // Returns boolean
 You can declare store fields at the project level so all brains share the same store shape:
 
 ```typescript
-// brain.ts
+// src/brain.ts
 export const brain = createBrain({
-  services: { slack },
+  plugins: [slack],
   store: {
     processedCount: z.number(),
     userSettings: { type: z.object({ notifications: z.boolean() }), perUser: true },
@@ -727,7 +688,7 @@ export const brain = createBrain({
 Or declare per-brain stores for brain-specific data:
 
 ```typescript
-// brains/my-brain.ts
+// src/brains/my-brain.ts
 export default brain('my-brain')
   .withStore({ counter: z.number() })
   .step('Increment', async ({ store }) => {
@@ -739,18 +700,15 @@ export default brain('my-brain')
 
 ### Using `createBrain()` for Project Configuration
 
-For project-wide configuration, use `createBrain()` in your `brain.ts` file:
+For project-wide configuration, use `createBrain()` in your `src/brain.ts` file:
 
 ```typescript
-// brain.ts
+// src/brain.ts
 import { createBrain } from '@positronic/core';
 import { z } from 'zod';
 
 export const brain = createBrain({
-  services: {
-    logger: console,
-    api: apiClient
-  },
+  plugins: [logger, api],
   tools: {
     search: {
       description: 'Search the web',
@@ -771,7 +729,7 @@ export const brain = createBrain({
 });
 ```
 
-All brains created with this factory will have access to the configured services, tools, components, and store.
+All brains created with this factory will have access to the configured plugins, tools, components, and store.
 
 #### Typing Initial State and Options
 
@@ -931,14 +889,11 @@ Resources are also available in prompt templates:
 
 ```typescript
 brain('Template Example').prompt('Generate Content', {
-  template: async (state, resources) => {
+  message: async ({ state, resources }) => {
     const template = await resources.prompts.customerSupport.load();
     return template.replace('{{issue}}', state.issue);
   },
-  outputSchema: {
-    schema: z.object({ response: z.string() }),
-    name: 'supportResponse' as const,
-  },
+  outputSchema: z.object({ response: z.string() }),
 });
 ```
 
@@ -997,7 +952,7 @@ When prompts become more than a sentence or two, extract them into separate file
 For complex brains, organize your code into folders:
 
 ```
-brains/
+src/brains/
 ├── hn-bot/
 │   ├── brain.ts           # Main brain definition
 │   └── ai-filter-prompt.ts # Complex prompt configuration
@@ -1009,7 +964,7 @@ brains/
 When you extract a prompt to a separate file, you'll need to explicitly specify the state type:
 
 ```typescript
-// brains/hn-bot/ai-filter-prompt.ts
+// src/brains/hn-bot/ai-filter-prompt.ts
 import { z } from 'zod';
 import type { Resources } from '@positronic/core';
 
@@ -1025,7 +980,7 @@ interface FilterPromptState {
 
 // Export the prompt configuration
 export const aiFilterPrompt = {
-  template: async (state: FilterPromptState, resources: Resources) => {
+  message: async ({ state, resources }: { state: FilterPromptState, resources: Resources }) => {
     // Load a prompt template from resources
     const template = await resources.prompts.hnFilter.load();
 
@@ -1038,17 +993,14 @@ export const aiFilterPrompt = {
       .replace('{{articleList}}', articleList)
       .replace('{{preferences}}', state.userPreferences || 'No specific preferences');
   },
-  outputSchema: {
-    schema: z.object({
-      selectedArticles: z.array(z.number()).describe('Indices of selected articles'),
-      reasoning: z.string().describe('Brief explanation of selections'),
-    }),
-    name: 'filterResults' as const,
-  },
+  outputSchema: z.object({
+    selectedArticles: z.array(z.number()).describe('Indices of selected articles'),
+    reasoning: z.string().describe('Brief explanation of selections'),
+  }),
 };
 
-// brains/hn-bot/brain.ts
-import { brain } from '../brain.js';
+// src/brains/hn-bot/brain.ts
+import { brain } from '../../brain.js';
 import { aiFilterPrompt } from './ai-filter-prompt.js';
 
 export default brain('HN Article Filter')
@@ -1059,62 +1011,154 @@ export default brain('HN Article Filter')
   })
   .prompt('Filter Articles', aiFilterPrompt)
   .step('Format Results', ({ state }) => ({
-    selectedArticles: state.filterResults.selectedArticles.map(
+    selectedArticles: state.selectedArticles.map(
       i => state.articles[i]
     ),
-    reasoning: state.filterResults.reasoning,
+    reasoning: state.reasoning,
   }));
 ```
 
 ### When to Extract Prompts
 
 Extract prompts to separate files when:
-- The template is more than 2-3 lines
+- The message is more than 2-3 lines
 - The prompt uses complex logic or formatting
-- You need to load resources or templates
+- You need to load resources
 - The prompt might be reused in other brains
 - You want to test the prompt logic separately
 
-## Iterating Over Items
+## JSX Templates
 
-When you need to run the same prompt, brain, or agent over multiple items, use the `over` option.
+Templates can be written as JSX instead of template literal strings. This improves readability for complex prompts with conditionals, loops, and multi-line content. Prettier formats JSX automatically, keeping your prompts properly indented within the builder chain.
 
-### Prompt Iterate
+### Basic Usage
 
-Run the same prompt once per item in a list:
+Rename your brain file from `.ts` to `.tsx` and return JSX from the message function:
 
-```typescript
-brain('Item Processor')
-  .step('Initialize', () => ({
-    items: [
-      { id: 1, title: 'First item' },
-      { id: 2, title: 'Second item' },
-      { id: 3, title: 'Third item' }
-    ]
-  }))
-  .prompt('Summarize Items', {
-    template: (item) => `Summarize this item: <%= '${item.title}' %>`,
-    outputSchema: {
-      schema: z.object({ summary: z.string() }),
-      name: 'summaries' as const
+```tsx
+// src/brains/analyze.tsx
+import { brain } from '../brain.js';
+import { z } from 'zod';
+
+export default brain('analyze')
+  .prompt('Analyze', {
+    message: ({ state: { topic, context } }) => (
+      <>
+        Analyze the following topic: {topic}
+
+        Context: {context}
+
+        Please provide:
+        - A summary
+        - Key insights
+        - Recommendations
+      </>
+    ),
+    outputSchema: z.object({
+      summary: z.string(),
+      insights: z.array(z.string()),
+      recommendations: z.array(z.string()),
+    }),
+  });
+```
+
+No `render()` call is needed — the runner handles JSX rendering internally. Old string messages still work, so this is fully opt-in.
+
+### Conditionals
+
+Use `&&` for boolean conditions and ternaries when you need both branches or when the condition could be a falsy non-boolean (like `0` or `""`):
+
+```tsx
+// && works when the condition is strictly boolean
+message: ({ state: { user, isVIP } }) => (
+  <>
+    Create a greeting for {user.name}.
+    {isVIP && <>This is a VIP customer. Use premium language.</>}
+  </>
+)
+
+// Ternary for either/or content
+message: ({ state: { user, tier } }) => (
+  <>
+    Create a greeting for {user.name}.
+    {tier === 'premium'
+      ? <>Use premium, personalized language.</>
+      : <>Use friendly, standard language.</>
     }
-  }, {
-    over: ({ state }) => state.items,
-    error: (item, error) => ({ summary: 'Failed to summarize' })
-  })
-  .step('Process Results', ({ state }) => ({
-    ...state,
-    // summaries is an IterateResult — use .values, .items, .entries, .filter(), .map()
-    processedSummaries: state.summaries.map((item, response) => ({
-      id: item.id,
-      summary: response.summary
-    }))
-  }));
+  </>
+)
+```
+
+**Watch out for non-boolean falsy values.** `{count && <>...</>}` renders `"0"` when count is 0 — use `{count > 0 && <>...</>}` or a ternary instead.
+
+### Loops
+
+Use `.map()` naturally inside JSX:
+
+```tsx
+message: ({ state: { items } }) => (
+  <>
+    Review the following items:
+    {items.map(item => (
+      <>
+        - {item.name}: {item.description}
+      </>
+    ))}
+  </>
+)
+```
+
+### Reusable Prompt Components
+
+Extract common prompt sections into function components:
+
+```tsx
+const CategoryInstructions = ({ categories }: { categories: string[] }) => (
+  <>
+    Valid categories: {categories.join(', ')}
+    Always pick exactly one. If unsure, pick "other".
+  </>
+);
+
+// Use in a message
+message: ({ state: { email, categories } }) => (
+  <>
+    Categorize this email:
+    From: {email.from}
+    Subject: {email.subject}
+
+    <CategoryInstructions categories={categories} />
+  </>
+)
 ```
 
-Prompt iterate also supports per-step `client` overrides (see Prompt Steps above), so you can use a different model for processing.
+### Async Components
 
-### Brain Iterate
+Function components can be async, which is useful for loading resources:
+
+```tsx
+const Resource = async ({ from }: { from: any }) => {
+  const content = await from.loadText();
+  return <>{content}</>;
+};
+
+message: ({ state, resources }) => (
+  <>
+    Summarize this document using the guidelines below:
+
+    <Resource from={resources.guidelines} />
+
+    Document:
+    {state.document}
+  </>
+)
+```
+
+## Iterating Over Items
+
+When you need to run the same operation over multiple items, use `.map()`. You can iterate a prompt directly, or iterate a brain for more complex per-item logic.
+
+### Basic `.map()` with a Brain
 
 Run a nested brain once per item:
 
@@ -1129,11 +1173,11 @@ brain('Process All Items')
   .step('Initialize', () => ({
     items: [{ value: 1 }, { value: 2 }, { value: 3 }]
   }))
-  .brain('Process Each', processBrain, {
+  .map('Process Each', 'results', {
+    run: processBrain,
     over: ({ state }) => state.items,
-    initialState: (item) => ({ value: item.value }),
-    outputKey: 'results' as const,
-    error: (item, error) => ({ value: item.value, failed: true }),
+    initialState: (item) => ({ value: item.value, result: 0 }),
+    error: (item, error) => ({ value: item.value, result: 0 }),
   })
   .step('Use Results', ({ state }) => ({
     ...state,
@@ -1142,58 +1186,101 @@ brain('Process All Items')
   }));
 ```
 
-### Agent Iterate
+### Iterating a Prompt
 
-Run an agent config once per item. The `configFn` receives the item as its first argument:
+Use `.map()` with `prompt: { message, outputSchema }` to run a prompt per item:
 
 ```typescript
+brain('Item Processor')
+  .step('Initialize', () => ({
+    items: [
+      { id: 1, title: 'First item' },
+      { id: 2, title: 'Second item' },
+      { id: 3, title: 'Third item' },
+    ]
+  }))
+  .map('Summarize Items', 'summaries', {
+    prompt: {
+      message: ({ item }) => `Summarize this item: <%= '${item.title}' %>`,
+      outputSchema: z.object({ summary: z.string() }),
+    },
+    over: ({ state }) => state.items,
+    error: () => ({ summary: 'Failed to summarize' }),
+  })
+  .step('Process Results', ({ state }) => ({
+    ...state,
+    processedSummaries: state.summaries.map((item, result) => ({
+      id: item.id,
+      summary: result.summary,
+    })),
+  }));
+```
+
+The `message` function receives `{ item, state, options, resources }` where `item` is the current iteration item. The result per item is `z.infer` of the `outputSchema`. You can also pass `client` to use a different LLM client for the prompt.
+
+### Iterating an Agent
+
+To iterate an agent over items, wrap it in a brain and use `.map()`:
+
+```typescript
+const researchBrain = brain('Research Single')
+  .brain('Research', ({ state, tools }) => ({
+    system: 'You are a research assistant.',
+    prompt: `Research this topic: <%= '${state.name}' %>`,
+    tools: { search: tools.search },
+    outputSchema: z.object({ summary: z.string() }),
+  }));
+
 brain('Research Topics')
   .step('Initialize', () => ({
     topics: [{ name: 'AI' }, { name: 'Robotics' }]
   }))
-  .brain('Research Each', (item, { state, tools }) => ({
-    system: 'You are a research assistant.',
-    prompt: `Research this topic: <%= '${item.name}' %>`,
-    tools: {
-      search: tools.search,
-    },
-    outputSchema: {
-      schema: z.object({ summary: z.string() }),
-      name: 'research' as const,
-    },
-  }), {
+  .map('Research Each', 'results', {
+    run: researchBrain,
     over: ({ state }) => state.topics,
-    outputKey: 'results' as const,
+    initialState: (topic) => ({ name: topic.name }),
   })
   .step('Use Results', ({ state }) => ({
     ...state,
-    // results is an IterateResult — use .values to get just the results
     summaries: state.results.values.map(result => result.summary),
   }));
 ```
 
-### Iterate Options
+### `.map()` Options
 
-All iterate variants share these options:
+`.map()` has two modes: **brain mode** (run an inner brain per item) and **prompt mode** (run a prompt per item).
 
-- `over: (context) => T[] | Promise<T[]>` - Function returning the array to iterate over. Receives the full step context (`{ state, options, client, resources, services, ... }`) — the same context object that step actions receive. Most commonly you'll destructure just `{ state }`, but you can access options, services, or any other context field. Can be async.
-- `error: (item, error) => Result | null` - Fallback when an item fails. Return `null` to skip the item entirely.
+Note: The `stateKey` is now the 2nd argument to `.map()`: `.map('title', 'stateKey', { ... })`.
 
-Brain and agent iterate also require:
+**Common options** (both modes):
 
-- `outputKey: string` - Key under which results are stored in state (use `as const` for type inference)
+- `over: (context) => T[] | Promise<T[]>` - Function returning the array to iterate over. Receives the full step context (`{ state, options, client, resources, ... }`) — the same context object that step actions receive. Most commonly you'll destructure just `{ state }`, but you can access options, plugin-provided values, or any other context field. Can be async.
+- `error: (item, error) => Result | null` - Optional fallback when an item fails. Return `null` to skip the item entirely.
 
-Brain iterate additionally requires:
+**Brain mode** (use `run`):
 
+- `run: Brain` - The inner brain to execute for each item
 - `initialState: (item, outerState) => State` - Function to create the inner brain's initial state from each item
 
-#### Accessing options and services in `over`
+**Prompt mode** (use `prompt: { message, outputSchema }`):
 
-Since `over` receives the full step context, you can use options or services to determine which items to iterate over:
+- `prompt.message: (context) => string` - Message function. Receives `{ item, state, options, resources }` where `item` is the current iteration item.
+- `prompt.outputSchema: ZodSchema` - Zod schema for the LLM output.
+- `client?: ObjectGenerator` - Optional per-step LLM client override.
+
+#### Accessing options and plugins in `over`
+
+Since `over` receives the full step context, you can use options or plugin-provided values to determine which items to iterate over:
 
 ```typescript
+const processItemBrain = brain('Process Single')
+  .step('Process', ({ state }) => ({
+    ...state,
+    result: `Processed item <%= '${state.id}' %>`,
+  }));
+
 brain('Dynamic Processor')
-  .withOptionsSchema(z.object({ category: z.string() }))
+  .withOptions(z.object({ category: z.string() }))
   .step('Load items', () => ({
     items: [
       { id: 1, category: 'a' },
@@ -1201,14 +1288,10 @@ brain('Dynamic Processor')
       { id: 3, category: 'a' },
     ]
   }))
-  .prompt('Process', {
-    template: (item) => `Process item <%= '${item.id}' %>`,
-    outputSchema: {
-      schema: z.object({ result: z.string() }),
-      name: 'results' as const,
-    },
-  }, {
+  .map('Process', 'results', {
+    run: processItemBrain,
     over: ({ state, options }) => state.items.filter(i => i.category === options.category),
+    initialState: (item) => ({ id: item.id, result: '' }),
   })
 ```
 
@@ -1224,155 +1307,148 @@ By default, results are stored as an `IterateResult` — a collection that wraps
 - **`.map((item, result) => value)`** — maps over both item and result, returns a plain array
 - **`for...of`** — iterates as `[item, result]` tuples (backward compatible with destructuring)
 
-For prompts, the key comes from `outputSchema.name`. For brain and agent iterate, it comes from `outputKey`.
+The key always comes from `stateKey`.
 
-## Agent Steps
+## Prompt Steps with Tool-Calling Loops
 
-For complex AI workflows that require tool use, use the `.brain()` method with an agent configuration:
+For complex AI workflows that require tool use, use `.prompt()` with a `loop` property. The LLM calls tools iteratively until it calls the auto-generated `done` tool with data matching the `outputSchema`:
 
 ```typescript
 brain('Research Assistant')
   .step('Initialize', () => ({
     query: 'What are the latest developments in AI?'
   }))
-  .brain('Research Agent', {
+  .prompt('Research', ({ state }) => ({
     system: 'You are a helpful research assistant with access to search tools.',
-    prompt: ({ query }) => `Research this topic: <%= '${query}' %>`,
-    tools: {
-      search: {
-        description: 'Search the web for information',
-        inputSchema: z.object({
-          query: z.string().describe('The search query')
-        }),
-        execute: async ({ query }) => {
-          // Implement search logic
-          const results = await searchWeb(query);
-          return { results };
+    message: `Research this topic: <%= '${state.query}' %>`,
+    outputSchema: z.object({
+      findings: z.array(z.string()),
+      summary: z.string(),
+    }),
+    loop: {
+      tools: {
+        search: {
+          description: 'Search the web for information',
+          inputSchema: z.object({
+            query: z.string().describe('The search query')
+          }),
+          execute: async ({ query }) => {
+            const results = await searchWeb(query);
+            return { results };
+          }
+        },
+        summarize: {
+          description: 'Summarize a piece of text',
+          inputSchema: z.object({
+            text: z.string().describe('Text to summarize')
+          }),
+          execute: async ({ text }) => {
+            return { summary: text.slice(0, 100) + '...' };
+          }
         }
       },
-      summarize: {
-        description: 'Summarize a piece of text',
-        inputSchema: z.object({
-          text: z.string().describe('Text to summarize')
-        }),
-        execute: async ({ text }) => {
-          return { summary: text.slice(0, 100) + '...' };
-        }
-      }
+      maxTokens: 10000,
     },
-    maxTokens: 10000,
-  })
-  .step('Format Results', ({ state, brainState }) => ({
+  }))
+  .step('Format Results', ({ state }) => ({
     ...state,
-    researchResults: brainState.response
+    researchResults: state.summary,
   }));
 ```
 
-### Agent Configuration Options
+### Prompt Config (with loop)
+
+- `message: string | TemplateReturn` - The user prompt sent to the LLM
+- `system?: string | TemplateReturn` - System prompt (optional, works with or without loop)
+- `outputSchema: ZodSchema` - **Required.** Structured output schema. With `loop`, generates a terminal `done` tool. Without `loop`, used for single-shot structured output.
+- `loop.tools: Record<string, Tool>` - Tools available to the LLM
+- `loop.maxTokens?: number` - Maximum cumulative tokens across all iterations
+- `loop.maxIterations?: number` - Maximum loop iterations (default: 100)
+- `loop.toolChoice?: 'auto' | 'required' | 'none'` - Tool choice strategy (default: `'required'`)
 
-- `system: string` - System prompt for the agent
-- `prompt: string | ((state) => string)` - User prompt (can be a function)
-- `tools: Record<string, ToolDefinition>` - Tools available to the agent
-- `outputSchema: { schema, name }` - Structured output schema (see below)
-- `maxTokens: number` - Maximum tokens for the agent response
-- `maxIterations: number` - Maximum agent loop iterations (default: 100)
+Without `loop`, `.prompt()` makes a single `generateObject()` call — no tools, no iteration.
 
 ### Tool Definition
 
 Each tool requires:
 - `description: string` - What the tool does
 - `inputSchema: ZodSchema` - Zod schema for the tool's input
-- `execute: (input, context) => Promise<any>` - Function to execute when the tool is called
-- `terminal?: boolean` - If true, calling this tool ends the agent loop
+- `execute?: (input, context) => Promise<any>` - Function to execute when the tool is called
+- `terminal?: boolean` - If true, calling this tool ends the loop
 
 ### Tool Webhooks (waitFor)
 
-Tools can pause agent execution and wait for external events by returning `{ waitFor: webhook(...) }` from their `execute` function. This is useful for human-in-the-loop workflows where the agent needs to wait for approval, external API callbacks, or other asynchronous events.
+Tools can pause execution and wait for external events by returning `{ waitFor: webhook(...) }` from their `execute` function:
 
 ```typescript
 import approvalWebhook from '../webhooks/approval.js';
 
 brain('Support Ticket Handler')
-  .brain('Handle Support Request', {
+  .prompt('Handle Request', ({ state }) => ({
     system: 'You are a support agent. Escalate complex issues for human review.',
-    prompt: ({ ticket }) => `Handle this support ticket: <%= '${ticket.description}' %>`,
-    tools: {
-      escalateToHuman: {
-        description: 'Escalate the ticket to a human reviewer for approval',
-        inputSchema: z.object({
-          summary: z.string().describe('Summary of the issue'),
-          recommendation: z.string().describe('Your recommended action'),
-        }),
-        execute: async ({ summary, recommendation }, context) => {
-          // Send notification to human reviewer (e.g., via Slack, email)
-          await notifyReviewer({ summary, recommendation, ticketId: context.state.ticketId });
-
-          // Return waitFor to pause until the webhook fires
-          return {
-            waitFor: approvalWebhook(context.state.ticketId),
-          };
+    message: `Handle this support ticket: <%= '${state.ticket.description}' %>`,
+    outputSchema: z.object({
+      resolution: z.string().describe('How the ticket was resolved'),
+    }),
+    loop: {
+      tools: {
+        escalateToHuman: {
+          description: 'Escalate the ticket to a human reviewer for approval',
+          inputSchema: z.object({
+            summary: z.string().describe('Summary of the issue'),
+            recommendation: z.string().describe('Your recommended action'),
+          }),
+          execute: async ({ summary, recommendation }, context) => {
+            await notifyReviewer({ summary, recommendation, ticketId: context.state.ticketId });
+            return { waitFor: approvalWebhook(context.state.ticketId) };
+          },
         },
       },
-      resolveTicket: {
-        description: 'Mark the ticket as resolved',
-        inputSchema: z.object({
-          resolution: z.string().describe('How the ticket was resolved'),
-        }),
-        terminal: true,
-      },
     },
-  })
-  .step('Process Result', ({ state, response }) => ({
+  }))
+  .step('Process Result', ({ state }) => ({
     ...state,
-    // response contains the webhook data (e.g., { approved: true, reviewerNote: '...' })
-    approved: response?.approved,
-    reviewerNote: response?.reviewerNote,
+    handled: true,
   }));
 ```
 
 Key points about tool `waitFor`:
-- Return `{ waitFor: webhook(...) }` to pause the agent and wait for an external event
-- The webhook response is available in the next step via the `response` parameter
+- Return `{ waitFor: webhook(...) }` to pause and wait for an external event
+- The webhook response is fed back as a tool result — the loop continues with this data
 - You can wait for multiple webhooks (first response wins): `{ waitFor: [webhook1(...), webhook2(...)] }`
 - The `execute` function receives a `context` parameter with access to `state`, `options`, `env`, etc.
-- Use this pattern for approvals, external API callbacks, or any human-in-the-loop workflow
-- The built-in `waitForWebhook` tool defaults to a 1-hour timeout. Agents can customize via the `timeout` parameter (e.g., "30m", "24h", "7d"). If the timeout elapses, the brain is cancelled.
 
-### Agent Output Schema
+### Output Schema
 
-Use `outputSchema` to get structured, typed output from agent steps. This generates a terminal tool that the agent must call to complete, ensuring the output matches your schema:
+The `outputSchema` generates a terminal `done` tool that the LLM must call to complete. The result is spread directly onto state:
 
 ```typescript
 brain('Entity Extractor')
-  .brain('Extract Entities', {
+  .prompt('Extract Entities', () => ({
     system: 'You are an entity extraction assistant.',
-    prompt: 'Extract all people and organizations from the provided text.',
-    outputSchema: {
-      schema: z.object({
-        people: z.array(z.string()).describe('Names of people mentioned'),
-        organizations: z.array(z.string()).describe('Organization names'),
-        confidence: z.number().min(0).max(1).describe('Confidence score'),
-      }),
-      name: 'entities' as const,  // Use 'as const' for type inference
-    },
-  })
+    message: 'Extract all people and organizations from the provided text.',
+    outputSchema: z.object({
+      people: z.array(z.string()).describe('Names of people mentioned'),
+      organizations: z.array(z.string()).describe('Organization names'),
+      confidence: z.number().min(0).max(1).describe('Confidence score'),
+    }),
+    loop: { tools: {} },
+  }))
   .step('Use Extracted Data', ({ state }) => {
-    // TypeScript knows state.entities has people, organizations, and confidence
-    console.log('Found ' + state.entities.people.length + ' people');
-    console.log('Found ' + state.entities.organizations.length + ' organizations');
+    // TypeScript knows state has people, organizations, and confidence
     return {
       ...state,
-      summary: 'Extracted ' + state.entities.people.length + ' people and ' +
-               state.entities.organizations.length + ' organizations',
+      summary: 'Extracted ' + state.people.length + ' people and ' +
+               state.organizations.length + ' organizations',
     };
   });
 ```
 
-Key points about `outputSchema`:
-- The agent automatically gets a `done` tool that uses your schema
-- The result is stored under `state[name]` (e.g., `state.entities`)
+Key points:
+- The `done` tool is auto-generated from your `outputSchema`
+- If the LLM provides invalid output, the error is fed back so it can retry
+- The result is spread directly onto state (e.g., `state.people`, `state.organizations`)
 - Full TypeScript type inference flows to subsequent steps
-- Use `as const` on the name for proper type narrowing
 
 ## Environment and Pages Service
 
@@ -1437,92 +1513,113 @@ The created page object contains:
 - `url: string` - Public URL to access the page
 - `webhook: WebhookConfig` - Webhook configuration for handling form submissions
 
-### Custom Pages with Forms (CSRF Token)
-
-When building custom HTML pages with forms, you must include a CSRF token to prevent unauthorized submissions. The `.ui()` step handles this automatically, but custom pages require manual setup. This applies whether you submit to the built-in `ui-form` endpoint or to a custom webhook.
+### Custom HTML Pages
 
-#### Using a Custom Webhook
+When you need full control over the page HTML (instead of having the LLM generate it), use `.page()` with the `html` property. The framework handles CSRF tokens, webhook registration, suspension, and form data merging automatically — same as LLM-generated pages.
 
-If your page submits to a custom webhook (e.g., `/webhooks/archive`), pass the token as the second argument when creating the webhook registration:
+Rename your brain file to `.tsx` and use JSX to build the page:
 
-```typescript
-import { generateFormToken } from '@positronic/core';
-import archiveWebhook from '../webhooks/archive.js';
+```tsx
+import { z } from 'zod';
+import { Form } from '@positronic/core';
 
 brain('Archive Workflow')
-  .step('Create Page', async ({ state, pages, env }) => {
-    const formToken = generateFormToken();
-
-    const html = `<html>
-      <body>
-        <form method="POST" action="<%= '${env.origin}' %>/webhooks/archive">
-          <input type="hidden" name="__positronic_token" value="<%= '${formToken}' %>">
-          <input type="text" name="name" placeholder="Your name">
-          <button type="submit">Submit</button>
-        </form>
-      </body>
-    </html>`;
-
-    await pages.create('my-page', html);
-    return { ...state, formToken };
+  .step('Fetch data', async ({ state }) => {
+    return { ...state, items: await fetchItems() };
   })
-  .wait('Wait for submission', ({ state }) => archiveWebhook(state.sessionId, state.formToken), { timeout: '24h' })
-  .step('Process', ({ state, response }) => ({
-    ...state,
-    name: response.name,
-  }));
+  .page('Review', ({ state }) => ({
+    html: (
+      <Form>
+        {state.items.map(item => (
+          <label>
+            <input type="checkbox" name="selectedIds" value={item.id} />
+            {item.name}
+          </label>
+        ))}
+        <button type="submit">Confirm</button>
+      </Form>
+    ),
+    formSchema: z.object({ selectedIds: z.array(z.string()) }),
+    onCreated: async (page) => {
+      // Notify user — page.url is the public URL
+    },
+  }))
+  .step('Process', ({ state }) => {
+    // state.selectedIds comes from the form submission
+    return { ...state, processed: true };
+  });
 ```
 
-#### Using the System `ui-form` Endpoint
+**Key details:**
+
+- **`Form`** is imported from `@positronic/core`. It's a Symbol-based built-in component (like `Fragment`, `File`, `Resource`). The framework injects the form action URL (including CSRF token) during rendering.
+- **`html`** accepts JSX directly, a string, or a function component.
+- The page is wrapped in a full HTML document with the step title as `<title>`.
+- You can use any HTML elements (`<div>`, `<input>`, `<table>`, etc.) and include `<style>` tags for custom CSS.
+- Read-only pages (no `formSchema`) work too — they complete immediately without suspending.
+
+#### Extracting Page JSX into Separate Files
+
+For complex pages, extract the JSX into a separate `.tsx` file:
+
+```tsx
+// brains/my-brain/pages/review-page.tsx
+import { Form } from '@positronic/core';
+export function ReviewPage({ items }: { items: { id: string; name: string }[] }) {
+  return (
+    <Form>
+      {items.map(item => (
+        <label>
+          <input type="checkbox" name="selectedIds" value={item.id} />
+          {item.name}
+        </label>
+      ))}
+      <button type="submit">Confirm</button>
+    </Form>
+  );
+}
+```
 
-If your page submits to the built-in `ui-form` endpoint, include the token in the webhook registration object:
+Then use it in the brain:
 
-```typescript
-import { generateFormToken } from '@positronic/core';
-
-brain('Custom Form')
-  .step('Create Form Page', async ({ state, pages, env }) => {
-    const formToken = generateFormToken();
-    const webhookIdentifier = `custom-form-<%= '${Date.now()}' %>`;
-    const formAction = `<%= '${env.origin}' %>/webhooks/system/ui-form?identifier=<%= '${encodeURIComponent(webhookIdentifier)}' %>`;
-
-    const page = await pages.create('my-form', `<html>
-      <body>
-        <form method="POST" action="<%= '${formAction}' %>">
-          <input type="hidden" name="__positronic_token" value="<%= '${formToken}' %>">
-          <input type="text" name="name" placeholder="Your name">
-          <button type="submit">Submit</button>
-        </form>
-      </body>
-    </html>`);
+```tsx
+import { ReviewPage } from './pages/review-page.js';
 
-    return {
-      ...state,
-      pageUrl: page.url,
-      webhook: { slug: 'ui-form', identifier: webhookIdentifier, token: formToken },
-    };
-  })
-  .wait('Wait for form', ({ state }) => state.webhook)
-  .step('Process', ({ state, response }) => ({
-    ...state,
-    name: response.name,
-  }));
+brain('Archive Workflow')
+  .page('Review', ({ state }) => ({
+    html: <ReviewPage items={state.items} />,
+    formSchema: z.object({ selectedIds: z.array(z.string()) }),
+  }))
 ```
 
-#### Summary
+This works because the positronic JSX runtime handles function components — it calls them with their props and renders the result. The `.tsx` file inherits `jsxImportSource: "@positronic/core"` from the project tsconfig.
+
+**Important:** Do NOT annotate the return type on page components. JSX produces `TemplateNode` (which is `JSX.Element`). Writing `: TemplateChild` or `: ReactNode` will cause type errors. Let TypeScript infer.
+
+**HTML elements work in page JSX.** `<div>`, `<input>`, `<label>`, `<table>`, `<style>`, etc. are all valid. This is specific to the `html` property on `.page()`. Prompt JSX (`.prompt()`, `.map()`) only supports `<>` (Fragment), `<File>`, `<Resource>`, and function components.
+
+#### No JavaScript in Custom Pages
+
+Custom HTML pages are static — `<script>` tags are blocked by Content Security Policy. This prevents XSS when user data is interpolated into page content.
+
+Form submission doesn't need JS — native HTML forms work. Unchecked checkboxes don't submit, and the framework's `parseFormData` handles duplicate field names as arrays.
 
-The three required pieces for any custom page with a form:
-1. Call `generateFormToken()` to get a token
-2. Add `<input type="hidden" name="__positronic_token" value="...">` to your form
-3. Include the `token` in your webhook registration — either as the second argument to a custom webhook function (e.g., `myWebhook(identifier, token)`) or in the registration object for `ui-form`
+For interactive UI (tabs, toggles), use `<details>`/`<summary>`:
 
-Without a token, the server will reject the form submission.
+```tsx
+{categories.map(cat => (
+  <details open={cat === firstCategory}>
+    <summary>{cat.label} ({cat.count})</summary>
+    <ItemList items={cat.items} />
+  </details>
+))}
+```
 
-## UI Steps
+## Page Steps
 
-UI steps allow brains to generate dynamic user interfaces using AI. The `.ui()` step generates a page and provides a `page` object to the next step. You then notify users and use `.wait()` to pause until the form is submitted.
+Page steps allow brains to generate dynamic user interfaces using AI. When `formSchema` is provided, `.page()` generates a page, auto-suspends the brain, and spreads the form response directly onto state. Use the optional `onCreated` callback for side effects (Slack messages, emails) that need access to the generated page URL.
 
-### Basic UI Step
+### Basic Page Step
 
 ```typescript
 import { z } from 'zod';
@@ -1532,55 +1629,49 @@ brain('Feedback Collector')
     ...state,
     userName: 'John Doe',
   }))
-  // Generate the form
-  .ui('Collect Feedback', {
-    template: (state) => `
+  // Generate the form, onCreated users, auto-suspend, auto-merge response
+  .page('Collect Feedback', ({ state, slack }) => ({
+    prompt: `
       Create a feedback form for <%= '${state.userName}' %>.
       Include fields for rating (1-5) and comments.
     `,
-    responseSchema: z.object({
+    formSchema: z.object({
       rating: z.number().min(1).max(5),
       comments: z.string(),
     }),
-  })
-  // Notify user
-  .step('Notify', async ({ state, page, slack }) => {
-    await slack.post('#feedback', `Please fill out: <%= '${page.url}' %>`);
-    return state;
-  })
-  // Wait for form submission (timeout after 24 hours, brain is cancelled if no response)
-  .wait('Wait for submission', ({ page }) => page.webhook, { timeout: '24h' })
-  // Process the form data (comes through response, not page)
-  .step('Process Feedback', ({ state, response }) => ({
+    onCreated: async (page) => {
+      await slack.post('#feedback', `Please fill out: <%= '${page.url}' %>`);
+    },
+  }))
+  // No .handle() needed — form data spreads onto state
+  .step('Process Feedback', ({ state }) => ({
     ...state,
     feedbackReceived: true,
-    rating: response.rating,     // typed from responseSchema
-    comments: response.comments,
+    // state.rating and state.comments are typed
   }));
 ```
 
-### How UI Steps Work
+### How Page Steps Work
 
-1. **Template**: The `template` function generates a prompt describing the desired UI
+1. **Prompt**: The `prompt` value describes the desired UI
 2. **AI Generation**: The AI creates a component tree based on the prompt
-3. **Page Object**: Next step receives `page` with `url` and `webhook`
-4. **Notification**: You notify users however you want (Slack, email, etc.)
-5. **Wait**: Use `.wait('title', ({ page }) => page.webhook)` to pause until form submission
-6. **Form Data**: Step after `.wait()` receives form data via `response`
+3. **onCreated**: The optional `onCreated` callback runs with a `page` object containing `url` and `webhook`. Use it to notify users (Slack, email, etc.)
+4. **Auto-Suspend**: The brain automatically suspends and waits for the form submission
+5. **Auto-Spread**: The form data is automatically spread onto state (`{ ...state, ...formData }`)
 
 ### The `page` Object
 
-After a `.ui()` step, the next step receives:
+The `page` object is available inside the `onCreated` callback:
 - `page.url` - URL where users can access the form
 - `page.webhook` - Pre-configured webhook for form submissions
 
-### Template Best Practices
+### Prompt Best Practices
 
 Be specific about layout and content:
 
 ```typescript
-.ui('Contact Form', {
-  template: (state) => `
+.page('Contact Form', ({ state }) => ({
+  prompt: `
     Create a contact form with:
     - Header: "Get in Touch"
     - Name field (required)
@@ -1590,12 +1681,12 @@ Be specific about layout and content:
 
     Use a clean, centered single-column layout.
   `,
-  responseSchema: z.object({
+  formSchema: z.object({
     name: z.string(),
     email: z.string().email(),
     message: z.string(),
   }),
-})
+}))
 ```
 
 ### Data Bindings
@@ -1603,78 +1694,71 @@ Be specific about layout and content:
 Use `{{path}}` syntax to bind props to runtime data:
 
 ```typescript
-.ui('Order Summary', {
-  template: (state) => `
+.page('Order Summary', ({ state }) => ({
+  prompt: `
     Create an order summary showing:
     - List of items from {{cart.items}}
     - Total: {{cart.total}}
     - Shipping address input
     - Confirm button
   `,
-  responseSchema: z.object({
+  formSchema: z.object({
     shippingAddress: z.string(),
   }),
-})
+}))
 ```
 
 ### Multi-Step Forms
 
-Chain UI steps for multi-page workflows:
+Chain page steps for multi-page workflows:
 
 ```typescript
 brain('User Onboarding')
   .step('Start', () => ({ userData: {} }))
 
   // Step 1: Personal info
-  .ui('Personal Info', {
-    template: () => `
+  .page('Personal Info', ({ notify }) => ({
+    prompt: `
       Create a form for personal information:
       - First name, Last name
       - Date of birth
       - Next button
     `,
-    responseSchema: z.object({
+    formSchema: z.object({
       firstName: z.string(),
       lastName: z.string(),
       dob: z.string(),
     }),
-  })
-  .step('Notify Personal', async ({ state, page, notify }) => {
-    await notify(`Step 1: <%= '${page.url}' %>`);
-    return state;
-  })
-  .wait('Wait for Personal', ({ page }) => page.webhook)
-  .step('Save Personal', ({ state, response }) => ({
-    ...state,
-    userData: { ...state.userData, ...response },
+    onCreated: async (page) => {
+      await notify(`Step 1: <%= '${page.url}' %>`);
+    },
   }))
+  // No .handle() needed — form data spreads onto state
 
   // Step 2: Preferences
-  .ui('Preferences', {
-    template: (state) => `
-      Create preferences form for <%= '${state.userData.firstName}' %>:
+  .page('Preferences', ({ state, notify }) => ({
+    prompt: `
+      Create preferences form for <%= '${state.firstName}' %>:
       - Newsletter subscription checkbox
       - Contact preference (email/phone/sms)
       - Complete button
     `,
-    responseSchema: z.object({
+    formSchema: z.object({
       newsletter: z.boolean(),
       contactMethod: z.enum(['email', 'phone', 'sms']),
     }),
-  })
-  .step('Notify Preferences', async ({ state, page, notify }) => {
-    await notify(`Step 2: <%= '${page.url}' %>`);
-    return state;
-  })
-  .wait('Wait for Preferences', ({ page }) => page.webhook)
-  .step('Complete', ({ state, response }) => ({
+    onCreated: async (page) => {
+      await notify(`Step 2: <%= '${page.url}' %>`);
+    },
+  }))
+  // No .handle() needed — form data spreads onto state
+  .step('Complete', ({ state }) => ({
     ...state,
-    userData: { ...state.userData, preferences: response },
     onboardingComplete: true,
   }));
 ```
 
-For more details on UI steps, see the full UI Step Guide in the main Positronic documentation.
+For more details on page steps, see the full Page Step Guide in the main Positronic documentation.
 
 ## Complete Example
 
@@ -1683,53 +1767,38 @@ import { brain } from '../brain.js';
 import { BrainRunner } from '@positronic/core';
 import { z } from 'zod';
 
-// Define services
-interface Services {
-  logger: Logger;
-  analytics: {
-    track: (event: string, properties?: any) => void;
-  };
-}
-
 // Create brain with all features
 const completeBrain = brain({
   title: 'Complete Example',
   description: 'Demonstrates all Brain DSL features',
 })
-  .withServices<Services>({
-    logger: console,
-    analytics: {
-      track: (event, props) => console.log('Track:', event, props)
-    }
-  })
+  .withPlugin(logger)
+  .withPlugin(analytics)
   .step('Initialize', ({ logger, analytics }) => {
     logger.log('Starting workflow');
     analytics.track('brain_started');
     return { startTime: Date.now() };
   })
   .prompt('Generate Plan', {
-    template: async (state, resources) => {
+    message: async ({ state, resources }) => {
       // Load a template from resources
       const template = await resources.templates.projectPlan.load();
       return template.replace('{{context}}', 'software project');
     },
-    outputSchema: {
-      schema: z.object({
-        tasks: z.array(z.string()),
-        duration: z.number(),
-      }),
-      name: 'plan' as const,
-    },
+    outputSchema: z.object({
+      tasks: z.array(z.string()),
+      duration: z.number(),
+    }),
   })
   .step('Process Plan', ({ state, logger, analytics }) => {
-    logger.log(`Plan generated with <%= '${state.plan.tasks.length}' %> tasks`);
+    logger.log(`Plan generated with <%= '${state.tasks.length}' %> tasks`);
     analytics.track('plan_processed', {
-      task_count: state.plan.tasks.length,
-      duration: state.plan.duration
+      task_count: state.tasks.length,
+      duration: state.duration
     });
     return {
       ...state,
-      taskCount: state.plan.tasks.length,
+      taskCount: state.tasks.length,
       endTime: Date.now(),
     };
   });
@@ -1743,3 +1812,85 @@ const runner = new BrainRunner({
 const finalState = await runner.run(completeBrain);
 console.log('Completed:', finalState);
 ```
+
+## Files Service
+
+The `files` service is available on the step context for creating, reading, and managing files.
+
+### Basic Usage
+
+```typescript
+.step("Save report", async ({ files }) => {
+  const file = files.open('report.txt');
+  await file.write('Report content');
+  const url = file.url; // public download URL
+  return { reportFile: file.name }; // store name in state, not URL
+})
+```
+
+### Streaming Writes
+
+```typescript
+// Stream from a URL — never buffered
+await file.write(await fetch('https://example.com/large.mp3'));
+
+// Copy between files
+await file.write(files.open('source.txt'));
+```
+
+### Zip Builder
+
+```typescript
+.step("Bundle", async ({ state, files }) => {
+  const zip = files.zip('results.zip');
+  await zip.write('data.txt', 'content');
+  await zip.write('audio.mp3', await fetch(state.mp3Url));
+  const ref = await zip.finalize();
+  return { downloadUrl: files.open(ref.name).url };
+})
+```
+
+### Scoping
+
+```typescript
+files.open('data.txt');                          // 'brain' (default) — persists across runs
+files.open('temp.txt', { scope: 'run' });        // cleaned up after run
+files.open('profile.json', { scope: 'global' }); // persists across brains
+```
+
+### JSX Components
+
+```tsx
+import { File, Resource } from '@positronic/core';
+
+.prompt("Analyze", ({ state }) => ({
+  prompt: (
+    <>
+      <Resource name="guidelines" />
+      <File name={state.transcriptFile} />
+    </>
+  ),
+  outputSchema: z.object({ summary: z.string() }),
+}))
+```
+
+### Attachments
+
+```typescript
+.prompt("Analyze PDF", async ({ files }) => ({
+  prompt: "Analyze the attached document.",
+  attachments: [files.open('report.pdf')],
+  outputSchema: z.object({ summary: z.string() }),
+}))
+```
+
+### Agent Tools
+
+```typescript
+import { readFile, writeFile } from '@positronic/core';
+
+.brain("Analyze", () => ({
+  prompt: "Review the files and write a summary.",
+  tools: { readFile, writeFile },
+}))
+```