@guuey/create-agentic-app 0.1.3 → 0.1.4

package/README.md

@@ -29,3 +29,13 @@ guuey deploy        # hosted: agent + MCP servers live on guuey
 ```
 npx @guuey/create-agentic-app <dir> [--framework claude-agent-sdk|openai-agents-sdk] [--skip-install]
 ```
+
+## Binding to an existing app
+
+`guuey deploy` (above) creates a new app on first run. To bind this
+scaffold to an app you already have — including a no-code agent built in
+[Studio](https://studio.guuey.com) — run `guuey pull --app-id <id>` instead: it
+refreshes `guuey.json`'s `appId`, and for a Studio no-code app pulls the
+Studio-authored system prompt/model/MCP servers down into the scaffold too.
+There is no `guuey link` command — `guuey pull --app-id` is the only way
+to bind a project to an existing app.

package/dist/templates/claude-agent-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
+(`src/worker.ts`'s agent pod — 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** (`src/worker.ts`)                                         | [`@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/claude-agent-sdk/README.md

@@ -9,7 +9,7 @@ locally with one command, and deployable to guuey with one more.
 ```
 .
 ├── guuey.json          # the deploy contract: agent framework/model, system prompt,
-│                        #   mcpServers (name → local dev port / hosted source), ggui config
+│                        #   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
@@ -38,16 +38,19 @@ cp .env.example .env.local   # done automatically on scaffold if .env.local is a
 pnpm dev
 ```
 
-`pnpm dev` (`scripts/dev.mjs`) boots five processes with prefixed, interleaved
+`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       |
-| `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                                            |
+| 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 Vite chat SPA                                                                                                                          |
+
+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).
 
 Open http://localhost:6890 to chat with your agent locally.
 
@@ -68,9 +71,13 @@ that only matter once real users and real money are involved:
   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).
+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
 
@@ -83,17 +90,40 @@ guuey deploy   # ships everything
 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`.
+   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/` (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.
+   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

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

@@ -6,7 +6,7 @@
     "model": "claude-sonnet-5",
     "systemPrompt": { "file": "prompts/system.md" },
     "mcpServers": {
-      "todo": { "kind": "hosted", "source": "./mcps/todo", "devPort": 6782 }
+      "todo": { "kind": "colocated", "source": "./mcps/todo", "devPort": 6782 }
     }
   },
   "ggui": { "configFile": "./ggui/ggui.json" }

package/dist/templates/claude-agent-sdk/mcps/todo/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "tsx src/server.ts",
-    "build": "tsup src/server.ts --format esm -d dist",
+    "build": "tsup",
     "start": "node dist/server.js",
     "typecheck": "tsc --noEmit"
   },

package/dist/templates/claude-agent-sdk/mcps/todo/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+
+// Self-contained ON PURPOSE — do not delete this file. Without a local
+// config, tsup's upward config discovery finds the scaffold ROOT
+// tsup.config.ts; its bundled form imports 'tsup' from the scaffold root,
+// which the platform image build deliberately leaves un-installed when the
+// bundled guuey.worker.js skips the root install — every colocated build
+// then dies with ERR_MODULE_NOT_FOUND (guuey#19). A config here stops the
+// walk; `defineConfig` resolves from this package's own devDependencies.
+export default defineConfig({
+  entry: ['src/server.ts'],
+  format: 'esm',
+  outDir: 'dist',
+});

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

