@alexkroman1/aai-cli 5.4.0 → 5.5.0

package/dist/{_agent-D8zBb3M5.mjs → _agent-DMyOab9_.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-D3F9km8X.mjs";
+import { a as readProjectConfig, i as readGlobalConfig, n as ensureApiKey, o as serverOrigin, t as approveServer } from "./_config-5AEqhh-O.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -92,4 +92,4 @@ async function getServerInfo(cwd, explicitServer) {
 	};
 }
 //#endregion
-export { resolveDeployTarget as i, getServerInfo as n, isDevMode as r, getMonorepoRoot as t };
+export { resolveServerUrl as a, resolveDeployTarget as i, getServerInfo as n, isDevMode as r, getMonorepoRoot as t };

package/dist/{_config-D3F9km8X.mjs → _config-5AEqhh-O.mjs}

@@ -115,10 +115,10 @@ async function ensureApiKey(configDir) {
 		await trySaveApiKey(dir, config, envKey);
 		return envKey;
 	}
-	if (!process.stdin.isTTY) throw new CliError("no_api_key", "No API key configured and no TTY to prompt for one.", "Set the ASSEMBLYAI_API_KEY environment variable, or run `aai` interactively once to save a key.");
+	if (!process.stdin.isTTY) throw new CliError("no_api_key", "No API key configured and no TTY to prompt for one.", "Set the ASSEMBLYAI_API_KEY environment variable, or run `aai login` interactively once to save a key.");
 	const apiKey = unwrapCancel(await p.password({ message: "Enter your AssemblyAI API key" }), "Setup cancelled");
 	await trySaveApiKey(dir, config, apiKey);
 	return apiKey;
 }
 //#endregion
-export { serverOrigin as a, readProjectConfig as i, ensureApiKey as n, writeProjectConfig as o, readGlobalConfig as r, approveServer as t };
+export { readProjectConfig as a, writeProjectConfig as c, readGlobalConfig as i, ensureApiKey as n, serverOrigin as o, getConfigDir as r, writeGlobalConfig as s, approveServer as t };

package/dist/{_dev-server-cigzayJe.mjs → _dev-server-vV05Fnki.mjs}

@@ -4,7 +4,7 @@ import { a as errorMessage, r as errorCode } from "./_utils-Ch0J4s6a.mjs";
 import { n as fallbackHtmlPlugin } from "./client-bundler-yiWoXrgb.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import { n as createWorkerEvaluator } from "./_bundler-Cjaxa2wi.mjs";
-import { n as ensureApiKey } from "./_config-D3F9km8X.mjs";
+import { n as ensureApiKey } from "./_config-5AEqhh-O.mjs";
 import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";

