@alexkroman1/aai-cli 5.2.0 → 5.4.0

package/dist/scaffold/CLAUDE.md

@@ -11,8 +11,9 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
    agent to verify behavior end-to-end. This is the primary feedback loop.
 2. **Run `pnpm test` after logic changes** — vitest. Co-locate tests as
    `agent.test.ts` (see `pipeline-simple` template for a reference).
-   **The project starts with an `agent.test.ts`, and it is yours to
-   maintain.** It asserts the agent's shape — name, providers, tool names —
+   **When the project has an `agent.test.ts` (the default `simple`
+   template and several others ship one), it is yours to maintain.** It
+   asserts the agent's shape — name, providers, tool names —
    so rewriting the agent without updating it leaves a test asserting an
    agent that no longer exists. When a test fails after your change, decide
    which side is stale: updating the test to match the new agent is a normal
@@ -26,17 +27,21 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
    `node_modules/@alexkroman1/aai-cli/dist/templates/`. Read them directly;
    `aai init --template <name>` scaffolds a fresh project from one. Closest
    matches: `simple`, `pipeline-simple`, `web-researcher`, `solo-rpg`,
-   `pizza-ordering`.
+   `pizza-ordering`. When reading SDK types under
+   `node_modules/@alexkroman1/aai*/dist/`, note the built entry points
+   re-export with source specifiers (`"./sdk/constants.ts"`,
+   `"./components/button.tsx"`) — rewrite `.ts`/`.tsx` to `.d.ts` to find
+   the shipped file.
 
 ## CLI
 
 ```sh
 npx @alexkroman1/aai-cli init             # Scaffold a new agent
+npx @alexkroman1/aai-cli templates        # List available templates
 npx @alexkroman1/aai-cli dev              # Start local dev server
 npx @alexkroman1/aai-cli test             # Run agent.test.ts via vitest
 npx @alexkroman1/aai-cli build            # Bundle and validate
 npx @alexkroman1/aai-cli deploy           # Deploy to production
-npx @alexkroman1/aai-cli deploy -y        # Deploy without prompts
 npx @alexkroman1/aai-cli delete           # Remove deployed agent
 npx @alexkroman1/aai-cli secret put NAME  # Set a secret
 npx @alexkroman1/aai-cli secret delete NAME
@@ -44,7 +49,7 @@ npx @alexkroman1/aai-cli secret list
 ```
 
 The scaffold's `package.json` exposes `dev`, `build`, `test`, and `deploy`
-as `pnpm <name>` shortcuts. Other commands (`init`, `delete`, `secret`)
+as `pnpm <name>` shortcuts. Other commands (`init`, `templates`, `delete`, `secret`)
 are CLI-only.
 
 ## Project structure
@@ -64,23 +69,25 @@ my-agent/
 
 ## `agent()` API
 
-```ts
+```ts no-check
 import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: string;                              // required — display name
   systemPrompt?: string;                     // default: general voice assistant
+                                             // (`system` is an accepted alias)
   greeting?: string;                         // default: "Hey there..."
   sttPrompt?: string;                        // STT guidance for jargon/acronyms
   builtinTools?: BuiltinTool[];              // see built-in tools table
   tools?: Record<string, ToolDef>;
   maxSteps?: number;                         // default: 10 — max tool calls per turn
-  toolChoice?: "auto" | "required";          // default: "auto"
+  toolChoice?: ToolChoice;                   // "auto" (default) | "required" | "none"
+                                             // | { type: "tool", toolName }
   idleTimeoutMs?: number;                    // disconnect after inactivity (ms)
   silenceTimeoutMs?: number;                 // pipeline only — assistant speaks up after this much user silence (ms)
   silencePrompt?: string;                    // instruction injected on silence timeout (requires silenceTimeoutMs)
   minBargeInWords?: number;                  // pipeline only — words before user speech interrupts the reply (default 2)
