@positronic/template-new-project 0.0.53 → 0.0.55

package/index.js

@@ -53,10 +53,10 @@ module.exports = {
   ],
   setup: async ctx => {
     const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
-    let coreVersion = '^0.0.53';
-    let cloudflareVersion = '^0.0.53';
-    let clientVercelVersion = '^0.0.53';
-    let genUIComponentsVersion = '^0.0.53';
+    let coreVersion = '^0.0.55';
+    let cloudflareVersion = '^0.0.55';
+    let clientVercelVersion = '^0.0.55';
+    let genUIComponentsVersion = '^0.0.55';
 
     // Map backend selection to package names
     const backendPackageMap = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@positronic/template-new-project",
-  "version": "0.0.53",
+  "version": "0.0.55",
   "publishConfig": {
     "access": "public"
   },

package/template/{components → .positronic}/bundle.ts

@@ -1,13 +1,13 @@
 /**
  * Bundle entry point for client-side rendering.
  *
- * This file is bundled by esbuild into dist/components.js which exposes
+ * This file is bundled by esbuild into .positronic/dist/components.js which exposes
  * React components to window.PositronicComponents for use by generated pages.
  *
- * When you add custom components to ./index.ts, they will automatically
+ * When you add custom components to components/index.ts, they will automatically
  * be included in the bundle.
  */
-import { components } from './index.js';
+import { components } from '../components/index.js';
 
 // Extract the React component from each UIComponent and expose to window
 const PositronicComponents: Record<string, React.ComponentType<any>> = {};

package/template/CLAUDE.md

@@ -38,7 +38,8 @@ For testing guidance, see `/docs/brain-testing-guide.md`
 The Brain DSL provides a fluent API for defining AI workflows:
 
 ```typescript
-import { brain } from '@positronic/core';
+// Import from the project brain wrapper (see positronic-guide.md)
+import { brain } from '../brain.js';
 
 const myBrain = brain('my-brain')
   .step('Initialize', ({ state }) => ({
@@ -46,12 +47,12 @@ const myBrain = brain('my-brain')
     initialized: true
   }))
   .step('Process', async ({ state, resources }) => {
-    // Access resources
-    const doc = await resources.get('example.md');
+    // Access resources with type-safe API
+    const content = await resources.example.loadText();
     return {
       ...state,
       processed: true,
-      content: doc.content
+      content
     };
   });
 

package/template/_env

@@ -1,6 +1,10 @@
 # Development Environment
 NODE_ENV=development
 
+# Google AI API Key (required for running brains)
+# Get your API key at https://aistudio.google.com/apikey
+GOOGLE_GENERATIVE_AI_API_KEY=
+
 # Cloudflare R2 Configuration
 R2_BUCKET_NAME=<%= projectName %>
 

package/template/_gitignore

@@ -16,12 +16,11 @@ node_modules/
 # Mac specific
 .DS_Store
 
-dist/
-
 # Test coverage
 coverage/
 
 .positronic-server.log
 .positronic-server.pid
 
-resources.d.ts
+resources.d.ts
+secrets.d.ts

package/template/brain.ts

@@ -1,8 +1,8 @@
-import { createBrain } from '@positronic/core';
+import { createBrain, defaultTools } from '@positronic/core';
 import { components } from './components/index.js';
 
 /**
- * Project-level brain function with pre-configured components.
+ * Project-level brain function with pre-configured components and tools.
  *
  * All brains in your project should import from this file:
  *
@@ -13,10 +13,15 @@ import { components } from './components/index.js';
  *   .step('Do something', ({ state }) => ({ ...state, done: true }));
  * ```
  *
+ * Default tools available in agent steps:
+ * - generateUI: Generate interactive UI components
+ * - consoleLog: Log messages for debugging
+ * - done: Complete the agent and return a result
+ *
  * To add services (e.g., Slack, Gmail, database clients):
  *
  * ```typescript
- * import { createBrain } from '@positronic/core';
+ * import { createBrain, defaultTools } from '@positronic/core';
  * import { components } from './components/index.js';
  * import slack from './services/slack.js';
  * import gmail from './services/gmail.js';
@@ -24,6 +29,7 @@ import { components } from './components/index.js';
  * export const brain = createBrain({
  *   services: { slack, gmail },
  *   components,
+ *   defaultTools,
  * });
  * ```
  *
@@ -37,27 +43,24 @@ import { components } from './components/index.js';
  *   });
  * ```
  *
- * You can also create agents directly:
+ * You can also create agents directly with access to default tools:
  *
  * ```typescript
