@alexkroman1/aai-cli 6.8.0 → 6.10.0

package/dist/cli.mjs

@@ -760,68 +760,95 @@ const storageDir = {
 	description: "Project directory",
 	required: false
 };
+const storageStatus = defineExec({
+	meta: {
+		name: "status",
+		description: "Show whether storage is enabled"
+	},
+	args: {
+		dir: storageDir,
+		server: sharedArgs.server,
+		json: sharedArgs.json
+	},
+	cwd: "any",
+	async run({ args, cwd }) {
+		const { executeStorageStatus } = await import("./storage-DzRZ-eCw.mjs");
+		return executeStorageStatus(resolveStorageCwd(cwd, args.dir), args.server);
+	}
+});
+const storageEnable = defineExec({
+	meta: {
+		name: "enable",
+		description: "Enable the agent's app database"
+	},
+	args: {
+		dir: storageDir,
+		server: sharedArgs.server,
+		json: sharedArgs.json
+	},
+	cwd: "any",
+	async run({ args, cwd }) {
+		const { executeStorageEnable } = await import("./storage-DzRZ-eCw.mjs");
+		return executeStorageEnable(resolveStorageCwd(cwd, args.dir), args.server);
+	}
+});
+const storageDisable = defineExec({
+	meta: {
+		name: "disable",
+		description: "Disable storage and DROP the database schema with all its data"
+	},
+	args: {
+		dir: storageDir,
+		force: {
+			type: "boolean",
+			alias: "f",
+			description: "Skip confirmation prompt"
+		},
+		server: sharedArgs.server,
+		json: sharedArgs.json
+	},
+	cwd: "any",
+	async run({ args, cwd }) {
+		const { executeStorageDisable } = await import("./storage-DzRZ-eCw.mjs");
+		return executeStorageDisable(resolveStorageCwd(cwd, args.dir), {
+			server: args.server,
+			force: args.force
+		});
+	}
+});
+const logs = defineExec({
+	meta: {
+		name: "logs",
+		description: "Show what the deployed agent has printed"
+	},
+	args: {
+		dir: storageDir,
+		follow: {
+			type: "boolean",
+			alias: "f",
+			description: "Keep printing new output"
+		},
+		server: sharedArgs.server,
+		json: sharedArgs.json
+	},
+	cwd: "any",
+	async run({ args, cwd }) {
+		const { executeLogs } = await import("./logs-BWVGSjLR.mjs");
+		return executeLogs(resolveStorageCwd(cwd, args.dir), {
+			server: args.server,
+			follow: args.follow
+		});
+	}
+});
 const storage = defineCommand({
 	meta: {
 		name: "storage",
 		description: "Manage the agent's app database"
 	},
 	subCommands: {
-		status: defineExec({
-			meta: {
-				name: "status",
-				description: "Show whether storage is enabled"
-			},
-			args: {
-				dir: storageDir,
-				server: sharedArgs.server,
-				json: sharedArgs.json
-			},
-			cwd: "any",
-			async run({ args, cwd }) {
-				const { executeStorageStatus } = await import("./storage-DzRZ-eCw.mjs");
-				return executeStorageStatus(resolveStorageCwd(cwd, args.dir), args.server);
-			}
-		}),
-		enable: defineExec({
-			meta: {
-				name: "enable",
-				description: "Enable the agent's app database"
-			},
-			args: {
-				dir: storageDir,
-				server: sharedArgs.server,
-				json: sharedArgs.json
-			},
-			cwd: "any",
-			async run({ args, cwd }) {
-				const { executeStorageEnable } = await import("./storage-DzRZ-eCw.mjs");
-				return executeStorageEnable(resolveStorageCwd(cwd, args.dir), args.server);
-			}
-		}),
-		disable: defineExec({
-			meta: {
-				name: "disable",
-				description: "Disable storage and DROP the database schema with all its data"
-			},
-			args: {
-				dir: storageDir,
-				force: {
-					type: "boolean",
-					alias: "f",
-					description: "Skip confirmation prompt"
-				},
-				server: sharedArgs.server,
-				json: sharedArgs.json
-			},
-			cwd: "any",
-			async run({ args, cwd }) {
-				const { executeStorageDisable } = await import("./storage-DzRZ-eCw.mjs");
-				return executeStorageDisable(resolveStorageCwd(cwd, args.dir), {
-					server: args.server,
-					force: args.force
-				});
-			}
-		})
+		status: storageStatus,
+		enable: storageEnable,
+		disable: storageDisable
 	}
 });
 const mainCommand = defineCommand({
@@ -854,6 +881,7 @@ const mainCommand = defineCommand({
 			}
 		}),
 		secret,
+		logs,
 		storage,
 		workflow,
 		templates: defineExec({

package/dist/logs-BWVGSjLR.mjs

@@ -0,0 +1,74 @@
+#!/usr/bin/env node
+import { a as ok } from "./_output-CKkmWs7i.mjs";
+import { n as log } from "./_ui-u7T4YooX.mjs";
+import { f as checkedResponse } from "./_studio-U3jhKlA3.mjs";
+import { n as slugRequest } from "./_slug-api-BxrsJXVI.mjs";
+import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
+import { sleep } from "@alexkroman1/aai/internal";
+function isLogsPage(value) {
+	return isRecord(value) && Array.isArray(value.lines) && typeof value.cursor === "number" && typeof value.running === "boolean";
+}
+/** `HH:MM:SS.mmm`, local — the same shape the studio pane prints. */
+function formatTime(at) {
+	const d = new Date(at);
+	const pad = (n, width = 2) => String(n).padStart(width, "0");
+	return `${pad(d.getHours())}:${pad(d.getMinutes())}:${pad(d.getSeconds())}.${pad(d.getMilliseconds(), 3)}`;
+}
+/** One rendered line: time, then the text. `stderr` is called out by name. */
+function formatLine(line) {
+	const mark = line.stream === "stderr" ? " ERR" : "";
+	return `${formatTime(line.at)}${mark}  ${line.text}`;
+}
+async function readPage(cwd, after, server) {
+	const { data, slug } = await slugRequest(cwd, `/logs?after=${after}`, { action: "logs" }, server);
+	return {
+		page: checkedResponse(data, isLogsPage, `the logs route for ${slug}`),
+		slug
+	};
+}
+/**
+* Print the agent's buffered output, once or continuously.
+*
+* The `--json` shape reports the LINE COUNT rather than the lines: a follow
+* loop has no final count to report, and a one-shot read that dumped every line
+* into a result object would duplicate what it just printed.
+*/
+async function executeLogs(cwd, opts = {}) {
+	const { page, slug } = await readPage(cwd, -1, opts.server);
+	let cursor = page.cursor;
+	let printed = printPage(page);
+	if (!opts.follow) {
+		if (printed === 0) log.info(page.running ? `${slug} is running and has printed nothing yet.` : `${slug} isn't running. Start a session, or send it a request, and its output shows up here.`);
+		log.info("Recent output only — an agent's log lives in its sandbox and goes when it does.");
+		return ok({
+			slug,
+			lines: printed,
+			running: page.running
+		});
+	}
+	log.info(`Following ${slug}. Ctrl-C to stop.`);
+	const pollMs = opts.pollMs ?? 1e3;
+	let running = page.running;
+	while (!opts.signal?.aborted) {
+		await sleep(pollMs, omitUndefined({ signal: opts.signal }));
+		if (opts.signal?.aborted) break;
+		const next = await readPage(cwd, cursor, opts.server).catch(() => void 0);
+		if (!next) continue;
+		cursor = next.page.cursor;
+		running = next.page.running;
+		printed += printPage(next.page);
+	}
+	return ok({
+		slug,
+		lines: printed,
+		running
+	});
+}
+/** Write a page's lines (and any gap) to the log. Returns how many lines. */
+function printPage(page) {
+	if (page.dropped > 0) log.warn(`… ${page.dropped} earlier line(s) dropped — the agent printed faster than this read`);
+	for (const line of page.lines) log.message(formatLine(line));
+	return page.lines.length;
+}
+//#endregion
+export { executeLogs };

package/dist/logs.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `aai logs` — what the deployed agent has printed.
+ *
+ * The terminal half of the same read the studio's Logs pane makes
+ * (`GET /:slug/logs`, aai-server/agent-logs.ts): a bounded ring the GUEST holds,
+ * paged by cursor. Two things follow from that and are what this command has to
+ * be honest about, because neither is visible in a wall of lines:
+ *
+ * - **The ring dies with the sandbox.** This is "what my agent printed
+ *   recently", never "what it printed last Tuesday", and the footer says so on
+ *   a one-shot read rather than leaving the absence to be inferred.
+ * - **`running` is not `lines.length`.** An agent that is up and quiet and one
+ *   that is not up at all both print nothing, and they want opposite things
+ *   from the reader. The one-shot read reports which it was.
+ *
+ * `--follow` polls. A stream would be the nicer shape and the source is not one:
+ * the guest holds a RING with a cursor, and a reconnecting stream would have to
+ * re-derive that cursor anyway.
+ */
+import { type CommandResult } from "./_output.ts";
+/** One captured line, as the platform reports it. */
+export type LogLine = {
+    seq: number;
+    at: number;
+    stream: "stdout" | "stderr";
+    text: string;
+};
+/** One read of the ring. Mirrors `AgentLogsResponse` on the platform. */
+export type LogsPage = {
+    lines: LogLine[];
+    cursor: number;
+    dropped: number;
+    running: boolean;
+};
+/** How often `--follow` asks for what is new. */
+export declare const FOLLOW_POLL_MS = 1000;
+export type LogsOpts = {
+    server?: string | undefined;
+    /** Keep polling until interrupted. */
+    follow?: boolean | undefined;
+    /** Poll cadence override, for tests. */
+    pollMs?: number | undefined;
+    /** Stops a `--follow` loop. Tests pass one; the CLI leaves it to Ctrl-C. */
+    signal?: AbortSignal | undefined;
+};
+/** `HH:MM:SS.mmm`, local — the same shape the studio pane prints. */
+export declare function formatTime(at: number): string;
+/** One rendered line: time, then the text. `stderr` is called out by name. */
+export declare function formatLine(line: LogLine): string;
+type LogsData = {
+    slug: string;
+    lines: number;
+    running: boolean;
+};
+/**
+ * Print the agent's buffered output, once or continuously.
+ *
+ * The `--json` shape reports the LINE COUNT rather than the lines: a follow
+ * loop has no final count to report, and a one-shot read that dumped every line
+ * into a result object would duplicate what it just printed.
+ */
+export declare function executeLogs(cwd: string, opts?: LogsOpts): Promise<CommandResult<LogsData>>;
+export {};

package/dist/scaffold/CLAUDE.md

@@ -300,8 +300,17 @@ callback. Reach for `agent()` when someone is on the line — a voice agent can
 also START a workflow from a tool (`ctx.workflows.start(def, input)`) and
 answer the turn, which is the other shape.
 
-**Requires storage** (`aai storage enable`, or `DATABASE_URL` under
-`aai dev`): runs live in the database.
+**Storage is OPTIONAL, and what it buys is DURABILITY.** With a database
+(`aai storage enable`, Settings → Database in the studio, or `DATABASE_URL`
+under `aai dev`) runs live in it and survive a restart, a redeploy and an idle
+sandbox. Without one they live in the process that started them — you can
+submit the form, watch the run and read its result, and everything in flight is
+lost when that process goes away. That is the honest tradeoff, and it is what
+lets you build a workflow app before provisioning anything.
+
+Two things do need the database whatever the run does: `ctx.db`, and a workflow
+**upload** — an upload's record is a row, so `api.upload` and the file-taking
+form hooks refuse by name until storage is on (see "Database API" below).
 
 ### Workflow bodies live in `workflows/`
 
@@ -1339,16 +1348,26 @@ also what you want for anything that can be a string, an array, or null.
 // shared.ts — the slot owns the shape; `agent()` has no `state` field.
 export const cartSlot = sessionSlot("cart", () => ({ cart: [] as Item[], staffPin: "" }));
 
+// Compose the projection HERE, once, and import it at both ends: staffPin stays
+// server-side, and the agent and the client cannot name different views of it.
+export const cartProjection = cartSlot.projection((s) => ({ cart: s.cart }));
+
 // agent.ts
-export default agent({
-  syncState: cartSlot.projection((s) => ({ cart: s.cart })),  // staffPin stays server-side
-});
+export default agent({ syncState: cartProjection });
 
-// client.tsx
-const view = useAgentState<{ cart: Item[] }>();   // null until the first push
-return <Cart items={view?.cart ?? []} />;
+// client.tsx — the projection types the state AND supplies the frame the client
+// renders before the first push, so there is no type argument and no `?? EMPTY`.
+const view = useAgentState(cartProjection);
+return <Cart items={view.cart} />;
 ```
 
+Passing the projection is the shape to copy. The other two overloads still
+exist: `useAgentState<S>()` returns `S | null` (nullable — nothing is pushed
+before the first tool call), and `useAgentState<S>(fallback)` returns `S` for a
+frame you build yourself. Reach for `fallback` only when the slot's factory is
+expensive to import into the browser — the projection overload calls it to build
+the empty frame.
+
 **Reach for this before wiring `useToolResult` into `useState`.** Without
 it the pattern is: return a cart snapshot from every tool, declare a type
 describing what those tools return, and mirror it into `useState` — three
@@ -1511,8 +1530,9 @@ Common mistakes when working in aai projects:
 - **`ctx.db` throws until the database is enabled.** Enable it with
   `aai storage enable` (CLI), Settings → Database (studio), or
   `DATABASE_URL` in `.env` (`aai dev`) before shipping tools that persist
-  data. In the studio it takes effect when each agent next deploys — the
-  preview redeploys itself, production on the next publish.
+  data. A deployed agent reads its connection string when its sandbox is
+  built, so enabling rebuilds it — the change reaches a running agent
+  without a redeploy.
 - **The database is per-app.** Rows are shared by every session of one
   deployment — key them yourself if sessions must not see each other's data
   (or keep session-scoped data in a `sessionSlot`).

package/dist/scaffold/package.json

@@ -13,8 +13,8 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^6.8.0",
-    "@alexkroman1/aai-ui": "^6.8.0",
+    "@alexkroman1/aai": "^6.10.0",
+    "@alexkroman1/aai-ui": "^6.10.0",
     "@workflow/world-postgres": "4.3.3",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
@@ -23,7 +23,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^6.8.0",
+    "@alexkroman1/aai-cli": "^6.10.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.2.0",
     "@types/react": "^19.2.18",

package/dist/templates/dispatch-center/agent.ts

@@ -1,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { dashboardView, dispatchSlot } from "./shared.ts";
+import { dashboardProjection } from "./shared.ts";
 
 export default agent({
   name: "Dispatch Command Center",
@@ -7,7 +7,7 @@ export default agent({
   // something to project rather than an empty state object.
   // One projection replaces eleven `ctx.send("incidents", ...)` calls, and
   // is the single place that decides caller PII stays server-side.
-  syncState: dispatchSlot.projection(dashboardView),
+  syncState: dashboardProjection,
   // A dispatcher reads addresses and unit numbers in bursts with pauses inside
   // one message ("unit twelve … respond to"). The default pipeline's
   // `max_turn_silence` already tolerates that; reach for

package/dist/templates/dispatch-center/client.tsx

@@ -7,8 +7,8 @@ import {
   useSession,
   useUserTranscript,
 } from "@alexkroman1/aai-ui";
-import type { DashboardView, DispatchState, IncidentSummary, Severity, Status } from "./shared.ts";
-import { dashboardView, dispatchSlot } from "./shared.ts";
+import type { DispatchState, IncidentSummary, Severity, Status } from "./shared.ts";
+import { dashboardProjection } from "./shared.ts";
 
 const CSS = `
 @keyframes dc-pulse {
@@ -57,10 +57,6 @@ const statusColors: Record<string, string> = {
   escalated: "#ef4444",
 } satisfies Record<Status, string>;
 
-// The board before the first tool call — derived from the projection so a
-// new DashboardView field can't silently miss the pre-first-tool-call render.
-const EMPTY_DASH: DashboardView = dispatchSlot.projection(dashboardView)(undefined);
-
 // The dot's colour per session state, as an EXHAUSTIVE map rather than an
 // if-chain with a grey default.
 //
@@ -152,7 +148,7 @@ function App() {
   // The agent's own board, projected by `syncState`. This replaced a
   // useState mirror that merged incident deltas out of tool events — the
   // projection is already the complete list, so there is nothing to merge.
-  const dash = useAgentState<DashboardView>(EMPTY_DASH);
+  const dash = useAgentState(dashboardProjection);
 
   const incidentList = [...dash.incidents].reverse();
   const activeIncidents = incidentList.filter((i) => i.status !== "resolved");

package/dist/templates/dispatch-center/shared.ts

@@ -215,6 +215,9 @@ export const dispatchSlot = sessionSlot("dispatch", createDefaultState, {
   },
 });
 
+/** The projection BOTH ends use: `syncState` on the agent, `useAgentState` in the client. */
+export const dashboardProjection = dispatchSlot.projection(dashboardView);
+
 /**
  * The board as a READ hands it out: deep-frozen, and typed to say so.
  *

package/dist/templates/link-digest/agent.ts

@@ -44,8 +44,11 @@
  * doc for the one thing that changes under `aai dev` (the key has to be in
  * `.env`, not just your shell).
  *
- * Requires storage (`aai storage enable`, or `DATABASE_URL` under `aai dev`) —
- * runs and the correlation-key index both live there.
+ * Storage is what makes it DURABLE (`aai storage enable`, Settings → Database
+ * in the studio, or `DATABASE_URL` under `aai dev`) — runs and the
+ * correlation-key index both live there. Without it both live in the process,
+ * so a run in flight is lost when the agent restarts, redeploys or goes idle —
+ * which is fine while you are building one.
  */
 
 import { workflow, workflowApp } from "@alexkroman1/aai";

package/dist/templates/pizza-ordering/agent.test.ts

@@ -18,7 +18,14 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-import { calculateTotal, orderSlot, orderView, type Pizza, pizzaPrice } from "./shared.ts";
+import {
+  calculateTotal,
+  orderProjection,
+  orderSlot,
+  orderView,
+  type Pizza,
+  pizzaPrice,
+} from "./shared.ts";
 
 // ─── Test doubles ────────────────────────────────────────────────────────────
 
@@ -231,8 +238,8 @@ describe("orderView projection", () => {
 
   test("an untouched session projects an empty cart, not undefined", () => {
     // The client renders before any tool has run, so `state.order` is absent —
-    // this is exactly the value `client.tsx` hoists as its fallback.
-    expect(orderSlot.projection(orderView)(undefined)).toMatchObject({
+    // this is exactly the frame `client.tsx` gets from the same projection.
+    expect(orderProjection()).toMatchObject({
       pizzas: [],
       total: "$0.00",
       orderPlaced: false,

package/dist/templates/pizza-ordering/agent.ts

@@ -1,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { menuText, orderSlot, orderView } from "./shared.ts";
+import { menuText, orderProjection } from "./shared.ts";
 import systemPrompt from "./system-prompt.md?raw";
 
 // The in-progress order lives in one `sessionSlot` (see shared.ts) —
@@ -15,7 +15,7 @@ export default agent({
   // The cart, pushed to the client after every tool call. Replaces a
   // `ctx.send("order", ...)` in each of the five order tools, and the
   // event-diffing the client had to do to rebuild the cart from them.
-  syncState: orderSlot.projection(orderView),
+  syncState: orderProjection,
   // The menu section is generated from MENU so the prompt can never quote a
   // price the pricing code doesn't charge.
   systemPrompt: `${systemPrompt}\n${menuText()}`,

package/dist/templates/pizza-ordering/client.tsx

@@ -1,11 +1,6 @@
 import "@alexkroman1/aai-ui/styles.css";
 import { client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
-import type { OrderView } from "./shared.ts";
-import { formatPrice, orderSlot, orderView, pizzaPrice } from "./shared.ts";
-
-// Derived from the projection so a new OrderView field can't silently miss
-// the pre-first-tool-call render — `projection` runs it over an empty cart.
-const EMPTY_ORDER: OrderView = orderSlot.projection(orderView)(undefined);
+import { formatPrice, orderProjection, pizzaPrice } from "./shared.ts";
 
 function PizzaIcon({ size }: { size: string }) {
   const dim = size === "small" ? 36 : size === "large" ? 52 : 44;
@@ -30,7 +25,7 @@ function OrderSidebar() {
   // tool call. This replaced ~45 lines that rebuilt the cart by diffing
   // added/removed/updated events — where one missed event desynced the view
   // for the rest of the session.
-  const order = useAgentState<OrderView>(EMPTY_ORDER);
+  const order = useAgentState(orderProjection);
 
   if (order.orderPlaced) {
     return (

package/dist/templates/pizza-ordering/shared.ts

@@ -157,3 +157,6 @@ export function orderView(order: FrozenOrderState): OrderView {
       : {}),
   };
 }
+
+/** The projection BOTH ends use: `syncState` on the agent, `useAgentState` in the client. */
+export const orderProjection = orderSlot.projection(orderView);

package/dist/templates/plan-and-execute/agent.test.ts

@@ -26,7 +26,7 @@ const agentDef = withDiscoveredTools(
 import { executeStep, MAX_STEP_SEARCHES, normalizeAct, planNode } from "./graph.ts";
 import { EXECUTOR_SYSTEM, PLANNER_SYSTEM, REPLANNER_SYSTEM, REVISE_SYSTEM } from "./prompts.ts";
 import type { SearchFn } from "./shared.ts";
-import { MAX_PAST_STEPS, planSlot, planView } from "./shared.ts";
+import { MAX_PAST_STEPS, planProjection, planSlot, planView } from "./shared.ts";
 
 // ─── A scripted model ────────────────────────────────────────────────────────
 //
@@ -381,8 +381,9 @@ describe("plan_status", () => {
 
 describe("planView projection", () => {
   test("an untouched call projects an empty plan, not undefined", () => {
-    // Exactly the value client.tsx hoists as its fallback.
-    expect(planSlot.projection(planView)(undefined)).toEqual({
+    // Exactly the frame `client.tsx` renders before the first push — it passes
+    // this same projection to `useAgentState`.
+    expect(planProjection()).toEqual({
       objective: null,
       plan: [],
       done: [],

package/dist/templates/plan-and-execute/agent.ts

@@ -1,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { planSlot, planView } from "./shared.ts";
+import { planProjection } from "./shared.ts";
 
 /**
  * A planning desk you can phone: plan-and-execute, with the caller in the loop.
@@ -18,6 +18,6 @@ export default agent({
   // The plan exists before the first tool call, so a resumed connection has
   // something to project.
   // The plan, its progress and its revision trail, pushed after every tool call.
-  syncState: planSlot.projection(planView),
+  syncState: planProjection,
   greeting: "Planning desk. Tell me what you're trying to get done and I'll work out the steps.",
 });

package/dist/templates/plan-and-execute/client.tsx

@@ -1,9 +1,6 @@
 import "@alexkroman1/aai-ui/styles.css";
 import { AutoScroll, client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
-import type { PlanView } from "./shared.ts";
-import { planSlot, planView } from "./shared.ts";
-
-const EMPTY_PLAN: PlanView = planSlot.projection(planView)(undefined);
+import { planProjection } from "./shared.ts";
 
 /**
  * The plan, ticking off.
@@ -14,7 +11,7 @@ const EMPTY_PLAN: PlanView = planSlot.projection(planView)(undefined);
  */
 function PlanSidebar() {
   const theme = useTheme();
-  const plan = useAgentState<PlanView>(EMPTY_PLAN);
+  const plan = useAgentState(planProjection);
 
   if (!plan.objective) {
     return (

package/dist/templates/plan-and-execute/shared.ts

@@ -159,3 +159,6 @@ export function planView(state: FrozenPlanState): PlanView {
     progress: total === 0 ? 0 : done / total,
   };
 }
+
+/** The projection BOTH ends use: `syncState` on the agent, `useAgentState` in the client. */
+export const planProjection = planSlot.projection(planView);

package/dist/templates/recap-workflow/agent.ts

@@ -65,8 +65,11 @@
  * the run really submits the recording, really polls it, and really deletes it
  * when it has to.
  *
- * Requires storage (`aai storage enable`, or `DATABASE_URL` under `aai dev`) —
- * runs and the correlation-key index both live there.
+ * Storage is what makes it DURABLE (`aai storage enable`, Settings → Database
+ * in the studio, or `DATABASE_URL` under `aai dev`) — runs and the
+ * correlation-key index both live there. Without it both live in the process:
+ * the flow still runs, and a recap parked on a callback does not survive the
+ * agent restarting, redeploying or going idle.
  */
 
 import { agent } from "@alexkroman1/aai";

package/dist/templates/research-workflow/agent.ts

@@ -69,8 +69,11 @@
  * thing that changes under `aai dev` (the key has to be in `.env`, not just your
  * shell).
  *
- * Requires storage (`aai storage enable`, or `DATABASE_URL` under `aai dev`) —
- * runs and the key index both live there.
+ * Storage is what makes it DURABLE (`aai storage enable`, Settings → Database
+ * in the studio, or `DATABASE_URL` under `aai dev`) — runs and the key index
+ * both live there. Without it both live in the process, so a run in flight is
+ * lost when the agent restarts, redeploys or goes idle; everything below still
+ * works, which is what lets you try it before provisioning anything.
  */
 
 import { agent } from "@alexkroman1/aai";

package/dist/templates/retail/client.tsx

@@ -43,10 +43,16 @@ const statusColors: Record<string, string> = {
 } satisfies Record<OrderStatus, string>;
 
 // The sidebar before the first tool call, derived from the projection itself so
-// a new StoreView field can't miss the pre-first-call render. Built from
-// `emptyRetailState` rather than `retailSlot.projection(...)(undefined)`,
-// because the slot's factory lives in `store.ts` and pulls the 107 KB seed —
-// importing it here would ship the whole catalog to the browser.
+// a new StoreView field can't miss the pre-first-call render.
+//
+// **This is the one template that does NOT pass its projection to
+// `useAgentState`**, and the reason is the browser bundle rather than style:
+// that overload derives the empty frame by calling the projection, which calls
+// the slot's `create()` — and this slot's factory lives in `store.ts` and pulls
+// the 107 KB seed, so importing it here would ship the whole catalog to the
+// browser. `emptyRetailState()` is the same shape without the seed. Reach for
+// the projection overload everywhere the factory is cheap, which is every
+// other stateful template.
 const EMPTY_VIEW: StoreView = storeView(emptyRetailState());
 
 // The dot's colour per session state, as an EXHAUSTIVE map rather than an

package/dist/templates/solo-rpg/agent.ts

@@ -1,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { gameSlot } from "./shared.ts";
+import { gameProjection } from "./shared.ts";
 
 export default agent({
   name: "Solo RPG",
@@ -14,5 +14,5 @@ export default agent({
   // remembering to push or watching the UI quietly fall out of sync.
   // The identity projection: this campaign IS what the client renders, and the
   // slot's own default is what a session that has run no tool projects.
-  syncState: gameSlot.projection((game) => game),
+  syncState: gameProjection,
 });

package/dist/templates/solo-rpg/client.tsx

@@ -7,7 +7,7 @@ import {
   type Disposition,
   type GameState,
   GENRES,
-  gameSlot,
+  gameProjection,
   MAX_RESOURCE,
   MIN_MOMENTUM,
   type NPC,
@@ -15,18 +15,6 @@ import {
   type TIME_PHASES,
 } from "./shared.ts";
 
-// The campaign before the first tool call, derived from the SAME projection the
-// server pushes rather than from the module default beside it — so a session
-// that has run no tool renders exactly what its first push will replace. Every
-// sibling template derives its fallback this way; this one read `DEFAULT_STATE`
-// directly, which is a second copy of "what an untouched session looks like".
-//
-// It is typed READONLY because that is what the projection produces, and a
-// client only ever renders what the server pushed — so the four components
-// below take a readonly campaign too, which is the deep-readonly slot
-// propagating exactly as far as it should.
-const EMPTY_GAME = gameSlot.projection((game) => game)(undefined);
-
 // ── Color Palette ────────────────────────────────────────────────────────────
 const C = {
   bg: "#0a0a0c",
@@ -784,7 +772,10 @@ function SoloRPGApp() {
   // The agent's own session state, projected by `syncState` and pushed after
   // every tool call — no per-tool `ctx.send`, and nothing to keep in step
   // when a new tool starts mutating the game.
-  const game = useAgentState<DeepReadonly<GameState>>(EMPTY_GAME);
+  // `gameProjection` carries both halves: the campaign's readonly type — which
+  // is what the four components below take — and the frame a session that has
+  // run no tool renders.
+  const game = useAgentState(gameProjection);
 
   return (
     <StartScreen

package/dist/templates/solo-rpg/shared.ts

@@ -328,6 +328,13 @@ export const DEFAULT_STATE: GameState = {
 // another's.
 export const gameSlot = sessionSlot("game", () => structuredClone(DEFAULT_STATE));
 
+/**
+ * The IDENTITY projection, used by `syncState` and by `useAgentState`: this
+ * campaign IS what the client renders, so there is nothing to trim — and it
+ * carries the deep-readonly type the client's components take.
+ */
+export const gameProjection = gameSlot.projection((game) => game);
+
 /**
  * The game as a READ hands it out: deep-frozen, and typed to say so.
  *

package/dist/templates/support-line/agent.test.ts

@@ -31,7 +31,7 @@ import {
   GROUNDED_SYSTEM,
   REWRITE_SYSTEM,
 } from "./prompts.ts";
-import { retrieve, supportSlot, supportView } from "./shared.ts";
+import { retrieve, supportProjection, supportSlot, supportView } from "./shared.ts";
 
 // ─── A scripted model ────────────────────────────────────────────────────────
 //
@@ -332,8 +332,9 @@ describe("log_ticket", () => {
 
 describe("supportView projection", () => {
   test("an untouched call projects an empty trace, not undefined", () => {
-    // Exactly the value client.tsx hoists as its fallback.
-    expect(supportSlot.projection(supportView)(undefined)).toMatchObject({
+    // Exactly the frame `client.tsx` renders before the first push — it passes
+    // this same projection to `useAgentState`.
+    expect(supportProjection()).toMatchObject({
       product: "Meridian Fibre",
       trace: null,
       asked: [],

package/dist/templates/support-line/agent.ts

@@ -1,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { PRODUCT, supportSlot, supportView } from "./shared.ts";
+import { PRODUCT, supportProjection } from "./shared.ts";
 
 /**
  * A support line that grades its own retrieval before it speaks — the
@@ -22,6 +22,6 @@ export default agent({
   // something to project.
   // The projection is also the privacy boundary: a logged ticket carries the
   // caller's callback number, and only its reference crosses to the browser.
-  syncState: supportSlot.projection(supportView),
+  syncState: supportProjection,
   greeting: `${PRODUCT} support, you're through to the automated line. What's happened?`,
 });

package/dist/templates/support-line/client.tsx

@@ -1,9 +1,6 @@
 import "@alexkroman1/aai-ui/styles.css";
 import { AutoScroll, client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
-import type { SupportView } from "./shared.ts";
-import { PRODUCT, supportSlot, supportView } from "./shared.ts";
-
-const EMPTY_SUPPORT: SupportView = supportSlot.projection(supportView)(undefined);
+import { PRODUCT, supportProjection } from "./shared.ts";
 
 /**
  * The graph, as it ran for the last question.
@@ -15,7 +12,7 @@ const EMPTY_SUPPORT: SupportView = supportSlot.projection(supportView)(undefined
  */
 function TraceSidebar() {
   const theme = useTheme();
-  const support = useAgentState<SupportView>(EMPTY_SUPPORT);
+  const support = useAgentState(supportProjection);
   const trace = support.trace;
 
   return (

package/dist/templates/support-line/shared.ts

@@ -238,3 +238,6 @@ export function supportView(state: FrozenSupportState): SupportView {
     ticket: state.ticket?.reference ?? null,
   };
 }
+
+/** The projection BOTH ends use: `syncState` on the agent, `useAgentState` in the client. */
+export const supportProjection = supportSlot.projection(supportView);

package/dist/templates/transcription-workflow/agent.ts

@@ -17,8 +17,10 @@
  *   `aai secret put ASSEMBLYAI_API_KEY` once deployed. `requiredEnv` below is
  *   what makes a deploy check for it rather than letting the first run find out.
  *   A step reads it with `requireStepEnv`; see `@alexkroman1/aai/utils`.
- * - **Storage** (`aai storage enable`, or `DATABASE_URL` under `aai dev`) — runs
- *   live there.
+ * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
+ *   `DATABASE_URL` under `aai dev`). REQUIRED here, unlike most workflow apps:
+ *   a run survives without it, but an UPLOAD's record is a row, so the form
+ *   below refuses by name until storage is on.
  * - **A linear-PCM WAV.** The cutting is arithmetic over byte offsets, which is
  *   only possible on uncompressed audio; `workflows/wav.ts` says so in more
  *   detail, and an unsupported file fails the run by name with the `ffmpeg`

package/dist/templates/transcription-workflow/client.tsx

@@ -168,7 +168,6 @@ import {
 } from "@alexkroman1/aai-ui";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type { transcribe } from "./agent.ts";
-import { ApiHelp } from "./api-help.tsx";
 import {
   clock,
   countWords,
@@ -463,10 +462,6 @@ function TranscriptionDesk() {
         openId={openId}
         onOpen={(runId) => setOpenId((current) => (current === runId ? undefined : runId))}
       />
-
-      {/* The most useful thing about a workflow app is the least discoverable:
-          this page is one caller of an ordinary HTTP API. See `api-help.tsx`. */}
-      <ApiHelp />
     </main>
   );
 }

package/dist/templates/travel-concierge/agent.test.ts

@@ -18,7 +18,7 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-import { activeAssistant, FLIGHTS, tripSlot, tripView } from "./shared.ts";
+import { activeAssistant, FLIGHTS, tripProjection, tripSlot, tripView } from "./shared.ts";
 
 // ─── Harness ─────────────────────────────────────────────────────────────────
 
@@ -298,8 +298,9 @@ describe("search tools", () => {
 
 describe("tripView projection", () => {
   test("an untouched call projects the seeded booking at the concierge desk", () => {
-    // Exactly the value client.tsx hoists as its fallback.
-    const view = tripSlot.projection(tripView)(undefined);
+    // Exactly the frame `client.tsx` renders before the first push — it passes
+    // this same projection to `useAgentState`.
+    const view = tripProjection();
     expect(view).toMatchObject({
       assistant: "primary",
       assistantTitle: "concierge",

package/dist/templates/travel-concierge/agent.ts

@@ -1,5 +1,5 @@
 import { agent } from "@alexkroman1/aai";
-import { tripSlot, tripView } from "./shared.ts";
+import { tripProjection } from "./shared.ts";
 
 /**
  * A phone travel concierge, adapted from LangGraph's customer-support tutorial.
@@ -23,7 +23,7 @@ export default agent({
   // so a resumed connection has something to project.
   // One projection replaces a `ctx.send` in each of eleven tools — and is the
   // single place that decides the caller's record leaves the server trimmed.
-  syncState: tripSlot.projection(tripView),
+  syncState: tripProjection,
   greeting:
     "Swiss Air Travel, this is the concierge desk. I can see your booking — what can I do for you today?",
 });

package/dist/templates/travel-concierge/client.tsx

@@ -1,11 +1,7 @@
 import "@alexkroman1/aai-ui/styles.css";
 import { AutoScroll, client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
 import type { TripView } from "./shared.ts";
-import { SPECIALIST_IDS, SPECIALISTS, tripSlot, tripView } from "./shared.ts";
-
-// Derived from the projection so a new TripView field cannot silently miss the
-// pre-first-tool-call render.
-const EMPTY_TRIP: TripView = tripSlot.projection(tripView)(undefined);
+import { SPECIALIST_IDS, SPECIALISTS, tripProjection } from "./shared.ts";
 
 const DESKS = ["primary", ...SPECIALIST_IDS] as const;
 
@@ -44,7 +40,7 @@ function DeskStrip({ active }: { active: TripView["assistant"] }) {
 
 function ItinerarySidebar() {
   const theme = useTheme();
-  const trip = useAgentState<TripView>(EMPTY_TRIP);
+  const trip = useAgentState(tripProjection);
 
   return (
     <div className="flex flex-col gap-4 p-4 h-full min-h-0" style={{ color: theme.text }}>

package/dist/templates/travel-concierge/shared.ts

@@ -545,3 +545,6 @@ export function tripView(state: FrozenTripState): TripView {
     log: state.log,
   };
 }
+
+/** The projection BOTH ends use: `syncState` on the agent, `useAgentState` in the client. */
+export const tripProjection = tripSlot.projection(tripView);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "6.8.0",
+  "version": "6.10.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -44,8 +44,8 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai-ui": "6.8.0",
-    "@alexkroman1/aai": "6.8.0"
+    "@alexkroman1/aai": "6.10.0",
+    "@alexkroman1/aai-ui": "6.10.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",

package/dist/templates/transcription-workflow/api-help.tsx

@@ -1,214 +0,0 @@
-// Copyright 2026 the AAI authors. MIT license.
-/**
- * "You do not need this page" — the HTTP API, on the page.
- *
- * A workflow app's whole surface is `GET|POST /workflows/*`, and the page is one
- * caller of it. That is the most useful thing about the shape and the least
- * discoverable: nothing in a form suggests that the same work is three `curl`
- * calls, that a run id is the entire handle (no session, no cookie), or that a
- * transcript can be collected days later from another machine. So the recipes are
- * rendered where somebody is already looking, rather than left in a README they
- * would have to know exists.
- *
- * ## It links to the LIVE listing
- *
- * `GET /workflows` serves each workflow's name, description and input schema — the
- * same JSON `<WorkflowFields>` renders this form from. So the link is not
- * documentation about the API, it is the API answering for itself, on this
- * deployment, at this version. A reader who wants the schema gets the real one;
- * a reader whose agent is behind `AAI_WORKFLOW_API_TOKEN` gets a 401, which is
- * also the truth.
- *
- * ## The three recipes are the three flows
- *
- * The first two differ only in who names the upload — which is the whole of what
- * lets one of them start before the bytes are in — and the third does none of that
- * work at all. Showing them side by side is the clearest statement of the trade
- * available, and cheaper than the prose that would otherwise have to make it.
- *
- * They are also KEPT HONEST by being runnable: every one of these was executed
- * against a real dev server, which is how two bugs in the streaming path were
- * found (a missing wake after the upload, and a poll that slept on a stale view).
- */
-
-/** @jsxImportSource react */
-
-import type { ReactNode } from "react";
-
-/** The API root, relative to wherever this page is served from. */
-const API = "workflows";
-
-/**
- * One shell recipe, with a heading and a note.
- *
- * Rendered in a `<pre>` rather than assembled from styled spans: it exists to be
- * SELECTED and pasted, and any markup inside the block is markup a copy picks up.
- */
-function Recipe({
-  title,
-  note,
-  script,
-}: {
-  title: string;
-  note: string;
-  script: string;
-}): ReactNode {
-  return (
-    <section className="flex flex-col gap-2">
-      <h4 className="text-xs font-medium uppercase tracking-[1.2px]">{title}</h4>
-      <p className="text-xs opacity-70">{note}</p>
-      <pre className="overflow-x-auto rounded-md border p-3 text-xs leading-relaxed">{script}</pre>
-    </section>
-  );
-}
-
-/** Store the whole file, then start a run on its id. */
-const CLASSIC = `# 1. store the recording. Answers 201 once the LAST byte is in, which is why
-#    this shape cannot start the run any earlier.
-ID=$(curl -s -X POST "$AGENT/workflows/uploads?name=standup.wav" \
-  -H 'content-type: audio/wav' --data-binary @standup.wav | jq -r .id)
-
-# 2. run it. \`wait\` holds the request open for up to 60s; drop it to get
-#    { runId } straight back and poll instead.
-curl -s -X POST "$AGENT/workflows/runs" \
-  -H 'content-type: application/json' \
-  -d "{\\"workflow\\":\\"transcribe\\",\\"wait\\":60000,
-       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r '.run.output.transcript'`;
-
-/** Start the run first, then stream the file to the id it is watching. */
-const STREAMING = `# No splitting, no ffmpeg — the file goes in ONE request. The only difference
-# from the recipe above is that YOU pick the upload id, so it is already valid
-# when the run starts and the run reads the bytes as they land.
-
-# 1. pick an id and start the run on it. Nothing has been uploaded yet.
-ID=$(openssl rand -hex 16)
-RUN=$(curl -s -X POST "$AGENT/workflows/runs" \
-  -H 'content-type: application/json' \
-  -d "{\\"workflow\\":\\"transcribeStream\\",
-       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r .runId)
-
-# 2. PUT the whole file. The upload record exists from the first byte with
-#    complete:false, and its size grows — which is what the run polls.
-curl -s -X PUT "$AGENT/workflows/uploads/$ID?name=standup.wav" \
-  -H 'content-type: audio/wav' --data-binary @standup.wav | jq -c '{size, complete}'
-
-# 3. wake it. The run sleeps between polls, so without this it notices the file
-#    is finished up to one poll interval late — every time.
-curl -s -X POST "$AGENT/workflows/runs/$RUN/wake" > /dev/null
-
-# 4. collect it whenever — a run id is the whole handle.
-curl -s "$AGENT/workflows/runs/$RUN?wait=60000" | jq -r '.run.output.transcript'
-
-# While it runs, from any other shell:
-#   curl -s "$AGENT/workflows/uploads/$ID/info"        # how much has arrived
-#   curl -sN "$AGENT/workflows/runs/$RUN/stream"       # what the run is saying`;
-
-/** Hand the whole thing to the async API. */
-const BATCH = `# The same two requests as the first recipe — only the workflow name differs.
-# No cutting happens anywhere: the run uploads your file to the async API,
-# polls the job, and reads the text. It also accepts mp3 and m4a, which the
-# two sync flows refuse.
-ID=$(curl -s -X POST "$AGENT/workflows/uploads?name=standup.m4a" \
-  -H 'content-type: audio/mp4' --data-binary @standup.m4a | jq -r .id)
-
-# No \`wait\` here: an async job takes minutes, well past the 60s ceiling a
-# synchronous read can hold. Start it, then follow the run.
-RUN=$(curl -s -X POST "$AGENT/workflows/runs" \
-  -H 'content-type: application/json' \
-  -d "{\\"workflow\\":\\"transcribeBatch\\",
-       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r .runId)
-
-curl -sN "$AGENT/workflows/runs/$RUN/events"          # status, as it changes
-curl -s "$AGENT/workflows/runs/$RUN" | jq -r '.output.transcript // .status'`;
-
-/** Every route this app answers, and what each is for. */
-const ROUTES: readonly { route: string; does: string }[] = [
-  { route: "GET  /workflows", does: "the three workflows and their input schemas" },
-  { route: "POST /workflows/runs", does: "start a run · body names workflow and input" },
-  { route: "GET  /workflows/runs", does: "runs so far · filter by workflow, key, limit" },
-  { route: "GET  /workflows/runs/:id", does: "one run · add wait=<ms> to block on it" },
-  { route: "GET  /workflows/runs/:id/events", does: "SSE, status transitions" },
-  { route: "GET  /workflows/runs/:id/stream", does: "SSE, what the run has written" },
-  { route: "POST /workflows/runs/:id/wake", does: "end a pending sleep early" },
-  { route: "DELETE /workflows/runs/:id", does: "cancel it" },
-  { route: "POST /workflows/uploads", does: "store a file, id minted by the store" },
-  {
-    route: "PUT  /workflows/uploads/:id",
-    does: "store a file under YOUR id, readable as it arrives",
-  },
-  {
-    route: "POST /workflows/uploads/:id/parts",
-    does: "declare an upload its parts fill in · ?total=<bytes>",
-  },
-  {
-    route: "PUT  /workflows/uploads/:id/parts",
-    does: "one window of it · ?offset=<byte>, sent concurrently",
-  },
-  { route: "GET  /workflows/uploads/:id", does: "read the bytes back · Range honoured" },
-  { route: "GET  /workflows/uploads/:id/info", does: "name, bytes stored so far, and complete" },
-];
-
-/**
- * The whole API, collapsed by default.
- *
- * `<details>` rather than a state hook: the browser owns disclosure, it is
- * keyboard-accessible and findable by in-page search without anyone wiring either,
- * and a page that renders a transcript should not re-render because somebody
- * expanded a help panel.
- */
-export function ApiHelp(): ReactNode {
-  return (
-    <details className="rounded-md border">
-      <summary className="cursor-pointer p-4 text-sm font-medium">
-        Use the API without this page
-      </summary>
-      <div className="flex flex-col gap-6 border-t p-4">
-        <p className="text-sm opacity-70">
-          This page is one caller. Everything it does is plain HTTP on this agent's own origin,
-          unauthenticated unless the deployment sets{" "}
-          <code className="text-xs">AAI_WORKFLOW_API_TOKEN</code> (then every route wants{" "}
-          <code className="text-xs">Authorization: Bearer …</code>). A run id is the whole handle —
-          no session, no cookie — so a transcript can be collected from another machine, days later.
-        </p>
-        <p className="text-sm">
-          {/* The API answering for itself: same JSON this form was rendered from. */}
-          <a className="underline" href={API} target="_blank" rel="noreferrer">
-            {`GET ${API}`}
-          </a>{" "}
-          <span className="opacity-70">
-            — the live listing, including each workflow's input schema. Set{" "}
-            <code className="text-xs">AGENT</code> to this page's origin for the recipes below.
-          </span>
-        </p>
-
-        <Recipe
-          title="Store it, then transcribe"
-          note="Sync API. One request per phase, and the upload has to finish before there is a run."
-          script={CLASSIC}
-        />
-        <Recipe
-          title="Transcribe while it uploads"
-          note="Sync API, one upload request, no splitting. The run starts on an id you chose and reads the bytes as they land."
-          script={STREAMING}
-        />
-        <Recipe
-          title="Let the provider do it"
-          note="Async API. No cutting and no seams, it accepts compressed audio, and the wait belongs to the provider's queue."
-          script={BATCH}
-        />
-
-        <section className="flex flex-col gap-2">
-          <h4 className="text-xs font-medium uppercase tracking-[1.2px]">Every route</h4>
-          <ul className="flex flex-col gap-1">
-            {ROUTES.map((entry) => (
-              <li key={entry.route} className="flex flex-col gap-0.5 text-xs sm:flex-row sm:gap-3">
-                <code className="shrink-0 sm:w-72">{entry.route}</code>
-                <span className="opacity-70">{entry.does}</span>
-              </li>
-            ))}
-          </ul>
-        </section>
-      </div>
-    </details>
-  );
-}