struere 0.3.6 → 0.3.8

package/dist/bin/struere.js

@@ -17480,6 +17480,332 @@ function getEnvLocal(deploymentUrl) {
   return `STRUERE_DEPLOYMENT_URL=${deploymentUrl}
 `;
 }
+function getClaudeMd(name) {
+  const displayName = name.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  return `# ${displayName} Agent
+
+This is a Struere AI agent project. Struere is a framework for building production AI agents with built-in data management, event tracking, and job scheduling.
+
+## Project Structure
+
+\`\`\`
+src/
+\u251C\u2500\u2500 agent.ts      # Agent definition (system prompt, model, tools)
+\u251C\u2500\u2500 context.ts    # Dynamic context injection per request
+\u251C\u2500\u2500 tools.ts      # Custom tool definitions
+\u2514\u2500\u2500 workflows/    # Multi-step workflow definitions
+tests/
+\u2514\u2500\u2500 *.test.yaml   # YAML-based conversation tests
+struere.json      # Project configuration (agentId, team, slug)
+struere.config.ts # Framework settings (port, CORS, logging)
+\`\`\`
+
+## Agent Definition
+
+Define your agent in \`src/agent.ts\`:
+
+\`\`\`typescript
+import { defineAgent } from 'struere'
+import { tools } from './tools'
+import { context } from './context'
+
+export default defineAgent({
+  name: 'my-agent',
+  version: '0.1.0',
+  description: 'My AI Agent',
+  model: {
+    provider: 'anthropic',
+    name: 'claude-sonnet-4-20250514',
+    temperature: 0.7,
+    maxTokens: 4096,
+  },
+  systemPrompt: \\\`You are a helpful assistant.
+
+Current time: {{datetime}}
+Customer: {{entity.get({"id": "{{thread.metadata.customerId}}"})}}\\\`,
+  tools,
+  context,
+  state: {
+    storage: 'memory',
+    ttl: 3600,
+  },
+})
+\`\`\`
+
+## System Prompt Templates
+
+System prompts support dynamic \`{{...}}\` templates that are resolved at runtime before the LLM call.
+
+### Available Variables
+
+| Variable | Description |
+|----------|-------------|
+| \`{{organizationId}}\` | Current organization ID |
+| \`{{userId}}\` | Current user ID |
+| \`{{threadId}}\` | Conversation thread ID |
+| \`{{agentId}}\` | Agent ID |
+| \`{{agent.name}}\` | Agent name |
+| \`{{agent.slug}}\` | Agent slug |
+| \`{{thread.metadata.X}}\` | Thread metadata field X |
+| \`{{message}}\` | Current user message |
+| \`{{timestamp}}\` | Unix timestamp (ms) |
+| \`{{datetime}}\` | ISO 8601 datetime |
+
+### Function Calls
+
+Call any agent tool directly in the system prompt:
+
+\`\`\`
+{{entity.get({"id": "ent_123"})}}
+{{entity.query({"type": "customer", "limit": 5})}}
+{{event.query({"entityId": "ent_123", "limit": 10})}}
+\`\`\`
+
+### Nested Templates
+
+Variables can be used inside function arguments:
+
+\`\`\`
+{{entity.get({"id": "{{thread.metadata.customerId}}"})}}
+\`\`\`
+
+### Error Handling
+
+Failed templates are replaced with inline errors:
+\`\`\`
+[TEMPLATE_ERROR: variableName not found]
+[TEMPLATE_ERROR: toolName - error message]
+\`\`\`
+
+## Custom Tools
+
+Define tools in \`src/tools.ts\`:
+
+\`\`\`typescript
+import { defineTools } from 'struere'
+
+export const tools = defineTools([
+  {
+    name: 'search_products',
+    description: 'Search the product catalog',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        limit: { type: 'number', description: 'Max results' },
+      },
+      required: ['query'],
+    },
+    handler: async (params) => {
+      const results = await searchProducts(params.query, params.limit ?? 10)
+      return { products: results }
+    },
+  },
+])
+\`\`\`
+
+Custom tool handlers are executed in a sandboxed Cloudflare Worker environment. They can make HTTP requests to allowlisted domains:
+- api.openai.com, api.anthropic.com, api.stripe.com
+- api.sendgrid.com, api.twilio.com, hooks.slack.com
+- discord.com, api.github.com
+
+## Built-in Tools
+
+Agents have access to these built-in tools for data management:
+
+### Entity Tools
+
+| Tool | Description |
+|------|-------------|
+| \`entity.create\` | Create a new entity |
+| \`entity.get\` | Get entity by ID |
+| \`entity.query\` | Query entities by type/filters |
+| \`entity.update\` | Update entity data |
+| \`entity.delete\` | Soft-delete entity |
+| \`entity.link\` | Create entity relation |
+| \`entity.unlink\` | Remove entity relation |
+
+Example entity operations:
+\`\`\`json
+// entity.create
+{ "type": "customer", "data": { "name": "John", "email": "john@example.com" } }
+
+// entity.query
+{ "type": "customer", "filters": { "status": "active" }, "limit": 10 }
+
+// entity.update
+{ "id": "ent_123", "data": { "status": "vip" } }
+\`\`\`
+
+### Event Tools
+
+| Tool | Description |
+|------|-------------|
+| \`event.emit\` | Emit a custom event |
+| \`event.query\` | Query event history |
+
+Example event operations:
+\`\`\`json
+// event.emit
+{ "entityId": "ent_123", "eventType": "order.placed", "payload": { "amount": 99.99 } }
+
+// event.query
+{ "entityId": "ent_123", "eventType": "order.*", "limit": 20 }
+\`\`\`
+
+### Job Tools
+
+| Tool | Description |
+|------|-------------|
+| \`job.enqueue\` | Schedule a background job |
+| \`job.status\` | Get job status |
+
+Example job operations:
+\`\`\`json
+// job.enqueue
+{ "jobType": "send_email", "payload": { "to": "user@example.com" }, "scheduledFor": 1706745600000 }
+
+// job.status
+{ "id": "job_abc123" }
+\`\`\`
+
+## Context Function
+
+Inject dynamic context per request in \`src/context.ts\`:
+
+\`\`\`typescript
+import { defineContext } from 'struere'
+
+export const context = defineContext(async (request) => {
+  const { conversationId, userId, channel, state } = request
+
+  const userProfile = await fetchUserProfile(userId)
+
+  return {
+    additionalContext: \\\`
+User: \${userProfile.name} (\${userProfile.tier} tier)
+Conversation: \${conversationId}
+Channel: \${channel}
+\\\`,
+    variables: {
+      userId,
+      userTier: userProfile.tier,
+      timestamp: new Date().toISOString(),
+    },
+  }
+})
+\`\`\`
+
+## Testing
+
+Write YAML-based conversation tests in \`tests/\`:
+
+\`\`\`yaml
+name: Order flow test
+description: Test the complete order flow
+
+conversation:
+  - role: user
+    content: I want to order a pizza
+  - role: assistant
+    assertions:
+      - type: contains
+        value: size
+      - type: toolCalled
+        value: get_menu
+
+  - role: user
+    content: Large pepperoni please
+  - role: assistant
+    assertions:
+      - type: toolCalled
+        value: entity.create
+\`\`\`
+
+### Assertion Types
+
+| Type | Description |
+|------|-------------|
+| \`contains\` | Response contains substring |
+| \`matches\` | Response matches regex |
+| \`toolCalled\` | Specific tool was called |
+| \`noToolCalled\` | No tools were called |
+
+Run tests with:
+\`\`\`bash
+bun run test
+\`\`\`
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| \`struere dev\` | Start development mode (live sync to Convex) |
+| \`struere build\` | Validate agent configuration |
+| \`struere deploy\` | Deploy agent to production |
+| \`struere test\` | Run YAML conversation tests |
+| \`struere logs\` | View recent execution logs |
+| \`struere state\` | Inspect conversation thread state |
+
+## Thread Metadata
+
+Set thread metadata when creating conversations to provide context:
+
+\`\`\`typescript
+// Via API
+POST /v1/chat
+{
+  "agentId": "agent_123",
+  "message": "Hello",
+  "metadata": {
+    "customerId": "ent_customer_456",
+    "channel": "web",
+    "language": "en"
+  }
+}
+\`\`\`
+
+Access in system prompt:
+\`\`\`
+Customer: {{entity.get({"id": "{{thread.metadata.customerId}}"})}}
+Channel: {{thread.metadata.channel}}
+\`\`\`
+
+## Development Workflow
+
+1. **Edit agent configuration** in \`src/agent.ts\`
+2. **Run \`bun run dev\`** to sync changes to Convex
+3. **Test via API** or dashboard chat interface
+4. **Write tests** in \`tests/*.test.yaml\`
+5. **Deploy** with \`bun run deploy\`
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| \`/v1/chat\` | POST | Chat by agent ID |
+| \`/v1/agents/:slug/chat\` | POST | Chat by agent slug |
+
+Authentication: Bearer token (API key from dashboard)
+
+\`\`\`bash
+curl -X POST https://your-deployment.convex.cloud/v1/chat \\
+  -H "Authorization: Bearer sk_live_..." \\
+  -H "Content-Type: application/json" \\
+  -d '{"agentId": "...", "message": "Hello"}'
+\`\`\`
+
+## Best Practices
+
+1. **System Prompts**: Use templates for dynamic data instead of hardcoding
+2. **Tools**: Keep tool handlers focused and stateless
+3. **Entities**: Model your domain data as entity types
+4. **Events**: Emit events for audit trails and analytics
+5. **Jobs**: Use jobs for async operations (emails, notifications)
+6. **Testing**: Write tests for critical conversation flows
+7. **Context**: Use context for user-specific personalization
+`;
+}
 
 // src/cli/utils/scaffold.ts
 function ensureDir(filePath) {
@@ -17519,7 +17845,8 @@ function scaffoldAgentFiles(cwd, projectName) {
     "src/tools.ts": getToolsTs(),
     "src/workflows/.gitkeep": "",
     "tests/basic.test.yaml": getBasicTestYaml(),
-    ".env.example": getEnvExample()
+    ".env.example": getEnvExample(),
+    ".claude.md": getClaudeMd(projectName)
   };
   for (const [relativePath, content] of Object.entries(files)) {
     const fullPath = join3(cwd, relativePath);
@@ -17797,6 +18124,7 @@ function readLine() {
 // src/cli/commands/dev.ts
 var import_chokidar = __toESM(require_chokidar(), 1);
 import { join as join7, basename as basename2 } from "path";
+import { existsSync as existsSync5, writeFileSync as writeFileSync4 } from "fs";
 
 // src/cli/utils/config.ts
 import { join as join5 } from "path";
@@ -17896,14 +18224,21 @@ var devCommand = new Command("dev").description("Sync agent to development envir
   spinner.start("Loading agent");
   let agent = await loadAgent(cwd);
   spinner.succeed(`Agent "${agent.name}" loaded`);
-  const credentials = loadCredentials();
+  const claudeMdPath = join7(cwd, ".claude.md");
+  if (!existsSync5(claudeMdPath)) {
+    writeFileSync4(claudeMdPath, getClaudeMd(project.agent.slug));
+    console.log(source_default.green("\u2713"), "Created .claude.md");
+  }
+  let credentials = loadCredentials();
   const apiKey = getApiKey();
   if (!credentials && !apiKey) {
-    spinner.fail("Not logged in");
-    console.log();
-    console.log(source_default.gray("Run"), source_default.cyan("struere login"), source_default.gray("to authenticate"));
+    console.log(source_default.gray("Authentication required"));
     console.log();
-    process.exit(1);
+    credentials = await performLogin();
+    if (!credentials) {
+      console.log(source_default.red("Authentication failed"));
+      process.exit(1);
+    }
   }
   spinner.start("Syncing to Convex");
   const performSync = async () => {
@@ -17918,13 +18253,38 @@ var devCommand = new Command("dev").description("Sync agent to development envir
       throw error;
     }
   };
+  const isAuthError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("Unauthenticated") || message.includes("OIDC") || message.includes("token") || message.includes("expired");
+  };
   try {
     await performSync();
     spinner.succeed("Synced to development");
   } catch (error) {
-    spinner.fail("Sync failed");
-    console.log(source_default.red("Error:"), error instanceof Error ? error.message : String(error));
-    process.exit(1);
+    if (isAuthError(error)) {
+      spinner.fail("Session expired");
+      console.log();
+      console.log(source_default.gray("Re-authenticating..."));
+      clearCredentials();
+      credentials = await performLogin();
+      if (!credentials) {
+        console.log(source_default.red("Authentication failed"));
+        process.exit(1);
+      }
+      spinner.start("Syncing to Convex");
+      try {
+        await performSync();
+        spinner.succeed("Synced to development");
+      } catch (retryError) {
+        spinner.fail("Sync failed");
+        console.log(source_default.red("Error:"), retryError instanceof Error ? retryError.message : String(retryError));
+        process.exit(1);
+      }
+    } else {
+      spinner.fail("Sync failed");
+      console.log(source_default.red("Error:"), error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
   }
   const devUrl = `https://${project.agent.slug}-dev.struere.dev`;
   console.log();
@@ -17945,8 +18305,28 @@ var devCommand = new Command("dev").description("Sync agent to development envir
       await performSync();
       syncSpinner.succeed("Synced");
     } catch (error) {
-      syncSpinner.fail("Sync failed");
-      console.log(source_default.red("Error:"), error instanceof Error ? error.message : String(error));
+      if (isAuthError(error)) {
+        syncSpinner.fail("Session expired");
+        console.log();
+        console.log(source_default.gray("Re-authenticating..."));
+        clearCredentials();
+        const newCredentials = await performLogin();
+        if (!newCredentials) {
+          console.log(source_default.red("Authentication failed"));
+          return;
+        }
+        const retrySyncSpinner = ora("Syncing...").start();
+        try {
+          await performSync();
+          retrySyncSpinner.succeed("Synced");
+        } catch (retryError) {
+          retrySyncSpinner.fail("Sync failed");
+          console.log(source_default.red("Error:"), retryError instanceof Error ? retryError.message : String(retryError));
+        }
+      } else {
+        syncSpinner.fail("Sync failed");
+        console.log(source_default.red("Error:"), error instanceof Error ? error.message : String(error));
+      }
     }
   });
   process.on("SIGINT", () => {
@@ -18768,9 +19148,17 @@ var whoamiCommand = new Command("whoami").description("Show current logged in us
 // package.json
 var package_default = {
   name: "struere",
-  version: "0.3.6",
+  version: "0.3.8",
   description: "Build, test, and deploy AI agents",
-  keywords: ["ai", "agents", "llm", "anthropic", "openai", "framework", "cli"],
+  keywords: [
+    "ai",
+    "agents",
+    "llm",
+    "anthropic",
+    "openai",
+    "framework",
+    "cli"
+  ],
   author: "struere",
   license: "MIT",
   publishConfig: {
@@ -18797,7 +19185,9 @@ var package_default = {
       types: "./dist/index.d.ts"
     }
   },
-  files: ["dist"],
+  files: [
+    "dist"
+  ],
   scripts: {
     build: "bun build ./src/cli/index.ts --outdir ./dist/cli --target bun --external commander --external chalk --external ora --external chokidar --external yaml && bun build ./src/index.ts --outdir ./dist --target node && bun build ./src/bin/struere.ts --outdir ./dist/bin --target bun && tsc --emitDeclarationOnly && chmod +x ./dist/bin/struere.js",
     dev: "tsc --watch",

package/dist/cli/commands/dev.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAanC,eAAO,MAAM,UAAU,SA8GnB,CAAA"}
+{"version":3,"file":"dev.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/dev.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAenC,eAAO,MAAM,UAAU,SAuKnB,CAAA"}

package/dist/cli/index.js

@@ -819,6 +819,332 @@ function getEnvLocal(deploymentUrl) {
   return `STRUERE_DEPLOYMENT_URL=${deploymentUrl}
 `;
 }
+function getClaudeMd(name) {
+  const displayName = name.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  return `# ${displayName} Agent
+
+This is a Struere AI agent project. Struere is a framework for building production AI agents with built-in data management, event tracking, and job scheduling.
+
+## Project Structure
+
+\`\`\`
+src/
+\u251C\u2500\u2500 agent.ts      # Agent definition (system prompt, model, tools)
+\u251C\u2500\u2500 context.ts    # Dynamic context injection per request
+\u251C\u2500\u2500 tools.ts      # Custom tool definitions
+\u2514\u2500\u2500 workflows/    # Multi-step workflow definitions
+tests/
+\u2514\u2500\u2500 *.test.yaml   # YAML-based conversation tests
+struere.json      # Project configuration (agentId, team, slug)
+struere.config.ts # Framework settings (port, CORS, logging)
+\`\`\`
+
+## Agent Definition
+
+Define your agent in \`src/agent.ts\`:
+
+\`\`\`typescript
+import { defineAgent } from 'struere'
+import { tools } from './tools'
+import { context } from './context'
+
+export default defineAgent({
+  name: 'my-agent',
+  version: '0.1.0',
+  description: 'My AI Agent',
+  model: {
+    provider: 'anthropic',
+    name: 'claude-sonnet-4-20250514',
+    temperature: 0.7,
+    maxTokens: 4096,
+  },
+  systemPrompt: \\\`You are a helpful assistant.
+
+Current time: {{datetime}}
+Customer: {{entity.get({"id": "{{thread.metadata.customerId}}"})}}\\\`,
+  tools,
+  context,
+  state: {
+    storage: 'memory',
+    ttl: 3600,
+  },
+})
+\`\`\`
+
+## System Prompt Templates
+
+System prompts support dynamic \`{{...}}\` templates that are resolved at runtime before the LLM call.
+
+### Available Variables
+
+| Variable | Description |
+|----------|-------------|
+| \`{{organizationId}}\` | Current organization ID |
+| \`{{userId}}\` | Current user ID |
+| \`{{threadId}}\` | Conversation thread ID |
+| \`{{agentId}}\` | Agent ID |
+| \`{{agent.name}}\` | Agent name |
+| \`{{agent.slug}}\` | Agent slug |
+| \`{{thread.metadata.X}}\` | Thread metadata field X |
+| \`{{message}}\` | Current user message |
+| \`{{timestamp}}\` | Unix timestamp (ms) |
+| \`{{datetime}}\` | ISO 8601 datetime |
+
+### Function Calls
+
+Call any agent tool directly in the system prompt:
+
+\`\`\`
+{{entity.get({"id": "ent_123"})}}
+{{entity.query({"type": "customer", "limit": 5})}}
+{{event.query({"entityId": "ent_123", "limit": 10})}}
+\`\`\`
+
+### Nested Templates
+
+Variables can be used inside function arguments:
+
+\`\`\`
+{{entity.get({"id": "{{thread.metadata.customerId}}"})}}
+\`\`\`
+
+### Error Handling
+
+Failed templates are replaced with inline errors:
+\`\`\`
+[TEMPLATE_ERROR: variableName not found]
+[TEMPLATE_ERROR: toolName - error message]
+\`\`\`
+
+## Custom Tools
+
+Define tools in \`src/tools.ts\`:
+
+\`\`\`typescript
+import { defineTools } from 'struere'
+
+export const tools = defineTools([
+  {
+    name: 'search_products',
+    description: 'Search the product catalog',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Search query' },
+        limit: { type: 'number', description: 'Max results' },
+      },
+      required: ['query'],
+    },
+    handler: async (params) => {
+      const results = await searchProducts(params.query, params.limit ?? 10)
+      return { products: results }
+    },
+  },
+])
+\`\`\`
+
+Custom tool handlers are executed in a sandboxed Cloudflare Worker environment. They can make HTTP requests to allowlisted domains:
+- api.openai.com, api.anthropic.com, api.stripe.com
+- api.sendgrid.com, api.twilio.com, hooks.slack.com
+- discord.com, api.github.com
+
+## Built-in Tools
+
+Agents have access to these built-in tools for data management:
+
+### Entity Tools
+
+| Tool | Description |
+|------|-------------|
+| \`entity.create\` | Create a new entity |
+| \`entity.get\` | Get entity by ID |
+| \`entity.query\` | Query entities by type/filters |
+| \`entity.update\` | Update entity data |
+| \`entity.delete\` | Soft-delete entity |
+| \`entity.link\` | Create entity relation |
+| \`entity.unlink\` | Remove entity relation |
+
+Example entity operations:
+\`\`\`json
+// entity.create
+{ "type": "customer", "data": { "name": "John", "email": "john@example.com" } }
+
+// entity.query
+{ "type": "customer", "filters": { "status": "active" }, "limit": 10 }
+
+// entity.update
+{ "id": "ent_123", "data": { "status": "vip" } }
+\`\`\`
+
+### Event Tools
+
+| Tool | Description |
+|------|-------------|
+| \`event.emit\` | Emit a custom event |
+| \`event.query\` | Query event history |
+
+Example event operations:
+\`\`\`json
+// event.emit
+{ "entityId": "ent_123", "eventType": "order.placed", "payload": { "amount": 99.99 } }
+
+// event.query
+{ "entityId": "ent_123", "eventType": "order.*", "limit": 20 }
+\`\`\`
+
+### Job Tools
+
+| Tool | Description |
+|------|-------------|
+| \`job.enqueue\` | Schedule a background job |
+| \`job.status\` | Get job status |
+
+Example job operations:
+\`\`\`json
+// job.enqueue
+{ "jobType": "send_email", "payload": { "to": "user@example.com" }, "scheduledFor": 1706745600000 }
+
+// job.status
+{ "id": "job_abc123" }
+\`\`\`
+
+## Context Function
+
+Inject dynamic context per request in \`src/context.ts\`:
+
+\`\`\`typescript
+import { defineContext } from 'struere'
+
+export const context = defineContext(async (request) => {
+  const { conversationId, userId, channel, state } = request
+
+  const userProfile = await fetchUserProfile(userId)
+
+  return {
+    additionalContext: \\\`
+User: \${userProfile.name} (\${userProfile.tier} tier)
+Conversation: \${conversationId}
+Channel: \${channel}
+\\\`,
+    variables: {
+      userId,
+      userTier: userProfile.tier,
+      timestamp: new Date().toISOString(),
+    },
+  }
+})
+\`\`\`
+
+## Testing
+
+Write YAML-based conversation tests in \`tests/\`:
+
+\`\`\`yaml
+name: Order flow test
+description: Test the complete order flow
+
+conversation:
+  - role: user
+    content: I want to order a pizza
+  - role: assistant
+    assertions:
+      - type: contains
+        value: size
+      - type: toolCalled
+        value: get_menu
+
+  - role: user
+    content: Large pepperoni please
+  - role: assistant
+    assertions:
+      - type: toolCalled
+        value: entity.create
+\`\`\`
+
+### Assertion Types
+
+| Type | Description |
+|------|-------------|
+| \`contains\` | Response contains substring |
+| \`matches\` | Response matches regex |
+| \`toolCalled\` | Specific tool was called |
+| \`noToolCalled\` | No tools were called |
+
+Run tests with:
+\`\`\`bash
+bun run test
+\`\`\`
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| \`struere dev\` | Start development mode (live sync to Convex) |
+| \`struere build\` | Validate agent configuration |
+| \`struere deploy\` | Deploy agent to production |
+| \`struere test\` | Run YAML conversation tests |
+| \`struere logs\` | View recent execution logs |
+| \`struere state\` | Inspect conversation thread state |
+
+## Thread Metadata
+
+Set thread metadata when creating conversations to provide context:
+
+\`\`\`typescript
+// Via API
+POST /v1/chat
+{
+  "agentId": "agent_123",
+  "message": "Hello",
+  "metadata": {
+    "customerId": "ent_customer_456",
+    "channel": "web",
+    "language": "en"
+  }
+}
+\`\`\`
+
+Access in system prompt:
+\`\`\`
+Customer: {{entity.get({"id": "{{thread.metadata.customerId}}"})}}
+Channel: {{thread.metadata.channel}}
+\`\`\`
+
+## Development Workflow
+
+1. **Edit agent configuration** in \`src/agent.ts\`
+2. **Run \`bun run dev\`** to sync changes to Convex
+3. **Test via API** or dashboard chat interface
+4. **Write tests** in \`tests/*.test.yaml\`
+5. **Deploy** with \`bun run deploy\`
+
+## API Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| \`/v1/chat\` | POST | Chat by agent ID |
+| \`/v1/agents/:slug/chat\` | POST | Chat by agent slug |
+
+Authentication: Bearer token (API key from dashboard)
+
+\`\`\`bash
+curl -X POST https://your-deployment.convex.cloud/v1/chat \\
+  -H "Authorization: Bearer sk_live_..." \\
+  -H "Content-Type: application/json" \\
+  -d '{"agentId": "...", "message": "Hello"}'
+\`\`\`
+
+## Best Practices
+
+1. **System Prompts**: Use templates for dynamic data instead of hardcoding
+2. **Tools**: Keep tool handlers focused and stateless
+3. **Entities**: Model your domain data as entity types
+4. **Events**: Emit events for audit trails and analytics
+5. **Jobs**: Use jobs for async operations (emails, notifications)
+6. **Testing**: Write tests for critical conversation flows
+7. **Context**: Use context for user-specific personalization
+`;
+}
 
 // src/cli/utils/scaffold.ts
 function ensureDir(filePath) {
@@ -858,7 +1184,8 @@ function scaffoldAgentFiles(cwd, projectName) {
     "src/tools.ts": getToolsTs(),
     "src/workflows/.gitkeep": "",
     "tests/basic.test.yaml": getBasicTestYaml(),
-    ".env.example": getEnvExample()
+    ".env.example": getEnvExample(),
+    ".claude.md": getClaudeMd(projectName)
   };
   for (const [relativePath, content] of Object.entries(files)) {
     const fullPath = join3(cwd, relativePath);
@@ -1139,6 +1466,7 @@ import chalk3 from "chalk";
 import ora3 from "ora";
 import chokidar from "chokidar";
 import { join as join7, basename as basename2 } from "path";
+import { existsSync as existsSync5, writeFileSync as writeFileSync4 } from "fs";
 
 // src/cli/utils/config.ts
 import { join as join5 } from "path";
@@ -1238,14 +1566,21 @@ var devCommand = new Command3("dev").description("Sync agent to development envi
   spinner.start("Loading agent");
   let agent = await loadAgent(cwd);
   spinner.succeed(`Agent "${agent.name}" loaded`);
-  const credentials = loadCredentials();
+  const claudeMdPath = join7(cwd, ".claude.md");
+  if (!existsSync5(claudeMdPath)) {
+    writeFileSync4(claudeMdPath, getClaudeMd(project.agent.slug));
+    console.log(chalk3.green("\u2713"), "Created .claude.md");
+  }
+  let credentials = loadCredentials();
   const apiKey = getApiKey();
   if (!credentials && !apiKey) {
-    spinner.fail("Not logged in");
-    console.log();
-    console.log(chalk3.gray("Run"), chalk3.cyan("struere login"), chalk3.gray("to authenticate"));
+    console.log(chalk3.gray("Authentication required"));
     console.log();
-    process.exit(1);
+    credentials = await performLogin();
+    if (!credentials) {
+      console.log(chalk3.red("Authentication failed"));
+      process.exit(1);
+    }
   }
   spinner.start("Syncing to Convex");
   const performSync = async () => {
@@ -1260,13 +1595,38 @@ var devCommand = new Command3("dev").description("Sync agent to development envi
       throw error;
     }
   };
+  const isAuthError = (error) => {
+    const message = error instanceof Error ? error.message : String(error);
+    return message.includes("Unauthenticated") || message.includes("OIDC") || message.includes("token") || message.includes("expired");
+  };
   try {
     await performSync();
     spinner.succeed("Synced to development");
   } catch (error) {
-    spinner.fail("Sync failed");
-    console.log(chalk3.red("Error:"), error instanceof Error ? error.message : String(error));
-    process.exit(1);
+    if (isAuthError(error)) {
+      spinner.fail("Session expired");
+      console.log();
+      console.log(chalk3.gray("Re-authenticating..."));
+      clearCredentials();
+      credentials = await performLogin();
+      if (!credentials) {
+        console.log(chalk3.red("Authentication failed"));
+        process.exit(1);
+      }
+      spinner.start("Syncing to Convex");
+      try {
+        await performSync();
+        spinner.succeed("Synced to development");
+      } catch (retryError) {
+        spinner.fail("Sync failed");
+        console.log(chalk3.red("Error:"), retryError instanceof Error ? retryError.message : String(retryError));
+        process.exit(1);
+      }
+    } else {
+      spinner.fail("Sync failed");
+      console.log(chalk3.red("Error:"), error instanceof Error ? error.message : String(error));
+      process.exit(1);
+    }
   }
   const devUrl = `https://${project.agent.slug}-dev.struere.dev`;
   console.log();
@@ -1287,8 +1647,28 @@ var devCommand = new Command3("dev").description("Sync agent to development envi
       await performSync();
       syncSpinner.succeed("Synced");
     } catch (error) {
-      syncSpinner.fail("Sync failed");
-      console.log(chalk3.red("Error:"), error instanceof Error ? error.message : String(error));
+      if (isAuthError(error)) {
+        syncSpinner.fail("Session expired");
+        console.log();
+        console.log(chalk3.gray("Re-authenticating..."));
+        clearCredentials();
+        const newCredentials = await performLogin();
+        if (!newCredentials) {
+          console.log(chalk3.red("Authentication failed"));
+          return;
+        }
+        const retrySyncSpinner = ora3("Syncing...").start();
+        try {
+          await performSync();
+          retrySyncSpinner.succeed("Synced");
+        } catch (retryError) {
+          retrySyncSpinner.fail("Sync failed");
+          console.log(chalk3.red("Error:"), retryError instanceof Error ? retryError.message : String(retryError));
+        }
+      } else {
+        syncSpinner.fail("Sync failed");
+        console.log(chalk3.red("Error:"), error instanceof Error ? error.message : String(error));
+      }
     }
   });
   process.on("SIGINT", () => {
@@ -2133,9 +2513,17 @@ var whoamiCommand = new Command11("whoami").description("Show current logged in
 // package.json
 var package_default = {
   name: "struere",
-  version: "0.3.6",
+  version: "0.3.8",
   description: "Build, test, and deploy AI agents",
-  keywords: ["ai", "agents", "llm", "anthropic", "openai", "framework", "cli"],
+  keywords: [
+    "ai",
+    "agents",
+    "llm",
+    "anthropic",
+    "openai",
+    "framework",
+    "cli"
+  ],
   author: "struere",
   license: "MIT",
   publishConfig: {
@@ -2162,7 +2550,9 @@ var package_default = {
       types: "./dist/index.d.ts"
     }
   },
-  files: ["dist"],
+  files: [
+    "dist"
+  ],
   scripts: {
     build: "bun build ./src/cli/index.ts --outdir ./dist/cli --target bun --external commander --external chalk --external ora --external chokidar --external yaml && bun build ./src/index.ts --outdir ./dist --target node && bun build ./src/bin/struere.ts --outdir ./dist/bin --target bun && tsc --emitDeclarationOnly && chmod +x ./dist/bin/struere.js",
     dev: "tsc --watch",

package/dist/cli/templates/index.d.ts

@@ -9,4 +9,5 @@ export declare function getEnvExample(): string;
 export declare function getGitignore(): string;
 export declare function getStruereJson(agentId: string, team: string, slug: string, name: string): string;
 export declare function getEnvLocal(deploymentUrl: string): string;
+export declare function getClaudeMd(name: string): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/templates/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/templates/index.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBnD;AAED,wBAAgB,WAAW,IAAI,MAAM,CAsBpC;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAgBzC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoC/C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAkBrC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAoDnC;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAmBzC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAatC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAgBrC;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAahG;AAED,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAGzD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/templates/index.ts"],"names":[],"mappings":"AAAA,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAuBnD;AAED,wBAAgB,WAAW,IAAI,MAAM,CAsBpC;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAgBzC;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAoC/C;AAED,wBAAgB,YAAY,IAAI,MAAM,CAkBrC;AAED,wBAAgB,UAAU,IAAI,MAAM,CAoDnC;AAED,wBAAgB,gBAAgB,IAAI,MAAM,CAmBzC;AAED,wBAAgB,aAAa,IAAI,MAAM,CAatC;AAED,wBAAgB,YAAY,IAAI,MAAM,CAgBrC;AAED,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAahG;AAED,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAGzD;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAyUhD"}

package/dist/cli/utils/scaffold.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/scaffold.ts"],"names":[],"mappings":"AAgBA,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB;AAeD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAexF;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CA+BrF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CA8BnF;AAsBD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../src/cli/utils/scaffold.ts"],"names":[],"mappings":"AAiBA,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,aAAa,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,EAAE,CAAA;IACtB,YAAY,EAAE,MAAM,EAAE,CAAA;CACvB;AAeD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAexF;AAED,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,cAAc,CAgCrF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,cAAc,CA+BnF;AAsBD,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAElD"}

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "struere",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "Build, test, and deploy AI agents",
-  "keywords": ["ai", "agents", "llm", "anthropic", "openai", "framework", "cli"],
+  "keywords": [
+    "ai",
+    "agents",
+    "llm",
+    "anthropic",
+    "openai",
+    "framework",
+    "cli"
+  ],
   "author": "struere",
   "license": "MIT",
   "publishConfig": {
@@ -29,7 +37,9 @@
       "types": "./dist/index.d.ts"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "bun build ./src/cli/index.ts --outdir ./dist/cli --target bun --external commander --external chalk --external ora --external chokidar --external yaml && bun build ./src/index.ts --outdir ./dist --target node && bun build ./src/bin/struere.ts --outdir ./dist/bin --target bun && tsc --emitDeclarationOnly && chmod +x ./dist/bin/struere.js",
     "dev": "tsc --watch",