-  interruptionMinDurationMs?: number;        // pipeline only — sustained speech (ms) before an interim barge-in interrupts (default 0 = off)
+  interruptionMinDurationMs?: number;        // pipeline only — sustained speech (ms) before an interim barge-in interrupts (default 500; 0 disables)
   holdPhrase?: string;                       // pipeline only — spoken before a silent tool-call turn (default "One moment."; "" disables)
   falseInterruptionTimeoutMs?: number;       // pipeline only — resume an interrupted reply if no user turn commits (default 2000; 0 disables)
   state?: () => S;                           // per-session mutable state, exposed as ctx.state
@@ -91,7 +98,10 @@ export default agent({
 ```
 
 > When `stt`, `llm`, and `tts` are all provided, the agent runs in
-> **Pipeline mode** — see the section below.
+> **Pipeline mode** — see the section below. `llm` also accepts a model-id
+> string: `"creator/model"` routes through the Vercel AI Gateway
+> (`AI_GATEWAY_API_KEY`), a bare id through the AssemblyAI LLM Gateway
+> (`ASSEMBLYAI_API_KEY`).
 
 Minimal agent — a cascaded pipeline, which is what you should build unless
 the user asks for the speech-to-speech API:
@@ -111,7 +121,7 @@ by setting it after the spread — everything else stays as the preset put it:
 
 ```ts
 import { agent, assemblyAIPipeline } from "@alexkroman1/aai";
-import { assemblyAI as assemblyAITts } from "@alexkroman1/aai/tts";
+import { assemblyAITts } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
@@ -120,11 +130,27 @@ export default agent({
 });
 ```
 
-`agent({ name })` alone is legal and gives you S2S mode instead — see below.
+The same pattern changes the gateway LLM model — `llm` accepts the model id
+as a plain string:
+
+```ts
+import { agent, assemblyAIPipeline } from "@alexkroman1/aai";
+
+export default agent({
+  name: "My Agent",
+  ...assemblyAIPipeline(),
+  llm: "claude-sonnet-4-6",
+});
+```
+
+`agent({ name })` alone is legal and equivalent — an agent that declares no
+providers gets `assemblyAIPipeline()` injected as the default. Speech-to-speech
+(S2S) mode is an explicit opt-in via the `s2s` field — see below.
 
 System prompt from file:
 
 ```ts
+/// <reference types="vite/client" />
 import { agent } from "@alexkroman1/aai";
 import systemPrompt from "./system-prompt.md?raw";
 export default agent({ name: "My Agent", systemPrompt });
@@ -138,14 +164,32 @@ explicit the modern spelling is `with { type: "json" }`, but plain is fine.
 
 ## Pipeline mode
 
-Omitting `stt`/`llm`/`tts` gives **S2S mode**: AssemblyAI's speech-to-speech
-service handles STT, the LLM loop, and TTS in one socket. Fewer moving
-parts, but you cannot choose the model, swap a provider, or tune a stage.
+Pipeline mode is the default: omitting `stt`/`llm`/`tts` (and `s2s`) gives
+you the all-AssemblyAI pipeline, exactly as if you had spread
+`assemblyAIPipeline()` yourself.
 
-**Prefer pipeline mode** — declare all three — unless the user specifically
+**S2S mode is an explicit opt-in.** Setting `s2s: assemblyAIS2s()` (imported
+from `@alexkroman1/aai`, next to `agent()`) selects AssemblyAI's
+speech-to-speech Voice Agent API: STT, the LLM loop, and TTS run
+service-side in one socket. Fewer moving parts, but you cannot choose the
+model, swap a provider, or tune a stage. There is no way to reach S2S by
+omission — only the `s2s` field selects it, and it is mutually exclusive
+with the `stt`/`llm`/`tts` triple.
+
+```ts
+import { agent, assemblyAIS2s } from "@alexkroman1/aai";
+
+export default agent({
+  name: "My Agent",
+  s2s: assemblyAIS2s(),
+});
+```
+
+**Prefer pipeline mode** — the default — unless the user specifically
 asks for the speech-to-speech API. Nearly every template ships this way, and
 it is what the App Builder defaults to. The host runs the LLM loop locally
-(Vercel AI SDK) with your chosen STT, LLM, and TTS. You need it when:
+(Vercel AI SDK) with your chosen STT, LLM, and TTS. You want explicit
+providers when:
 
 - you want a specific LLM (Anthropic, OpenAI, Gemini, Mistral, xAI, Groq,
   hundreds of models via OpenRouter, or 25+ models via the AssemblyAI
@@ -153,18 +197,21 @@ it is what the App Builder defaults to. The host runs the LLM loop locally
 - you want a specific STT model or TTS voice
 - you need to swap providers without changing agent code
 
-**The rule:** set all three of `stt`, `llm`, `tts` together, or none. A
-partial config is rejected at parse time.
+**The rule:** set all three of `stt`, `llm`, `tts` together, or none.
+`agent()`'s parameter type enforces this — a partial triple is a compile
+error ("missing: llm, tts"), as is combining `s2s` with any pipeline
+provider or pipeline-only tuning field. A raw config that skips `agent()`
+is still rejected at parse time.
 
 ```ts
 import { agent } from "@alexkroman1/aai";
-import { assemblyAI } from "@alexkroman1/aai/stt";
+import { assemblyAIStt } from "@alexkroman1/aai/stt";
 import { anthropic } from "@alexkroman1/aai/llm";
 import { cartesia } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
-  stt: assemblyAI({ model: "universal-3-5-pro" }),
+  stt: assemblyAIStt({ model: "universal-3-5-pro" }),
   llm: anthropic({ model: "claude-haiku-4-5" }),
   tts: cartesia(),
 });
@@ -186,11 +233,12 @@ user speaks again.
 **Voice-UX tuning (pipeline only):** `minBargeInWords` controls how many
 words of user speech interrupt the assistant mid-reply (default 2, so
 one-word backchannels like "yeah" don't cut it off);
-`interruptionMinDurationMs` adds an optional sustained-speech gate on top
-(interim transcripts only — committed turns always land). End-of-turn
-detection (how long a pause ends the user's turn) belongs to the STT
-provider: `assemblyAI({ minTurnSilenceMs })` / `deepgram({ endpointing })`,
-both defaulting to 1500 ms so mid-utterance pauses don't split a request.
+`interruptionMinDurationMs` adds a sustained-speech gate on top (default
+500 ms; `0` disables; interim transcripts only — committed turns always
+land). End-of-turn detection (how long a pause ends the user's turn)
+belongs to the STT provider: `assemblyAIStt({ minTurnSilenceMs })` (default
+2000 ms) / `deepgram({ endpointing })` (default 1500 ms), so mid-utterance
+pauses don't split a request.
 `holdPhrase` is spoken when a turn opens with a tool call and no speech.
 `falseInterruptionTimeoutMs` resumes an interrupted reply when a barge-in
 turns out to be noise (no user turn commits within the window).
@@ -202,34 +250,34 @@ for the providers you actually use.
 
 ### STT — `@alexkroman1/aai/stt`
 
-| Factory       | Default model            | Env var              |
-| ------------- | ------------------------ | -------------------- |
-| `assemblyAI`  | `"universal-3-5-pro"`    | `ASSEMBLYAI_API_KEY` |
-| `deepgram`    | `"nova-3"`               | `DEEPGRAM_API_KEY`   |
-| `elevenlabs`  | `"scribe_v2_realtime"`   | `ELEVENLABS_API_KEY` |
-| `soniox`      | `"stt-rt-v3"`            | `SONIOX_API_KEY`     |
+| Factory         | Default model          | Env var              |
+| --------------- | ---------------------- | -------------------- |
+| `assemblyAIStt` | `"universal-3-5-pro"`  | `ASSEMBLYAI_API_KEY` |
+| `deepgram`      | `"nova-3"`             | `DEEPGRAM_API_KEY`   |
+| `elevenlabs`    | `"scribe_v2_realtime"` | `ELEVENLABS_API_KEY` |
+| `soniox`        | `"stt-rt-v3"`          | `SONIOX_API_KEY`     |
 
 All STT factories accept `{ model?: string, ... }`. Bare calls
 (`deepgram()`, `soniox()`, etc.) use the default model.
 
-`assemblyAI` accepts an optional `region: "eu"` for EU data residency —
+`assemblyAIStt` accepts an optional `region: "eu"` for EU data residency —
 it routes streaming transcription to AssemblyAI's EU endpoints. EU-region
 API keys require it; the US endpoints reject them. Example:
-`assemblyAI({ model: "universal-3-5-pro", region: "eu" })`.
+`assemblyAIStt({ model: "universal-3-5-pro", region: "eu" })`.
 
 ### LLM — `@alexkroman1/aai/llm`
 
-| Factory     | SDK package           | Env var                          |
-| ----------- | --------------------- | -------------------------------- |
-| `anthropic` | `@ai-sdk/anthropic`   | `ANTHROPIC_API_KEY`              |
-| `openai`    | `@ai-sdk/openai`      | `OPENAI_API_KEY`                 |
-| `google`    | `@ai-sdk/google`      | `GOOGLE_GENERATIVE_AI_API_KEY`   |
-| `mistral`   | `@ai-sdk/mistral`     | `MISTRAL_API_KEY`                |
-| `xai`       | `@ai-sdk/xai`         | `XAI_API_KEY`                    |
-| `groq`      | `@ai-sdk/groq`        | `GROQ_API_KEY`                   |
-| `openrouter`| `@ai-sdk/openai`      | `OPENROUTER_API_KEY`             |
-| `gateway`   | `ai` (built in)       | `AI_GATEWAY_API_KEY`             |
-| `assemblyAI`| `@ai-sdk/openai`      | `ASSEMBLYAI_API_KEY`             |
+| Factory         | SDK package         | Env var                        |
+| --------------- | ------------------- | ------------------------------ |
+| `anthropic`     | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY`            |
+| `openai`        | `@ai-sdk/openai`    | `OPENAI_API_KEY`               |
+| `google`        | `@ai-sdk/google`    | `GOOGLE_GENERATIVE_AI_API_KEY` |
+| `mistral`       | `@ai-sdk/mistral`   | `MISTRAL_API_KEY`              |
+| `xai`           | `@ai-sdk/xai`       | `XAI_API_KEY`                  |
+| `groq`          | `@ai-sdk/groq`      | `GROQ_API_KEY`                 |
+| `openrouter`    | `@ai-sdk/openai`    | `OPENROUTER_API_KEY`           |
+| `gateway`       | `ai` (built in)     | `AI_GATEWAY_API_KEY`           |
+| `assemblyAILlm` | `@ai-sdk/openai`    | `ASSEMBLYAI_API_KEY`           |
 
 LLM factories require `{ model: string }`. Example:
 `anthropic({ model: "claude-haiku-4-5" })`.
@@ -246,50 +294,52 @@ hundreds of models addressed as `"creator/model"`, e.g.
 `gateway({ model: "zai/glm-4.6" })`. It needs no extra SDK install
 (the gateway client ships inside the `ai` package).
 
-`assemblyAI` routes through the [AssemblyAI LLM
+`assemblyAILlm` routes through the [AssemblyAI LLM
 Gateway](https://www.assemblyai.com/docs/llm-gateway) — an
 OpenAI-compatible endpoint fronting 25+ models (Claude, GPT, Gemini,
-etc.) with the same API key as AssemblyAI STT. It accepts an optional
-`region: "eu"` for EU data residency. It shares its name with the STT
-factory, so alias one when using both:
+etc.) with the same API key as AssemblyAI STT:
 
 ```ts
-import { assemblyAI } from "@alexkroman1/aai/stt";
-import { assemblyAI as assemblyAILlm } from "@alexkroman1/aai/llm";
+import { agent } from "@alexkroman1/aai";
+import { assemblyAILlm } from "@alexkroman1/aai/llm";
+import { assemblyAIStt } from "@alexkroman1/aai/stt";
+import { cartesia } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
-  stt: assemblyAI({ model: "universal-3-5-pro" }),
+  stt: assemblyAIStt({ model: "universal-3-5-pro" }),
   llm: assemblyAILlm({ model: "claude-sonnet-4-6" }),
   tts: cartesia(),
 });
 ```
 
+It accepts an optional `region: "eu"` for EU data residency.
+
 An all-AssemblyAI pipeline — one provider, one key:
 
 ```ts
 import { agent } from "@alexkroman1/aai";
-import { assemblyAI } from "@alexkroman1/aai/stt";
-import { assemblyAI as assemblyAILlm } from "@alexkroman1/aai/llm";
-import { assemblyAI as assemblyAITts } from "@alexkroman1/aai/tts";
+import { assemblyAILlm } from "@alexkroman1/aai/llm";
+import { assemblyAIStt } from "@alexkroman1/aai/stt";
+import { assemblyAITts } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
-  stt: assemblyAI({ model: "universal-3-5-pro" }),
+  stt: assemblyAIStt({ model: "universal-3-5-pro" }),
   llm: assemblyAILlm({ model: "gemini-2.5-flash-lite" }),
-  tts: assemblyAITts({ voice: "vera" }),
+  tts: assemblyAITts({ voice: "jane" }),
 });
 ```
 
 ### TTS — `@alexkroman1/aai/tts`
 
-| Factory      | Default voice                            | Env var              |
-| ------------ | ---------------------------------------- | -------------------- |
-| `assemblyAI` | `"vera"`                                 | `ASSEMBLYAI_API_KEY` |
-| `cartesia`   | `"f786b574-daa5-4673-aa0c-cbe3e8534c02"` | `CARTESIA_API_KEY`   |
-| `rime`       | `"cove"` (model `mistv2`)                | `RIME_API_KEY`       |
+| Factory         | Default voice                            | Env var              |
+| --------------- | ---------------------------------------- | -------------------- |
+| `assemblyAITts` | `"jane"`                                 | `ASSEMBLYAI_API_KEY` |
+| `cartesia`      | `"f786b574-daa5-4673-aa0c-cbe3e8534c02"` | `CARTESIA_API_KEY`   |
+| `rime`          | `"cove"` (model `mistv2`)                | `RIME_API_KEY`       |
 
-Bare calls (`assemblyAI()`, `cartesia()`, `rime()`) use the defaults.
+Bare calls (`assemblyAITts()`, `cartesia()`, `rime()`) use the defaults.
 Override with `{ voice, model, language }`.
 
 **AssemblyAI TTS** shares `ASSEMBLYAI_API_KEY` with AssemblyAI STT and the
@@ -300,8 +350,8 @@ connected, "ready", and permanently silent**, so pick one from here rather
 than guessing a plausible name:
 
 - **English, US accent**: `alba`, `anna`, `charles`, `eve`, `george`,
-  `jane`, `jean`, `mary`, `michael`
-- **English, UK accent**: `paul`, `vera` (the default)
+  `jane` (the default), `jean`, `mary`, `michael`
+- **English, UK accent**: `paul`, `vera`
 - **Native accent, code-switches with English**: `estelle` (fr),
   `giovanni` (it), `juergen` (de), `lola` (es), `rafael` (pt)
 
@@ -312,8 +362,7 @@ Set
 `language` only alongside a voice that speaks it, as an ISO 639-1 code —
 `"en"`, `"fr"`, `"de"`, `"it"`, `"pt"`, `"es"` are the six the catalog
 covers, and the SDK translates each to the full name the service wants.
-Anything else fails at session start. Because the factory is named
-`assemblyAI` in `/stt`, `/llm`, and `/tts`, alias on import.
+Anything else fails at session start.
 
 **Rime quirk:** language uses ISO 639-3 three-letter codes (e.g. `"eng"`
 not `"en"`).
@@ -323,13 +372,13 @@ Set provider keys the same way as any secret: `.env` for local dev,
 
 ## `tool()` API
 
-```ts
+```ts no-check
 import { tool } from "@alexkroman1/aai";
 import { z } from "zod";
 
 const myTool = tool({
   description: string;           // shown to LLM — decides when to call
-  parameters?: z.ZodObject;      // Zod schema (omit for no-arg tools)
+  inputSchema?: z.ZodObject;     // Zod schema (omit for no-arg tools)
   execute(args, ctx): unknown;   // sync or async
 });
 ```
@@ -339,13 +388,13 @@ same way in `aai dev` and deployed.
 
 ### `ctx` (ToolContext)
 
-```ts
+```ts no-check
 ctx.env: Readonly<Record<string, string>>     // secrets from .env / aai secret put
 ctx.state: S                                   // per-session mutable state (agent's `state` factory)
 ctx.db: Db                                     // SQL database, needs storage enabled (see Database section)
 ctx.messages: readonly Message[]               // conversation history [{role, content}]
 ctx.sessionId: string                          // unique session ID
-ctx.send(event: string, data: unknown): void   // push custom event to browser client
+ctx.send(event: string, data: unknown): void   // push custom event to browser client (silently dropped over 64 KB JSON)
 ctx.generate(opts): Promise<{ text, object? }> // one-shot LLM call (host-side)
 ```
 
@@ -353,7 +402,7 @@ ctx.generate(opts): Promise<{ text, object? }> // one-shot LLM call (host-side)
 the project's tsconfig turns off `noImplicitAny`, so both of these compile
 with no annotations and no errors:
 
-```ts
+```ts no-check
 ctx.state.count++;
 ctx.state.incidents.filter((i) => i.status === "open");
 ```
@@ -366,7 +415,7 @@ declare empty.** With `noImplicitAny` off, TypeScript does not widen an empty
 initializer from what you later assign, so `[]` stays `never[]` and `null`
 stays `null` — forever, whether or not a callback is involved:
 
-```ts
+```ts no-check
 const items = [];            // never[]  → items.push(x) is an error
 let best = null;             // null     → best = {...} is an error
 const [picks, set] = useState([]);  // never[] in a client, same thing
@@ -418,10 +467,11 @@ compile error, which is the point.
 
 `ctx.generate({ prompt, system?, llm?, schema?, temperature?, maxOutputTokens? })`
 runs one LLM generation on the host. It defaults to the agent's pipeline
-`llm`; pass an `llm` descriptor (from `@alexkroman1/aai/llm`) to use another
-provider whose API key is in the agent's secrets — that's also how S2S
-agents use it. `schema` must be a **plain JSON Schema object** (use
-`z.toJSONSchema(...)`), never a Zod schema.
+`llm`; pass an `llm` descriptor (from `@alexkroman1/aai/llm`) or a model-id
+string to use another provider whose API key is in the agent's secrets —
+that's also how S2S agents use it. Pass a Zod schema as `schema` for typed
+structured output (`generateObject`-style): the result's `object` carries
+the parsed, typed value. A plain JSON Schema object also works.
 
 ### Inline tool example
 
@@ -434,7 +484,7 @@ export default agent({
   tools: {
     get_weather: tool({
       description: "Get current weather for a city",
-      parameters: z.object({
+      inputSchema: z.object({
         city: z.string().describe("City name"),
       }),
       async execute({ city }, ctx) {
@@ -453,7 +503,7 @@ export default agent({
 them, and they are not on `ctx`. When your own `execute` needs one, import
 it:
 
-```ts
+```ts no-check
 import { fetchJson, visitWebpage, webSearch } from "@alexkroman1/aai/tools";
 
 execute: async ({ city }) => await fetchJson(`https://api.example.com/${city}`),
@@ -482,18 +532,18 @@ Wrapping `webSearch` in a single custom tool is the mistake to avoid — it
 replaces "the model searches as needed" with one fixed query-and-summarize
 pipeline, and no amount of prompting gets the flexibility back.
 
-**`parameters` is a Zod object, or absent.** The field itself is optional,
-but its VALUE must be a plain `z.object(...)` — so all of these are type
-errors:
+**`inputSchema` is a Zod object, or absent.** The field itself is
+optional, but its VALUE must be a plain `z.object(...)` — so all of these
+are type errors:
 
-```ts
-parameters: z.undefined(),                 // ✗ ZodUndefined
-parameters: z.void(),                      // ✗
-parameters: z.object({ q: z.string() }).optional(),  // ✗ ZodOptional
+```ts no-check
+inputSchema: z.undefined(),                // ✗ ZodUndefined
+inputSchema: z.void(),                     // ✗
+inputSchema: z.object({ q: z.string() }).optional(),  // ✗ ZodOptional
 ```
 
 For a tool with no arguments write `tool({ description, execute })`, or
-`parameters: z.object({})` if you prefer it explicit. To make an individual
+`inputSchema: z.object({})` if you prefer it explicit. To make an individual
 argument optional, put `.optional()` on the FIELD, never on the object:
 `z.object({ notes: z.string().optional() })`.
 
@@ -514,14 +564,14 @@ import { z } from "zod";
 
 export const rollDice = tool({
   description: "Roll dice",
-  parameters: z.object({ sides: z.number() }),
+  inputSchema: z.object({ sides: z.number() }),
   execute({ sides }) {
     return Math.floor(Math.random() * sides) + 1;
   },
 });
 ```
 
-```ts
+```ts no-check
 // agent.ts
 import { agent } from "@alexkroman1/aai";
 import { rollDice } from "./tools/roll_dice.ts";
@@ -584,7 +634,7 @@ call it from `execute` — see the builtin table above.
 Persistent SQL storage scoped per app, backed by the app's own Postgres
 schema. Access via `ctx.db`:
 
-```ts
+```ts no-check
 ctx.db.query<T = Record<string, unknown>>(sql: string, params?: unknown[]): Promise<T[]>
 ```
 
@@ -602,7 +652,7 @@ A query returning more than 1000 rows throws — always bound reads with
 
 Create tables lazily from tool code and upsert with `on conflict`:
 
-```ts
+```ts no-check
 await ctx.db.query(`create table if not exists app_state (
   key text primary key,
   value jsonb not null,
@@ -633,6 +683,7 @@ Always import `"@alexkroman1/aai-ui/styles.css"` first.
 ### Tier 1 — config only (default UI)
 
 ```tsx
+/// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
 import { client } from "@alexkroman1/aai-ui";
 
@@ -642,6 +693,7 @@ client({ name: "My Agent" });
 ### Tier 1 with sidebar
 
 ```tsx
+/// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
 import { client, useEvent } from "@alexkroman1/aai-ui";
 import { useState } from "react";
@@ -664,6 +716,7 @@ client({ name: "My Agent", sidebar: Sidebar });
 ### Tier 2 — full custom component
 
 ```tsx
+/// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
 import { client, useSession } from "@alexkroman1/aai-ui";
 
@@ -714,7 +767,7 @@ to put it in.
 | `state` | `AgentState` | `"disconnected"` `"connecting"` `"ready"` `"listening"` `"thinking"` `"speaking"` `"error"` |
 | `messages` | `ChatMessage[]` | `{ role, content }` |
 | `toolCalls` | `ToolCallInfo[]` | `{ callId, name, args, status, result? }` |
-| `customEvents` | `CustomEvent[]` | `{ id, event, data }` from `ctx.send()` |
+| `customEvents` | `AgentCustomEvent[]` | `{ id, event, data }` from `ctx.send()` |
 | `userTranscript` | `string \| null` | `null` = not speaking, `""` = speech detected, string = text |
 | `agentTranscript` | `string \| null` | `null` = not speaking, string = streaming response |
 | `error` | `SessionError \| null` | `{ code, message }` |
@@ -729,7 +782,7 @@ Methods: `start()`, `toggle()`, `reset()`, `cancel()`, `disconnect()`,
 **`useToolResult`** — fires once per completed tool call (deduplicates by
 callId):
 
-```ts
+```ts no-check
 useToolResult("tool_name", (result, toolCall) => { ... })          // one tool
 useToolResult((toolName, result, toolCall) => { ... })             // all tools
 useToolResult<ResultType>("tool_name", (result) => { ... })        // typed (optional)
@@ -746,7 +799,7 @@ also what you want for anything that can be a string, an array, or null.
 
 **`useAgentState`** — the agent's session state, pushed automatically:
 
-```ts
+```ts no-check
 // agent.ts
 export default agent({
   state: () => ({ cart: [] as Item[], staffPin: "" }),
@@ -772,7 +825,7 @@ after every tool call and is sent only when the result changed.
 
 **`useEvent`** — fires for custom events from `ctx.send()`:
 
-```ts
+```ts no-check
 useEvent<DataType>("event_name", (data) => { ... })
 ```
 
@@ -793,13 +846,33 @@ Available from `@alexkroman1/aai-ui`:
 
 | Component | Props | Description |
 | --- | --- | --- |
-| `StartScreen` | `children, icon?, title?, subtitle?, buttonText?` | Centered start card; renders children after start |
+| `StartScreen` | `children` (**required**)`, icon?, title?, subtitle?, buttonText?` | **Wrapper, never self-closing.** Shows the start card, then renders `children` — your whole app — once the session starts |
 | `ChatView` | `icon?, title?` | Chat interface (header + messages + controls) |
 | `SidebarLayout` | `sidebar, children, sidebarWidth?, sidebarPosition?` | Two-column layout |
 | `MessageList` | — | Messages with auto-scroll, tool calls, transcript |
 | `Controls` | — | Stop/Resume + New Conversation buttons |
 | `Button` | — | Styled button |
 
+The usual shape — note `StartScreen` **wraps** the app rather than sitting
+beside it; writing `<StartScreen ... />` self-closing is a `TS2741:
+Property 'children' is missing` build error:
+
+```tsx
+/// <reference types="vite/client" />
+import "@alexkroman1/aai-ui/styles.css";
+import { ChatView, client, StartScreen } from "@alexkroman1/aai-ui";
+
+function PizzaApp() {
+  return (
+    <StartScreen title="Pizza Palace" subtitle="Voice-powered ordering">
+      <ChatView />
+    </StartScreen>
+  );
+}
+
+client({ component: PizzaApp });
+```
+
 ## Styling
 
 - **Tailwind CSS v4** — compiled at bundle time, configured via CSS.
@@ -877,8 +950,8 @@ Common mistakes when working in aai projects:
   values are injected into LLM context. Truncate, summarize, or extract
   only what the model needs.
 - **Pipeline mode requires all three of `stt` / `llm` / `tts`.** Partial
-  configs are rejected at parse time. Use S2S (omit all three) if you
-  don't need provider control.
+  configs are rejected at parse time. Omit all three for the default
+  AssemblyAI pipeline; S2S needs an explicit `s2s: assemblyAIS2s()`.
 - **Never hardcode secrets.** Use `ctx.env.MY_KEY`. `.env` for local dev,
   `aai secret put` for production.
 - **Don't use `useEffect` + `toolCalls` to derive state.** Use
@@ -906,10 +979,10 @@ Common mistakes when working in aai projects:
 
 ## Constraints
 
-- Tool `execute` return values go into LLM context — filter and truncate
-  large API responses
-- `fetch` is proxied through the host; private/internal IPs are blocked
-  (SSRF protection)
+- Tool `execute` return values go into LLM context, capped at 4000 chars
+  (a truncation marker replaces the tail) — filter large API responses
+- Tool code uses plain `fetch` with open egress; the keyless web builtins
+  screen private/internal IPs (SSRF) when running outside a sandbox
 - Agent code runs in a sandboxed worker — use `fetch` for HTTP, `ctx.env`
   for secrets
 - Tool execution timeout: 30 seconds

package/dist/scaffold/package.json

@@ -11,15 +11,15 @@
     "deploy": "aai deploy"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^5.2.0",
-    "@alexkroman1/aai-ui": "^5.2.0",
+    "@alexkroman1/aai": "^5.4.0",
+    "@alexkroman1/aai-ui": "^5.4.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^5.2.0",
+    "@alexkroman1/aai-cli": "^5.4.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.1.1",
     "@types/react": "^19.2.17",

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

@@ -90,17 +90,17 @@ describe("dispatch-center template", () => {
 
   test("negative casualty counts are rejected by the parameter schemas", () => {
     expect(
-      incidentTriage.parameters?.safeParse({ incidentId: "INC-0001", casualtyUpdate: -5 }).success,
+      incidentTriage.inputSchema?.safeParse({ incidentId: "INC-0001", casualtyUpdate: -5 }).success,
     ).toBe(false);
     expect(
-      incidentCreate.parameters?.safeParse({
+      incidentCreate.inputSchema?.safeParse({
         location: "1 First St",
         description: "fire",
         estimatedCasualties: -1,
       }).success,
     ).toBe(false);
     expect(
-      incidentUpdateStatus.parameters?.safeParse({
+      incidentUpdateStatus.inputSchema?.safeParse({
         incidentId: "INC-0001",
         status: "on_scene",
         casualtyUpdate: { confirmed: -2 },