@positronic/template-new-project 0.0.2

package/.claude/settings.local.json

@@ -0,0 +1,8 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test)"
+    ],
+    "deny": []
+  }
+}

package/CLAUDE.md

@@ -0,0 +1,215 @@
+# Maintainer's Guide to the Positronic Project Template & Caz
+
+This document serves as the complete guide for maintainers of the `@positronic/template-new-project`. It provides a deep dive into the structure of this template, its configuration, and the underlying scaffolding engine, `caz`, that powers it.
+
+This guide assumes no prior knowledge of the `caz` codebase.
+
+## Part 1: The `@positronic/template-new-project`
+
+This project is a `caz` template. Its sole purpose is to generate new Positronic projects by running a command like `npx @positronic/template-new-project <new-project-name>`.
+
+### The Anatomy of the Template
+
+The template is controlled by its `index.js` file, which defines how `caz` should behave. The actual files to be generated live inside the `template/` directory.
+
+#### Key Files
+
+*   **`index.js`**: The brain of the template. This is a configuration file that tells `caz` what questions to ask, what logic to run before generating files, and how to prepare the files.
+*   **`package.json`**: This defines the template itself, including its dependencies like `caz`. Note that the dependencies here are for the *template*, not the *generated project*.
+*   **`template/`**: This directory contains the skeleton of the project that will be created. Files and filenames here can contain template variables.
+
+#### The Generation Process at a Glance
+
+When a user runs this template, `caz` performs the following high-level steps:
+
+1.  **Prompts**: Asks the user a series of questions defined in `index.js`.
+2.  **Setup**: Runs custom logic to process the user's answers and prepare dynamic variables.
+3.  **Prepare**: Prepares the list of files to be generated, renaming special files like `_gitignore`.
+4.  **Render & Emit**: Copies files from the `template/` directory, injecting variables and processing logic.
+5.  **Install & Initialize**: (Optionally) installs dependencies and initializes a Git repository in the new project.
+
+### In-Depth Configuration (`index.js`)
+
+The `index.js` file exports a configuration object that `caz` uses to drive the entire process. Let's break down its key sections.
+
+#### **1. Prompts (`prompts` array)**
+
+This array defines the interactive questions `caz` will ask the user.
+
+*   **`name`**: The name of the new project. Defaults to `my-positronic-project`.
+*   **`backend`**: A selection list for the deployment backend. This is critical as it drives which dependencies and configurations are included. Currently, only 'Cloudflare' is enabled.
+*   **`install`**: A confirmation to ask whether dependencies should be installed automatically.
+*   **`pm`**: A selection list for the package manager (npm, pnpm, yarn), which only appears if the user opts to install dependencies.
+
+#### **2. Pre-Generation Logic (`setup` hook)**
+
+This asynchronous function runs after the user has answered the prompts but before any files are generated. It's used for complex, dynamic configuration.
+
+*   **Local Development with `POSITRONIC_LOCAL_PATH`**: This is a crucial feature for maintainers. If the `POSITRONIC_LOCAL_PATH` environment variable is set (pointing to the root of a local monorepo), the template will map the `@positronic/*` dependencies to local `file:` paths instead of fetching them from `npm`. This allows for simultaneous development and testing of the core libraries and the template.
+*   **Backend Package Mapping**: It maps the user's `backend` choice (e.g., 'cloudflare') to a specific npm package name (e.g., `@positronic/cloudflare`).
+*   **Dynamic Versioning**: It sets the versions for `@positronic/core`, `@positronic/cloudflare`, and `@positronic/client-vercel` to either `'latest'` or a local `file:` path.
+*   **Installation Control**: It sets `ctx.config.install` to the chosen package manager or `false`, telling `caz` whether to run an installation step later.
+*   **Context Augmentation**: It adds new properties to `ctx.answers` (like `projectName`, `positronicCoreVersion`, etc.) which can then be used as variables in the template files.
+
+#### **3. File Preparation (`prepare` hook)**
+
+This function runs after `caz` has gathered all the template files but before they are rendered and written to disk. It allows for final manipulation of the file list.
+
+*   **Renaming System Files**: It renames `_gitignore` to `.gitignore` and `_env` to `.env`. This is a common pattern to prevent the template's own `.gitignore` or `.env` from affecting the template repository itself.
+*   **Marking Files as Binary**: It iterates through the files and marks any markdown files in the `docs/` directory as binary. This tells `caz`'s rendering engine to skip them, preventing it from trying to inject template variables into the documentation.
+
+### The Template Files (`template/` directory)
+
+Files within this directory are the blueprint for the generated project. They utilize Lodash template syntax.
+
+*   **Variable Injection**: Simple variables are injected using `<%=...%>`.
+    *   Example from `template/positronic.config.json`: `"projectName": "<%= name %>"`
+*   **Conditional Logic**: JavaScript logic can be embedded with `<%...%>`. This is used powerfully in `template/package.json` to conditionally include dependencies based on the backend choice.
+    ```json
+    "dependencies": {
+      ...
+      "@positronic/core": "<%= positronicCoreVersion %>"<% if (backend === 'cloudflare') { %>,
+      "@positronic/cloudflare": "<%= positronicCloudflareVersion %>"<% } %>
+    }
+    ```
+*   **File Renaming**: `caz` also supports renaming files that contain `{variable}` syntax in their names, though this template does not currently use that feature.
+
+***
+
+## Part 2: `caz` - The Scaffolding Engine
+
+`caz` is the engine that interprets and executes our template. Understanding its workflow is key to understanding why the template is built the way it is.
+
+### The Core `caz` Workflow (Middleware Chain)
+
+`caz` processes a project in a strict, sequential order of middleware.
+
+1.  **`confirm`**: Checks if the target project directory exists. If it's not empty, it prompts the user to either merge, overwrite, or cancel. The `--force` flag bypasses this.
+2.  **`resolve`**: Locates the template. It can be a local path (`./my-template`) or a remote repository (`zce/nm`). Remote templates are downloaded and cached in `~/.cache/caz` for offline use and speed.
+3.  **`load`**: Loads the template's configuration (`index.js`). **Crucially, it also runs `npm install --production` inside the template's directory**, installing any `dependencies` listed in the template's `package.json`.
+4.  **`inquire`**: Presents the interactive prompts from the `prompts` array to the user. `caz` automatically provides smart defaults and validation for common fields like `name`, `version`, `author`, `email`, and `url` by reading system `.npmrc` and `.gitconfig` files.
+5.  **`setup`**: Executes the `setup` hook from the template config, as described above.
+6.  **`prepare`**: Reads all files from the `source` directory (`template/` by default). It applies any `filters` defined in the config to conditionally exclude files. After this, it runs the `prepare` hook.
+7.  **`rename`**: Scans filenames for `{variable}` patterns and renames them based on user answers.
+8.  **`render`**: Scans the content of all non-binary files for template syntax (`<%=...%>` or `${...}`) and renders them using the user's answers and any configured `helpers`.
+9.  **`emit`**: Writes the final, rendered files to the destination project directory. It runs an `emit` hook if one is defined.
+10. **`install`**: If `config.install` is set to `'npm'`, `'yarn'`, or `'pnpm'`, it runs the corresponding installation command in the new project directory.
+11. **`init`**: If `config.init` is `true` (or if a `.gitignore` file is present), it runs `git init`, `git add`, and `git commit`.
+12. **`complete`**: Executes the `complete` hook, which is typically used to print a "getting started" message to the user. If not defined, it prints a default message listing the created files.
+
+***
+
+## Part 3: Practical Maintainer Tasks
+
+With this knowledge, here is how to approach common maintenance tasks.
+
+### How to Add a New Backend (e.g., "Fly.io")
+
+1.  **Modify Prompts (`index.js`)**: Add a new choice to the `backend` prompt. You can disable it initially if it's a work in progress.
+    ```javascript
+    {
+      name: 'backend',
+      type: 'select',
+      message: 'Select your deployment backend',
+      choices: [
+        { title: 'Cloudflare', value: 'cloudflare' },
+        // ...
+        { title: 'Fly.io', value: 'fly', disabled: false }, // Add new choice
+        { title: 'None (Core only)', value: 'none' }
+      ]
+    }
+    ```
+2.  **Update Setup Logic (`index.js`)**:
+    *   Add the new backend to `backendPackageMap`.
+    *   Add logic to handle the `file:` path for the new backend when `POSITRONIC_LOCAL_PATH` is set.
+    *   Add the new dependency version to `ctx.answers`.
+3.  **Update Template Files (`template/package.json`)**: Add a conditional block to include the new dependency.
+    ```json
+    "dependencies": {
+        ...
+        <% if (backend === 'fly') { %>
+        "@positronic/fly": "<%= positronicFlyVersion %>"
+        <% } %>
+    }
+    ```
+4.  **Add New Files**: If the new backend requires specific files (e.g., `fly.toml`), add them to the `template/` directory. You can use `filters` in `index.js` to ensure they are only included when that backend is selected.
+
+### How to Test Changes Locally
+
+This is the most important workflow for a maintainer.
+
+1.  Make your changes to the `template-new-project` repository.
+2.  In your terminal, navigate to a directory *outside* of the project.
+3.  To simulate a normal user's experience, run:
+    ```bash
+    # Use 'npx caz' to run caz without a global install
+    # Point it to the local directory of your template
+    # 'my-test-app' is the output directory
+    npx caz ./path/to/template-new-project my-test-app --force
+    ```
+4.  To test with local monorepo packages, set the environment variable first:
+    ```bash
+    # Point to the root of your positronic monorepo
+    export POSITRONIC_LOCAL_PATH=~/dev/positronic
+
+    npx caz ./path/to/template-new-project my-local-test-app --force
+    ```
+5.  Inspect the generated `my-test-app` or `my-local-test-app` directory to ensure the files and `package.json` are correct. The `--force` flag is useful for quickly re-running the command.
+
+### Gotcha: Accidental Template Processing
+
+The `caz` rendering engine is greedy. It scans every non-binary file for its template syntax. If it finds a match, it will attempt to process the *entire file*, which can cause unexpected behavior or break the scaffolding process.
+
+**Important**: Any file containing text that matches the `<%= ... %>` or `${...}` patterns will be treated as a template and processed by the engine, which can cause errors if the content is not a valid template variable or expression.
+
+For example, imagine you add a new shell script to the template called `configure.sh`:
+
+```sh
+#!/bin/bash
+
+# This script configures the local environment
+echo "Setting up for user: ${USER}"
+```
+
+When `caz` processes this file, it will see `${USER}` and interpret it as a template variable. It will search for a `USER` key in the answers provided by the user during the prompts. If it's not found, the output will likely be `Setting up for user: undefined`, or it could even throw an error, breaking the project generation.
+
+### How to Prevent Accidental Processing
+
+The codebase reveals two ways to handle this, depending on your goal.
+
+1.  **Escaping the Syntax (The Preferred Method)**
+
+    If you need the literal syntax (like `${USER}`) to appear in the final generated file, you must escape it using the template engine itself. The `caz` documentation (`docs/create-template.md`) explicitly describes this:
+
+    *   To output a literal `<%= name %>`, you must write `<%= '\<%= name %\>' %>` in your template file.
+    *   To output a literal `${name}`, you must write `<%= '${name}' %>` in your template file.
+
+2.  **Marking the File as Binary**
+
+    If a file should be copied verbatim with no processing whatsoever, the solution is to instruct `caz` to treat it as a binary file. The renderer explicitly skips binary files.
+
+    The `@positronic/template-new-project` template already does this for its documentation files as a preventative measure. You can add a similar rule in the `prepare` hook within `index.js`:
+
+    ```javascript
+    // in index.js
+    prepare: async ctx => {
+      // ... existing prepare logic ...
+
+      // Add a rule to treat all .sh files as binary
+      ctx.files.forEach(file => {
+        if (file.path.endsWith('.sh')) {
+          // This is a made-up property for the example, but it would
+          // need to be supported by caz's `isBinary` check.
+          // A more robust way is to check the file contents.
+          // The key insight is that the prepare hook is where you would
+          // manipulate files before rendering.
+          // The current template shows a real example for .md files:
+          if (file.path.startsWith('docs/') && file.path.endsWith('.md')) {
+            file.binary = true; // This is a conceptual flag.
+                                // The actual implementation is in caz's `isBinary` check.
+          }
+        }
+      });
+    }
+    ```
+    This tells the `render` step to ignore the file completely, ensuring it is copied as-is.