@@ -10,11 +10,11 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.199",
-    "@guuey/config": "0.1.1",
+    "@guuey/config": "0.1.2",
     "@guuey/worker": "0.1.1"
   },
   "devDependencies": {
-    "@guuey/cli": "0.1.3",
+    "@guuey/cli": "0.1.4",
     "tsup": "^8.5.0",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0"

package/dist/templates/claude-agent-sdk/scripts/dev.mjs

@@ -29,10 +29,11 @@ if (!existsSync(".env.local"))
   console.warn("hint: cp .env.example .env.local and set your LLM key");
 
 boot("worker", "pnpm", ["exec", "tsup", "--watch"]); // rebuilds guuey.worker.js on change
+// `guuey dev` auto-spawns every `kind: 'colocated'` mcpServers entry itself
+// (name→localhost devPort resolution) — the todo MCP is colocated, so it no
+// longer needs its own boot() here; a manual second spawn would double-bind
+// :6782 and crash with EADDRINUSE.
 boot("agent", "pnpm", ["exec", "guuey", "dev", "--serve", "--port", "6790"]);
-boot("todo", "pnpm", ["--filter", "@agentic-app-template/todo-mcp", "dev"], {
-  env: { ...process.env, PORT: "6782" },
-});
 boot("ggui", "pnpm", ["exec", "ggui", "serve", "--mcp-only", "--dev-allow-all", "--port", "6781"], {
   cwd: "ggui",
 });

package/dist/templates/google-adk/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
+(`src/worker.ts`'s agent pod — 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** (`src/worker.ts`)                                         | [`@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/google-adk/README.md

@@ -12,7 +12,8 @@ import type { GuueyContext } from "@guuey/config";
 export default (guuey: GuueyContext<MCPToolset>) =>
   new LlmAgent({
     model: guuey.model,
-    instruction: guuey.instruction,
+    // Wrapped as a function — see the "instruction" row below.
+    instruction: () => guuey.instruction,
     tools: [myTool, ...guuey.mcpToolsets],
   });
 ```
@@ -30,24 +31,24 @@ guuey deploy                    # same code, hosted
 
 Your factory runs **once per turn** and receives:
 
-| field                                 | what it is                                                                                                                                        |
-| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `model`                               | resolved model id (from `guuey.json`, registry default otherwise)                                                                                 |
-| `instruction`                         | your system prompt **with the conversation preamble already prepended** — feed it to the agent and it is conversational with zero state code      |
-| `mcpToolsets`                         | ready-to-use ADK `MCPToolset`s for every server in `guuey.json#mcpServers` — credentials, URLs, and auth headers already resolved by the platform |
-| `user`                                | the end user this turn serves: `{ id, authMode }` — build multi-tenant behavior on `user.id`                                                      |
-| `files`                               | three storage tiers (absolute paths — see the state map below)                                                                                    |
-| `history` / `memory` / `workingState` | the raw conversation state, if you want to render context yourself instead of using `instruction`                                                 |
+| field                                 | what it is                                                                                                                                                                                                                                                                                                                                                                                        |
+| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model`                               | resolved model id (from `guuey.json`, registry default otherwise)                                                                                                                                                                                                                                                                                                                                 |
+| `instruction`                         | your system prompt **with the conversation preamble already prepended** — feed it to the agent and it is conversational with zero state code. **Pass it as `() => guuey.instruction`, not a bare string** — ADK applies `{var}` session-state substitution to a string instruction, and the preamble embeds prior user messages verbatim; a message containing `{anything}` would crash the turn. |
+| `mcpToolsets`                         | ready-to-use ADK `MCPToolset`s for every server in `guuey.json#mcpServers` — credentials, URLs, and auth headers already resolved by the platform                                                                                                                                                                                                                                                 |
+| `user`                                | the end user this turn serves: `{ id, authMode }` — build multi-tenant behavior on `user.id`                                                                                                                                                                                                                                                                                                      |
+| `files`                               | three storage tiers (absolute paths — see the state map below)                                                                                                                                                                                                                                                                                                                                    |
+| `history` / `memory` / `workingState` | the raw conversation state, if you want to render context yourself instead of using `instruction`                                                                                                                                                                                                                                                                                                 |
 
 ## Where state lives (the three-tier map)
 
-| you want to…                                                     | use                                                                                                                            | persistence                                                                                                                                                         |
-| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| save/read **files** from agent code or tools                     | `guuey.files.home` (per-USER durable) · `guuey.files.session` (per-session scratch) · `guuey.files.app` (read-only app assets) | `home` survives across sessions per user                                                                                                                            |
-| have the agent **remember the conversation**                     | nothing — `instruction` already carries history + thread memory + working state                                                | automatic (Guuey folds every turn)                                                                                                                                  |
-| store data from your **MCP server's tools** (e.g. the todo list) | `@guuey/state` KV inside the MCP server — scoped per `(user, server)`                                                          | **in-memory in the current release** (durable managed KV + console export/delete is on the roadmap) — persist anything you can't lose to `guuey.files.home` for now |
+| you want to…                                                     | use                                                                                                                            | persistence                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| save/read **files** from agent code or tools                     | `guuey.files.home` (per-USER durable) · `guuey.files.session` (per-session scratch) · `guuey.files.app` (read-only app assets) | `home` survives across sessions per user                                                                                                                                                                                      |
+| have the agent **remember the conversation**                     | nothing — `instruction` already carries history + thread memory + working state                                                | automatic (Guuey folds every turn)                                                                                                                                                                                            |
+| store data from your **MCP server's tools** (e.g. the todo list) | `@guuey/state` KV inside the MCP server — scoped per `(user, server)`                                                          | **durable when `GUUEY_KV_URL` is injected — colocated (like `mcps/todo`) and hosted servers get it automatically on deploy**; the scope survives pod restarts and redeploys. Locally (`pnpm dev`) it falls back to in-memory. |
 
-Two honest notes:
+Three honest notes:
 
 - **ADK-native session state does not persist across turns here.** Guuey
   runs your agent with a fresh `InMemoryRunner` per turn (that's what makes
@@ -57,12 +58,27 @@ Two honest notes:
   pre-rendered in `instruction`.
 - **Writing `workingState` for the next turn** is a platform feature in
   flight; today the fold carries what the conversation itself establishes.
+- **Guuey's cross-session `MEMORY.md` file recall is `claude-agent-sdk`-only
+  today** — ADK agents get `guuey.files.home` for their own reads/writes,
+  but not the platform's automatic recall of it into `instruction`.
+  All-framework support arrives with guuey's own memory MCP. Separately,
+  ADK's own durable-memory feature (Vertex MemoryBank) is unsupported on
+  Guuey — it stores user data in GCP, outside guuey's deletion boundary.
+
+The three `guuey.files` paths above are the same platform-wide filesystem
+contract every framework gets (plain paths, `$GUUEY_HOME_DIR`/
+`$GUUEY_APP_DIR` under the hood) — see the guuey monorepo's
+`docs/quickstart.md` ("Your agent's filesystem") for the full contract,
+memory behavior, and rollout status if you want the framework-neutral
+version.
 
 ## MCP servers
 
 `guuey.json#mcpServers` declares them; the platform connects them and hands
-you `guuey.mcpToolsets`. Locally, `pnpm dev` boots the colocated `mcps/todo`
-server on its `devPort`. Note: ADK speaks **Streamable HTTP** only — an
+you `guuey.mcpToolsets`. Locally, `pnpm dev`'s `guuey dev` auto-spawns the
+colocated `mcps/todo` server on its `devPort`; deployed, the same code runs
+as a supervised child inside your agent's pod. Note: ADK speaks
+**Streamable HTTP** only — an
 `sse` transport server will be rejected with a clear error.
 
 ## When you outgrow the factory

package/dist/templates/google-adk/guuey.json

@@ -3,11 +3,11 @@
   "agent": {
     "mode": "code",
     "framework": "google-adk",
-    "model": "gemini-3.5-flash",
+    "model": "gemini-3.6-flash",
     "entry": "agent.js",
     "systemPrompt": { "file": "prompts/system.md" },
     "mcpServers": {
-      "todo": { "kind": "hosted", "source": "./mcps/todo", "devPort": 6782 }
+      "todo": { "kind": "colocated", "source": "./mcps/todo", "devPort": 6782 }
     }
   },
   "ggui": { "configFile": "./ggui/ggui.json" }

package/dist/templates/google-adk/mcps/todo/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "tsx src/server.ts",
-    "build": "tsup src/server.ts --format esm -d dist",
+    "build": "tsup",
     "start": "node dist/server.js",
     "typecheck": "tsc --noEmit"
   },

package/dist/templates/google-adk/mcps/todo/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+
+// Self-contained ON PURPOSE — do not delete this file. Without a local
+// config, tsup's upward config discovery finds the scaffold ROOT
+// tsup.config.ts; its bundled form imports 'tsup' from the scaffold root,
+// which the platform image build deliberately leaves un-installed when the
+// bundled guuey.worker.js skips the root install — every colocated build
+// then dies with ERR_MODULE_NOT_FOUND (guuey#19). A config here stops the
+// walk; `defineConfig` resolves from this package's own devDependencies.
+export default defineConfig({
+  entry: ['src/server.ts'],
+  format: 'esm',
+  outDir: 'dist',
+});

package/dist/templates/google-adk/package.json

@@ -13,10 +13,10 @@
     "zod": "^4.2.1"
   },
   "devDependencies": {
-    "@guuey/cli": "0.1.3",
+    "@guuey/cli": "0.1.4",
     "tsup": "^8.5.0",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0",
-    "@guuey/config": "0.1.1"
+    "@guuey/config": "0.1.2"
   }
 }