- * export default brain('my-agent', ({ slack, env }) => ({
+ * export default brain('my-agent', ({ slack, tools }) => ({
  *   system: 'You are a helpful assistant',
  *   prompt: 'Help the user with their request',
  *   tools: {
+ *     ...tools, // includes generateUI, consoleLog, done
  *     notify: {
  *       description: 'Send a Slack notification',
  *       inputSchema: z.object({ message: z.string() }),
  *       execute: ({ message }) => slack.postMessage('#general', message),
  *     },
- *     done: {
- *       description: 'Complete the task',
- *       inputSchema: z.object({ result: z.string() }),
- *       terminal: true,
- *     },
  *   },
  * }));
  * ```
  */
 export const brain = createBrain({
   components,
+  defaultTools,
 });

package/template/brains/hello.ts

@@ -0,0 +1,33 @@
+import { brain } from '../brain.js';
+
+/**
+ * A simple agent brain that demonstrates the default tools.
+ *
+ * This brain uses only a system prompt and tools - no explicit user prompt needed.
+ * When prompt is omitted, the agent automatically starts with "Begin."
+ *
+ * This brain:
+ * 1. Uses generateUI to create a form asking for the user's name
+ * 2. Waits for the user to submit the form
+ * 3. Uses consoleLog to log a personalized greeting
+ * 4. Uses done to complete with a welcome message
+ *
+ * Run with: px brain run hello
+ */
+export default brain('hello', ({ tools }) => ({
+  system: `You are a friendly greeter for the Positronic framework.
+Your job is to welcome new users and make them feel excited about building AI workflows.
+
+When you start:
+1. Use generateUI to create a simple, welcoming form that asks for the user's name
+   (use a friendly title and a single text input)
+2. After receiving their name, use consoleLog to log a warm, personalized greeting
+3. Use done to complete with an encouraging message about what they can build
+
+You have access to these tools:
+- generateUI: Create a form to collect the user's name
+- consoleLog: Log messages to the console
+- done: Complete the greeting with a final message`,
+
+  tools,
+}));

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

@@ -165,7 +165,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
-- Custom services (if configured with `.withServices()`)
+- `response` - Webhook response data (available after `waitFor` 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()`)
 
 ## Configuration Methods
 
@@ -473,15 +477,141 @@ expect(result.finalState.data).toEqual({ id: '123', name: 'Test' });
 - Services are not serialized - they're for side effects and external interactions
 - Each brain instance maintains its own service references
 
+### Tool Configuration with `withTools()`
+
+The `withTools()` method registers tools that can be used by agent steps:
+
+```typescript
+import { z } from 'zod';
+
+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));
+        }
+        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
+  });
+```
+
+### Component Configuration with `withComponents()`
+
+The `withComponents()` method registers custom UI components for use in `.ui()` steps:
+
+```typescript
+const brainWithComponents = brain('Custom UI Brain')
+  .withComponents({
+    CustomCard: {
+      description: 'A styled card component for displaying content',
+      props: z.object({
+        title: z.string(),
+        content: z.string(),
+        variant: z.enum(['default', 'highlighted', 'warning']).default('default')
+      }),
+      render: (props) => `
+        <div class="card card-<%= '${props.variant}' %>">
+          <h3><%= '${props.title}' %></h3>
+          <p><%= '${props.content}' %></p>
+        </div>
+      `
+    },
+    DataTable: {
+      description: 'A table for displaying structured data',
+      props: z.object({
+        headers: z.array(z.string()),
+        rows: z.array(z.array(z.string()))
+      }),
+      render: (props) => {
+        // Build table HTML from headers and rows
+        const headerRow = props.headers.map(h => '<th>' + h + '</th>').join('');
+        const bodyRows = props.rows.map(row =>
+          '<tr>' + row.map(cell => '<td>' + cell + '</td>').join('') + '</tr>'
+        ).join('');
+        return '<table><thead><tr>' + headerRow + '</tr></thead><tbody>' + bodyRows + '</tbody></table>';
+      }
+    }
+  })
+  .ui('Dashboard', {
+    template: (state) => `
+      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({
+      acknowledged: z.boolean()
+    })
+  });
+```
+
+### Using `createBrain()` for Project Configuration
+
+For project-wide configuration, use `createBrain()` in your `brain.ts` file:
+
+```typescript
+// brain.ts
+import { createBrain } from '@positronic/core';
+import { z } from 'zod';
+
+export const brain = createBrain({
+  services: {
+    logger: console,
+    api: apiClient
+  },
+  tools: {
+    search: {
+      description: 'Search the web',
+      inputSchema: z.object({ query: z.string() }),
+      execute: async ({ query }) => searchWeb(query)
+    }
+  },
+  components: {
+    Alert: {
+      description: 'Alert banner',
+      props: z.object({ message: z.string(), type: z.enum(['info', 'warning', 'error']) }),
+      render: (props) => `<div class="alert alert-<%= '${props.type}' %>"><%= '${props.message}' %></div>`
+    }
+  }
+});
+```
+
+All brains created with this factory will have access to the configured services, tools, and components.
+
 ## Running Brains
 
 ### Basic Execution
 
 ```typescript