package/index.js

@@ -0,0 +1,180 @@
+const { name, version } = require('./package.json')
+const path = require('path')
+const { existsSync } = require('fs')
+
+module.exports = {
+  name,
+  version,
+  prompts: [
+    {
+      name: 'name',
+      type: 'text',
+      message: 'Project name',
+      initial: 'my-positronic-project'
+    },
+    {
+      name: 'backend',
+      type: 'select',
+      message: 'Select your deployment backend',
+      hint: ' ',
+      choices: [
+        { title: 'Cloudflare', value: 'cloudflare' },
+        { title: 'AWS Lambda', value: 'aws', disabled: true },
+        { title: 'Azure Functions', value: 'azure', disabled: true },
+        { title: 'Google Cloud Functions', value: 'gcp', disabled: true },
+        { title: 'Fly.io', value: 'fly', disabled: true },
+        { title: 'None (Core only)', value: 'none' }
+      ],
+      initial: 0
+    },
+    {
+      name: 'install',
+      type: 'confirm',
+      message: 'Install dependencies',
+      initial: true
+    },
+    {
+      name: 'pm',
+      type: prev => prev ? 'select' : null,
+      message: 'Package manager',
+      hint: ' ',
+      choices: [
+        { title: 'npm', value: 'npm' },
+        { title: 'pnpm', value: 'pnpm' },
+        { title: 'yarn', value: 'yarn' }
+      ]
+    },
+    {
+      name: 'claudemd',
+      type: 'confirm',
+      message: 'Initialize CLAUDE.md for AI-assisted development',
+      initial: true
+    }
+  ],
+  setup: async ctx => {
+    const devRootPath = process.env.POSITRONIC_LOCAL_PATH;
+    let coreVersion = 'latest';
+    let cloudflareVersion = 'latest';
+    let clientVercelVersion = 'latest';
+
+    // Map backend selection to package names
+    const backendPackageMap = {
+      'cloudflare': '@positronic/cloudflare',
+      'aws': '@positronic/aws-lambda', // Future
+      'azure': '@positronic/azure-functions', // Future
+      'gcp': '@positronic/gcp-functions', // Future
+      'fly': '@positronic/fly', // Future
+      'none': null
+    };
+
+    ctx.answers.backendPackage = backendPackageMap[ctx.answers.backend];
+
+    if (devRootPath) {
+      console.log(`Found POSITRONIC_LOCAL_PATH: ${devRootPath}. Using local file path for @positronic/core.`);
+      const corePath = path.resolve(devRootPath, 'packages', 'core');
+      coreVersion = `file:${corePath}`;
+      console.log(`  - Mapping @positronic/core to ${coreVersion}`);
+
+      // Handle backend packages for local development
+      if (ctx.answers.backend === 'cloudflare') {
+        const cloudflarePath = path.resolve(devRootPath, 'packages', 'cloudflare');
+        if (existsSync(cloudflarePath)) {
+          cloudflareVersion = `file:${cloudflarePath}`;
+          // Also update the backend package for the config file
+          ctx.answers.backendPackage = `file:${cloudflarePath}`;
+          console.log(`  - Mapping @positronic/cloudflare to ${cloudflareVersion}`);
+        }
+      }
+      // Add similar blocks for other backends when they exist
+      // Example for future backends:
+      // if (ctx.answers.backend === 'aws') {
+      //   const awsPath = path.resolve(devRootPath, 'packages', 'aws-lambda');
+      //   if (existsSync(awsPath)) {
+      //     ctx.answers.backendPackage = `file:${awsPath}`;
+      //   }
+      // }
+
+      const clientVercelPath = path.resolve(devRootPath, 'packages', 'client-vercel');
+      if (existsSync(clientVercelPath)) {
+        clientVercelVersion = `file:${clientVercelPath}`;
+      }
+    }
+
+    ctx.answers.positronicCoreVersion = coreVersion;
+    if (ctx.answers.backend === 'cloudflare') {
+      ctx.answers.positronicCloudflareVersion = cloudflareVersion;
+    }
+
+    ctx.answers.positronicClientVercelVersion = clientVercelVersion;
+
+    if (ctx.answers.install) {
+      const pm = ctx.answers.pm;
+      if (!pm) {
+        ctx.config.install = 'npm';
+        ctx.answers.pm = 'npm';
+      } else {
+        ctx.config.install = pm;
+      }
+    } else {
+      ctx.config.install = false;
+    }
+
+    // Disable git initialization in test environments
+    if (process.env.NODE_ENV === 'test') {
+      ctx.config.init = false;
+    }
+
+    ctx.answers.projectName = ctx.answers.name;
+  },
+  prepare: async ctx => {
+    // Find our specially named gitignore file in the list of files to be processed
+    const gitignoreFile = ctx.files.find(file => file.path === '_gitignore');
+    if (gitignoreFile) {
+      // Change its path to '.gitignore' so it's correctly named in the generated project
+      gitignoreFile.path = '.gitignore';
+    }
+
+    // Find our specially named env file in the list of files to be processed
+    const envFile = ctx.files.find(file => file.path === '_env');
+    if (envFile) {
+      // Change its path to '.env' so it's correctly named in the generated project
+      envFile.path = '.env';
+    }
+
+    // Remove CLAUDE.md if user chose not to include it
+    if (!ctx.answers.claudemd) {
+      ctx.files = ctx.files.filter(file => file.path !== 'CLAUDE.md');
+    }
+  },
+  complete: async ctx => {
+    // Display getting started message
+    console.log('\n✨ Project created successfully!\n');
+    console.log(`📁 Project location: ${ctx.dest}\n`);
+    
+    console.log('🚀 Getting started:\n');
+    console.log(`   cd ${ctx.answers.name}`);
+    
+    if (!ctx.answers.install) {
+      console.log(`   ${ctx.answers.pm || 'npm'} install`);
+    }
+    
+    console.log('   px server              # Start the development server');
+    console.log('   px brain list          # List available brains');
+    console.log('   px brain run example   # Run the example brain\n');
+    
+    if (ctx.answers.backend === 'cloudflare') {
+      console.log('☁️  Cloudflare deployment:\n');
+      console.log('   wrangler login         # Authenticate with Cloudflare');
+      console.log('   px deploy              # Deploy to Cloudflare Workers\n');
+    }
+    
+    console.log('📚 Resources:\n');
+    console.log('   • Documentation: https://positronic.dev');
+    console.log('   • GitHub: https://github.com/positronic-ai/positronic');
+    console.log('   • CLI Help: px --help\n');
+    
+    if (ctx.answers.claudemd) {
+      console.log('💡 Pro tip: Check out CLAUDE.md in your project for AI-assisted development guidance!\n');
+    }
+  }
+}

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@positronic/template-new-project",
+  "version": "0.0.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Caz template for generating a new Positronic project.",
+  "main": "index.js",
+  "scripts": {
+    "build": "",
+    "clean": "rm -rf node_modules"
+  },
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "caz": "^2.0.0"
+  }
+}