package/dist/templates/google-adk/scripts/dev.mjs

@@ -29,10 +29,11 @@ if (!existsSync(".env.local"))
   console.warn("hint: cp .env.example .env.local and set your LLM key");
 
 boot("worker", "pnpm", ["exec", "tsup", "--watch"]); // rebuilds guuey.worker.js on change
+// `guuey dev` auto-spawns every `kind: 'colocated'` mcpServers entry itself
+// (name→localhost devPort resolution) — the todo MCP is colocated, so it no
+// longer needs its own boot() here; a manual second spawn would double-bind
+// :6782 and crash with EADDRINUSE.
 boot("agent", "pnpm", ["exec", "guuey", "dev", "--serve", "--port", "6790"]);
-boot("todo", "pnpm", ["--filter", "@agentic-app-template/todo-mcp", "dev"], {
-  env: { ...process.env, PORT: "6782" },
-});
 boot("ggui", "pnpm", ["exec", "ggui", "serve", "--mcp-only", "--dev-allow-all", "--port", "6781"], {
   cwd: "ggui",
 });

package/dist/templates/google-adk/src/agent.ts

@@ -31,8 +31,12 @@ export default (guuey: GuueyContext<MCPToolset>) =>
     model: guuey.model,
     // `instruction` already carries your system prompt PLUS the conversation
     // preamble (history, thread memory, working state) — your agent is