-const brain = brain('Simple').step('Process', () => ({ result: 'done' }));
+const myBrain = brain('Simple').step('Process', () => ({ result: 'done' }));
 
 // Run and collect events
-for await (const event of brain.run({ client: aiClient })) {
+for await (const event of myBrain.run({ client: aiClient })) {
   console.log(event.type); // START, STEP_START, STEP_COMPLETE, etc.
 }
 ```
@@ -678,6 +808,178 @@ Extract prompts to separate files when:
 - The prompt might be reused in other brains
 - You want to test the prompt logic separately
 
+## Batch Prompt Mode
+
+When you need to run the same prompt over multiple items, use batch mode with the `over` option:
+
+```typescript
+brain('Batch 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
+    }
+  }, {
+    over: (state) => state.items,  // Array to iterate over
+    concurrency: 10,               // Parallel requests (default: 10)
+    stagger: 100,                  // Delay between requests in ms
+    retry: {
+      maxRetries: 3,
+      backoff: 'exponential',
+      initialDelay: 1000,
+      maxDelay: 30000,
+    },
+    error: (item, error) => ({ summary: 'Failed to summarize' })  // Fallback on error
+  })
+  .step('Process Results', ({ state }) => ({
+    ...state,
+    // summaries is [item, response][] - array of tuples
+    processedSummaries: state.summaries.map(([item, response]) => ({
+      id: item.id,
+      summary: response.summary
+    }))
+  }));
+```
+
+### Batch Options
+
+- `over: (state) => T[]` - Function returning the array to iterate over
+- `concurrency: number` - Maximum parallel requests (default: 10)
+- `stagger: number` - Milliseconds to wait between starting requests
+- `retry: RetryConfig` - Retry configuration for failed requests
+- `error: (item, error) => Response` - Fallback function when a request fails
+
+### Result Format
+
+The result is stored as an array of `[item, response]` tuples, preserving the relationship between each input item and its generated response.
+
+## Agent Steps
+
+For complex AI workflows that require tool use, use the `.brain()` method with an agent configuration:
+
+```typescript
+brain('Research Assistant')
+  .step('Initialize', () => ({
+    query: 'What are the latest developments in AI?'
+  }))
+  .brain('Research Agent', {
+    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 };
+        }
+      },
+      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,
+  })
+  .step('Format Results', ({ state, brainState }) => ({
+    ...state,
+    researchResults: brainState.response
+  }));
+```
+
+### Agent Configuration Options
+
+- `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
+- `maxTokens: number` - Maximum tokens for the agent response
+
+### Tool Definition
+
+Each tool requires:
+- `description: string` - What the tool does
+- `inputSchema: ZodSchema` - Zod schema for the tool's input
+- `execute: (input) => Promise<any>` - Function to execute when the tool is called
+
+## Environment and Pages Service
+
+### The `env` Parameter
+
+Steps have access to the runtime environment via the `env` parameter:
+
+```typescript
+brain('Environment Example')
+  .step('Use Environment', ({ state, env }) => {
+    // env.origin - Base URL of the deployment
+    console.log('Running at:', env.origin);
+
+    // env.secrets - Type-augmented secrets object
+    const apiKey = env.secrets.EXTERNAL_API_KEY;
+
+    return {
+      ...state,
+      baseUrl: env.origin,
+      configured: true
+    };
+  });
+```
+
+### The `pages` Service
+
+The `pages` service allows you to create and manage HTML pages programmatically:
+
+```typescript
+brain('Page Creator')
+  .step('Create Custom Page', async ({ state, pages, env }) => {
+    // Create a page with HTML content
+    const page = await pages.create(
+      `<html>
+        <body>
+          <h1>Hello, <%= '${state.userName}' %>!</h1>
+          <p>Your dashboard is ready.</p>
+        </body>
+      </html>`,
+      { persist: true }  // Keep the page after brain completes
+    );
+
+    return {
+      ...state,
+      dashboardUrl: page.url,      // URL where users can view the page
+      pageWebhook: page.webhook    // Webhook for form submissions (if any)
+    };
+  })
+  .step('Notify User', async ({ state, slack }) => {
+    await slack.post('#general', `Your dashboard: <%= '${state.dashboardUrl}' %>`);
+    return state;
+  });
+```
+
+### Page Options
+
+- `persist: boolean` - If true, the page remains accessible after the brain completes
+
+### Page Object
+
+The created page object contains:
+- `url: string` - Public URL to access the page
+- `webhook: WebhookConfig` - Webhook configuration for handling form submissions
+
 ## UI 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 `waitFor` to pause until the form is submitted.

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