package/template/.positronic/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "<%= projectName %>-server",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "src/index.ts",
+  "scripts": {},
+  "dependencies": {
+    "@positronic/core": "<%= positronicCoreVersion %>", <% if (backend === 'cloudflare') { %>
+    "@positronic/cloudflare": "<%= positronicCloudflareVersion %>", <% } %>
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20240405.0",
+    "typescript": "^5.0.0"
+  }
+}

package/template/.positronic/src/index.ts

@@ -0,0 +1,35 @@
+import {
+  api as app,
+  setManifest,
+  setBrainRunner,
+  BrainRunnerDO,
+  MonitorDO,
+  ScheduleDO,
+  PositronicManifest,
+} from "@positronic/cloudflare";
+// Import the generated manifest - NOTE the .js extension for runtime compatibility
+// @ts-expect-error - _manifest.js is generated during template processing
+import { staticManifest } from "./_manifest.js";
+import { runner } from "./runner.js";
+// Configure the manifest to use the statically generated list
+const manifest = new PositronicManifest({
+  staticManifest,
+});
+
+setManifest(manifest);
+setBrainRunner(runner);
+
+// Define Env type based on wrangler.jsonc bindings
+interface Env {
+  BRAIN_RUNNER_DO: DurableObjectNamespace<BrainRunnerDO>;
+  MONITOR_DO: DurableObjectNamespace<MonitorDO>;
+  SCHEDULE_DO: DurableObjectNamespace<ScheduleDO>;
+  RESOURCES_BUCKET: R2Bucket;
+}
+
+// Export the API handler and Durable Objects
+export default {
+  fetch: app.fetch,
+} satisfies ExportedHandler<Env>;
+
+export { BrainRunnerDO, MonitorDO, ScheduleDO };

