@positronic/template-new-project 0.0.76 → 0.0.78

package/template/docs/positronic-guide.md

@@ -7,23 +7,28 @@ This guide covers project-level patterns and best practices for Positronic appli
 A typical Positronic project has the following structure:
 
 ```
-├── brain.ts         # Project brain wrapper
-├── brains/          # Brain definitions
+├── src/
+│   ├── brain.ts         # Project brain wrapper
+│   ├── brains/          # Brain definitions
+│   ├── plugins/         # Plugin definitions (webhooks, tools, services)
+│   ├── runner.ts        # Local runner for development
+│   ├── services/        # Service implementations
+│   ├── utils/           # Shared utilities
+│   └── components/      # Reusable UI/prompt components
 ├── resources/       # Files accessible to brains
 ├── tests/           # Test files
 ├── docs/            # Documentation
-├── runner.ts        # Local runner for development
 └── positronic.config.json  # Project configuration
 ```
 
 ## The Project Brain Pattern
 
-Every Positronic project includes a `brain.ts` file in the root directory. This file exports a custom `brain` function that wraps the core Positronic brain function.
+Every Positronic project includes a `src/brain.ts` file. This file exports a custom `brain` function that wraps the core Positronic brain function.
 
 ### Why Use a Project Brain?
 
 The project brain pattern provides a single place to:
-- Configure services that all brains can access
+- Configure plugins that all brains can access
 - Set up logging, monitoring, or analytics
 - Add authentication or API clients
 - Establish project-wide conventions
@@ -33,54 +38,61 @@ The project brain pattern provides a single place to:
 All brains in your project should import from `../brain.js` instead of `@positronic/core`:
 
 ```typescript
-// ✅ DO THIS (from a file in the brains/ directory)
+// ✅ DO THIS (from a file in src/brains/)
 import { brain } from '../brain.js';
 
 // ❌ NOT THIS
 import { brain } from '@positronic/core';
 ```
 
-### Configuring Services
+### Configuring Plugins
 
-To add project-wide services, modify the `brain.ts` file in the root directory using `createBrain()`:
+To add project-wide plugins, modify the `src/brain.ts` file using `createBrain()`. Plugins are defined with `definePlugin` and passed to `createBrain({ plugins: [...] })`:
 
 ```typescript
-import { createBrain } from '@positronic/core';
+// src/plugins/logger.ts
+import { definePlugin } from '@positronic/core';
+
+export const logger = definePlugin({
+  name: 'logger',
+  create: () => ({
+    info: (msg: string) => console.log(`[<%= '${new Date().toISOString()}' %>] INFO: <%= '${msg}' %>`),
+    error: (msg: string) => console.error(`[<%= '${new Date().toISOString()}' %>] ERROR: <%= '${msg}' %>`),
+  }),
+});
+```
 
-// Define your services
-interface ProjectServices {
-  logger: {
-    info: (message: string) => void;
-    error: (message: string) => void;
-  };
-  database: {
-    get: (key: string) => Promise<any>;
-    set: (key: string, value: any) => Promise<void>;
-  };
-}
+```typescript
+// src/plugins/database.ts
+import { definePlugin } from '@positronic/core';
+
+export const database = definePlugin({
+  name: 'database',
+  create: () => ({
+    get: async (key: string) => {
+      // Your database implementation
+      return localStorage.getItem(key);
+    },
+    set: async (key: string, value: any) => {
+      // Your database implementation
+      localStorage.setItem(key, JSON.stringify(value));
+    },
+  }),
+});
+```
+
+```typescript
+// src/brain.ts
+import { createBrain } from '@positronic/core';
+import { logger } from './plugins/logger.js';
+import { database } from './plugins/database.js';
 
-// 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);
-      },
-      set: async (key, value) => {
-        // Your database implementation
-        localStorage.setItem(key, JSON.stringify(value));
-      }
-    }
-  }
+  plugins: [logger, database],
 });
 ```
 
