glove-foundry 0.0.0 → 0.2.0

package/dist/cli.js

@@ -3,7 +3,7 @@ import {
   FoundryRuntime,
   FoundryServer,
   writeGeneratedTypes
-} from "./chunk-UNHGCCSA.js";
+} from "./chunk-P65RT7H5.js";
 import {
   DEFAULT_FOUNDRY_CONFIG
 } from "./chunk-ZFNMFE3T.js";
@@ -16,8 +16,8 @@ import {
 import { watch } from "node:fs";
 import { access as access2 } from "node:fs/promises";
 import { spawn } from "node:child_process";
-import { relative, resolve as resolve2, sep } from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
+import { relative as relative2, resolve as resolve3, sep as sep2 } from "node:path";
+import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
 import process2 from "node:process";
 
 // src/env.ts
@@ -52,8 +52,97 @@ async function loadEnvFile(path) {
 }
 
 // src/scaffold.ts
-import { access, mkdir, readdir, writeFile } from "node:fs/promises";
-import { basename, dirname, resolve } from "node:path";
+import { access, mkdir, readFile as readFile3, readdir, writeFile } from "node:fs/promises";
+import { basename, dirname as dirname2, join, relative, resolve as resolve2, sep } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// src/scaffold-versions.ts
+import { readFile as readFile2 } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var TEMPLATE_DEPENDENCIES = [
+  "effect",
+  "glove-core",
+  "glove-js",
+  "glove-lisp",
+  "glove-mcp",
+  "glove-memory",
+  "glove-python",
+  "glove-working-environment",
+  "zod"
+];
+var FALLBACK_RANGES = Object.freeze({
+  effect: "^3.22.1",
+  "glove-core": "^3.6.0",
+  "glove-js": "^0.4.0",
+  "glove-lisp": "^0.4.0",
+  "glove-mcp": "^1.1.0",
+  "glove-memory": "^1.1.0",
+  "glove-python": "^0.3.0",
+  "glove-working-environment": "^0.6.0",
+  zod: "^4.3.6"
+});
+var FALLBACK_FOUNDRY_RANGE = "^0.1.0";
+function toRange(value) {
+  if (typeof value !== "string" || value.length === 0) return null;
+  if (value.startsWith("workspace:") || value.startsWith("link:") || value.startsWith("file:")) {
+    return null;
+  }
+  if (/^[\^~><=]|^\d+\.x|\|\||\s-\s/.test(value)) return value;
+  return `^${value}`;
+}
+async function readOwnManifest() {
+  const path = resolve(dirname(fileURLToPath(import.meta.url)), "../package.json");
+  try {
+    return JSON.parse(await readFile2(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+async function resolveTemplateVersions() {
+  const manifest = await readOwnManifest();
+  const declared = manifest?.dependencies ?? {};
+  const dependencies = { ...FALLBACK_RANGES };
+  const fellBack = [];
+  for (const name of TEMPLATE_DEPENDENCIES) {
+    const range = toRange(declared[name]);
+    if (range) dependencies[name] = range;
+    else fellBack.push(name);
+  }
+  const own = toRange(manifest?.version);
+  const foundry = own && own !== "^0.0.0" ? own : FALLBACK_FOUNDRY_RANGE;
+  return Object.freeze({
+    foundry,
+    dependencies: Object.freeze(dependencies),
+    resolved: fellBack.length === 0,
+    fellBack: Object.freeze(fellBack)
+  });
+}
+
+// src/scaffold.ts
+var FOUNDRY_TEMPLATES = [
+  "travel-concierge",
+  "minimal"
+];
+var TEMPLATE_IMPORTS = Object.freeze({
+  "travel-concierge": [
+    "effect",
+    "glove-core",
+    "glove-js",
+    "glove-memory",
+    "glove-working-environment",
+    "zod"
+  ],
+  minimal: ["effect", "glove-core", "zod"]
+});
+var TEMPLATE_AGENT_ROUTE = Object.freeze({
+  "travel-concierge": "concierge",
+  minimal: "assistant"
+});
+var RENAMED_ON_COPY = Object.freeze({
+  gitignore: ".gitignore",
+  "env.example": ".env.example"
+});
 async function exists(path) {
   try {
     await access(path);
@@ -62,18 +151,172 @@ async function exists(path) {
     return false;
   }
 }
+function templatesRoot() {
+  return resolve2(dirname2(fileURLToPath2(import.meta.url)), "../templates");
+}
+async function walk(root, prefix = "") {
+  const entries = await readdir(resolve2(root, prefix), { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) files.push(...await walk(root, relativePath));
+    else files.push(relativePath);
+  }
+  return files.sort();
+}
+function projectNameFrom(rootDir) {
+  return basename(rootDir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "") || "glove-foundry-app";
+}
+function runner(packageManager, script) {
+  if (packageManager === "npm") return `npm run ${script}`;
+  return `${packageManager} ${script}`;
+}
+function installCommand(packageManager) {
+  return packageManager === "yarn" ? "yarn" : `${packageManager} install`;
+}
+async function detectScaffoldTarget(rootDir) {
+  for (const config of [
+    "next.config.js",
+    "next.config.mjs",
+    "next.config.ts",
+    "next.config.cjs"
+  ]) {
+    if (await exists(resolve2(rootDir, config))) return "nextjs";
+  }
+  try {
+    const manifest = JSON.parse(
+      await readFile3(resolve2(rootDir, "package.json"), "utf8")
+    );
+    if (manifest.dependencies?.next ?? manifest.devDependencies?.next) return "nextjs";
+  } catch {
+  }
+  return "standalone";
+}
+async function detectPackageManager(rootDir) {
+  if (await exists(resolve2(rootDir, "pnpm-lock.yaml"))) return "pnpm";
+  if (await exists(resolve2(rootDir, "yarn.lock"))) return "yarn";
+  if (await exists(resolve2(rootDir, "bun.lockb"))) return "bun";
+  if (await exists(resolve2(rootDir, "package-lock.json"))) return "npm";
+  const agent = process.env.npm_config_user_agent ?? "";
+  if (agent.startsWith("yarn")) return "yarn";
+  if (agent.startsWith("bun")) return "bun";
+  if (agent.startsWith("npm")) return "npm";
+  return "pnpm";
+}
+function fill(content, values) {
+  return content.replace(
+    /\{\{(\w+)\}\}/g,
+    (match, key) => Object.hasOwn(values, key) ? values[key] : match
+  );
+}
+function dependenciesFor(template, versions) {
+  const dependencies = { "glove-foundry": versions.foundry };
+  for (const name of TEMPLATE_IMPORTS[template]) {
+    dependencies[name] = versions.dependencies[name];
+  }
+  return Object.fromEntries(
+    Object.entries(dependencies).sort(([a], [b]) => a.localeCompare(b))
+  );
+}
+var DEV_DEPENDENCIES = Object.freeze({
+  "@types/node": "^25.2.3",
+  eslint: "^9.39.2",
+  typescript: "^5.9.3",
+  "typescript-eslint": "^8.54.0"
+});
+function routesDeclaration(agentsDir, route) {
+  return `// Generated by Glove Foundry. Do not edit.
+export type FoundryRoutes = {
+  readonly "${route}": typeof import("../${agentsDir}/${route}/agent.js").default;
+};
+`;
+}
 async function scaffoldFoundryProject(options) {
-  const rootDir = resolve(options.directory);
-  if (await exists(rootDir)) {
+  const rootDir = resolve2(options.directory);
+  const template = options.template ?? "travel-concierge";
+  if (!FOUNDRY_TEMPLATES.includes(template)) {
+    throw new Error(
+      `Unknown Foundry template "${template}". Available: ${FOUNDRY_TEMPLATES.join(", ")}.`
+    );
+  }
+  const templateDir = resolve2(templatesRoot(), template);
+  if (!await exists(templateDir)) {
+    throw new Error(`Foundry template "${template}" is missing from this install.`);
+  }
+  const target = options.target ?? await detectScaffoldTarget(rootDir);
+  const packageManager = options.packageManager ?? await detectPackageManager(rootDir);
+  if (target === "standalone" && await exists(rootDir)) {
     const entries = await readdir(rootDir);
     if (entries.length > 0) {
-      throw new Error(`Cannot scaffold into non-empty directory ${rootDir}.`);
+      throw new Error(
+        `Cannot scaffold into non-empty directory ${rootDir}. Pass --target nextjs to add Foundry to an existing project.`
+      );
     }
   }
   await mkdir(rootDir, { recursive: true });
-  const projectName = basename(rootDir).toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "") || "glove-foundry-app";
-  const files = /* @__PURE__ */ new Map([
-    [
+  const versions = await resolveTemplateVersions();
+  const projectName = projectNameFrom(rootDir);
+  const agentRoute = TEMPLATE_AGENT_ROUTE[template];
+  const foundryDir = target === "nextjs" ? "foundry" : "";
+  const agentsDir = foundryDir ? `${foundryDir}/agents` : "agents";
+  const devScript = target === "nextjs" ? "foundry:dev" : "dev";
+  const startScript = target === "nextjs" ? "foundry:start" : "start";
+  const placeholders = {
+    projectName,
+    installCommand: installCommand(packageManager),
+    devCommand: runner(packageManager, devScript),
+    startCommand: runner(packageManager, startScript),
+    lintCommand: runner(packageManager, "lint"),
+    typecheckCommand: runner(packageManager, "typecheck")
+  };
+  const files = /* @__PURE__ */ new Map();
+  for (const relativePath of await walk(templateDir)) {
+    const source = await readFile3(resolve2(templateDir, relativePath), "utf8");
+    const name = basename(relativePath);
+    const renamed = RENAMED_ON_COPY[name];
+    let destination = renamed ? join(dirname2(relativePath), renamed).split(sep).join("/") : relativePath;
+    if (target === "nextjs") {
+      if (destination === "README.md" || destination === ".gitignore") continue;
+      if (destination.startsWith("src/")) continue;
+      if (destination === "foundry.config.ts") continue;
+      if (destination === ".env.example") destination = "foundry.env.example";
+      else destination = `${foundryDir}/${destination}`;
+    }
+    files.set(destination, fill(source, placeholders));
+  }
+  if (target === "nextjs") {
+    files.set(
+      "foundry.config.mts",
+      `import { defineConfig } from "glove-foundry/config";
+
+export default defineConfig({
+  agentsDir: "${agentsDir}",
+  applicationFile: "${foundryDir}/foundry.application.ts",
+  server: { port: 4141 },
+  execution: { pollIntervalMs: 100, maxConcurrent: 4 },
+});
+`
+    );
+    files.set(
+      `${foundryDir}/package.json`,
+      `${JSON.stringify(
+        {
+          name: `${projectName}-foundry`,
+          private: true,
+          // Foundry and the Glove packages are ESM. This scopes that to the
+          // agents, so the surrounding app keeps its own module system.
+          type: "module"
+        },
+        null,
+        2
+      )}
+`
+    );
+  }
+  files.set(".foundry/routes.d.ts", routesDeclaration(agentsDir, agentRoute));
+  const dependencies = dependenciesFor(template, versions);
+  if (target === "standalone") {
+    files.set(
       "package.json",
       `${JSON.stringify(
         {
@@ -87,29 +330,15 @@ async function scaffoldFoundryProject(options) {
             lint: "eslint .",
             typecheck: "tsc --noEmit"
           },
-          dependencies: {
-            effect: "^3.22.1",
-            "glove-core": "^3.5.0",
-            "glove-foundry": "^0.1.0",
-            "glove-js": "^0.3.0",
-            "glove-mcp": "^1.0.1",
-            "glove-memory": "^1.0.2",
-            "glove-working-environment": "^0.5.0",
-            zod: "^4.3.6"
-          },
-          devDependencies: {
-            "@types/node": "^25.2.3",
-            eslint: "^9.39.2",
-            "typescript-eslint": "^8.54.0",
-            typescript: "^5.9.3"
-          }
+          dependencies,
+          devDependencies: DEV_DEPENDENCIES
         },
         null,
         2
       )}
 `
-    ],
-    [
+    );
+    files.set(
       "tsconfig.json",
       `${JSON.stringify(
         {
@@ -122,324 +351,207 @@ async function scaffoldFoundryProject(options) {
             noEmit: true,
             skipLibCheck: true
           },
-          include: ["agents", "src", "foundry.application.ts", "foundry.config.ts", ".foundry/routes.d.ts"]
+          include: [
+            "agents",
+            "lib",
+            "src",
+            "foundry.application.ts",
+            "foundry.config.ts",
+            ".foundry/routes.d.ts"
+          ]
         },
         null,
         2
       )}
 `
-    ],
-    [
-      "foundry.config.ts",
-      `import { defineConfig } from "glove-foundry/config";
-
-export default defineConfig({
-  server: { port: 4141 },
-  execution: {
-    pollIntervalMs: 100,
-    maxConcurrent: 4,
-  },
-});
-`
-    ],
-    [
-      "agents/assistant/composition.ts",
-      `import { composeAgent } from "glove-foundry";
-import notes from "./apps/notes.app.js";
-import requestContext from "./layers/request-context.layer.js";
-import notion from "./mcp/notion.mcp.js";
-import personalMemory from "./memory/personal.memory.js";
-import usage from "./subscribers/usage.subscriber.js";
-import currentTime from "./tools/current-time.tool.js";
-
-export const components = composeAgent(
-  notes,
-  requestContext,
-  notion,
-  personalMemory,
-  usage,
-  currentTime,
-);
-`
-    ],
-    [
-      "agents/assistant/agent.ts",
-      `import { MemoryStore } from "glove-core";
-import { createAdapter } from "glove-core/models/providers";
-import { defineAgent } from "glove-foundry";
-import { components } from "./composition.js";
-import { loadDefaultInbox } from "./inboxes/default.inbox.js";
-import requestContext from "./layers/request-context.layer.js";
-import personalMemory from "./memory/personal.memory.js";
-import usage from "./subscribers/usage.subscriber.js";
-import { assistantRepl, assistantWorkspace } from "./workbench.js";
-
-export default defineAgent({
-  description: "A general-purpose Glove assistant",
-  components,
-  memory: [personalMemory],
-  inboxes: (_agent, context) => loadDefaultInbox(context),
-  workingEnvironment: assistantWorkspace,
-  repl: (_agent, context) => assistantRepl(context.agentId, context.messageText),
-  store: ({ conversationId }) => new MemoryStore(\`foundry:\${conversationId}\`),
-  model: createAdapter({
-    provider: "openrouter",
-    model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4.1-mini",
-    stream: true,
-  }),
-  systemPrompt: (_agent, { message, history }) =>
-    [
-      "You are a precise, practical assistant.",
-      \`Current request: \${message.text}\`,
-      \`Prior messages: \${history.length}\`,
-    ].join("\\n"),
-  compactionInstructions: () =>
-    "Preserve decisions, open work, and important context.",
-  compactionLimit: (_agent, { messageText }) =>
-    messageText.length > 2_000 ? 80_000 : 40_000,
-  layers: [requestContext],
-  subscribers: [usage],
-});
-`
-    ],
-    [
-      "agents/assistant/workbench.ts",
-      `import { JsSession, defineFn } from "glove-js";
-import { defineRepl, defineWorkingEnvironment } from "glove-foundry";
-import { z } from "zod";
-
-export const assistantWorkspace = defineWorkingEnvironment({
-  options: { limits: { maxVfsBytes: 32 * 1024 * 1024 } },
-});
-
-export function assistantRepl(actor: string, message: string) {
-  const session = JsSession.create({ actor });
-  session.register(defineFn({
-    name: "request__current",
-    description: "Read the current request inside the REPL",
-    input: z.object({}),
-    readOnlyHint: true,
-    handler: () => ({ text: message, length: message.length }),
-  }));
-  return defineRepl({ language: "javascript", session });
+    );
+    files.set(
+      "eslint.config.js",
+      'import tseslint from "typescript-eslint";\nimport foundry from "glove-foundry/eslint";\n\nexport default [...tseslint.configs.recommended, foundry];\n'
+    );
+  } else {
+    const [clientPath, clientSource] = nextClientModule(agentRoute, foundryDir);
+    files.set(clientPath, clientSource);
+    const [handlerPath, handlerSource] = nextRouteHandler(agentRoute);
+    files.set(handlerPath, handlerSource);
+    files.set(`${foundryDir}/README.md`, nextReadme(projectName, agentRoute, placeholders));
+  }
+  for (const [relativePath, content] of files) {
+    const path = resolve2(rootDir, relativePath);
+    await mkdir(dirname2(path), { recursive: true });
+    if (target === "nextjs" && await exists(path)) continue;
+    await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+  }
+  if (target === "nextjs") {
+    await mergeNextManifest(rootDir, dependencies, files);
+  }
+  return {
+    rootDir,
+    files: [...files.keys()].sort(),
+    template,
+    target,
+    packageManager,
+    agentsDir,
+    versions,
+    agentRoute
+  };
 }
-`
-    ],
-    [
-      "agents/assistant/layers/request-context.layer.ts",
-      `import { Effect } from "effect";
-import { defineLayer } from "glove-foundry";
-
-const requestContext = defineLayer({
-  description: "Expose Foundry request identity as a native Glove skill",
-  setup: ({ glove, agentId, runId, message, history }) => Effect.sync(() => {
-    glove.defineSkill({
-      name: "request-context",
-      description: "Read the current Foundry agent and run ids",
-      exposeToAgent: true,
-      async handler() { return \`agent=\${agentId} run=\${runId} message=\${message.text} prior=\${history.length}\`; },
-    });
-  }),
-});
-
-export default requestContext;
-`
-    ],
-    [
-      "agents/assistant/subscribers/usage.subscriber.ts",
-      `import { defineSubscriber } from "glove-foundry";
-
-const usage = defineSubscriber({
-  description: "Observe token consumption without changing the agent",
-  create: {
-    async record(type, data) {
-      if (type === "token_consumption") console.log("[tokens]", data);
-    },
-  },
-});
-
-export default usage;
-`
-    ],
-    [
-      "foundry.application.ts",
-      `import { MemoryFoundryDataAdapter, defineApplication } from "glove-foundry";
-
-export const data = new MemoryFoundryDataAdapter();
+function nextClientModule(route, foundryDir) {
+  return [
+    "lib/foundry.ts",
+    `/**
+ * The Next.js app talks to the Foundry runtime over HTTP, so nothing from
+ * the agent graph is bundled into your app. \`FoundryRoutes\` is a type-only
+ * import, erased at build time, and it is regenerated on every dev run \u2014 so
+ * agent("${route}") is checked against the files that actually exist.
+ */
+import { createFoundryClient } from "glove-foundry/client";
+import type { FoundryRoutes } from "../.foundry/routes.js";
 
-export default defineApplication({
-  name: "${projectName}",
-  data,
-  accounts: [],
-  routes: [],
-  bindings: [],
+export const foundry = createFoundryClient<FoundryRoutes>({
+  baseUrl: process.env.FOUNDRY_URL ?? "http://127.0.0.1:4141",
 });
-`
-    ],
-    [
-      "agents/assistant/tools/current-time.tool.ts",
-      `import { defineSharedTool } from "glove-foundry";
-import { z } from "zod";
 
-const currentTime = defineSharedTool({
-  description: "Return the current ISO timestamp",
-  tool: {
-    name: "current_time",
-  description: "Return the current ISO timestamp",
-  inputSchema: z.object({}),
-  async do() {
-    return { status: "success", data: new Date().toISOString() };
-  },
-  },
-});
 
-export default currentTime;
+// The agents live in ${foundryDir}/agents. Start the runtime with
+// \`foundry:dev\`; it serves the inspector at http://127.0.0.1:4141.
 `
-    ],
-    [
-      "agents/assistant/apps/notes.app.ts",
-      `import { Effect } from "effect";
-import { defineApp } from "glove-foundry";
-import { z } from "zod";
-
-const notes = defineApp({
-  description: "An example application installed only when selected",
-  config: z.object({ namespace: z.string().default("default") }),
-  inbound: [],
-  outbound: [],
-  install: ({ config }) => Effect.sync(() => {
-    return { tools: [{
-      name: "notes_namespace",
-      description: "Return the installed notes namespace",
-      inputSchema: z.object({}),
-      async do() { return { status: "success", data: config.namespace }; },
-    }] };
-  }),
-});
-
-export default notes;
-`
-    ],
-    [
-      "agents/assistant/inboxes/default.inbox.ts",
-      `import type { InboxItem } from "glove-core";
-import type { AgentAssemblyContext } from "glove-foundry";
-
-export async function loadDefaultInbox(
-  context: AgentAssemblyContext,
-): Promise<ReadonlyArray<InboxItem>> {
-  // Load this conversation's inbox from your own adapter or service.
-  void \`\${context.agentId}:\${context.conversationId}\`;
-  return [];
+  ];
 }
-`
-    ],
-    [
-      "agents/assistant/mcp/notion.mcp.ts",
-      `import { defineMcp } from "glove-foundry";
-
-// This remains disconnected until an agent instance installs it.
-const notion = defineMcp({
-  entry: {
-    name: "Notion",
-    description: "Search and update a Notion workspace",
-    url: "https://mcp.notion.com/mcp",
-    tags: ["notes", "workspace"],
-  },
-});
-
-export default notion;
-`
-    ],
-    [
-      "agents/assistant/memory/personal.memory.ts",
-      `import { Effect } from "effect";
-import { defineMemory } from "glove-foundry";
-import { MemorySchema } from "glove-memory/core";
-import { InMemoryContextAdapter } from "glove-memory/in-memory";
-
-const schema = new MemorySchema();
-const context = new InMemoryContextAdapter({ schema });
-
-const personalMemory = defineMemory({
-  description: "Ambient user context backed by a replaceable memory adapter",
-  context: { adapter: () => Effect.succeed(context) },
-});
-
-export default personalMemory;
-`
-    ],
-    [
-      "src/client.ts",
-      `import { createFoundryClient } from "glove-foundry/client";
-import type { FoundryRoutes } from "../.foundry/routes.js";
-
-export const foundry = createFoundryClient<FoundryRoutes>();
-
-const agent = await foundry.agent("assistant").create({ workspaceId: "default" });
-const conversation = await foundry.createConversation(agent.id);
-const run = await foundry.send(agent.id, conversation.id, "Hello");
-const completed = await run.wait();
-console.log(completed.output);
-`
-    ],
-    [
-      ".foundry/routes.d.ts",
-      `// Generated by Glove Foundry. Do not edit.
-export type FoundryRoutes = {
-  readonly "assistant": typeof import("../agents/assistant/agent.js").default;
-};
-`
-    ],
-    [".env.example", "OPENROUTER_API_KEY=\nOPENROUTER_MODEL=openai/gpt-4.1-mini\n"],
-    [
-      "eslint.config.js",
-      `import tseslint from "typescript-eslint";
-import foundry from "glove-foundry/eslint";
-
-export default [...tseslint.configs.recommended, foundry];
-`
-    ],
-    [".gitignore", "node_modules\n.env.local\n.foundry/manifest.json\n"],
-    [
-      "README.md",
-      `# ${projectName}
-
-A file-routed Glove Foundry application.
+function nextRouteHandler(route) {
+  return [
+    `app/api/${route}/route.ts`,
+    `/**
+ * POST /api/${route} \u2014 send a message to the agent and wait for its result.
+ *
+ * This runs on the server, so the Foundry runtime never has to be public.
+ * For a streaming UI, subscribe to the runtime's /api/events instead of
+ * awaiting run.wait().
+ */
+import { foundry } from "../../../lib/foundry.js";
+
+export async function POST(request: Request) {
+  const { message, workspaceId = "default" } = (await request.json()) as {
+    message: string;
+    workspaceId?: string;
+  };
 
-1. Copy \`.env.example\` to \`.env.local\` and add your API key.
-2. Install dependencies with \`pnpm install\`.
-3. Run \`pnpm dev\`.
-4. Open http://127.0.0.1:4141.
+  // A real app reuses one instance per user rather than creating one per call.
+  const agent = await foundry.agent("${route}").create({ workspaceId });
+  const conversation = await foundry.createConversation(agent.id);
+  const run = await foundry.send(agent.id, conversation.id, message);
+  const completed = await run.wait();
 
-Add agents under \`agents/<route>/agent.ts\`; the file path is the route. Keep that agent's applications, transmissions, tools, MCPs, memory, inboxes, layers, subscribers, and workbench beside it, then combine reusable capabilities with \`composeAgent\`. Code-authored references use imported definition values; Foundry normalizes them to ids only when instance data is persisted. Applications and MCPs remain inert until an agent instance installs them. The scaffold mounts a sandboxed VFS/script environment and a request-aware JavaScript REPL; change or remove them in \`workbench.ts\`. Agents create future and recurring work only through Foundry's scheduling and sleep tools.
+  return Response.json({ runId: run.id, output: completed.output });
+}
 `
-    ]
-  ]);
-  for (const [relativePath, content] of files) {
-    const path = resolve(rootDir, relativePath);
-    await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, content, { encoding: "utf8", flag: "wx" });
+  ];
+}
+function nextReadme(projectName, route, placeholders) {
+  return [
+    `# Foundry agents for ${projectName}`,
+    "",
+    "The agents live here; the Next.js app calls them over HTTP through",
+    "`lib/foundry.ts`. Nothing in this folder is bundled into your app.",
+    "",
+    "## Running",
+    "",
+    "Two processes, because they have different lifecycles \u2014 the runtime keeps",
+    "durable state and should not restart when a React component changes:",
+    "",
+    "```bash",
+    placeholders.devCommand + "      # Foundry runtime + inspector on :4141",
+    placeholders.installCommand.split(" ")[0] + " dev              # Next.js on :3000",
+    "```",
+    "",
+    "Then POST to your own route:",
+    "",
+    "```bash",
+    `curl -X POST http://localhost:3000/api/${route} \\`,
+    "  -H 'content-type: application/json' \\",
+    `  -d '{"message":"I want to fly from Lisbon to Nairobi in April."}'`,
+    "```",
+    "",
+    "## Layout",
+    "",
+    "| Path | What it is |",
+    "| --- | --- |",
+    `| \`foundry/agents/${route}/agent.ts\` | The agent. The file path is its id. |`,
+    "| `foundry/foundry.application.ts` | Data adapter, accounts, routes |",
+    "| `foundry.config.ts` | Points the runtime at `foundry/agents` |",
+    "| `lib/foundry.ts` | Typed HTTP client for your app to import |",
+    `| \`app/api/${route}/route.ts\` | An example Next.js route handler |`,
+    "| `.foundry/routes.d.ts` | Generated. Do not edit |",
+    "",
+    "## Deploying",
+    "",
+    "The runtime is a normal Node process. Deploy it wherever you run servers,",
+    "set `FOUNDRY_URL` in your Next.js environment to point at it, and keep it",
+    "private to your network \u2014 the inspector is a development surface.",
+    "",
+    "See the [full Foundry guide](https://github.com/porkytheblack/glove/blob/main/packages/glove-foundry/docs/building-with-foundry.md).",
+    ""
+  ].join("\n");
+}
+async function mergeNextManifest(rootDir, dependencies, files) {
+  const path = resolve2(rootDir, "package.json");
+  let manifest = {};
+  if (await exists(path)) {
+    manifest = JSON.parse(await readFile3(path, "utf8"));
   }
-  return { rootDir, files: [...files.keys()] };
+  const scripts = { ...manifest.scripts };
+  scripts["foundry:dev"] ??= "glove foundry dev";
+  scripts["foundry:start"] ??= "glove foundry start";
+  const merged = {
+    ...manifest,
+    scripts,
+    dependencies: Object.fromEntries(
+      Object.entries({
+        ...manifest.dependencies,
+        ...dependencies
+      }).sort(([a], [b]) => a.localeCompare(b))
+    )
+  };
+  await writeFile(path, `${JSON.stringify(merged, null, 2)}
+`, "utf8");
+  files.set("package.json", "(merged)");
+}
+function displayPath(rootDir) {
+  return relative(process.cwd(), rootDir) || ".";
 }
 
 // src/cli.ts
 var HELP = `Glove Foundry \u2014 a file-routed runtime for agents
 
 Usage:
-  glove foundry [directory]       Create a Foundry application
-  glove foundry dev [options]     Run the development runtime and DevTools
+  glove foundry init [directory]  Create a Foundry application
+  glove foundry dev [options]     Run the development runtime and inspector
   glove foundry start [options]   Run without file watching
-  glove-foundry init [directory]  Create a Foundry application
-  glove-foundry dev [options]     Run the development runtime and DevTools
-  glove-foundry start [options]   Run without file watching
 
-Options:
+  The bare form still works: glove foundry my-app
+
+Create options:
+  --template <name>               travel-concierge (default) or minimal
+                                    travel-concierge  a worked example: flights, a
+                                                      calendar app, chat transport,
+                                                      memory, a schedule, a REPL
+                                    minimal           one agent and one tool
+  --target <name>                 standalone (default) or nextjs
+                                    Detected automatically: a directory holding a
+                                    Next.js app gets the nextjs target, which adds
+                                    agents under foundry/ and leaves the app alone.
+  --package-manager <name>        pnpm, npm, yarn, or bun (detected by lockfile)
+
+Run options:
   --root <directory>              Project root (default: current directory)
   --port <number>                 Override the configured port
   --host <address>                Override the configured host
   --no-watch                      Disable agent/config hot restart
+
+Examples:
+  glove foundry init my-agents
+  glove foundry init my-agents --template minimal
+  glove foundry init . --target nextjs     Add agents to the app in this directory
 `;
 function parseArgs(raw) {
   const args = [...raw];
@@ -476,7 +588,7 @@ async function pathExists(path) {
 async function loadConfig(rootDir) {
   const candidates = ["foundry.config.ts", "foundry.config.mts", "foundry.config.js", "foundry.config.mjs"];
   for (const candidate of candidates) {
-    const path = resolve2(rootDir, candidate);
+    const path = resolve3(rootDir, candidate);
     if (!await pathExists(path)) continue;
     const url = pathToFileURL(path);
     url.searchParams.set("t", String(Date.now()));
@@ -490,7 +602,7 @@ async function loadConfig(rootDir) {
 }
 async function loadApplication(rootDir, config) {
   const relativePath = config.applicationFile ?? DEFAULT_FOUNDRY_CONFIG.applicationFile;
-  const path = resolve2(rootDir, relativePath);
+  const path = resolve3(rootDir, relativePath);
   if (!await pathExists(path)) return EMPTY_FOUNDRY_APPLICATION;
   const url = pathToFileURL(path);
   url.searchParams.set("t", String(Date.now()));
@@ -501,18 +613,18 @@ async function loadApplication(rootDir, config) {
   return imported.default;
 }
 async function runWorker(parsed) {
-  const rootDir = resolve2(
+  const rootDir = resolve3(
     typeof parsed.flags.root === "string" ? parsed.flags.root : process2.cwd()
   );
-  await loadEnvFile(resolve2(rootDir, ".env"));
-  await loadEnvFile(resolve2(rootDir, ".env.local"));
+  await loadEnvFile(resolve3(rootDir, ".env"));
+  await loadEnvFile(resolve3(rootDir, ".env.local"));
   const config = await loadConfig(rootDir);
   const application = await loadApplication(rootDir, config);
-  const applicationFilePath = resolve2(
+  const applicationFilePath = resolve3(
     rootDir,
     config.applicationFile ?? DEFAULT_FOUNDRY_CONFIG.applicationFile
   );
-  const agentsDir = resolve2(
+  const agentsDir = resolve3(
     rootDir,
     config.agentsDir ?? DEFAULT_FOUNDRY_CONFIG.agentsDir
   );
@@ -558,16 +670,17 @@ async function runWorker(parsed) {
   process2.once("SIGTERM", () => void close());
   process2.once("SIGINT", () => void close());
 }
-function shouldRestart(rootDir, changed) {
+function shouldRestart(rootDir, changed, agentsDir) {
   if (!changed) return false;
-  const normalized = relative(rootDir, resolve2(rootDir, changed)).split(sep).join("/");
-  return normalized.startsWith("agents/") || normalized === ".env" || normalized === ".env.local" || /^foundry\.application\.(?:ts|mts|js|mjs)$/.test(normalized) || /^foundry\.config\.(?:ts|mts|js|mjs)$/.test(normalized);
+  const normalized = relative2(rootDir, resolve3(rootDir, changed)).split(sep2).join("/");
+  return normalized.startsWith(`${agentsDir}/`) || normalized === ".env" || normalized === ".env.local" || /^(?:[\w.-]+\/)*foundry\.application\.(?:ts|mts|js|mjs)$/.test(normalized) || /^foundry\.config\.(?:ts|mts|js|mjs)$/.test(normalized);
 }
 async function superviseDev(parsed) {
-  const rootDir = resolve2(
+  const rootDir = resolve3(
     typeof parsed.flags.root === "string" ? parsed.flags.root : process2.cwd()
   );
-  const cliPath = fileURLToPath(import.meta.url);
+  const agentsDir = (await loadConfig(rootDir)).agentsDir ?? DEFAULT_FOUNDRY_CONFIG.agentsDir;
+  const cliPath = fileURLToPath3(import.meta.url);
   const tsxImport = import.meta.resolve("tsx");
   let child = null;
   const watchers = [];
@@ -618,7 +731,7 @@ async function superviseDev(parsed) {
   if (!parsed.flags["no-watch"]) {
     try {
       const onChange = (filename) => {
-        if (!shouldRestart(rootDir, filename?.toString() ?? null)) return;
+        if (!shouldRestart(rootDir, filename?.toString() ?? null, agentsDir)) return;
         if (debounce) clearTimeout(debounce);
         debounce = setTimeout(restart, 120);
       };
@@ -629,14 +742,14 @@ async function superviseDev(parsed) {
           (_event, filename) => onChange(filename?.toString() ?? null)
         )
       );
-      const defaultAgentsDir = resolve2(rootDir, "agents");
-      if (await pathExists(defaultAgentsDir)) {
+      const watchedAgentsDir = resolve3(rootDir, agentsDir);
+      if (await pathExists(watchedAgentsDir)) {
         watchers.push(
           watch(
-            defaultAgentsDir,
+            watchedAgentsDir,
             { recursive: true },
             (_event, filename) => onChange(
-              filename ? `agents/${filename.toString()}` : "agents"
+              filename ? `${agentsDir}/${filename.toString()}` : agentsDir
             )
           )
         );
@@ -648,7 +761,7 @@ async function superviseDev(parsed) {
         "memory",
         "inboxes"
       ]) {
-        const watched = resolve2(rootDir, directory);
+        const watched = resolve3(rootDir, directory);
         if (await pathExists(watched)) {
           watchers.push(
             watch(
@@ -678,7 +791,7 @@ async function superviseDev(parsed) {
   process2.once("SIGTERM", stop);
 }
 async function superviseStart(parsed) {
-  const rootDir = resolve2(
+  const rootDir = resolve3(
     typeof parsed.flags.root === "string" ? parsed.flags.root : process2.cwd()
   );
   const child = spawn(
@@ -686,7 +799,7 @@ async function superviseStart(parsed) {
     [
       "--import",
       import.meta.resolve("tsx"),
-      fileURLToPath(import.meta.url),
+      fileURLToPath3(import.meta.url),
       "__start-worker",
       "--root",
       rootDir,
@@ -716,6 +829,77 @@ async function superviseStart(parsed) {
     throw new Error(`Foundry worker exited with code ${exitCode}.`);
   }
 }
+var UsageError = class extends Error {
+};
+function flagValue(parsed, name, allowed) {
+  const raw = parsed.flags[name];
+  if (raw === void 0) return void 0;
+  if (typeof raw !== "string" || !allowed.includes(raw)) {
+    throw new UsageError(
+      `--${name} must be one of: ${allowed.join(", ")}.` + (typeof raw === "string" ? ` Received "${raw}".` : "")
+    );
+  }
+  return raw;
+}
+async function create(directory, parsed) {
+  const template = flagValue(parsed, "template", FOUNDRY_TEMPLATES);
+  const target = flagValue(parsed, "target", ["standalone", "nextjs"]);
+  const packageManager = flagValue(
+    parsed,
+    "package-manager",
+    ["pnpm", "npm", "yarn", "bun"]
+  );
+  const result = await scaffoldFoundryProject({
+    directory,
+    ...template ? { template } : {},
+    ...target ? { target } : {},
+    ...packageManager ? { packageManager } : {}
+  });
+  const where = displayPath(result.rootDir);
+  const pm = result.packageManager;
+  const run = (script) => pm === "npm" ? `npm run ${script}` : `${pm} ${script}`;
+  const install = pm === "yarn" ? "yarn" : `${pm} install`;
+  const lines = [""];
+  if (result.target === "nextjs") {
+    lines.push(`  Added Glove Foundry to the app in ${result.rootDir}`);
+    lines.push("");
+    lines.push(`  Agents:   ${result.agentsDir}/${result.agentRoute}/agent.ts`);
+    lines.push(`  Client:   lib/foundry.ts`);
+    lines.push(`  Route:    app/api/${result.agentRoute}/route.ts`);
+    lines.push(`  Guide:    foundry/README.md`);
+    lines.push("");
+    lines.push("  Next:");
+    if (where !== ".") lines.push(`    cd ${where}`);
+    lines.push(`    ${install}`);
+    lines.push(`    ${run("foundry:dev")}      # runtime + inspector on :4141`);
+    lines.push(`    ${run("dev")}              # your Next.js app`);
+  } else {
+    lines.push(`  Created a Glove Foundry app in ${result.rootDir}`);
+    lines.push("");
+    lines.push(`  Template: ${result.template}`);
+    lines.push(`  Agent:    ${result.agentsDir}/${result.agentRoute}/agent.ts`);
+    lines.push(`  Guide:    README.md`);
+    lines.push("");
+    lines.push("  Next:");
+    if (where !== ".") lines.push(`    cd ${where}`);
+    lines.push("    cp .env.example .env.local");
+    lines.push(`    ${install}`);
+    lines.push(`    ${run("dev")}`);
+    lines.push("");
+    lines.push("  Then open http://127.0.0.1:4141 and press Start a run.");
+    if (result.template === "travel-concierge") {
+      lines.push("  It works without an API key \u2014 a demo model answers until you set one.");
+    }
+  }
+  if (!result.versions.resolved) {
+    lines.push("");
+    lines.push("  Note: some Glove versions came from built-in defaults rather than");
+    lines.push("  this install's own manifest. Check before installing:");
+    lines.push(`    ${result.versions.fellBack.join(", ")}`);
+  }
+  lines.push("");
+  process2.stdout.write(lines.join("\n"));
+}
 async function main() {
   const parsed = parseArgs(process2.argv.slice(2));
   if (parsed.command === "__dev-worker" || parsed.command === "__start-worker") {
@@ -729,18 +913,7 @@ async function main() {
   const createByGloveSyntax = parsed.gloveSyntax && parsed.command !== "dev" && parsed.command !== "start";
   if (parsed.command === "init" || createByGloveSyntax || parsed.gloveSyntax && !parsed.command) {
     const directory = parsed.command === "init" ? parsed.positional[0] ?? "glove-foundry-app" : parsed.command ?? "glove-foundry-app";
-    const result = await scaffoldFoundryProject({ directory });
-    process2.stdout.write(`Created Glove Foundry in ${result.rootDir}
-
-`);
-    process2.stdout.write(`  cd ${relative(process2.cwd(), result.rootDir) || "."}
-`);
-    process2.stdout.write(`  cp .env.example .env.local
-`);
-    process2.stdout.write(`  pnpm install
-`);
-    process2.stdout.write(`  pnpm dev
-`);
+    await create(directory, parsed);
     return;
   }
   if (parsed.command === "dev") {
@@ -754,7 +927,18 @@ async function main() {
   process2.stdout.write(HELP);
 }
 main().catch((error) => {
-  process2.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}
+  if (error instanceof UsageError) {
+    process2.stderr.write(`
+  ${error.message}
+
+  Run "glove foundry help" for usage.
+
 `);
+  } else {
+    process2.stderr.write(
+      `${error instanceof Error ? error.stack ?? error.message : String(error)}
+`
+    );
+  }
   process2.exitCode = 1;
 });