@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/scaffold/CLAUDE.md

@@ -77,7 +77,8 @@ The fast loop: edit → `pnpm dev` (browser, talk to it) →
    you stopped talking, barge-in, two sentences merging into one turn. Those
    need `pnpm dev` and your own voice.
 4. **Run `pnpm build` before declaring done** — bundles `agent.ts`,
-   type-checks, and validates the manifest. Catches issues `dev` won't.
+   type-checks, validates the manifest, and runs the WHOLE spec suite first.
+   Catches issues `dev` won't.
 5. **Make small, focused changes** — verify each one before stacking the
    next.
 6. **Look at templates before writing custom code** — the CLI ships working
@@ -109,6 +110,7 @@ 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 test --all       # ...or every spec in the project
 npx @alexkroman1/aai-cli eval             # Run agent.eval.test.ts against a model
 npx @alexkroman1/aai-cli build            # Bundle and validate
 npx @alexkroman1/aai-cli deploy           # Deploy to production
@@ -122,10 +124,17 @@ The scaffold's `package.json` exposes `dev`, `build`, `test`, `eval` and
 `deploy` as `pnpm <name>` shortcuts. Other commands (`init`, `templates`,
 `delete`, `secret`) are CLI-only.
 
+**`aai test` targets `agent.test.ts` and nothing else**, which `--all` widens.
+What matters is that a narrowed run does not report itself as a pass: when the
+project holds spec files the run did not cover, it FAILS and names them rather
+than printing a green line that says nothing about `tools/*.test.ts`. `pnpm
+test` (the scaffold's own script) already runs the whole suite, and so does the
+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
@@ -133,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
@@ -152,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
 
@@ -416,14 +454,14 @@ below.
 
 ### Workflow bodies live in `workflows/`
 
-A body is an ordinary exported async function of its input and a `WorkflowCtx`.
+A body is an ordinary exported async function of its input and a `WorkflowContext`.
 There is no directive and no compile step of its own — the agent bundle compiles
 `workflows/` like any other source file — and durability is a method call:
 
 ```ts
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 
-export async function digestFlow(input: { url: string }, ctx: WorkflowCtx) {
+export async function digestFlow(input: { url: string }, ctx: WorkflowContext) {
   const digest = await ctx.step("summarize", () => summarize(input.url));
 
   // Suspended, not blocked: the container is free to exit here and the run
@@ -515,11 +553,11 @@ The three undurable reads a body most often wants, each journaled — read once
 the first reach, and the same value on every later walk:
 
 ```ts
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 
 declare function charge(amount: number, idempotencyKey: string, jitter: number): Promise<void>;
 
-export async function chargeFlow(input: { amount: number }, ctx: WorkflowCtx) {
+export async function chargeFlow(input: { amount: number }, ctx: WorkflowContext) {
   const startedAt = await ctx.now(); // epoch ms, decided once
   const idempotencyKey = await ctx.uuid(); // still the same id after a crash
   const jitter = await ctx.random(); // one float in [0, 1), journaled per call
@@ -601,6 +639,22 @@ Five things worth knowing:
   which is how a "send it now" tool cuts a scheduled wait short. Naming no ids
   wakes every outstanding SLEEP and deliberately not a `waitFor` deadline, so
   cutting a schedule short cannot also close an approval window.
+- **A SUSPEND is not free, so `ctx.sleep` is not a `setTimeout`.** A wait costs
+  a journal write to record it, a queued delivery to bring the run back, and a
+  fresh WALK of the body — measured on a deployed agent at roughly a second of
+  overhead around the sleep itself, on top of whatever you asked for. There is a
+  cliff at the bottom of the range worth knowing about: a sleep shorter
+  than the round trip that records it never suspends AT ALL — `ctx.sleep("beat",
+  100)` and `ctx.sleep("beat", 0)` are both simply free — while anything longer
+  pays the whole cost. Measured, `nap(100)` and `nap(0)` came back within 30 ms
+  of each other on a run whose total was 2.1 s.
+
+  So a sub-second pause is not what this is for. For a short backoff inside a
+  step, use an ordinary timer (`sleep` from `@alexkroman1/aai/internal`) — a step
+  body may not call `ctx.sleep` anyway, and the engine refuses one that does. Use
+  `ctx.sleep` for a wait you want to SURVIVE the process, which is the thing a
+  timer cannot do. A body that polls in a loop pays the suspend per iteration,
+  which is the strongest argument for the next section: park on the callback.
 
 #### A third-party callback is an OPTIMIZATION over a reconciling read
 
@@ -656,15 +710,15 @@ trap somebody has already paid for:
 Steps are ordinary exported functions, so a spec imports and calls them. The
 BODY needs an engine, and there are two, for two different questions.
 
-**"What did the body ask for?"** — `createWorkflowCtx` from
+**"What did the body ask for?"** — `createWorkflowContext` from
 `@alexkroman1/aai/testing`. It runs the steps and records the names, the retry
 policies and the sleeps, over one walk with no journal. Nothing replays, so a
 spec built on it must not claim to test durability.
 
 ```ts no-check
-import { createWorkflowCtx } from "@alexkroman1/aai/testing";
+import { createWorkflowContext } from "@alexkroman1/aai/testing";
 
-const ctx = createWorkflowCtx({ runSteps: false });
+const ctx = createWorkflowContext({ runSteps: false });
 await digestFlow({ url: "https://example.com/a" }, ctx);
 
 expect(ctx.steps.map((s) => s.name)).toEqual(["fetchArticle", "summarize", "file"]);
@@ -729,7 +783,7 @@ root barrel would drag the whole SDK into that bundle.
 
 ```ts
 import { stepEnv } from "@alexkroman1/aai/step";
-import { stepGenerateClassified } from "@alexkroman1/aai/step-errors";
+import { stepGenerateOrFail } from "@alexkroman1/aai/step-errors";
 
 async function summarize(text: string) {
   // The agent's env by name — the same values a tool reads from `ctx.env`.
@@ -737,7 +791,7 @@ async function summarize(text: string) {
   const style = stepEnv("DIGEST_STYLE") ?? "plain";
 
   // One model call, on the agent's own ASSEMBLYAI_API_KEY and default model.
-  return await stepGenerateClassified(`${style} summary of:\n\n${text}`, {
+  return await stepGenerateOrFail(`${style} summary of:\n\n${text}`, {
     system: "Reply with two sentences and nothing else.",
   });
 }
@@ -749,9 +803,9 @@ before and after a deploy. List what you read in `requiredEnv` and a deploy
 checks it for you. And **`stepGenerate` is not `ctx.generate`**: it is one
 request to the AssemblyAI LLM Gateway, with no tools and no structured output,
 because bundling the AI SDK into a step artifact costs megabytes on every
-deploy. Use `stepGenerateJsonClassified` with a Zod `schema` if you need a shape.
+deploy. Use `stepGenerateJsonOrFail` with a Zod `schema` if you need a shape.
 
-### From a step, reach for the `Classified` call
+### From a step, reach for the `OrFail` call
 
 `@alexkroman1/aai/step-errors` publishes a wrapper for every `/step` call that
 can fail against a remote service, and **inside a step the wrapper is the one to
@@ -759,14 +813,14 @@ use**:
 
 | Raw, on `@alexkroman1/aai/step` | Use this instead, on `@alexkroman1/aai/step-errors` |
 | --- | --- |
-| `stepGenerate` | `stepGenerateClassified` |
-| `stepGenerateJson` | `stepGenerateJsonClassified` |
-| `stepFetch` | `stepFetchOk` |
-| `stepTranscribeSync` | `stepTranscribeSyncClassified` |
-| `stepTranscribeUpload` / `Submit` / `Poll` | the matching `*Classified` |
-| `sendToChannel` (`/channels`) | `sendToChannelClassified` |
-
-`stepFetchOk` is the one that is not spelled `*Classified`, and the name is the
+| `stepGenerate` | `stepGenerateOrFail` |
+| `stepGenerateJson` | `stepGenerateJsonOrFail` |
+| `stepFetch` | `stepFetchOrFail` |
+| `stepTranscribeSync` | `stepTranscribeSyncOrFail` |
+| `stepTranscribeUpload` / `Submit` / `Poll` | the matching `*OrFail` |
+| `sendToChannel` (`/channels`) | `sendToChannelOrFail` |
+
+`stepFetchOrFail` is the one that is not spelled `*OrFail`, and the name is the
 difference: the others turn an already-thrown failure into a classified one,
 while this also turns a NON-2XX RESPONSE into a throw — `stepFetch` resolves
 with a `404` rather than raising it. Two changes, so two names.
@@ -804,7 +858,7 @@ bundling rule as `/step` — import them there, never through the root barrel:
   recording, or `stepTranscribeUpload` → `stepTranscribeSubmit` →
   `stepTranscribePoll` for a long one, plus `Transcript`, `TranscribeError` and
   the `TRANSCRIBE_*` limits. (There is no `/transcribe` subpath; transcription
-  lives on `/step` with the other step primitives.) Use the `Classified`
+  lives on `/step` with the other step primitives.) Use the `OrFail`
   wrappers above: a provider refusal — a container it will not read, a
   recording with no speech — arrives
   with `retryable: false`, and unclassified a step re-uploads the same bytes
@@ -841,19 +895,19 @@ export async function measure(uploadId: string) {
 
 A run that finishes while nobody is on the line needs somewhere to put the
 result. `slackChannel({ webhookUrl })` names a destination and
-`sendToChannelClassified(channel, message)` posts to it:
+`sendToChannelOrFail(channel, message)` posts to it:
 
 ```ts no-check
 import { type ChannelMessage, slackChannel } from "@alexkroman1/aai/channels";
 import { requireStepEnv } from "@alexkroman1/aai/step";
-import { sendToChannelClassified } from "@alexkroman1/aai/step-errors";
+import { sendToChannelOrFail } from "@alexkroman1/aai/step-errors";
 
 export async function announce(headline: string, points: string[]) {
   const message: ChannelMessage = {
     text: headline,
     sections: points.map((point) => ({ text: point })),
   };
-  return await sendToChannelClassified(slackChannel({ webhookUrl: requireStepEnv("SLACK_WEBHOOK_URL") }), message);
+  return await sendToChannelOrFail(slackChannel({ webhookUrl: requireStepEnv("SLACK_WEBHOOK_URL") }), message);
 }
 ```
 
@@ -862,7 +916,7 @@ it with `aai secret put`. A channel's credential is its DESTINATION and is
 passed in, which is why no channel reads an env var of its own. `ChannelMessage`
 is rendered per platform, so the same message is legal on a channel kind added
 later; `isSlackWebhookUrl` / `isSlackWorkflowTriggerUrl` validate a pasted URL
-before a run depends on it, and `channelAdvice` turns a refusal into a sentence
+before a run depends on it, and `explainChannelFailure` turns a refusal into a sentence
 a person can act on. `podcast-digest` is the worked example.
 
 ### A step's HTTP: use `stepFetch`, not `fetch`
@@ -941,11 +995,11 @@ Both are on `@alexkroman1/aai/step`, and `spoken-summary` is the template that
 shows the whole round trip.
 
 ```ts
-import { stepSpeak, writeUpload } from "@alexkroman1/aai/step";
+import { stepSpeak, stepWriteUpload } from "@alexkroman1/aai/step";
 
 export async function narrate(script: string) {
   const spoken = await stepSpeak(script, { voice: "jane" });
-  const stored = await writeUpload(spoken.audio, { name: "summary.wav", type: "audio/wav" });
+  const stored = await stepWriteUpload(spoken.audio, { name: "summary.wav", type: "audio/wav" });
   return { audio: stored.id, durationMs: spoken.durationMs };
 }
 ```
@@ -962,11 +1016,13 @@ opens and produces silence rather than an error. The `AssemblyAITtsVoice` type
 gives you autocomplete over it and nothing more: it accepts any string, so that
 a voice the service adds after this release still compiles.
 
-**`writeUpload` is `readUpload`'s other direction, and you need it.** A run's
-output is read back as JSON, so audio cannot travel in one — the same rule that
-keeps an uploaded recording's bytes out of a run's INPUT, arriving at the other
-end of the run. Store the bytes, return the **id**, and let the page fetch it
-with `api.download(id)`.
+**`stepWriteUpload` is `stepReadUpload`'s other direction, and you need it.** A
+run's output is read back as JSON, so audio cannot travel in one — the same rule
+that keeps an uploaded recording's bytes out of a run's INPUT, arriving at the
+other end of the run. Store the bytes, return the **id**, and let the page fetch
+it with `api.download(id)`. A step that wants the record rather than the bytes
+reads it with `stepUploadInfo(id)`, which answers an `UploadInfo` — the name,
+the size stored so far, and whether that is all of it.
 
 Three rules come with it:
 
@@ -1020,12 +1076,13 @@ naming a shape is what asks the compiler to make you handle the failure.
 
 ### The page
 
-A workflow app's `client.tsx` mounts with `page()` rather than `client()` —
-there is no session to build, so no socket, no audio graph and no microphone
-request. Everything else is the same file, React and Tailwind included.
+A workflow app's `client.tsx` mounts with `mountPage()` rather than
+`mountClient()` — there is no session to build, so no socket, no audio graph
+and no microphone request. Everything else is the same file, React and
+Tailwind included.
 
 ```tsx no-check
-import { createWorkflowApi, page, useWorkflowRun } from "@alexkroman1/aai-ui";
+import { createWorkflowApi, mountPage, useWorkflowRun } from "@alexkroman1/aai-ui";
 import "@alexkroman1/aai-ui/styles.css";
 import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import { useState } from "react";
@@ -1053,7 +1110,7 @@ export function App() {
   );
 }
 
-page({ name: "Link Digest", component: App });
+mountPage({ name: "Link Digest", component: App });
 ```
 
 `api.start()` resolves as soon as the RUN EXISTS, not when it finishes — that
@@ -1171,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. `createServer` 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
@@ -1183,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 `createServer`. 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.
@@ -1268,12 +1347,12 @@ API keys require it; the US endpoints reject them. Example:
 | Factory         | SDK package         | Env var                        |
 | --------------- | ------------------- | ------------------------------ |
 | `anthropicLlm`  | `@ai-sdk/anthropic` | `ANTHROPIC_API_KEY`            |
-| `openaiLlm`     | `@ai-sdk/openai`    | `OPENAI_API_KEY`               |
+| `openAILlm`     | `@ai-sdk/openai`    | `OPENAI_API_KEY`               |
 | `googleLlm`     | `@ai-sdk/google`    | `GOOGLE_GENERATIVE_AI_API_KEY` |
 | `mistralLlm`    | `@ai-sdk/mistral`   | `MISTRAL_API_KEY`              |
-| `xaiLlm`        | `@ai-sdk/xai`       | `XAI_API_KEY`                  |
+| `xAILlm`        | `@ai-sdk/xai`       | `XAI_API_KEY`                  |
 | `groqLlm`       | `@ai-sdk/groq`      | `GROQ_API_KEY`                 |
-| `openrouterLlm` | `@ai-sdk/openai`    | `OPENROUTER_API_KEY`           |
+| `openRouterLlm` | `@ai-sdk/openai`    | `OPENROUTER_API_KEY`           |
 | `gatewayLlm`    | `ai` (built in)     | `AI_GATEWAY_API_KEY`           |
 | `assemblyAILlm` | `@ai-sdk/openai`    | `ASSEMBLYAI_API_KEY`           |
 
@@ -1283,10 +1362,10 @@ shared by all of them except `assemblyAILlm`. Example:
 because a third-party vendor's catalog is not this SDK's to default from;
 `assemblyAILlm()` is the one bare call, since it has a default model.
 
-`openrouterLlm` routes through [OpenRouter](https://openrouter.ai) — an
+`openRouterLlm` routes through [OpenRouter](https://openrouter.ai) — an
 OpenAI-compatible endpoint fronting hundreds of models addressed as
 `"creator/model"`, e.g.
-`openrouterLlm({ model: "meta-llama/llama-3.3-70b-instruct" })`. It needs
+`openRouterLlm({ model: "meta-llama/llama-3.3-70b-instruct" })`. It needs
 no extra SDK install (it reuses the `@ai-sdk/openai` client).
 
 `gatewayLlm` routes through the [Vercel AI
@@ -1947,7 +2026,7 @@ Those three cover almost everything an agent wants. A database is for data that
 must outlive a session AND be queryable: a ledger, filed records, cross-session
 saves.
 
-## Custom UI — `client()`
+## Custom UI — `mountClient()`
 
 File: `client.tsx` alongside `agent.ts`. Uses **React** (not Preact).
 Always import `"@alexkroman1/aai-ui/styles.css"` first.
@@ -1957,9 +2036,9 @@ Always import `"@alexkroman1/aai-ui/styles.css"` first.
 ```tsx
 /// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
-import { client } from "@alexkroman1/aai-ui";
+import { mountClient } from "@alexkroman1/aai-ui";
 
-client({ name: "My Agent" });
+mountClient({ name: "My Agent" });
 ```
 
 ### Tier 1 with sidebar
@@ -1967,7 +2046,7 @@ client({ name: "My Agent" });
 ```tsx
 /// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
-import { client, useEvent } from "@alexkroman1/aai-ui";
+import { mountClient, useEvent } from "@alexkroman1/aai-ui";
 import { useState } from "react";
 
 function Sidebar() {
@@ -1982,7 +2061,7 @@ function Sidebar() {
   );
 }
 
-client({ name: "My Agent", sidebar: Sidebar });
+mountClient({ name: "My Agent", sidebar: Sidebar });
 ```
 
 ### Tier 2 — full custom component
@@ -1990,7 +2069,7 @@ client({ name: "My Agent", sidebar: Sidebar });
 ```tsx
 /// <reference types="vite/client" />
 import "@alexkroman1/aai-ui/styles.css";
-import { client, useSession } from "@alexkroman1/aai-ui";
+import { mountClient, useSession } from "@alexkroman1/aai-ui";
 
 function MyApp() {
   const { messages, userTranscript, started, running, start, toggle, end } =
@@ -2011,10 +2090,10 @@ function MyApp() {
   );
 }
 
-client({ component: MyApp });
+mountClient({ component: MyApp });
 ```
 
-### `client()` config
+### `mountClient()` config
 
 | Field | Type | Default | Description |
 | --- | --- | --- | --- |
@@ -2172,7 +2251,7 @@ 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";
+import { ChatView, mountClient, StartScreen } from "@alexkroman1/aai-ui";
 
 function PizzaApp() {
   return (
@@ -2182,7 +2261,7 @@ function PizzaApp() {
   );
 }
 
-client({ component: PizzaApp });
+mountClient({ component: PizzaApp });
 ```
 
 ## Styling
@@ -2190,7 +2269,7 @@ client({ component: PizzaApp });
 - **Tailwind CSS v4** — compiled at bundle time, configured via CSS.
   Do NOT create `tailwind.config.js` — it will be ignored.
 - Use Tailwind classes for layout, `useTheme()` for dynamic colors.
-- Set theme: `client({ theme: { bg, primary, text, surface, border } })`.
+- Set theme: `mountClient({ theme: { bg, primary, text, surface, border } })`.
 - Override CSS custom properties for extra tokens:
   `--color-aai-*`, `--radius-aai`, `--font-aai`.
 - Always import `"@alexkroman1/aai-ui/styles.css"` at the top of `client.tsx`.

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": "^13.3.0",
-    "@alexkroman1/aai-runtime": "^13.3.0",
-    "@alexkroman1/aai-ui": "^13.3.0",
+    "@alexkroman1/aai": "^15.0.0",
+    "@alexkroman1/aai-cli": "^15.0.0",
+    "@alexkroman1/aai-runtime": "^15.0.0",
+    "@alexkroman1/aai-ui": "^15.0.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": "^13.3.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",

package/dist/{secret-V1w7y9-j.mjs → secret-Cjp912yF.mjs}

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { a as ok, n as fail, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { a as ok, n as fail, t as CliError } from "./_output-DBP9Op_d.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-DCt4qZrk.mjs";
-import { f as checkedResponse, p as isStringArray } from "./_studio-DTi3EdXQ.mjs";
-import { t as secretRequest } from "./_slug-api-DlKpj91X.mjs";
-import { isRecord } from "@alexkroman1/aai/utils";
+import { f as checkedResponse, p as isStringArray } from "./_studio-DnR_BqFp.mjs";
+import { t as secretRequest } from "./_slug-api-CGvc2YSQ.mjs";
+import { isRecord, plural } from "@alexkroman1/aai/utils";
 import * as p from "@clack/prompts";
 import pTimeout from "p-timeout";
 //#region src/secret.ts
@@ -153,7 +153,7 @@ async function executeSecretList(cwd, server) {
 	const { vars } = checkedResponse(data, (value) => isRecord(value) && isStringArray(value.vars), `the secret list for ${target}`);
 	if (vars.length === 0) log.info("No secrets set. Use `aai secret put <name>` to add one.");
 	else {
-		log.message(`${vars.length} secret${vars.length === 1 ? "" : "s"}:`);
+		log.message(`${vars.length} ${plural(vars.length, "secret")}:`);
 		for (const v of vars) log.message(`  ${v}`);
 	}
 	return ok({ secrets: vars });

package/dist/secret.d.ts

@@ -38,10 +38,12 @@ export type SecretValueIo = {
  *   sitting at a terminal has no reason to send.
  */
 export declare function resolveSecretValue(name: string, mode: OutputMode, io?: SecretValueIo): Promise<string | undefined>;
-type SecretPutData = {
-    name: string;
-};
-type SecretDeleteData = {
+/**
+ * Both the put and the delete result — one shape, so one name. They were two
+ * distinct aliases for `{ name: string }`, which implied a difference that does
+ * not exist and left "which alias meant the secret result" to be re-decided.
+ */
+type SecretNameData = {
     name: string;
 };
 type SecretListData = {
@@ -52,7 +54,7 @@ type SecretListData = {
  * path). If not, prompt for it — masked — which is what
  * {@link resolveSecretValue} returning `undefined` asks for.
  */
-export declare function executeSecretPut(cwd: string, name: string, value: string | undefined, server: string | undefined): Promise<CommandResult<SecretPutData>>;
-export declare function executeSecretDelete(cwd: string, name: string, server: string | undefined): Promise<CommandResult<SecretDeleteData>>;
+export declare function executeSecretPut(cwd: string, name: string, value: string | undefined, server: string | undefined): Promise<CommandResult<SecretNameData>>;
+export declare function executeSecretDelete(cwd: string, name: string, server: string | undefined): Promise<CommandResult<SecretNameData>>;
 export declare function executeSecretList(cwd: string, server: string | undefined): Promise<CommandResult<SecretListData>>;
 export {};