@alexkroman1/aai-cli 5.3.0 → 5.5.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,23 @@ 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`, `retail` (the most complex — 15 tools over a
+   relational store, with a `syncState`-driven UI). 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 +51,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 +71,32 @@ 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..."
+  voice?: string;                            // TTS voice for the default pipeline, e.g. "michael"
+                                             // (shorthand for tts: assemblyAITts({ voice });
+                                             // invalid with an explicit `tts` or with `s2s`)
+  stt?: SttProvider;                         // pipeline stage overrides — set any subset;
+  llm?: LlmProvider | string;                // unset stages default to AssemblyAI
+  tts?: TtsProvider;                         // (llm also takes a model-id string)
+  s2s?: S2sProvider;                         // explicit opt-in to speech-to-speech mode
   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
@@ -90,41 +106,60 @@ export default agent({
 });
 ```
 
-> When `stt`, `llm`, and `tts` are all provided, the agent runs in
-> **Pipeline mode** — see the section below.
+> Unless `s2s` is set, the agent runs in **Pipeline mode** — see the section
+> below. Declare any subset of `stt`/`llm`/`tts`; unset stages default to
+> AssemblyAI. `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:
 
 ```ts
-import { agent, assemblyAIPipeline } from "@alexkroman1/aai";
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "My Agent",
-  ...assemblyAIPipeline(),
 });
 ```
 
-`assemblyAIPipeline()` sets all three stages to AssemblyAI, which bill to
-the one key a published agent is guaranteed to have. Override a single stage
-by setting it after the spread — everything else stays as the preset put it:
+No provider fields means the default all-AssemblyAI pipeline: all three
+stages bill to the one key a published agent is guaranteed to have. Pick
+its voice with the `voice` field — this is the normal way to choose a
+voice:
 
 ```ts
-import { agent, assemblyAIPipeline } from "@alexkroman1/aai";
-import { assemblyAI as assemblyAITts } from "@alexkroman1/aai/tts";
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "My Agent",
-  ...assemblyAIPipeline(),
-  tts: assemblyAITts({ voice: "paul" }),
+  voice: "paul",
 });
 ```
 
-`agent({ name })` alone is legal and gives you S2S mode instead — see below.
+Swap a single stage by declaring just that field — everything you leave
+unset stays on the default. `llm` accepts the gateway model id as a plain
+string:
+
+```ts
+import { agent } from "@alexkroman1/aai";
+
+export default agent({
+  name: "My Agent",
+  llm: "claude-sonnet-4-6",
+});
+```
+
+`assemblyAIPipeline()` (from `@alexkroman1/aai`) is the explicit spelling of
+the same default — spread it (`...assemblyAIPipeline({ region: "eu" })`) when
+you want the three stages visible in the config or EU data residency across
+STT and the LLM gateway. 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,33 +173,56 @@ 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, and any stage you do declare replaces just
+that stage — the rest keep the default.
+
+**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** — declare all three — unless the user specifically
+**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
   LLM Gateway)
-- you want a specific STT model or TTS voice
+- you want a specific STT model, or a non-AssemblyAI TTS provider (for the
+  default pipeline's voice, use the `voice` field instead)
 - 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:** declare only the stages you're changing — any subset of
+`stt`, `llm`, `tts`; each unset stage runs on the AssemblyAI default.
+Combining `s2s` with any pipeline provider or pipeline-only tuning field is
+a compile error naming the rule, as is `voice` alongside an explicit `tts`
+descriptor (the descriptor owns its own voice). A raw config that skips
+`agent()` is still checked 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 +244,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 +261,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,62 +305,60 @@ 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. A bare model-id string on
+`llm` is shorthand for it, and unset stages keep the AssemblyAI default:
 
 ```ts
-import { assemblyAI } from "@alexkroman1/aai/stt";
-import { assemblyAI as assemblyAILlm } from "@alexkroman1/aai/llm";
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "My Agent",
-  stt: assemblyAI({ model: "universal-3-5-pro" }),
-  llm: assemblyAILlm({ model: "claude-sonnet-4-6" }),
-  tts: cartesia(),
+  llm: "claude-sonnet-4-6",
 });
 ```
 
-An all-AssemblyAI pipeline — one provider, one key:
+`assemblyAILlm({ model, region: "eu" })` is the explicit form; `region`
+selects EU data residency.
+
+Mixing providers works the same way — declare the stages you're changing:
 
 ```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 { cartesia } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
-  stt: assemblyAI({ model: "universal-3-5-pro" }),
-  llm: assemblyAILlm({ model: "gemini-2.5-flash-lite" }),
-  tts: assemblyAITts({ voice: "vera" }),
+  llm: "claude-sonnet-4-6",
+  tts: cartesia(),
 });
 ```
 
 ### 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
-LLM Gateway, so an all-AssemblyAI pipeline needs exactly one secret. Each
+LLM Gateway, so an all-AssemblyAI pipeline needs exactly one secret. On the
+default pipeline, `agent({ voice: "michael" })` is the shorthand for
+`tts: assemblyAITts({ voice: "michael" })` — same catalog, same rules. Each
 voice speaks one language, and this is the whole catalog — **a voice not on
 this list is rejected after the socket opens, which leaves the agent
 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 +369,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 +379,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 +395,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 +409,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 +422,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 +474,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 +491,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 +510,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 +539,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 +571,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 +641,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 +659,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 +690,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 +700,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,11 +723,12 @@ 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";
 
 function MyApp() {
-  const { messages, userTranscript, started, running, start, toggle, reset } =
+  const { messages, userTranscript, started, running, start, toggle, end } =
     useSession();
   return (
     <div>
@@ -679,7 +739,7 @@ function MyApp() {
       ) : (
         <>
           <button onClick={toggle}>{running ? "Stop" : "Resume"}</button>
-          <button onClick={reset}>Reset</button>
+          <button onClick={end}>End</button>
         </>
       )}
     </div>
@@ -714,22 +774,30 @@ 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 }` |
 | `started` | `boolean` | Whether session started |
 | `running` | `boolean` | Whether session active |
 
-Methods: `start()`, `toggle()`, `reset()`, `cancel()`, `disconnect()`,
-`resetState()`.
+Methods: `start()`, `toggle()`, `end()`, `reset()`, `cancel()`,
+`disconnect()`, `resetState()`.
+
+- `end()` hangs up: it flips `started` back to `false` (a start-screen UI
+  shows its Start control again) and the next `start()` is a brand-new
+  session — fresh per-session tool state, greeting included. Use it for
+  End/Hang up/New game buttons.
+- `reset()` clears the conversation but keeps the call live (`started`
+  stays `true`) — the control stays on Stop/Resume, and per-session tool
+  state survives. Use it for a "clear chat" control, not for ending.
 
 ## UI hooks
 
 **`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 +814,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 +840,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) => { ... })
 ```
 
@@ -805,6 +873,7 @@ 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";
 
@@ -895,9 +964,10 @@ Common mistakes when working in aai projects:
 - **Filter large API responses before returning them from tools.** Return
   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.
+- **Declare only the pipeline stages you're changing.** Unset stages of
+  `stt` / `llm` / `tts` default to AssemblyAI (omit all three for the full
+  default pipeline; `voice` picks its TTS voice). S2S needs an explicit
+  `s2s: assemblyAIS2s()` and takes no pipeline fields.
 - **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
@@ -925,10 +995,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