@alexkroman1/aai-cli 14.0.0 → 15.1.0

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { i as installStdoutGuard, n as fail, o as writeLine, r as getOutputMode, t as CliError } from "./_output-DBP9Op_d.mjs";
-import { n as log, o as silenceOutput } from "./_ui-DCt4qZrk.mjs";
+import { a as parsePort, n as log, o as silenceOutput } from "./_ui-DCt4qZrk.mjs";
 import { c as fileExists, f as readPackageJson, p as resolveCwd, s as errorMessage$1, t as AGENT_ENTRY } from "./_utils-D5JGcjiW.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { isRecord, plural } from "@alexkroman1/aai/utils";
+import { isRecord, omitUndefined, plural } from "@alexkroman1/aai/utils";
 import { defineCommand, runMain, showUsage } from "citty";
 //#region src/_cli-common.ts
 /** Shared arg definitions for citty commands. */
@@ -395,7 +395,7 @@ const list = defineExec({
 	args: { ...platformArgs },
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeList } = await import("./studio-CpHlNHUZ.mjs");
+		const { executeList } = await import("./studio-C_zuRC_z.mjs");
 		return executeList({
 			cwd,
 			server: args.server
@@ -427,7 +427,7 @@ const pull = defineExec({
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executePull } = await import("./studio-CpHlNHUZ.mjs");
+		const { executePull } = await import("./studio-C_zuRC_z.mjs");
 		return executePull({
 			cwd,
 			project: args.project,
@@ -448,7 +448,7 @@ const push = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePush } = await import("./studio-CpHlNHUZ.mjs");
+		const { executePush } = await import("./studio-C_zuRC_z.mjs");
 		return executePush({
 			cwd,
 			server: args.server,
@@ -471,7 +471,7 @@ const publish = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePublish } = await import("./studio-CpHlNHUZ.mjs");
+		const { executePublish } = await import("./studio-C_zuRC_z.mjs");
 		return executePublish({
 			cwd,
 			server: args.server,
@@ -693,26 +693,19 @@ const init = defineExec({
 		template: {
 			type: "string",
 			alias: "t",
-			description: "Template to use (run `aai templates` for the list)"
+			description: "Template to use (prompted when omitted)"
 		},
-		server: sharedArgs.server,
 		yes: sharedArgs.yes,
-		json: sharedArgs.json,
-		skipDeploy: {
-			type: "boolean",
-			description: "Skip deploy after scaffolding"
-		}
+		json: sharedArgs.json
 	},
 	cwd: "none",
 	async run({ args, mode }) {
-		const { executeInit } = await import("./init-DukDxECd.mjs");
+		const { executeInit } = await import("./init-CQbj3ycf.mjs");
 		return executeInit({
 			dir: args.dir,
 			force: args.force,
 			template: args.template,
-			yes: mode === "json" ? true : args.yes,
-			skipDeploy: args.skipDeploy,
-			server: args.server
+			yes: mode === "json" ? true : args.yes
 		}, mode === "json" ? { silent: true } : void 0);
 	}
 });
@@ -736,7 +729,7 @@ const dev = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeDev } = await import("./dev-DApPSaE_.mjs");
+		const { executeDev } = await import("./dev-Bx9gYBHM.mjs");
 		return executeDev({
 			cwd,
 			port: args.port,
@@ -744,6 +737,35 @@ const dev = defineExec({
 		});
 	}
 });
+const start = defineExec({
+	meta: {
+		name: "start",
+		description: "Serve the built agent (production)"
+	},
+	args: {
+		port: {
+			type: "string",
+			alias: "p",
+			description: "Port to listen on"
+		},
+		host: {
+			type: "string",
+			description: "Address to bind (default: loopback)"
+		},
+		json: sharedArgs.json
+	},
+	cwd: "agent",
+	async run({ args, cwd }) {
+		const { executeStart } = await import("./start.mjs");
+		return executeStart({
+			cwd,
+			...omitUndefined({
+				port: args.port === void 0 ? void 0 : parsePort(args.port),
+				host: args.host?.trim() || void 0
+			})
+		});
+	}
+});
 const test = defineExec({
 	meta: {
 		name: "test",
@@ -770,7 +792,7 @@ const evalCommand = defineExec({
 	args: { json: sharedArgs.json },
 	cwd: "agent",
 	async run({ cwd }) {
-		const { executeEval } = await import("./eval-BK47A_K5.mjs");
+		const { executeEval } = await import("./eval-B3I7FqN9.mjs");
 		return executeEval(cwd);
 	}
 });
@@ -788,15 +810,20 @@ const build = defineExec({
 		skipTypecheck: {
 			type: "boolean",
 			description: "Skip type checking before build"
+		},
+		target: {
+			type: "string",
+			description: "Deployment shape to emit (node, vercel; default: detected)"
 		}
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeBuild } = await import("./build-Mxk8gWvX.mjs");
+		const { executeBuild } = await import("./build-BhEaxBPu.mjs");
 		return executeBuild({
 			cwd,
 			skipTests: args.skipTests,
-			skipTypecheck: args.skipTypecheck
+			skipTypecheck: args.skipTypecheck,
+			target: args.target
 		});
 	}
 });
@@ -819,7 +846,7 @@ const deploy = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeDeploy } = await import("./deploy-uAJ4NukN.mjs");
+		const { executeDeploy } = await import("./deploy-CGqPU5U-.mjs");
 		return executeDeploy({
 			cwd,
 			server: args.server,
@@ -863,7 +890,7 @@ const templates = defineExec({
 	args: { json: sharedArgs.json },
 	cwd: "none",
 	async run({ mode }) {
-		const { listTemplates } = await import("./_templates-CK4oKoeX.mjs");
+		const { listTemplates } = await import("./_templates-CIlJ3Vay.mjs");
 		const names = await listTemplates();
 		if (mode === "human") {
 			for (const name of names) log.message(name);
@@ -880,6 +907,7 @@ const mainCommand = defineCommand({
 	subCommands: {
 		init,
 		dev,
+		start,
 		test,
 		eval: evalCommand,
 		build,

package/dist/{client-bundler-BJgREAh6.mjs → client-bundler-6mTLs6ny.mjs}

@@ -81,10 +81,10 @@ const DEFAULT_OUT_DIR = ".aai/client";
 * @internal — build hook for aai-server/the studio; not a supported public
 * API and not covered by semver.
 */
-async function buildClient(cwd, opts = {}) {
+async function buildClient(cwd, options = {}) {
 	const clientEntry = path.join(cwd, "client.tsx");
 	if (!await fileExists(clientEntry)) return {};
-	const outDir = opts.outDir ?? DEFAULT_OUT_DIR;
+	const outDir = options.outDir ?? DEFAULT_OUT_DIR;
 	const clientDir = path.join(cwd, outDir);
 	let cleanupHtml = () => {};
 	try {
@@ -93,8 +93,8 @@ async function buildClient(cwd, opts = {}) {
 			root: cwd,
 			base: "./",
 			logLevel: "silent",
-			...opts.configFile === false && { configFile: false },
-			...omitUndefined({ plugins: opts.plugins }),
+			...options.configFile === false && { configFile: false },
+			...omitUndefined({ plugins: options.plugins }),
 			resolve: { dedupe: DEDUPED_PEERS },
 			build: {
 				outDir,

package/dist/client-bundler.d.ts

@@ -27,4 +27,4 @@ export type BuildClientOptions = {
  * @internal — build hook for aai-server/the studio; not a supported public
  * API and not covered by semver.
  */
-export declare function buildClient(cwd: string, opts?: BuildClientOptions): Promise<Record<string, string>>;
+export declare function buildClient(cwd: string, options?: BuildClientOptions): Promise<Record<string, string>>;

package/dist/client-bundler.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as buildClient } from "./client-bundler-BJgREAh6.mjs";
+import { t as buildClient } from "./client-bundler-6mTLs6ny.mjs";
 export { buildClient };

package/dist/{deploy-uAJ4NukN.mjs → deploy-CGqPU5U-.mjs}

@@ -3,8 +3,8 @@ import { a as ok } from "./_output-DBP9Op_d.mjs";
 import { n as log, r as notify, t as fmtUrl } from "./_ui-DCt4qZrk.mjs";
 import { s as errorMessage$1 } from "./_utils-D5JGcjiW.mjs";
 import { s as updateProjectConfig } from "./_config-DYzC6WMD.mjs";
-import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-DolUCMxu.mjs";
-import { t as resolveServerEnv } from "./_server-common-vILJp3it.mjs";
+import { n as resolveServerEnv } from "./_server-common-De0haHr9.mjs";
+import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-DM0d0M7m.mjs";
 import { o as resolveDeployTarget } from "./_agent-BzUeqOdj.mjs";
 import { assertTypechecks } from "./_typecheck-gate-U3jcil8L.mjs";
 import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-CvpqMpdh.mjs";

package/dist/{dev-DApPSaE_.mjs → dev-Bx9gYBHM.mjs}

@@ -12,7 +12,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-CSMqF8PN.mjs");
+	const { startDevServer } = await import("./_dev-server-BzWB6-4y.mjs");
 	let cleanup;
 	let shuttingDown = false;
 	const onSignal = () => {

package/dist/{eval-BK47A_K5.mjs → eval-B3I7FqN9.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { a as ok, n as fail } from "./_output-DBP9Op_d.mjs";
 import { n as log } from "./_ui-DCt4qZrk.mjs";
-import { t as resolveServerEnv } from "./_server-common-vILJp3it.mjs";
+import { n as resolveServerEnv } from "./_server-common-De0haHr9.mjs";
 import { classifyVitestError, runVitest } from "./test-D032V2cA.mjs";
 //#region src/eval.ts
 /**

package/dist/{init-DukDxECd.mjs → init-CQbj3ycf.mjs}

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { a as ok } from "./_output-DBP9Op_d.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-DCt4qZrk.mjs";
-import { c as fileExists, d as readJson, p as resolveCwd, s as errorMessage$1, t as AGENT_ENTRY } from "./_utils-D5JGcjiW.mjs";
+import { c as fileExists, d as readJson, p as resolveCwd, s as errorMessage, t as AGENT_ENTRY } from "./_utils-D5JGcjiW.mjs";
 import { r as isDevMode, t as getMonorepoRoot } from "./_agent-BzUeqOdj.mjs";
+import { listTemplates } from "./_templates-CIlJ3Vay.mjs";
 import path from "node:path";
-import { omitUndefined } from "@alexkroman1/aai/utils";
 import { styleText } from "node:util";
 import * as p from "@clack/prompts";
 import { execa } from "execa";
@@ -39,6 +39,41 @@ async function promptProjectName(yes) {
 		defaultValue: DEFAULT_PROJECT_NAME
 	}), "Setup cancelled") || DEFAULT_PROJECT_NAME;
 }
+/**
+* The template a non-interactive `init` gets, and the entry the selector opens
+* on — so an author who just presses Enter lands where they used to.
+*/
+const DEFAULT_TEMPLATE = "simple";
+/**
+* Ask which template to scaffold, listing what this CLI actually ships.
+*
+* The options are derived from {@link listTemplates} rather than a roster kept
+* here: that function already backs `aai templates` AND the unknown-template
+* error, so a template added to the package shows up in the picker with no
+* second list to update. {@link DEFAULT_TEMPLATE} is hoisted to the top and
+* pre-selected, which is what keeps a bare `aai init` a single Enter away from
+* the project it produced before there was a picker.
+*
+* Callers must not reach here when there is nobody to answer — `--yes` and
+* JSON mode (auto-detected on a pipe) resolve the default without prompting.
+*/
+async function promptTemplate(list = listTemplates) {
+	const [first, ...rest] = await list();
+	if (first === void 0) return DEFAULT_TEMPLATE;
+	if (rest.length === 0) return first;
+	const names = [first, ...rest];
+	const hasDefault = names.includes(DEFAULT_TEMPLATE);
+	const ordered = hasDefault ? [DEFAULT_TEMPLATE, ...names.filter((name) => name !== DEFAULT_TEMPLATE)] : names;
+	return unwrapCancel(await p.select({
+		message: "Which template?",
+		maxItems: 12,
+		initialValue: hasDefault ? DEFAULT_TEMPLATE : first,
+		options: ordered.map((name) => name === DEFAULT_TEMPLATE ? {
+			value: name,
+			hint: "the default starting point"
+		} : { value: name })
+	}), "Setup cancelled");
+}
 /** Best-effort corepack enable so pnpm is available (scaffold declares packageManager: pnpm). */
 async function ensurePnpm() {
 	await execa("corepack", ["enable"], { reject: false });
@@ -73,9 +108,14 @@ async function runPnpmInstall(cwd) {
 	const pnpmArgs = isDevMode() ? ["install"] : ["install", "--ignore-workspace"];
 	await execa(cmd, [...args, ...pnpmArgs], { cwd });
 }
-/** Install deps with pnpm. Returns true on success (or no deps to install). */
+/**
+* Install deps with pnpm, reporting a failure through `warn` rather than
+* throwing: the project is scaffolded either way, and the two warnings say how
+* to finish the install by hand. Nothing downstream branches on the outcome —
+* `init` stops here — so it returns nothing.
+*/
 async function installDeps(cwd, warn, silent) {
-	if (!await hasDeps(cwd)) return true;
+	if (!await hasDeps(cwd)) return;
 	await ensurePnpm();
 	try {
 		await withSpinner(silent, {
@@ -83,11 +123,9 @@ async function installDeps(cwd, warn, silent) {
 			done: "Dependencies installed",
 			failed: "Dependency install failed"
 		}, () => runPnpmInstall(cwd));
-		return true;
 	} catch (err) {
-		warn(`pnpm install failed: ${errorMessage$1(err)}`);
+		warn(`pnpm install failed: ${errorMessage(err)}`);
 		warn("Install pnpm (`npm install -g pnpm`), then run `pnpm install` in the project.");
-		return false;
 	}
 }
 /** Resolve target directory relative to the user's current directory. */
@@ -104,30 +142,9 @@ function collectWarnings() {
 		}
 	};
 }
-/** Publish after init and return deploy metadata if successful. */
-async function tryPublish(cwd, server, warn) {
-	const { executePublish } = await import("./studio-CpHlNHUZ.mjs");
-	try {
-		const result = await executePublish({
-			cwd,
-			...omitUndefined({ server })
-		});
-		if (result.ok) return {
-			slug: result.data.slug,
-			url: result.data.url,
-			studioUrl: result.data.studioUrl
-		};
-		warn(`Publish failed: ${result.error}`);
-		return null;
-	} catch (err) {
-		warn(`Publish failed: ${errorMessage$1(err)}`);
-		warn("Your project was still created — run `aai publish` in it to retry.");
-		return null;
-	}
-}
 /** Scaffold the project, optionally showing a spinner. */
 async function scaffoldProject(dir, cwd, template, silent) {
-	const { runInit } = await import("./_init-CQ8idAwo.mjs");
+	const { runInit } = await import("./_init-Bsi3DZNJ.mjs");
 	await withSpinner(silent, {
 		start: `Creating ${dir}`,
 		done: "Project created",
@@ -150,22 +167,15 @@ async function executeInit(opts, extra) {
 	const monorepoRoot = getMonorepoRoot();
 	const cwd = resolveTargetDir(dir);
 	if (!opts.force && await fileExists(path.join(cwd, "agent.ts"))) throw new Error(`${AGENT_ENTRY} already exists in this directory. Use ${styleText("cyanBright", "--force")} to overwrite.`);
-	const template = opts.template ?? "simple";
+	const template = opts.template ?? (opts.yes || suppressUi ? DEFAULT_TEMPLATE : await promptTemplate());
 	const { warn, warnings } = collectWarnings();
 	await scaffoldProject(dir, cwd, template, suppressUi);
-	const installed = await installDeps(cwd, warn, suppressUi);
-	if (!installed) warn("Skipping publish because dependencies were not installed.");
-	const published = installed && !opts.skipDeploy ? await tryPublish(cwd, opts.server, warn) : null;
+	await installDeps(cwd, warn, suppressUi);
 	if (!suppressUi) printPostInitInfo(cwd, monorepoRoot);
 	const data = {
 		dir: cwd,
-		template,
-		deployed: published !== null
+		template
 	};
-	if (published) {
-		data.slug = published.slug;
-		data.url = published.url;
-	}
 	if (warnings.length > 0) data.warnings = warnings;
 	return ok(data);
 }

package/dist/init.d.ts

@@ -2,21 +2,32 @@ import { type CommandResult } from "./_output.ts";
 type InitData = {
     dir: string;
     template: string;
-    deployed: boolean;
-    slug?: string;
-    url?: string;
     /**
-     * Diagnostics a human sees as `log.warn` lines: a failed `pnpm install`, a
-     * failed publish, the publish skipped because of the former.
+     * Diagnostics a human sees as `log.warn` lines — today only a failed
+     * `pnpm install`.
      *
      * They have to ride the result for the same reason `PushOutcome.warnings`
      * does — `log.warn` is silenced in JSON mode and JSON mode is AUTO-DETECTED
-     * on a pipe, so a scripted `aai init` was told `{ ok: true, deployed: false }`
-     * for a project whose dependencies never installed and could not tell that
-     * apart from `--skipDeploy`.
+     * on a pipe, so a scripted `aai init` was told `{ ok: true }` for a project
+     * whose dependencies never installed and could not tell that apart from a
+     * clean run.
      */
     warnings?: string[];
 };
+/**
+ * Ask which template to scaffold, listing what this CLI actually ships.
+ *
+ * The options are derived from {@link listTemplates} rather than a roster kept
+ * here: that function already backs `aai templates` AND the unknown-template
+ * error, so a template added to the package shows up in the picker with no
+ * second list to update. {@link DEFAULT_TEMPLATE} is hoisted to the top and
+ * pre-selected, which is what keeps a bare `aai init` a single Enter away from
+ * the project it produced before there was a picker.
+ *
+ * Callers must not reach here when there is nobody to answer — `--yes` and
+ * JSON mode (auto-detected on a pipe) resolve the default without prompting.
+ */
+export declare function promptTemplate(list?: () => Promise<string[]>): Promise<string>;
 /** Build the command + args for running pnpm, routing through safe-chain when available. */
 export declare function resolvePnpmCommand(checkSafeChain?: () => Promise<boolean>): Promise<{
     cmd: string;
@@ -27,8 +38,6 @@ export declare function executeInit(opts: {
     force?: boolean | undefined;
     template?: string | undefined;
     yes?: boolean | undefined;
-    skipDeploy?: boolean | undefined;
-    server?: string | undefined;
 }, extra?: {
     silent?: boolean | undefined;
 }): Promise<CommandResult<InitData>>;

package/dist/scaffold/CLAUDE.md

@@ -133,8 +133,8 @@ gate in front of `aai build`.
 
 ## Running it yourself (`npm start`)
 
-`server.mjs` serves this agent from a plain Node process — no platform
-account, nothing managed. It is the deployment counterpart of `aai dev`:
+`aai start` serves this agent from a plain Node process — no platform account,
+nothing managed. It is the deployment counterpart of `aai dev`:
 
 ```sh
 npm start                          # http://127.0.0.1:3000
@@ -142,11 +142,18 @@ PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container
 ```
 
 `npm start` **builds first** (that is the `prestart` script) and then serves
-the result: `server.mjs` boots `.aai/worker.mjs`, the same artifact
+the result: `aai start` boots `.aai/worker.mjs`, the same artifact
 `aai publish` uploads. It serves your own `client.tsx` build when there is one
-and falls back to `defaultClientDir()` (`@alexkroman1/aai-ui/client-dir`), the
-prebuilt default UI shipped inside the package — the only export of `aai-ui`
-that runs on Node rather than in the browser.
+and falls back to the prebuilt default UI shipped inside `@alexkroman1/aai-ui`.
+
+There is no server file in your project, and that is deliberate — the boot
+belongs to the framework, so it improves when you update rather than being
+frozen at the moment you scaffolded. When you need to own it, import
+`createProjectServer` from `@alexkroman1/aai-cli/start`: it builds the server
+and binds nothing, so you decide how it is served. Building one from scratch
+instead, `defaultClientDir()` (`@alexkroman1/aai-ui/client-dir`) is where that
+prebuilt UI lives — the only export of `aai-ui` that runs on Node rather than
+in the browser.
 
 The build is what makes `tools/` work — a tool is registered by existing, and
 the enumeration happens where the bundle is assembled, so a server that loaded
@@ -161,9 +168,31 @@ One thing to know: it binds **loopback by default**, because this server has
 no request authentication of its own; set `HOST=0.0.0.0` only behind your own
 proxy or auth.
 
-Deleting `server.mjs` costs nothing: `aai dev`, `aai publish` and the managed
-platform never read it. `run_code` is the one feature that does not follow —
-it needs the platform's sandbox and refuses outside one.
+`run_code` is the one feature that does not follow — it needs the platform's
+sandbox and refuses outside one.
+
+### Deploying to a host that wants its own entry file
+
+`aai build --target <host>` writes the deployment that host expects into the
+build output. Nothing host-specific lives in your project: the files are
+generated, gitignored, and rewritten by the host's own build.
+
+```sh
+aai build --target vercel   # writes .vercel/output/ (Build Output API v3)
+```
+
+You rarely type it. The target is detected from the host's own build
+environment, so `vercel deploy` (or a git push) picks it up with nothing
+configured; `--target node`, the default everywhere else, emits nothing extra
+and is what `npm start` runs.
+
+One thing to know before deploying a VOICE agent to a serverless host: the
+session is a WebSocket, so the host has to support one. Vercel does — it hands
+the function the raw upgrade, and the emitted entry passes it to the same
+server `aai dev` runs. A host that serves only request/response still runs the
+HTTP surface — `/health`, `/client-config`,
+`/workflows/*` and your static assets — which is everything a workflow app
+needs and none of what a voice agent needs.
 
 ## Project structure
 
@@ -1199,11 +1228,23 @@ statement about pipeline mode, not about the SDK.
 
 ### Answering a phone call
 
-A deployed voice agent already serves carrier media streams — there is nothing
-to switch on. `createRuntimeServer` mounts `WS /phone` whenever the agent is a voice
-agent (`telephony` defaults to `true`, and to `false` for a `page: "static"`
-workflow app, which has no stages to put on a call). Point the carrier at it
-with a `carrier` query parameter naming who is dialling:
+**Say which carriers may call, and `WS /phone` is served for exactly those.**
+`telephony` is an allow-list on `agent()`, and it is the whole of the wiring:
+
+```ts
+import { agent } from "@alexkroman1/aai";
+
+export default agent({
+  name: "Support",
+  greeting: "Support line — what's happened?",
+  // The carrier this agent's number is with. `true` admits every carrier this
+  // build decodes; omit the field and `/phone` is not served at all.
+  telephony: ["twilio"],
+});
+```
+
+Point the carrier at the deployed agent with a `carrier` query parameter naming
+who is dialling:
 
 ```text
 wss://<your-agent-url>/phone?carrier=twilio
@@ -1211,15 +1252,25 @@ wss://<your-agent-url>/phone?carrier=telnyx
 ```
 
 Twilio and Telnyx are the two carriers this build decodes (`CARRIER_CODECS`);
-an unknown `carrier` is declined at the upgrade. Both speak 8 kHz mu-law, which
-the bridge transcodes in both directions, so the agent, its tools and its slots
+an unknown `carrier` is declined at the upgrade with a `400`, and a real one
+this agent did not declare with a `404`. Both speak 8 kHz mu-law, which the
+bridge transcodes in both directions, so the agent, its tools and its slots
 behave exactly as they do in the browser — a phone call is a transport, not a
-mode. Nothing about `agent.ts` changes to support one.
-
-Turn the route off with `telephony: false` on `createRuntimeServer`. If you are
-embedding the runtime yourself rather than deploying, the pieces are
-`createTelephonyBridge`, `startTelephonySession`, `TELEPHONY_PATH` and
-`carrierByName`, all on `@alexkroman1/aai-runtime`.
+mode. Nothing else about `agent.ts` changes to support one.
+
+**An agent that declares nothing answers no carrier**, which is a change from
+earlier releases: every voice agent used to serve both carriers' framing from
+the moment it booted, whether or not it had a phone number. `/phone` is the one
+door dialled from OUTSIDE your deployment, by a carrier following a number, so
+it is opened by a sentence in `agent.ts` rather than inherited. `aai dev` and a
+deployed sandbox honour the same declaration, so a call refused after a deploy
+is refused on your laptop too.
+
+`telephony: false` is the same refusal stated out loud, and an operator can pass
+`telephony` to `createAgentServer` to override one deployment of an agent that
+does declare a carrier. If you are embedding the runtime yourself rather than
+deploying, the pieces are `createTelephonyBridge`, `startTelephonySession`,
+`TELEPHONY_PATH` and `carrierByName`, all on `@alexkroman1/aai-runtime`.
 
 **Silence nudge (pipeline only):** set `silenceTimeoutMs` to make the
 assistant proactively take a turn after that much user silence (e.g.

package/dist/scaffold/package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "dev": "aai dev",
     "prestart": "aai build --skip-tests",
-    "start": "node server.mjs",
+    "start": "aai start",
     "build": "aai build",
     "test": "vitest run --exclude \"**/*.eval.test.*\"",
     "test:agent": "aai test",
@@ -15,9 +15,10 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^14.0.0",
-    "@alexkroman1/aai-runtime": "^14.0.0",
-    "@alexkroman1/aai-ui": "^14.0.0",
+    "@alexkroman1/aai": "^15.1.0",
+    "@alexkroman1/aai-cli": "^15.1.0",
+    "@alexkroman1/aai-runtime": "^15.1.0",
+    "@alexkroman1/aai-ui": "^15.1.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
@@ -25,9 +26,8 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^14.0.0",
     "@tailwindcss/vite": "^4.3.3",
-    "@types/node": "^26.4.1",
+    "@types/node": "^24.10.1",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
     "@vitejs/plugin-react": "^6.1.1",