package/dist/{_init-_G8l4lh2.mjs → _init-BZ9t_Kz-.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-D8zBb3M5.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-DW9CvuDN.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DMyOab9_.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-Bv8CR800.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region _init.ts

package/dist/{_slug-api-19R5kZ0U.mjs → _slug-api-DaqQJHk8.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as getServerInfo } from "./_agent-D8zBb3M5.mjs";
+import { n as getServerInfo } from "./_agent-DMyOab9_.mjs";
 import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-MenP4-O7.mjs";
 //#region _slug-api.ts
 /**

package/dist/{_templates-DW9CvuDN.mjs → _templates-Bv8CR800.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { a as errorMessage } from "./_utils-Ch0J4s6a.mjs";
-import { t as getMonorepoRoot } from "./_agent-D8zBb3M5.mjs";
+import { t as getMonorepoRoot } from "./_agent-DMyOab9_.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";

package/dist/cli.mjs

@@ -108,7 +108,7 @@ const init = defineCommand({
 	},
 	async run({ args }) {
 		await runCommand(args, async (mode) => {
-			const { executeInit } = await import("./init-BkW9BuZF.mjs");
+			const { executeInit } = await import("./init-DoU4_txp.mjs");
 			return executeInit({
 				dir: args.dir,
 				force: args.force,
@@ -137,7 +137,7 @@ const dev = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeDev } = await import("./dev-2oUsvgRX.mjs");
+			const { executeDev } = await import("./dev-gVNdGFYY.mjs");
 			return executeDev({
 				cwd,
 				port: args.port
@@ -207,7 +207,7 @@ const deploy = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup({ agent: true });
-			const { executeDeploy } = await import("./deploy-C0VLnnJe.mjs");
+			const { executeDeploy } = await import("./deploy-1eaXcfUw.mjs");
 			return executeDeploy({
 				cwd,
 				server: args.server,
@@ -229,7 +229,7 @@ const del = defineCommand({
 	async run({ args }) {
 		await runCommand(args, async () => {
 			const cwd = await setup();
-			const { executeDelete } = await import("./delete-kSXFLxek.mjs");
+			const { executeDelete } = await import("./delete-DXilFBb1.mjs");
 			return executeDelete({
 				cwd,
 				server: args.server
@@ -260,7 +260,7 @@ const secret = defineCommand({
 			async run({ args }) {
 				await runCommand(args, async (mode) => {
 					const cwd = await setup();
-					const { executeSecretPut, NO_INPUT, readStdin } = await import("./secret-DOva9OGk.mjs");
+					const { executeSecretPut, NO_INPUT, readStdin } = await import("./secret-CGAIAbUx.mjs");
 					const value = mode === "json" ? await readStdin() : void 0;
 					if (mode === "json" && !value) throw new CliError(...NO_INPUT);
 					return executeSecretPut(cwd, args.name, value, args.server);
@@ -284,7 +284,7 @@ const secret = defineCommand({
 			async run({ args }) {
 				await runCommand(args, async () => {
 					const cwd = await setup();
-					const { executeSecretDelete } = await import("./secret-DOva9OGk.mjs");
+					const { executeSecretDelete } = await import("./secret-CGAIAbUx.mjs");
 					return executeSecretDelete(cwd, args.name, args.server);
 				});
 			}
@@ -301,7 +301,7 @@ const secret = defineCommand({
 			async run({ args }) {
 				await runCommand(args, async () => {
 					const cwd = await setup();
-					const { executeSecretList } = await import("./secret-DOva9OGk.mjs");
+					const { executeSecretList } = await import("./secret-CGAIAbUx.mjs");
 					return executeSecretList(cwd, args.server);
 				});
 			}
@@ -336,7 +336,7 @@ const storage = defineCommand({
 			},
 			async run({ args }) {
 				await runCommand(args, async () => {
-					const { executeStorageStatus } = await import("./storage-vM6HjDZZ.mjs");
+					const { executeStorageStatus } = await import("./storage-CnhOayhm.mjs");
 					return executeStorageStatus(resolveStorageCwd(args.dir), args.server);
 				});
 			}
@@ -353,7 +353,7 @@ const storage = defineCommand({
 			},
 			async run({ args }) {
 				await runCommand(args, async () => {
-					const { executeStorageEnable } = await import("./storage-vM6HjDZZ.mjs");
+					const { executeStorageEnable } = await import("./storage-CnhOayhm.mjs");
 					return executeStorageEnable(resolveStorageCwd(args.dir), args.server);
 				});
 			}
@@ -375,7 +375,7 @@ const storage = defineCommand({
 			},
 			async run({ args }) {
 				await runCommand(args, async () => {
-					const { executeStorageDisable } = await import("./storage-vM6HjDZZ.mjs");
+					const { executeStorageDisable } = await import("./storage-CnhOayhm.mjs");
 					return executeStorageDisable(resolveStorageCwd(args.dir), {
 						server: args.server,
 						force: args.force
@@ -385,6 +385,22 @@ const storage = defineCommand({
 		})
 	}
 });
+const login = defineCommand({
+	meta: {
+		name: "login",
+		description: "Sign in with your email and save your API key"
+	},
+	args: {
+		server: sharedArgs.server,
+		json: sharedArgs.json
+	},
+	async run({ args }) {
+		await runCommand(args, async () => {
+			const { executeLogin } = await import("./login-C59ZHzuO.mjs");
+			return executeLogin({ server: args.server });
+		});
+	}
+});
 const templates = defineCommand({
 	meta: {
 		name: "templates",
@@ -393,7 +409,7 @@ const templates = defineCommand({
 	args: { json: sharedArgs.json },
 	async run({ args }) {
 		await runCommand(args, async (mode) => {
-			const { listTemplates } = await import("./_templates-DW9CvuDN.mjs");
+			const { listTemplates } = await import("./_templates-Bv8CR800.mjs");
 			const names = await listTemplates();
 			if (mode === "human") {
 				for (const name of names) log.message(name);
@@ -419,6 +435,7 @@ const mainCommand = defineCommand({
 		build,
 		deploy,
 		delete: del,
+		login,
 		secret,
 		storage,
 		templates

package/dist/{delete-kSXFLxek.mjs → delete-DXilFBb1.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as log, u as ok } from "./_ui-8kOEB-JH.mjs";
-import { n as getServerInfo } from "./_agent-D8zBb3M5.mjs";
+import { n as getServerInfo } from "./_agent-DMyOab9_.mjs";
 import { n as apiRequest, t as HINT_NOT_DEPLOYED } from "./_api-client-MenP4-O7.mjs";
 //#region delete.ts
 async function runDelete(opts) {

package/dist/{deploy-C0VLnnJe.mjs → deploy-1eaXcfUw.mjs}

@@ -2,9 +2,9 @@
 import { n as log, t as fmtUrl, u as ok } from "./_ui-8kOEB-JH.mjs";
 import { a as errorMessage } from "./_utils-Ch0J4s6a.mjs";
 import { t as buildAgentBundle } from "./_bundler-Cjaxa2wi.mjs";
-import { o as writeProjectConfig } from "./_config-D3F9km8X.mjs";
+import { c as writeProjectConfig } from "./_config-5AEqhh-O.mjs";
 import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
-import { i as resolveDeployTarget } from "./_agent-D8zBb3M5.mjs";
+import { i as resolveDeployTarget } from "./_agent-DMyOab9_.mjs";
 import { t as assertTypechecks } from "./_typecheck-gate-9IHWDnl1.mjs";
 import { n as apiRequest } from "./_api-client-MenP4-O7.mjs";
 import { gzipSync } from "node:zlib";

package/dist/{dev-2oUsvgRX.mjs → dev-gVNdGFYY.mjs}

@@ -11,7 +11,7 @@ import { styleText } from "node:util";
 async function executeDev(opts) {
 	const port = parsePort(opts.port);
 	const agentName = path.basename(path.resolve(opts.cwd));
-	const { startDevServer } = await import("./_dev-server-cigzayJe.mjs");
+	const { startDevServer } = await import("./_dev-server-vV05Fnki.mjs");
 	let cleanup;
 	let shuttingDown = false;
 	const onSignal = () => {

package/dist/{init-BkW9BuZF.mjs → init-DoU4_txp.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { a as unwrapCancel, n as log, u as ok } from "./_ui-8kOEB-JH.mjs";
 import { a as errorMessage, c as readJson, l as resolveCwd, o as fileExists, t as AGENT_ENTRY } from "./_utils-Ch0J4s6a.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-D8zBb3M5.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DMyOab9_.mjs";
 import path from "node:path";
 import { styleText } from "node:util";
 import * as p from "@clack/prompts";
@@ -74,7 +74,7 @@ function resolveTargetDir(dir) {
 }
 /** Run deploy after init and return deploy metadata if successful. */
 async function tryDeploy(cwd, server) {
-	const { executeDeploy } = await import("./deploy-C0VLnnJe.mjs");
+	const { executeDeploy } = await import("./deploy-1eaXcfUw.mjs");
 	try {
 		const result = await executeDeploy({
 			cwd,
@@ -92,7 +92,7 @@ async function tryDeploy(cwd, server) {
 }
 /** Scaffold the project, optionally showing a spinner. */
 async function scaffoldProject(dir, cwd, template, silent) {
-	const { runInit } = await import("./_init-_G8l4lh2.mjs");
+	const { runInit } = await import("./_init-BZ9t_Kz-.mjs");
 	const s = silent ? void 0 : p.spinner();
 	s?.start(`Creating ${dir}`);
 	await runInit({

package/dist/login-C59ZHzuO.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import { a as unwrapCancel, n as log, o as CliError, u as ok } from "./_ui-8kOEB-JH.mjs";
+import { i as readGlobalConfig, r as getConfigDir, s as writeGlobalConfig, t as approveServer } from "./_config-5AEqhh-O.mjs";
+import { a as resolveServerUrl } from "./_agent-DMyOab9_.mjs";
+import * as p from "@clack/prompts";
+//#region login.ts
+/**
+* `aai login` — email sign-in against the platform, ending with the
+* account's AssemblyAI API key stored in the global config (the same slot
+* `ensureApiKey` reads), so every other command is untouched by how the
+* key was acquired.
+*
+* Flow (the CLI mirror of the browser studio's two gates):
+* 1. `GET /studio/auth` names the login mode.
+*    - `supabase`: Supabase email OTP — `POST /auth/v1/otp` emails a
+*      one-time code, the user types it here, `POST /auth/v1/verify`
+*      returns the session. The magic LINK in the same email targets the
+*      browser; the CLI uses the code because a terminal has no redirect
+*      to land on. (The Supabase email template must include the
+*      `{{ .Token }}` code for this to work.)
+*    - `dev`: mint the same self-describing dev token the studio's local
+*      login mints — nothing is emailed anywhere.
+* 2. `GET /studio/account` — when no key is on file yet, prompt for one
+*    and `PUT /studio/account/key` (the same mandatory onboarding step
+*    the browser shows after sign-in).
+* 3. `GET /studio/account/key` — fetch the key and save it locally.
+*    Unlike the browser, the CLI needs the RAW key: `aai dev` runs the
+*    provider pipeline in-process on it.
+*/
+async function jsonBody(res, what) {
+	const body = await res.json().catch(() => null);
+	if (!res.ok) throw new CliError("login_failed", `${what} failed: ${body?.error ?? body?.msg ?? `HTTP ${res.status}`}`);
+	if (body === null) throw new CliError("login_failed", `${what} returned an invalid response`);
+	return body;
+}
+function requireTty() {
+	if (!process.stdin.isTTY) throw new CliError("login_interactive", "`aai login` is interactive and needs a TTY.", "Non-interactive setups can set the ASSEMBLYAI_API_KEY environment variable instead.");
+}
+/** The same self-describing token the studio's local-dev login mints. */
+function mintDevToken(email) {
+	return `dev.${Buffer.from(JSON.stringify({
+		id: `dev:${email}`,
+		email
+	})).toString("base64url").replace(/=+$/, "")}.dev`;
+}
+/** Supabase email OTP: send the code, prompt for it, verify to a session. */
+async function supabaseSession(auth, email, fetchFn) {
+	const base = auth.supabaseUrl.replace(/\/+$/, "");
+	const headers = {
+		apikey: auth.supabasePublishableKey,
+		"Content-Type": "application/json"
+	};
+	await jsonBody(await fetchFn(`${base}/auth/v1/otp`, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({
+			email,
+			create_user: true
+		})
+	}), "Sending the sign-in code");
+	log.info(`Sent a sign-in code to ${email}.`);
+	const code = unwrapCancel(await p.text({ message: "Enter the code from your email" }), "Login cancelled").trim();
+	const session = await jsonBody(await fetchFn(`${base}/auth/v1/verify`, {
+		method: "POST",
+		headers,
+		body: JSON.stringify({
+			type: "email",
+			email,
+			token: code
+		})
+	}), "Verifying the code");
+	if (!session.access_token) throw new CliError("login_failed", "Verifying the code did not return a session.");
+	return session.access_token;
+}
+async function executeLogin(opts, deps = {}) {
+	const fetchFn = deps.fetchFn ?? globalThis.fetch;
+	requireTty();
+	const globalConfig = await readGlobalConfig();
+	const serverUrl = resolveServerUrl(opts.server, void 0, globalConfig.approvedServers ?? []);
+	if (opts.server) await approveServer(serverUrl);
+	const auth = await jsonBody(await fetchFn(`${serverUrl}/studio/auth`), "Reading the server's login configuration");
+	if (auth.mode === "none") throw new CliError("login_unavailable", "This server has no browser/email login configured.", "Set the ASSEMBLYAI_API_KEY environment variable, or run any platform command to be prompted for a key.");
+	const email = unwrapCancel(await p.text({ message: "Email address" }), "Login cancelled").trim();
+	const bearer = { Authorization: `Bearer ${auth.mode === "dev" ? mintDevToken(email) : await supabaseSession(auth, email, fetchFn)}` };
+	if (!(await jsonBody(await fetchFn(`${serverUrl}/studio/account`, { headers: bearer }), "Loading your account")).hasKey) {
+		const newKey = unwrapCancel(await p.password({ message: "Enter your AssemblyAI API key (stored with your account)" }), "Login cancelled").trim();
+		await jsonBody(await fetchFn(`${serverUrl}/studio/account/key`, {
+			method: "PUT",
+			headers: {
+				...bearer,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({ apiKey: newKey })
+		}), "Saving your API key");
+	}
+	const { apiKey } = await jsonBody(await fetchFn(`${serverUrl}/studio/account/key`, { headers: bearer }), "Fetching your API key");
+	const dir = getConfigDir();
+	await writeGlobalConfig(dir, {
+		...await readGlobalConfig(dir),
+		apiKey
+	});
+	log.success(`Signed in as ${email} — your API key is saved for future commands.`);
+	return ok({
+		email,
+		server: serverUrl
+	});
+}
+//#endregion
+export { executeLogin };

package/dist/login.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `aai login` — email sign-in against the platform, ending with the
+ * account's AssemblyAI API key stored in the global config (the same slot
+ * `ensureApiKey` reads), so every other command is untouched by how the
+ * key was acquired.
+ *
+ * Flow (the CLI mirror of the browser studio's two gates):
+ * 1. `GET /studio/auth` names the login mode.
+ *    - `supabase`: Supabase email OTP — `POST /auth/v1/otp` emails a
+ *      one-time code, the user types it here, `POST /auth/v1/verify`
+ *      returns the session. The magic LINK in the same email targets the
+ *      browser; the CLI uses the code because a terminal has no redirect
+ *      to land on. (The Supabase email template must include the
+ *      `{{ .Token }}` code for this to work.)
+ *    - `dev`: mint the same self-describing dev token the studio's local
+ *      login mints — nothing is emailed anywhere.
+ * 2. `GET /studio/account` — when no key is on file yet, prompt for one
+ *    and `PUT /studio/account/key` (the same mandatory onboarding step
+ *    the browser shows after sign-in).
+ * 3. `GET /studio/account/key` — fetch the key and save it locally.
+ *    Unlike the browser, the CLI needs the RAW key: `aai dev` runs the
+ *    provider pipeline in-process on it.
+ */
+import { type CommandResult } from "./_output.ts";
+export type LoginDeps = {
+    /** Test seam — never set outside tests. */
+    fetchFn?: typeof globalThis.fetch;
+};
+export declare function executeLogin(opts: {
+    server?: string | undefined;
+}, deps?: LoginDeps): Promise<CommandResult<{
+    email: string;
+    server: string;
+}>>;

package/dist/scaffold/CLAUDE.md

@@ -27,7 +27,9 @@ 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`. When reading SDK types under
+   `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
@@ -77,6 +79,13 @@ export default agent({
   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>;
@@ -97,55 +106,55 @@ export default agent({
 });
 ```
 
-> When `stt`, `llm`, and `tts` are all provided, the agent runs in
-> **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`).
+> 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 { assemblyAITts } from "@alexkroman1/aai/tts";
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "My Agent",
-  ...assemblyAIPipeline(),
-  tts: assemblyAITts({ voice: "paul" }),
+  voice: "paul",
 });
 ```
 
-The same pattern changes the gateway LLM model — `llm` accepts the model id
-as a plain string:
+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, assemblyAIPipeline } from "@alexkroman1/aai";
+import { agent } 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.
+`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:
 
@@ -165,8 +174,8 @@ explicit the modern spelling is `with { type: "json" }`, but plain is fine.
 ## Pipeline mode
 
 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.
+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
@@ -194,14 +203,16 @@ 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.
-`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.
+**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";
@@ -297,37 +308,31 @@ hundreds of models addressed as `"creator/model"`, e.g.
 `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:
+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 { 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: assemblyAIStt({ model: "universal-3-5-pro" }),
-  llm: assemblyAILlm({ model: "claude-sonnet-4-6" }),
-  tts: cartesia(),
+  llm: "claude-sonnet-4-6",
 });
 ```
 
-It accepts an optional `region: "eu"` for EU data residency.
+`assemblyAILlm({ model, region: "eu" })` is the explicit form; `region`
+selects EU data residency.
 
-An all-AssemblyAI pipeline — one provider, one key:
+Mixing providers works the same way — declare the stages you're changing:
 
 ```ts
 import { agent } from "@alexkroman1/aai";
-import { assemblyAILlm } from "@alexkroman1/aai/llm";
-import { assemblyAIStt } from "@alexkroman1/aai/stt";
-import { assemblyAITts } from "@alexkroman1/aai/tts";
+import { cartesia } from "@alexkroman1/aai/tts";
 
 export default agent({
   name: "My Agent",
-  stt: assemblyAIStt({ model: "universal-3-5-pro" }),
-  llm: assemblyAILlm({ model: "gemini-2.5-flash-lite" }),
-  tts: assemblyAITts({ voice: "jane" }),
+  llm: "claude-sonnet-4-6",
+  tts: cartesia(),
 });
 ```
 
@@ -343,7 +348,9 @@ 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
@@ -721,7 +728,7 @@ 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>
@@ -732,7 +739,7 @@ function MyApp() {
       ) : (
         <>
           <button onClick={toggle}>{running ? "Stop" : "Resume"}</button>
-          <button onClick={reset}>Reset</button>
+          <button onClick={end}>End</button>
         </>
       )}
     </div>
@@ -774,8 +781,16 @@ to put it in.
 | `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
 
@@ -949,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. Omit all three for the default
-  AssemblyAI pipeline; S2S needs an explicit `s2s: assemblyAIS2s()`.
+- **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