-Now all brains automatically have access to these services:
+Now all brains automatically have access to these plugins:
 
 ```typescript
 import { brain } from '../brain.js';
@@ -120,7 +132,7 @@ See `/docs/brain-testing-guide.md` for detailed testing guidance.
 ## Development Workflow
 
 1. **Start the development server**: `px server -d`
-2. **Create or modify brains**: Always import from `./brain.js`
+2. **Create or modify brains**: Always import from `../brain.js` (from files in `src/brains/`)
 3. **Test locally**: 
    ```bash
    # Basic run
@@ -162,7 +174,7 @@ CLOUDFLARE_API_TOKEN=your-api-token
 
 ## Best Practices
 
-1. **Services**: Configure once in `brain.ts`, use everywhere
+1. **Plugins**: Configure once in `src/brain.ts`, use everywhere
 2. **Resources**: Use for content that non-developers should be able to edit
 3. **Secrets**: Never commit API keys; use environment variables
 4. **Organization**: Group related brains in folders as your project grows
@@ -174,14 +186,25 @@ CLOUDFLARE_API_TOKEN=your-api-token
 ### Logging and Monitoring
 
 ```typescript
-// In brain.ts
-interface ProjectServices {
-  metrics: {
-    track: (event: string, properties?: any) => void;
-    time: (label: string) => () => void;
-  };
-}
+// src/plugins/metrics.ts
+import { definePlugin } from '@positronic/core';
+
+export const metrics = definePlugin({
+  name: 'metrics',
+  create: () => ({
+    track: (event: string, properties?: any) => {
+      // Your analytics implementation
+      console.log('track', event, properties);
+    },
+    time: (label: string) => {
+      const start = Date.now();
+      return () => console.log(label, Date.now() - start, 'ms');
+    },
+  }),
+});
+```
 
+```typescript
 // In your brain
 export default brain('Analytics Brain')
   .step('Start Timer', ({ metrics }) => {
@@ -202,34 +225,32 @@ export default brain('Analytics Brain')
 ### API Integration
 
 ```typescript
-// In brain.ts
-interface ProjectServices {
-  api: {
-    get: (path: string) => Promise<any>;
-    post: (path: string, data: any) => Promise<any>;
-  };
-}
-
-// Configure with base URL and auth
-const api = {
-  get: async (path: string) => {
-    const response = await fetch(`https://api.example.com<%= '${path}' %>`, {
-      headers: { 'Authorization': `Bearer <%= '${process.env.API_KEY}' %>` }
-    });
-    return response.json();
-  },
-  post: async (path: string, data: any) => {
-    const response = await fetch(`https://api.example.com<%= '${path}' %>`, {
-      method: 'POST',
-      headers: {
-        'Authorization': `Bearer <%= '${process.env.API_KEY}' %>`,
-        'Content-Type': 'application/json'
-      },
-      body: JSON.stringify(data)
-    });
-    return response.json();
-  }
-};
+// src/plugins/api.ts
+import { definePlugin } from '@positronic/core';
+
+export const api = definePlugin({
+  name: 'api',
+  setup: (config: { baseUrl: string; apiKey: string }) => config,
+  create: ({ config }) => ({
+    get: async (path: string) => {
+      const response = await fetch(`<%= '${config!.baseUrl}${path}' %>`, {
+        headers: { 'Authorization': `Bearer <%= '${config!.apiKey}' %>` }
+      });
+      return response.json();
+    },
+    post: async (path: string, data: any) => {
+      const response = await fetch(`<%= '${config!.baseUrl}${path}' %>`, {
+        method: 'POST',
+        headers: {
+          'Authorization': `Bearer <%= '${config!.apiKey}' %>`,
+          'Content-Type': 'application/json'
+        },
+        body: JSON.stringify(data)
+      });
+      return response.json();
+    },
+  }),
+});
 ```
 
 ## currentUser
@@ -247,8 +268,8 @@ The way `currentUser` is provided depends on how the brain is running:
 **Local development with `runner.ts`**: When calling `runner.run()` directly, you must pass `currentUser`:
 
 ```typescript