-    // conversational without writing any state code.
-    instruction: guuey.instruction,
+    // conversational without writing any state code. Wrapped as a function:
+    // ADK applies `{var}` session-state substitution to a STRING instruction,
+    // and the preamble embeds prior user messages verbatim — if one contains
+    // `{anything}`, a string instruction crashes the turn. The function form
+    // bypasses substitution entirely.
+    instruction: () => guuey.instruction,
     // Your own tools compose with the MCP servers from guuey.json. Drop
     // `...guuey.mcpToolsets` if you want a fully self-contained agent.
     tools: [rollDice, ...guuey.mcpToolsets],

package/dist/templates/mcp-base/src/server.ts

@@ -25,6 +25,24 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { z } from "zod";
 
+// ─────────────────────────────────────────────────────────────────────────
+// Optional: per-user durable state via `@guuey/state`.
+//
+// Hosted (`kind: 'hosted'`) and colocated (`kind: 'colocated'`) MCP servers
+// get `GUUEY_KV_URL` (and a per-request auth token) injected automatically —
+// zero setup, state just works. A `dev-hosted` external server (your own
+// `kind: 'external', federate: true` deployment reached over a real URL)
+// sets `GUUEY_KV_URL` itself, per the package README.
+//
+// Uncomment to try it: `pnpm add @guuey/state` (not yet on npm as of this
+// scaffold — developer preview, see the guuey monorepo's publish runbook —
+// so it's commented rather than a hard dependency, to keep this starter
+// installing cleanly out of the box), then uncomment the import + the
+// `withGuueyContext(...)` wrapper below.
+//
+// import { withGuueyContext, scopeFromAuthorization, kv } from "@guuey/state";
+// ─────────────────────────────────────────────────────────────────────────
+
 const SERVER_NAME = "NAME_PLACEHOLDER-mcp";
 
 /** Wrap a structured result as both `structuredContent` and a text block. */
