@guuey/create-agentic-app 0.1.0

package/dist/cli.js

@@ -0,0 +1,128 @@
+#!/usr/bin/env node
+import {
+  scaffold
+} from "./chunk-JD4RAKEG.js";
+
+// src/cli.ts
+import { createInterface } from "readline/promises";
+import { stdin, stdout } from "process";
+var FRAMEWORKS = ["claude-agent-sdk", "openai-agents-sdk"];
+function isFramework(value) {
+  return FRAMEWORKS.includes(value);
+}
+function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        flags[key] = true;
+      }
+    } else {
+      positional.push(arg);
+    }
+  }
+  return { positional, flags };
+}
+function printHelp() {
+  console.log(`create-agentic-app -- scaffold a guuey agentic app
+
+Usage: create-agentic-app [target] [options]
+
+Arguments:
+  target               Directory to create the project in (prompted if omitted)
+
+Options:
+  --name <name>         Project name (default: derived from target)
+  --scope <scope>       npm scope for @<scope>/* packages (default: name)
+  --framework <f>       Framework: ${FRAMEWORKS.join(" | ")}
+  --agent <f>           Alias for --framework
+  --install             Run "pnpm install" after scaffolding
+  --no-git              Skip "git init" + initial commit
+  --force               Scaffold into a non-empty target directory
+  --list-agents         List available frameworks and exit
+  --help                Show this help
+
+Examples:
+  create-agentic-app my-app --framework claude-agent-sdk
+  create-agentic-app my-app --agent openai-agents-sdk --install
+`);
+}
+function deriveName(target) {
+  const base = target.split(/[\\/]/).filter(Boolean).pop() ?? target;
+  const slug = base.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+/, "");
+  return slug || "agentic-app";
+}
+async function promptFor(question) {
+  const rl = createInterface({ input: stdin, output: stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+async function main() {
+  const { positional, flags } = parseArgs(process.argv.slice(2));
+  if (flags.help) {
+    printHelp();
+    return;
+  }
+  if (flags["list-agents"]) {
+    console.log(FRAMEWORKS.join("\n"));
+    return;
+  }
+  let target = positional[0];
+  if (!target) {
+    target = await promptFor("Project directory: ");
+  }
+  if (!target) {
+    console.error("A target directory is required.");
+    process.exit(1);
+    return;
+  }
+  const frameworkFlag = flags.framework ?? flags.agent;
+  let frameworkInput = typeof frameworkFlag === "string" ? frameworkFlag : void 0;
+  if (!frameworkInput) {
+    frameworkInput = await promptFor(`Framework (${FRAMEWORKS.join(" | ")}): `);
+  }
+  if (!isFramework(frameworkInput)) {
+    console.error(`Unknown framework "${frameworkInput}". Available: ${FRAMEWORKS.join(", ")}`);
+    process.exit(1);
+    return;
+  }
+  const framework = frameworkInput;
+  const name = typeof flags.name === "string" ? flags.name : deriveName(target);
+  const scope = typeof flags.scope === "string" ? flags.scope : void 0;
+  const install = flags.install === true;
+  const { projectDir } = await scaffold({
+    targetDir: target,
+    name,
+    framework,
+    scope,
+    install,
+    git: flags["no-git"] !== true,
+    force: flags.force === true
+  });
+  console.log(`
+Scaffolded "${name}" in ${projectDir}
+`);
+  console.log("Next steps:");
+  console.log(`  cd ${projectDir}`);
+  if (!install) console.log("  pnpm install");
+  console.log("  pnpm dev");
+  console.log("  guuey login && guuey deploy");
+}
+main().catch((err) => {
+  if (err instanceof Error) {
+    console.error(`\u2717 ${err.message}`);
+  } else {
+    console.error(`\u2717 ${err}`);
+  }
+  process.exit(1);
+});

package/dist/index.cjs

@@ -0,0 +1,233 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  isNpmSafeName: () => isNpmSafeName,
+  scaffold: () => scaffold,
+  scaffoldMcp: () => scaffoldMcp
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/scaffold.ts
+var import_node_fs2 = require("fs");
+var import_node_path = require("path");
+var import_node_url = require("url");
+var import_node_child_process = require("child_process");
+var import_node_util = require("util");
+
+// src/rename.ts
+function renameContent(content, name, scope) {
+  return content.replaceAll("@agentic-app-template/", `@${scope}/`).replaceAll("agentic-app-template", name);
+}
+function isProbablyText(buf) {
+  const window = buf.subarray(0, 8192);
+  return !window.includes(0);
+}
+
+// src/shared.ts
+var import_node_fs = require("fs");
+var NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+function isNpmSafeName(name) {
+  return NAME_PATTERN.test(name);
+}
+function assertNpmSafeName(name, label) {
+  if (!isNpmSafeName(name)) {
+    throw new Error(
+      `Invalid ${label} name "${name}": must be npm-safe (match ${NAME_PATTERN.toString()}).`
+    );
+  }
+}
+function isErrnoException(err) {
+  return err instanceof Error && "code" in err;
+}
+async function pathExists(path) {
+  try {
+    await import_node_fs.promises.access(path);
+    return true;
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") return false;
+    throw err;
+  }
+}
+async function ensureTargetDir(targetDir, force) {
+  if (!await pathExists(targetDir)) {
+    await import_node_fs.promises.mkdir(targetDir, { recursive: true });
+    return;
+  }
+  const entries = await import_node_fs.promises.readdir(targetDir);
+  if (entries.length > 0 && !force) {
+    throw new Error(
+      `Target directory "${targetDir}" is not empty. Pass force: true (or --force) to scaffold into it anyway.`
+    );
+  }
+}
+
+// src/scaffold.ts
+var import_meta = {};
+var execFileAsync = (0, import_node_util.promisify)(import_node_child_process.execFile);
+var here = (0, import_node_path.dirname)((0, import_node_url.fileURLToPath)(import_meta.url));
+var packageRoot = (0, import_node_path.join)(here, "..");
+var defaultTemplatesDir = (0, import_node_path.join)(packageRoot, "dist", "templates");
+async function listAvailableFrameworks(templatesDir) {
+  try {
+    const entries = await import_node_fs2.promises.readdir(templatesDir, { withFileTypes: true });
+    return entries.filter((entry) => entry.isDirectory()).map((entry) => entry.name);
+  } catch (err) {
+    if (isErrnoException(err) && err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+async function resolveTemplateDir(templatesDir, framework) {
+  const dir = (0, import_node_path.join)(templatesDir, framework);
+  if (await pathExists(dir)) return dir;
+  const available = await listAvailableFrameworks(templatesDir);
+  const list = available.length > 0 ? available.join(", ") : `(none found under ${templatesDir})`;
+  throw new Error(`No template for framework "${framework}". Available frameworks: ${list}`);
+}
+async function copyTree(src, dest, name, scope) {
+  await import_node_fs2.promises.mkdir(dest, { recursive: true });
+  const entries = await import_node_fs2.promises.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const destName = renameContent(entry.name, name, scope);
+    const srcPath = (0, import_node_path.join)(src, entry.name);
+    const destPath = (0, import_node_path.join)(dest, destName);
+    if (entry.isDirectory()) {
+      await copyTree(srcPath, destPath, name, scope);
+    } else {
+      const buf = await import_node_fs2.promises.readFile(srcPath);
+      if (isProbablyText(buf)) {
+        await import_node_fs2.promises.writeFile(destPath, renameContent(buf.toString("utf8"), name, scope), "utf8");
+      } else {
+        await import_node_fs2.promises.writeFile(destPath, buf);
+      }
+    }
+  }
+}
+async function seedEnvLocal(projectDir) {
+  const envExample = (0, import_node_path.join)(projectDir, ".env.example");
+  const envLocal = (0, import_node_path.join)(projectDir, ".env.local");
+  if (!await pathExists(envExample)) return;
+  if (await pathExists(envLocal)) return;
+  await import_node_fs2.promises.copyFile(envExample, envLocal);
+}
+async function initGit(projectDir) {
+  try {
+    await execFileAsync("git", ["init"], { cwd: projectDir });
+    await execFileAsync("git", ["add", "-A"], { cwd: projectDir });
+    await execFileAsync(
+      "git",
+      [
+        "-c",
+        "user.name=guuey",
+        "-c",
+        "user.email=scaffold@guuey.com",
+        "commit",
+        "-m",
+        "chore: scaffold"
+      ],
+      { cwd: projectDir }
+    );
+  } catch {
+    console.error(
+      `Warning: git init failed; the project was scaffolded without a repo. Initialize it manually:
+  cd ${projectDir}
+  git init && git add -A && git commit -m "chore: scaffold"`
+    );
+  }
+}
+async function runInstall(projectDir) {
+  try {
+    await execFileAsync("pnpm", ["install"], { cwd: projectDir });
+  } catch {
+    console.error(
+      `Warning: "pnpm install" failed to run automatically. Run it manually:
+  cd ${projectDir}
+  pnpm install`
+    );
+  }
+}
+async function scaffold(opts) {
+  assertNpmSafeName(opts.name, "project");
+  const scope = opts.scope ?? opts.name;
+  const templatesDir = opts.templatesDir ?? defaultTemplatesDir;
+  const templateDir = await resolveTemplateDir(templatesDir, opts.framework);
+  const projectDir = (0, import_node_path.resolve)(opts.targetDir);
+  await ensureTargetDir(projectDir, opts.force);
+  await copyTree(templateDir, projectDir, opts.name, scope);
+  await seedEnvLocal(projectDir);
+  if (opts.git !== false) {
+    await initGit(projectDir);
+  }
+  if (opts.install) {
+    await runInstall(projectDir);
+  }
+  return { projectDir };
+}
+
+// src/scaffold-mcp.ts
+var import_node_fs3 = require("fs");
+var import_node_path2 = require("path");
+var import_node_url2 = require("url");
+var import_meta2 = {};
+var here2 = (0, import_node_path2.dirname)((0, import_node_url2.fileURLToPath)(import_meta2.url));
+var packageRoot2 = (0, import_node_path2.join)(here2, "..");
+var defaultTemplatesDir2 = (0, import_node_path2.join)(packageRoot2, "dist", "templates");
+function renameMcpTokens(content, name, scope) {
+  return renameContent(content.replaceAll("NAME_PLACEHOLDER", name), scope, scope);
+}
+async function copyMcpTree(src, dest, name, scope) {
+  await import_node_fs3.promises.mkdir(dest, { recursive: true });
+  const entries = await import_node_fs3.promises.readdir(src, { withFileTypes: true });
+  for (const entry of entries) {
+    const destName = renameMcpTokens(entry.name, name, scope);
+    const srcPath = (0, import_node_path2.join)(src, entry.name);
+    const destPath = (0, import_node_path2.join)(dest, destName);
+    if (entry.isDirectory()) {
+      await copyMcpTree(srcPath, destPath, name, scope);
+    } else {
+      const buf = await import_node_fs3.promises.readFile(srcPath);
+      if (isProbablyText(buf)) {
+        await import_node_fs3.promises.writeFile(destPath, renameMcpTokens(buf.toString("utf8"), name, scope), "utf8");
+      } else {
+        await import_node_fs3.promises.writeFile(destPath, buf);
+      }
+    }
+  }
+}
+async function scaffoldMcp(opts) {
+  assertNpmSafeName(opts.name, "MCP");
+  const scope = opts.scope ?? opts.name;
+  const templatesDir = opts.templatesDir ?? defaultTemplatesDir2;
+  const templateDir = (0, import_node_path2.join)(templatesDir, "mcp-base");
+  if (!await pathExists(templateDir)) {
+    throw new Error(`No mcp-base template found at ${templateDir}.`);
+  }
+  const mcpDir = (0, import_node_path2.resolve)(opts.targetDir);
+  await ensureTargetDir(mcpDir, void 0);
+  await copyMcpTree(templateDir, mcpDir, opts.name, scope);
+  return { mcpDir };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isNpmSafeName,
+  scaffold,
+  scaffoldMcp
+});

package/dist/index.d.cts

@@ -0,0 +1,76 @@
+/** Frameworks the scaffolder ships templates for. */
+type Framework = 'claude-agent-sdk' | 'openai-agents-sdk';
+interface ScaffoldOptions {
+    /** Absolute or cwd-relative path to create/populate the new project in. */
+    targetDir: string;
+    /** npm-safe project name (also used as the default scope). */
+    name: string;
+    framework: Framework;
+    /** Package scope for `@<scope>/*` packages. Default: `name`. */
+    scope?: string;
+    /** Run `pnpm install` in the new project after scaffolding. Default: false. */
+    install?: boolean;
+    /** Run `git init` + an initial commit in the new project. Default: true. */
+    git?: boolean;
+    /** Scaffold into a non-empty targetDir anyway. Default: false. */
+    force?: boolean;
+    /** Root directory holding one subdirectory per framework. Default: dist/templates. */
+    templatesDir?: string;
+}
+interface ScaffoldResult {
+    projectDir: string;
+}
+/**
+ * Scaffold a new agentic-app project from a bundled template.
+ *
+ * Copies the template tree for `opts.framework`, rewrites the
+ * `agentic-app-template` / `@agentic-app-template` placeholder tokens to the
+ * requested project name/scope (in file contents and in file/dir names),
+ * seeds `.env.local` from `.env.example` when absent, and optionally runs
+ * `git init` + an initial commit and/or `pnpm install` in the new project.
+ */
+declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
+
+interface ScaffoldMcpOptions {
+    /** Absolute or cwd-relative path to create the MCP package in. */
+    targetDir: string;
+    /** npm-safe MCP name (also the default scope in standalone mode). */
+    name: string;
+    /**
+     * Package scope for the emitted `@<scope>/<name>-mcp` name. Project-mode
+     * callers (`guuey mcp new` inside a scaffolded app) pass the surrounding
+     * project's own scope — its root `package.json` name, since a scaffolded
+     * app's own `scope` defaults to its (unscoped) project name (see
+     * `scaffold()`'s `scope ?? name`). Standalone-mode callers default this
+     * to `name`.
+     */
+    scope?: string;
+    /** Root directory holding `mcp-base/`. Default: `dist/templates`. */
+    templatesDir?: string;
+}
+interface ScaffoldMcpResult {
+    mcpDir: string;
+}
+/**
+ * Scaffold a single hosted-MCP package from the shared `mcp-base` template
+ * (`templates-src/mcp-base/`, emitted verbatim with `NAME_PLACEHOLDER`
+ * unresolved to `dist/templates/mcp-base/` by `build-templates.mjs`; see
+ * the mcp-lifecycle design spec §5).
+ *
+ * The sole consumer today is `guuey mcp new` (`@guuey/cli`):
+ * - **Project mode** — `targetDir: <project>/mcps/<name>`, `scope`: the
+ *   surrounding project's own scope.
+ * - **Standalone mode** — `targetDir: ./<name>`, `scope` left `undefined`
+ *   (defaults to `name`).
+ *
+ * Refuses (via {@link ensureTargetDir}) a non-empty `targetDir` — callers
+ * that want a stricter "refuse ANY existing directory" rule (project mode's
+ * "refuse if `mcps/<name>` exists") check `existsSync(targetDir)` themselves
+ * before calling this.
+ */
+declare function scaffoldMcp(opts: ScaffoldMcpOptions): Promise<ScaffoldMcpResult>;
+
+/** Whether `name` matches the npm-safe {@link NAME_PATTERN} rule. */
+declare function isNpmSafeName(name: string): boolean;
+
+export { type Framework, type ScaffoldMcpOptions, type ScaffoldMcpResult, type ScaffoldOptions, type ScaffoldResult, isNpmSafeName, scaffold, scaffoldMcp };

package/dist/index.d.ts

@@ -0,0 +1,76 @@
+/** Frameworks the scaffolder ships templates for. */
+type Framework = 'claude-agent-sdk' | 'openai-agents-sdk';
+interface ScaffoldOptions {
+    /** Absolute or cwd-relative path to create/populate the new project in. */
+    targetDir: string;
+    /** npm-safe project name (also used as the default scope). */
+    name: string;
+    framework: Framework;
+    /** Package scope for `@<scope>/*` packages. Default: `name`. */
+    scope?: string;
+    /** Run `pnpm install` in the new project after scaffolding. Default: false. */
+    install?: boolean;
+    /** Run `git init` + an initial commit in the new project. Default: true. */
+    git?: boolean;
+    /** Scaffold into a non-empty targetDir anyway. Default: false. */
+    force?: boolean;
+    /** Root directory holding one subdirectory per framework. Default: dist/templates. */
+    templatesDir?: string;
+}
+interface ScaffoldResult {
+    projectDir: string;
+}
+/**
+ * Scaffold a new agentic-app project from a bundled template.
+ *
+ * Copies the template tree for `opts.framework`, rewrites the
+ * `agentic-app-template` / `@agentic-app-template` placeholder tokens to the
+ * requested project name/scope (in file contents and in file/dir names),
+ * seeds `.env.local` from `.env.example` when absent, and optionally runs
+ * `git init` + an initial commit and/or `pnpm install` in the new project.
+ */
+declare function scaffold(opts: ScaffoldOptions): Promise<ScaffoldResult>;
+
+interface ScaffoldMcpOptions {
+    /** Absolute or cwd-relative path to create the MCP package in. */
+    targetDir: string;
+    /** npm-safe MCP name (also the default scope in standalone mode). */
+    name: string;
+    /**
+     * Package scope for the emitted `@<scope>/<name>-mcp` name. Project-mode
+     * callers (`guuey mcp new` inside a scaffolded app) pass the surrounding
+     * project's own scope — its root `package.json` name, since a scaffolded
+     * app's own `scope` defaults to its (unscoped) project name (see
+     * `scaffold()`'s `scope ?? name`). Standalone-mode callers default this
+     * to `name`.
+     */
+    scope?: string;
+    /** Root directory holding `mcp-base/`. Default: `dist/templates`. */
+    templatesDir?: string;
+}
+interface ScaffoldMcpResult {
+    mcpDir: string;
+}
+/**
+ * Scaffold a single hosted-MCP package from the shared `mcp-base` template
+ * (`templates-src/mcp-base/`, emitted verbatim with `NAME_PLACEHOLDER`
+ * unresolved to `dist/templates/mcp-base/` by `build-templates.mjs`; see
+ * the mcp-lifecycle design spec §5).
+ *
+ * The sole consumer today is `guuey mcp new` (`@guuey/cli`):
+ * - **Project mode** — `targetDir: <project>/mcps/<name>`, `scope`: the
+ *   surrounding project's own scope.
+ * - **Standalone mode** — `targetDir: ./<name>`, `scope` left `undefined`
+ *   (defaults to `name`).
+ *
+ * Refuses (via {@link ensureTargetDir}) a non-empty `targetDir` — callers
+ * that want a stricter "refuse ANY existing directory" rule (project mode's
+ * "refuse if `mcps/<name>` exists") check `existsSync(targetDir)` themselves
+ * before calling this.
+ */
+declare function scaffoldMcp(opts: ScaffoldMcpOptions): Promise<ScaffoldMcpResult>;
+
+/** Whether `name` matches the npm-safe {@link NAME_PATTERN} rule. */
+declare function isNpmSafeName(name: string): boolean;
+
+export { type Framework, type ScaffoldMcpOptions, type ScaffoldMcpResult, type ScaffoldOptions, type ScaffoldResult, isNpmSafeName, scaffold, scaffoldMcp };

package/dist/index.js

@@ -0,0 +1,10 @@
+import {
+  isNpmSafeName,
+  scaffold,
+  scaffoldMcp
+} from "./chunk-JD4RAKEG.js";
+export {
+  isNpmSafeName,
+  scaffold,
+  scaffoldMcp
+};

package/dist/templates/claude-agent-sdk/.env.example

@@ -0,0 +1,4 @@
+# LLM key for local dev — the deployed agent uses guuey's managed broker instead.
+ANTHROPIC_API_KEY=
+# Only needed for the openai-agents-sdk template:
+OPENAI_API_KEY=

package/dist/templates/claude-agent-sdk/.mcp.json

@@ -0,0 +1 @@
+{ "mcpServers": { "ggui-dev": { "type": "http", "url": "https://mcp.ggui.ai/dev" } } }

package/dist/templates/claude-agent-sdk/README.md

@@ -0,0 +1,107 @@
+# agentic-app-template
+
+A guuey agentic app: a code-mode agent, a custom MCP server you can copy to
+add your own tools, and a `ggui` config for generative UI — all runnable
+locally with one command, and deployable to guuey with one more.
+
+## What got scaffolded
+
+```
+.
+├── guuey.json          # the deploy contract: agent framework/model, system prompt,
+│                        #   mcpServers (name → local dev port / hosted source), ggui config
+├── package.json         # agent deps + the pnpm workspace root (workspaces: mcps/*, web)
+├── src/worker.ts        # your agent code (code-mode worker); build emits ./guuey.worker.js
+├── prompts/system.md    # system prompt, referenced from guuey.json#agent.systemPrompt.file
+├── mcps/todo/           # the "copy-me" custom MCP server — @modelcontextprotocol/sdk,
+│                         #   Streamable HTTP, in-memory todo list, port :6782
+├── ggui/                # ggui.json + blueprints/ + themes/ — generative-UI config.
+│                         #   `ggui serve` runs against this locally; it's pushed to your
+│                         #   deployed app's guuey-managed ggui instance on `guuey deploy`.
+├── web/                 # a small Vite SPA chat client — the local dev surface, and a
+│                         #   worked example of the bring-your-own-frontend path
+├── scripts/dev.mjs      # `pnpm dev` orchestrator — boots the whole local stack
+├── .env.example          # ANTHROPIC_API_KEY / OPENAI_API_KEY for local dev
+└── .mcp.json             # Claude Code convenience wiring (mcp.ggui.ai/dev)
+```
+
+The project root **is** the agent package — `guuey deploy` packs this directory
+directly as the deploy tarball, so `guuey.json` and `src/worker.ts` live at the top
+level rather than nested under a `servers/` or `apps/` folder.
+
+## Quick start
+
+```bash
+pnpm install
+cp .env.example .env.local   # done automatically on scaffold if .env.local is absent
+# set ANTHROPIC_API_KEY (or OPENAI_API_KEY, for the openai-agents-sdk template) in .env.local
+pnpm dev
+```
+
+`pnpm dev` (`scripts/dev.mjs`) boots five processes with prefixed, interleaved
+logs. Ctrl-C tears all of them down together.
+
+| process      | port  | what                                                         |
+| ------------ | ----- | ------------------------------------------------------------ |
+| `worker`     | —     | `tsup --watch` — rebuilds `guuey.worker.js` on every save    |
+| `guuey dev`  | :6790 | local router: spawns your worker per turn, streams SSE       |
+| `mcps/todo`  | :6782 | the example MCP server (copy this directory to add your own) |
+| `ggui serve` | :6781 | local generative-UI server, over `ggui/`                     |
+| `web`        | :6890 | the Vite chat SPA                                            |
+
+Open http://localhost:6890 to chat with your agent locally.
+
+## Local dev vs. deployed — what's different
+
+`guuey dev` is the open, local equivalent of the pod router that runs your
+worker in production. It mirrors the real spawn/stream contract closely — the
+same normalizer, the same SSE shape — but it deliberately cuts three corners
+that only matter once real users and real money are involved:
+
+- **No sandboxing.** Locally your worker runs as a plain child process — no
+  `bwrap`/gVisor isolation. In production every invocation runs inside a
+  gVisor-isolated pod.
+- **Permissive auth.** `ggui serve --dev-allow-all` accepts any bearer
+  locally. The deployed ggui instance enforces real auth.
+- **No metering or history.** Local runs aren't billed and aren't persisted.
+  Deployed conversations are metered and their history is written to
+  DynamoDB so users can resume a thread.
+
+None of this changes your code — `guuey.json` is the same file in both
+worlds; only how it's resolved differs (`guuey dev` points MCP server names
+at `localhost:<devPort>`, `guuey deploy` points them at the platform's
+federated URLs).
+
+## Deploying
+
+```bash
+guuey login    # device-flow auth; stores a token in ~/.guuey/auth.json
+guuey deploy   # ships everything
+```
+
+`guuey deploy` runs four legs, in order, so a hard failure aborts before
+anything user-visible changes:
+
+1. **MCP leg** — deploys each `hosted` entry under `guuey.json#agent.mcpServers`
+   (e.g. `mcps/todo`) as its own hosted MCP server (build → deploy → registry),
+   then writes the resulting server id back into `guuey.json`.
+2. **ggui asset leg** — pushes `ggui/` (ggui.json, blueprints, themes) to your
+   app's guuey-managed ggui instance.
+3. **Agent leg** — builds `src/worker.ts` into `guuey.worker.js`, packs the
+   project root, and deploys it as a gVisor-isolated, scale-to-zero pod.
+4. **Output** — prints your agent's endpoint URL and a Portal deep link.
+
+Re-running `guuey deploy` converges: unchanged pieces are skipped or reused,
+nothing is duplicated.
+
+## How people talk to your agent
+
+- **guuey Portal** — a Telegram-like agent App Store and universal chat
+  client. Once deployed, your agent is reachable from Portal with **zero
+  frontend code** — most builders never need to touch `web/` at all.
+- **`web/`** — ships anyway, because the local dev loop needs a chat surface,
+  and it's a worked example of the bring-your-own-frontend path if you want
+  to embed your agent somewhere Portal doesn't reach.
+- **Future: guuey widgets** — an embeddable web-chat widget for dropping
+  your agent into an existing site is planned as a separate feature; `web/`
+  is designed to make that graduation straightforward when it lands.

package/dist/templates/claude-agent-sdk/ggui/ggui.json

@@ -0,0 +1,15 @@
+{
+  "schema": "1",
+  "protocol": "draft-2026-06-12",
+  "app": {
+    "slug": "agentic-app-template",
+    "name": "agentic-app-template"
+  },
+  "generation": {
+    "model": "anthropic:claude-haiku-4-5-20251001"
+  },
+  "theme": {
+    "preset": "indigo",
+    "mode": "dark"
+  }
+}

package/dist/templates/claude-agent-sdk/guuey.json

@@ -0,0 +1,13 @@
+{
+  "schema": "1",
+  "agent": {
+    "mode": "code",
+    "framework": "claude-agent-sdk",
+    "model": "claude-sonnet-5",
+    "systemPrompt": { "file": "prompts/system.md" },
+    "mcpServers": {
+      "todo": { "kind": "hosted", "source": "./mcps/todo", "devPort": 6782 }
+    }
+  },
+  "ggui": { "configFile": "./ggui/ggui.json" }
+}