@guuey/create-agentic-app 0.9.0 → 0.11.0

package/dist/templates/base/google-adk/web/src/styles.css

@@ -0,0 +1,248 @@
+/* agentic-app-template site styles — one accent, light/dark, no framework. */
+
+:root {
+  --app-accent: #6c5ce7;
+  --bg: #ffffff;
+  --bg-soft: #f6f7f9;
+  --fg: #16181d;
+  --fg-soft: #5b6270;
+  --line: #e4e7ec;
+  --ok: #1a7f37;
+}
+
+:root[data-mode="dark"] {
+  --bg: #101216;
+  --bg-soft: #181b21;
+  --fg: #e8eaee;
+  --fg-soft: #9aa2b1;
+  --line: #262a33;
+  --ok: #3fb950;
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  background: var(--bg);
+  color: var(--fg);
+}
+
+code,
+pre {
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+  font-size: 0.9em;
+}
+
+pre {
+  background: var(--bg-soft);
+  border: 1px solid var(--line);
+  border-radius: 8px;
+  padding: 12px 14px;
+  overflow-x: auto;
+}
+
+a {
+  color: var(--app-accent);
+}
+
+.shell {
+  min-height: 100vh;
+  display: flex;
+  flex-direction: column;
+}
+
+.topbar {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 12px 24px;
+  border-bottom: 1px solid var(--line);
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  font-weight: 700;
+  color: var(--fg);
+  text-decoration: none;
+}
+
+.brand-mark {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 30px;
+  height: 30px;
+  border-radius: 8px;
+  background: var(--app-accent);
+  color: #fff;
+  font-size: 13px;
+}
+
+.topbar nav {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+}
+
+.topbar nav a {
+  color: var(--fg-soft);
+  text-decoration: none;
+}
+
+.topbar nav a.active {
+  color: var(--fg);
+  font-weight: 600;
+}
+
+.btn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 8px 16px;
+  border-radius: 8px;
+  border: 1px solid var(--line);
+  background: var(--bg);
+  color: var(--fg);
+  font-size: 14px;
+  cursor: pointer;
+  text-decoration: none;
+}
+
+.btn:disabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+}
+
+.btn-accent {
+  background: var(--app-accent);
+  border-color: var(--app-accent);
+  color: #fff;
+}
+
+.btn-wide {
+  width: 100%;
+}
+
+.page {
+  flex: 1;
+  width: 100%;
+  max-width: 880px;
+  margin: 0 auto;
+  padding: 32px 24px;
+}
+
+.hero {
+  text-align: center;
+  padding: 64px 0;
+}
+
+.hero h1 {
+  font-size: 44px;
+  margin: 0 0 12px;
+}
+
+.hero p {
+  color: var(--fg-soft);
+  font-size: 18px;
+  margin: 0 0 28px;
+}
+
+.hero-actions {
+  display: flex;
+  gap: 12px;
+  justify-content: center;
+}
+
+.login {
+  display: flex;
+  justify-content: center;
+}
+
+.login-card,
+.gate-card {
+  width: 100%;
+  max-width: 380px;
+  margin-top: 48px;
+  padding: 28px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  background: var(--bg-soft);
+  display: flex;
+  flex-direction: column;
+  gap: 12px;
+}
+
+.gate {
+  min-height: 100vh;
+  display: flex;
+  justify-content: center;
+  background: var(--bg);
+  color: var(--fg);
+}
+
+.gate-card {
+  max-width: 520px;
+}
+
+.chat-page {
+  display: flex;
+  max-width: 880px;
+  height: calc(100vh - 61px);
+  padding: 16px 24px 24px;
+}
+
+.chat-fill {
+  flex: 1;
+  min-height: 0;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  overflow: hidden;
+}
+
+.card {
+  border: 1px solid var(--line);
+  border-radius: 12px;
+  padding: 20px 24px;
+  margin-bottom: 24px;
+  background: var(--bg);
+}
+
+.facts {
+  display: grid;
+  grid-template-columns: 140px 1fr;
+  gap: 8px 16px;
+  margin: 0;
+}
+
+.facts dt {
+  color: var(--fg-soft);
+}
+
+.facts dd {
+  margin: 0;
+  overflow-wrap: anywhere;
+}
+
+.ok {
+  color: var(--ok);
+  font-weight: 600;
+}
+
+.calm {
+  color: var(--fg-soft);
+}
+
+.hint {
+  color: var(--fg-soft);
+  font-size: 14px;
+}
+
+.error {
+  color: #c0392b;
+  font-size: 14px;
+}