-import { runner } from './runner.js';
-import myBrain from './brains/my-brain.js';
+import { runner } from './src/runner.js';
+import myBrain from './src/brains/my-brain.js';
 
 await runner.run(myBrain, {
   currentUser: { name: 'local-dev-user' },
@@ -286,6 +307,6 @@ export default brain('greet')
 
 - **Documentation**: https://positronic.dev
 - **CLI Help**: `px --help`
-- **Brain DSL Guide**: `/docs/brain-dsl-guide.md` (includes UI steps for generating forms)
+- **Brain DSL Guide**: `/docs/brain-dsl-guide.md` (includes page steps for generating forms)
 - **Memory Guide**: `/docs/memory-guide.md`
 - **Testing Guide**: `/docs/brain-testing-guide.md`

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

@@ -31,11 +31,11 @@ This also applies to variable declarations and function parameters:
 ```typescript
 // ❌ DON'T DO THIS
 const names: string[] = options.notify.split(',');
-template: (state: any) => { ... }
+message: ({ state }: any) => { ... }
 
 // ✅ DO THIS
 const names = options.notify.split(',');
-template: (state) => { ... }
+message: ({ state }) => { ... }
 ```
 
 If you genuinely need a cast to fix a type error, prefer the narrowest cast possible and add it only after seeing the error.
@@ -199,10 +199,10 @@ The same applies to prompt templates:
 
 ```typescript
 // ❌ DON'T DO THIS
-template: (state) => `Hello <%= '${state.user.name}' %>, your order <%= '${state.order.id}' %> is ready.`,
+message: ({ state }) => `Hello <%= '${state.user.name}' %>, your order <%= '${state.order.id}' %> is ready.`,
 
 // ✅ DO THIS
-template: ({ user, order }) => `Hello <%= '${user.name}' %>, your order <%= '${order.id}' %> is ready.`,
+message: ({ state: { user, order } }) => `Hello <%= '${user.name}' %>, your order <%= '${order.id}' %> is ready.`,
 ```
 
 When you still need `state` (e.g. for `...state` in the return value), destructure in the function body instead:
@@ -224,6 +224,27 @@ When you still need `state` (e.g. for `...state` in the return value), destructu
   })
 ```
 
+## JSX for Prompt Templates
+
+For complex, multi-line prompts, use JSX instead of template literals. Rename the file to `.tsx` and return JSX from the template function:
+
+```tsx
+// Before (template literal — hard to read when indented in builder chain)
+message: ({ state: { user, order } }) =>
+  `Hello <%= '${user.name}' %>, your order <%= '${order.id}' %> is ready.
+<%= '${order.isExpress ? "\\nThis is an express order." : ""}' %>`,
+
+// After (JSX — Prettier manages indentation, conditionals are clean)
+message: ({ state: { user, order } }) => (
+  <>
+    Hello {user.name}, your order {order.id} is ready.
+    {order.isExpress && <>This is an express order.</>}
+  </>
+)
+```
+
+See `/docs/brain-dsl-guide.md` for full JSX template documentation including loops, reusable components, and async components for resource loading.
+
 ## State Shape
 
 ### Each step should have one clear purpose, and add one thing to state
@@ -296,7 +317,53 @@ Use `.values` for simple extraction, `.filter()` for correlated filtering, and `
   }))
 ```
 
-**Name the `outputKey` after the content.** If results contain analyses, use `outputKey: 'analyses' as const`, not `outputKey: 'processedItems' as const`.
+**Name the `stateKey` after the content.** The stateKey is now the 2nd argument to `.map()`. If results contain analyses, use `.map('title', 'analyses', { ... })`, not `.map('title', 'processedItems', { ... })`.
+
+### Naming convention for filter/map parameters
+
+`IterateResult.filter()` and `.map()` take two parameters: the input item and the AI result. **Name them after what they represent**, not generic names like `item` and `r`:
+
+```typescript
+// ❌ DON'T DO THIS - generic parameter names
+state.validations.filter((item, r) => r.matches)
+state.transcripts.filter((t) => t.hasTranscript)  // WRONG: single param is the item, not the result
+
+// ✅ DO THIS - descriptive names that reflect the data
+state.validations.filter((crawledResult, validation) => validation.matches)
+state.transcripts.filter((match, extraction) => extraction.hasTranscript)
+```
+
+The first parameter is always the input item (what you passed to `over`), and the second is the AI's output (what the `outputSchema` describes). A single-parameter callback only receives the item — if you need the AI result, you must use both parameters.
+
+### Nested brain state spreading
+
+When a `.brain()` step runs an inner brain, the inner brain's final state is spread directly onto the outer state:
+
+```typescript
+.brain('Search and validate', searchAndValidate)
+```
+
+All properties from the inner brain's final state are merged onto the outer state. Subsequent steps can access those properties directly (e.g., `state.matches`). The inner brain's state type is fully inferred from its definition, so you get full type safety.
+
+If you want namespacing (to avoid collisions with existing state properties), design the inner brain to return a namespaced state shape:
+
+```typescript
+// Inner brain returns its results under a single key
+const searchAndValidate = brain('search-and-validate')
+  .step('Search', ({ state }) => ({ ...state, matches: [] }))
+  .step('Package', ({ state }) => ({
+    searchResults: { matches: state.matches }
+  }));
+
+// Outer brain accesses via state.searchResults.matches
+brain('parent')
+  .step('Init', () => ({ query: 'test' }))
+  .brain('Search and validate', searchAndValidate)
+  .step('Use results', ({ state }) => ({
+    ...state,
+    count: state.searchResults.matches.length,
+  }));
+```
 
 ## Brain DSL Type Inference
 
@@ -328,6 +395,30 @@ brain('example')
 
 The type inference flows through the entire chain, making the code cleaner and more maintainable.
 
+### Brains that receive initial state from outside
+
+If a brain receives its initial state from the outside — via `.map()`, `.brain()`, or `run({ initialState })` — declare the state type in the generic parameters:
+
+```typescript
+// This brain is used inside .map() — it receives thread data as initial state
+const categorizeBrain = brain<{}, RawThread>('categorize-thread')
+  .prompt('Categorize', {
+    message: ({ state }) => `Categorize: <%= '${state.subject}' %>`,
+    outputSchema: z.object({ category: z.string() }),
+  });
+
+// The parent brain maps over threads
+brain('email-digest')
+  .step('Fetch', async () => ({ threads: await fetchThreads() }))
+  .map('Categorize', 'categorized', {
+    run: categorizeBrain,
+    over: ({ state }) => state.threads,
+    initialState: (thread) => thread,
+  });
+```
+
+Without the generic, `TState` defaults to `object` and steps can't see any properties. The generic tells TypeScript "this brain starts with this shape." If the brain builds its own state from nothing (first step returns the initial shape), skip the generic — inference handles it.
+
 ## Error Handling in Brains
 
 **Important**: Do NOT catch errors in brain steps unless error handling is specifically part of the brain's workflow logic. The brain runner handles all errors automatically.
@@ -375,13 +466,9 @@ brain('validation-example')
 
 Most generated brains should not have try-catch blocks. Only use them when the error state is meaningful to subsequent steps in the workflow.
 
-## UI Steps for Form Generation
+## Page Steps for Form Generation
 
-When you need to collect user input, use the `.ui()` method. The pattern is:
-1. `.ui()` generates the page
-2. Next step gets `page.url` and `page.webhook`
-3. Notify users, then use `.wait()` with `page.webhook`
-4. Step after `.wait()` gets form data in `response`
+When you need to collect user input, use the `.page()` method with `formSchema`. The brain auto-suspends after generating the page, then auto-merges the form response directly onto state. Use the `onCreated` callback for side effects.
 
 ```typescript
 import { z } from 'zod';