@@ -35,6 +53,9 @@ function toolResult(data: Record<string, unknown>) {
   };
 }
 
+// To uncomment the `@guuey/state` example below, change this signature to
+// `buildMcpServer(authHeader: string | undefined)` and pass
+// `req.headers.authorization` at the one call site further down.
 function buildMcpServer(): McpServer {
   const server = new McpServer({
     name: SERVER_NAME,
@@ -53,6 +74,32 @@ function buildMcpServer(): McpServer {
     async ({ message }) => toolResult({ message }),
   );
 
+  // ── Example: a durable, per-user tool via `@guuey/state` (uncomment) ──
+  //
+  // server.registerTool(
+  //   "remember",
+  //   {
+  //     title: "Remember",
+  //     description: "Store a value under a key, scoped to the calling user.",
+  //     inputSchema: {
+  //       key: z.string().min(1),
+  //       value: z.string(),
+  //     },
+  //     outputSchema: { stored: z.boolean() },
+  //   },
+  //   async ({ key, value }) => {
+  //     if (!authHeader) throw new Error("missing Authorization header");
+  //     return withGuueyContext(scopeFromAuthorization(authHeader), async () => {
+  //       await kv.set(key, value, { ttl: 60 * 60 * 24 * 7 }); // 7 days
+  //       return toolResult({ stored: true });
+  //     });
+  //   },
+  // );
+  //
+  // A companion "recall" tool would mirror this with `await kv.get(key)`.
+  // See `@guuey/state`'s README for the full API (increment/decrement,
+  // keys(), scope() usage quota, etc).
+
   return server;
 }
 
@@ -73,6 +120,8 @@ const httpServer = createServer(async (req: IncomingMessage, res: ServerResponse
   }
 
   // Fresh server + transport per request (stateless mode) — see module doc.
+  // (`buildMcpServer(req.headers.authorization)` once the `@guuey/state`
+  // example above is uncommented.)
   const mcp = buildMcpServer();
   const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
 

package/dist/templates/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
+(`src/worker.ts`'s agent pod — 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** (`src/worker.ts`)                                         | [`@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/openai-agents-sdk/README.md

@@ -9,7 +9,7 @@ locally with one command, and deployable to guuey with one more.
 ```
 .
 ├── guuey.json          # the deploy contract: agent framework/model, system prompt,
-│                        #   mcpServers (name → local dev port / hosted source), ggui config
+│                        #   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
@@ -38,16 +38,19 @@ cp .env.example .env.local   # done automatically on scaffold if .env.local is a
 pnpm dev
 ```
 
-`pnpm dev` (`scripts/dev.mjs`) boots five processes with prefixed, interleaved
+`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       |
-| `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                                            |
+| 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 Vite chat SPA                                                                                                                          |
+
+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).
 
 Open http://localhost:6890 to chat with your agent locally.
 
@@ -68,9 +71,13 @@ that only matter once real users and real money are involved:
   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).
+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
 
@@ -83,17 +90,40 @@ guuey deploy   # ships everything
 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`.
+   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/` (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.
+   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

package/dist/templates/openai-agents-sdk/guuey.json

@@ -1,13 +1,22 @@
 {
   "schema": "1",
+  "worker": "worker.js",
   "agent": {
     "mode": "code",
     "framework": "openai-agents-sdk",
-    "model": "gpt-5.5",
-    "systemPrompt": { "file": "prompts/system.md" },
+    "model": "gpt-5.6-terra",
+    "systemPrompt": {
+      "file": "prompts/system.md"
+    },
     "mcpServers": {
-      "todo": { "kind": "hosted", "source": "./mcps/todo", "devPort": 6782 }
+      "todo": {
+        "kind": "colocated",
+        "source": "./mcps/todo",
+        "devPort": 6782
+      }
     }
   },
-  "ggui": { "configFile": "./ggui/ggui.json" }
+  "ggui": {
+    "configFile": "./ggui/ggui.json"
+  }
 }

package/dist/templates/openai-agents-sdk/mcps/todo/package.json

@@ -5,7 +5,7 @@
   "type": "module",
   "scripts": {
     "dev": "tsx src/server.ts",
-    "build": "tsup src/server.ts --format esm -d dist",
+    "build": "tsup",
     "start": "node dist/server.js",
     "typecheck": "tsc --noEmit"
   },

package/dist/templates/openai-agents-sdk/mcps/todo/tsup.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsup';
+
+// Self-contained ON PURPOSE — do not delete this file. Without a local
+// config, tsup's upward config discovery finds the scaffold ROOT
+// tsup.config.ts; its bundled form imports 'tsup' from the scaffold root,
+// which the platform image build deliberately leaves un-installed when the
+// bundled guuey.worker.js skips the root install — every colocated build
+// then dies with ERR_MODULE_NOT_FOUND (guuey#19). A config here stops the
+// walk; `defineConfig` resolves from this package's own devDependencies.
+export default defineConfig({
+  entry: ['src/server.ts'],
+  format: 'esm',
+  outDir: 'dist',
+});

package/dist/templates/openai-agents-sdk/package.json

@@ -10,11 +10,11 @@
   },
   "dependencies": {
     "@openai/agents": "^0.12.0",
-    "@guuey/config": "0.1.1",
+    "@guuey/config": "0.1.2",
     "@guuey/worker": "0.1.1"
   },
   "devDependencies": {
-    "@guuey/cli": "0.1.3",
+    "@guuey/cli": "0.1.4",
     "tsup": "^8.5.0",
     "tsx": "^4.19.0",
     "typescript": "^5.8.0"

package/dist/templates/openai-agents-sdk/scripts/dev.mjs

@@ -29,10 +29,11 @@ if (!existsSync(".env.local"))
   console.warn("hint: cp .env.example .env.local and set your LLM key");
 
 boot("worker", "pnpm", ["exec", "tsup", "--watch"]); // rebuilds guuey.worker.js on change
+// `guuey dev` auto-spawns every `kind: 'colocated'` mcpServers entry itself
+// (name→localhost devPort resolution) — the todo MCP is colocated, so it no
+// longer needs its own boot() here; a manual second spawn would double-bind
+// :6782 and crash with EADDRINUSE.
 boot("agent", "pnpm", ["exec", "guuey", "dev", "--serve", "--port", "6790"]);
-boot("todo", "pnpm", ["--filter", "@agentic-app-template/todo-mcp", "dev"], {
-  env: { ...process.env, PORT: "6782" },
-});
 boot("ggui", "pnpm", ["exec", "ggui", "serve", "--mcp-only", "--dev-allow-all", "--port", "6781"], {
   cwd: "ggui",
 });

package/dist/templates/openai-agents-sdk/tsup.config.ts

@@ -1,9 +1,16 @@
 import { defineConfig } from "tsup";
 
 export default defineConfig({
-  entry: { "guuey.worker": "src/worker.ts" },
+  entry: { worker: "src/worker.ts" },
   format: ["esm"],
   outDir: ".",
   clean: false,
-  noExternal: [/./], // bundle everything — the deploy tarball must be runnable via `node guuey.worker.js`
+  // Dependencies stay EXTERNAL (tsup's default): @openai/agents' dependency
+  // tree is not ESM-bundle-safe (debug's dynamic require("tty"); circular
+  // class hierarchies in its MCP module — both crash a noExternal bundle at
+  // boot, caught by the first live openai pod gate). The platform installs
+  // deps from the lockfile at image-build time — the same registry-install
+  // path the google-adk graceful lane uses. The output is `worker.js` (via
+  // guuey.json#worker): the `guuey.worker.js` name specifically means
+  // "self-contained, skip install" to the platform's image build.
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guuey/create-agentic-app",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Scaffold a guuey agentic app: code-mode agent + custom MCP + ggui + web, local pnpm dev, one-command guuey deploy.",
   "license": "MIT",
   "type": "module",
@@ -22,7 +22,7 @@
     "tsup": "^8.5.0",
     "typescript": "^5.8.0",
     "vitest": "^3.2.4",
-    "@guuey/config": "0.1.1"
+    "@guuey/config": "0.1.2"
   },
   "publishConfig": {
     "access": "public"