package/template/.positronic/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ESNext",
+    "module": "ESNext",
+    "lib": ["ESNext"],
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "strict": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "incremental": true,
+    "types": ["@cloudflare/workers-types"],
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["node_modules", "dist"]
+}

package/template/.positronic/wrangler.jsonc

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://raw.githubusercontent.com/cloudflare/wrangler/main/config-schema.json",
+  "name": "<%= projectName %>",
+  "main": "src/index.ts",
+  "compatibility_date": "2024-09-23",
+  "compatibility_flags": ["nodejs_compat", "nodejs_compat_populate_process_env"],
+  "workers_dev": true,
+  "migrations": [
+    {
+      "tag": "v1",
+      "new_sqlite_classes": ["BrainRunnerDO", "MonitorDO", "ScheduleDO"]
+    }
+  ],
+  "durable_objects": {
+    "bindings": [
+      { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
+      { "name": "MONITOR_DO", "class_name": "MonitorDO" },
+      { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" }
+    ]
+  },
+  "r2_buckets": [
+    {
+      "binding": "RESOURCES_BUCKET",
+      "bucket_name": "<%= projectName %>"
+    }
+  ],
+  "vars": {
+    "R2_BUCKET_NAME": "<%= projectName %>"
+  },
+  "env": {
+    "production": {
+      "name": "<%= projectName %>",
+      "workers_dev": false,
+      "vars": {
+        "NODE_ENV": "production",
+        "R2_BUCKET_NAME": "<%= projectName %>"
+      },
+      "durable_objects": {
+        "bindings": [
+          { "name": "BRAIN_RUNNER_DO", "class_name": "BrainRunnerDO" },
+          { "name": "MONITOR_DO", "class_name": "MonitorDO" },
+          { "name": "SCHEDULE_DO", "class_name": "ScheduleDO" }
+        ]
+      },
+      "r2_buckets": [
+        {
+          "binding": "RESOURCES_BUCKET",
+          "bucket_name": "<%= projectName %>"
+        }
+      ]
+    }
+  }
+}

package/template/CLAUDE.md

@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is a Positronic project - an AI-powered framework for building and running "brains" (stateful AI workflows) that can be deployed to various cloud backends. It provides a fluent DSL for defining AI workflows, resource management, and a CLI for development and deployment.
+
+## Project Structure
+
+- **`/brains`** - AI workflow definitions using the Brain DSL
+- **`/resources`** - Files and documents that brains can access via the resource system
+- **`/tests`** - Test files for brains (kept separate to avoid deployment issues)
+- **`/docs`** - Documentation including brain testing guide
+- **`/runner.ts`** - The main entry point for running brains locally
+- **`/positronic.config.json`** - Project configuration
+
+## Key Commands
+
+### Development
+
+- `px brain run <brain-name>` - Run a brain workflow
+- `px brain list` - List all available brains
+- `px resource list` - List all available resources
+- `px server` - Start the local development server (add `-d` for background mode)
+
+### Testing & Building
+
+- `npm test` - Run tests (uses Jest with @positronic/core/testing utilities)
+- `npm run build` - Build the project
+- `npm run dev` - Start development mode with hot reload
+
+For testing guidance, see `/docs/brain-testing-guide.md`
+
+## Brain DSL
+
+The Brain DSL provides a fluent API for defining AI workflows:
+
+```typescript
+import { brain } from '@positronic/core';
+
+const myBrain = brain('my-brain')
+  .step('Initialize', ({ state }) => ({
+    ...state,
+    initialized: true
+  }))
+  .step('Process', async ({ state, resources }) => {
+    // Access resources
+    const doc = await resources.get('example.md');
+    return {
+      ...state,
+      processed: true,
+      content: doc.content
+    };
+  });
+
+export default myBrain;
+```
+
+## Resource System
+
+Resources are files that brains can access during execution. They're stored in the `/resources` directory and are automatically typed based on the manifest.
+
+## Development Workflow
+
+1. Define your brain in `/brains`
+2. Add any required resources to `/resources`
+3. Run `px brain run <brain-name>` to test locally
+4. Deploy using backend-specific commands
+
+## Backend-Specific Notes
+
+<% if (backend === 'cloudflare') { %>
+### Cloudflare Workers
+
+This project is configured for Cloudflare Workers deployment:
+
+- Uses Durable Objects for state persistence
+- R2 for resource storage
+- Requires Cloudflare account and API keys
+
+Deployment:
+```bash
+# Configure Cloudflare credentials
+wrangler login
+
+# Deploy
+px deploy
+```
+<% } else if (backend === 'none') { %>
+### Core Only
+
+This project uses only the Positronic core without a specific deployment backend. You can:
+
+- Run brains locally using `px brain run`
+- Add a backend later by installing the appropriate package
+- Use the framework for local AI workflow development
+<% } %>
+
+## Best Practices
+
+1. **State Management**: Keep brain state minimal and serializable
+2. **Resource Naming**: Use descriptive names for resources (e.g., `prompt-templates/customer-support.md`)
+3. **Error Handling**: Always handle potential errors in brain steps
+4. **Testing**: Write tests for your brains focusing on outcomes, not implementation details (see `/docs/brain-testing-guide.md`)
+
+## Getting Help
+
+- Documentation: https://positronic.dev
+- GitHub: https://github.com/positronic-ai/positronic
+- CLI Help: `px --help` or `px <command> --help`
+
+## Project-Level Patterns
+
+For project structure, the project brain pattern, and other Positronic conventions, see:
+@docs/positronic-guide.md
+
+## Additional Tips for AI Agents
+
+@docs/tips-for-agents.md