struere 0.3.5 → 0.3.7

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);
@@ -17627,12 +17954,12 @@ var initCommand = new Command("init").description("Initialize a new Struere proj
     }
   }
   if (!selectedAgent) {
-    const displayName = projectName.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+    const displayName2 = projectName.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
     spinner.start("Creating agent");
     const { agentId, error: createError } = await createAgent({
-      name: displayName,
+      name: displayName2,
       slug: projectName,
-      description: `${displayName} Agent`
+      description: `${displayName2} Agent`
     });
     if (createError || !agentId) {
       spinner.fail("Failed to create agent");
@@ -17640,7 +17967,7 @@ var initCommand = new Command("init").description("Initialize a new Struere proj
       console.log(source_default.red("Error:"), createError || "Unknown error");
       process.exit(1);
     }
-    selectedAgent = { id: agentId, name: displayName, slug: projectName };
+    selectedAgent = { id: agentId, name: displayName2, slug: projectName };
     deploymentUrl = `https://${projectName}-dev.struere.dev`;
     spinner.succeed(`Created agent "${projectName}"`);
   } else {
@@ -17691,10 +18018,43 @@ var initCommand = new Command("init").description("Initialize a new Struere proj
     }
   }
   console.log();
+  spinner.start("Installing dependencies");
+  const installResult = Bun.spawnSync(["bun", "install"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  if (installResult.exitCode === 0) {
+    spinner.succeed("Dependencies installed");
+  } else {
+    spinner.warn("Could not install dependencies automatically");
+    console.log(source_default.gray("  Run"), source_default.cyan("bun install"), source_default.gray("manually"));
+  }
+  spinner.start("Syncing initial config to Convex");
+  const displayName = projectName.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  const defaultConfig = {
+    name: displayName,
+    version: "0.1.0",
+    systemPrompt: `You are ${displayName}, a helpful AI assistant. You help users with their questions and tasks.`,
+    model: {
+      provider: "anthropic",
+      name: "claude-sonnet-4-20250514",
+      temperature: 0.7,
+      maxTokens: 4096
+    },
+    tools: []
+  };
+  const syncResult = await syncToConvex(selectedAgent.id, defaultConfig);
+  if (syncResult.success) {
+    spinner.succeed("Initial config synced");
+  } else {
+    spinner.warn("Could not sync initial config");
+    console.log(source_default.gray("  Run"), source_default.cyan("struere dev"), source_default.gray("to sync manually"));
+  }
+  console.log();
   console.log(source_default.green("Success!"), "Project initialized");
   console.log();
   console.log(source_default.gray("Next steps:"));
-  console.log(source_default.gray("  $"), source_default.cyan("bun install"));
   console.log(source_default.gray("  $"), source_default.cyan("struere dev"));
   console.log();
 });
@@ -18735,9 +19095,17 @@ var whoamiCommand = new Command("whoami").description("Show current logged in us
 // package.json
 var package_default = {
   name: "struere",
-  version: "0.3.5",
+  version: "0.3.7",
   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: {
@@ -18764,7 +19132,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/init.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAWnC,eAAO,MAAM,WAAW,SA0KpB,CAAA;AAEJ,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYpE;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C"}
+{"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../../src/cli/commands/init.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAWnC,eAAO,MAAM,WAAW,SA4NpB,CAAA;AAEJ,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAYpE;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK5C"}

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);
@@ -966,12 +1293,12 @@ var initCommand = new Command2("init").description("Initialize a new Struere pro
     }
   }
   if (!selectedAgent) {
-    const displayName = projectName.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+    const displayName2 = projectName.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
     spinner.start("Creating agent");
     const { agentId, error: createError } = await createAgent({
-      name: displayName,
+      name: displayName2,
       slug: projectName,
-      description: `${displayName} Agent`
+      description: `${displayName2} Agent`
     });
     if (createError || !agentId) {
       spinner.fail("Failed to create agent");
@@ -979,7 +1306,7 @@ var initCommand = new Command2("init").description("Initialize a new Struere pro
       console.log(chalk2.red("Error:"), createError || "Unknown error");
       process.exit(1);
     }
-    selectedAgent = { id: agentId, name: displayName, slug: projectName };
+    selectedAgent = { id: agentId, name: displayName2, slug: projectName };
     deploymentUrl = `https://${projectName}-dev.struere.dev`;
     spinner.succeed(`Created agent "${projectName}"`);
   } else {
@@ -1030,10 +1357,43 @@ var initCommand = new Command2("init").description("Initialize a new Struere pro
     }
   }
   console.log();
+  spinner.start("Installing dependencies");
+  const installResult = Bun.spawnSync(["bun", "install"], {
+    cwd,
+    stdout: "pipe",
+    stderr: "pipe"
+  });
+  if (installResult.exitCode === 0) {
+    spinner.succeed("Dependencies installed");
+  } else {
+    spinner.warn("Could not install dependencies automatically");
+    console.log(chalk2.gray("  Run"), chalk2.cyan("bun install"), chalk2.gray("manually"));
+  }
+  spinner.start("Syncing initial config to Convex");
+  const displayName = projectName.split("-").map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+  const defaultConfig = {
+    name: displayName,
+    version: "0.1.0",
+    systemPrompt: `You are ${displayName}, a helpful AI assistant. You help users with their questions and tasks.`,
+    model: {
+      provider: "anthropic",
+      name: "claude-sonnet-4-20250514",
+      temperature: 0.7,
+      maxTokens: 4096
+    },
+    tools: []
+  };
+  const syncResult = await syncToConvex(selectedAgent.id, defaultConfig);
+  if (syncResult.success) {
+    spinner.succeed("Initial config synced");
+  } else {
+    spinner.warn("Could not sync initial config");
+    console.log(chalk2.gray("  Run"), chalk2.cyan("struere dev"), chalk2.gray("to sync manually"));
+  }
+  console.log();
   console.log(chalk2.green("Success!"), "Project initialized");
   console.log();
   console.log(chalk2.gray("Next steps:"));
-  console.log(chalk2.gray("  $"), chalk2.cyan("bun install"));
   console.log(chalk2.gray("  $"), chalk2.cyan("struere dev"));
   console.log();
 });
@@ -2100,9 +2460,17 @@ var whoamiCommand = new Command11("whoami").description("Show current logged in
 // package.json
 var package_default = {
   name: "struere",
-  version: "0.3.5",
+  version: "0.3.7",
   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: {
@@ -2129,7 +2497,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.5",
+  "version": "0.3.7",
   "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",