create-cogitator-app 0.3.0 → 0.4.0

package/dist/index.js

@@ -2,7 +2,8 @@
 
 // src/index.ts
 import * as p3 from "@clack/prompts";
-import { readFileSync } from "fs";
+import { readFileSync as readFileSync2 } from "fs";
+import path5 from "path";
 import pc2 from "picocolors";
 
 // src/utils/logger.ts
@@ -34,74 +35,170 @@ function banner(version) {
 
 // src/prompts.ts
 import * as p from "@clack/prompts";
-import path from "path";
+import path3 from "path";
 
 // src/utils/providers.ts
 var defaultModels = {
-  ollama: "qwen3:8b",
+  ollama: "qwen3.5:9b",
   openai: "gpt-6.1-sol",
   anthropic: "claude-sonnet-5-5",
   google: "gemini-3.8-flash"
 };
-function providerConfig(provider) {
-  switch (provider) {
-    case "ollama":
-      return [
-        `  llm: {`,
-        `    defaultProvider: 'ollama',`,
-        `    providers: {`,
-        `      ollama: { baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434' },`,
-        `    },`,
-        `  },`
-      ].join("\n");
-    case "openai":
-      return [
-        `  llm: {`,
-        `    defaultProvider: 'openai',`,
-        `    providers: {`,
-        `      openai: { apiKey: process.env.OPENAI_API_KEY! },`,
-        `    },`,
-        `  },`
-      ].join("\n");
-    case "anthropic":
-      return [
-        `  llm: {`,
-        `    defaultProvider: 'anthropic',`,
-        `    providers: {`,
-        `      anthropic: { apiKey: process.env.ANTHROPIC_API_KEY! },`,
-        `    },`,
-        `  },`
-      ].join("\n");
-    case "google":
-      return [
-        `  llm: {`,
-        `    defaultProvider: 'google',`,
-        `    providers: {`,
-        `      google: { apiKey: process.env.GOOGLE_API_KEY! },`,
-        `    },`,
-        `  },`
-      ].join("\n");
+function modelFor(options) {
+  return options.model?.trim() || defaultModels[options.provider];
+}
+function providerEnvKey(provider) {
+  const map = {
+    ollama: "OLLAMA_BASE_URL",
+    openai: "OPENAI_API_KEY",
+    anthropic: "ANTHROPIC_API_KEY",
+    google: "GOOGLE_API_KEY"
+  };
+  return map[provider];
+}
+function apiKeyExpression(envKey, access) {
+  return access === "requireEnv" ? `requireEnv('${envKey}')` : `process.env.${envKey} ?? ''`;
+}
+function providerConfig(provider, access = "process-env") {
+  if (provider === "ollama") {
+    return [
+      `  llm: {`,
+      `    defaultProvider: 'ollama',`,
+      `    providers: {`,
+      `      ollama: { baseUrl: process.env.OLLAMA_BASE_URL || 'http://localhost:11434' },`,
+      `    },`,
+      `  },`
+    ].join("\n");
   }
+  return [
+    `  llm: {`,
+    `    defaultProvider: '${provider}',`,
+    `    providers: {`,
+    `      ${provider}: { apiKey: ${apiKeyExpression(providerEnvKey(provider), access)} },`,
+    `    },`,
+    `  },`
+  ].join("\n");
 }
 
 // src/templates/versions.ts
+import { existsSync, readFileSync } from "fs";
+import path from "path";
+import { fileURLToPath } from "url";
 var ZOD_VERSION = "^4.6.5";
+var IOREDIS_VERSION = "^6.0.0";
+var OWN_NAME = "create-cogitator-app";
+var SCOPE = "@cogitator-ai/";
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function readManifest(file) {
+  const parsed = JSON.parse(readFileSync(file, "utf-8"));
+  if (!isRecord(parsed)) throw new Error(`${file} is not a package manifest`);
+  return parsed;
+}
+function findOwnRoot(from) {
+  let dir = from;
+  while (true) {
+    const manifest = path.join(dir, "package.json");
+    if (existsSync(manifest) && readManifest(manifest).name === OWN_NAME) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) throw new Error(`Cannot find the ${OWN_NAME} package.json above ${from}`);
+    dir = parent;
+  }
+}
+function linkedVersion(packageRoot, name) {
+  const manifest = path.join(packageRoot, "node_modules", name, "package.json");
+  if (!existsSync(manifest)) {
+    throw new Error(`Cannot resolve the version of ${name}: ${manifest} does not exist`);
+  }
+  const version = readManifest(manifest).version;
+  if (typeof version !== "string") throw new Error(`${manifest} has no version`);
+  return version;
+}
+function readCogitatorVersions(packageRoot) {
+  const devDependencies = readManifest(path.join(packageRoot, "package.json")).devDependencies;
+  const versions = {};
+  if (!isRecord(devDependencies)) return versions;
+  for (const [name, range] of Object.entries(devDependencies)) {
+    if (!name.startsWith(SCOPE) || typeof range !== "string") continue;
+    versions[name] = range.startsWith("workspace:") ? `^${linkedVersion(packageRoot, name)}` : range;
+  }
+  return versions;
+}
+var resolved;
+function cogitatorVersion(name) {
+  resolved ??= readCogitatorVersions(findOwnRoot(path.dirname(fileURLToPath(import.meta.url))));
+  const range = resolved[name];
+  if (!range) {
+    throw new Error(`${name} is not a devDependency of ${OWN_NAME}, so its version is unknown`);
+  }
+  return range;
+}
+
+// src/templates/shared.ts
+function tsString(value) {
+  const escaped = value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\p{Zl}/gu, "\\u2028").replace(/\p{Zp}/gu, "\\u2029");
+  return `'${escaped}'`;
+}
+function needsApiKey(provider) {
+  return provider !== "ollama";
+}
+function envHelperFiles(provider) {
+  if (!needsApiKey(provider)) return [];
+  const content = [
+    `export function requireEnv(name: string): string {`,
+    `  const value = process.env[name]`,
+    `  if (!value) {`,
+    `    throw new Error(\`\${name} is not set. Copy .env.example to .env and fill it in.\`)`,
+    `  }`,
+    `  return value`,
+    `}`,
+    ``
+  ].join("\n");
+  return [{ path: "src/env.ts", content }];
+}
+function envHelperImport(provider) {
+  return needsApiKey(provider) ? [`import { requireEnv } from './env.js'`] : [];
+}
+var RUN_MAIN = [
+  `main().catch((error: unknown) => {`,
+  `  console.error(error)`,
+  `  process.exitCode = 1`,
+  `})`,
+  ``
+];
+function scriptTemplateScripts() {
+  return {
+    dev: "tsx watch --env-file-if-exists=.env src/index.ts",
+    start: "tsx --env-file-if-exists=.env src/index.ts",
+    build: "tsc",
+    typecheck: "tsc --noEmit"
+  };
+}
+function scriptTemplateDevDependencies() {
+  return {
+    typescript: "^5.8.0",
+    tsx: "^4.19.0",
+    "@types/node": "^22.0.0"
+  };
+}
 
 // src/templates/basic.ts
 var basicTemplate = {
   files(options) {
-    const model = defaultModels[options.provider];
+    const model = modelFor(options);
     const indexTs = [
       `import { Cogitator, Agent } from '@cogitator-ai/core'`,
       `import { searchTool, summarizeTool } from './tools.js'`,
+      ...envHelperImport(options.provider),
       ``,
       `const cogitator = new Cogitator({`,
-      providerConfig(options.provider),
+      providerConfig(options.provider, "requireEnv"),
       `})`,
       ``,
       `const agent = new Agent({`,
-      `  name: '${options.name}-agent',`,
-      `  model: '${model}',`,
+      `  name: ${tsString(`${options.name}-agent`)},`,
+      `  model: ${tsString(model)},`,
       `  instructions: 'You are a helpful AI assistant. Use your tools to help the user.',`,
       `  tools: [searchTool, summarizeTool],`,
       `  temperature: 0.7,`,
@@ -115,8 +212,7 @@ var basicTemplate = {
       `  console.log(result.output)`,
       `}`,
       ``,
-      `main().catch(console.error)`,
-      ``
+      ...RUN_MAIN
     ].join("\n");
     const toolsTs = [
       `import { tool } from '@cogitator-ai/core'`,
@@ -149,42 +245,36 @@ var basicTemplate = {
     ].join("\n");
     return [
       { path: "src/index.ts", content: indexTs },
-      { path: "src/tools.ts", content: toolsTs }
+      { path: "src/tools.ts", content: toolsTs },
+      ...envHelperFiles(options.provider)
     ];
   },
   dependencies() {
     return {
-      "@cogitator-ai/core": "latest",
+      "@cogitator-ai/core": cogitatorVersion("@cogitator-ai/core"),
       zod: ZOD_VERSION
     };
   },
   devDependencies() {
-    return {
-      typescript: "^5.8.0",
-      tsx: "^4.19.0",
-      "@types/node": "^22.0.0"
-    };
+    return scriptTemplateDevDependencies();
   },
   scripts() {
-    return {
-      dev: "tsx watch src/index.ts",
-      start: "tsx src/index.ts",
-      build: "tsc",
-      typecheck: "tsc --noEmit"
-    };
+    return scriptTemplateScripts();
   }
 };
 
 // src/templates/memory.ts
 var memoryTemplate = {
+  memoryAdapter: "redis",
   files(options) {
-    const model = defaultModels[options.provider];
+    const model = modelFor(options);
     const indexTs = [
       `import { Cogitator, Agent } from '@cogitator-ai/core'`,
       `import { searchTool, noteTool } from './tools.js'`,
+      ...envHelperImport(options.provider),
       ``,
       `const cogitator = new Cogitator({`,
-      providerConfig(options.provider),
+      providerConfig(options.provider, "requireEnv"),
       `  memory: {`,
       `    adapter: 'redis',`,
       `    redis: { url: process.env.REDIS_URL || 'redis://localhost:6379' },`,
@@ -192,8 +282,8 @@ var memoryTemplate = {
       `})`,
       ``,
       `const agent = new Agent({`,
-      `  name: '${options.name}-agent',`,
-      `  model: '${model}',`,
+      `  name: ${tsString(`${options.name}-agent`)},`,
+      `  model: ${tsString(model)},`,
       `  instructions: [`,
       `    'You are an AI assistant with persistent memory.',`,
       `    'You remember past conversations and user preferences.',`,
@@ -206,25 +296,26 @@ var memoryTemplate = {
       `async function main() {`,
       `  const threadId = 'demo-thread'`,
       ``,
-      `  const result1 = await cogitator.run(agent, {`,
-      `    input: 'My name is Alex and I prefer TypeScript.',`,
-      `    threadId,`,
-      `    useMemory: true,`,
-      `  })`,
-      `  console.log('Response 1:', result1.output)`,
-      ``,
-      `  const result2 = await cogitator.run(agent, {`,
-      `    input: 'What is my name and preferred language?',`,
-      `    threadId,`,
-      `    useMemory: true,`,
-      `  })`,
-      `  console.log('Response 2:', result2.output)`,
-      ``,
-      `  await cogitator.close()`,
+      `  try {`,
+      `    const result1 = await cogitator.run(agent, {`,
+      `      input: 'My name is Alex and I prefer TypeScript.',`,
+      `      threadId,`,
+      `      useMemory: true,`,
+      `    })`,
+      `    console.log('Response 1:', result1.output)`,
+      ``,
+      `    const result2 = await cogitator.run(agent, {`,
+      `      input: 'What is my name and preferred language?',`,
+      `      threadId,`,
+      `      useMemory: true,`,
+      `    })`,
+      `    console.log('Response 2:', result2.output)`,
+      `  } finally {`,
+      `    await cogitator.close()`,
+      `  }`,
       `}`,
       ``,
-      `main().catch(console.error)`,
-      ``
+      ...RUN_MAIN
     ].join("\n");
     const toolsTs = [
       `import { tool } from '@cogitator-ai/core'`,
@@ -256,45 +347,38 @@ var memoryTemplate = {
     ].join("\n");
     return [
       { path: "src/index.ts", content: indexTs },
-      { path: "src/tools.ts", content: toolsTs }
+      { path: "src/tools.ts", content: toolsTs },
+      ...envHelperFiles(options.provider)
     ];
   },
   dependencies() {
     return {
-      "@cogitator-ai/core": "latest",
-      "@cogitator-ai/memory": "latest",
-      "@cogitator-ai/redis": "latest",
+      "@cogitator-ai/core": cogitatorVersion("@cogitator-ai/core"),
+      "@cogitator-ai/memory": cogitatorVersion("@cogitator-ai/memory"),
+      "@cogitator-ai/redis": cogitatorVersion("@cogitator-ai/redis"),
+      ioredis: IOREDIS_VERSION,
       zod: ZOD_VERSION
     };
   },
   devDependencies() {
-    return {
-      typescript: "^5.8.0",
-      tsx: "^4.19.0",
-      "@types/node": "^22.0.0"
-    };
+    return scriptTemplateDevDependencies();
   },
   scripts() {
-    return {
-      dev: "tsx watch src/index.ts",
-      start: "tsx src/index.ts",
-      build: "tsc",
-      typecheck: "tsc --noEmit"
-    };
+    return scriptTemplateScripts();
   }
 };
 
 // src/templates/swarm.ts
 var swarmTemplate = {
   files(options) {
-    const model = defaultModels[options.provider];
+    const model = modelFor(options);
     const researcherTs = [
       `import { Agent } from '@cogitator-ai/core'`,
       `import { searchTool } from '../tools.js'`,
       ``,
       `export const researcher = new Agent({`,
       `  name: 'researcher',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: [`,
       `    'You are a research specialist.',`,
       `    'Use the search tool to find information.',`,
@@ -310,7 +394,7 @@ var swarmTemplate = {
       ``,
       `export const writer = new Agent({`,
       `  name: 'writer',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: [`,
       `    'You are a skilled content writer.',`,
       `    'Take research findings and craft well-structured, engaging content.',`,
@@ -325,7 +409,7 @@ var swarmTemplate = {
       ``,
       `export const reviewer = new Agent({`,
       `  name: 'reviewer',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: [`,
       `    'You are a meticulous content reviewer.',`,
       `    'Check for accuracy, grammar, and overall quality.',`,
@@ -357,13 +441,14 @@ var swarmTemplate = {
       `import { researcher } from './agents/researcher.js'`,
       `import { writer } from './agents/writer.js'`,
       `import { reviewer } from './agents/reviewer.js'`,
+      ...envHelperImport(options.provider),
       ``,
       `const cogitator = new Cogitator({`,
-      providerConfig(options.provider),
+      providerConfig(options.provider, "requireEnv"),
       `})`,
       ``,
       `const team = new Swarm(cogitator, {`,
-      `  name: '${options.name}-team',`,
+      `  name: ${tsString(`${options.name}-team`)},`,
       `  strategy: 'hierarchical',`,
       `  supervisor: reviewer,`,
       `  workers: [researcher, writer],`,
@@ -380,75 +465,68 @@ var swarmTemplate = {
       `async function main() {`,
       `  console.log('Starting swarm...')`,
       ``,
-      `  const result = await team.run({`,
-      `    input: 'Write a comprehensive article about AI agent orchestration.',`,
-      `  })`,
+      `  try {`,
+      `    const result = await team.run({`,
+      `      input: 'Write a comprehensive article about AI agent orchestration.',`,
+      `    })`,
       ``,
-      `  console.log('Result:', result.output)`,
-      `  console.log('Strategy:', team.strategyType)`,
-      ``,
-      `  await team.close()`,
+      `    console.log('Result:', result.output)`,
+      `    console.log('Strategy:', team.strategyType)`,
+      `  } finally {`,
+      `    await team.close()`,
+      `  }`,
       `}`,
       ``,
-      `main().catch(console.error)`,
-      ``
+      ...RUN_MAIN
     ].join("\n");
     return [
       { path: "src/index.ts", content: indexTs },
       { path: "src/tools.ts", content: toolsTs },
       { path: "src/agents/researcher.ts", content: researcherTs },
       { path: "src/agents/writer.ts", content: writerTs },
-      { path: "src/agents/reviewer.ts", content: reviewerTs }
+      { path: "src/agents/reviewer.ts", content: reviewerTs },
+      ...envHelperFiles(options.provider)
     ];
   },
   dependencies() {
     return {
-      "@cogitator-ai/core": "latest",
-      "@cogitator-ai/swarms": "latest",
+      "@cogitator-ai/core": cogitatorVersion("@cogitator-ai/core"),
+      "@cogitator-ai/swarms": cogitatorVersion("@cogitator-ai/swarms"),
       zod: ZOD_VERSION
     };
   },
   devDependencies() {
-    return {
-      typescript: "^5.8.0",
-      tsx: "^4.19.0",
-      "@types/node": "^22.0.0"
-    };
+    return scriptTemplateDevDependencies();
   },
   scripts() {
-    return {
-      dev: "tsx watch src/index.ts",
-      start: "tsx src/index.ts",
-      build: "tsc",
-      typecheck: "tsc --noEmit"
-    };
+    return scriptTemplateScripts();
   }
 };
 
 // src/templates/workflow.ts
 var workflowTemplate = {
   files(options) {
-    const model = defaultModels[options.provider];
+    const model = modelFor(options);
     const agentsTs = [
       `import { Agent } from '@cogitator-ai/core'`,
       ``,
       `export const analyzer = new Agent({`,
       `  name: 'analyzer',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: 'You analyze input data and extract key information. Be thorough and structured.',`,
       `  temperature: 0.3,`,
       `})`,
       ``,
       `export const processor = new Agent({`,
       `  name: 'processor',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: 'You process analyzed data and transform it into actionable insights.',`,
       `  temperature: 0.5,`,
       `})`,
       ``,
       `export const formatter = new Agent({`,
       `  name: 'formatter',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: 'You format processed data into a clean, readable report.',`,
       `  temperature: 0.7,`,
       `})`,
@@ -463,9 +541,10 @@ var workflowTemplate = {
       `  functionNode,`,
       `} from '@cogitator-ai/workflows'`,
       `import { analyzer, processor, formatter } from './agents.js'`,
+      ...envHelperImport(options.provider),
       ``,
       `const cogitator = new Cogitator({`,
-      providerConfig(options.provider),
+      providerConfig(options.provider, "requireEnv"),
       `})`,
       ``,
       `type WorkflowState = {`,
@@ -495,7 +574,7 @@ var workflowTemplate = {
       `  async (state) => state.report,`,
       `)`,
       ``,
-      `const workflow = new WorkflowBuilder<WorkflowState>('${options.name}-workflow')`,
+      `const workflow = new WorkflowBuilder<WorkflowState>(${tsString(`${options.name}-workflow`)})`,
       `  .initialState({ input: '' })`,
       `  .entryPoint(analyzeNode.name)`,
       `  .addNode(analyzeNode.name, analyzeNode.fn)`,
@@ -513,48 +592,45 @@ var workflowTemplate = {
       `    input: 'Analyze the current state of AI agent frameworks and their adoption in enterprise.',`,
       `  })`,
       ``,
-      `  console.log('Workflow completed!')`,
-      `  console.log('Result:', JSON.stringify(result, null, 2))`,
+      `  if (result.error) throw result.error`,
+      ``,
+      `  console.log(\`Workflow completed in \${result.duration}ms\`)`,
+      `  console.log('Report:', result.state.report)`,
+      `  console.log('Nodes:', JSON.stringify(Object.fromEntries(result.nodeResults), null, 2))`,
       `}`,
       ``,
-      `main().catch(console.error)`,
-      ``
+      ...RUN_MAIN
     ].join("\n");
     return [
       { path: "src/index.ts", content: indexTs },
-      { path: "src/agents.ts", content: agentsTs }
+      { path: "src/agents.ts", content: agentsTs },
+      ...envHelperFiles(options.provider)
     ];
   },
   dependencies() {
     return {
-      "@cogitator-ai/core": "latest",
-      "@cogitator-ai/workflows": "latest",
+      "@cogitator-ai/core": cogitatorVersion("@cogitator-ai/core"),
+      "@cogitator-ai/workflows": cogitatorVersion("@cogitator-ai/workflows"),
       zod: ZOD_VERSION
     };
   },
   devDependencies() {
-    return {
-      typescript: "^5.8.0",
-      tsx: "^4.19.0",
-      "@types/node": "^22.0.0"
-    };
+    return scriptTemplateDevDependencies();
   },
   scripts() {
-    return {
-      dev: "tsx watch src/index.ts",
-      start: "tsx src/index.ts",
-      build: "tsc",
-      typecheck: "tsc --noEmit"
-    };
+    return scriptTemplateScripts();
   }
 };
 
 // src/templates/api-server.ts
 var BASE_PATH = "/api";
+var PUBLIC_PATHS = ["/health", "/ready", "/docs", "/openapi.json"];
 var apiServerTemplate = {
+  memoryAdapter: "memory",
+  secrets: ["API_TOKEN"],
   healthPath: `${BASE_PATH}/health`,
   files(options) {
-    const model = defaultModels[options.provider];
+    const model = modelFor(options);
     const agentsTs = [
       `import { Agent, tool } from '@cogitator-ai/core'`,
       `import { z } from 'zod'`,
@@ -572,7 +648,7 @@ var apiServerTemplate = {
       ``,
       `export const assistant = new Agent({`,
       `  name: 'assistant',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: 'You are a helpful API assistant. Answer questions clearly and concisely.',`,
       `  tools: [searchTool],`,
       `  temperature: 0.7,`,
@@ -580,23 +656,45 @@ var apiServerTemplate = {
       ``,
       `export const coder = new Agent({`,
       `  name: 'coder',`,
-      `  model: '${model}',`,
+      `  model: ${tsString(model)},`,
       `  instructions: 'You are an expert programmer. Write clean, well-structured code.',`,
       `  temperature: 0.3,`,
       `})`,
       ``
     ].join("\n");
     const indexTs = [
-      `import express from 'express'`,
+      `import { timingSafeEqual } from 'node:crypto'`,
+      `import express, { type Request } from 'express'`,
       `import { Cogitator } from '@cogitator-ai/core'`,
       `import { CogitatorServer } from '@cogitator-ai/express'`,
       `import { assistant, coder } from './agents.js'`,
+      ...envHelperImport(options.provider),
+      ``,
+      `const production = process.env.NODE_ENV === 'production'`,
+      `const port = Number(process.env.PORT ?? 3000)`,
+      `const host = process.env.HOST ?? (production ? '0.0.0.0' : '127.0.0.1')`,
+      `const apiToken = process.env.API_TOKEN`,
+      `const corsOrigin = process.env.CORS_ORIGIN`,
+      `const publicPaths = new Set([${PUBLIC_PATHS.map(tsString).join(", ")}])`,
+      ``,
+      `function hasToken(header: string | undefined): boolean {`,
+      `  if (!apiToken || !header) return false`,
+      `  const expected = Buffer.from(\`Bearer \${apiToken}\`)`,
+      `  const given = Buffer.from(header)`,
+      `  return given.length === expected.length && timingSafeEqual(given, expected)`,
+      `}`,
+      ``,
+      `function authenticate(req: Request) {`,
+      `  if (!apiToken || publicPaths.has(req.path)) return undefined`,
+      `  if (!hasToken(req.get('authorization'))) throw new Error('Unauthorized')`,
+      `  return { userId: 'api-token' }`,
+      `}`,
       ``,
       `const app = express()`,
-      `const port = process.env.PORT || 3000`,
       ``,
       `const cogitator = new Cogitator({`,
-      providerConfig(options.provider),
+      providerConfig(options.provider, "requireEnv"),
+      `  memory: { adapter: 'memory' },`,
       `})`,
       ``,
       `const server = new CogitatorServer({`,
@@ -606,62 +704,62 @@ var apiServerTemplate = {
       `  config: {`,
       `    basePath: '${BASE_PATH}',`,
       `    enableSwagger: true,`,
-      `    cors: { origin: '*' },`,
+      `    auth: authenticate,`,
+      `    ...(corsOrigin ? { cors: { origin: corsOrigin.split(',').map((o) => o.trim()) } } : {}),`,
       `    swagger: {`,
-      `      title: '${options.name} API',`,
+      `      title: ${tsString(`${options.name} API`)},`,
       `      version: '1.0.0',`,
       `    },`,
       `  },`,
       `})`,
       ``,
       `async function main() {`,
+      `  if (production && !apiToken) {`,
+      `    throw new Error('Set API_TOKEN in production: it guards every route except health and docs')`,
+      `  }`,
+      ``,
       `  await server.init()`,
       ``,
-      `  app.listen(port, () => {`,
-      `    console.log(\`Server running at http://localhost:\${port}\`)`,
-      `    console.log(\`Swagger docs at http://localhost:\${port}${BASE_PATH}/docs\`)`,
+      `  app.listen(port, host, () => {`,
+      `    console.log(\`Server running at http://\${host}:\${port}\`)`,
+      `    console.log(\`Swagger docs at http://\${host}:\${port}${BASE_PATH}/docs\`)`,
+      `    if (!apiToken) console.log('API_TOKEN is not set, so the API is open to anyone who can reach it')`,
       `  })`,
       `}`,
       ``,
-      `main().catch(console.error)`,
-      ``
+      ...RUN_MAIN
     ].join("\n");
     return [
       { path: "src/index.ts", content: indexTs },
-      { path: "src/agents.ts", content: agentsTs }
+      { path: "src/agents.ts", content: agentsTs },
+      ...envHelperFiles(options.provider)
     ];
   },
   dependencies() {
     return {
-      "@cogitator-ai/core": "latest",
-      "@cogitator-ai/express": "latest",
+      "@cogitator-ai/core": cogitatorVersion("@cogitator-ai/core"),
+      "@cogitator-ai/express": cogitatorVersion("@cogitator-ai/express"),
       express: "^5.2.1",
       zod: ZOD_VERSION
     };
   },
   devDependencies() {
     return {
-      typescript: "^5.8.0",
-      tsx: "^4.19.0",
-      "@types/node": "^22.0.0",
+      ...scriptTemplateDevDependencies(),
       "@types/express": "^5.0.6"
     };
   },
   scripts() {
-    return {
-      dev: "tsx watch src/index.ts",
-      start: "tsx src/index.ts",
-      build: "tsc",
-      typecheck: "tsc --noEmit"
-    };
+    return scriptTemplateScripts();
   }
 };
 
 // src/templates/nextjs.ts
 var nextjsTemplate = {
+  memoryAdapter: "memory",
   healthPath: "/api/health",
   files(options) {
-    const model = defaultModels[options.provider];
+    const model = modelFor(options);
     const agentTs = [
       `import { Cogitator, Agent, tool } from '@cogitator-ai/core'`,
       `import { z } from 'zod'`,
@@ -679,11 +777,12 @@ var nextjsTemplate = {
       ``,
       `export const cogitator = new Cogitator({`,
       providerConfig(options.provider),
+      `  memory: { adapter: 'memory' },`,
       `})`,
       ``,
       `export const agent = new Agent({`,
-      `  name: '${options.name}-chat',`,
-      `  model: '${model}',`,
+      `  name: ${tsString(`${options.name}-chat`)},`,
+      `  model: ${tsString(model)},`,
       `  instructions: 'You are a helpful AI chat assistant. Be conversational and helpful.',`,
       `  tools: [searchTool],`,
       `  temperature: 0.7,`,
@@ -710,7 +809,7 @@ var nextjsTemplate = {
       `import { useState, useRef, useEffect } from 'react'`,
       ``,
       `export default function Home() {`,
-      `  const { messages, input, setInput, send, isLoading } = useCogitatorChat({`,
+      `  const { messages, input, setInput, send, stop, isLoading, error } = useCogitatorChat({`,
       `    api: '/api/chat',`,
       `  })`,
       `  const messagesEndRef = useRef<HTMLDivElement>(null)`,
@@ -730,27 +829,29 @@ var nextjsTemplate = {
       `    <main className="flex min-h-screen flex-col items-center p-4 bg-gray-950 text-white">`,
       `      <div className="w-full max-w-2xl flex flex-col h-screen">`,
       `        <header className="py-6 text-center">`,
-      `          <h1 className="text-2xl font-bold">${options.name}</h1>`,
+      `          <h1 className="text-2xl font-bold">{${tsString(options.name)}}</h1>`,
       `          <p className="text-gray-400 text-sm mt-1">Powered by Cogitator</p>`,
       `        </header>`,
       ``,
       `        <div className="flex-1 overflow-y-auto space-y-4 pb-4">`,
-      `          {messages.map((msg, i) => (`,
-      `            <div`,
-      `              key={i}`,
-      `              className={\`flex \${msg.role === 'user' ? 'justify-end' : 'justify-start'}\`}`,
-      `            >`,
+      `          {messages`,
+      `            .filter((msg) => msg.content)`,
+      `            .map((msg) => (`,
       `              <div`,
-      `                className={\`max-w-[80%] rounded-2xl px-4 py-2 \${`,
-      `                  msg.role === 'user'`,
-      `                    ? 'bg-blue-600 text-white'`,
-      `                    : 'bg-gray-800 text-gray-100'`,
-      `                }\`}`,
+      `                key={msg.id}`,
+      `                className={\`flex \${msg.role === 'user' ? 'justify-end' : 'justify-start'}\`}`,
       `              >`,
-      `                {msg.content}`,
+      `                <div`,
+      `                  className={\`max-w-[80%] rounded-2xl px-4 py-2 \${`,
+      `                    msg.role === 'user'`,
+      `                      ? 'bg-blue-600 text-white'`,
+      `                      : 'bg-gray-800 text-gray-100'`,
+      `                  }\`}`,
+      `                >`,
+      `                  {msg.content}`,
+      `                </div>`,
       `              </div>`,
-      `            </div>`,
-      `          ))}`,
+      `            ))}`,
       `          {isLoading && (`,
       `            <div className="flex justify-start">`,
       `              <div className="bg-gray-800 rounded-2xl px-4 py-2 text-gray-400">`,
@@ -758,6 +859,11 @@ var nextjsTemplate = {
       `              </div>`,
       `            </div>`,
       `          )}`,
+      `          {error && (`,
+      `            <div className="rounded-xl border border-red-800 bg-red-950 px-4 py-2 text-sm text-red-200">`,
+      `              {error.message}`,
+      `            </div>`,
+      `          )}`,
       `          <div ref={messagesEndRef} />`,
       `        </div>`,
       ``,
@@ -768,13 +874,23 @@ var nextjsTemplate = {
       `            placeholder="Type a message..."`,
       `            className="flex-1 bg-gray-800 border border-gray-700 rounded-xl px-4 py-3 text-white placeholder-gray-500 focus:outline-none focus:border-blue-500"`,
       `          />`,
-      `          <button`,
-      `            type="submit"`,
-      `            disabled={isLoading || !input.trim()}`,
-      `            className="bg-blue-600 hover:bg-blue-500 disabled:opacity-50 disabled:cursor-not-allowed text-white rounded-xl px-6 py-3 font-medium transition-colors"`,
-      `          >`,
-      `            Send`,
-      `          </button>`,
+      `          {isLoading ? (`,
+      `            <button`,
+      `              type="button"`,
+      `              onClick={stop}`,
+      `              className="bg-gray-700 hover:bg-gray-600 text-white rounded-xl px-6 py-3 font-medium transition-colors"`,
+      `            >`,
+      `              Stop`,
+      `            </button>`,
+      `          ) : (`,
+      `            <button`,
+      `              type="submit"`,
+      `              disabled={!input.trim()}`,
+      `              className="bg-blue-600 hover:bg-blue-500 disabled:opacity-50 disabled:cursor-not-allowed text-white rounded-xl px-6 py-3 font-medium transition-colors"`,
+      `            >`,
+      `              Send`,
+      `            </button>`,
+      `          )}`,
       `        </form>`,
       `      </div>`,
       `    </main>`,
@@ -787,7 +903,7 @@ var nextjsTemplate = {
       `import './globals.css'`,
       ``,
       `export const metadata: Metadata = {`,
-      `  title: '${options.name}',`,
+      `  title: ${tsString(options.name)},`,
       `  description: 'AI chat app powered by Cogitator',`,
       `}`,
       ``,
@@ -881,8 +997,8 @@ var nextjsTemplate = {
   },
   dependencies() {
     return {
-      "@cogitator-ai/core": "latest",
-      "@cogitator-ai/next": "latest",
+      "@cogitator-ai/core": cogitatorVersion("@cogitator-ai/core"),
+      "@cogitator-ai/next": cogitatorVersion("@cogitator-ai/next"),
       next: "^15.0.0",
       react: "^19.0.0",
       "react-dom": "^19.0.0",
@@ -905,7 +1021,7 @@ var nextjsTemplate = {
       dev: "next dev",
       build: "next build",
       start: "next start",
-      lint: "next lint"
+      typecheck: "tsc --noEmit"
     };
   }
 };
@@ -946,12 +1062,8 @@ var templateChoices = [
 // src/utils/package-manager.ts
 import { execSync } from "child_process";
 function detectPackageManager() {
-  const ua = process.env.npm_config_user_agent;
-  if (ua) {
-    if (ua.startsWith("pnpm")) return "pnpm";
-    if (ua.startsWith("yarn")) return "yarn";
-    if (ua.startsWith("bun")) return "bun";
-  }
+  const name = process.env.npm_config_user_agent?.split("/")[0];
+  if (name === "npm" || name === "pnpm" || name === "yarn" || name === "bun") return name;
   return "pnpm";
 }
 function installDependencies(cwd, pm) {
@@ -962,6 +1074,112 @@ function devCommand(pm) {
   return `${pm} dev`;
 }
 
+// src/utils/project-name.ts
+import path2 from "path";
+var PACKAGE_NAME = /^[a-z0-9][a-z0-9._-]*$/;
+var MAX_LENGTH = 214;
+function validateProjectName(name) {
+  const trimmed = name.trim();
+  if (!trimmed) return "Project name is required";
+  if (trimmed.length > MAX_LENGTH) return `Use at most ${MAX_LENGTH} characters`;
+  if (!PACKAGE_NAME.test(trimmed)) {
+    return 'Use lowercase letters, digits, ".", "_" or "-", starting with a letter or digit';
+  }
+  return void 0;
+}
+function projectNameFromDirectory(dir, cwd = process.cwd()) {
+  return path2.basename(path2.resolve(cwd, dir.trim()));
+}
+
+// src/utils/ollama.ts
+var DEFAULT_OLLAMA_URL = "http://localhost:11434";
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value[end - 1] === "/") end--;
+  return value.slice(0, end);
+}
+function resolveOllamaUrl(env = process.env) {
+  const raw = env.OLLAMA_BASE_URL?.trim() || env.OLLAMA_HOST?.trim();
+  if (!raw) return DEFAULT_OLLAMA_URL;
+  const withScheme = /^https?:\/\//i.test(raw) ? raw : `http://${raw}`;
+  return trimTrailingSlashes(withScheme);
+}
+async function listOllamaModels(baseUrl, timeoutMs = 2e3) {
+  try {
+    const res = await fetch(`${baseUrl}/api/tags`, { signal: AbortSignal.timeout(timeoutMs) });
+    if (!res.ok) return void 0;
+    const data = await res.json();
+    if (!isRecord2(data) || !Array.isArray(data.models)) return void 0;
+    return data.models.flatMap(
+      (model) => isRecord2(model) && typeof model.name === "string" ? [{ name: model.name, size: typeof model.size === "number" ? model.size : 0 }] : []
+    );
+  } catch {
+    return void 0;
+  }
+}
+function withTag(name) {
+  return name.includes(":") ? name : `${name}:latest`;
+}
+function hasOllamaModel(installed, model) {
+  const wanted = withTag(model);
+  return installed.some((m) => withTag(m.name) === wanted);
+}
+function describeProgress(event, status) {
+  const { completed, total } = event;
+  if (typeof completed === "number" && typeof total === "number" && total > 0) {
+    return `${status} ${Math.floor(completed / total * 100)}%`;
+  }
+  return status;
+}
+async function* ndjson(stream) {
+  const reader = stream.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let newline = buffer.indexOf("\n");
+      while (newline >= 0) {
+        const line = buffer.slice(0, newline).trim();
+        buffer = buffer.slice(newline + 1);
+        if (line) yield JSON.parse(line);
+        newline = buffer.indexOf("\n");
+      }
+    }
+    const rest = (buffer + decoder.decode()).trim();
+    if (rest) yield JSON.parse(rest);
+  } finally {
+    reader.releaseLock();
+  }
+}
+async function pullOllamaModel(baseUrl, model, onStatus) {
+  const res = await fetch(`${baseUrl}/api/pull`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ model, stream: true })
+  });
+  if (!res.ok || !res.body) {
+    const detail = await res.text().catch(() => "");
+    throw new Error(`Failed to pull ${model}: HTTP ${res.status}${detail ? ` ${detail}` : ""}`);
+  }
+  let succeeded = false;
+  for await (const event of ndjson(res.body)) {
+    if (!isRecord2(event)) continue;
+    if (typeof event.error === "string") throw new Error(`Failed to pull ${model}: ${event.error}`);
+    if (typeof event.status !== "string") continue;
+    if (event.status === "success") succeeded = true;
+    onStatus(describeProgress(event, event.status));
+  }
+  if (!succeeded) {
+    throw new Error(`Failed to pull ${model}: the download stopped before it finished`);
+  }
+}
+
 // src/prompts.ts
 var validTemplates = ["basic", "memory", "swarm", "workflow", "api-server", "nextjs"];
 var validProviders = ["ollama", "openai", "anthropic", "google"];
@@ -980,6 +1198,12 @@ function parseArgs(args) {
         const val = args[++i];
         if (validProviders.includes(val)) parsed.provider = val;
       }
+    } else if (arg === "--model") {
+      const val = args[i + 1];
+      if (val !== void 0 && !val.startsWith("-")) {
+        parsed.model = val;
+        i++;
+      }
     } else if (arg === "--pm") {
       if (i + 1 < args.length) {
         const val = args[++i];
@@ -1019,22 +1243,54 @@ function unlessCancelled(answer) {
   }
   return answer;
 }
+function validateDirectory(value) {
+  if (!value) return void 0;
+  if (!value.trim()) return "Project name is required";
+  return validateProjectName(projectNameFromDirectory(value));
+}
+function formatSize(bytes) {
+  return bytes > 0 ? `${(bytes / 1e9).toFixed(1)} GB` : void 0;
+}
+async function promptOllamaModel() {
+  const installed = await listOllamaModels(resolveOllamaUrl());
+  if (!installed) return void 0;
+  const recommended = defaultModels.ollama;
+  const others = installed.filter((model) => !hasOllamaModel([model], recommended));
+  return unlessCancelled(
+    await p.select({
+      message: "Which Ollama model?",
+      options: [
+        {
+          value: recommended,
+          label: recommended,
+          hint: hasOllamaModel(installed, recommended) ? "recommended, installed" : "recommended, not installed yet"
+        },
+        ...others.map((model) => ({
+          value: model.name,
+          label: model.name,
+          hint: formatSize(model.size)
+        }))
+      ],
+      initialValue: recommended
+    })
+  );
+}
 async function collectOptions(args) {
   const interactive = !args.yes;
-  const rawName = args.name || (interactive ? unlessCancelled(
+  const directory = (args.name || (interactive ? unlessCancelled(
     await p.text({
       message: "Where should we create your project?",
       placeholder: `./${defaultAnswers.name}`,
       defaultValue: defaultAnswers.name,
-      validate: (value) => {
-        if (value && !value.trim()) return "Project name is required";
-        return void 0;
-      }
+      validate: validateDirectory
     })
-  ) : defaultAnswers.name);
-  const name = rawName.trim();
-  const projectName = path.basename(path.normalize(name).replace(/^\.\//, "").replace(/^\.\\/, ""));
-  const projectPath = path.resolve(process.cwd(), name);
+  ) : defaultAnswers.name)).trim();
+  const projectPath = path3.resolve(process.cwd(), directory);
+  const projectName = projectNameFromDirectory(directory);
+  const nameError = validateProjectName(projectName);
+  if (nameError) {
+    throw new Error(`Invalid project name "${projectName}": ${nameError}`);
+  }
   const template = args.template ?? (interactive ? unlessCancelled(
     await p.select({
       message: "Which template would you like?",
@@ -1049,7 +1305,7 @@ async function collectOptions(args) {
         {
           value: "ollama",
           label: "Ollama",
-          hint: `${defaultModels.ollama} \u2014 local, free, requires Ollama installed`
+          hint: `${defaultModels.ollama}, local, free, requires Ollama installed`
         },
         { value: "openai", label: "OpenAI", hint: defaultModels.openai },
         { value: "anthropic", label: "Anthropic", hint: defaultModels.anthropic },
@@ -1058,6 +1314,7 @@ async function collectOptions(args) {
       initialValue: defaultAnswers.provider
     })
   ) : defaultAnswers.provider);
+  const model = args.model ?? (interactive && provider === "ollama" ? await promptOllamaModel() : void 0);
   const packageManager = args.packageManager ?? (interactive ? unlessCancelled(
     await p.select({
       message: "Package manager?",
@@ -1087,6 +1344,7 @@ async function collectOptions(args) {
     path: projectPath,
     template,
     provider,
+    ...model !== void 0 && { model },
     packageManager,
     docker,
     git,
@@ -1096,7 +1354,7 @@ async function collectOptions(args) {
 
 // src/scaffold.ts
 import fs from "fs";
-import path2 from "path";
+import path4 from "path";
 import * as p2 from "@clack/prompts";
 
 // src/templates/base/tsconfig.ts
@@ -1127,15 +1385,19 @@ function generateTsconfig() {
 }
 
 // src/templates/base/gitignore.ts
-function generateGitignore() {
+var NEXT_OUTPUT = [".next/", "out/", "next-env.d.ts"];
+function generateGitignore(template) {
   return {
     path: ".gitignore",
     content: [
       "node_modules/",
       "dist/",
+      ...template === "nextjs" ? NEXT_OUTPUT : [],
       ".env",
-      ".env.local",
+      ".env.*",
+      "!.env.example",
       "*.log",
+      "*.tsbuildinfo",
       ".DS_Store",
       "coverage/",
       ".turbo/",
@@ -1153,16 +1415,16 @@ function generateEnvExample(provider, template) {
       lines.push("# OLLAMA_BASE_URL=http://localhost:11434");
       break;
     case "openai":
-      lines.push("# OpenAI");
-      lines.push("OPENAI_API_KEY=sk-...");
+      lines.push("# OpenAI, https://platform.openai.com/api-keys");
+      lines.push("OPENAI_API_KEY=");
       break;
     case "anthropic":
-      lines.push("# Anthropic");
-      lines.push("ANTHROPIC_API_KEY=sk-ant-...");
+      lines.push("# Anthropic, https://console.anthropic.com/settings/keys");
+      lines.push("ANTHROPIC_API_KEY=");
       break;
     case "google":
-      lines.push("# Google AI");
-      lines.push("GOOGLE_API_KEY=...");
+      lines.push("# Google AI, https://aistudio.google.com/apikey");
+      lines.push("GOOGLE_API_KEY=");
       break;
   }
   if (template === "memory") {
@@ -1170,25 +1432,54 @@ function generateEnvExample(provider, template) {
     lines.push("# Redis");
     lines.push("REDIS_URL=redis://localhost:6379");
   }
+  if (template === "api-server") {
+    lines.push("");
+    lines.push("# Bearer token that every API route except health and docs requires.");
+    lines.push("# Optional in development, where the server listens on 127.0.0.1 only,");
+    lines.push("# required in production (NODE_ENV=production), where it listens on 0.0.0.0.");
+    lines.push("API_TOKEN=");
+    lines.push("");
+    lines.push("# Comma-separated browser origins allowed to call the API, CORS is off without it");
+    lines.push("# CORS_ORIGIN=http://localhost:5173");
+    lines.push("");
+    lines.push("# HOST=127.0.0.1");
+    lines.push("# PORT=3000");
+  }
   lines.push("");
   return { path: ".env.example", content: lines.join("\n") };
 }
 
 // src/templates/base/docker-compose.ts
-function generateDockerCompose(provider) {
+function ollamaServices(model) {
+  return [
+    "  ollama:",
+    "    image: ollama/ollama:latest",
+    "    ports:",
+    '      - "11434:11434"',
+    "    volumes:",
+    "      - ollama_data:/root/.ollama",
+    "    healthcheck:",
+    '      test: ["CMD", "ollama", "list"]',
+    "      interval: 5s",
+    "      timeout: 5s",
+    "      retries: 20",
+    "",
+    "  ollama-pull:",
+    "    image: ollama/ollama:latest",
+    "    depends_on:",
+    "      ollama:",
+    "        condition: service_healthy",
+    "    environment:",
+    "      OLLAMA_HOST: http://ollama:11434",
+    `    entrypoint: ["ollama", "pull", ${JSON.stringify(model)}]`,
+    '    restart: "no"',
+    ""
+  ];
+}
+function generateDockerCompose(provider, model = defaultModels[provider]) {
   const services = [];
   if (provider === "ollama") {
-    services.push(
-      ...[
-        "  ollama:",
-        "    image: ollama/ollama:latest",
-        "    ports:",
-        '      - "11434:11434"',
-        "    volumes:",
-        "      - ollama_data:/root/.ollama",
-        ""
-      ]
-    );
+    services.push(...ollamaServices(model));
   }
   services.push(
     ...[
@@ -1219,12 +1510,15 @@ function generateDockerCompose(provider) {
 }
 
 // src/templates/base/cogitator-yml.ts
-function generateCogitatorYml(provider, template) {
-  const lines = [
-    "llm:",
-    `  defaultProvider: ${provider}`,
-    `  defaultModel: ${defaultModels[provider]}`
-  ];
+var HEADER = [
+  "# Read by `cogitator run` and `cogitator deploy`: the provider and model, the",
+  "# memory to provision and the deploy settings. The code in src/ configures",
+  "# Cogitator itself, so change the provider, model or memory in both places.",
+  ""
+];
+function generateCogitatorYml(provider, template, model = defaultModels[provider]) {
+  const generator = template ? getTemplate(template) : void 0;
+  const lines = [...HEADER, "llm:", `  defaultProvider: ${provider}`, `  defaultModel: ${model}`];
   if (provider === "ollama") {
     lines.push(
       "  providers:",
@@ -1232,7 +1526,7 @@ function generateCogitatorYml(provider, template) {
       "      baseUrl: ${OLLAMA_BASE_URL:-http://localhost:11434}"
     );
   }
-  if (template === "memory") {
+  if (generator?.memoryAdapter === "redis") {
     lines.push(
       "",
       "memory:",
@@ -1240,15 +1534,56 @@ function generateCogitatorYml(provider, template) {
       "  redis:",
       "    url: ${REDIS_URL:-redis://localhost:6379}"
     );
+  } else if (generator?.memoryAdapter === "memory") {
+    lines.push("", "memory:", "  adapter: memory");
+  }
+  const deploy = [];
+  if (generator?.healthPath) {
+    deploy.push("  health:", `    path: ${generator.healthPath}`);
+  }
+  if (generator?.secrets?.length) {
+    const secrets = [
+      ...provider === "ollama" ? [] : [providerEnvKey(provider)],
+      ...generator.secrets
+    ];
+    deploy.push("  secrets:", ...secrets.map((name) => `    - ${name}`));
   }
-  const healthPath = template ? getTemplate(template).healthPath : void 0;
-  if (healthPath) {
-    lines.push("", "deploy:", "  health:", `    path: ${healthPath}`);
+  if (deploy.length > 0) {
+    lines.push("", "deploy:", ...deploy);
   }
   lines.push("");
   return { path: "cogitator.yml", content: lines.join("\n") };
 }
 
+// src/next-steps.ts
+function nextSteps(options, state) {
+  const steps = [];
+  if (state.directory) {
+    const dir = /^[\w./-]+$/.test(state.directory) ? state.directory : JSON.stringify(state.directory);
+    steps.push({ command: `cd ${dir}` });
+  }
+  if (!state.installed) {
+    steps.push({ command: `${options.packageManager} install` });
+  }
+  if (options.provider !== "ollama") {
+    steps.push({
+      command: "cp .env.example .env",
+      note: `then set ${providerEnvKey(options.provider)} in .env`
+    });
+  }
+  if (options.provider === "ollama" && !state.modelReady) {
+    steps.push({
+      command: `ollama pull ${modelFor(options)}`,
+      note: options.docker ? "download the model the agents use, or let `docker compose up -d` pull it into the Ollama container" : "download the model the agents use"
+    });
+  }
+  if (options.template === "memory" && options.docker) {
+    steps.push({ command: "docker compose up -d redis", note: "the memory lives in Redis" });
+  }
+  steps.push({ command: devCommand(options.packageManager) });
+  return steps;
+}
+
 // src/utils/links.ts
 var DOCS_URL = "https://cogitator.app/docs";
 var REPO_URL = "https://github.com/cogitator-ai/Cogitator-AI";
@@ -1263,24 +1598,33 @@ var templateNames = {
   nextjs: "Next.js Chat App"
 };
 function generateReadme(options) {
-  const dev = devCommand(options.packageManager);
   const templateName = templateNames[options.template] || options.template;
+  const steps = nextSteps(options, { installed: false, modelReady: false });
   const content = [
     `# ${options.name}`,
     "",
-    `> Created with [create-cogitator-app](${REPO_URL}) \u2014 ${templateName} template`,
+    `> Created with [create-cogitator-app](${REPO_URL}) - ${templateName} template`,
     "",
     "## Getting Started",
     "",
     "```bash",
-    `# Install dependencies`,
-    `${options.packageManager} install`,
-    "",
-    `# Run the project`,
-    dev,
+    ...steps.flatMap((step, i) => [
+      ...i > 0 ? [""] : [],
+      ...step.note ? [`# ${step.note}`] : [],
+      step.command
+    ]),
     "```",
     "",
-    ...options.docker ? ["## Docker Services", "", "```bash", "docker compose up -d", "```", ""] : [],
+    ...options.docker ? [
+      "## Docker Services",
+      "",
+      "```bash",
+      "docker compose up -d",
+      "```",
+      "",
+      options.provider === "ollama" ? "Starts Redis, Postgres and Ollama, and pulls the model into the Ollama container." : "Starts Redis and Postgres.",
+      ""
+    ] : [],
     "## Learn More",
     "",
     `- [Cogitator Documentation](${DOCS_URL})`,
@@ -1337,9 +1681,10 @@ function initGitRepo(cwd) {
 }
 
 // src/scaffold.ts
+var NODE_ENGINES = ">=22.12.0";
 function writeFile(basePath, file) {
-  const fullPath = path2.join(basePath, file.path);
-  fs.mkdirSync(path2.dirname(fullPath), { recursive: true });
+  const fullPath = path4.join(basePath, file.path);
+  fs.mkdirSync(path4.dirname(fullPath), { recursive: true });
   fs.writeFileSync(fullPath, file.content, "utf-8");
 }
 function buildPackageJson(options) {
@@ -1350,6 +1695,7 @@ function buildPackageJson(options) {
     version: "0.1.0",
     private: true,
     ...isNextjs ? {} : { type: "module" },
+    engines: { node: NODE_ENGINES },
     scripts: template.scripts(),
     dependencies: template.dependencies(),
     devDependencies: template.devDependencies()
@@ -1361,9 +1707,9 @@ function collectFiles(options) {
   const files = [];
   files.push({ path: "package.json", content: buildPackageJson(options) });
   files.push(...template.files(options));
-  files.push(generateGitignore());
+  files.push(generateGitignore(options.template));
   files.push(generateEnvExample(options.provider, options.template));
-  files.push(generateCogitatorYml(options.provider, options.template));
+  files.push(generateCogitatorYml(options.provider, options.template, modelFor(options)));
   files.push(generateReadme(options));
   if (options.template !== "nextjs") {
     files.push(generateTsconfig());
@@ -1372,22 +1718,26 @@ function collectFiles(options) {
     files.push(generatePnpmWorkspace());
   }
   if (options.docker) {
-    files.push(generateDockerCompose(options.provider));
+    files.push(generateDockerCompose(options.provider, modelFor(options)));
   }
   return files;
 }
-function runStep(spinner2, messages, step) {
-  spinner2.start(messages.start);
+function runStep(spinner3, messages, step) {
+  spinner3.start(messages.start);
   try {
     step();
-    spinner2.stop(messages.done);
+    spinner3.stop(messages.done);
     return { status: "done" };
   } catch (error) {
-    spinner2.stop(messages.failed);
+    spinner3.stop(messages.failed);
     return { status: "failed", error: error instanceof Error ? error : new Error(String(error)) };
   }
 }
 async function scaffold(options) {
+  const nameError = validateProjectName(options.name);
+  if (nameError) {
+    throw new Error(`Invalid project name "${options.name}": ${nameError}`);
+  }
   if (fs.existsSync(options.path) && fs.readdirSync(options.path).length > 0) {
     throw new Error(`Directory "${options.path}" already exists and is not empty`);
   }
@@ -1421,7 +1771,35 @@ async function scaffold(options) {
 }
 
 // src/index.ts
-var pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
+var pkg = JSON.parse(readFileSync2(new URL("../package.json", import.meta.url), "utf-8"));
+async function prepareOllamaModel(options, interactive) {
+  const model = modelFor(options);
+  const baseUrl = resolveOllamaUrl();
+  const installed = await listOllamaModels(baseUrl);
+  if (!installed) {
+    p3.log.warn(
+      `Ollama is not running at ${baseUrl}. Start it and pull ${model} before the first run.`
+    );
+    return false;
+  }
+  if (hasOllamaModel(installed, model)) return true;
+  if (!interactive) return false;
+  const pull = await p3.confirm({
+    message: `${model} is not installed in Ollama. Pull it now?`,
+    initialValue: true
+  });
+  if (p3.isCancel(pull) || !pull) return false;
+  const s = p3.spinner();
+  s.start(`Pulling ${model}`);
+  try {
+    await pullOllamaModel(baseUrl, model, (status) => s.message(`Pulling ${model}: ${status}`));
+    s.stop(`Pulled ${model}`);
+    return true;
+  } catch (error) {
+    s.stop(error instanceof Error ? error.message : `Failed to pull ${model}`);
+    return false;
+  }
+}
 async function main() {
   banner(pkg.version);
   p3.intro(pc2.cyan("Let's build something with AI agents"));
@@ -1434,15 +1812,19 @@ async function main() {
   if (result.git.status === "failed") {
     p3.log.warn(`git init failed: ${result.git.error.message}`);
   }
-  const dev = devCommand(options.packageManager);
-  const install = result.install.status === "done" ? [] : [`  ${pc2.cyan(`${options.packageManager} install`)}`];
+  const modelReady = options.provider === "ollama" ? await prepareOllamaModel(options, !args.yes) : true;
+  const steps = nextSteps(options, {
+    installed: result.install.status === "done",
+    modelReady,
+    directory: path5.relative(process.cwd(), options.path) || void 0
+  });
   p3.outro(
     [
       pc2.green("Done! ") + "Next steps:",
       "",
-      `  ${pc2.cyan("cd")} ${options.name}`,
-      ...install,
-      `  ${pc2.cyan(dev)}`,
+      ...steps.map(
+        (step) => `  ${pc2.cyan(step.command)}${step.note ? pc2.dim(`  # ${step.note}`) : ""}`
+      ),
       "",
       pc2.dim(`Docs: ${DOCS_URL}`)
     ].join("\n")