@@ -56,7 +56,7 @@ const result = await runBrainTest(brain, {
   client: mockClient,           // Optional: defaults to createMockClient()
   initialState: { count: 0 },   // Optional: initial state
   resources: resourceLoader,    // Optional: resources
-  brainOptions: { mode: 'test' } // Optional: brain-specific options
+  options: { mode: 'test' } // Optional: brain-specific options
 });
 ```
 
@@ -64,9 +64,9 @@ const result = await runBrainTest(brain, {
 - `completed: boolean` - Whether the brain completed successfully
 - `error: Error | null` - Any error that occurred
 - `finalState: State` - The final state after all steps
-- `steps: string[]` - Names of executed steps in order
+- `events: BrainEvent[]` - All emitted events during execution
 
-## MockObjectGenerator API
+## MockClient API
 
 ### Creating a Mock Client
 
@@ -76,44 +76,42 @@ const mockClient = createMockClient();
 
 ### Mocking Responses
 
-#### Single Response
-```typescript
-mockClient.mockNextResponse({
-  answer: 'The capital of France is Paris',
-  confidence: 0.95
-});
-```
+Queue responses that will be consumed in order by `generateObject` calls:
 
-#### Multiple Responses
 ```typescript
+// Queue one or more responses
 mockClient.mockResponses(
   { step1: 'completed' },
   { step2: 'processed' },
   { finalResult: 'success' }
 );