@@ -391,74 +478,98 @@ brain('feedback-collector')
     ...state,
     userName: 'John',
   }))
-  // Generate the form
-  .ui('Collect Feedback', {
-    template: (state) => <%= '\`' %>
+  // Generate the form, onCreated, auto-suspend, auto-merge response
+  .page('Collect Feedback', ({ state, slack }) => ({
+    prompt: <%= '\`' %>
       Create a feedback form for <%= '${state.userName}' %>:
       - Rating (1-5)
       - Comments textarea
       - Submit button
     <%= '\`' %>,
-    responseSchema: z.object({
+    formSchema: z.object({
       rating: z.number().min(1).max(5),
       comments: z.string(),
     }),
-  })
-  // Notify users
-  .step('Notify', async ({ state, page, slack }) => {
-    await slack.post('#feedback', `Fill out: <%= '${page.url}' %>`);
-    return state;
-  })
-  // Wait for form submission
-  .wait('Wait for submission', ({ page }) => page.webhook)
-  // Form data comes through response (not page)
-  .step('Process', ({ state, response }) => ({
+    onCreated: async (page) => {
+      await slack.post('#feedback', `Fill out: <%= '${page.url}' %>`);
+    },
+  }))
+  // No .handle() needed — form data auto-merges directly onto state
+  .step('Process', ({ state }) => ({
     ...state,
-    rating: response.rating,     // Typed from responseSchema
-    comments: response.comments,
+    // state.rating and state.comments are typed
+    processed: true,
   }));
 ```
 
 Key points:
+- `page` is available inside the `onCreated` callback, not in a separate step
 - `page.url` - where to send users
-- `page.webhook` - use with `.wait()` to pause for submission
-- `response` - form data arrives here (in step after `.wait()`)
-- You control how users are notified (Slack, email, etc.)
+- The brain auto-suspends after `.page()` with `formSchema`
+- Form data is spread directly onto state (e.g., `state.rating`, `state.comments`)
+- You control how users are notified (Slack, email, etc.) inside `onCreated`
+
+See `/docs/brain-dsl-guide.md` for more page step examples.
 
-See `/docs/brain-dsl-guide.md` for more UI step examples.
+### Use `.page()` for Data Display, Not `generatePage` in Loops
 
-## Service Organization
+When a brain needs to display data and collect user input, prefer `.page()` steps over calling the `generatePage` tool inside a `.prompt()` loop. The `.page()` step passes data via `props` — the page generation LLM never sees the actual data, only its shape. This is more reliable and keeps data out of the LLM context.
 
-When implementing services for the project brain, consider creating a `services/` directory at the root of your project to keep service implementations organized and reusable:
+```typescript
+// ❌ DON'T DO THIS - LLM fetches data then passes it to generatePage
+brain('reader')
+  .prompt('Show Articles', () => ({
+    message: 'Fetch articles and create a page showing them',
+    outputSchema: z.object({ articlesShown: z.number() }),
+    loop: { tools: { fetchArticles, generatePage, waitForWebhook } },
+  }))
 
+// ✅ DO THIS - fetch data in a step, display with .page()
+brain('reader')
+  .step('Fetch Articles', async () => {
+    const articles = await fetchArticles();
+    return { articles };
+  })
+  .page('Show Articles', ({ state }) => ({
+    prompt: 'Create a reading list with checkboxes to mark articles as read',
+    props: { articles: state.articles },
+    formSchema: z.object({
+      readArticleIds: z.array(z.string()),
+    }),
+  }))
 ```
-services/
-├── gmail.js         # Gmail API integration
-├── slack.js         # Slack notifications
-├── database.js      # Database client
-└── analytics.js     # Analytics tracking
+
+The `.page()` step automatically suspends, waits for the form submission, and merges the response onto state. Use `.prompt()` loops for tasks that genuinely need LLM decision-making with tools (research, multi-step reasoning, human-in-the-loop via webhooks), not for data display.
+
+## Plugin Organization
+
+When implementing plugins for the project brain, keep plugin implementations in the `src/plugins/` directory to stay organized and reusable:
+
+```
+src/plugins/
+├── gmail.ts         # Gmail API integration
+├── slack.ts         # Slack notifications
+├── database.ts      # Database client
+└── analytics.ts     # Analytics tracking
 ```
 
-Then in your `brain.ts` (at the project root):
+Then in your `src/brain.ts`:
 
 ```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';
+import { gmail } from './plugins/gmail.js';
+import { slack } from './plugins/slack.js';
+import { database } from './plugins/database.js';
+import { analytics } from './plugins/analytics.js';
 
 export const brain = createBrain({
-  services: {
-    gmail,
-    slack,
-    database,
-    analytics
-  }
+  plugins: [gmail, slack, database, analytics],
 });
 ```
 
-This keeps your service implementations separate from your brain logic and makes them easier to test and maintain.
+Each plugin is defined with `definePlugin` from `@positronic/core`. See `/docs/plugin-guide.md` for how to create plugins with typed config, tools, and adapters.
+
+This keeps your plugin implementations separate from your brain logic and makes them easier to test and maintain.
 
 ## Rate Limiting with bottleneck
 
@@ -495,7 +606,7 @@ const slow = bottleneck({ rpd: 1000 }); // 1000 per day
 Create one limiter per API and wrap all calls through it:
 
 ```typescript
-// services/github.ts
+// src/services/github.ts
 import { bottleneck } from '../utils/bottleneck.js';
 
 const limit = bottleneck({ rps: 10 });
@@ -555,7 +666,7 @@ const alertSchema = z.object({
 });
 
 const alertBrain = brain('Alert System')
-  .withOptionsSchema(alertSchema)
+  .withOptions(alertSchema)
   .step('Check Threshold', ({ state, options }) => ({
     ...state,
     shouldAlert: state.errorCount > parseInt(options.alertThreshold)
@@ -585,9 +696,9 @@ This project uses ES modules (ESM). **Always include the `.js` extension in your
 
 ```typescript
 // ✅ CORRECT - Include .js extension
-import { brain } from '../brain.js';  // From a file in brains/ directory
-import { analyzeData } from '../utils/analyzer.js';
-import gmail from '../services/gmail.js';
+import { brain } from '../brain.js';  // From a file in src/brains/ (brain.ts is at src/brain.ts)
+import { analyzeData } from '../utils/analyzer.js';  // From src/brains/ to src/utils/
+import gmail from '../services/gmail.js';  // From src/brains/ to src/services/
 
 // ❌ WRONG - Missing .js extension
 import { brain } from '../brain';
@@ -615,7 +726,7 @@ Start by following the brain testing guide (`/docs/brain-testing-guide.md`) and
 // tests/my-new-brain.test.ts
 import { describe, it, expect } from '@jest/globals';
 import { createMockClient, runBrainTest } from './test-utils.js';
-import myNewBrain from '../brains/my-new-brain.js';
+import myNewBrain from '../src/brains/my-new-brain.js';
 
 describe('MyNewBrain', () => {
   it('should process data and return expected result', async () => {
@@ -678,7 +789,7 @@ Build the brain one step at a time, testing as you go. **Actually run the brain
 
 ```bash
 # 1. Create the brain with just the first step
-# Write minimal implementation in brains/my-new-brain.ts
+# Write minimal implementation in src/brains/my-new-brain.ts
 
 # 2. Run the brain to test the first step
 px brain run my-new-brain
@@ -739,34 +850,23 @@ export default feedbackBrain;
 // Step 3: Run and check logs, see it doesn't analyze yet
 // Step 4: Add sentiment analysis step
   .prompt('Analyze sentiment', {
-    template: ({ feedback }) =>
+    message: ({ state: { feedback } }) =>
       <%= '\`Analyze the sentiment of this feedback: "${feedback}"\`' %>,
-    outputSchema: {
-      schema: z.object({
-        sentiment: z.enum(['positive', 'neutral', 'negative']),
-        score: z.number().min(0).max(1)
-      }),
-      name: 'sentimentAnalysis' as const
-    }
+    outputSchema: z.object({
+      sentiment: z.enum(['positive', 'neutral', 'negative']),
+      score: z.number().min(0).max(1)
+    }),
   })
 
 // Step 5: Run again, check logs, test still fails (no response)
 // Step 6: Add response generation
   .prompt('Generate response', {
-    template: ({ sentimentAnalysis, feedback }) =>
-      <%= '\`Generate a brief response to this ${sentimentAnalysis.sentiment} feedback: "${feedback}"\`' %>,
-    outputSchema: {
-      schema: z.object({
-        response: z.string()
-      }),
-      name: 'responseData' as const
-    }
-  })
-  .step('Format output', ({ state }) => ({
-    ...state,
-    sentiment: state.sentimentAnalysis.sentiment,
-    response: state.responseData.response
-  }));
+    message: ({ state: { sentiment, feedback } }) =>
+      <%= '\`Generate a brief response to this ${sentiment} feedback: "${feedback}"\`' %>,
+    outputSchema: z.object({
+      response: z.string()
+    }),
+  });
 
 // Step 7: Run test - it should pass now!
 ```