package/dist/templates/base/google-adk/web/src/vite-env.d.ts

@@ -0,0 +1,14 @@
+/// <reference types="vite/client" />
+
+interface ImportMetaEnv {
+  /**
+   * Optional external-script hook (guuey#303): a URL loaded at boot — the
+   * demo tour's bundle rides this in the demo apps; unset in customer
+   * builds.
+   */
+  readonly VITE_DEMO_TOUR_SRC?: string;
+}
+
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}

package/dist/templates/base/google-adk/web/tsconfig.json

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "esModuleInterop": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "vite.config.ts", "../guuey.app.json"]
+}

package/dist/templates/base/google-adk/web/vite.config.ts

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { defineConfig, type Plugin } from "vite";
+import react from "@vitejs/plugin-react";
+
+const projectRoot = join(dirname(fileURLToPath(import.meta.url)), "..");
+
+/**
+ * Fail-loud production gate (never a half-styled deploy): `pnpm bootstrap`
+ * not run yet → the BUILD fails with the exact command. An UNLINKED build
+ * is allowed — the pages state the missing binding honestly — but gets a
+ * loud warning, since a deployed frontend without a bound guuey app has no
+ * live agent to talk to.
+ *
+ * Dev is NOT gated here — `src/components/BootstrapGate.tsx` renders the
+ * "run bootstrap first" screen instead, so `pnpm dev` always starts.
+ */
+function bootstrapGatePlugin(): Plugin {
+  return {
+    name: "guuey-bootstrap-gate",
+    apply: "build",
+    buildStart() {
+      const raw = readFileSync(join(projectRoot, "guuey.app.json"), "utf8");
+      const app = JSON.parse(raw) as { bootstrapped?: boolean; link?: object | null };
+      if (app.bootstrapped !== true) {
+        throw new Error(
+          "guuey.app.json is not bootstrapped — run `pnpm bootstrap` at the project root first.",
+        );
+      }
+      if (!app.link) {
+        console.warn(
+          "[guuey-bootstrap-gate] building WITHOUT a bound guuey app — the deployed site will have " +
+            "no live agent until you run `pnpm bootstrap -- --link --app-id <appId>` and rebuild.",
+        );
+      }
+    },
+  };
+}
+
+// Port is passed via the `dev` script's `--port 6890` flag (see package.json)
+// so it stays visible in one place; `scripts/dev.mjs` boots this on the same
+// port.
+export default defineConfig({
+  plugins: [react(), bootstrapGatePlugin()],
+});

package/dist/templates/base/openai-agents-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/base/openai-agents-sdk/.mcp.json

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

package/dist/templates/base/openai-agents-sdk/AGENTS.md