-```
 
-#### Error Responses
-```typescript
-mockClient.mockNextError('API rate limit exceeded');
-// or
-mockClient.mockNextError(new Error('Connection timeout'));
+// Clear all mocked responses
+mockClient.clearMocks();
 ```
 
 ### Assertions
 
+Use standard Jest assertions on the mock:
+
 ```typescript
 // Check call count
-mockClient.expectCallCount(3);
+expect(mockClient.generateObject).toHaveBeenCalledTimes(3);
 
 // Check call parameters
-mockClient.expectCalledWith({
-  prompt: 'Generate a summary',
-  schemaName: 'summarySchema'
-});
+expect(mockClient.generateObject).toHaveBeenCalledWith(
+  expect.objectContaining({
+    prompt: expect.stringContaining('Generate a summary')
+  })
+);
 
-// Get call history
-const calls = mockClient.getCalls();
+// Check specific call (0-indexed)
+expect(mockClient.generateObject).toHaveBeenNthCalledWith(
+  1,
+  expect.objectContaining({
+    prompt: expect.stringContaining('first prompt')
+  })
+);
 ```
 
 ## Testing Patterns
@@ -145,13 +143,19 @@ it('should generate personalized recommendations', async () => {
 
 ### Testing Error Cases
 
+To test error handling, create a mock client that throws:
+
 ```typescript
 it('should handle API failures gracefully', async () => {
-  // Arrange
-  mockClient.mockNextError('Service temporarily unavailable');
+  // Arrange - create a mock that throws on the first call
+  const errorClient = {
+    generateObject: jest.fn().mockRejectedValue(
+      new Error('Service temporarily unavailable')
+    )
+  };
 
   // Act
-  const result = await runBrainTest(processingBrain, { client: mockClient });
+  const result = await runBrainTest(processingBrain, { client: errorClient });
 
   // Assert
   expect(result.completed).toBe(false);
@@ -167,6 +171,7 @@ Verify that data flows correctly through your brain:
 it('should use customer data to generate personalized content', async () => {
   // Arrange
   const customerName = 'Alice';
+  const mockClient = createMockClient();
   mockClient.mockResponses(
     { greeting: 'Hello Alice!', tone: 'friendly' },
     { email: 'Personalized email content...' }
@@ -179,8 +184,11 @@ it('should use customer data to generate personalized content', async () => {
   });
 
   // Assert that the AI used the customer data
-  const calls = mockClient.getCalls();
-  expect(calls[0].params.prompt).toContain(customerName);
+  expect(mockClient.generateObject).toHaveBeenCalledWith(
+    expect.objectContaining({
+      prompt: expect.stringContaining(customerName)
+    })
+  );
   expect(result.finalState.email).toContain('Personalized email content');
 });
 ```
@@ -227,28 +235,23 @@ Following testing best practices, avoid testing:
 ## Complete Example
 
 ```typescript
-import { createMockClient, runBrainTest } from '@positronic/core';
-import analysisBrain from './analysis-brain.js';
+import { createMockClient, runBrainTest } from './test-utils.js';
+import analysisBrain from '../brains/analysis-brain.js';
 
 describe('analysis-brain', () => {
-  let mockClient;
-
-  beforeEach(() => {
-    mockClient = createMockClient();
-  });
-
   it('should analyze customer feedback and generate insights', async () => {
     // Arrange: Set up AI to return analysis
-    mockClient.mockNextResponse({
+    const mockClient = createMockClient();
+    mockClient.mockResponses({
       sentiment: 'positive',
       keywords: ['innovation', 'quality', 'service'],
       summary: 'Customers appreciate product quality and innovation'
     });
 
     // Act: Run analysis on customer feedback
-    const result = await runBrainTest(analysisBrain, { 
+    const result = await runBrainTest(analysisBrain, {
       client: mockClient,
-      initialState: { 
+      initialState: {
         feedback: 'Your product is innovative and high quality...'
       }
     });
@@ -265,14 +268,18 @@ describe('analysis-brain', () => {
 
   it('should handle analysis service outages', async () => {
     // Arrange: Simulate service failure
-    mockClient.mockNextError('Analysis service unavailable');
+    const errorClient = {
+      generateObject: jest.fn().mockRejectedValue(
+        new Error('Analysis service unavailable')
+      )
+    };
 
     // Act: Attempt analysis
-    const result = await runBrainTest(analysisBrain, { 
-      client: mockClient,
+    const result = await runBrainTest(analysisBrain, {
+      client: errorClient,
       initialState: { feedback: 'Some feedback...' }
     });
-    
+
     // Assert: Verify graceful failure
     expect(result.completed).toBe(false);
     expect(result.error?.message).toBe('Analysis service unavailable');
@@ -300,12 +307,12 @@ expect(result.finalState.myProperty).toBe('value');
 ### Debugging Tips
 
 ```typescript
-// See what prompts are being sent to AI
-const calls = mockClient.getCalls();
-console.log('AI prompts:', calls.map(c => c.params.prompt));
+// See what prompts were sent to AI
+const calls = mockClient.generateObject.mock.calls;
+console.log('AI prompts:', calls.map(c => c[0].prompt));
 
-// Check execution order
-console.log('Steps executed:', result.steps);
+// Check events that occurred during execution
+console.log('Events:', result.events.map(e => e.type));
 ```
 
 ## Next Steps

package/template/docs/positronic-guide.md

@@ -42,10 +42,10 @@ import { brain } from '@positronic/core';
 
 ### Configuring Services
 
-To add project-wide services, modify the `brain.ts` file in the root directory:
+To add project-wide services, modify the `brain.ts` file in the root directory using `createBrain()`:
 
 ```typescript
-import { brain as coreBrain, type Brain } from '@positronic/core';
+import { createBrain } from '@positronic/core';
 
 // Define your services
 interface ProjectServices {
@@ -59,28 +59,25 @@ interface ProjectServices {
   };
 }
 
-// Export the wrapped brain function
-export function brain(
-  brainConfig: string | { title: string; description?: string }
-) {
-  return coreBrain(brainConfig)
-    .withServices({
-      logger: {
-        info: (msg) => console.log(`[<%= '${new Date().toISOString()}' %>] INFO: <%= '${msg}' %>`),
-        error: (msg) => console.error(`[<%= '${new Date().toISOString()}' %>] ERROR: <%= '${msg}' %>`)
+// Export the project brain factory
+export const brain = createBrain({
+  services: {
+    logger: {
+      info: (msg) => console.log(`[<%= '${new Date().toISOString()}' %>] INFO: <%= '${msg}' %>`),
+      error: (msg) => console.error(`[<%= '${new Date().toISOString()}' %>] ERROR: <%= '${msg}' %>`)
+    },
+    database: {
+      get: async (key) => {
+        // Your database implementation
+        return localStorage.getItem(key);
       },
-      database: {
-        get: async (key) => {
-          // Your database implementation
-          return localStorage.getItem(key);
-        },
-        set: async (key, value) => {
-          // Your database implementation
-          localStorage.setItem(key, JSON.stringify(value));
-        }
+      set: async (key, value) => {
+        // Your database implementation
+        localStorage.setItem(key, JSON.stringify(value));
       }
-    });
-}
+    }
+  }
+});
 ```
 
 Now all brains automatically have access to these services:
@@ -158,9 +155,9 @@ Use `.env` files for configuration:
 ANTHROPIC_API_KEY=your-key-here
 OPENAI_API_KEY=your-key-here
 
-# Backend-specific
-<% if (backend === 'cloudflare') { %>CLOUDFLARE_ACCOUNT_ID=your-account-id
-CLOUDFLARE_API_TOKEN=your-api-token<% } %>
+# Backend-specific (Cloudflare example)
+CLOUDFLARE_ACCOUNT_ID=your-account-id
+CLOUDFLARE_API_TOKEN=your-api-token
 ```
 
 ## Best Practices
@@ -224,7 +221,7 @@ const api = {
   post: async (path: string, data: any) => {
     const response = await fetch(`https://api.example.com<%= '${path}' %>`, {
       method: 'POST',
-      headers: { 
+      headers: {
         'Authorization': `Bearer <%= '${process.env.API_KEY}' %>`,
         'Content-Type': 'application/json'
       },

package/template/docs/tips-for-agents.md

@@ -247,22 +247,20 @@ services/
 Then in your `brain.ts` (at the project root):
 
 ```typescript
+import { createBrain } from '@positronic/core';
 import gmail from './services/gmail.js';
 import slack from './services/slack.js';
 import database from './services/database.js';
 import analytics from './services/analytics.js';
 
-export function brain(
-  brainConfig: string | { title: string; description?: string }
-) {
-  return coreBrain(brainConfig)
-    .withServices({
-      gmail,
-      slack,
-      database,
-      analytics
-    });
-}
+export const brain = createBrain({
+  services: {
+    gmail,
+    slack,
+    database,
+    analytics
+  }
+});
 ```
 
 This keeps your service implementations separate from your brain logic and makes them easier to test and maintain.
@@ -452,7 +450,7 @@ describe('FeedbackProcessor', () => {
 });
 
 // Step 2: Create minimal brain implementation
-import { brain } from '@positronic/core';
+import { brain } from '../brain.js';
 import { z } from 'zod';
 
 const feedbackBrain = brain('feedback-processor')

package/template/esbuild.config.mjs

@@ -1,7 +1,7 @@
 /**
  * esbuild configuration for bundling UI components.
  *
- * This bundles the components from ./components/bundle.ts into a single
+ * This bundles the components from .positronic/bundle.ts into a single
  * JavaScript file that can be served to the browser.
  *
  * Run: npm run build:components
@@ -10,11 +10,11 @@
 import * as esbuild from 'esbuild';
 
 await esbuild.build({
-  entryPoints: ['components/bundle.ts'],
+  entryPoints: ['.positronic/bundle.ts'],
   bundle: true,
   external: ['react', 'react-dom'],
   format: 'iife',
-  outfile: 'dist/components.js',
+  outfile: '.positronic/dist/components.js',
   jsx: 'transform',
   jsxFactory: 'React.createElement',
   jsxFragment: 'React.Fragment',

package/template/package.json

@@ -15,7 +15,8 @@
   "dependencies": {
     "zod": "^3.24.1",
     "@positronic/client-vercel": "<%= positronicClientVercelVersion %>",
-    "@ai-sdk/openai": "^1.3.22",
+    "@ai-sdk/google": "^3.0.13",
+    "ai": "^6.0.48",
     "@positronic/core": "<%= positronicCoreVersion %>",
     "@positronic/gen-ui-components": "<%= positronicGenUIComponentsVersion %>"<% if (backend === 'cloudflare') { %>,
     "@positronic/cloudflare": "<%= positronicCloudflareVersion %>"<% } %>
@@ -27,7 +28,7 @@
     "@jest/globals": "^30.0.4",
     "ts-jest": "^29.2.6",
     "@types/jest": "^30.0.0",
-    "esbuild": "^0.24.0",
+    "esbuild": "^0.27.2",
     "@types/react": "^18.2.0"
   }
 }

package/template/runner.ts

@@ -1,9 +1,9 @@
 import { BrainRunner } from '@positronic/core';
 import { VercelClient } from '@positronic/client-vercel';
-import { openai } from '@ai-sdk/openai';
+import { google } from '@ai-sdk/google';
 
 export const runner = new BrainRunner({
   adapters: [],
-  client: new VercelClient(openai('gpt-4o-mini')),
+  client: new VercelClient(google('gemini-3-pro-preview')),
   resources: {},
 });