@positronic/template-new-project 0.0.76 → 0.0.77

package/index.js

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

package/package.json

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

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

@@ -81,7 +81,7 @@ brain('AI Education Assistant')
     context: 'We are creating an educational example',
   }))
   .prompt('Generate explanation', {
-    template: ({ topic, context }) =>
+    template: ({ state: { topic, context } }) =>
       `<%= '${context}' %>. Please provide a brief, beginner-friendly explanation of <%= '${topic}' %>.`,
     outputSchema: {
       schema: z.object({
@@ -104,7 +104,7 @@ brain('AI Education Assistant')
   .prompt(
     'Generate follow-up questions',
     {
-      template: ({ formattedOutput }) =>
+      template: ({ state: { formattedOutput } }) =>
         `Based on this explanation about <%= '${formattedOutput.topic}' %>: "<%= '${formattedOutput.explanation}' %>"
         
         Generate 3 thoughtful follow-up questions that a student might ask.`,
@@ -147,7 +147,7 @@ const smartModel = createAnthropicClient({ model: 'claude-sonnet-4-5-20250929' }
 
 brain('Multi-Model Brain')
   .prompt('Quick summary', {
-    template: ({ document }) => `Summarize this briefly: <%= '${document}' %>`,
+    template: ({ state: { document } }) => `Summarize this briefly: <%= '${document}' %>`,
     outputSchema: {
       schema: z.object({ summary: z.string() }),
       name: 'quickSummary' as const,
@@ -155,7 +155,7 @@ brain('Multi-Model Brain')
     client: fastModel,  // Use a fast, cheap model for summarization
   })
   .prompt('Deep analysis', {
-    template: ({ quickSummary }) =>
+    template: ({ state: { quickSummary } }) =>
       `Analyze the implications of this summary: <%= '${quickSummary.summary}' %>`,
     outputSchema: {
       schema: z.object({
@@ -419,7 +419,7 @@ Services are destructured alongside other parameters in:
 2. **Prompt Reduce Functions**:
 ```typescript
 .prompt('Generate', {
-  template: (state) => 'Generate something',
+  template: ({ state }) => 'Generate something',
   outputSchema: { schema, name: 'result' as const }
 }, async ({ state, response, logger, database }) => {
   logger.info('Saving AI response');
@@ -477,7 +477,7 @@ const analysisBrain = brain('Data Analysis')
     return { ...state, data };
   })
   .prompt('Analyze Data', {
-    template: ({ data }) => `Analyze this data: <%= '${JSON.stringify(data)}' %>`,
+    template: ({ state: { data } }) => `Analyze this data: <%= '${JSON.stringify(data)}' %>`,
     outputSchema: {
       schema: z.object({
         insights: z.array(z.string()),
@@ -630,7 +630,7 @@ const brainWithComponents = brain('Custom UI Brain')
     }
   })
   .ui('Dashboard', {
-    template: (state) => `
+    template: ({ state }) => `
       Create a dashboard using CustomCard components to display:
       - User name: <%= '${state.userName}' %>
       - Account status: <%= '${state.status}' %>
@@ -931,7 +931,7 @@ Resources are also available in prompt templates:
 
 ```typescript
 brain('Template Example').prompt('Generate Content', {
-  template: async (state, resources) => {
+  template: async ({ state, resources }) => {
     const template = await resources.prompts.customerSupport.load();
     return template.replace('{{issue}}', state.issue);
   },
@@ -1025,7 +1025,7 @@ interface FilterPromptState {
 
 // Export the prompt configuration
 export const aiFilterPrompt = {
-  template: async (state: FilterPromptState, resources: Resources) => {
+  template: async ({ state, resources }: { state: FilterPromptState, resources: Resources }) => {
     // Load a prompt template from resources
     const template = await resources.prompts.hnFilter.load();
 
@@ -1093,7 +1093,7 @@ brain('Item Processor')
     ]
   }))
   .prompt('Summarize Items', {
-    template: (item) => `Summarize this item: <%= '${item.title}' %>`,
+    template: ({ item }) => `Summarize this item: <%= '${item.title}' %>`,
     outputSchema: {
       schema: z.object({ summary: z.string() }),
       name: 'summaries' as const
@@ -1202,7 +1202,7 @@ brain('Dynamic Processor')
     ]
   }))
   .prompt('Process', {
-    template: (item) => `Process item <%= '${item.id}' %>`,
+    template: ({ item }) => `Process item <%= '${item.id}' %>`,
     outputSchema: {
       schema: z.object({ result: z.string() }),
       name: 'results' as const,
@@ -1534,7 +1534,7 @@ brain('Feedback Collector')
   }))
   // Generate the form
   .ui('Collect Feedback', {
-    template: (state) => `
+    template: ({ state }) => `
       Create a feedback form for <%= '${state.userName}' %>.
       Include fields for rating (1-5) and comments.
     `,
@@ -1580,7 +1580,7 @@ Be specific about layout and content:
 
 ```typescript
 .ui('Contact Form', {
-  template: (state) => `
+  template: ({ state }) => `
     Create a contact form with:
     - Header: "Get in Touch"
     - Name field (required)
@@ -1604,7 +1604,7 @@ Use `{{path}}` syntax to bind props to runtime data:
 
 ```typescript
 .ui('Order Summary', {
-  template: (state) => `
+  template: ({ state }) => `
     Create an order summary showing:
     - List of items from {{cart.items}}
     - Total: {{cart.total}}
@@ -1651,7 +1651,7 @@ brain('User Onboarding')
 
   // Step 2: Preferences
   .ui('Preferences', {
-    template: (state) => `
+    template: ({ state }) => `
       Create preferences form for <%= '${state.userData.firstName}' %>:
       - Newsletter subscription checkbox
       - Contact preference (email/phone/sms)
@@ -1708,7 +1708,7 @@ const completeBrain = brain({
     return { startTime: Date.now() };
   })
   .prompt('Generate Plan', {
-    template: async (state, resources) => {
+    template: async ({ state, resources }) => {
       // Load a template from resources
       const template = await resources.templates.projectPlan.load();
       return template.replace('{{context}}', 'software project');

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) => { ... }
+template: ({ state }: any) => { ... }
 
 // ✅ DO THIS
 const names = options.notify.split(',');
-template: (state) => { ... }
+template: ({ 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.`,
+template: ({ 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.`,
+template: ({ 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:
@@ -298,6 +298,44 @@ 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`.
 
+### 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 mapping
+
+When a `.brain()` step runs an inner brain and maps its state into the outer brain, **destructure to select the fields you need** instead of casting:
+
+```typescript
+// ❌ DON'T DO THIS - casting to force the type
+.brain(
+    'Search and validate',
+    searchAndValidate,
+    ({ brainState }) => brainState as { matches: Match[] },
+  )
+
+// ✅ DO THIS - destructure to select and let inference work
+.brain(
+    'Search and validate',
+    searchAndValidate,
+    ({ brainState: { matches } }) => ({ matches }),
+  )
+```
+
+The inner brain's state type is fully inferred from its definition. Destructuring picks the fields you want and TypeScript infers the outer state correctly — no casts needed. If the inner brain exports an interface for its output shape, import it for use in downstream steps (like prompt templates).
+
 ## Brain DSL Type Inference
 
 The Brain DSL has very strong type inference capabilities. **Important**: You should NOT explicitly specify types on the state object as it flows through steps. The types are automatically inferred from the previous step.
@@ -393,7 +431,7 @@ brain('feedback-collector')
   }))
   // Generate the form
   .ui('Collect Feedback', {
-    template: (state) => <%= '\`' %>
+    template: ({ state }) => <%= '\`' %>
       Create a feedback form for <%= '${state.userName}' %>:
       - Rating (1-5)
       - Comments textarea
@@ -739,7 +777,7 @@ 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 }) =>
+    template: ({ state: { feedback } }) =>
       <%= '\`Analyze the sentiment of this feedback: "${feedback}"\`' %>,
     outputSchema: {
       schema: z.object({
@@ -753,7 +791,7 @@ export default feedbackBrain;
 // Step 5: Run again, check logs, test still fails (no response)
 // Step 6: Add response generation
   .prompt('Generate response', {
-    template: ({ sentimentAnalysis, feedback }) =>
+    template: ({ state: { sentimentAnalysis, feedback } }) =>
       <%= '\`Generate a brief response to this ${sentimentAnalysis.sentiment} feedback: "${feedback}"\`' %>,
     outputSchema: {
       schema: z.object({