@@ -0,0 +1,135 @@
+# AGENTS.md — steering for the coding agent working in this repo
+
+You (the coding agent) are extending a guuey agentic app. Before you reach
+for a database or a cache, read this file. The single most common mistake
+here is standing up local Redis/SQLite/file-based state "just to get
+something working" — **don't.** Every pod this project deploys to
+(the agent entry's pod — `src/worker.ts`, or `src/agent.ts` in a google-adk scaffold — including every `kind: colocated` `mcps/*`
+server auto-spawned inside it, like this scaffold's `mcps/todo` — and every
+`mcps/*` server deployed with `kind: hosted`) is **ephemeral and horizontally
+replaced**: gVisor-isolated,
+scale-to-zero, ordinary process death on every deploy or idle timeout. A
+local file or an in-process `Map` used as a database is not a shortcut —
+it is silent data loss the first time the pod recycles.
+
+Use this table to route persistence decisions. Pick a row, don't invent one.
+
+| Need                                                                                                         | Use                                                                                                                                                                                                                                                                                                                                                                    | Why                                                                                                                                                                                                                                                                                                                                     |
+| ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Small per-user state on an MCP server (idempotency keys, rate-limit counters, OAuth nonces, prefs, a few KB) | [`@guuey/state`](https://www.npmjs.com/package/@guuey/state) — `withGuueyContext(scopeFromAuthorization(...), fn)`                                                                                                                                                                                                                                                     | Zero auth code — guuey owns the identity rails. Durable, per-`(user, mcp)`, survives pod restarts.                                                                                                                                                                                                                                      |
+| Large or relational data (rows, queries, joins, anything you'd reach for Postgres/Redis for)                 | An external managed serverless DB — Neon, Upstash, Supabase, or Turso — wired in via `guuey mcp secrets set DATABASE_URL=... --server <id>` (hosted MCP) or `guuey env set DATABASE_URL=...` (the agent worker and its colocated MCP children — the pod's declared env/secrets are handed to every colocated child), consumed through the provider's serverless driver | Guuey **integrates, never operates** databases — that's the platform's hosting policy, not a v1 gap. Pick the provider's **`us-east-1`** region: a guuey-hosted MCP → provider hop is then same-region AWS backbone, single-digit-ms — comparable to a cross-AZ hop, and agent turns are already dominated by seconds of LLM inference. |
+| Local Redis, SQLite, or any file written as a database                                                       | **Never.** Not for v1, not "temporarily."                                                                                                                                                                                                                                                                                                                              | Pods are ephemeral and horizontally replaced — a local store vanishes on the next deploy, restart, or scale event, with no warning to you or the user.                                                                                                                                                                                  |
+| Per-user files/blobs from **inside the agent pod** (the agent entry)                                         | [`@guuey/fs`](https://www.npmjs.com/package/@guuey/fs)'s `homeDir()`/`appDir()`/`sessionDir()`, or the raw `$GUUEY_HOME_DIR`/`$GUUEY_APP_DIR` env vars + `node:fs`                                                                                                                                                                                                     | Every invoke already gets these three bound directories — `$GUUEY_HOME_DIR` is durable per-user, `$GUUEY_APP_DIR` is read-only shared, cwd is session scratch. No wrapper API required, but the helpers save you the env-var lookups.                                                                                                   |
+| Per-user files/blobs from **inside an MCP server** (`mcps/*`)                                                | Not yet available — `@guuey/files` is planned but not shipped. Fall back to the managed-DB row above (e.g. store blobs in the provider's object storage) until it lands.                                                                                                                                                                                               | Don't build against an API that doesn't exist yet.                                                                                                                                                                                                                                                                                      |
+| Conversation / chat history                                                                                  | **Do not re-implement.** The platform already persists it.                                                                                                                                                                                                                                                                                                             | Guuey writes thread history to DynamoDB and streams it back over AppSync; agents that keep their own transcript store are duplicating (and diverging from) data the platform already owns.                                                                                                                                              |
+
+## `@guuey/state`: the one-line pattern
+
+`@guuey/state` only works inside an MCP server whose `guuey.json` entry is
+**federated** — that's the opt-in. A `kind: colocated` entry (like
+`mcps/todo` in this scaffold) or a `kind: hosted` entry is federated
+automatically. If you add a `kind: external` entry (a server you host
+yourself, reached by URL), you must set `federate: true` on it:
+
+```json
+{
+  "kind": "external",
+  "url": "https://your-server.example.com",
+  "federate": true
+}
+```
+
+Without `federate: true` (or `kind: colocated`/`kind: hosted`/a `ggui`
+URL), guuey has no
+identity to hand your server — a plain external entry with static
+`headers` gets **no token and no state.** The token guuey sends on every
+request to a federated server IS the credential; there is no separate
+API key to provision.
+
+Inside a federated MCP server, wrap each request in
+`withGuueyContext(scopeFromAuthorization(header), fn)` and use the
+barrel-exported `kv` inside `fn` — that's the whole integration. One
+complete, runnable example — an idempotency-key check on a tool call,
+using the raw Node `http` transport this scaffold's `mcps/todo/src/server.ts`
+already uses:
+
+```ts
+import { createHash } from "node:crypto";
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { withGuueyContext, scopeFromAuthorization, kv, QuotaExceededError } from "@guuey/state";
+
+// Inside the per-request handler (see mcps/todo/src/server.ts for the
+// full StreamableHTTPServerTransport wiring this drops into):
+async function handleRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+  const authHeader = req.headers.authorization;
+  if (typeof authHeader !== "string") {
+    res.writeHead(401).end();
+    return;
+  }
+
+  await withGuueyContext(scopeFromAuthorization(authHeader), async () => {
+    // ... hand off to your MCP transport/tool dispatch here; the
+    // AsyncLocalStorage context set above is visible to every `kv.*`
+    // call for the lifetime of this request, however deep the call
+    // stack goes (tool handlers, helper functions, etc.).
+    await handleCreateOrder({ orderPayload: "..." });
+  });
+}
+
+async function handleCreateOrder(input: { orderPayload: string }): Promise<{ duplicate: boolean }> {
+  const idempotencyKey = `order:${createHash("sha256").update(input.orderPayload).digest("hex")}`;
+
+  if (await kv.has(idempotencyKey)) {
+    return { duplicate: true };
+  }
+
+  try {
+    // TTL is required on every `set` — no permanent keys. Pick a window
+    // that covers realistic retry storms; 1 hour is a reasonable default
+    // for an idempotency key.
+    await kv.set(idempotencyKey, true, { ttl: 60 * 60 });
+  } catch (err) {
+    if (err instanceof QuotaExceededError) {
+      // The (user, mcp) scope hit its 1 MiB cap. Surface this to the
+      // caller instead of silently dropping the idempotency guard.
+      throw new Error("state quota exceeded — cannot verify idempotency");
+    }
+    throw err;
+  }
+
+  // ... actually create the order here.
+  return { duplicate: false };
+}
+```
+
+`scopeFromAuthorization` derives `{ userId, mcpId }` from the inbound
+`Authorization: Bearer <jwt>` header guuey sends on every federated call —
+`userId` from the JWT's `sub`, `mcpId` deterministically from its `aud`
+(your server's federated resource URL). You never assert either id
+yourself; a mismatched or missing token is rejected server-side.
+
+## The hard caps (design your data model around these, don't work around them)
+
+`@guuey/state` is a KV, not a database — enforced, not a suggestion:
+
+| Cap                | Value                                         |
+| ------------------ | --------------------------------------------- |
+| Scope size         | 1 MiB (per `(user, mcp)`, key bytes included) |
+| Single value       | 64 KiB                                        |
+| TTL                | required, ≤ 90 days — no permanent keys       |
+| `keys()` page size | ≤ 1000                                        |
+| `mget()` batch     | ≤ 100 keys                                    |
+| Counters           | safe integers only (`increment`/`decrement`)  |
+
+If your data model needs more than this — queries, joins, cross-user
+data, anything past a long tail of small per-user facts — that's the
+signal to use the managed-DB row above, not to fight the cap.
+
+## Chat history: really, don't
+
+If you find yourself writing message transcripts to `@guuey/state`,
+`$GUUEY_HOME_DIR`, or an external DB keyed by conversation, stop — that's
+the platform's job. Guuey persists every thread to DynamoDB and streams
+history back over AppSync subscriptions; the client and Portal already
+read it from there. A parallel, agent-owned history store will drift from
+the platform's copy and confuse users about which one is authoritative.

package/dist/templates/base/openai-agents-sdk/README.md

@@ -0,0 +1,173 @@
+# 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 → colocated source + devPort), 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/ — generative-UI config.
+│                         #   `ggui serve` runs against this locally; `guuey deploy` pushes
+│                         #   generation config + blueprints (the deployed RENDER THEME is
+│                         #   platform data, not this dir — ggui.json#theme is local-preview
+│                         #   only, kept in step with guuey.app.json by `pnpm bootstrap`).
+├── web/                 # the product frontend (Vite + React on @guuey/chat):
+│                         #   landing (widget) · login (guest + BYO-OIDC seam) · home
+│                         #   (status + distribution guide) · the chat surface
+├── guuey.app.json       # frontend/brand config — written by `pnpm bootstrap`
+│                         #   (schema: guuey.app.schema.json; public-safe by design)
+├── AGENTS.md            # coding-agent steering; `pnpm bootstrap` maintains the
+│                         #   managed block with this project's real facts
+├── scripts/dev.mjs      # `pnpm dev` orchestrator — boots the whole local stack
+├── scripts/bootstrap.mjs # `pnpm bootstrap` — configure, then `-- --link` to bind
+├── .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
+pnpm bootstrap               # brand, theme, copy → guuey.app.json + AGENTS.md (no account needed;
+                             #   every web page is gated on this, and production builds fail without it)
+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
+```
+
+When the agent is deployed (`guuey login && guuey deploy`), bind it into the
+frontend: `pnpm bootstrap -- --link` — that records the app id, endpoint,
+widget origin and portal link in `guuey.app.json` and pushes brand basics to
+the platform. `pnpm status` shows the live app state; `pnpm bootstrap -- --check`
+prints machine-readable configuration state.
+
+`pnpm dev` (`scripts/dev.mjs`) boots four 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; auto-spawns every `colocated` MCP entry — `mcps/todo` lands on its `devPort` :6782 |
+| `ggui serve` | :6781 | local generative-UI server, over `ggui/`                                                                                                   |
+| `web`        | :6890 | the product frontend (landing/login/home/chat on @guuey/chat)                                                                              |
+
+The todo MCP still answers on :6782 — it's just a supervised child of
+`guuey dev` now (copy `mcps/todo/` to add your own server; new `colocated`
+entries in `guuey.json` are auto-spawned the same way).
+
+> **If a server's deps carry build scripts** (the classic: `tsx` → esbuild's
+> platform-binary fetch), pnpm ≥11 refuses to run them on a fresh install —
+> `ERR_PNPM_IGNORED_BUILDS` — and the server never boots. Approve the
+> specific packages declaratively in the workspace-root `package.json` (or
+> the server's own, for a standalone install):
+> `"pnpm": { "onlyBuiltDependencies": ["esbuild"] }`. This scaffold ships
+> the approval already; add to the list when a new dep needs its build step.
+> Don't disable the gate wholesale — it's pnpm's supply-chain protection.
+
+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:
+two that only matter once real users and real money are involved, and one
+you should read twice:
+
+- **No sandboxing — read this one twice.** Locally your worker runs as a
+  plain child process: no `bwrap`/gVisor isolation on any platform, it
+  inherits your **full shell environment** (every variable, including
+  credentials unrelated to this agent), and when filesystem layers are
+  bound the host grants the agent shell and file tools **without
+  prompting** (the production jail those tools assume does not exist
+  locally). Net: `guuey dev` runs an LLM-driven agent with unprompted
+  shell access as you, with your env. That's a deliberate dev-trust
+  posture, not an accident — treat the agent like any script you'd run
+  from the internet: run `guuey dev` in a throwaway shell/container with
+  a minimal environment if your agent (or any MCP server it talks to)
+  handles untrusted input. In production every invocation runs inside a
+  gVisor-isolated pod with only its declared environment.
+- **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. Locally, `guuey dev` auto-spawns each
+`colocated` entry on its `devPort` and points the agent at
+`localhost:<devPort>`; deployed, the same server code runs as a supervised
+child inside your agent's pod, reached over the pod's loopback with a
+per-request federated identity. (`hosted` entries deploy to the platform's
+federated URLs; locally they need a `devPort` pointing at a server you run
+yourself, or they're skipped with a warning.)
+
+## 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`
+   as its own hosted MCP server (build → deploy → registry), then writes the
+   resulting server id back into `guuey.json`. This scaffold has none — the
+   todo MCP is `colocated`, so this leg is a no-op here.
+2. **ggui asset leg** — pushes `ggui/` (generation config, blueprints) to your
+   app's guuey-managed ggui instance.
+3. **Agent leg** — builds `src/worker.ts` into `guuey.worker.js`, packs the
+   project root (including `mcps/`), and deploys it as a gVisor-isolated,
+   scale-to-zero pod. Each `colocated` entry (e.g. `mcps/todo`) is built into
+   the worker image and auto-spawned as a supervised, sandboxed child at pod
+   boot — no separate server, registry row, or write-back.
+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.
+
+## Filesystem + memory
+
+Every deployed invoke gets three bound directories — `$GUUEY_HOME_DIR`
+(durable, per-user), `$GUUEY_APP_DIR` (read-only, shared), and cwd (session
+scratch) — plain `node:fs`, no wrapper API required. Signed-in users get
+durable cross-session memory for free (a platform-owned prompt tells the
+model to read/write `$GUUEY_HOME_DIR/memories/MEMORY.md`); guests never get
+durable storage, by design. **This recall is `claude-agent-sdk`-only today**
+— openai-agents-sdk and google-adk agents get the three bound directories
+but not the automatic memory-file recall; all-framework support arrives
+with guuey's own memory MCP (a platform tool every framework can call over
+its existing MCP channel). Framework-native memory backends (e.g. ADK's
+Vertex MemoryBank) are unsupported on Guuey — they'd store user data
+outside guuey's deletion boundary. Full contract, code examples, and
+rollout status: the "Your agent's filesystem" section of the guuey
+monorepo's `docs/quickstart.md`, or
+[`@guuey/fs`](https://www.npmjs.com/package/@guuey/fs)'s own README — an
+optional, three-helper sugar layer over the same paths.
+
+## 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/base/openai-agents-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/base/openai-agents-sdk/gitignore

@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.env.local
+guuey.worker.js
+.guuey-dev/