From 95ba58f23a5d84e0b902681302569cb8e610912d Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 14:57:49 -0700
Subject: [PATCH 01/32] docs: design spec for aai init scaffolder

Vercel-style interactive scaffolder: pick from 4 templates (transcribe,
stream, agent, llm), copy a real Vercel-deployable Python web project,
install deps, launch a local server, and open the browser. stream and
agent both connect the browser directly to AssemblyAI via temp tokens;
transcribe and llm use a thin upload/poll backend. Generated files kept
deliberately flat/simple for human + Claude Code iteration.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                          |   3 +
 specs/2026-06-04-aai-init-design.md | 229 ++++++++++++++++++++++++++++
 2 files changed, 232 insertions(+)
 create mode 100644 specs/2026-06-04-aai-init-design.md

diff --git a/.gitignore b/.gitignore
index caa963c5..fd4feafd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -19,3 +19,6 @@ transcribe/
 
 # Wrong tool for this project (hatchling + uv); never commit a poetry lock
 poetry.lock
+
+# Brainstorming visual-companion scratch
+.superpowers/
diff --git a/specs/2026-06-04-aai-init-design.md b/specs/2026-06-04-aai-init-design.md
new file mode 100644
index 00000000..83cafbb6
--- /dev/null
+++ b/specs/2026-06-04-aai-init-design.md
@@ -0,0 +1,229 @@
+# `aai init` — interactive project scaffolder
+
+**Status:** Approved (design)
+**Date:** 2026-06-04
+
+## Summary
+
+Add an `aai init` command: a Vercel-style scaffolder that lets a user pick from
+four templates, then **copies a real, runnable Python web project**, installs its
+dependencies, starts a local server, and opens the browser — so the user can
+interact with an AssemblyAI capability immediately and then keep building.
+
+The generated project's prime directive: **the files must be as simple as
+possible** so a human (or Claude Code) can read and extend them right after
+creation. No build step, no framework magic — two files carry the real logic.
+
+## Goals
+
+- One command (`aai init`) takes a user from nothing to a running, browser-based
+  AssemblyAI demo.
+- Four templates covering the CLI's core capabilities: `transcribe`, `stream`,
+  `agent`, `llm`.
+- Generated code is flat, plain, and immediately editable.
+- The browser **never** receives the real API key.
+- Each template is **structured so Vercel can deploy it as-is** (static frontend +
+  a thin stateless backend). We add the conventional layout + a `vercel.json`, but
+  build **no** deploy tooling of our own (no Dockerfiles, deploy buttons, or
+  Cloudflare functions) — that would only overlap with what Vercel already does.
+
+## Non-goals
+
+- Replacing `aai samples create` (it coexists — see below).
+- A Node/JavaScript toolchain. Templates are Python backend + a single vanilla
+  HTML/JS page.
+- A reusable framework or component library. Each template is self-contained.
+
+## Relationship to existing commands
+
+- **`aai samples create`** stays as-is: the quick **single-script** scaffolder
+  (one `.py` file, terminal output, no browser). `aai init` is the **full
+  interactive project + browser** experience. Clear split: *samples = snippet,
+  init = app.*
+- Template `api/index.py` logic is kept consistent with `aai_cli/code_gen`'s
+  generators (same AssemblyAI call patterns), verified by a test. `code_gen`
+  remains the reference; templates are committed real files (Approach A below).
+
+## Architecture decision: ship real template projects (Approach A)
+
+The four templates live as **actual, committed, runnable project directories**
+inside the package (`aai_cli/init/templates/<id>/`). `aai init` *copies* the
+chosen one rather than rendering it from string templates.
+
+- The generated output **is** the files we hand-wrote and tested — no
+  template-rendering indirection between what we verify and what the user gets.
+  This is the simplest possible output, which is the core constraint.
+- Templates are runnable in-repo, so they are easy to test and dogfood.
+- Trade-off: some AssemblyAI call logic overlaps with `code_gen`. We keep them
+  honest with a smoke test that loads each template and an optional
+  reference-consistency check.
+
+(Rejected: generating everything from `code_gen` + a web shell. String
+templating produces more abstract/indirected code — the opposite of the
+"simple files Claude can improve" goal.)
+
+## Command surface
+
+```
+aai init [TEMPLATE] [DIRECTORY] [options]
+```
+
+- **No args** → arrow-key picker (`questionary`) for the template, then a prompt
+  for the directory (default `./<template>-app`).
+- **TEMPLATE** ids mirror the CLI commands for memorability: `transcribe`,
+  `stream`, `agent`, `llm`. Descriptive titles shown in the picker.
+- **Options:**
+  - `--no-install` — scaffold only; skip env creation, install, launch, open.
+  - `--no-open` — install + launch, but don't open the browser.
+  - `--force` — overwrite a non-empty target directory.
+  - `--here` — scaffold into the current directory.
+  - `--port` — server port (default `3000`; auto-increments if taken).
+  - `--json` — machine-readable step output.
+
+**Default behavior (no skip flags):** scaffold → install deps → launch server →
+open browser. Vercel-style "it just opens."
+
+## Scaffold layout (per template)
+
+Templates adopt **Vercel's conventional layout** so the exact same files run
+locally (via `uvicorn`) and deploy to Vercel untouched — see Deployment below.
+
+```
+<dir>/
+  api/index.py      # FastAPI ASGI app: loads key, mints temp tokens (+ upload/poll for transcribe & llm)
+  index.html        # one vanilla-JS page, no build step
+  vercel.json       # routes "/" to index.html and "/api/*" to the FastAPI function
+  requirements.txt  # fastapi, assemblyai, python-dotenv (uvicorn for local run)
+  .env              # ASSEMBLYAI_API_KEY=…   (written by init, gitignored)
+  .env.example      # ASSEMBLYAI_API_KEY=
+  .gitignore        # .env, .venv, __pycache__
+  README.md         # what it is, how to run, deploy-to-Vercel note, "ideas to extend" hints
+```
+
+Only `api/index.py` and `index.html` carry real logic; the rest is boilerplate.
+
+## Template behavior
+
+Two backend shapes. **`stream` and `agent` are architecturally identical**: the
+backend only mints a short-lived temp token and the **browser holds the WebSocket
+directly to AssemblyAI** — no audio ever passes through the backend.
+**`transcribe` and `llm`** need a thin backend proxy (file upload + transcript
+polling) because the REST/upload endpoints aren't temp-token authorized.
+
+- **transcribe** — drop/pick an audio or video file → backend uploads to
+  AssemblyAI, creates the transcript, and the browser polls a short `/api/status`
+  call until done → page renders the JSON (speaker labels, chapters, sentiment,
+  entities, highlights). The split into create + poll keeps each backend call
+  short, which is also what makes it serverless-friendly.
+- **stream** (live captions) — browser captures mic audio and connects to
+  AssemblyAI Streaming v3 **directly using a short-lived temp token** minted by
+  the backend `/api/token` route; renders partial → final turns live.
+- **agent** (voice agent) — same pattern as `stream`: backend `/api/token` mints
+  a token (`GET /v1/token`, with `expires_in_seconds` / `max_session_duration_seconds`),
+  and the browser opens its own WebSocket directly to
+  `wss://agents.assemblyai.com/v1/ws?token=…`, streaming mic audio up and playing
+  agent audio back. No backend audio proxy, no persistent server WebSocket.
+- **llm** (chat with audio) — transcribe a file (same create+poll path as the
+  transcribe template), then a chat box posts questions to `/api/chat`, which
+  calls the LLM Gateway over the transcript and returns answers.
+
+## API key handling & browser safety (invariant)
+
+- `aai init` resolves the key via the **CLI's existing resolution chain**
+  (`ASSEMBLYAI_API_KEY` env → OS keyring) and writes it to the **gitignored**
+  `.env`. The backend loads it with `python-dotenv`.
+- **The browser never receives the real key.** File uploads and LLM calls go
+  through the backend (`transcribe`/`llm`); `stream` and `agent` use the backend's
+  `/api/token` endpoint, which mints a short-lived AssemblyAI temporary token for
+  the browser. For every template the API key stays server-side.
+- **No key resolvable** → scaffold anyway, write `.env` with a placeholder value,
+  warn the user, and **skip auto-launch** (the server would fail without a key).
+
+**Noted tension:** this is the one place the system diverges from the CLI's
+"never write the key to a plaintext dotfile" rule. Justification: the scaffold is
+a *separate generated project* (not the CLI's own credential store), `.env` is
+gitignored, and `.env` is the universal web-dev convention. Accepted deliberately.
+
+## Install / launch flow
+
+Reuses the "steps with status" rendering pattern from `aai claude` (themed step
+lines, `--json` support).
+
+1. Resolve template + target dir. Conflict (non-empty dir) → error unless
+   `--force`/`--here`.
+2. Copy template files; write `.env` (from resolved key), `.env.example`,
+   `.gitignore`.
+3. Create the environment: `uv venv` if `uv` is on PATH, else stdlib
+   `python -m venv`; install `requirements.txt` (`uv pip install` / `pip
+   install`). *(skipped on `--no-install`)*
+4. Launch the server as a subprocess — `uvicorn api.index:app --port <port>` (via
+   `uv run` or the created venv) — wait for the port to accept connections, open
+   the browser. *(skipped on `--no-install`/`--no-open`)*
+5. Print the URL and next steps. Ctrl-C stops the server cleanly (exit 0).
+
+## Deployment (Vercel-ready, no extra tooling)
+
+Each template uses Vercel's conventional layout (`api/index.py` + `index.html` +
+`vercel.json`), so the **same files run locally and deploy to Vercel untouched**:
+the user pushes the generated directory to a Git repo, imports it on Vercel, and
+sets `ASSEMBLYAI_API_KEY` as a Vercel environment variable (the local `.env` is
+git-ignored and never deployed). The README includes a short "Deploy to Vercel"
+note.
+
+- All four templates are Vercel-deployable because every backend is **thin and
+  stateless**: `stream`/`agent` only mint a temp token, and `transcribe`/`llm`
+  split work into short create + poll calls — no persistent WebSocket server and
+  no long-running request.
+- We deliberately ship **no deploy tooling of our own** — no Dockerfiles, deploy
+  buttons, CI config, or Cloudflare functions. That would only duplicate what
+  Vercel already provides. Our responsibility ends at producing a layout Vercel
+  can deploy.
+- Cloudflare is explicitly out of scope (no production Python runtime; would
+  require a JS rewrite).
+
+## Error handling
+
+- `uv` missing → fall back to stdlib `venv` + `pip` (shown in the step detail).
+- Install failure → leave scaffolded files in place, print manual run steps, exit
+  non-zero.
+- Port in use → increment to the next free port (or honor `--port`).
+- Target dir exists & non-empty → error unless `--force`.
+- No key → warn, scaffold anyway, do not auto-launch.
+- Ctrl-C during the running server → clean shutdown, exit 0 (mirrors the CLI's
+  existing closed-pipe / signal handling posture).
+
+## Code organization
+
+- `aai_cli/commands/init.py` — the Typer command; registered in `_COMMAND_ORDER`
+  in `main.py` (placed near `samples`).
+- `aai_cli/init/` package:
+  - `scaffold.py` — copy template files, write `.env`/`.env.example`/`.gitignore`.
+  - `runner.py` — environment setup, dependency install, server launch, browser
+    open, port selection.
+  - `templates/<id>/…` — the four real template projects, shipped as package data.
+- New CLI dependency: `questionary` (arrow-key picker).
+- `fastapi` / `uvicorn` / `python-dotenv` are dependencies of the **generated**
+  `requirements.txt`, **not** of the CLI itself.
+- `pyproject.toml` — include `aai_cli/init/templates/**` (all template files,
+  incl. `vercel.json`, `.env.example`, dotfiles) as package data.
+
+## Testing (TDD)
+
+- **Unit:** template/dir argument resolution, picker default-dir logic,
+  target-dir conflict handling, key → `.env` writing (assert the committed
+  template fixtures contain **no** real key), step rendering, `--json` output.
+- **Template integrity:** each template loads via FastAPI `TestClient`; `GET /`
+  returns 200 and serves the page; `/api/token` mints a token (AssemblyAI mocked)
+  for `stream`/`agent`. Each template directory contains the required files
+  (incl. `vercel.json`).
+- **Install flow:** with **mocked** subprocess — assert correct `uv`/`venv`/`pip`
+  commands, the uv→venv fallback path, and that `--no-install`/`--no-open` skip
+  their steps. No real network or pip in tests.
+- **Reference consistency (light):** each template's core AssemblyAI call matches
+  the corresponding `code_gen` reference pattern.
+
+## Open questions
+
+None blocking. Future follow-ups (out of scope for v1): additional templates,
+a `--template-url` for community templates, and first-class Cloudflare support
+(would require JS-based edge functions).

From 48c286d8916bd914ffc0dc04f43a19953274c991 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:09:22 -0700
Subject: [PATCH 02/32] docs: implementation plan for aai init core +
 transcribe template

Plan 1 of a series: full aai init machinery (picker, scaffold, runner,
step output, packaging) plus the transcribe template as a complete
vertical slice. stream/agent/llm templates are sibling follow-on plans.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...2026-06-04-aai-init-core-and-transcribe.md | 1418 +++++++++++++++++
 1 file changed, 1418 insertions(+)
 create mode 100644 specs/plans/2026-06-04-aai-init-core-and-transcribe.md

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
new file mode 100644
index 00000000..59f7abd1
--- /dev/null
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -0,0 +1,1418 @@
+# `aai init` Core Machinery + `transcribe` Template — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add an `aai init` command that interactively picks a template, copies a real, Vercel-deployable Python web project, installs its dependencies, launches a local server, and opens the browser — implemented end-to-end for the `transcribe` template.
+
+**Architecture:** A new `aai_cli/commands/init.py` Typer command drives three small, independently testable units under a new `aai_cli/init/` package: a template registry, a `scaffold` step (copy committed template files + write `.env`), and a `runner` step (detect `uv`/`venv`, install deps, pick a free port, launch `uvicorn`, open the browser). Templates are committed real projects under `aai_cli/init/templates/<id>/` and copied verbatim (Approach A from the spec) — the generated output *is* the files we hand-wrote and test. Progress is reported with the same "steps with status" pattern as `aai claude`.
+
+**Tech Stack:** Python 3.10+, Typer/Click (vendored in typer), `questionary` (new dep, arrow-key picker), `importlib.resources` (locate packaged template files), `uv`/`venv`+`pip` (env setup for the generated app), FastAPI + uvicorn + python-dotenv (dependencies of the *generated* app only), pytest + Typer `CliRunner` + FastAPI `TestClient` (tests).
+
+**Spec:** `specs/2026-06-04-aai-init-design.md`
+
+---
+
+## Scope & follow-on plans
+
+This plan delivers the **full `aai init` machinery** plus **one template (`transcribe`)** as a complete, working vertical slice. The remaining three templates from the spec are **separate sibling plans**, each additive and of the same shape (add `aai_cli/init/templates/<id>/`, register the id, add an integrity test):
+
+- `2026-06-XX-aai-init-stream-template.md` — live captions; backend `/api/token` only, browser holds the AssemblyAI Streaming WS directly.
+- `2026-06-XX-aai-init-agent-template.md` — voice agent; same token-only backend shape as `stream` (`GET /v1/token` → `wss://agents.assemblyai.com/v1/ws`).
+- `2026-06-XX-aai-init-llm-template.md` — chat with audio; transcribe create+poll, then `/api/chat` over the transcript via LLM Gateway.
+
+Splitting this way keeps each plan focused and lets the template plans build on the *proven* machinery from this one. The picker and registry are written to make adding a template a one-line registration plus a template directory.
+
+## File structure
+
+**New files (CLI package):**
+- `aai_cli/init/__init__.py` — package marker; re-exports the public surface (`TEMPLATES`, `TEMPLATE_ORDER`, `scaffold`, `resolve_optional_api_key`).
+- `aai_cli/init/templates.py` — the template registry: `TEMPLATES` (id → human title), `TEMPLATE_ORDER` (display order), `title_for`, `is_template`.
+- `aai_cli/init/keys.py` — `resolve_optional_api_key(profile)`: the CLI's key chain (env → keyring) but returning `None` instead of raising when absent.
+- `aai_cli/init/scaffold.py` — `scaffold(template, target_dir, api_key)`: copy the packaged template tree (renaming dotfile templates) and write `.env`; plus `target_conflict(dir)` and `template_files(template)` helpers.
+- `aai_cli/init/runner.py` — pure command builders + IO helpers: `has_uv`, `venv_python`, `env_setup_commands`, `serve_command`, `find_free_port`, `wait_for_port`, `launch_and_open`.
+- `aai_cli/init/steps.py` — `Step` TypedDict + `render_steps(steps)` (same shape as `aai_cli/commands/claude.py`, kept local to `init`).
+- `aai_cli/commands/init.py` — the Typer command wiring picker → scaffold → runner → step output.
+
+**New files (the `transcribe` template, committed real project):**
+- `aai_cli/init/templates/transcribe/api/index.py` — FastAPI app: serve `index.html`, `POST /api/transcribe` (submit), `GET /api/status/{id}` (poll).
+- `aai_cli/init/templates/transcribe/index.html` — one vanilla-JS page: file picker → submit → poll → render transcript + audio-intelligence chips.
+- `aai_cli/init/templates/transcribe/vercel.json` — route `/` to the page and `/api/*` to the function.
+- `aai_cli/init/templates/transcribe/requirements.txt` — `fastapi`, `assemblyai`, `python-dotenv`, `uvicorn`, `python-multipart`.
+- `aai_cli/init/templates/transcribe/README.md` — what it is, run locally, deploy to Vercel, "ideas to extend".
+- `aai_cli/init/templates/transcribe/gitignore` — packaged WITHOUT a leading dot; scaffold renames to `.gitignore`.
+- `aai_cli/init/templates/transcribe/env.example` — packaged without a leading dot; scaffold renames to `.env.example`.
+
+**Modified files:**
+- `pyproject.toml` — add `questionary` to `dependencies`; ensure the template tree (incl. non-`.py` files) is included in the wheel.
+- `aai_cli/main.py` — import and register the `init` command; add `"init"` to `_COMMAND_ORDER`.
+- `tests/` — new test modules per task.
+
+**Design note on dotfiles:** template dotfiles are stored under plain names (`gitignore`, `env.example`) so (a) the repo's own `.gitignore` can't accidentally ignore them, and (b) they're reliably included in the wheel. `scaffold` maps them to their dotted names on copy. The real `.env` is never committed in a template — it's written at scaffold time from the resolved key (or a placeholder).
+
+---
+
+## Task 1: New dependency + package skeleton + packaging
+
+**Files:**
+- Modify: `pyproject.toml` (dependencies + wheel package data)
+- Create: `aai_cli/init/__init__.py`
+- Test: `tests/test_init_packaging.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_packaging.py
+import importlib
+
+
+def test_init_package_imports():
+    mod = importlib.import_module("aai_cli.init")
+    assert mod is not None
+
+
+def test_questionary_is_available():
+    # questionary is a runtime dependency of the CLI (the init picker).
+    assert importlib.import_module("questionary") is not None
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_packaging.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init'` (and possibly `questionary`).
+
+- [ ] **Step 3: Add the dependency and create the package**
+
+In `pyproject.toml`, add to the `dependencies` array (keep the existing list; add this line):
+
+```toml
+    "questionary>=2.0.1",
+```
+
+Then ensure the template tree ships in the wheel. The wheel target currently is:
+
+```toml
+[tool.hatch.build.targets.wheel]
+packages = ["aai_cli"]
+```
+
+Add an explicit artifacts include so non-`.py` template files (and renamed dotfiles) are always packaged:
+
+```toml
+[tool.hatch.build.targets.wheel]
+packages = ["aai_cli"]
+artifacts = ["aai_cli/init/templates/**"]
+```
+
+Create the package marker:
+
+```python
+# aai_cli/init/__init__.py
+from __future__ import annotations
+```
+
+- [ ] **Step 4: Sync the environment and run the test**
+
+Run: `uv sync --extra dev && uv run pytest tests/test_init_packaging.py -v`
+Expected: PASS (both tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add pyproject.toml uv.lock aai_cli/init/__init__.py tests/test_init_packaging.py
+git commit -m "feat(init): add questionary dep + init package skeleton"
+```
+
+---
+
+## Task 2: Template registry
+
+**Files:**
+- Create: `aai_cli/init/templates.py`
+- Test: `tests/test_init_templates.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_templates.py
+from aai_cli.init import templates
+
+
+def test_all_four_template_ids_present():
+    assert set(templates.TEMPLATES) == {"transcribe", "stream", "agent", "llm"}
+
+
+def test_template_order_is_complete_and_stable():
+    # Display order mirrors the CLI's command order; every id appears exactly once.
+    assert templates.TEMPLATE_ORDER == ("transcribe", "stream", "agent", "llm")
+    assert set(templates.TEMPLATE_ORDER) == set(templates.TEMPLATES)
+
+
+def test_title_for_known_and_unknown():
+    assert "Transcribe" in templates.title_for("transcribe")
+    assert templates.title_for("nope") == "nope"  # falls back to the raw id
+
+
+def test_is_template():
+    assert templates.is_template("agent") is True
+    assert templates.is_template("nope") is False
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_templates.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.templates'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# aai_cli/init/templates.py
+from __future__ import annotations
+
+# id -> human-facing title shown in the picker. Ids mirror the CLI's commands.
+TEMPLATES: dict[str, str] = {
+    "transcribe": "Transcribe & explore a file",
+    "stream": "Live captions (mic → browser)",
+    "agent": "Talk to a voice agent",
+    "llm": "Chat with your audio (LLM)",
+}
+
+# Display order for the picker and `--help`, matching the CLI's command order.
+TEMPLATE_ORDER: tuple[str, ...] = ("transcribe", "stream", "agent", "llm")
+
+
+def is_template(name: str) -> bool:
+    return name in TEMPLATES
+
+
+def title_for(name: str) -> str:
+    """The human title for a template id, or the raw id if unknown."""
+    return TEMPLATES.get(name, name)
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_init_templates.py -v`
+Expected: PASS (4 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add aai_cli/init/templates.py tests/test_init_templates.py
+git commit -m "feat(init): template registry"
+```
+
+---
+
+## Task 3: Optional API-key resolution
+
+**Files:**
+- Create: `aai_cli/init/keys.py`
+- Test: `tests/test_init_keys.py`
+
+The CLI's `config.resolve_api_key` raises `NotAuthenticated` when no key exists. `aai init` must still scaffold without a key (writing a placeholder), so it needs a non-raising variant.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_keys.py
+from aai_cli import config
+from aai_cli.init import keys
+
+
+def test_resolves_from_env(monkeypatch):
+    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "env-key-123")
+    assert keys.resolve_optional_api_key(profile=None) == "env-key-123"
+
+
+def test_resolves_from_keyring(memory_keyring):
+    config.set_api_key("default", "stored-key-456")
+    assert keys.resolve_optional_api_key(profile=None) == "stored-key-456"
+
+
+def test_returns_none_when_absent():
+    # isolate_env strips the env var and memory_keyring starts empty.
+    assert keys.resolve_optional_api_key(profile=None) is None
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_keys.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.keys'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# aai_cli/init/keys.py
+from __future__ import annotations
+
+from aai_cli import config
+from aai_cli.errors import NotAuthenticated
+
+
+def resolve_optional_api_key(*, profile: str | None) -> str | None:
+    """The CLI's key chain (env -> keyring), but None instead of raising when absent.
+
+    `aai init` scaffolds even without a key (writing a placeholder), so it must not
+    fail the way run commands do.
+    """
+    try:
+        return config.resolve_api_key(profile=profile)
+    except NotAuthenticated:
+        return None
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_init_keys.py -v`
+Expected: PASS (3 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add aai_cli/init/keys.py tests/test_init_keys.py
+git commit -m "feat(init): optional API-key resolution (no raise when absent)"
+```
+
+---
+
+## Task 4: The `transcribe` template files
+
+**Files:**
+- Create: `aai_cli/init/templates/transcribe/api/index.py`
+- Create: `aai_cli/init/templates/transcribe/index.html`
+- Create: `aai_cli/init/templates/transcribe/vercel.json`
+- Create: `aai_cli/init/templates/transcribe/requirements.txt`
+- Create: `aai_cli/init/templates/transcribe/README.md`
+- Create: `aai_cli/init/templates/transcribe/gitignore`
+- Create: `aai_cli/init/templates/transcribe/env.example`
+- Test: `tests/test_init_template_transcribe.py`
+
+This task writes the real, runnable template and a test that loads its FastAPI app via `TestClient` with the AssemblyAI SDK mocked. The template uses a **submit + poll** split (each backend call is short → serverless-friendly), per the spec.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_template_transcribe.py
+import importlib.util
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from fastapi.testclient import TestClient
+
+TEMPLATE_DIR = Path("aai_cli/init/templates/transcribe")
+
+
+def _load_app(monkeypatch):
+    """Import the template's api/index.py as a module and return its FastAPI app.
+
+    The template is a standalone project (not part of aai_cli's import graph), so we
+    load it by file path. assemblyai is stubbed so no network/key is needed.
+    """
+    fake_aai = MagicMock()
+    fake_aai.TranscriptStatus.completed = "completed"
+    fake_aai.TranscriptStatus.error = "error"
+    submitted = MagicMock(id="t-123")
+    fake_aai.Transcriber.return_value.submit.return_value = submitted
+    done = MagicMock(status="completed", error=None,
+                     json_response={"text": "hello world", "utterances": []})
+    fake_aai.Transcript.get_by_id.return_value = done
+    monkeypatch.setitem(sys.modules, "assemblyai", fake_aai)
+
+    spec = importlib.util.spec_from_file_location(
+        "_tmpl_transcribe", TEMPLATE_DIR / "api" / "index.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.app, fake_aai
+
+
+def test_required_files_exist():
+    for rel in ("api/index.py", "index.html", "vercel.json",
+                "requirements.txt", "README.md", "gitignore", "env.example"):
+        assert (TEMPLATE_DIR / rel).exists(), rel
+
+
+def test_template_ships_no_real_key():
+    # No committed file may contain a literal .env with a key; only env.example.
+    assert not (TEMPLATE_DIR / ".env").exists()
+    assert "your_assemblyai_api_key_here" in (TEMPLATE_DIR / "env.example").read_text()
+
+
+def test_index_route_serves_page(monkeypatch):
+    app, _ = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.get("/")
+    assert resp.status_code == 200
+    assert "<html" in resp.text.lower()
+
+
+def test_submit_returns_transcript_id(monkeypatch):
+    app, fake = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.post("/api/transcribe", files={"file": ("a.mp3", b"\x00\x01", "audio/mpeg")})
+    assert resp.status_code == 200
+    assert resp.json() == {"id": "t-123"}
+    fake.Transcriber.return_value.submit.assert_called_once()
+
+
+def test_status_returns_completed_transcript(monkeypatch):
+    app, _ = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.get("/api/status/t-123")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["status"] == "completed"
+    assert body["transcript"]["text"] == "hello world"
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_template_transcribe.py -v`
+Expected: FAIL — the template files don't exist yet (`test_required_files_exist` fails; loaders error on missing path).
+
+- [ ] **Step 3: Create the backend `api/index.py`**
+
+```python
+# aai_cli/init/templates/transcribe/api/index.py
+"""Transcribe & explore — AssemblyAI starter (FastAPI).
+
+Two short endpoints so each request stays fast (serverless-friendly):
+  POST /api/transcribe  -> submit the upload, return {"id": ...}
+  GET  /api/status/{id} -> poll; returns the full transcript JSON when complete
+
+The browser (index.html) submits a file, then polls status until done.
+Your API key stays on the server — the browser never sees it.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+import uuid
+from pathlib import Path
+
+import assemblyai as aai
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+
+load_dotenv()
+aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY", "")
+
+# Audio-intelligence features to showcase. Tweak these — that's the point of a starter.
+CONFIG = aai.TranscriptionConfig(
+    speaker_labels=True,
+    auto_chapters=True,
+    sentiment_analysis=True,
+    entity_detection=True,
+    auto_highlights=True,
+)
+
+ROOT = Path(__file__).resolve().parent.parent
+app = FastAPI()
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(ROOT / "index.html")
+
+
+@app.post("/api/transcribe")
+async def transcribe(file: UploadFile) -> dict[str, str]:
+    suffix = Path(file.filename or "audio").suffix
+    tmp = Path(tempfile.gettempdir()) / f"aai-{uuid.uuid4().hex}{suffix}"
+    tmp.write_bytes(await file.read())
+    transcript = aai.Transcriber().submit(str(tmp), config=CONFIG)
+    return {"id": transcript.id}
+
+
+@app.get("/api/status/{transcript_id}")
+def status(transcript_id: str) -> dict[str, object]:
+    t = aai.Transcript.get_by_id(transcript_id)
+    if t.status == aai.TranscriptStatus.error:
+        raise HTTPException(status_code=502, detail=t.error or "Transcription failed")
+    if t.status == aai.TranscriptStatus.completed:
+        return {"status": "completed", "transcript": t.json_response}
+    return {"status": str(getattr(t.status, "value", t.status))}
+```
+
+- [ ] **Step 4: Create the frontend `index.html`**
+
+```html
+<!-- aai_cli/init/templates/transcribe/index.html -->
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Transcribe &amp; explore · AssemblyAI</title>
+  <style>
+    body { font: 15px/1.6 system-ui, sans-serif; max-width: 760px; margin: 40px auto; padding: 0 16px; }
+    h1 { font-size: 20px; }
+    #drop { border: 2px dashed #bbb; border-radius: 10px; padding: 28px; text-align: center; cursor: pointer; }
+    #drop.busy { opacity: .6; pointer-events: none; }
+    .chips span { display: inline-block; background: #eef; border-radius: 99px; padding: 3px 10px; margin: 2px; font-size: 12px; }
+    .turn { margin: 6px 0; }
+    .spk { font-weight: 600; }
+    pre { white-space: pre-wrap; }
+  </style>
+</head>
+<body>
+  <h1>🎧 Transcribe &amp; explore</h1>
+  <p>Pick an audio or video file. The server transcribes it with AssemblyAI and returns speakers, chapters, sentiment, entities, and highlights.</p>
+
+  <label id="drop">
+    <input id="file" type="file" accept="audio/*,video/*" hidden />
+    <span id="droplabel">Click to choose a file</span>
+  </label>
+
+  <p id="status"></p>
+  <div id="result"></div>
+
+  <script>
+    const fileInput = document.getElementById("file");
+    const drop = document.getElementById("drop");
+    const statusEl = document.getElementById("status");
+    const result = document.getElementById("result");
+
+    drop.addEventListener("click", () => fileInput.click());
+    fileInput.addEventListener("change", () => fileInput.files[0] && upload(fileInput.files[0]));
+
+    async function upload(file) {
+      drop.classList.add("busy");
+      result.innerHTML = "";
+      statusEl.textContent = "Uploading…";
+      const body = new FormData();
+      body.append("file", file);
+      const res = await fetch("/api/transcribe", { method: "POST", body });
+      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
+      const { id } = await res.json();
+      poll(id);
+    }
+
+    async function poll(id) {
+      statusEl.textContent = "Transcribing…";
+      const res = await fetch("/api/status/" + id);
+      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
+      const data = await res.json();
+      if (data.status !== "completed") { setTimeout(() => poll(id), 2000); return; }
+      statusEl.textContent = "Done.";
+      drop.classList.remove("busy");
+      render(data.transcript);
+    }
+
+    function render(t) {
+      const chips = [];
+      if (t.chapters) chips.push("Chapters");
+      if (t.sentiment_analysis_results) chips.push("Sentiment");
+      if (t.entities) chips.push("Entities");
+      if (t.auto_highlights_result) chips.push("Highlights");
+      const utterances = (t.utterances || []).map(
+        (u) => `<div class="turn"><span class="spk">Speaker ${u.speaker}:</span> ${escapeHtml(u.text)}</div>`
+      ).join("");
+      result.innerHTML =
+        `<div class="chips">${chips.map((c) => `<span>${c}</span>`).join("")}</div>` +
+        (utterances || `<pre>${escapeHtml(t.text || "")}</pre>`);
+    }
+
+    function escapeHtml(s) {
+      return (s || "").replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
+    }
+  </script>
+</body>
+</html>
+```
+
+- [ ] **Step 5: Create `vercel.json`, `requirements.txt`, `README.md`, `gitignore`, `env.example`**
+
+```json
+// aai_cli/init/templates/transcribe/vercel.json
+{
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/index" },
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
+```
+
+```text
+# aai_cli/init/templates/transcribe/requirements.txt
+fastapi
+uvicorn
+assemblyai
+python-dotenv
+python-multipart
+```
+
+```markdown
+<!-- aai_cli/init/templates/transcribe/README.md -->
+# Transcribe & explore — AssemblyAI starter
+
+Upload an audio/video file and see the transcript with speaker labels, chapters,
+sentiment, entities, and highlights. Built with FastAPI + a single HTML page.
+
+## Run locally
+
+```sh
+uvicorn api.index:app --reload --port 3000
+# open http://localhost:3000
+```
+
+`ASSEMBLYAI_API_KEY` is read from `.env` (already created for you if you ran `aai init`).
+
+## Deploy to Vercel
+
+Push this folder to a Git repo and import it on Vercel. Set `ASSEMBLYAI_API_KEY`
+as a Vercel environment variable (the local `.env` is git-ignored and not deployed).
+No extra config — `vercel.json` routes the page and the `/api` function.
+
+## Ideas to extend
+
+- Show chapter summaries and highlight timestamps.
+- Add a waveform / audio player synced to the transcript.
+- Swap the analysis features in `CONFIG` (api/index.py).
+```
+
+```text
+# aai_cli/init/templates/transcribe/gitignore
+.env
+.venv
+__pycache__/
+```
+
+```text
+# aai_cli/init/templates/transcribe/env.example
+ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
+```
+
+- [ ] **Step 6: Add `python-multipart` to the dev env so the test client can post files**
+
+`fastapi`/`uvicorn`/`python-multipart` are runtime deps of the *generated* app, not the CLI. The test loads the template app in-process, so they must be available in the dev environment. Add them to the `dev` optional-dependencies in `pyproject.toml`:
+
+```toml
+dev = [
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "hypothesis>=6.155.1",
+    "ruff>=0.15.15",
+    "mypy>=2.1.0",
+    "pre-commit>=4.6.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.30.0",
+    "python-dotenv>=1.0.0",
+    "python-multipart>=0.0.9",
+]
+```
+
+Then: `uv sync --extra dev`
+
+- [ ] **Step 7: Run the tests to verify they pass**
+
+Run: `uv run pytest tests/test_init_template_transcribe.py -v`
+Expected: PASS (5 tests).
+
+- [ ] **Step 8: Commit**
+
+```bash
+git add aai_cli/init/templates/transcribe pyproject.toml uv.lock tests/test_init_template_transcribe.py
+git commit -m "feat(init): transcribe template (FastAPI submit+poll, Vercel-ready)"
+```
+
+---
+
+## Task 5: Scaffold (copy template + write `.env`)
+
+**Files:**
+- Create: `aai_cli/init/scaffold.py`
+- Test: `tests/test_init_scaffold.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_scaffold.py
+from pathlib import Path
+
+import pytest
+
+from aai_cli.errors import CLIError
+from aai_cli.init import scaffold
+
+
+def test_scaffold_copies_files_and_renames_dotfiles(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
+    assert (target / "api" / "index.py").exists()
+    assert (target / "index.html").exists()
+    assert (target / "vercel.json").exists()
+    # dotfile templates are renamed to their dotted names
+    assert (target / ".gitignore").exists()
+    assert (target / ".env.example").exists()
+    # the plain-named source files are NOT copied verbatim
+    assert not (target / "gitignore").exists()
+    assert not (target / "env.example").exists()
+
+
+def test_scaffold_writes_env_with_key(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
+    env = (target / ".env").read_text()
+    assert "ASSEMBLYAI_API_KEY=sk-real-key" in env
+
+
+def test_scaffold_writes_placeholder_when_no_key(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key=None)
+    env = (target / ".env").read_text()
+    assert scaffold.PLACEHOLDER_KEY in env
+
+
+def test_scaffold_unknown_template_raises(tmp_path):
+    with pytest.raises(CLIError):
+        scaffold.scaffold("nope", tmp_path / "app", api_key=None)
+
+
+def test_target_conflict_detects_nonempty_dir(tmp_path):
+    empty = tmp_path / "empty"
+    empty.mkdir()
+    assert scaffold.target_conflict(empty) is False
+    assert scaffold.target_conflict(tmp_path / "missing") is False
+    nonempty = tmp_path / "full"
+    nonempty.mkdir()
+    (nonempty / "x.txt").write_text("hi")
+    assert scaffold.target_conflict(nonempty) is True
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_scaffold.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.scaffold'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# aai_cli/init/scaffold.py
+from __future__ import annotations
+
+from importlib import resources
+from importlib.resources.abc import Traversable
+from pathlib import Path
+
+from aai_cli.errors import CLIError
+from aai_cli.init import templates
+
+PLACEHOLDER_KEY = "your_assemblyai_api_key_here"
+
+# Template files stored under plain names -> their real dotted names on copy.
+_DOTFILE_RENAMES = {"gitignore": ".gitignore", "env.example": ".env.example"}
+
+
+def _template_root(template: str) -> Traversable:
+    if not templates.is_template(template):
+        raise CLIError(
+            f"Unknown template {template!r}. Choose one of: "
+            f"{', '.join(templates.TEMPLATE_ORDER)}.",
+            error_type="unknown_template",
+            exit_code=1,
+        )
+    return resources.files("aai_cli.init.templates") / template
+
+
+def target_conflict(target: Path) -> bool:
+    """True when the target exists and is a non-empty directory."""
+    return target.is_dir() and any(target.iterdir())
+
+
+def _copy_tree(node: Traversable, dest: Path) -> None:
+    for child in node.iterdir():
+        name = _DOTFILE_RENAMES.get(child.name, child.name)
+        out = dest / name
+        if child.is_dir():
+            out.mkdir(parents=True, exist_ok=True)
+            _copy_tree(child, out)
+        else:
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_bytes(child.read_bytes())
+
+
+def scaffold(template: str, target: Path, *, api_key: str | None) -> Path:
+    """Copy the template into `target` and write `.env`. Returns `target`."""
+    root = _template_root(template)
+    target.mkdir(parents=True, exist_ok=True)
+    _copy_tree(root, target)
+    key = api_key or PLACEHOLDER_KEY
+    (target / ".env").write_text(f"ASSEMBLYAI_API_KEY={key}\n")
+    return target
+```
+
+> Note on `from importlib.resources.abc import Traversable`: on Python 3.10 use `from importlib.abc import Traversable` instead. If supporting both, import defensively:
+> ```python
+> try:
+>     from importlib.resources.abc import Traversable
+> except ImportError:  # Python 3.10
+>     from importlib.abc import Traversable
+> ```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_init_scaffold.py -v`
+Expected: PASS (5 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add aai_cli/init/scaffold.py tests/test_init_scaffold.py
+git commit -m "feat(init): scaffold (copy template tree + write .env)"
+```
+
+---
+
+## Task 6: Runner — command builders + port/launch helpers
+
+**Files:**
+- Create: `aai_cli/init/runner.py`
+- Test: `tests/test_init_runner.py`
+
+The pure command builders and port finder are unit-tested directly; the subprocess launch is exercised in Task 7 with mocks.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_runner.py
+import socket
+import sys
+from pathlib import Path
+
+from aai_cli.init import runner
+
+
+def test_has_uv_reflects_path(monkeypatch):
+    monkeypatch.setattr(runner.shutil, "which", lambda name: "/usr/bin/uv")
+    assert runner.has_uv() is True
+    monkeypatch.setattr(runner.shutil, "which", lambda name: None)
+    assert runner.has_uv() is False
+
+
+def test_venv_python_path_per_platform(monkeypatch):
+    target = Path("/proj")
+    monkeypatch.setattr(runner.os, "name", "posix")
+    assert runner.venv_python(target) == target / ".venv" / "bin" / "python"
+    monkeypatch.setattr(runner.os, "name", "nt")
+    assert runner.venv_python(target) == target / ".venv" / "Scripts" / "python.exe"
+
+
+def test_env_setup_commands_uv():
+    cmds = runner.env_setup_commands(Path("/proj"), use_uv=True)
+    assert cmds == [["uv", "venv"], ["uv", "pip", "install", "-r", "requirements.txt"]]
+
+
+def test_env_setup_commands_venv():
+    target = Path("/proj")
+    cmds = runner.env_setup_commands(target, use_uv=False)
+    py = str(runner.venv_python(target))
+    assert cmds == [
+        [sys.executable, "-m", "venv", ".venv"],
+        [py, "-m", "pip", "install", "-r", "requirements.txt"],
+    ]
+
+
+def test_serve_command_uv_and_venv():
+    target = Path("/proj")
+    assert runner.serve_command(target, port=3000, use_uv=True) == [
+        "uv", "run", "uvicorn", "api.index:app", "--port", "3000",
+    ]
+    py = str(runner.venv_python(target))
+    assert runner.serve_command(target, port=3000, use_uv=False) == [
+        py, "-m", "uvicorn", "api.index:app", "--port", "3000",
+    ]
+
+
+def test_find_free_port_returns_preferred_when_open():
+    # Bind nothing on a high port we expect to be free.
+    port = runner.find_free_port(0)  # 0 -> OS assigns a free port
+    assert isinstance(port, int) and port > 0
+
+
+def test_find_free_port_skips_taken_port():
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.bind(("127.0.0.1", 0))
+    taken = s.getsockname()[1]
+    s.listen(1)
+    try:
+        chosen = runner.find_free_port(taken)
+        assert chosen != taken
+    finally:
+        s.close()
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_runner.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.runner'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# aai_cli/init/runner.py
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import subprocess
+import time
+import webbrowser
+from pathlib import Path
+
+
+def has_uv() -> bool:
+    return shutil.which("uv") is not None
+
+
+def venv_python(target: Path) -> Path:
+    if os.name == "nt":
+        return target / ".venv" / "Scripts" / "python.exe"
+    return target / ".venv" / "bin" / "python"
+
+
+def env_setup_commands(target: Path, *, use_uv: bool) -> list[list[str]]:
+    """Commands (run with cwd=target) to create a venv and install requirements."""
+    if use_uv:
+        return [["uv", "venv"], ["uv", "pip", "install", "-r", "requirements.txt"]]
+    import sys
+
+    py = str(venv_python(target))
+    return [
+        [sys.executable, "-m", "venv", ".venv"],
+        [py, "-m", "pip", "install", "-r", "requirements.txt"],
+    ]
+
+
+def serve_command(target: Path, *, port: int, use_uv: bool) -> list[str]:
+    if use_uv:
+        return ["uv", "run", "uvicorn", "api.index:app", "--port", str(port)]
+    return [str(venv_python(target)), "-m", "uvicorn", "api.index:app", "--port", str(port)]
+
+
+def _port_open(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+def find_free_port(preferred: int, *, tries: int = 20) -> int:
+    """The preferred port if free, else the next free port; OS-assigned when preferred is 0."""
+    if preferred == 0:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("127.0.0.1", 0))
+            return int(s.getsockname()[1])
+    for candidate in range(preferred, preferred + tries):
+        if not _port_open(candidate):
+            return candidate
+    return preferred
+
+
+def wait_for_port(port: int, *, timeout: float = 30.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if _port_open(port):
+            return True
+        time.sleep(0.2)
+    return False
+
+
+def run_setup(target: Path, *, use_uv: bool) -> subprocess.CompletedProcess:
+    """Run env-setup commands in order; return the first failure or the last success."""
+    last: subprocess.CompletedProcess | None = None
+    for cmd in env_setup_commands(target, use_uv=use_uv):
+        last = subprocess.run(cmd, cwd=target, capture_output=True, text=True)
+        if last.returncode != 0:
+            return last
+    assert last is not None
+    return last
+
+
+def launch_and_open(target: Path, *, port: int, use_uv: bool, open_browser: bool) -> int:
+    """Start the dev server, wait for it, open the browser, and block until Ctrl-C.
+
+    Returns the process exit code (0 on a clean Ctrl-C shutdown).
+    """
+    proc = subprocess.Popen(serve_command(target, port=port, use_uv=use_uv), cwd=target)
+    try:
+        if wait_for_port(port) and open_browser:
+            webbrowser.open(f"http://localhost:{port}")
+        proc.wait()
+    except KeyboardInterrupt:
+        proc.terminate()
+        proc.wait()
+        return 0
+    return proc.returncode
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_init_runner.py -v`
+Expected: PASS (7 tests).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add aai_cli/init/runner.py tests/test_init_runner.py
+git commit -m "feat(init): runner command builders + port/launch helpers"
+```
+
+---
+
+## Task 7: Step rendering helper
+
+**Files:**
+- Create: `aai_cli/init/steps.py`
+- Test: `tests/test_init_steps.py`
+
+Mirrors the `Step`/`_render_steps` shape in `aai_cli/commands/claude.py`, kept local to `init`.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_steps.py
+from aai_cli.init import steps
+
+
+def test_render_steps_includes_name_status_detail():
+    data = [
+        {"name": "scaffold", "status": "created", "detail": "./my-app"},
+        {"name": "install", "status": "skipped", "detail": "--no-install"},
+    ]
+    out = steps.render_steps(data)
+    assert "scaffold" in out
+    assert "created" in out
+    assert "./my-app" in out
+    assert "install" in out
+    assert "skipped" in out
+
+
+def test_render_steps_has_heading():
+    out = steps.render_steps([{"name": "scaffold", "status": "created", "detail": "x"}])
+    assert "init" in out.lower() or "AssemblyAI" in out
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_steps.py -v`
+Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.steps'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```python
+# aai_cli/init/steps.py
+from __future__ import annotations
+
+from typing import TypedDict
+
+from rich.markup import escape
+
+from aai_cli import theme
+
+
+class Step(TypedDict):
+    name: str
+    status: str
+    detail: str
+
+
+def render_steps(items: list[Step]) -> str:
+    lines = []
+    for s in items:
+        style = theme.status_style(s["status"])
+        lines.append(
+            f"  {escape(s['name'])}: "
+            f"[{style}]{escape(s['status'])}[/{style}] — {escape(s['detail'])}"
+        )
+    return "[aai.heading]aai init:[/aai.heading]\n" + "\n".join(lines)
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_init_steps.py -v`
+Expected: PASS (2 tests).
+
+> If `theme.status_style` doesn't recognize a status string it should already
+> return a safe default (it does for `aai claude`). Confirm by reading
+> `aai_cli/theme.py`; reuse the same status vocabulary
+> (`created`/`installed`/`skipped`/`failed`/`already`).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add aai_cli/init/steps.py tests/test_init_steps.py
+git commit -m "feat(init): step-status rendering helper"
+```
+
+---
+
+## Task 8: The `init` command (wire everything) + registration
+
+**Files:**
+- Create: `aai_cli/commands/init.py`
+- Modify: `aai_cli/main.py` (import, register, `_COMMAND_ORDER`)
+- Modify: `aai_cli/init/__init__.py` (re-export public surface)
+- Test: `tests/test_init_command.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_command.py
+from pathlib import Path
+
+from typer.testing import CliRunner
+
+from aai_cli.main import app
+
+runner = CliRunner()
+
+
+def test_init_scaffold_only_creates_project(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / "myapp" / "api" / "index.py").exists()
+    assert (tmp_path / "myapp" / ".env").exists()
+
+
+def test_init_writes_key_from_env(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "sk-from-env")
+    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    assert "ASSEMBLYAI_API_KEY=sk-from-env" in (tmp_path / "myapp" / ".env").read_text()
+
+
+def test_init_placeholder_key_when_logged_out(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    env = (tmp_path / "myapp" / ".env").read_text()
+    assert "your_assemblyai_api_key_here" in env
+
+
+def test_init_unknown_template_errors(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "nope", "myapp", "--no-install"])
+    assert result.exit_code == 1
+
+
+def test_init_refuses_nonempty_dir_without_force(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"]).exit_code == 0
+    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    assert result.exit_code == 1
+
+
+def test_init_force_overwrites(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"]).exit_code == 0
+    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install", "--force"])
+    assert result.exit_code == 0
+
+
+def test_init_no_template_non_interactive_errors(tmp_path, monkeypatch):
+    # CliRunner has no TTY, so the picker can't run; bare `aai init` must error helpfully.
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init"])
+    assert result.exit_code != 0
+    assert "transcribe" in result.output  # lists the available templates
+
+
+def test_init_default_dir_is_template_app(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "transcribe", "--no-install"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / "transcribe-app" / "api" / "index.py").exists()
+
+
+def test_init_appears_in_help():
+    result = runner.invoke(app, ["--help"])
+    assert "init" in result.output
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_init_command.py -v`
+Expected: FAIL — `init` is not a registered command (non-zero exit / usage error).
+
+- [ ] **Step 3: Implement the command**
+
+```python
+# aai_cli/commands/init.py
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+from rich.markup import escape
+
+from aai_cli import output
+from aai_cli.context import AppState, run_command
+from aai_cli.errors import UsageError
+from aai_cli.init import keys, runner, scaffold, steps, templates
+
+app = typer.Typer(
+    help="Scaffold a runnable AssemblyAI web app and open it in your browser.",
+    no_args_is_help=False,  # bare `aai init` runs the interactive picker (or errors if no TTY)
+)
+
+
+def _pick_template() -> str:
+    """Interactive picker; raises UsageError when there's no TTY to prompt on."""
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        raise UsageError(
+            "No template given and not running interactively. "
+            f"Pass one of: {', '.join(templates.TEMPLATE_ORDER)}."
+        )
+    import questionary
+
+    choice = questionary.select(
+        "Pick a template",
+        choices=[
+            questionary.Choice(title=templates.title_for(t), value=t)
+            for t in templates.TEMPLATE_ORDER
+        ],
+    ).ask()
+    if choice is None:  # user pressed Ctrl-C
+        raise typer.Exit(code=130)
+    return str(choice)
+
+
+def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
+    if here:
+        return Path.cwd()
+    if directory:
+        return Path(directory)
+    return Path.cwd() / f"{template}-app"
+
+
+@app.callback(invoke_without_command=True)
+def init(
+    ctx: typer.Context,
+    template: str = typer.Argument(None, help="Template id: transcribe, stream, agent, llm."),
+    directory: str = typer.Argument(None, help="Target directory (default: <template>-app)."),
+    no_install: bool = typer.Option(False, "--no-install", help="Scaffold only; don't install or launch."),
+    no_open: bool = typer.Option(False, "--no-open", help="Install + launch, but don't open the browser."),
+    force: bool = typer.Option(False, "--force", help="Overwrite a non-empty target directory."),
+    here: bool = typer.Option(False, "--here", help="Scaffold into the current directory."),
+    port: int = typer.Option(3000, "--port", help="Local server port."),
+    json_out: bool = typer.Option(False, "--json", help="Output raw JSON."),
+) -> None:
+    """Pick a template, scaffold it, install deps, launch the server, open the browser."""
+
+    def body(state: AppState, json_mode: bool) -> None:
+        chosen = template
+        if chosen is None:
+            chosen = _pick_template()
+        if not templates.is_template(chosen):
+            raise UsageError(
+                f"Unknown template {chosen!r}. Choose one of: "
+                f"{', '.join(templates.TEMPLATE_ORDER)}."
+            )
+
+        target = _resolve_dir(directory, chosen, here=here)
+        if scaffold.target_conflict(target) and not force:
+            raise UsageError(
+                f"{target} already exists and is not empty. "
+                f"Use --force to overwrite or pick another directory."
+            )
+
+        api_key = keys.resolve_optional_api_key(profile=state.profile)
+        scaffold.scaffold(chosen, target, api_key=api_key)
+
+        report: list[steps.Step] = [
+            {"name": "scaffold", "status": "created", "detail": str(target)}
+        ]
+        if api_key is None:
+            report.append(
+                {"name": "key", "status": "skipped",
+                 "detail": "no API key found; wrote a placeholder to .env (run `aai login`)"}
+            )
+
+        will_launch = not no_install and api_key is not None
+        if no_install:
+            report.append({"name": "install", "status": "skipped", "detail": "--no-install"})
+        else:
+            use_uv = runner.has_uv()
+            setup = runner.run_setup(target, use_uv=use_uv)
+            if setup.returncode != 0:
+                report.append(
+                    {"name": "install", "status": "failed",
+                     "detail": (setup.stderr or setup.stdout).strip()[:300]}
+                )
+                will_launch = False
+            else:
+                report.append(
+                    {"name": "install", "status": "installed",
+                     "detail": "uv" if use_uv else "venv + pip"}
+                )
+
+        output.emit(report, lambda d: steps.render_steps(d), json_mode=json_mode)
+        if any(s["status"] == "failed" for s in report):
+            raise typer.Exit(code=1)
+
+        if will_launch:
+            chosen_port = runner.find_free_port(port)
+            url = f"http://localhost:{chosen_port}"
+            if not json_mode:
+                output.console.print(f"[aai.heading]Starting[/aai.heading] {escape(url)}  (Ctrl-C to stop)")
+            runner.launch_and_open(
+                target, port=chosen_port, use_uv=runner.has_uv(), open_browser=not no_open
+            )
+
+    run_command(ctx, body, json=json_out)
+```
+
+- [ ] **Step 4: Register the command in `main.py`**
+
+In `aai_cli/main.py`, add `init` to the imports:
+
+```python
+from aai_cli.commands import (
+    agent,
+    claude,
+    doctor,
+    init,
+    llm,
+    login,
+    samples,
+    stream,
+    transcribe,
+    transcripts,
+)
+```
+
+Add `"init"` to `_COMMAND_ORDER` (place it after `samples`, with tooling commands):
+
+```python
+_COMMAND_ORDER = (
+    "transcribe",
+    "stream",
+    "transcripts",
+    "agent",
+    "llm",
+    "login",
+    "logout",
+    "whoami",
+    "doctor",
+    "samples",
+    "init",
+    "claude",
+    "version",
+)
+```
+
+Register the typer app (near the other `add_typer` calls):
+
+```python
+app.add_typer(init.app, name="init")
+```
+
+- [ ] **Step 5: Re-export the public surface**
+
+```python
+# aai_cli/init/__init__.py
+from __future__ import annotations
+
+from aai_cli.init.keys import resolve_optional_api_key
+from aai_cli.init.scaffold import scaffold, target_conflict
+from aai_cli.init.templates import TEMPLATE_ORDER, TEMPLATES, is_template, title_for
+
+__all__ = [
+    "TEMPLATES",
+    "TEMPLATE_ORDER",
+    "is_template",
+    "title_for",
+    "scaffold",
+    "target_conflict",
+    "resolve_optional_api_key",
+]
+```
+
+- [ ] **Step 6: Run the tests to verify they pass**
+
+Run: `uv run pytest tests/test_init_command.py -v`
+Expected: PASS (9 tests).
+
+> If `app.add_typer(init.app, name="init")` plus `@app.callback(invoke_without_command=True)`
+> doesn't bind the positional `template`/`directory` arguments as expected, fall back to
+> registering `init` as a single `@app.command()` on a dedicated sub-typer (mirror how
+> `samples`/`claude` expose commands) — the test contract (args + flags + exit codes) is
+> what matters, not the registration mechanism.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add aai_cli/commands/init.py aai_cli/main.py aai_cli/init/__init__.py tests/test_init_command.py
+git commit -m "feat(init): wire init command (picker, scaffold, install, launch) + register"
+```
+
+---
+
+## Task 9: Full suite, lint, types, and README
+
+**Files:**
+- Modify: `README.md` (document `aai init`)
+- Test: full suite
+
+- [ ] **Step 1: Run the whole test suite**
+
+Run: `uv run pytest -q`
+Expected: PASS (all existing tests + the new `test_init_*` modules). Investigate and fix any regression before continuing.
+
+- [ ] **Step 2: Lint and type-check**
+
+Run: `uv run ruff check . && uv run ruff format --check . && uv run mypy`
+Expected: clean. Fix issues inline.
+
+> Likely ruff items: `S603`/`S607` (subprocess) are already ignored project-wide.
+> The `init` package may need `# noqa` only if a new lint surfaces — prefer fixing
+> over suppressing. The `importlib.resources` Traversable import may need the 3.10
+> fallback from Task 5.
+
+- [ ] **Step 3: Document the command in `README.md`**
+
+Add a short section after the Quick start (match the README's existing tone):
+
+````markdown
+## Scaffold a starter app
+
+```sh
+aai init                  # pick a template, scaffold it, install deps, open the browser
+aai init transcribe myapp # non-interactive: template + directory
+```
+
+`aai init` copies a small, self-contained FastAPI + HTML project you can run
+locally and deploy to Vercel as-is. Your key is written to a git-ignored `.env`
+(and is never sent to the browser). Use `--no-install` to scaffold only.
+````
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add README.md
+git commit -m "docs: document aai init"
+```
+
+---
+
+## Self-review (completed during planning)
+
+**Spec coverage (this plan's scope = machinery + transcribe):**
+- Command surface, options, default behavior → Task 8. ✓
+- Arrow-key picker + non-interactive fallback → Task 8 (`_pick_template`). ✓
+- Approach A (copy committed real templates) → Tasks 4, 5. ✓
+- Flat Vercel-ready layout (`api/index.py`, `index.html`, `vercel.json`) → Task 4. ✓
+- Key handling: env→keyring, gitignored `.env`, placeholder + skip-launch when absent, key never in browser → Tasks 3, 5, 8 + template design. ✓
+- Install/launch: uv→venv fallback, free-port, launch+open, Ctrl-C clean exit → Tasks 6, 8. ✓
+- Step-status rendering + `--json` → Tasks 7, 8. ✓
+- Packaging template files (incl. dotfiles) → Tasks 1, 4, 5. ✓
+- Testing approach (TestClient, mocked subprocess/SDK, no real network) → Tasks 4, 6, 8. ✓
+- `stream`/`agent`/`llm` templates → **out of scope; sibling plans** (stated up front). ✓ (intentional)
+
+**Placeholder scan:** none — every code/step block is concrete.
+
+**Type/name consistency:** `scaffold.scaffold(template, target, *, api_key)`, `scaffold.target_conflict`, `scaffold.PLACEHOLDER_KEY`, `runner.has_uv/venv_python/env_setup_commands/serve_command/find_free_port/run_setup/launch_and_open`, `steps.Step`/`steps.render_steps`, `templates.TEMPLATES/TEMPLATE_ORDER/is_template/title_for`, `keys.resolve_optional_api_key` — used consistently across tasks.

From b5419eba53d285f65c3edadfbc2c267f195e1c48 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:14:14 -0700
Subject: [PATCH 03/32] feat(init): add questionary dep + init package skeleton

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/init/__init__.py     |  1 +
 pyproject.toml               |  2 ++
 tests/test_init_packaging.py | 11 +++++++++++
 uv.lock                      | 35 +++++++++++++++++++++++++++++++++++
 4 files changed, 49 insertions(+)
 create mode 100644 aai_cli/init/__init__.py
 create mode 100644 tests/test_init_packaging.py

diff --git a/aai_cli/init/__init__.py b/aai_cli/init/__init__.py
new file mode 100644
index 00000000..9d48db4f
--- /dev/null
+++ b/aai_cli/init/__init__.py
@@ -0,0 +1 @@
+from __future__ import annotations
diff --git a/pyproject.toml b/pyproject.toml
index 2a2142a7..eca0ca60 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -38,6 +38,7 @@ dependencies = [
     "sounddevice>=0.5.5",
     "openai>=2.41.0",
     "yt-dlp>=2026.3.17",
+    "questionary>=2.0.1",
     # audioop (used for PCM resampling) left the stdlib in 3.13; this backport provides it.
     "audioop-lts>=0.2; python_version >= '3.13'",
 ]
@@ -62,6 +63,7 @@ aai = "aai_cli.main:run"
 
 [tool.hatch.build.targets.wheel]
 packages = ["aai_cli"]
+artifacts = ["aai_cli/init/templates/**"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
diff --git a/tests/test_init_packaging.py b/tests/test_init_packaging.py
new file mode 100644
index 00000000..34e83f5d
--- /dev/null
+++ b/tests/test_init_packaging.py
@@ -0,0 +1,11 @@
+import importlib
+
+
+def test_init_package_imports():
+    mod = importlib.import_module("aai_cli.init")
+    assert mod is not None
+
+
+def test_questionary_is_available():
+    # questionary is a runtime dependency of the CLI (the init picker).
+    assert importlib.import_module("questionary") is not None
diff --git a/uv.lock b/uv.lock
index 467b4b6e..dc0e183e 100644
--- a/uv.lock
+++ b/uv.lock
@@ -19,6 +19,7 @@ dependencies = [
     { name = "keyring" },
     { name = "openai" },
     { name = "platformdirs" },
+    { name = "questionary" },
     { name = "rich" },
     { name = "sounddevice" },
     { name = "tomli-w" },
@@ -50,6 +51,7 @@ requires-dist = [
     { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=4.6.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=7.1.0" },
+    { name = "questionary", specifier = ">=2.0.1" },
     { name = "rich", specifier = ">=15.0.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.15.15" },
     { name = "sounddevice", specifier = ">=0.5.5" },
@@ -1046,6 +1048,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/80/6e/4b28b62ecb6aae56769c34a8ff1d661473ec1e9519e2d5f8b2c150086b26/pre_commit-4.6.0-py2.py3-none-any.whl", hash = "sha256:e2cf246f7299edcabcf15f9b0571fdce06058527f0a06535068a86d38089f29b", size = 226472, upload-time = "2026-04-21T20:31:40.092Z" },
 ]
 
+[[package]]
+name = "prompt-toolkit"
+version = "3.0.52"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "wcwidth" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/a1/96/06e01a7b38dce6fe1db213e061a4602dd6032a8a97ef6c1a862537732421/prompt_toolkit-3.0.52.tar.gz", hash = "sha256:28cde192929c8e7321de85de1ddbe736f1375148b02f2e17edd840042b1be855", size = 434198, upload-time = "2025-08-27T15:24:02.057Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/84/03/0d3ce49e2505ae70cf43bc5bb3033955d2fc9f932163e84dc0779cc47f48/prompt_toolkit-3.0.52-py3-none-any.whl", hash = "sha256:9aac639a3bbd33284347de5ad8d68ecc044b91a762dc39b7c21095fcd6a19955", size = 391431, upload-time = "2025-08-27T15:23:59.498Z" },
+]
+
 [[package]]
 name = "pycparser"
 version = "3.0"
@@ -1336,6 +1350,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
 ]
 
+[[package]]
+name = "questionary"
+version = "2.1.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "prompt-toolkit" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/f6/45/eafb0bba0f9988f6a2520f9ca2df2c82ddfa8d67c95d6625452e97b204a5/questionary-2.1.1.tar.gz", hash = "sha256:3d7e980292bb0107abaa79c68dd3eee3c561b83a0f89ae482860b181c8bd412d", size = 25845, upload-time = "2025-08-28T19:00:20.851Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/3c/26/1062c7ec1b053db9e499b4d2d5bc231743201b74051c973dadeac80a8f43/questionary-2.1.1-py3-none-any.whl", hash = "sha256:a51af13f345f1cdea62347589fbb6df3b290306ab8930713bfae4d475a7d4a59", size = 36753, upload-time = "2025-08-28T19:00:19.56Z" },
+]
+
 [[package]]
 name = "rich"
 version = "15.0.0"
@@ -1557,6 +1583,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/f4/34/a9dbe051de88a63eb7408ea66630bac38e72f7f6077d4be58737106860d9/virtualenv-21.3.3-py3-none-any.whl", hash = "sha256:7d5987d8369e098e41406efb780a3d4ca79280097293899e351a6407ee153ab3", size = 7594554, upload-time = "2026-05-13T18:01:27.815Z" },
 ]
 
+[[package]]
+name = "wcwidth"
+version = "0.7.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/2c/ee/afaf0f85a9a18fe47a67f1e4422ed6cf1fe642f0ae0a2f81166231303c52/wcwidth-0.7.0.tar.gz", hash = "sha256:90e3a7ea092341c44b99562e75d09e4d5160fe7a3974c6fb842a101a95e7eed0", size = 182132, upload-time = "2026-05-02T16:04:12.653Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/41/52/e465037f5375f43533d1a80b6923955201596a99142ed524d77b571a1418/wcwidth-0.7.0-py3-none-any.whl", hash = "sha256:5d69154c429a82910e241c738cd0e2976fac8a2dd47a1a805f4afed1c0f136f2", size = 110825, upload-time = "2026-05-02T16:04:11.033Z" },
+]
+
 [[package]]
 name = "websockets"
 version = "16.0"

From c3b6d2e82e371f447bff2bbd7236721ee8758936 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:15:12 -0700
Subject: [PATCH 04/32] feat(init): template registry

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/init/templates.py    | 21 +++++++++++++++++++++
 tests/test_init_templates.py | 21 +++++++++++++++++++++
 2 files changed, 42 insertions(+)
 create mode 100644 aai_cli/init/templates.py
 create mode 100644 tests/test_init_templates.py

diff --git a/aai_cli/init/templates.py b/aai_cli/init/templates.py
new file mode 100644
index 00000000..f1ea7423
--- /dev/null
+++ b/aai_cli/init/templates.py
@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+# id -> human-facing title shown in the picker. Ids mirror the CLI's commands.
+TEMPLATES: dict[str, str] = {
+    "transcribe": "Transcribe & explore a file",
+    "stream": "Live captions (mic → browser)",
+    "agent": "Talk to a voice agent",
+    "llm": "Chat with your audio (LLM)",
+}
+
+# Display order for the picker and `--help`, matching the CLI's command order.
+TEMPLATE_ORDER: tuple[str, ...] = ("transcribe", "stream", "agent", "llm")
+
+
+def is_template(name: str) -> bool:
+    return name in TEMPLATES
+
+
+def title_for(name: str) -> str:
+    """The human title for a template id, or the raw id if unknown."""
+    return TEMPLATES.get(name, name)
diff --git a/tests/test_init_templates.py b/tests/test_init_templates.py
new file mode 100644
index 00000000..ebf708e0
--- /dev/null
+++ b/tests/test_init_templates.py
@@ -0,0 +1,21 @@
+from aai_cli.init import templates
+
+
+def test_all_four_template_ids_present():
+    assert set(templates.TEMPLATES) == {"transcribe", "stream", "agent", "llm"}
+
+
+def test_template_order_is_complete_and_stable():
+    # Display order mirrors the CLI's command order; every id appears exactly once.
+    assert templates.TEMPLATE_ORDER == ("transcribe", "stream", "agent", "llm")
+    assert set(templates.TEMPLATE_ORDER) == set(templates.TEMPLATES)
+
+
+def test_title_for_known_and_unknown():
+    assert "Transcribe" in templates.title_for("transcribe")
+    assert templates.title_for("nope") == "nope"  # falls back to the raw id
+
+
+def test_is_template():
+    assert templates.is_template("agent") is True
+    assert templates.is_template("nope") is False

From f01dcc00e698bbf919fc554dbfb2459ba1198079 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:16:04 -0700
Subject: [PATCH 05/32] feat(init): optional API-key resolution (no raise when
 absent)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/init/keys.py    | 16 ++++++++++++++++
 tests/test_init_keys.py | 17 +++++++++++++++++
 2 files changed, 33 insertions(+)
 create mode 100644 aai_cli/init/keys.py
 create mode 100644 tests/test_init_keys.py

diff --git a/aai_cli/init/keys.py b/aai_cli/init/keys.py
new file mode 100644
index 00000000..892c4604
--- /dev/null
+++ b/aai_cli/init/keys.py
@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from aai_cli import config
+from aai_cli.errors import NotAuthenticated
+
+
+def resolve_optional_api_key(*, profile: str | None) -> str | None:
+    """The CLI's key chain (env -> keyring), but None instead of raising when absent.
+
+    `aai init` scaffolds even without a key (writing a placeholder), so it must not
+    fail the way run commands do.
+    """
+    try:
+        return config.resolve_api_key(profile=profile)
+    except NotAuthenticated:
+        return None
diff --git a/tests/test_init_keys.py b/tests/test_init_keys.py
new file mode 100644
index 00000000..e471a502
--- /dev/null
+++ b/tests/test_init_keys.py
@@ -0,0 +1,17 @@
+from aai_cli import config
+from aai_cli.init import keys
+
+
+def test_resolves_from_env(monkeypatch):
+    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "env-key-123")
+    assert keys.resolve_optional_api_key(profile=None) == "env-key-123"
+
+
+def test_resolves_from_keyring(memory_keyring):
+    config.set_api_key("default", "stored-key-456")
+    assert keys.resolve_optional_api_key(profile=None) == "stored-key-456"
+
+
+def test_returns_none_when_absent():
+    # isolate_env strips the env var and memory_keyring starts empty.
+    assert keys.resolve_optional_api_key(profile=None) is None

From a0a42a890a5e75a3aa6c70961895ab0efc24a2e1 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:19:11 -0700
Subject: [PATCH 06/32] feat(init): transcribe template (FastAPI submit+poll,
 Vercel-ready)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                                    |  2 +
 aai_cli/init/templates/transcribe/README.md   | 25 ++++++
 .../init/templates/transcribe/api/index.py    | 59 ++++++++++++++
 aai_cli/init/templates/transcribe/env.example |  1 +
 aai_cli/init/templates/transcribe/gitignore   |  3 +
 aai_cli/init/templates/transcribe/index.html  | 81 +++++++++++++++++++
 .../templates/transcribe/requirements.txt     |  5 ++
 aai_cli/init/templates/transcribe/vercel.json |  6 ++
 pyproject.toml                                |  4 +
 tests/test_init_template_transcribe.py        | 72 +++++++++++++++++
 uv.lock                                       | 72 +++++++++++++++++
 11 files changed, 330 insertions(+)
 create mode 100644 aai_cli/init/templates/transcribe/README.md
 create mode 100644 aai_cli/init/templates/transcribe/api/index.py
 create mode 100644 aai_cli/init/templates/transcribe/env.example
 create mode 100644 aai_cli/init/templates/transcribe/gitignore
 create mode 100644 aai_cli/init/templates/transcribe/index.html
 create mode 100644 aai_cli/init/templates/transcribe/requirements.txt
 create mode 100644 aai_cli/init/templates/transcribe/vercel.json
 create mode 100644 tests/test_init_template_transcribe.py

diff --git a/.gitignore b/.gitignore
index fd4feafd..f676fdf4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -16,6 +16,8 @@ docs/
 
 # Local scratch scripts (often contain live keys)
 transcribe/
+# But do track the packaged template
+!aai_cli/init/templates/transcribe/
 
 # Wrong tool for this project (hatchling + uv); never commit a poetry lock
 poetry.lock
diff --git a/aai_cli/init/templates/transcribe/README.md b/aai_cli/init/templates/transcribe/README.md
new file mode 100644
index 00000000..039d29e2
--- /dev/null
+++ b/aai_cli/init/templates/transcribe/README.md
@@ -0,0 +1,25 @@
+# Transcribe & explore — AssemblyAI starter
+
+Upload an audio/video file and see the transcript with speaker labels, chapters,
+sentiment, entities, and highlights. Built with FastAPI + a single HTML page.
+
+## Run locally
+
+```sh
+uvicorn api.index:app --reload --port 3000
+# open http://localhost:3000
+```
+
+`ASSEMBLYAI_API_KEY` is read from `.env` (already created for you if you ran `aai init`).
+
+## Deploy to Vercel
+
+Push this folder to a Git repo and import it on Vercel. Set `ASSEMBLYAI_API_KEY`
+as a Vercel environment variable (the local `.env` is git-ignored and not deployed).
+No extra config — `vercel.json` routes the page and the `/api` function.
+
+## Ideas to extend
+
+- Show chapter summaries and highlight timestamps.
+- Add a waveform / audio player synced to the transcript.
+- Swap the analysis features in `CONFIG` (api/index.py).
diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/transcribe/api/index.py
new file mode 100644
index 00000000..c036ad04
--- /dev/null
+++ b/aai_cli/init/templates/transcribe/api/index.py
@@ -0,0 +1,59 @@
+"""Transcribe & explore — AssemblyAI starter (FastAPI).
+
+Two short endpoints so each request stays fast (serverless-friendly):
+  POST /api/transcribe  -> submit the upload, return {"id": ...}
+  GET  /api/status/{id} -> poll; returns the full transcript JSON when complete
+
+The browser (index.html) submits a file, then polls status until done.
+Your API key stays on the server — the browser never sees it.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+import uuid
+from pathlib import Path
+
+import assemblyai as aai
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException, UploadFile
+from fastapi.responses import FileResponse
+
+load_dotenv()
+aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY", "")
+
+# Audio-intelligence features to showcase. Tweak these — that's the point of a starter.
+CONFIG = aai.TranscriptionConfig(
+    speaker_labels=True,
+    auto_chapters=True,
+    sentiment_analysis=True,
+    entity_detection=True,
+    auto_highlights=True,
+)
+
+ROOT = Path(__file__).resolve().parent.parent
+app = FastAPI()
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(ROOT / "index.html")
+
+
+@app.post("/api/transcribe")
+async def transcribe(file: UploadFile) -> dict[str, str]:
+    suffix = Path(file.filename or "audio").suffix
+    tmp = Path(tempfile.gettempdir()) / f"aai-{uuid.uuid4().hex}{suffix}"
+    tmp.write_bytes(await file.read())
+    transcript = aai.Transcriber().submit(str(tmp), config=CONFIG)
+    return {"id": transcript.id}
+
+
+@app.get("/api/status/{transcript_id}")
+def status(transcript_id: str) -> dict[str, object]:
+    t = aai.Transcript.get_by_id(transcript_id)
+    if t.status == aai.TranscriptStatus.error:
+        raise HTTPException(status_code=502, detail=t.error or "Transcription failed")
+    if t.status == aai.TranscriptStatus.completed:
+        return {"status": "completed", "transcript": t.json_response}
+    return {"status": str(getattr(t.status, "value", t.status))}
diff --git a/aai_cli/init/templates/transcribe/env.example b/aai_cli/init/templates/transcribe/env.example
new file mode 100644
index 00000000..ae0847f2
--- /dev/null
+++ b/aai_cli/init/templates/transcribe/env.example
@@ -0,0 +1 @@
+ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
diff --git a/aai_cli/init/templates/transcribe/gitignore b/aai_cli/init/templates/transcribe/gitignore
new file mode 100644
index 00000000..5b01785a
--- /dev/null
+++ b/aai_cli/init/templates/transcribe/gitignore
@@ -0,0 +1,3 @@
+.env
+.venv
+__pycache__/
diff --git a/aai_cli/init/templates/transcribe/index.html b/aai_cli/init/templates/transcribe/index.html
new file mode 100644
index 00000000..b9d74ab3
--- /dev/null
+++ b/aai_cli/init/templates/transcribe/index.html
@@ -0,0 +1,81 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Transcribe &amp; explore · AssemblyAI</title>
+  <style>
+    body { font: 15px/1.6 system-ui, sans-serif; max-width: 760px; margin: 40px auto; padding: 0 16px; }
+    h1 { font-size: 20px; }
+    #drop { border: 2px dashed #bbb; border-radius: 10px; padding: 28px; text-align: center; cursor: pointer; }
+    #drop.busy { opacity: .6; pointer-events: none; }
+    .chips span { display: inline-block; background: #eef; border-radius: 99px; padding: 3px 10px; margin: 2px; font-size: 12px; }
+    .turn { margin: 6px 0; }
+    .spk { font-weight: 600; }
+    pre { white-space: pre-wrap; }
+  </style>
+</head>
+<body>
+  <h1>🎧 Transcribe &amp; explore</h1>
+  <p>Pick an audio or video file. The server transcribes it with AssemblyAI and returns speakers, chapters, sentiment, entities, and highlights.</p>
+
+  <label id="drop">
+    <input id="file" type="file" accept="audio/*,video/*" hidden />
+    <span id="droplabel">Click to choose a file</span>
+  </label>
+
+  <p id="status"></p>
+  <div id="result"></div>
+
+  <script>
+    const fileInput = document.getElementById("file");
+    const drop = document.getElementById("drop");
+    const statusEl = document.getElementById("status");
+    const result = document.getElementById("result");
+
+    drop.addEventListener("click", () => fileInput.click());
+    fileInput.addEventListener("change", () => fileInput.files[0] && upload(fileInput.files[0]));
+
+    async function upload(file) {
+      drop.classList.add("busy");
+      result.innerHTML = "";
+      statusEl.textContent = "Uploading…";
+      const body = new FormData();
+      body.append("file", file);
+      const res = await fetch("/api/transcribe", { method: "POST", body });
+      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
+      const { id } = await res.json();
+      poll(id);
+    }
+
+    async function poll(id) {
+      statusEl.textContent = "Transcribing…";
+      const res = await fetch("/api/status/" + id);
+      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
+      const data = await res.json();
+      if (data.status !== "completed") { setTimeout(() => poll(id), 2000); return; }
+      statusEl.textContent = "Done.";
+      drop.classList.remove("busy");
+      render(data.transcript);
+    }
+
+    function render(t) {
+      const chips = [];
+      if (t.chapters) chips.push("Chapters");
+      if (t.sentiment_analysis_results) chips.push("Sentiment");
+      if (t.entities) chips.push("Entities");
+      if (t.auto_highlights_result) chips.push("Highlights");
+      const utterances = (t.utterances || []).map(
+        (u) => `<div class="turn"><span class="spk">Speaker ${u.speaker}:</span> ${escapeHtml(u.text)}</div>`
+      ).join("");
+      result.innerHTML =
+        `<div class="chips">${chips.map((c) => `<span>${c}</span>`).join("")}</div>` +
+        (utterances || `<pre>${escapeHtml(t.text || "")}</pre>`);
+    }
+
+    function escapeHtml(s) {
+      return (s || "").replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
+    }
+  </script>
+</body>
+</html>
diff --git a/aai_cli/init/templates/transcribe/requirements.txt b/aai_cli/init/templates/transcribe/requirements.txt
new file mode 100644
index 00000000..38145aff
--- /dev/null
+++ b/aai_cli/init/templates/transcribe/requirements.txt
@@ -0,0 +1,5 @@
+fastapi
+uvicorn
+assemblyai
+python-dotenv
+python-multipart
diff --git a/aai_cli/init/templates/transcribe/vercel.json b/aai_cli/init/templates/transcribe/vercel.json
new file mode 100644
index 00000000..7f1e3652
--- /dev/null
+++ b/aai_cli/init/templates/transcribe/vercel.json
@@ -0,0 +1,6 @@
+{
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/index" },
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
diff --git a/pyproject.toml b/pyproject.toml
index eca0ca60..07eab844 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -56,6 +56,10 @@ dev = [
     "ruff>=0.15.15",
     "mypy>=2.1.0",
     "pre-commit>=4.6.0",
+    "fastapi>=0.115.0",
+    "uvicorn>=0.30.0",
+    "python-dotenv>=1.0.0",
+    "python-multipart>=0.0.9",
 ]
 
 [project.scripts]
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
new file mode 100644
index 00000000..789e7f70
--- /dev/null
+++ b/tests/test_init_template_transcribe.py
@@ -0,0 +1,72 @@
+import importlib.util
+import sys
+from pathlib import Path
+from unittest.mock import MagicMock
+
+import pytest
+from fastapi.testclient import TestClient
+
+TEMPLATE_DIR = Path("aai_cli/init/templates/transcribe")
+
+
+def _load_app(monkeypatch):
+    """Import the template's api/index.py as a module and return its FastAPI app.
+
+    The template is a standalone project (not part of aai_cli's import graph), so we
+    load it by file path. assemblyai is stubbed so no network/key is needed.
+    """
+    fake_aai = MagicMock()
+    fake_aai.TranscriptStatus.completed = "completed"
+    fake_aai.TranscriptStatus.error = "error"
+    submitted = MagicMock(id="t-123")
+    fake_aai.Transcriber.return_value.submit.return_value = submitted
+    done = MagicMock(status="completed", error=None,
+                     json_response={"text": "hello world", "utterances": []})
+    fake_aai.Transcript.get_by_id.return_value = done
+    monkeypatch.setitem(sys.modules, "assemblyai", fake_aai)
+
+    spec = importlib.util.spec_from_file_location(
+        "_tmpl_transcribe", TEMPLATE_DIR / "api" / "index.py"
+    )
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.app, fake_aai
+
+
+def test_required_files_exist():
+    for rel in ("api/index.py", "index.html", "vercel.json",
+                "requirements.txt", "README.md", "gitignore", "env.example"):
+        assert (TEMPLATE_DIR / rel).exists(), rel
+
+
+def test_template_ships_no_real_key():
+    # No committed file may contain a literal .env with a key; only env.example.
+    assert not (TEMPLATE_DIR / ".env").exists()
+    assert "your_assemblyai_api_key_here" in (TEMPLATE_DIR / "env.example").read_text()
+
+
+def test_index_route_serves_page(monkeypatch):
+    app, _ = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.get("/")
+    assert resp.status_code == 200
+    assert "<html" in resp.text.lower()
+
+
+def test_submit_returns_transcript_id(monkeypatch):
+    app, fake = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.post("/api/transcribe", files={"file": ("a.mp3", b"\x00\x01", "audio/mpeg")})
+    assert resp.status_code == 200
+    assert resp.json() == {"id": "t-123"}
+    fake.Transcriber.return_value.submit.assert_called_once()
+
+
+def test_status_returns_completed_transcript(monkeypatch):
+    app, _ = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.get("/api/status/t-123")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["status"] == "completed"
+    assert body["transcript"]["text"] == "hello world"
diff --git a/uv.lock b/uv.lock
index dc0e183e..da6fc03b 100644
--- a/uv.lock
+++ b/uv.lock
@@ -30,18 +30,23 @@ dependencies = [
 
 [package.optional-dependencies]
 dev = [
+    { name = "fastapi" },
     { name = "hypothesis" },
     { name = "mypy" },
     { name = "pre-commit" },
     { name = "pytest" },
     { name = "pytest-cov" },
+    { name = "python-dotenv" },
+    { name = "python-multipart" },
     { name = "ruff" },
+    { name = "uvicorn" },
 ]
 
 [package.metadata]
 requires-dist = [
     { name = "assemblyai", specifier = ">=0.64.4" },
     { name = "audioop-lts", marker = "python_full_version >= '3.13'", specifier = ">=0.2" },
+    { name = "fastapi", marker = "extra == 'dev'", specifier = ">=0.115.0" },
     { name = "httpx", specifier = ">=0.28.1" },
     { name = "hypothesis", marker = "extra == 'dev'", specifier = ">=6.155.1" },
     { name = "keyring", specifier = ">=25.7.0" },
@@ -51,12 +56,15 @@ requires-dist = [
     { name = "pre-commit", marker = "extra == 'dev'", specifier = ">=4.6.0" },
     { name = "pytest", marker = "extra == 'dev'", specifier = ">=9.0.3" },
     { name = "pytest-cov", marker = "extra == 'dev'", specifier = ">=7.1.0" },
+    { name = "python-dotenv", marker = "extra == 'dev'", specifier = ">=1.0.0" },
+    { name = "python-multipart", marker = "extra == 'dev'", specifier = ">=0.0.9" },
     { name = "questionary", specifier = ">=2.0.1" },
     { name = "rich", specifier = ">=15.0.0" },
     { name = "ruff", marker = "extra == 'dev'", specifier = ">=0.15.15" },
     { name = "sounddevice", specifier = ">=0.5.5" },
     { name = "tomli-w", specifier = ">=1.2.0" },
     { name = "typer", specifier = ">=0.26.7" },
+    { name = "uvicorn", marker = "extra == 'dev'", specifier = ">=0.30.0" },
     { name = "websockets", specifier = ">=16.0" },
     { name = "yt-dlp", specifier = ">=2026.3.17" },
 ]
@@ -315,6 +323,18 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/db/3c/33bac158f8ab7f89b2e59426d5fe2e4f63f7ed25df84c036890172b412b5/cfgv-3.5.0-py2.py3-none-any.whl", hash = "sha256:a8dc6b26ad22ff227d2634a65cb388215ce6cc96bbcc5cfde7641ae87e8dacc0", size = 7445, upload-time = "2025-11-19T20:55:50.744Z" },
 ]
 
+[[package]]
+name = "click"
+version = "8.4.1"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "colorama", marker = "sys_platform == 'win32'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/9b/98/518d8e5081007684232226f475082b30087d0f585e8457db087298259f49/click-8.4.1.tar.gz", hash = "sha256:918b5633eddf6b41c32d4f454bf0de810065c74e3f7dbf8ee5452f8be88d3e96", size = 353007, upload-time = "2026-05-22T04:08:37.769Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/c7/0d/67e5b4109ea4a837e80daa87c2c696711955e40449a97e8926672534def2/click-8.4.1-py3-none-any.whl", hash = "sha256:482be17c6991b8c19c5429a1e995d9b0efdbb63172824c41f99965dc0ade8ec2", size = 116639, upload-time = "2026-05-22T04:08:35.26Z" },
+]
+
 [[package]]
 name = "colorama"
 version = "0.4.6"
@@ -521,6 +541,22 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/8a/0e/97c33bf5009bdbac74fd2beace167cab3f978feb69cc36f1ef79360d6c4e/exceptiongroup-1.3.1-py3-none-any.whl", hash = "sha256:a7a39a3bd276781e98394987d3a5701d0c4edffb633bb7a5144577f82c773598", size = 16740, upload-time = "2025-11-21T23:01:53.443Z" },
 ]
 
+[[package]]
+name = "fastapi"
+version = "0.136.3"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "annotated-doc" },
+    { name = "pydantic" },
+    { name = "starlette" },
+    { name = "typing-extensions" },
+    { name = "typing-inspection" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/81/2d/ff8d91d7b564d464629a0fd50a4489c97fcb836ac230bf3a7269232a9b1f/fastapi-0.136.3.tar.gz", hash = "sha256:e487fae93ad408e6f47641ee4dfe389864fd7bec92e547ea8498fc13f43e83ab", size = 396410, upload-time = "2026-05-23T18:53:15.192Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/e0/82/45359b62a067409bd929ae8a56b8ed13e5a8c8a61194b3c236920999ab83/fastapi-0.136.3-py3-none-any.whl", hash = "sha256:3d2a69bdf04b7e9f3afa292c3bc7a98816bbfafa10bc9b45f3f3700d2f761620", size = 117481, upload-time = "2026-05-23T18:53:16.924Z" },
+]
+
 [[package]]
 name = "filelock"
 version = "3.29.0"
@@ -1277,6 +1313,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0b/d7/1959b9648791274998a9c3526f6d0ec8fd2233e4d4acce81bbae76b44b2a/python_dotenv-1.2.2-py3-none-any.whl", hash = "sha256:1d8214789a24de455a8b8bd8ae6fe3c6b69a5e3d64aa8a8e5d68e694bbcb285a", size = 22101, upload-time = "2026-03-01T16:00:25.09Z" },
 ]
 
+[[package]]
+name = "python-multipart"
+version = "0.0.29"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/4e/fe/70bd71a6738b09a0bdf6480ca6436b167469ca4578b2a0efbe390b4b0e70/python_multipart-0.0.29.tar.gz", hash = "sha256:643e93849196645e2dbdd81a0f8829a23123ad7f797a84a364c6fb3563f18904", size = 45678, upload-time = "2026-05-17T17:29:47.654Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/8f/cb/769cfc37177252872a45a71f3fbdde9d51b471a3f3c14bfe95dde3407386/python_multipart-0.0.29-py3-none-any.whl", hash = "sha256:2ddcc971cef266225f54f552d8fa10bcfbb1f14446caec199060daac59ff2d69", size = 29640, upload-time = "2026-05-17T17:29:45.69Z" },
+]
+
 [[package]]
 name = "pywin32-ctypes"
 version = "0.2.3"
@@ -1456,6 +1501,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/4e/39/a61d4b83a7746b70d23d9173be688c0c6bfc7173772344b7442c2c155497/sounddevice-0.5.5-py3-none-win_arm64.whl", hash = "sha256:3861901ddd8230d2e0e8ae62ac320cdd4c688d81df89da036dcb812f757bb3e6", size = 317115, upload-time = "2026-01-23T18:36:42.235Z" },
 ]
 
+[[package]]
+name = "starlette"
+version = "1.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "anyio" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/c5/bf/616a066c2760f6c2b1ae3437cc28149734d069fbb46511712beae118a68c/starlette-1.2.0.tar.gz", hash = "sha256:3c5a6b23fff42492914e93890bb80cbfea72dbf37de268eec06185d62a4ca553", size = 2668923, upload-time = "2026-05-28T11:42:50.568Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/9f/85/492183764d5d01d4514be3730fdb8e228a80605783099551c51627578b5d/starlette-1.2.0-py3-none-any.whl", hash = "sha256:36e0c76ac59157e75dc4b3bdeafba97fb04eaf1878045f15dbef666a6f092ed7", size = 73213, upload-time = "2026-05-28T11:42:48.801Z" },
+]
+
 [[package]]
 name = "tomli"
 version = "2.4.1"
@@ -1567,6 +1625,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/dc/9b/47798a6c91d8bdb567fe2698fe81e0c6b7cb7ef4d13da4114b41d239f65d/typing_inspection-0.4.2-py3-none-any.whl", hash = "sha256:4ed1cacbdc298c220f1bd249ed5287caa16f34d44ef4e9c3d0cbad5b521545e7", size = 14611, upload-time = "2025-10-01T02:14:40.154Z" },
 ]
 
+[[package]]
+name = "uvicorn"
+version = "0.48.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "h11" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/e6/bf/f6544ba992ddb9a6077343a576f9844f7f8f06ab819aefd00206e9255f18/uvicorn-0.48.0.tar.gz", hash = "sha256:a5504207195d08c2511bf9125ede5ac4a4b71725d519e758d01dcf0bc2d31c37", size = 91074, upload-time = "2026-05-24T12:08:41.925Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/01/be/72532be3da7acc5fdfbccdb95215cd04f995a0886532a5b423f929cda4cc/uvicorn-0.48.0-py3-none-any.whl", hash = "sha256:48097851328b87ec36117d3d575234519eb58c2b22d79666e9bbc6c49a761dad", size = 71410, upload-time = "2026-05-24T12:08:40.258Z" },
+]
+
 [[package]]
 name = "virtualenv"
 version = "21.3.3"

From 2355f63046b4c0b1213fd9c9d89f591f21cf2fc9 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:36:53 -0700
Subject: [PATCH 07/32] docs(plan): fix transcribe poll to non-blocking SDK
 call + add contract tests

Review found aai.Transcript.get_by_id() blocks (wait_for_completion), which
breaks the submit+poll design on serverless. Switch the status endpoint to
the SDK's non-blocking api.get_transcript, strengthen the transcribe tests,
and add a parametrized cross-template contract test (Task 10).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...2026-06-04-aai-init-core-and-transcribe.md | 164 ++++++++++++++++--
 1 file changed, 154 insertions(+), 10 deletions(-)

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index 59f7abd1..0a457697 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -315,17 +315,25 @@ def _load_app(monkeypatch):
     fake_aai.TranscriptStatus.error = "error"
     submitted = MagicMock(id="t-123")
     fake_aai.Transcriber.return_value.submit.return_value = submitted
-    done = MagicMock(status="completed", error=None,
-                     json_response={"text": "hello world", "utterances": []})
-    fake_aai.Transcript.get_by_id.return_value = done
+
+    # The template fetches status via the SDK's non-blocking api.get_transcript,
+    # so stub the assemblyai.api and assemblyai.client submodules too.
+    fake_api = MagicMock()
+    done = MagicMock(status="completed", error=None)
+    done.dict.return_value = {"text": "hello world", "utterances": []}
+    fake_api.get_transcript.return_value = done
+    fake_client = MagicMock()
+
     monkeypatch.setitem(sys.modules, "assemblyai", fake_aai)
+    monkeypatch.setitem(sys.modules, "assemblyai.api", fake_api)
+    monkeypatch.setitem(sys.modules, "assemblyai.client", fake_client)
 
     spec = importlib.util.spec_from_file_location(
         "_tmpl_transcribe", TEMPLATE_DIR / "api" / "index.py"
     )
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
-    return module.app, fake_aai
+    return module.app, fake_aai, fake_api
 
 
 def test_required_files_exist():
@@ -341,7 +349,7 @@ def test_template_ships_no_real_key():
 
 
 def test_index_route_serves_page(monkeypatch):
-    app, _ = _load_app(monkeypatch)
+    app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)
     resp = client.get("/")
     assert resp.status_code == 200
@@ -349,7 +357,7 @@ def test_index_route_serves_page(monkeypatch):
 
 
 def test_submit_returns_transcript_id(monkeypatch):
-    app, fake = _load_app(monkeypatch)
+    app, fake, _api = _load_app(monkeypatch)
     client = TestClient(app)
     resp = client.post("/api/transcribe", files={"file": ("a.mp3", b"\x00\x01", "audio/mpeg")})
     assert resp.status_code == 200
@@ -358,13 +366,33 @@ def test_submit_returns_transcript_id(monkeypatch):
 
 
 def test_status_returns_completed_transcript(monkeypatch):
-    app, _ = _load_app(monkeypatch)
+    app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)
     resp = client.get("/api/status/t-123")
     assert resp.status_code == 200
     body = resp.json()
     assert body["status"] == "completed"
     assert body["transcript"]["text"] == "hello world"
+
+
+def test_status_returns_processing_when_not_done(monkeypatch):
+    # A poll endpoint MUST report a non-terminal status without blocking. This guards
+    # against regressing to the blocking aai.Transcript.get_by_id() (which would only
+    # ever return completed/error, making this branch dead code).
+    app, _aai, fake_api = _load_app(monkeypatch)
+    fake_api.get_transcript.return_value = MagicMock(status="processing", error=None)
+    client = TestClient(app)
+    resp = client.get("/api/status/t-xyz")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "processing"}
+
+
+def test_status_returns_502_on_error(monkeypatch):
+    app, _aai, fake_api = _load_app(monkeypatch)
+    fake_api.get_transcript.return_value = MagicMock(status="error", error="bad audio")
+    client = TestClient(app)
+    resp = client.get("/api/status/t-bad")
+    assert resp.status_code == 502
 ```
 
 - [ ] **Step 2: Run test to verify it fails**
@@ -393,6 +421,8 @@ import uuid
 from pathlib import Path
 
 import assemblyai as aai
+from assemblyai.api import get_transcript  # single non-blocking GET (see status())
+from assemblyai.client import Client
 from dotenv import load_dotenv
 from fastapi import FastAPI, HTTPException, UploadFile
 from fastapi.responses import FileResponse
@@ -429,11 +459,15 @@ async def transcribe(file: UploadFile) -> dict[str, str]:
 
 @app.get("/api/status/{transcript_id}")
 def status(transcript_id: str) -> dict[str, object]:
-    t = aai.Transcript.get_by_id(transcript_id)
+    # One non-blocking GET. NOTE: aai.Transcript.get_by_id() BLOCKS until the job
+    # finishes (it calls wait_for_completion) — wrong for a poll endpoint, and it
+    # would time out on serverless. api.get_transcript does a single request and
+    # uses the SDK's configured client (auth + region from aai.settings).
+    t = get_transcript(Client.get_default().http_client, transcript_id)
     if t.status == aai.TranscriptStatus.error:
         raise HTTPException(status_code=502, detail=t.error or "Transcription failed")
     if t.status == aai.TranscriptStatus.completed:
-        return {"status": "completed", "transcript": t.json_response}
+        return {"status": "completed", "transcript": t.dict()}
     return {"status": str(getattr(t.status, "value", t.status))}
 ```
 
@@ -610,7 +644,7 @@ Then: `uv sync --extra dev`
 - [ ] **Step 7: Run the tests to verify they pass**
 
 Run: `uv run pytest tests/test_init_template_transcribe.py -v`
-Expected: PASS (5 tests).
+Expected: PASS (7 tests).
 
 - [ ] **Step 8: Commit**
 
@@ -1399,6 +1433,116 @@ git commit -m "docs: document aai init"
 
 ---
 
+## Task 10: Cross-template contract tests (keep every example working)
+
+**Files:**
+- Create: `tests/test_init_template_contract.py`
+
+**Why:** The templates are user-facing starter apps that drift from the SDK/API over
+time. A parametrized contract test — discovering every template directory on disk —
+catches the breakages a single smoke test misses, and **auto-covers the future
+`stream`/`agent`/`llm` templates** the moment their directories land. These are
+static-analysis checks (no app load, no network), so they're fast and robust.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/test_init_template_contract.py
+import ast
+import re
+from pathlib import Path
+
+import pytest
+
+TEMPLATES_ROOT = Path("aai_cli/init/templates")
+TEMPLATE_DIRS = sorted(
+    p for p in TEMPLATES_ROOT.iterdir() if p.is_dir() and not p.name.startswith("__")
+)
+# Map an import name to its PyPI distribution where they differ.
+_PKG_MAP = {"dotenv": "python-dotenv", "multipart": "python-multipart"}
+_STDLIB = {"os", "tempfile", "uuid", "pathlib", "__future__", "json", "typing"}
+
+
+@pytest.fixture(params=TEMPLATE_DIRS, ids=lambda p: p.name)
+def template_dir(request):
+    return request.param
+
+
+def test_required_files_present(template_dir):
+    for rel in ("api/index.py", "index.html", "vercel.json",
+                "requirements.txt", "README.md", "gitignore", "env.example"):
+        assert (template_dir / rel).exists(), f"{template_dir.name} missing {rel}"
+
+
+def test_no_committed_dotenv_or_real_key(template_dir):
+    assert not (template_dir / ".env").exists(), f"{template_dir.name} ships a real .env"
+    assert "your_assemblyai_api_key_here" in (template_dir / "env.example").read_text()
+
+
+def test_frontend_routes_exist_in_backend(template_dir):
+    """Every /api path the page fetches must be a route the backend registers."""
+    html = (template_dir / "index.html").read_text()
+    fetched = set(re.findall(r'fetch\(\s*["\'`](/api/[^"\'`?]+)', html))
+    # Also catch template-literal paths like fetch(`/api/status/${id}`) and "/api/x/" + id
+    fetched |= set(re.findall(r'["\'`](/api/[A-Za-z0-9_\-/]+?)(?:/?\$\{|/?["\'`]\s*\+)', html))
+    src = (template_dir / "api" / "index.py").read_text()
+    registered = set(re.findall(r'@app\.\w+\(\s*["\']([^"\']+)["\']', src))
+    registered_bases = {re.sub(r"/\{[^}]+\}$", "", r).rstrip("/") for r in registered}
+    for path in fetched:
+        base = path.rstrip("/")
+        assert any(base == r or base.startswith(r + "/") for r in registered_bases), (
+            f"{template_dir.name}: index.html fetches {path!r}, "
+            f"not registered in api/index.py (routes: {sorted(registered_bases)})"
+        )
+
+
+def test_requirements_cover_backend_imports(template_dir):
+    """Every third-party import in api/index.py appears in requirements.txt."""
+    tree = ast.parse((template_dir / "api" / "index.py").read_text())
+    imports: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imports.add(node.names[0].name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            imports.add(node.module.split(".")[0])
+    third_party = imports - _STDLIB
+    reqs = (template_dir / "requirements.txt").read_text().lower()
+    for pkg in third_party:
+        dist = _PKG_MAP.get(pkg, pkg)
+        assert dist in reqs, f"{template_dir.name}: import {pkg!r} ({dist}) missing from requirements.txt"
+
+
+def test_status_endpoint_does_not_block(template_dir):
+    """Guard against the blocking SDK call: a poll endpoint must not wait_for_completion."""
+    src = (template_dir / "api" / "index.py").read_text()
+    tree = ast.parse(src)
+    blocking = {"get_by_id", "wait_for_completion"}
+    called = {n.attr for n in ast.walk(tree) if isinstance(n, ast.Attribute)}
+    assert not (called & blocking), (
+        f"{template_dir.name}: uses blocking SDK call {called & blocking} — "
+        f"poll endpoints must do a single non-blocking fetch"
+    )
+```
+
+- [ ] **Step 2: Run test to verify it passes (transcribe already satisfies the contract)**
+
+Run: `uv run pytest tests/test_init_template_contract.py -v`
+Expected: PASS — 5 checks × however many templates exist (just `transcribe` for now).
+
+> If any check fails for `transcribe`, the contract found a real defect — fix the
+> template, not the test. (The route-regex and import-detection are intentionally
+> conservative; if a legitimate future template pattern trips them, widen the regex
+> rather than weakening the assertion.)
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add tests/test_init_template_contract.py
+git commit -m "test(init): parametrized template contract tests (keep examples working)"
+```
+
+---
+
 ## Self-review (completed during planning)
 
 **Spec coverage (this plan's scope = machinery + transcribe):**

From f7820132a4ede9e0c547c978b9c0febcabe8d7e7 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:38:07 -0700
Subject: [PATCH 08/32] fix(init): transcribe poll uses non-blocking SDK
 get_transcript

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../init/templates/transcribe/api/index.py    | 10 +++-
 tests/test_init_template_transcribe.py        | 46 +++++++++++++++----
 2 files changed, 44 insertions(+), 12 deletions(-)

diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/transcribe/api/index.py
index c036ad04..4ad53176 100644
--- a/aai_cli/init/templates/transcribe/api/index.py
+++ b/aai_cli/init/templates/transcribe/api/index.py
@@ -15,6 +15,8 @@
 from pathlib import Path
 
 import assemblyai as aai
+from assemblyai.api import get_transcript  # single non-blocking GET (see status())
+from assemblyai.client import Client
 from dotenv import load_dotenv
 from fastapi import FastAPI, HTTPException, UploadFile
 from fastapi.responses import FileResponse
@@ -51,9 +53,13 @@ async def transcribe(file: UploadFile) -> dict[str, str]:
 
 @app.get("/api/status/{transcript_id}")
 def status(transcript_id: str) -> dict[str, object]:
-    t = aai.Transcript.get_by_id(transcript_id)
+    # One non-blocking GET. NOTE: aai.Transcript.get_by_id() BLOCKS until the job
+    # finishes (it calls wait_for_completion) — wrong for a poll endpoint, and it
+    # would time out on serverless. api.get_transcript does a single request and
+    # uses the SDK's configured client (auth + region from aai.settings).
+    t = get_transcript(Client.get_default().http_client, transcript_id)
     if t.status == aai.TranscriptStatus.error:
         raise HTTPException(status_code=502, detail=t.error or "Transcription failed")
     if t.status == aai.TranscriptStatus.completed:
-        return {"status": "completed", "transcript": t.json_response}
+        return {"status": "completed", "transcript": t.dict()}
     return {"status": str(getattr(t.status, "value", t.status))}
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index 789e7f70..2f5f4c48 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -3,7 +3,6 @@
 from pathlib import Path
 from unittest.mock import MagicMock
 
-import pytest
 from fastapi.testclient import TestClient
 
 TEMPLATE_DIR = Path("aai_cli/init/templates/transcribe")
@@ -13,24 +12,32 @@ def _load_app(monkeypatch):
     """Import the template's api/index.py as a module and return its FastAPI app.
 
     The template is a standalone project (not part of aai_cli's import graph), so we
-    load it by file path. assemblyai is stubbed so no network/key is needed.
+    load it by file path. The assemblyai SDK is stubbed so no network/key is needed.
     """
     fake_aai = MagicMock()
     fake_aai.TranscriptStatus.completed = "completed"
     fake_aai.TranscriptStatus.error = "error"
     submitted = MagicMock(id="t-123")
     fake_aai.Transcriber.return_value.submit.return_value = submitted
-    done = MagicMock(status="completed", error=None,
-                     json_response={"text": "hello world", "utterances": []})
-    fake_aai.Transcript.get_by_id.return_value = done
+
+    # The template fetches status via the SDK's non-blocking api.get_transcript,
+    # so stub the assemblyai.api and assemblyai.client submodules too.
+    fake_api = MagicMock()
+    done = MagicMock(status="completed", error=None)
+    done.dict.return_value = {"text": "hello world", "utterances": []}
+    fake_api.get_transcript.return_value = done
+    fake_client = MagicMock()
+
     monkeypatch.setitem(sys.modules, "assemblyai", fake_aai)
+    monkeypatch.setitem(sys.modules, "assemblyai.api", fake_api)
+    monkeypatch.setitem(sys.modules, "assemblyai.client", fake_client)
 
     spec = importlib.util.spec_from_file_location(
         "_tmpl_transcribe", TEMPLATE_DIR / "api" / "index.py"
     )
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
-    return module.app, fake_aai
+    return module.app, fake_aai, fake_api
 
 
 def test_required_files_exist():
@@ -40,13 +47,12 @@ def test_required_files_exist():
 
 
 def test_template_ships_no_real_key():
-    # No committed file may contain a literal .env with a key; only env.example.
     assert not (TEMPLATE_DIR / ".env").exists()
     assert "your_assemblyai_api_key_here" in (TEMPLATE_DIR / "env.example").read_text()
 
 
 def test_index_route_serves_page(monkeypatch):
-    app, _ = _load_app(monkeypatch)
+    app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)
     resp = client.get("/")
     assert resp.status_code == 200
@@ -54,7 +60,7 @@ def test_index_route_serves_page(monkeypatch):
 
 
 def test_submit_returns_transcript_id(monkeypatch):
-    app, fake = _load_app(monkeypatch)
+    app, fake, _api = _load_app(monkeypatch)
     client = TestClient(app)
     resp = client.post("/api/transcribe", files={"file": ("a.mp3", b"\x00\x01", "audio/mpeg")})
     assert resp.status_code == 200
@@ -63,10 +69,30 @@ def test_submit_returns_transcript_id(monkeypatch):
 
 
 def test_status_returns_completed_transcript(monkeypatch):
-    app, _ = _load_app(monkeypatch)
+    app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)
     resp = client.get("/api/status/t-123")
     assert resp.status_code == 200
     body = resp.json()
     assert body["status"] == "completed"
     assert body["transcript"]["text"] == "hello world"
+
+
+def test_status_returns_processing_when_not_done(monkeypatch):
+    # A poll endpoint MUST report a non-terminal status without blocking. This guards
+    # against regressing to the blocking aai.Transcript.get_by_id() (which would only
+    # ever return completed/error, making this branch dead code).
+    app, _aai, fake_api = _load_app(monkeypatch)
+    fake_api.get_transcript.return_value = MagicMock(status="processing", error=None)
+    client = TestClient(app)
+    resp = client.get("/api/status/t-xyz")
+    assert resp.status_code == 200
+    assert resp.json() == {"status": "processing"}
+
+
+def test_status_returns_502_on_error(monkeypatch):
+    app, _aai, fake_api = _load_app(monkeypatch)
+    fake_api.get_transcript.return_value = MagicMock(status="error", error="bad audio")
+    client = TestClient(app)
+    resp = client.get("/api/status/t-bad")
+    assert resp.status_code == 502

From c9490a2cf783ff3688acf4c7a069c93339326c52 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:38:37 -0700
Subject: [PATCH 09/32] docs(plan): drop unused pytest import from transcribe
 test

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 specs/plans/2026-06-04-aai-init-core-and-transcribe.md | 1 -
 1 file changed, 1 deletion(-)

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index 0a457697..5288a45c 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -298,7 +298,6 @@ import sys
 from pathlib import Path
 from unittest.mock import MagicMock
 
-import pytest
 from fastapi.testclient import TestClient
 
 TEMPLATE_DIR = Path("aai_cli/init/templates/transcribe")

From 047e5472f8be76110a0c1b09964c06f51dbc58b6 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:39:50 -0700
Subject: [PATCH 10/32] docs(plan): scaffold skips __pycache__/.pyc + test for
 it

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../2026-06-04-aai-init-core-and-transcribe.md  | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index 5288a45c..f0605bc5 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -693,6 +693,15 @@ def test_scaffold_writes_env_with_key(tmp_path):
     assert "ASSEMBLYAI_API_KEY=sk-real-key" in env
 
 
+def test_scaffold_skips_pycache(tmp_path):
+    # Importing a template's api/index.py during our own test run leaves a
+    # __pycache__ next to it; the scaffolder must not copy that into the project.
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key=None)
+    assert not list(target.rglob("__pycache__"))
+    assert not list(target.rglob("*.pyc"))
+
+
 def test_scaffold_writes_placeholder_when_no_key(tmp_path):
     target = tmp_path / "app"
     scaffold.scaffold("transcribe", target, api_key=None)
@@ -739,6 +748,10 @@ PLACEHOLDER_KEY = "your_assemblyai_api_key_here"
 # Template files stored under plain names -> their real dotted names on copy.
 _DOTFILE_RENAMES = {"gitignore": ".gitignore", "env.example": ".env.example"}
 
+# Never copy build/test detritus into the user's fresh project. (Loading a template's
+# api/index.py during our own tests leaves a __pycache__ next to it.)
+_SKIP_NAMES = {"__pycache__"}
+
 
 def _template_root(template: str) -> Traversable:
     if not templates.is_template(template):
@@ -758,6 +771,8 @@ def target_conflict(target: Path) -> bool:
 
 def _copy_tree(node: Traversable, dest: Path) -> None:
     for child in node.iterdir():
+        if child.name in _SKIP_NAMES or child.name.endswith(".pyc"):
+            continue
         name = _DOTFILE_RENAMES.get(child.name, child.name)
         out = dest / name
         if child.is_dir():
@@ -789,7 +804,7 @@ def scaffold(template: str, target: Path, *, api_key: str | None) -> Path:
 - [ ] **Step 4: Run test to verify it passes**
 
 Run: `uv run pytest tests/test_init_scaffold.py -v`
-Expected: PASS (5 tests).
+Expected: PASS (6 tests).
 
 - [ ] **Step 5: Commit**
 

From f21e787961f374ddd1fca5026f85dd7cd17b5969 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:42:05 -0700
Subject: [PATCH 11/32] docs(plan): scaffold resolves templates via
 aai_cli.init package + TYPE_CHECKING Traversable

templates/ has no __init__.py so resources.files() must navigate from the
aai_cli.init package. Keep requires-python>=3.10 (TYPE_CHECKING import keeps
it clean). Verified runtime 3.11 + mypy --python-version 3.10.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...2026-06-04-aai-init-core-and-transcribe.md | 23 +++++++++++--------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index f0605bc5..b6b6a78b 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -737,12 +737,17 @@ Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.scaffold'
 from __future__ import annotations
 
 from importlib import resources
-from importlib.resources.abc import Traversable
 from pathlib import Path
+from typing import TYPE_CHECKING
 
 from aai_cli.errors import CLIError
 from aai_cli.init import templates
 
+if TYPE_CHECKING:
+    # Annotations only (PEP 563 strings), so no runtime import — `Traversable`'s
+    # module location differs across 3.10/3.11 but that never matters at runtime.
+    from importlib.resources.abc import Traversable
+
 PLACEHOLDER_KEY = "your_assemblyai_api_key_here"
 
 # Template files stored under plain names -> their real dotted names on copy.
@@ -761,7 +766,9 @@ def _template_root(template: str) -> Traversable:
             error_type="unknown_template",
             exit_code=1,
         )
-    return resources.files("aai_cli.init.templates") / template
+    # Navigate from the `aai_cli.init` package (templates/ has no __init__.py, so it
+    # is not itself an importable package).
+    return resources.files("aai_cli.init") / "templates" / template
 
 
 def target_conflict(target: Path) -> bool:
@@ -793,13 +800,11 @@ def scaffold(template: str, target: Path, *, api_key: str | None) -> Path:
     return target
 ```
 
-> Note on `from importlib.resources.abc import Traversable`: on Python 3.10 use `from importlib.abc import Traversable` instead. If supporting both, import defensively:
-> ```python
-> try:
->     from importlib.resources.abc import Traversable
-> except ImportError:  # Python 3.10
->     from importlib.abc import Traversable
-> ```
+> The `Traversable` import is under `TYPE_CHECKING` and used only in annotations
+> (which `from __future__ import annotations` keeps as strings), so it never runs at
+> runtime — that sidesteps its differing module location on 3.10 vs 3.11+. Verified:
+> `resources.files("aai_cli.init") / "templates" / <id>` works at runtime (3.11) and
+> `mypy --python-version 3.10` is clean.
 
 - [ ] **Step 4: Run test to verify it passes**
 

From 683a8f8fe89e0c2cf1ebefbbe37475f3e43c4d65 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:43:29 -0700
Subject: [PATCH 12/32] feat(init): scaffold (copy template tree + write .env)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/init/scaffold.py    | 65 +++++++++++++++++++++++++++++++++++++
 tests/test_init_scaffold.py | 57 ++++++++++++++++++++++++++++++++
 2 files changed, 122 insertions(+)
 create mode 100644 aai_cli/init/scaffold.py
 create mode 100644 tests/test_init_scaffold.py

diff --git a/aai_cli/init/scaffold.py b/aai_cli/init/scaffold.py
new file mode 100644
index 00000000..2113d391
--- /dev/null
+++ b/aai_cli/init/scaffold.py
@@ -0,0 +1,65 @@
+# aai_cli/init/scaffold.py
+from __future__ import annotations
+
+from importlib import resources
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from aai_cli.errors import CLIError
+from aai_cli.init import templates
+
+if TYPE_CHECKING:
+    # Annotations only (PEP 563 strings), so no runtime import — `Traversable`'s
+    # module location differs across 3.10/3.11 but that never matters at runtime.
+    from importlib.resources.abc import Traversable
+
+PLACEHOLDER_KEY = "your_assemblyai_api_key_here"
+
+# Template files stored under plain names -> their real dotted names on copy.
+_DOTFILE_RENAMES = {"gitignore": ".gitignore", "env.example": ".env.example"}
+
+# Never copy build/test detritus into the user's fresh project. (Loading a template's
+# api/index.py during our own tests leaves a __pycache__ next to it.)
+_SKIP_NAMES = {"__pycache__"}
+
+
+def _template_root(template: str) -> Traversable:
+    if not templates.is_template(template):
+        raise CLIError(
+            f"Unknown template {template!r}. Choose one of: "
+            f"{', '.join(templates.TEMPLATE_ORDER)}.",
+            error_type="unknown_template",
+            exit_code=1,
+        )
+    # Navigate from the `aai_cli.init` package (templates/ has no __init__.py, so it
+    # is not itself an importable package).
+    return resources.files("aai_cli.init") / "templates" / template
+
+
+def target_conflict(target: Path) -> bool:
+    """True when the target exists and is a non-empty directory."""
+    return target.is_dir() and any(target.iterdir())
+
+
+def _copy_tree(node: Traversable, dest: Path) -> None:
+    for child in node.iterdir():
+        if child.name in _SKIP_NAMES or child.name.endswith(".pyc"):
+            continue
+        name = _DOTFILE_RENAMES.get(child.name, child.name)
+        out = dest / name
+        if child.is_dir():
+            out.mkdir(parents=True, exist_ok=True)
+            _copy_tree(child, out)
+        else:
+            out.parent.mkdir(parents=True, exist_ok=True)
+            out.write_bytes(child.read_bytes())
+
+
+def scaffold(template: str, target: Path, *, api_key: str | None) -> Path:
+    """Copy the template into `target` and write `.env`. Returns `target`."""
+    root = _template_root(template)
+    target.mkdir(parents=True, exist_ok=True)
+    _copy_tree(root, target)
+    key = api_key or PLACEHOLDER_KEY
+    (target / ".env").write_text(f"ASSEMBLYAI_API_KEY={key}\n")
+    return target
diff --git a/tests/test_init_scaffold.py b/tests/test_init_scaffold.py
new file mode 100644
index 00000000..37c4112d
--- /dev/null
+++ b/tests/test_init_scaffold.py
@@ -0,0 +1,57 @@
+import pytest
+
+from aai_cli.errors import CLIError
+from aai_cli.init import scaffold
+
+
+def test_scaffold_copies_files_and_renames_dotfiles(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
+    assert (target / "api" / "index.py").exists()
+    assert (target / "index.html").exists()
+    assert (target / "vercel.json").exists()
+    # dotfile templates are renamed to their dotted names
+    assert (target / ".gitignore").exists()
+    assert (target / ".env.example").exists()
+    # the plain-named source files are NOT copied verbatim
+    assert not (target / "gitignore").exists()
+    assert not (target / "env.example").exists()
+
+
+def test_scaffold_writes_env_with_key(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
+    env = (target / ".env").read_text()
+    assert "ASSEMBLYAI_API_KEY=sk-real-key" in env
+
+
+def test_scaffold_skips_pycache(tmp_path):
+    # Importing a template's api/index.py during our own test run leaves a
+    # __pycache__ next to it; the scaffolder must not copy that into the project.
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key=None)
+    assert not list(target.rglob("__pycache__"))
+    assert not list(target.rglob("*.pyc"))
+
+
+def test_scaffold_writes_placeholder_when_no_key(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key=None)
+    env = (target / ".env").read_text()
+    assert scaffold.PLACEHOLDER_KEY in env
+
+
+def test_scaffold_unknown_template_raises(tmp_path):
+    with pytest.raises(CLIError):
+        scaffold.scaffold("nope", tmp_path / "app", api_key=None)
+
+
+def test_target_conflict_detects_nonempty_dir(tmp_path):
+    empty = tmp_path / "empty"
+    empty.mkdir()
+    assert scaffold.target_conflict(empty) is False
+    assert scaffold.target_conflict(tmp_path / "missing") is False
+    nonempty = tmp_path / "full"
+    nonempty.mkdir()
+    (nonempty / "x.txt").write_text("hi")
+    assert scaffold.target_conflict(nonempty) is True

From 8d9448f2e5e387b2cb13945a0b6f5e815d5dfea9 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:43:49 -0700
Subject: [PATCH 13/32] docs(plan): drop unused Path import from scaffold test

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 specs/plans/2026-06-04-aai-init-core-and-transcribe.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index b6b6a78b..a045090e 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -664,8 +664,6 @@ git commit -m "feat(init): transcribe template (FastAPI submit+poll, Vercel-read
 
 ```python
 # tests/test_init_scaffold.py
-from pathlib import Path
-
 import pytest
 
 from aai_cli.errors import CLIError

From c8bdda78b04e76d6600cb32e737f5c330c104d8a Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:44:37 -0700
Subject: [PATCH 14/32] docs(plan): runner run_setup avoids bare assert (ruff
 S101)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 specs/plans/2026-06-04-aai-init-core-and-transcribe.md | 3 +--
 1 file changed, 1 insertion(+), 2 deletions(-)

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index a045090e..788d1b2e 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -973,12 +973,11 @@ def wait_for_port(port: int, *, timeout: float = 30.0) -> bool:
 
 def run_setup(target: Path, *, use_uv: bool) -> subprocess.CompletedProcess:
     """Run env-setup commands in order; return the first failure or the last success."""
-    last: subprocess.CompletedProcess | None = None
+    last = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
     for cmd in env_setup_commands(target, use_uv=use_uv):
         last = subprocess.run(cmd, cwd=target, capture_output=True, text=True)
         if last.returncode != 0:
             return last
-    assert last is not None
     return last
 
 

From c11c13075480b4518556def63caa5f03ae56986a Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:45:49 -0700
Subject: [PATCH 15/32] feat(init): runner command builders + port/launch
 helpers

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/init/runner.py    | 91 +++++++++++++++++++++++++++++++++++++++
 tests/test_init_runner.py | 63 +++++++++++++++++++++++++++
 2 files changed, 154 insertions(+)
 create mode 100644 aai_cli/init/runner.py
 create mode 100644 tests/test_init_runner.py

diff --git a/aai_cli/init/runner.py b/aai_cli/init/runner.py
new file mode 100644
index 00000000..cf905d8e
--- /dev/null
+++ b/aai_cli/init/runner.py
@@ -0,0 +1,91 @@
+# aai_cli/init/runner.py
+from __future__ import annotations
+
+import os
+import shutil
+import socket
+import subprocess
+import sys
+import time
+import webbrowser
+from pathlib import Path
+
+
+def has_uv() -> bool:
+    return shutil.which("uv") is not None
+
+
+def venv_python(target: Path) -> Path:
+    if os.name == "nt":
+        return target / ".venv" / "Scripts" / "python.exe"
+    return target / ".venv" / "bin" / "python"
+
+
+def env_setup_commands(target: Path, *, use_uv: bool) -> list[list[str]]:
+    """Commands (run with cwd=target) to create a venv and install requirements."""
+    if use_uv:
+        return [["uv", "venv"], ["uv", "pip", "install", "-r", "requirements.txt"]]
+    py = str(venv_python(target))
+    return [
+        [sys.executable, "-m", "venv", ".venv"],
+        [py, "-m", "pip", "install", "-r", "requirements.txt"],
+    ]
+
+
+def serve_command(target: Path, *, port: int, use_uv: bool) -> list[str]:
+    if use_uv:
+        return ["uv", "run", "uvicorn", "api.index:app", "--port", str(port)]
+    return [str(venv_python(target)), "-m", "uvicorn", "api.index:app", "--port", str(port)]
+
+
+def _port_open(port: int) -> bool:
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+def find_free_port(preferred: int, *, tries: int = 20) -> int:
+    """The preferred port if free, else the next free port; OS-assigned when preferred is 0."""
+    if preferred == 0:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind(("127.0.0.1", 0))
+            return int(s.getsockname()[1])
+    for candidate in range(preferred, preferred + tries):
+        if not _port_open(candidate):
+            return candidate
+    return preferred
+
+
+def wait_for_port(port: int, *, timeout: float = 30.0) -> bool:
+    deadline = time.monotonic() + timeout
+    while time.monotonic() < deadline:
+        if _port_open(port):
+            return True
+        time.sleep(0.2)
+    return False
+
+
+def run_setup(target: Path, *, use_uv: bool) -> subprocess.CompletedProcess:
+    """Run env-setup commands in order; return the first failure or the last success."""
+    last = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
+    for cmd in env_setup_commands(target, use_uv=use_uv):
+        last = subprocess.run(cmd, cwd=target, capture_output=True, text=True)
+        if last.returncode != 0:
+            return last
+    return last
+
+
+def launch_and_open(target: Path, *, port: int, use_uv: bool, open_browser: bool) -> int:
+    """Start the dev server, wait for it, open the browser, and block until Ctrl-C.
+
+    Returns the process exit code (0 on a clean Ctrl-C shutdown).
+    """
+    proc = subprocess.Popen(serve_command(target, port=port, use_uv=use_uv), cwd=target)
+    try:
+        if wait_for_port(port) and open_browser:
+            webbrowser.open(f"http://localhost:{port}")
+        proc.wait()
+    except KeyboardInterrupt:
+        proc.terminate()
+        proc.wait()
+        return 0
+    return proc.returncode
diff --git a/tests/test_init_runner.py b/tests/test_init_runner.py
new file mode 100644
index 00000000..8091ef01
--- /dev/null
+++ b/tests/test_init_runner.py
@@ -0,0 +1,63 @@
+import socket
+import sys
+from pathlib import Path
+
+from aai_cli.init import runner
+
+
+def test_has_uv_reflects_path(monkeypatch):
+    monkeypatch.setattr(runner.shutil, "which", lambda name: "/usr/bin/uv")
+    assert runner.has_uv() is True
+    monkeypatch.setattr(runner.shutil, "which", lambda name: None)
+    assert runner.has_uv() is False
+
+
+def test_venv_python_path_per_platform(monkeypatch):
+    target = Path("/proj")
+    monkeypatch.setattr(runner.os, "name", "posix")
+    assert runner.venv_python(target) == target / ".venv" / "bin" / "python"
+    monkeypatch.setattr(runner.os, "name", "nt")
+    assert runner.venv_python(target) == target / ".venv" / "Scripts" / "python.exe"
+
+
+def test_env_setup_commands_uv():
+    cmds = runner.env_setup_commands(Path("/proj"), use_uv=True)
+    assert cmds == [["uv", "venv"], ["uv", "pip", "install", "-r", "requirements.txt"]]
+
+
+def test_env_setup_commands_venv():
+    target = Path("/proj")
+    cmds = runner.env_setup_commands(target, use_uv=False)
+    py = str(runner.venv_python(target))
+    assert cmds == [
+        [sys.executable, "-m", "venv", ".venv"],
+        [py, "-m", "pip", "install", "-r", "requirements.txt"],
+    ]
+
+
+def test_serve_command_uv_and_venv():
+    target = Path("/proj")
+    assert runner.serve_command(target, port=3000, use_uv=True) == [
+        "uv", "run", "uvicorn", "api.index:app", "--port", "3000",
+    ]
+    py = str(runner.venv_python(target))
+    assert runner.serve_command(target, port=3000, use_uv=False) == [
+        py, "-m", "uvicorn", "api.index:app", "--port", "3000",
+    ]
+
+
+def test_find_free_port_returns_preferred_when_open():
+    port = runner.find_free_port(0)  # 0 -> OS assigns a free port
+    assert isinstance(port, int) and port > 0
+
+
+def test_find_free_port_skips_taken_port():
+    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    s.bind(("127.0.0.1", 0))
+    taken = s.getsockname()[1]
+    s.listen(1)
+    try:
+        chosen = runner.find_free_port(taken)
+        assert chosen != taken
+    finally:
+        s.close()

From 889554dd26727bb9843136fe0ddfe91c22d5e9c4 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:47:19 -0700
Subject: [PATCH 16/32] feat(init): step-status rendering helper

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/init/steps.py    | 25 +++++++++++++++++++++++++
 tests/test_init_steps.py | 19 +++++++++++++++++++
 2 files changed, 44 insertions(+)
 create mode 100644 aai_cli/init/steps.py
 create mode 100644 tests/test_init_steps.py

diff --git a/aai_cli/init/steps.py b/aai_cli/init/steps.py
new file mode 100644
index 00000000..a1159c2f
--- /dev/null
+++ b/aai_cli/init/steps.py
@@ -0,0 +1,25 @@
+# aai_cli/init/steps.py
+from __future__ import annotations
+
+from typing import TypedDict
+
+from rich.markup import escape
+
+from aai_cli import theme
+
+
+class Step(TypedDict):
+    name: str
+    status: str
+    detail: str
+
+
+def render_steps(items: list[Step]) -> str:
+    lines = []
+    for s in items:
+        style = theme.status_style(s["status"])
+        lines.append(
+            f"  {escape(s['name'])}: "
+            f"[{style}]{escape(s['status'])}[/{style}] — {escape(s['detail'])}"
+        )
+    return "[aai.heading]aai init:[/aai.heading]\n" + "\n".join(lines)
diff --git a/tests/test_init_steps.py b/tests/test_init_steps.py
new file mode 100644
index 00000000..2be40d6a
--- /dev/null
+++ b/tests/test_init_steps.py
@@ -0,0 +1,19 @@
+from aai_cli.init import steps
+
+
+def test_render_steps_includes_name_status_detail():
+    data = [
+        {"name": "scaffold", "status": "created", "detail": "./my-app"},
+        {"name": "install", "status": "skipped", "detail": "--no-install"},
+    ]
+    out = steps.render_steps(data)
+    assert "scaffold" in out
+    assert "created" in out
+    assert "./my-app" in out
+    assert "install" in out
+    assert "skipped" in out
+
+
+def test_render_steps_has_heading():
+    out = steps.render_steps([{"name": "scaffold", "status": "created", "detail": "x"}])
+    assert "init" in out.lower() or "AssemblyAI" in out

From 413d4ae0c4096aa9a54b3865ca873d6d42ab16bc Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:53:51 -0700
Subject: [PATCH 17/32] docs(plan): init uses proven flat @app.command()
 registration (like transcribe)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...2026-06-04-aai-init-core-and-transcribe.md | 26 ++++++++++---------
 1 file changed, 14 insertions(+), 12 deletions(-)

diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index 788d1b2e..3ef3c44c 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -1204,10 +1204,10 @@ from aai_cli.context import AppState, run_command
 from aai_cli.errors import UsageError
 from aai_cli.init import keys, runner, scaffold, steps, templates
 
-app = typer.Typer(
-    help="Scaffold a runnable AssemblyAI web app and open it in your browser.",
-    no_args_is_help=False,  # bare `aai init` runs the interactive picker (or errors if no TTY)
-)
+# Single-command sub-typer flattened to `aai init` (the exact pattern `aai transcribe`
+# uses): one @app.command() named `init`, registered via app.add_typer(init.app) with
+# no name. Bare `aai init` runs the command with template=None -> the interactive picker.
+app = typer.Typer()
 
 
 def _pick_template() -> str:
@@ -1239,7 +1239,7 @@ def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
     return Path.cwd() / f"{template}-app"
 
 
-@app.callback(invoke_without_command=True)
+@app.command()
 def init(
     ctx: typer.Context,
     template: str = typer.Argument(None, help="Template id: transcribe, stream, agent, llm."),
@@ -1355,10 +1355,11 @@ _COMMAND_ORDER = (
 )
 ```
 
-Register the typer app (near the other `add_typer` calls):
+Register the typer app (near the other `add_typer` calls) — **no `name=`**, so the
+single `init` command flattens to `aai init` (same as `app.add_typer(transcribe.app)`):
 
 ```python
-app.add_typer(init.app, name="init")
+app.add_typer(init.app)
 ```
 
 - [ ] **Step 5: Re-export the public surface**
@@ -1387,11 +1388,12 @@ __all__ = [
 Run: `uv run pytest tests/test_init_command.py -v`
 Expected: PASS (9 tests).
 
-> If `app.add_typer(init.app, name="init")` plus `@app.callback(invoke_without_command=True)`
-> doesn't bind the positional `template`/`directory` arguments as expected, fall back to
-> registering `init` as a single `@app.command()` on a dedicated sub-typer (mirror how
-> `samples`/`claude` expose commands) — the test contract (args + flags + exit codes) is
-> what matters, not the registration mechanism.
+> This mirrors the verified `aai transcribe` registration (`typer.Typer()` + a single
+> `@app.command()` + `app.add_typer(...)` with no name), which renders as
+> `aai transcribe [OPTIONS] [SOURCE]` — a flat leaf command with positional args. So
+> `aai init [OPTIONS] [TEMPLATE] [DIRECTORY]` binds the positionals the same way; bare
+> `aai init` runs the command with `template=None` and falls into the picker (which
+> errors helpfully under CliRunner since there's no TTY).
 
 - [ ] **Step 7: Commit**
 

From 694ea3689d41e52d8240d5475879e98a64341c50 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 15:59:22 -0700
Subject: [PATCH 18/32] feat(init): wire init command (picker, scaffold,
 install, launch) + register

Adds `aai init [TEMPLATE] [DIRECTORY]` Typer command that scaffolds a project
from a template, optionally installs deps, launches the dev server, and opens
the browser; bare `aai init` with no TTY errors helpfully listing templates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py                      | 147 ++++++++++++++++++
 aai_cli/init/__init__.py                      |  16 ++
 aai_cli/init/scaffold.py                      |   3 +-
 .../init/templates/transcribe/api/index.py    |   1 +
 aai_cli/main.py                               |   3 +
 tests/test_init_command.py                    |  67 ++++++++
 tests/test_init_runner.py                     |  14 +-
 tests/test_init_template_transcribe.py        |  11 +-
 tests/test_smoke.py                           |   1 +
 9 files changed, 257 insertions(+), 6 deletions(-)
 create mode 100644 aai_cli/commands/init.py
 create mode 100644 tests/test_init_command.py

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
new file mode 100644
index 00000000..164f2c33
--- /dev/null
+++ b/aai_cli/commands/init.py
@@ -0,0 +1,147 @@
+# aai_cli/commands/init.py
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import typer
+from rich.markup import escape
+
+from aai_cli import output
+from aai_cli.context import AppState, run_command
+from aai_cli.errors import CLIError
+from aai_cli.init import keys, runner, steps, templates
+from aai_cli.init.scaffold import scaffold as _scaffold_fn
+from aai_cli.init.scaffold import target_conflict as _target_conflict
+
+# Single-command sub-typer flattened to `aai init` (the exact pattern `aai transcribe`
+# uses): one @app.command() named `init`, registered via app.add_typer(init.app) with
+# no name. Bare `aai init` runs the command with template=None -> the interactive picker.
+app = typer.Typer()
+
+
+def _pick_template() -> str:
+    """Interactive picker; raises UsageError when there's no TTY to prompt on."""
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        raise CLIError(
+            "No template given and not running interactively. "
+            f"Pass one of: {', '.join(templates.TEMPLATE_ORDER)}.",
+            error_type="usage_error",
+            exit_code=1,
+        )
+    import questionary
+
+    choice = questionary.select(
+        "Pick a template",
+        choices=[
+            questionary.Choice(title=templates.title_for(t), value=t)
+            for t in templates.TEMPLATE_ORDER
+        ],
+    ).ask()
+    if choice is None:  # user pressed Ctrl-C
+        raise typer.Exit(code=130)
+    return str(choice)
+
+
+def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
+    if here:
+        return Path.cwd()
+    if directory:
+        return Path(directory)
+    return Path.cwd() / f"{template}-app"
+
+
+@app.command()
+def init(
+    ctx: typer.Context,
+    template: str = typer.Argument(None, help="Template id: transcribe, stream, agent, llm."),
+    directory: str = typer.Argument(None, help="Target directory (default: <template>-app)."),
+    no_install: bool = typer.Option(
+        False, "--no-install", help="Scaffold only; don't install or launch."
+    ),
+    no_open: bool = typer.Option(
+        False, "--no-open", help="Install + launch, but don't open the browser."
+    ),
+    force: bool = typer.Option(False, "--force", help="Overwrite a non-empty target directory."),
+    here: bool = typer.Option(False, "--here", help="Scaffold into the current directory."),
+    port: int = typer.Option(3000, "--port", help="Local server port."),
+    json_out: bool = typer.Option(False, "--json", help="Output raw JSON."),
+) -> None:
+    """Pick a template, scaffold it, install deps, launch the server, open the browser."""
+
+    def body(state: AppState, json_mode: bool) -> None:
+        chosen = template
+        if chosen is None:
+            chosen = _pick_template()
+        if not templates.is_template(chosen):
+            raise CLIError(
+                f"Unknown template {chosen!r}. Choose one of: "
+                f"{', '.join(templates.TEMPLATE_ORDER)}.",
+                error_type="usage_error",
+                exit_code=1,
+            )
+
+        target = _resolve_dir(directory, chosen, here=here)
+        if _target_conflict(target) and not force:
+            raise CLIError(
+                f"{target} already exists and is not empty. "
+                f"Use --force to overwrite or pick another directory.",
+                error_type="usage_error",
+                exit_code=1,
+            )
+
+        api_key = keys.resolve_optional_api_key(profile=state.profile)
+        _scaffold_fn(chosen, target, api_key=api_key)
+
+        report: list[steps.Step] = [
+            {"name": "scaffold", "status": "created", "detail": str(target)}
+        ]
+        if api_key is None:
+            report.append(
+                {
+                    "name": "key",
+                    "status": "skipped",
+                    "detail": "no API key found; wrote a placeholder to .env (run `aai login`)",
+                }
+            )
+
+        will_launch = not no_install and api_key is not None
+        if no_install:
+            report.append({"name": "install", "status": "skipped", "detail": "--no-install"})
+        else:
+            use_uv = runner.has_uv()
+            setup = runner.run_setup(target, use_uv=use_uv)
+            if setup.returncode != 0:
+                report.append(
+                    {
+                        "name": "install",
+                        "status": "failed",
+                        "detail": (setup.stderr or setup.stdout).strip()[:300],
+                    }
+                )
+                will_launch = False
+            else:
+                report.append(
+                    {
+                        "name": "install",
+                        "status": "installed",
+                        "detail": "uv" if use_uv else "venv + pip",
+                    }
+                )
+
+        output.emit(report, lambda d: steps.render_steps(d), json_mode=json_mode)
+        if any(s["status"] == "failed" for s in report):
+            raise typer.Exit(code=1)
+
+        if will_launch:
+            chosen_port = runner.find_free_port(port)
+            url = f"http://localhost:{chosen_port}"
+            if not json_mode:
+                output.console.print(
+                    f"[aai.heading]Starting[/aai.heading] {escape(url)}  (Ctrl-C to stop)"
+                )
+            runner.launch_and_open(
+                target, port=chosen_port, use_uv=runner.has_uv(), open_browser=not no_open
+            )
+
+    run_command(ctx, body, json=json_out)
diff --git a/aai_cli/init/__init__.py b/aai_cli/init/__init__.py
index 9d48db4f..c4a2d372 100644
--- a/aai_cli/init/__init__.py
+++ b/aai_cli/init/__init__.py
@@ -1 +1,17 @@
+# aai_cli/init/__init__.py
 from __future__ import annotations
+
+from aai_cli.init.keys import resolve_optional_api_key
+from aai_cli.init.scaffold import scaffold as scaffold_fn
+from aai_cli.init.scaffold import target_conflict
+from aai_cli.init.templates import TEMPLATE_ORDER, TEMPLATES, is_template, title_for
+
+__all__ = [
+    "TEMPLATES",
+    "TEMPLATE_ORDER",
+    "is_template",
+    "resolve_optional_api_key",
+    "scaffold_fn",
+    "target_conflict",
+    "title_for",
+]
diff --git a/aai_cli/init/scaffold.py b/aai_cli/init/scaffold.py
index 2113d391..0707b7da 100644
--- a/aai_cli/init/scaffold.py
+++ b/aai_cli/init/scaffold.py
@@ -26,8 +26,7 @@
 def _template_root(template: str) -> Traversable:
     if not templates.is_template(template):
         raise CLIError(
-            f"Unknown template {template!r}. Choose one of: "
-            f"{', '.join(templates.TEMPLATE_ORDER)}.",
+            f"Unknown template {template!r}. Choose one of: {', '.join(templates.TEMPLATE_ORDER)}.",
             error_type="unknown_template",
             exit_code=1,
         )
diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/transcribe/api/index.py
index 4ad53176..7ef8bc84 100644
--- a/aai_cli/init/templates/transcribe/api/index.py
+++ b/aai_cli/init/templates/transcribe/api/index.py
@@ -7,6 +7,7 @@
 The browser (index.html) submits a file, then polls status until done.
 Your API key stays on the server — the browser never sees it.
 """
+
 from __future__ import annotations
 
 import os
diff --git a/aai_cli/main.py b/aai_cli/main.py
index d911812c..30026f35 100644
--- a/aai_cli/main.py
+++ b/aai_cli/main.py
@@ -16,6 +16,7 @@
     agent,
     claude,
     doctor,
+    init,
     llm,
     login,
     samples,
@@ -40,6 +41,7 @@
     "whoami",
     "doctor",
     "samples",
+    "init",
     "claude",
     "version",
 )
@@ -100,6 +102,7 @@ def main(
 app.add_typer(login.app)  # login, logout, whoami
 app.add_typer(doctor.app)
 app.add_typer(samples.app, name="samples")
+app.add_typer(init.app)
 app.add_typer(claude.app, name="claude")
 
 
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
new file mode 100644
index 00000000..83050f8e
--- /dev/null
+++ b/tests/test_init_command.py
@@ -0,0 +1,67 @@
+from typer.testing import CliRunner
+
+from aai_cli.main import app
+
+runner = CliRunner()
+
+
+def test_init_scaffold_only_creates_project(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / "myapp" / "api" / "index.py").exists()
+    assert (tmp_path / "myapp" / ".env").exists()
+
+
+def test_init_writes_key_from_env(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "sk-from-env")
+    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    assert "ASSEMBLYAI_API_KEY=sk-from-env" in (tmp_path / "myapp" / ".env").read_text()
+
+
+def test_init_placeholder_key_when_logged_out(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    env = (tmp_path / "myapp" / ".env").read_text()
+    assert "your_assemblyai_api_key_here" in env
+
+
+def test_init_unknown_template_errors(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "nope", "myapp", "--no-install"])
+    assert result.exit_code == 1
+
+
+def test_init_refuses_nonempty_dir_without_force(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"]).exit_code == 0
+    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    assert result.exit_code == 1
+
+
+def test_init_force_overwrites(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"]).exit_code == 0
+    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install", "--force"])
+    assert result.exit_code == 0
+
+
+def test_init_no_template_non_interactive_errors(tmp_path, monkeypatch):
+    # CliRunner has no TTY, so the picker can't run; bare `aai init` must error helpfully.
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init"])
+    assert result.exit_code != 0
+    assert "transcribe" in result.output  # lists the available templates
+
+
+def test_init_default_dir_is_template_app(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "transcribe", "--no-install"])
+    assert result.exit_code == 0, result.output
+    assert (tmp_path / "transcribe-app" / "api" / "index.py").exists()
+
+
+def test_init_appears_in_help():
+    result = runner.invoke(app, ["--help"])
+    assert "init" in result.output
diff --git a/tests/test_init_runner.py b/tests/test_init_runner.py
index 8091ef01..9e19a7be 100644
--- a/tests/test_init_runner.py
+++ b/tests/test_init_runner.py
@@ -38,11 +38,21 @@ def test_env_setup_commands_venv():
 def test_serve_command_uv_and_venv():
     target = Path("/proj")
     assert runner.serve_command(target, port=3000, use_uv=True) == [
-        "uv", "run", "uvicorn", "api.index:app", "--port", "3000",
+        "uv",
+        "run",
+        "uvicorn",
+        "api.index:app",
+        "--port",
+        "3000",
     ]
     py = str(runner.venv_python(target))
     assert runner.serve_command(target, port=3000, use_uv=False) == [
-        py, "-m", "uvicorn", "api.index:app", "--port", "3000",
+        py,
+        "-m",
+        "uvicorn",
+        "api.index:app",
+        "--port",
+        "3000",
     ]
 
 
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index 2f5f4c48..3065ec2a 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -41,8 +41,15 @@ def _load_app(monkeypatch):
 
 
 def test_required_files_exist():
-    for rel in ("api/index.py", "index.html", "vercel.json",
-                "requirements.txt", "README.md", "gitignore", "env.example"):
+    for rel in (
+        "api/index.py",
+        "index.html",
+        "vercel.json",
+        "requirements.txt",
+        "README.md",
+        "gitignore",
+        "env.example",
+    ):
         assert (TEMPLATE_DIR / rel).exists(), rel
 
 
diff --git a/tests/test_smoke.py b/tests/test_smoke.py
index a55891b5..10213deb 100644
--- a/tests/test_smoke.py
+++ b/tests/test_smoke.py
@@ -51,6 +51,7 @@ def test_help_lists_commands_in_workflow_order():
         "whoami",
         "doctor",
         "samples",
+        "init",
         "claude",
         "version",
     ]

From 77282849cd827570ede78b66e33464c35ee40ca4 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:01:23 -0700
Subject: [PATCH 19/32] refactor(init): use scaffold submodule directly; drop
 unused __init__ re-exports

The __init__ re-exports were unused and shadowed the scaffold submodule
(forcing a scaffold_fn alias). Import the scaffold module like the other
init submodules and keep __init__ minimal.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py |  8 +++-----
 aai_cli/init/__init__.py | 18 +++---------------
 2 files changed, 6 insertions(+), 20 deletions(-)

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index 164f2c33..3bd9702f 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -10,9 +10,7 @@
 from aai_cli import output
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import CLIError
-from aai_cli.init import keys, runner, steps, templates
-from aai_cli.init.scaffold import scaffold as _scaffold_fn
-from aai_cli.init.scaffold import target_conflict as _target_conflict
+from aai_cli.init import keys, runner, scaffold, steps, templates
 
 # Single-command sub-typer flattened to `aai init` (the exact pattern `aai transcribe`
 # uses): one @app.command() named `init`, registered via app.add_typer(init.app) with
@@ -82,7 +80,7 @@ def body(state: AppState, json_mode: bool) -> None:
             )
 
         target = _resolve_dir(directory, chosen, here=here)
-        if _target_conflict(target) and not force:
+        if scaffold.target_conflict(target) and not force:
             raise CLIError(
                 f"{target} already exists and is not empty. "
                 f"Use --force to overwrite or pick another directory.",
@@ -91,7 +89,7 @@ def body(state: AppState, json_mode: bool) -> None:
             )
 
         api_key = keys.resolve_optional_api_key(profile=state.profile)
-        _scaffold_fn(chosen, target, api_key=api_key)
+        scaffold.scaffold(chosen, target, api_key=api_key)
 
         report: list[steps.Step] = [
             {"name": "scaffold", "status": "created", "detail": str(target)}
diff --git a/aai_cli/init/__init__.py b/aai_cli/init/__init__.py
index c4a2d372..52e487a8 100644
--- a/aai_cli/init/__init__.py
+++ b/aai_cli/init/__init__.py
@@ -1,17 +1,5 @@
 # aai_cli/init/__init__.py
+# Submodules (templates, keys, scaffold, runner, steps) are imported directly by
+# consumers (e.g. `from aai_cli.init import scaffold`); re-exporting their members
+# here would shadow the same-named submodule (notably `scaffold`), so we don't.
 from __future__ import annotations
-
-from aai_cli.init.keys import resolve_optional_api_key
-from aai_cli.init.scaffold import scaffold as scaffold_fn
-from aai_cli.init.scaffold import target_conflict
-from aai_cli.init.templates import TEMPLATE_ORDER, TEMPLATES, is_template, title_for
-
-__all__ = [
-    "TEMPLATES",
-    "TEMPLATE_ORDER",
-    "is_template",
-    "resolve_optional_api_key",
-    "scaffold_fn",
-    "target_conflict",
-    "title_for",
-]

From 1f25a8cffe52c1ec22ae6be41dd966cfc5eedb41 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:02:29 -0700
Subject: [PATCH 20/32] docs(plan)+chore: align Task 8 with impl (CLIError exit
 1, minimal __init__, smoke)

Fix stale docstring; sync plan to the accepted deviations (CLIError exit_code=1
matching the samples convention, minimal init/__init__.py, test_smoke update).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py                      |  2 +-
 ...2026-06-04-aai-init-core-and-transcribe.md | 55 +++++++++++--------
 2 files changed, 33 insertions(+), 24 deletions(-)

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index 3bd9702f..4fb6746b 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -19,7 +19,7 @@
 
 
 def _pick_template() -> str:
-    """Interactive picker; raises UsageError when there's no TTY to prompt on."""
+    """Interactive picker; raises a usage error when there's no TTY to prompt on."""
     if not sys.stdin.isatty() or not sys.stdout.isatty():
         raise CLIError(
             "No template given and not running interactively. "
diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
index 3ef3c44c..8c9f79ca 100644
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
@@ -1201,7 +1201,7 @@ from rich.markup import escape
 
 from aai_cli import output
 from aai_cli.context import AppState, run_command
-from aai_cli.errors import UsageError
+from aai_cli.errors import CLIError
 from aai_cli.init import keys, runner, scaffold, steps, templates
 
 # Single-command sub-typer flattened to `aai init` (the exact pattern `aai transcribe`
@@ -1211,11 +1211,13 @@ app = typer.Typer()
 
 
 def _pick_template() -> str:
-    """Interactive picker; raises UsageError when there's no TTY to prompt on."""
+    """Interactive picker; raises a usage error when there's no TTY to prompt on."""
     if not sys.stdin.isatty() or not sys.stdout.isatty():
-        raise UsageError(
+        raise CLIError(
             "No template given and not running interactively. "
-            f"Pass one of: {', '.join(templates.TEMPLATE_ORDER)}."
+            f"Pass one of: {', '.join(templates.TEMPLATE_ORDER)}.",
+            error_type="usage_error",
+            exit_code=1,
         )
     import questionary
 
@@ -1258,16 +1260,20 @@ def init(
         if chosen is None:
             chosen = _pick_template()
         if not templates.is_template(chosen):
-            raise UsageError(
+            raise CLIError(
                 f"Unknown template {chosen!r}. Choose one of: "
-                f"{', '.join(templates.TEMPLATE_ORDER)}."
+                f"{', '.join(templates.TEMPLATE_ORDER)}.",
+                error_type="usage_error",
+                exit_code=1,
             )
 
         target = _resolve_dir(directory, chosen, here=here)
         if scaffold.target_conflict(target) and not force:
-            raise UsageError(
+            raise CLIError(
                 f"{target} already exists and is not empty. "
-                f"Use --force to overwrite or pick another directory."
+                f"Use --force to overwrite or pick another directory.",
+                error_type="usage_error",
+                exit_code=1,
             )
 
         api_key = keys.resolve_optional_api_key(profile=state.profile)
@@ -1362,27 +1368,30 @@ single `init` command flattens to `aai init` (same as `app.add_typer(transcribe.
 app.add_typer(init.app)
 ```
 
-- [ ] **Step 5: Re-export the public surface**
+If `tests/test_smoke.py` asserts the exact set/order of top-level commands, add
+`"init"` to that expected list too (placed after `samples`, matching `_COMMAND_ORDER`).
+
+- [ ] **Step 5: Keep `aai_cli/init/__init__.py` minimal**
+
+Do NOT re-export submodule members from the package `__init__`. Consumers import the
+submodules directly (`from aai_cli.init import scaffold` → the module, then
+`scaffold.scaffold(...)`), and re-exporting a function named `scaffold` here would
+shadow the `scaffold` submodule. Leave `__init__.py` as the minimal marker created in
+Task 1:
 
 ```python
 # aai_cli/init/__init__.py
+# Submodules (templates, keys, scaffold, runner, steps) are imported directly by
+# consumers (e.g. `from aai_cli.init import scaffold`); re-exporting their members
+# here would shadow the same-named submodule (notably `scaffold`), so we don't.
 from __future__ import annotations
-
-from aai_cli.init.keys import resolve_optional_api_key
-from aai_cli.init.scaffold import scaffold, target_conflict
-from aai_cli.init.templates import TEMPLATE_ORDER, TEMPLATES, is_template, title_for
-
-__all__ = [
-    "TEMPLATES",
-    "TEMPLATE_ORDER",
-    "is_template",
-    "title_for",
-    "scaffold",
-    "target_conflict",
-    "resolve_optional_api_key",
-]
 ```
 
+> Note on error type: these raises use `CLIError(error_type="usage_error", exit_code=1)`
+> rather than `UsageError` (which forces exit code 2). Exit code **1** matches the
+> existing `aai samples` scaffolder's convention for "unknown name"/"file exists" and
+> the test assertions. `run_command` renders any `CLIError` cleanly.
+
 - [ ] **Step 6: Run the tests to verify they pass**
 
 Run: `uv run pytest tests/test_init_command.py -v`

From ca2c9c5b700a723b3175ad061602af89062a52de Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:04:17 -0700
Subject: [PATCH 21/32] test(init): parametrized template contract tests (keep
 examples working)

Per Daisy's request: discover every template dir and assert required files,
no committed key, front/back route agreement, requirements cover imports,
and no blocking SDK call. Auto-covers future stream/agent/llm templates.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 tests/test_init_template_contract.py | 74 ++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 tests/test_init_template_contract.py

diff --git a/tests/test_init_template_contract.py b/tests/test_init_template_contract.py
new file mode 100644
index 00000000..f77df25f
--- /dev/null
+++ b/tests/test_init_template_contract.py
@@ -0,0 +1,74 @@
+import ast
+import re
+from pathlib import Path
+
+import pytest
+
+TEMPLATES_ROOT = Path("aai_cli/init/templates")
+TEMPLATE_DIRS = sorted(
+    p for p in TEMPLATES_ROOT.iterdir() if p.is_dir() and not p.name.startswith("__")
+)
+# Map an import name to its PyPI distribution where they differ.
+_PKG_MAP = {"dotenv": "python-dotenv", "multipart": "python-multipart"}
+_STDLIB = {"os", "tempfile", "uuid", "pathlib", "__future__", "json", "typing"}
+
+
+@pytest.fixture(params=TEMPLATE_DIRS, ids=lambda p: p.name)
+def template_dir(request):
+    return request.param
+
+
+def test_required_files_present(template_dir):
+    for rel in ("api/index.py", "index.html", "vercel.json",
+                "requirements.txt", "README.md", "gitignore", "env.example"):
+        assert (template_dir / rel).exists(), f"{template_dir.name} missing {rel}"
+
+
+def test_no_committed_dotenv_or_real_key(template_dir):
+    assert not (template_dir / ".env").exists(), f"{template_dir.name} ships a real .env"
+    assert "your_assemblyai_api_key_here" in (template_dir / "env.example").read_text()
+
+
+def test_frontend_routes_exist_in_backend(template_dir):
+    """Every /api path the page fetches must be a route the backend registers."""
+    html = (template_dir / "index.html").read_text()
+    fetched = set(re.findall(r'fetch\(\s*["\'`](/api/[^"\'`?]+)', html))
+    # Also catch template-literal paths like fetch(`/api/status/${id}`) and "/api/x/" + id
+    fetched |= set(re.findall(r'["\'`](/api/[A-Za-z0-9_\-/]+?)(?:/?\$\{|/?["\'`]\s*\+)', html))
+    src = (template_dir / "api" / "index.py").read_text()
+    registered = set(re.findall(r'@app\.\w+\(\s*["\']([^"\']+)["\']', src))
+    registered_bases = {re.sub(r"/\{[^}]+\}$", "", r).rstrip("/") for r in registered}
+    for path in fetched:
+        base = path.rstrip("/")
+        assert any(base == r or base.startswith(r + "/") for r in registered_bases), (
+            f"{template_dir.name}: index.html fetches {path!r}, "
+            f"not registered in api/index.py (routes: {sorted(registered_bases)})"
+        )
+
+
+def test_requirements_cover_backend_imports(template_dir):
+    """Every third-party import in api/index.py appears in requirements.txt."""
+    tree = ast.parse((template_dir / "api" / "index.py").read_text())
+    imports: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imports.add(node.names[0].name.split(".")[0])
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
+            imports.add(node.module.split(".")[0])
+    third_party = imports - _STDLIB
+    reqs = (template_dir / "requirements.txt").read_text().lower()
+    for pkg in third_party:
+        dist = _PKG_MAP.get(pkg, pkg)
+        assert dist in reqs, f"{template_dir.name}: import {pkg!r} ({dist}) missing from requirements.txt"
+
+
+def test_status_endpoint_does_not_block(template_dir):
+    """Guard against the blocking SDK call: a poll endpoint must not wait_for_completion."""
+    src = (template_dir / "api" / "index.py").read_text()
+    tree = ast.parse(src)
+    blocking = {"get_by_id", "wait_for_completion"}
+    called = {n.attr for n in ast.walk(tree) if isinstance(n, ast.Attribute)}
+    assert not (called & blocking), (
+        f"{template_dir.name}: uses blocking SDK call {called & blocking} — "
+        f"poll endpoints must do a single non-blocking fetch"
+    )

From 1e69b0efb35aec05487496c99abc3faeb2a780b4 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:05:11 -0700
Subject: [PATCH 22/32] docs: document aai init in README; ruff-format contract
 test

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md                            | 11 +++++++++++
 tests/test_init_template_contract.py | 15 ++++++++++++---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index cb099db2..65513843 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,17 @@ aai login                 # store your API key (browser-assisted)
 aai transcribe --sample   # transcribe the hosted wildfires.mp3 sample
 ```
 
+## Scaffold a starter app
+
+```sh
+aai init                   # pick a template, scaffold it, install deps, open the browser
+aai init transcribe myapp  # non-interactive: template + directory
+```
+
+`aai init` copies a small, self-contained FastAPI + HTML project you can run locally
+and deploy to Vercel as-is. Your key is written to a git-ignored `.env` (and is never
+sent to the browser). Use `--no-install` to scaffold only.
+
 ## API key & security
 
 `aai` resolves your key in this order:
diff --git a/tests/test_init_template_contract.py b/tests/test_init_template_contract.py
index f77df25f..c64dc08b 100644
--- a/tests/test_init_template_contract.py
+++ b/tests/test_init_template_contract.py
@@ -19,8 +19,15 @@ def template_dir(request):
 
 
 def test_required_files_present(template_dir):
-    for rel in ("api/index.py", "index.html", "vercel.json",
-                "requirements.txt", "README.md", "gitignore", "env.example"):
+    for rel in (
+        "api/index.py",
+        "index.html",
+        "vercel.json",
+        "requirements.txt",
+        "README.md",
+        "gitignore",
+        "env.example",
+    ):
         assert (template_dir / rel).exists(), f"{template_dir.name} missing {rel}"
 
 
@@ -59,7 +66,9 @@ def test_requirements_cover_backend_imports(template_dir):
     reqs = (template_dir / "requirements.txt").read_text().lower()
     for pkg in third_party:
         dist = _PKG_MAP.get(pkg, pkg)
-        assert dist in reqs, f"{template_dir.name}: import {pkg!r} ({dist}) missing from requirements.txt"
+        assert dist in reqs, (
+            f"{template_dir.name}: import {pkg!r} ({dist}) missing from requirements.txt"
+        )
 
 
 def test_status_endpoint_does_not_block(template_dir):

From 7b98d542b7e37521af3b3f28d57b983233ff8fcb Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:30:14 -0700
Subject: [PATCH 23/32] fix(init): only register shipped templates; harden
 picker/runner/launch

Final-review fixes:
- Registry lists only the transcribe template that actually ships; picking an
  unshipped id now gives a clean error instead of FileNotFoundError. A test
  enforces registry == on-disk template dirs (auto-extends as templates land).
- scaffold._template_root guards a missing dir defensively.
- _pick_template gives a clean message if questionary is missing (stale install)
  instead of a raw ModuleNotFoundError traceback.
- find_free_port raises instead of returning an occupied port when exhausted.
- init propagates the dev-server exit code; rejects DIRECTORY + --here together.
- theme: 'created' renders as success (green).
- Tests for --here, --json, unshipped-template error.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py     | 21 +++++++++++++++++++--
 aai_cli/init/runner.py       |  9 ++++++++-
 aai_cli/init/scaffold.py     | 12 +++++++++++-
 aai_cli/init/templates.py    | 13 ++++++++-----
 aai_cli/theme.py             |  2 +-
 tests/test_init_command.py   | 36 ++++++++++++++++++++++++++++++++++++
 tests/test_init_templates.py | 26 ++++++++++++++++++++------
 7 files changed, 103 insertions(+), 16 deletions(-)

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index 4fb6746b..623cd78c 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -27,7 +27,16 @@ def _pick_template() -> str:
             error_type="usage_error",
             exit_code=1,
         )
-    import questionary
+    try:
+        import questionary
+    except ImportError as exc:  # a broken/stale install missing the declared dep
+        raise CLIError(
+            "The interactive picker needs 'questionary'. Reinstall the CLI "
+            "(e.g. `uv tool install --reinstall aai-cli`), or pass a template "
+            f"directly: {', '.join(templates.TEMPLATE_ORDER)}.",
+            error_type="missing_dependency",
+            exit_code=1,
+        ) from exc
 
     choice = questionary.select(
         "Pick a template",
@@ -79,6 +88,12 @@ def body(state: AppState, json_mode: bool) -> None:
                 exit_code=1,
             )
 
+        if here and directory:
+            raise CLIError(
+                "Pass either a DIRECTORY or --here, not both.",
+                error_type="usage_error",
+                exit_code=1,
+            )
         target = _resolve_dir(directory, chosen, here=here)
         if scaffold.target_conflict(target) and not force:
             raise CLIError(
@@ -138,8 +153,10 @@ def body(state: AppState, json_mode: bool) -> None:
                 output.console.print(
                     f"[aai.heading]Starting[/aai.heading] {escape(url)}  (Ctrl-C to stop)"
                 )
-            runner.launch_and_open(
+            code = runner.launch_and_open(
                 target, port=chosen_port, use_uv=runner.has_uv(), open_browser=not no_open
             )
+            if code:
+                raise typer.Exit(code=code)
 
     run_command(ctx, body, json=json_out)
diff --git a/aai_cli/init/runner.py b/aai_cli/init/runner.py
index cf905d8e..9e3f4eda 100644
--- a/aai_cli/init/runner.py
+++ b/aai_cli/init/runner.py
@@ -10,6 +10,8 @@
 import webbrowser
 from pathlib import Path
 
+from aai_cli.errors import CLIError
+
 
 def has_uv() -> bool:
     return shutil.which("uv") is not None
@@ -52,7 +54,12 @@ def find_free_port(preferred: int, *, tries: int = 20) -> int:
     for candidate in range(preferred, preferred + tries):
         if not _port_open(candidate):
             return candidate
-    return preferred
+    raise CLIError(
+        f"No free port found in {preferred}-{preferred + tries - 1}. "
+        "Pass --port to choose another.",
+        error_type="port_unavailable",
+        exit_code=1,
+    )
 
 
 def wait_for_port(port: int, *, timeout: float = 30.0) -> bool:
diff --git a/aai_cli/init/scaffold.py b/aai_cli/init/scaffold.py
index 0707b7da..9eae3190 100644
--- a/aai_cli/init/scaffold.py
+++ b/aai_cli/init/scaffold.py
@@ -32,7 +32,17 @@ def _template_root(template: str) -> Traversable:
         )
     # Navigate from the `aai_cli.init` package (templates/ has no __init__.py, so it
     # is not itself an importable package).
-    return resources.files("aai_cli.init") / "templates" / template
+    root = resources.files("aai_cli.init") / "templates" / template
+    # Defense in depth: the registry should only list shipped templates, but if it ever
+    # drifts ahead of the on-disk directories, fail cleanly instead of with a traceback.
+    if not root.is_dir():
+        raise CLIError(
+            f"Template {template!r} is registered but its files are missing. "
+            "This is a packaging bug — please report it.",
+            error_type="template_missing",
+            exit_code=1,
+        )
+    return root
 
 
 def target_conflict(target: Path) -> bool:
diff --git a/aai_cli/init/templates.py b/aai_cli/init/templates.py
index f1ea7423..a3fad13d 100644
--- a/aai_cli/init/templates.py
+++ b/aai_cli/init/templates.py
@@ -1,15 +1,18 @@
 from __future__ import annotations
 
 # id -> human-facing title shown in the picker. Ids mirror the CLI's commands.
+#
+# Only list templates whose directory actually ships under templates/<id>/ — the
+# picker must never advertise a template that would crash on scaffold. The design
+# covers four (transcribe, stream, agent, llm); the latter three are added here as
+# their template directories land in follow-on PRs. A test enforces registry ==
+# shipped directories.
 TEMPLATES: dict[str, str] = {
     "transcribe": "Transcribe & explore a file",
-    "stream": "Live captions (mic → browser)",
-    "agent": "Talk to a voice agent",
-    "llm": "Chat with your audio (LLM)",
 }
 
-# Display order for the picker and `--help`, matching the CLI's command order.
-TEMPLATE_ORDER: tuple[str, ...] = ("transcribe", "stream", "agent", "llm")
+# Display order for the picker and `--help`.
+TEMPLATE_ORDER: tuple[str, ...] = ("transcribe",)
 
 
 def is_template(name: str) -> bool:
diff --git a/aai_cli/theme.py b/aai_cli/theme.py
index 8b7654d8..b29847cc 100644
--- a/aai_cli/theme.py
+++ b/aai_cli/theme.py
@@ -39,7 +39,7 @@
 )
 
 # Status strings grouped by the semantic style they render in.
-_SUCCESS = {"completed", "installed", "removed", "ok", "present", "authenticated"}
+_SUCCESS = {"completed", "installed", "removed", "ok", "present", "authenticated", "created"}
 _ERROR = {"error", "failed"}
 _WARN = {"queued", "processing", "in_progress", "running"}
 
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
index 83050f8e..ced95ad8 100644
--- a/tests/test_init_command.py
+++ b/tests/test_init_command.py
@@ -65,3 +65,39 @@ def test_init_default_dir_is_template_app(tmp_path, monkeypatch):
 def test_init_appears_in_help():
     result = runner.invoke(app, ["--help"])
     assert "init" in result.output
+
+
+def test_init_here_scaffolds_into_cwd(tmp_path, monkeypatch):
+    work = tmp_path / "work"  # a fresh empty dir (tmp_path itself holds the test config/)
+    work.mkdir()
+    monkeypatch.chdir(work)
+    result = runner.invoke(app, ["init", "transcribe", "--here", "--no-install"])
+    assert result.exit_code == 0, result.output
+    assert (work / "api" / "index.py").exists()  # scaffolded into cwd, no subdir
+
+
+def test_init_here_with_directory_errors(tmp_path, monkeypatch):
+    work = tmp_path / "work"
+    work.mkdir()
+    monkeypatch.chdir(work)
+    result = runner.invoke(app, ["init", "transcribe", "mydir", "--here", "--no-install"])
+    assert result.exit_code != 0  # ambiguous: directory AND --here both given
+
+
+def test_init_json_output_is_machine_readable(tmp_path, monkeypatch):
+    import json
+
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install", "--json"])
+    assert result.exit_code == 0, result.output
+    payload = json.loads(result.stdout)
+    assert any(step["name"] == "scaffold" and step["status"] == "created" for step in payload)
+
+
+def test_init_unshipped_template_errors_cleanly(tmp_path, monkeypatch):
+    # `stream` is in the design but its template doesn't ship yet, so it must not be
+    # registered — and picking it must give a clean error, not a FileNotFoundError.
+    monkeypatch.chdir(tmp_path)
+    result = runner.invoke(app, ["init", "stream", "s", "--no-install"])
+    assert result.exit_code == 1
+    assert "stream" in result.output
diff --git a/tests/test_init_templates.py b/tests/test_init_templates.py
index ebf708e0..bc0a9529 100644
--- a/tests/test_init_templates.py
+++ b/tests/test_init_templates.py
@@ -1,14 +1,28 @@
+from pathlib import Path
+
 from aai_cli.init import templates
 
+_TEMPLATES_ROOT = Path("aai_cli/init/templates")
+
 
-def test_all_four_template_ids_present():
-    assert set(templates.TEMPLATES) == {"transcribe", "stream", "agent", "llm"}
+def test_transcribe_is_registered():
+    assert "transcribe" in templates.TEMPLATES
+    assert "transcribe" in templates.TEMPLATE_ORDER
 
 
-def test_template_order_is_complete_and_stable():
-    # Display order mirrors the CLI's command order; every id appears exactly once.
-    assert templates.TEMPLATE_ORDER == ("transcribe", "stream", "agent", "llm")
+def test_order_matches_registry():
+    # Every ordered id is registered and vice versa (no stray/missing entries).
     assert set(templates.TEMPLATE_ORDER) == set(templates.TEMPLATES)
+    assert len(templates.TEMPLATE_ORDER) == len(templates.TEMPLATES)
+
+
+def test_every_registered_template_has_a_directory():
+    # The registry must never advertise a template whose files don't ship — that
+    # would crash `aai init <id>` with a FileNotFoundError. This guards the picker.
+    for tid in templates.TEMPLATES:
+        assert (_TEMPLATES_ROOT / tid / "api" / "index.py").exists(), (
+            f"template {tid!r} is registered but aai_cli/init/templates/{tid}/ is missing"
+        )
 
 
 def test_title_for_known_and_unknown():
@@ -17,5 +31,5 @@ def test_title_for_known_and_unknown():
 
 
 def test_is_template():
-    assert templates.is_template("agent") is True
+    assert templates.is_template("transcribe") is True
     assert templates.is_template("nope") is False

From c35e8785edacf9eef4e5b9aab65e18e1632a1986 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:30:38 -0700
Subject: [PATCH 24/32] docs(login): drop 'Stytch' from the help text

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/login.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aai_cli/commands/login.py b/aai_cli/commands/login.py
index 924546fb..5a71bdb6 100644
--- a/aai_cli/commands/login.py
+++ b/aai_cli/commands/login.py
@@ -17,7 +17,7 @@ def login(
     api_key: str = typer.Option(None, "--api-key", help="Provide key non-interactively."),
     json_out: bool = typer.Option(False, "--json", help="Output raw JSON."),
 ) -> None:
-    """Authenticate via your browser (Stytch); stores a CLI API key."""
+    """Authenticate via your browser; stores a CLI API key."""
 
     def body(state: AppState, json_mode: bool) -> None:
         profile = resolve_profile(state)

From af68fe0d9edc9c55fa5d672ecfbb8b54d39f7750 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:43:25 -0700
Subject: [PATCH 25/32] =?UTF-8?q?feat(init):=20transcribe=20template=20?=
 =?UTF-8?q?=E2=80=94=20URL/sample=20default=20+=20cleaner=20UI;=20rename?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Rename to 'Transcribe a pre-recorded file' (drop '& explore') in the picker
  title, page, backend docstring, and README.
- Add POST /api/transcribe-url: AssemblyAI transcribes a public URL directly
  (no upload), defaulting to the wildfires sample so the demo works in one click.
- Redesign index.html: URL field pre-filled with the sample + primary Transcribe
  button, file upload as the secondary path; tidier card layout and transcript
  rendering. Still a single, dependency-free HTML file.
- Tests for the URL endpoint (given URL + default-to-sample); contract test
  enforces the new route stays wired to the frontend.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/init/templates.py                     |   2 +-
 aai_cli/init/templates/transcribe/README.md   |   7 +-
 .../init/templates/transcribe/api/index.py    |  31 ++--
 aai_cli/init/templates/transcribe/index.html  | 134 +++++++++++++-----
 tests/test_init_template_transcribe.py        |  19 +++
 5 files changed, 143 insertions(+), 50 deletions(-)

diff --git a/aai_cli/init/templates.py b/aai_cli/init/templates.py
index a3fad13d..27238135 100644
--- a/aai_cli/init/templates.py
+++ b/aai_cli/init/templates.py
@@ -8,7 +8,7 @@
 # their template directories land in follow-on PRs. A test enforces registry ==
 # shipped directories.
 TEMPLATES: dict[str, str] = {
-    "transcribe": "Transcribe & explore a file",
+    "transcribe": "Transcribe a pre-recorded file",
 }
 
 # Display order for the picker and `--help`.
diff --git a/aai_cli/init/templates/transcribe/README.md b/aai_cli/init/templates/transcribe/README.md
index 039d29e2..b1338430 100644
--- a/aai_cli/init/templates/transcribe/README.md
+++ b/aai_cli/init/templates/transcribe/README.md
@@ -1,7 +1,8 @@
-# Transcribe & explore — AssemblyAI starter
+# Transcribe a pre-recorded file — AssemblyAI starter
 
-Upload an audio/video file and see the transcript with speaker labels, chapters,
-sentiment, entities, and highlights. Built with FastAPI + a single HTML page.
+Transcribe an audio/video URL (defaults to a public sample) or upload a file, and
+see the transcript with speaker labels, chapters, sentiment, entities, and
+highlights. Built with FastAPI + a single HTML page.
 
 ## Run locally
 
diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/transcribe/api/index.py
index 7ef8bc84..056ba1e1 100644
--- a/aai_cli/init/templates/transcribe/api/index.py
+++ b/aai_cli/init/templates/transcribe/api/index.py
@@ -1,10 +1,11 @@
-"""Transcribe & explore — AssemblyAI starter (FastAPI).
+"""Transcribe a pre-recorded file — AssemblyAI starter (FastAPI).
 
-Two short endpoints so each request stays fast (serverless-friendly):
-  POST /api/transcribe  -> submit the upload, return {"id": ...}
-  GET  /api/status/{id} -> poll; returns the full transcript JSON when complete
+Each call stays short, so it's serverless-friendly:
+  POST /api/transcribe       -> submit an uploaded file, return {"id": ...}
+  POST /api/transcribe-url   -> submit a public URL (defaults to the sample), {"id": ...}
+  GET  /api/status/{id}      -> poll; returns the full transcript JSON when complete
 
-The browser (index.html) submits a file, then polls status until done.
+The browser (index.html) submits a URL or file, then polls status until done.
 Your API key stays on the server — the browser never sees it.
 """
 
@@ -19,12 +20,15 @@
 from assemblyai.api import get_transcript  # single non-blocking GET (see status())
 from assemblyai.client import Client
 from dotenv import load_dotenv
-from fastapi import FastAPI, HTTPException, UploadFile
+from fastapi import Body, FastAPI, HTTPException, UploadFile
 from fastapi.responses import FileResponse
 
 load_dotenv()
 aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY", "")
 
+# A public sample so you can try it instantly without uploading anything.
+SAMPLE_URL = "https://assembly.ai/wildfires.mp3"
+
 # Audio-intelligence features to showcase. Tweak these — that's the point of a starter.
 CONFIG = aai.TranscriptionConfig(
     speaker_labels=True,
@@ -43,13 +47,24 @@ def index() -> FileResponse:
     return FileResponse(ROOT / "index.html")
 
 
+def _submit(audio: str) -> dict[str, str]:
+    """Submit an audio reference (local file path or public URL); return its id."""
+    transcript = aai.Transcriber().submit(audio, config=CONFIG)
+    return {"id": transcript.id}
+
+
 @app.post("/api/transcribe")
 async def transcribe(file: UploadFile) -> dict[str, str]:
     suffix = Path(file.filename or "audio").suffix
     tmp = Path(tempfile.gettempdir()) / f"aai-{uuid.uuid4().hex}{suffix}"
     tmp.write_bytes(await file.read())
-    transcript = aai.Transcriber().submit(str(tmp), config=CONFIG)
-    return {"id": transcript.id}
+    return _submit(str(tmp))
+
+
+@app.post("/api/transcribe-url")
+def transcribe_url(url: str = Body(default=SAMPLE_URL, embed=True)) -> dict[str, str]:
+    # AssemblyAI transcribes a public URL directly — no upload step needed.
+    return _submit(url.strip() or SAMPLE_URL)
 
 
 @app.get("/api/status/{transcript_id}")
diff --git a/aai_cli/init/templates/transcribe/index.html b/aai_cli/init/templates/transcribe/index.html
index b9d74ab3..b3710d76 100644
--- a/aai_cli/init/templates/transcribe/index.html
+++ b/aai_cli/init/templates/transcribe/index.html
@@ -3,47 +3,103 @@
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Transcribe &amp; explore · AssemblyAI</title>
+  <title>Transcribe a pre-recorded file · AssemblyAI</title>
   <style>
-    body { font: 15px/1.6 system-ui, sans-serif; max-width: 760px; margin: 40px auto; padding: 0 16px; }
-    h1 { font-size: 20px; }
-    #drop { border: 2px dashed #bbb; border-radius: 10px; padding: 28px; text-align: center; cursor: pointer; }
-    #drop.busy { opacity: .6; pointer-events: none; }
-    .chips span { display: inline-block; background: #eef; border-radius: 99px; padding: 3px 10px; margin: 2px; font-size: 12px; }
-    .turn { margin: 6px 0; }
-    .spk { font-weight: 600; }
-    pre { white-space: pre-wrap; }
+    :root { --accent: #4338ca; --line: #e5e7eb; --muted: #6b7280; --bg: #f8fafc; }
+    * { box-sizing: border-box; }
+    body {
+      font: 15px/1.6 -apple-system, system-ui, sans-serif; color: #111827;
+      background: var(--bg); margin: 0; padding: 48px 16px;
+    }
+    main { max-width: 720px; margin: 0 auto; }
+    h1 { font-size: 22px; margin: 0 0 4px; }
+    .sub { color: var(--muted); margin: 0 0 24px; }
+    .card { background: #fff; border: 1px solid var(--line); border-radius: 14px; padding: 20px; }
+    .row { display: flex; gap: 8px; }
+    input[type=url] {
+      flex: 1; min-width: 0; padding: 11px 13px; border: 1px solid var(--line);
+      border-radius: 9px; font-size: 14px;
+    }
+    input[type=url]:focus { outline: none; border-color: var(--accent); }
+    button {
+      background: var(--accent); color: #fff; border: 0; border-radius: 9px;
+      padding: 0 18px; font-size: 14px; font-weight: 600; cursor: pointer; white-space: nowrap;
+    }
+    button:disabled { opacity: .55; cursor: default; }
+    .or { display: flex; align-items: center; gap: 12px; color: var(--muted); font-size: 13px; margin: 16px 0; }
+    .or::before, .or::after { content: ""; flex: 1; height: 1px; background: var(--line); }
+    .upload {
+      display: block; text-align: center; padding: 16px; border: 1.5px dashed var(--line);
+      border-radius: 10px; color: var(--muted); cursor: pointer; font-size: 14px;
+    }
+    .upload:hover { border-color: var(--accent); color: var(--accent); }
+    #status { min-height: 22px; color: var(--muted); margin: 18px 0 0; font-size: 14px; }
+    .chips { margin: 4px 0 14px; }
+    .chips span {
+      display: inline-block; background: #eef2ff; color: var(--accent); border-radius: 999px;
+      padding: 3px 11px; margin: 2px 4px 2px 0; font-size: 12px; font-weight: 600;
+    }
+    .turn { padding: 7px 0; border-top: 1px solid var(--line); }
+    .spk { font-weight: 600; color: var(--accent); }
+    pre { white-space: pre-wrap; margin: 0; font: inherit; }
   </style>
 </head>
 <body>
-  <h1>🎧 Transcribe &amp; explore</h1>
-  <p>Pick an audio or video file. The server transcribes it with AssemblyAI and returns speakers, chapters, sentiment, entities, and highlights.</p>
+  <main>
+    <h1>🎧 Transcribe a pre-recorded file</h1>
+    <p class="sub">Transcribe an audio or video URL (or upload a file) and explore speakers, chapters, sentiment, entities, and highlights.</p>
 
-  <label id="drop">
-    <input id="file" type="file" accept="audio/*,video/*" hidden />
-    <span id="droplabel">Click to choose a file</span>
-  </label>
+    <div class="card">
+      <div class="row">
+        <input id="url" type="url" value="https://assembly.ai/wildfires.mp3"
+               placeholder="https://example.com/audio.mp3" />
+        <button id="go">Transcribe</button>
+      </div>
+      <div class="or">or</div>
+      <label class="upload">
+        <input id="file" type="file" accept="audio/*,video/*" hidden />
+        Upload an audio or video file
+      </label>
+    </div>
 
-  <p id="status"></p>
-  <div id="result"></div>
+    <p id="status"></p>
+    <div id="result"></div>
+  </main>
 
   <script>
+    const urlInput = document.getElementById("url");
+    const goBtn = document.getElementById("go");
     const fileInput = document.getElementById("file");
-    const drop = document.getElementById("drop");
     const statusEl = document.getElementById("status");
     const result = document.getElementById("result");
 
-    drop.addEventListener("click", () => fileInput.click());
-    fileInput.addEventListener("change", () => fileInput.files[0] && upload(fileInput.files[0]));
+    goBtn.addEventListener("click", () => transcribeUrl(urlInput.value.trim()));
+    urlInput.addEventListener("keydown", (e) => e.key === "Enter" && goBtn.click());
+    fileInput.addEventListener("change", () => fileInput.files[0] && transcribeFile(fileInput.files[0]));
 
-    async function upload(file) {
-      drop.classList.add("busy");
-      result.innerHTML = "";
-      statusEl.textContent = "Uploading…";
+    async function transcribeUrl(url) {
+      if (!url) return;
+      await start(() =>
+        fetch("/api/transcribe-url", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ url }),
+        })
+      );
+    }
+
+    async function transcribeFile(file) {
       const body = new FormData();
       body.append("file", file);
-      const res = await fetch("/api/transcribe", { method: "POST", body });
-      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
+      await start(() => fetch("/api/transcribe", { method: "POST", body }));
+    }
+
+    async function start(submit) {
+      busy(true);
+      result.innerHTML = "";
+      statusEl.textContent = "Uploading…";
+      const res = await submit();
+      if (!res.ok) return fail(await res.text());
       const { id } = await res.json();
       poll(id);
     }
@@ -51,29 +107,31 @@ <h1>🎧 Transcribe &amp; explore</h1>
     async function poll(id) {
       statusEl.textContent = "Transcribing…";
       const res = await fetch("/api/status/" + id);
-      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
+      if (!res.ok) return fail(await res.text());
       const data = await res.json();
-      if (data.status !== "completed") { setTimeout(() => poll(id), 2000); return; }
+      if (data.status !== "completed") return void setTimeout(() => poll(id), 2000);
       statusEl.textContent = "Done.";
-      drop.classList.remove("busy");
+      busy(false);
       render(data.transcript);
     }
 
     function render(t) {
       const chips = [];
-      if (t.chapters) chips.push("Chapters");
-      if (t.sentiment_analysis_results) chips.push("Sentiment");
-      if (t.entities) chips.push("Entities");
-      if (t.auto_highlights_result) chips.push("Highlights");
-      const utterances = (t.utterances || []).map(
-        (u) => `<div class="turn"><span class="spk">Speaker ${u.speaker}:</span> ${escapeHtml(u.text)}</div>`
-      ).join("");
+      if (t.chapters) chips.push(`${t.chapters.length} chapters`);
+      if (t.sentiment_analysis_results) chips.push("sentiment");
+      if (t.entities) chips.push(`${t.entities.length} entities`);
+      if (t.auto_highlights_result) chips.push("highlights");
+      const turns = (t.utterances || [])
+        .map((u) => `<div class="turn"><span class="spk">Speaker ${u.speaker}:</span> ${esc(u.text)}</div>`)
+        .join("");
       result.innerHTML =
         `<div class="chips">${chips.map((c) => `<span>${c}</span>`).join("")}</div>` +
-        (utterances || `<pre>${escapeHtml(t.text || "")}</pre>`);
+        (turns || `<pre>${esc(t.text || "")}</pre>`);
     }
 
-    function escapeHtml(s) {
+    function busy(on) { goBtn.disabled = on; }
+    function fail(msg) { busy(false); statusEl.textContent = "Error: " + msg; }
+    function esc(s) {
       return (s || "").replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
     }
   </script>
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index 3065ec2a..c244b015 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -75,6 +75,25 @@ def test_submit_returns_transcript_id(monkeypatch):
     fake.Transcriber.return_value.submit.assert_called_once()
 
 
+def test_transcribe_url_submits_given_url(monkeypatch):
+    app, fake, _api = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.post("/api/transcribe-url", json={"url": "https://example.com/a.mp3"})
+    assert resp.status_code == 200
+    assert resp.json() == {"id": "t-123"}
+    submitted = fake.Transcriber.return_value.submit.call_args[0][0]
+    assert submitted == "https://example.com/a.mp3"  # URL passed straight through, no upload
+
+
+def test_transcribe_url_defaults_to_sample(monkeypatch):
+    app, fake, _api = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.post("/api/transcribe-url", json={})  # no url -> the bundled sample
+    assert resp.status_code == 200
+    submitted = fake.Transcriber.return_value.submit.call_args[0][0]
+    assert "wildfires" in submitted
+
+
 def test_status_returns_completed_transcript(monkeypatch):
     app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)

From 119b00580b997be01ed848da96971bec8cdfb5ed Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 16:49:22 -0700
Subject: [PATCH 26/32] fix(init): pin scaffolded app to the key's AssemblyAI
 environment

A sandbox key (minted by 'aai login' against a non-prod env) was rejected by the
template's production default. Now 'aai init' writes ASSEMBLYAI_BASE_URL (the active
environment's api_base) into .env, and the transcribe template applies it via
aai.settings.base_url (defaulting to production when unset). Tests cover scaffold
writing the base URL, the template honoring it, and the command emitting it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py                       |  8 +++++---
 aai_cli/init/scaffold.py                       | 17 +++++++++++++----
 aai_cli/init/templates/transcribe/api/index.py |  4 ++++
 aai_cli/init/templates/transcribe/env.example  |  2 ++
 tests/test_init_command.py                     |  7 +++++++
 tests/test_init_scaffold.py                    | 12 ++++++++++++
 tests/test_init_template_transcribe.py         |  7 +++++++
 7 files changed, 50 insertions(+), 7 deletions(-)

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index 623cd78c..f9db8b1e 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -7,7 +7,7 @@
 import typer
 from rich.markup import escape
 
-from aai_cli import output
+from aai_cli import environments, output
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import CLIError
 from aai_cli.init import keys, runner, scaffold, steps, templates
@@ -61,7 +61,7 @@ def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
 @app.command()
 def init(
     ctx: typer.Context,
-    template: str = typer.Argument(None, help="Template id: transcribe, stream, agent, llm."),
+    template: str = typer.Argument(None, help="Template to scaffold (omit to pick interactively)."),
     directory: str = typer.Argument(None, help="Target directory (default: <template>-app)."),
     no_install: bool = typer.Option(
         False, "--no-install", help="Scaffold only; don't install or launch."
@@ -104,7 +104,9 @@ def body(state: AppState, json_mode: bool) -> None:
             )
 
         api_key = keys.resolve_optional_api_key(profile=state.profile)
-        scaffold.scaffold(chosen, target, api_key=api_key)
+        # Pin the app to the active environment's API host so a sandbox key (minted by
+        # `aai login` against a non-prod env) isn't rejected by the production default.
+        scaffold.scaffold(chosen, target, api_key=api_key, base_url=environments.active().api_base)
 
         report: list[steps.Step] = [
             {"name": "scaffold", "status": "created", "detail": str(target)}
diff --git a/aai_cli/init/scaffold.py b/aai_cli/init/scaffold.py
index 9eae3190..280b7c14 100644
--- a/aai_cli/init/scaffold.py
+++ b/aai_cli/init/scaffold.py
@@ -64,11 +64,20 @@ def _copy_tree(node: Traversable, dest: Path) -> None:
             out.write_bytes(child.read_bytes())
 
 
-def scaffold(template: str, target: Path, *, api_key: str | None) -> Path:
-    """Copy the template into `target` and write `.env`. Returns `target`."""
+def scaffold(
+    template: str, target: Path, *, api_key: str | None, base_url: str | None = None
+) -> Path:
+    """Copy the template into `target` and write `.env`. Returns `target`.
+
+    `base_url`, when given, pins the generated app to the same AssemblyAI environment
+    the key was minted for (e.g. a sandbox) — otherwise a sandbox key would be rejected
+    by the production default.
+    """
     root = _template_root(template)
     target.mkdir(parents=True, exist_ok=True)
     _copy_tree(root, target)
-    key = api_key or PLACEHOLDER_KEY
-    (target / ".env").write_text(f"ASSEMBLYAI_API_KEY={key}\n")
+    lines = [f"ASSEMBLYAI_API_KEY={api_key or PLACEHOLDER_KEY}"]
+    if base_url:
+        lines.append(f"ASSEMBLYAI_BASE_URL={base_url}")
+    (target / ".env").write_text("\n".join(lines) + "\n")
     return target
diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/transcribe/api/index.py
index 056ba1e1..ce09c855 100644
--- a/aai_cli/init/templates/transcribe/api/index.py
+++ b/aai_cli/init/templates/transcribe/api/index.py
@@ -25,6 +25,10 @@
 
 load_dotenv()
 aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY", "")
+# Target the same AssemblyAI environment the key was minted for. `aai init` writes
+# this for you; leave it unset to use the production default.
+if base_url := os.environ.get("ASSEMBLYAI_BASE_URL"):
+    aai.settings.base_url = base_url
 
 # A public sample so you can try it instantly without uploading anything.
 SAMPLE_URL = "https://assembly.ai/wildfires.mp3"
diff --git a/aai_cli/init/templates/transcribe/env.example b/aai_cli/init/templates/transcribe/env.example
index ae0847f2..5cc402a0 100644
--- a/aai_cli/init/templates/transcribe/env.example
+++ b/aai_cli/init/templates/transcribe/env.example
@@ -1 +1,3 @@
 ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
+# Optional — target a non-production AssemblyAI environment (aai init fills this in):
+# ASSEMBLYAI_BASE_URL=https://api.assemblyai.com
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
index ced95ad8..1951f11d 100644
--- a/tests/test_init_command.py
+++ b/tests/test_init_command.py
@@ -20,6 +20,13 @@ def test_init_writes_key_from_env(tmp_path, monkeypatch):
     assert "ASSEMBLYAI_API_KEY=sk-from-env" in (tmp_path / "myapp" / ".env").read_text()
 
 
+def test_init_writes_base_url_for_active_env(tmp_path, monkeypatch):
+    # The generated .env pins the app to the CLI's active environment host.
+    monkeypatch.chdir(tmp_path)
+    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    assert "ASSEMBLYAI_BASE_URL=https://" in (tmp_path / "myapp" / ".env").read_text()
+
+
 def test_init_placeholder_key_when_logged_out(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
diff --git a/tests/test_init_scaffold.py b/tests/test_init_scaffold.py
index 37c4112d..ee8ae97d 100644
--- a/tests/test_init_scaffold.py
+++ b/tests/test_init_scaffold.py
@@ -25,6 +25,18 @@ def test_scaffold_writes_env_with_key(tmp_path):
     assert "ASSEMBLYAI_API_KEY=sk-real-key" in env
 
 
+def test_scaffold_writes_base_url_when_given(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key="k", base_url="https://api.sb.example")
+    assert "ASSEMBLYAI_BASE_URL=https://api.sb.example" in (target / ".env").read_text()
+
+
+def test_scaffold_omits_base_url_when_none(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold("transcribe", target, api_key="k")
+    assert "ASSEMBLYAI_BASE_URL" not in (target / ".env").read_text()
+
+
 def test_scaffold_skips_pycache(tmp_path):
     # Importing a template's api/index.py during our own test run leaves a
     # __pycache__ next to it; the scaffolder must not copy that into the project.
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index c244b015..8237c576 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -58,6 +58,13 @@ def test_template_ships_no_real_key():
     assert "your_assemblyai_api_key_here" in (TEMPLATE_DIR / "env.example").read_text()
 
 
+def test_base_url_env_is_applied(monkeypatch):
+    # aai init writes ASSEMBLYAI_BASE_URL so a sandbox key targets the sandbox host.
+    monkeypatch.setenv("ASSEMBLYAI_BASE_URL", "https://api.sb.example")
+    _app, fake, _api = _load_app(monkeypatch)
+    assert fake.settings.base_url == "https://api.sb.example"
+
+
 def test_index_route_serves_page(monkeypatch):
     app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)

From 82d005e8a0c5c408db68ebb2da79e7e70daec9ce Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 17:01:26 -0700
Subject: [PATCH 27/32] =?UTF-8?q?feat(init):=20transcribe=20UI=20=E2=80=94?=
 =?UTF-8?q?=20explore=20chapters/sentiment/entities/highlights=20+=20per-s?=
 =?UTF-8?q?peaker=20colors?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Results area becomes a tabbed explorer (Transcript · Chapters · Sentiment ·
  Entities · Highlights), showing only tabs that have data. Chapters show
  headline/summary + timestamps; sentiment color-codes POSITIVE/NEGATIVE/NEUTRAL;
  entities group by type; highlights rank key phrases with counts.
- Speakers are differentiated with a per-speaker color (name + left rule) from a
  small palette, in both Transcript and Sentiment views.
- Status messages get state-styled pills (working / done / error).
- Still a single dependency-free HTML file; verified end-to-end in a browser
  against the sandbox sample. Guard test keeps the feature views + speaker
  coloring wired.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .gitignore                                   |   3 +
 aai_cli/init/templates/transcribe/index.html | 169 +++++++++++++++----
 tests/test_init_template_transcribe.py       |  13 ++
 3 files changed, 153 insertions(+), 32 deletions(-)

diff --git a/.gitignore b/.gitignore
index f676fdf4..18d796db 100644
--- a/.gitignore
+++ b/.gitignore
@@ -24,3 +24,6 @@ poetry.lock
 
 # Brainstorming visual-companion scratch
 .superpowers/
+
+# Playwright MCP scratch
+.playwright-mcp/
diff --git a/aai_cli/init/templates/transcribe/index.html b/aai_cli/init/templates/transcribe/index.html
index b3710d76..58c30d05 100644
--- a/aai_cli/init/templates/transcribe/index.html
+++ b/aai_cli/init/templates/transcribe/index.html
@@ -11,7 +11,7 @@
       font: 15px/1.6 -apple-system, system-ui, sans-serif; color: #111827;
       background: var(--bg); margin: 0; padding: 48px 16px;
     }
-    main { max-width: 720px; margin: 0 auto; }
+    main { max-width: 760px; margin: 0 auto; }
     h1 { font-size: 22px; margin: 0 0 4px; }
     .sub { color: var(--muted); margin: 0 0 24px; }
     .card { background: #fff; border: 1px solid var(--line); border-radius: 14px; padding: 20px; }
@@ -33,21 +33,57 @@
       border-radius: 10px; color: var(--muted); cursor: pointer; font-size: 14px;
     }
     .upload:hover { border-color: var(--accent); color: var(--accent); }
-    #status { min-height: 22px; color: var(--muted); margin: 18px 0 0; font-size: 14px; }
-    .chips { margin: 4px 0 14px; }
-    .chips span {
-      display: inline-block; background: #eef2ff; color: var(--accent); border-radius: 999px;
-      padding: 3px 11px; margin: 2px 4px 2px 0; font-size: 12px; font-weight: 600;
-    }
-    .turn { padding: 7px 0; border-top: 1px solid var(--line); }
-    .spk { font-weight: 600; color: var(--accent); }
+    #status {
+      display: inline-block; margin: 18px 0; padding: 6px 13px; border-radius: 999px;
+      font-size: 13px; font-weight: 600;
+    }
+    #status:empty { display: none; }
+    #status.working { background: #eef2ff; color: var(--accent); }
+    #status.done { background: #dcfce7; color: #166534; }
+    #status.error { background: #fee2e2; color: #991b1b; }
+
+    /* Tabs */
+    .tabs { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 14px; }
+    .tabs button {
+      background: #fff; color: #374151; border: 1px solid var(--line); border-radius: 999px;
+      padding: 6px 14px; font-size: 13px; font-weight: 600;
+    }
+    .tabs button.active { background: var(--accent); color: #fff; border-color: var(--accent); }
+    .time { color: var(--muted); font-variant-numeric: tabular-nums; font-size: 12px; }
+
+    /* Transcript / sentiment turns */
+    .turn { padding: 8px 0 8px 12px; border-left: 3px solid var(--line); margin: 8px 0; }
+    .spk { font-weight: 700; }
+    .turn .t { color: #374151; }
+
+    /* Chapters */
+    .chapter { padding: 12px 0; border-top: 1px solid var(--line); }
+    .chapter h4 { margin: 0 0 2px; font-size: 15px; }
+    .chapter p { margin: 4px 0 0; color: #374151; }
+
+    /* Entities */
+    .egroup { padding: 10px 0; border-top: 1px solid var(--line); }
+    .elabel { font-size: 11px; text-transform: uppercase; letter-spacing: .05em; color: var(--muted); }
+    .etag { display: inline-block; background: #eef2ff; color: var(--accent); border-radius: 999px;
+            padding: 2px 10px; margin: 4px 4px 0 0; font-size: 13px; }
+
+    /* Highlights */
+    .hl { display: flex; align-items: center; gap: 10px; padding: 8px 0; border-top: 1px solid var(--line); }
+    .hl .count { background: #eef2ff; color: var(--accent); border-radius: 999px; padding: 2px 9px;
+                 font-size: 12px; font-weight: 700; }
+
+    /* Sentiment pills */
+    .sent { font-size: 11px; font-weight: 700; border-radius: 999px; padding: 1px 8px; margin-left: 8px; }
+    .POSITIVE { background: #dcfce7; color: #166534; }
+    .NEGATIVE { background: #fee2e2; color: #991b1b; }
+    .NEUTRAL { background: #f3f4f6; color: #4b5563; }
     pre { white-space: pre-wrap; margin: 0; font: inherit; }
   </style>
 </head>
 <body>
   <main>
     <h1>🎧 Transcribe a pre-recorded file</h1>
-    <p class="sub">Transcribe an audio or video URL (or upload a file) and explore speakers, chapters, sentiment, entities, and highlights.</p>
+    <p class="sub">Transcribe an audio or video URL (or upload a file), then explore speakers, chapters, sentiment, entities, and highlights.</p>
 
     <div class="card">
       <div class="row">
@@ -63,7 +99,8 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
     </div>
 
     <p id="status"></p>
-    <div id="result"></div>
+    <div id="tabs" class="tabs"></div>
+    <div id="view"></div>
   </main>
 
   <script>
@@ -71,7 +108,8 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
     const goBtn = document.getElementById("go");
     const fileInput = document.getElementById("file");
     const statusEl = document.getElementById("status");
-    const result = document.getElementById("result");
+    const tabsEl = document.getElementById("tabs");
+    const viewEl = document.getElementById("view");
 
     goBtn.addEventListener("click", () => transcribeUrl(urlInput.value.trim()));
     urlInput.addEventListener("keydown", (e) => e.key === "Enter" && goBtn.click());
@@ -96,43 +134,110 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
 
     async function start(submit) {
       busy(true);
-      result.innerHTML = "";
-      statusEl.textContent = "Uploading…";
+      tabsEl.innerHTML = viewEl.innerHTML = "";
+      setStatus("Uploading…", "working");
       const res = await submit();
       if (!res.ok) return fail(await res.text());
-      const { id } = await res.json();
-      poll(id);
+      poll((await res.json()).id);
     }
 
     async function poll(id) {
-      statusEl.textContent = "Transcribing…";
+      setStatus("Transcribing…", "working");
       const res = await fetch("/api/status/" + id);
       if (!res.ok) return fail(await res.text());
       const data = await res.json();
       if (data.status !== "completed") return void setTimeout(() => poll(id), 2000);
-      statusEl.textContent = "Done.";
+      setStatus("✓ Done", "done");
       busy(false);
-      render(data.transcript);
+      explore(data.transcript);
+    }
+
+    // --- speaker colors --------------------------------------------------
+    const PALETTE = ["#4338ca", "#0d9488", "#b45309", "#be185d", "#15803d", "#7c3aed"];
+    const speakerColor = (() => {
+      const seen = {};
+      return (spk) => (seen[spk] ??= PALETTE[Object.keys(seen).length % PALETTE.length]);
+    })();
+
+    // --- build the tabbed explorer --------------------------------------
+    function explore(t) {
+      const views = {};
+      const turns = t.utterances || [];
+      views.Transcript = turns.length
+        ? turns.map((u) => turnHtml(u.speaker, u.text)).join("")
+        : `<pre>${esc(t.text || "")}</pre>`;
+
+      if (t.chapters?.length) views[`Chapters · ${t.chapters.length}`] = chaptersHtml(t.chapters);
+      if (t.sentiment_analysis_results?.length)
+        views.Sentiment = t.sentiment_analysis_results.map(sentimentHtml).join("");
+      if (t.entities?.length) views[`Entities · ${t.entities.length}`] = entitiesHtml(t.entities);
+      const hl = t.auto_highlights_result?.results || [];
+      if (hl.length) views.Highlights = highlightsHtml(hl);
+
+      tabsEl.innerHTML = "";
+      Object.keys(views).forEach((name, i) => {
+        const b = document.createElement("button");
+        b.textContent = name;
+        b.onclick = () => {
+          viewEl.innerHTML = views[name];
+          [...tabsEl.children].forEach((c) => c.classList.toggle("active", c === b));
+        };
+        tabsEl.appendChild(b);
+        if (i === 0) b.click();
+      });
+    }
+
+    function turnHtml(speaker, text, extra = "") {
+      const c = speakerColor(speaker);
+      return `<div class="turn" style="border-left-color:${c}">
+        <span class="spk" style="color:${c}">Speaker ${esc(speaker)}</span>${extra}
+        <div class="t">${esc(text)}</div></div>`;
+    }
+
+    function sentimentHtml(s) {
+      const pill = `<span class="sent ${s.sentiment}">${esc(s.sentiment)}</span>`;
+      return turnHtml(s.speaker || "?", s.text, pill);
+    }
+
+    function chaptersHtml(chapters) {
+      return chapters
+        .map(
+          (c) => `<div class="chapter">
+            <h4>${esc(c.headline || c.gist || "Chapter")}</h4>
+            <span class="time">${fmt(c.start)} – ${fmt(c.end)}</span>
+            <p>${esc(c.summary || c.gist || "")}</p></div>`
+        )
+        .join("");
+    }
+
+    function entitiesHtml(entities) {
+      const groups = {};
+      for (const e of entities) (groups[e.entity_type] ??= []).push(e.text);
+      return Object.entries(groups)
+        .map(
+          ([type, items]) => `<div class="egroup"><div class="elabel">${esc(type)}</div>
+            ${[...new Set(items)].map((x) => `<span class="etag">${esc(x)}</span>`).join("")}</div>`
+        )
+        .join("");
     }
 
-    function render(t) {
-      const chips = [];
-      if (t.chapters) chips.push(`${t.chapters.length} chapters`);
-      if (t.sentiment_analysis_results) chips.push("sentiment");
-      if (t.entities) chips.push(`${t.entities.length} entities`);
-      if (t.auto_highlights_result) chips.push("highlights");
-      const turns = (t.utterances || [])
-        .map((u) => `<div class="turn"><span class="spk">Speaker ${u.speaker}:</span> ${esc(u.text)}</div>`)
+    function highlightsHtml(results) {
+      return results
+        .sort((a, b) => b.rank - a.rank)
+        .map((h) => `<div class="hl"><span class="count">${h.count}×</span> ${esc(h.text)}</div>`)
         .join("");
-      result.innerHTML =
-        `<div class="chips">${chips.map((c) => `<span>${c}</span>`).join("")}</div>` +
-        (turns || `<pre>${esc(t.text || "")}</pre>`);
     }
 
+    // --- helpers ---------------------------------------------------------
+    function fmt(ms) {
+      const s = Math.round((ms || 0) / 1000);
+      return `${Math.floor(s / 60)}:${String(s % 60).padStart(2, "0")}`;
+    }
     function busy(on) { goBtn.disabled = on; }
-    function fail(msg) { busy(false); statusEl.textContent = "Error: " + msg; }
+    function setStatus(msg, state) { statusEl.textContent = msg; statusEl.className = state; }
+    function fail(msg) { busy(false); setStatus("⚠ " + msg, "error"); }
     function esc(s) {
-      return (s || "").replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
+      return String(s ?? "").replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
     }
   </script>
 </body>
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index 8237c576..d1afb66f 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -65,6 +65,19 @@ def test_base_url_env_is_applied(monkeypatch):
     assert fake.settings.base_url == "https://api.sb.example"
 
 
+def test_page_explores_all_features_and_speakers():
+    # Guard the UI surface: each audio-intelligence view + per-speaker coloring stay wired.
+    html = (TEMPLATE_DIR / "index.html").read_text()
+    for token in (
+        "chapters",
+        "sentiment_analysis_results",
+        "entities",
+        "auto_highlights_result",
+        "speakerColor",
+    ):
+        assert token in html, token
+
+
 def test_index_route_serves_page(monkeypatch):
     app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)

From 47355b910223ecdf8fcb5d04671c84a28bf5931d Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 17:07:47 -0700
Subject: [PATCH 28/32] =?UTF-8?q?feat(init):=20transcribe=20template=20?=
 =?UTF-8?q?=E2=80=94=20ask=20the=20transcript=20via=20LLM=20Gateway?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an Ask panel that questions the transcript with AssemblyAI's LLM Gateway
(OpenAI-compatible; transcript injected server-side via extra_body transcript_id),
shown alongside the transcript explorer so both stay visible.

- New POST /api/ask endpoint (model claude-haiku-4-5), surfaces gateway errors
  (e.g. plan access) as a clean 502 the UI shows.
- aai init now also writes ASSEMBLYAI_LLM_GATEWAY_URL (active env's gateway) to
  .env; the template honors it, defaulting to production. Adds openai to the
  template requirements.
- Tests: ask endpoint (openai stubbed, asserts transcript_id passed via extra_body),
  scaffold/command write the gateway URL, guard test keeps the Ask panel wired.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py                      | 13 +++--
 aai_cli/init/scaffold.py                      | 15 ++++--
 .../init/templates/transcribe/api/index.py    | 31 +++++++++++-
 aai_cli/init/templates/transcribe/env.example |  3 +-
 aai_cli/init/templates/transcribe/index.html  | 50 ++++++++++++++++++-
 .../templates/transcribe/requirements.txt     |  1 +
 tests/test_init_command.py                    |  6 ++-
 tests/test_init_scaffold.py                   | 12 ++++-
 tests/test_init_template_transcribe.py        | 21 ++++++++
 9 files changed, 138 insertions(+), 14 deletions(-)

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index f9db8b1e..8541dfd1 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -104,9 +104,16 @@ def body(state: AppState, json_mode: bool) -> None:
             )
 
         api_key = keys.resolve_optional_api_key(profile=state.profile)
-        # Pin the app to the active environment's API host so a sandbox key (minted by
-        # `aai login` against a non-prod env) isn't rejected by the production default.
-        scaffold.scaffold(chosen, target, api_key=api_key, base_url=environments.active().api_base)
+        # Pin the app to the active environment's hosts so a sandbox key (minted by
+        # `aai login` against a non-prod env) isn't rejected by the production defaults.
+        env = environments.active()
+        scaffold.scaffold(
+            chosen,
+            target,
+            api_key=api_key,
+            base_url=env.api_base,
+            llm_gateway_url=env.llm_gateway_base,
+        )
 
         report: list[steps.Step] = [
             {"name": "scaffold", "status": "created", "detail": str(target)}
diff --git a/aai_cli/init/scaffold.py b/aai_cli/init/scaffold.py
index 280b7c14..f103b49e 100644
--- a/aai_cli/init/scaffold.py
+++ b/aai_cli/init/scaffold.py
@@ -65,13 +65,18 @@ def _copy_tree(node: Traversable, dest: Path) -> None:
 
 
 def scaffold(
-    template: str, target: Path, *, api_key: str | None, base_url: str | None = None
+    template: str,
+    target: Path,
+    *,
+    api_key: str | None,
+    base_url: str | None = None,
+    llm_gateway_url: str | None = None,
 ) -> Path:
     """Copy the template into `target` and write `.env`. Returns `target`.
 
-    `base_url`, when given, pins the generated app to the same AssemblyAI environment
-    the key was minted for (e.g. a sandbox) — otherwise a sandbox key would be rejected
-    by the production default.
+    `base_url`/`llm_gateway_url`, when given, pin the generated app to the same
+    AssemblyAI environment the key was minted for (e.g. a sandbox) — otherwise a
+    sandbox key would be rejected by the production defaults.
     """
     root = _template_root(template)
     target.mkdir(parents=True, exist_ok=True)
@@ -79,5 +84,7 @@ def scaffold(
     lines = [f"ASSEMBLYAI_API_KEY={api_key or PLACEHOLDER_KEY}"]
     if base_url:
         lines.append(f"ASSEMBLYAI_BASE_URL={base_url}")
+    if llm_gateway_url:
+        lines.append(f"ASSEMBLYAI_LLM_GATEWAY_URL={llm_gateway_url}")
     (target / ".env").write_text("\n".join(lines) + "\n")
     return target
diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/transcribe/api/index.py
index ce09c855..8716b886 100644
--- a/aai_cli/init/templates/transcribe/api/index.py
+++ b/aai_cli/init/templates/transcribe/api/index.py
@@ -4,6 +4,7 @@
   POST /api/transcribe       -> submit an uploaded file, return {"id": ...}
   POST /api/transcribe-url   -> submit a public URL (defaults to the sample), {"id": ...}
   GET  /api/status/{id}      -> poll; returns the full transcript JSON when complete
+  POST /api/ask              -> ask a question about a transcript via the LLM Gateway
 
 The browser (index.html) submits a URL or file, then polls status until done.
 Your API key stays on the server — the browser never sees it.
@@ -22,13 +23,19 @@
 from dotenv import load_dotenv
 from fastapi import Body, FastAPI, HTTPException, UploadFile
 from fastapi.responses import FileResponse
+from openai import OpenAI  # the LLM Gateway is OpenAI-compatible
 
 load_dotenv()
-aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY", "")
+API_KEY = os.environ.get("ASSEMBLYAI_API_KEY", "")
+aai.settings.api_key = API_KEY
 # Target the same AssemblyAI environment the key was minted for. `aai init` writes
-# this for you; leave it unset to use the production default.
+# these for you; leave them unset to use the production defaults.
 if base_url := os.environ.get("ASSEMBLYAI_BASE_URL"):
     aai.settings.base_url = base_url
+LLM_GATEWAY_URL = os.environ.get(
+    "ASSEMBLYAI_LLM_GATEWAY_URL", "https://llm-gateway.assemblyai.com/v1"
+)
+LLM_MODEL = "claude-haiku-4-5-20251001"
 
 # A public sample so you can try it instantly without uploading anything.
 SAMPLE_URL = "https://assembly.ai/wildfires.mp3"
@@ -71,6 +78,26 @@ def transcribe_url(url: str = Body(default=SAMPLE_URL, embed=True)) -> dict[str,
     return _submit(url.strip() or SAMPLE_URL)
 
 
+@app.post("/api/ask")
+def ask(transcript_id: str = Body(...), question: str = Body(...)) -> dict[str, str]:
+    """Answer a question about a transcript via the LLM Gateway.
+
+    The gateway is OpenAI-compatible: pass `transcript_id` in `extra_body` and it
+    substitutes the `{{ transcript }}` tag with the transcript text server-side.
+    """
+    client = OpenAI(api_key=API_KEY, base_url=LLM_GATEWAY_URL)
+    try:
+        resp = client.chat.completions.create(
+            model=LLM_MODEL,
+            messages=[{"role": "user", "content": f"{question}\n\n{{{{ transcript }}}}"}],
+            max_tokens=1000,
+            extra_body={"transcript_id": transcript_id},
+        )
+    except Exception as exc:  # surface the gateway's own error (e.g. plan access)
+        raise HTTPException(status_code=502, detail=f"LLM Gateway error: {exc}") from exc
+    return {"answer": resp.choices[0].message.content or ""}
+
+
 @app.get("/api/status/{transcript_id}")
 def status(transcript_id: str) -> dict[str, object]:
     # One non-blocking GET. NOTE: aai.Transcript.get_by_id() BLOCKS until the job
diff --git a/aai_cli/init/templates/transcribe/env.example b/aai_cli/init/templates/transcribe/env.example
index 5cc402a0..c989b993 100644
--- a/aai_cli/init/templates/transcribe/env.example
+++ b/aai_cli/init/templates/transcribe/env.example
@@ -1,3 +1,4 @@
 ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
-# Optional — target a non-production AssemblyAI environment (aai init fills this in):
+# Optional — target a non-production AssemblyAI environment (aai init fills these in):
 # ASSEMBLYAI_BASE_URL=https://api.assemblyai.com
+# ASSEMBLYAI_LLM_GATEWAY_URL=https://llm-gateway.assemblyai.com/v1
diff --git a/aai_cli/init/templates/transcribe/index.html b/aai_cli/init/templates/transcribe/index.html
index 58c30d05..c27a0372 100644
--- a/aai_cli/init/templates/transcribe/index.html
+++ b/aai_cli/init/templates/transcribe/index.html
@@ -42,6 +42,16 @@
     #status.done { background: #dcfce7; color: #166534; }
     #status.error { background: #fee2e2; color: #991b1b; }
 
+    /* Ask the transcript (LLM Gateway) */
+    #ask { margin: 0 0 18px; }
+    #ask .q { display: flex; gap: 8px; }
+    #ask input { flex: 1; min-width: 0; padding: 11px 13px; border: 1px solid var(--line);
+                 border-radius: 9px; font-size: 14px; }
+    #ask input:focus { outline: none; border-color: var(--accent); }
+    .answer { margin-top: 12px; padding: 12px 14px; background: #f5f3ff; border-radius: 10px;
+              white-space: pre-wrap; color: #1e1b4b; }
+    .answer:empty { display: none; }
+
     /* Tabs */
     .tabs { display: flex; flex-wrap: wrap; gap: 6px; margin-bottom: 14px; }
     .tabs button {
@@ -99,6 +109,15 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
     </div>
 
     <p id="status"></p>
+
+    <div id="ask" class="card" hidden>
+      <div class="q">
+        <input id="q" type="text" placeholder="Ask a question about this transcript…" />
+        <button id="askBtn">Ask</button>
+      </div>
+      <div id="answer" class="answer"></div>
+    </div>
+
     <div id="tabs" class="tabs"></div>
     <div id="view"></div>
   </main>
@@ -110,10 +129,18 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
     const statusEl = document.getElementById("status");
     const tabsEl = document.getElementById("tabs");
     const viewEl = document.getElementById("view");
+    const askPanel = document.getElementById("ask");
+    const qInput = document.getElementById("q");
+    const askBtn = document.getElementById("askBtn");
+    const answerEl = document.getElementById("answer");
+
+    let currentId = null;  // transcript the Ask panel questions against
 
     goBtn.addEventListener("click", () => transcribeUrl(urlInput.value.trim()));
     urlInput.addEventListener("keydown", (e) => e.key === "Enter" && goBtn.click());
     fileInput.addEventListener("change", () => fileInput.files[0] && transcribeFile(fileInput.files[0]));
+    askBtn.addEventListener("click", () => ask(qInput.value.trim()));
+    qInput.addEventListener("keydown", (e) => e.key === "Enter" && askBtn.click());
 
     async function transcribeUrl(url) {
       if (!url) return;
@@ -134,7 +161,9 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
 
     async function start(submit) {
       busy(true);
-      tabsEl.innerHTML = viewEl.innerHTML = "";
+      tabsEl.innerHTML = viewEl.innerHTML = answerEl.textContent = "";
+      askPanel.hidden = true;
+      currentId = null;
       setStatus("Uploading…", "working");
       const res = await submit();
       if (!res.ok) return fail(await res.text());
@@ -149,9 +178,28 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
       if (data.status !== "completed") return void setTimeout(() => poll(id), 2000);
       setStatus("✓ Done", "done");
       busy(false);
+      currentId = id;
+      askPanel.hidden = false;  // transcript stays visible below; ask alongside it
       explore(data.transcript);
     }
 
+    async function ask(question) {
+      if (!question || !currentId) return;
+      askBtn.disabled = true;
+      answerEl.textContent = "Thinking…";
+      try {
+        const res = await fetch("/api/ask", {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ transcript_id: currentId, question }),
+        });
+        const data = await res.json();
+        answerEl.textContent = res.ok ? data.answer : "Error: " + (data.detail || res.statusText);
+      } finally {
+        askBtn.disabled = false;
+      }
+    }
+
     // --- speaker colors --------------------------------------------------
     const PALETTE = ["#4338ca", "#0d9488", "#b45309", "#be185d", "#15803d", "#7c3aed"];
     const speakerColor = (() => {
diff --git a/aai_cli/init/templates/transcribe/requirements.txt b/aai_cli/init/templates/transcribe/requirements.txt
index 38145aff..0a6b9dfc 100644
--- a/aai_cli/init/templates/transcribe/requirements.txt
+++ b/aai_cli/init/templates/transcribe/requirements.txt
@@ -3,3 +3,4 @@ uvicorn
 assemblyai
 python-dotenv
 python-multipart
+openai
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
index 1951f11d..dacbd89e 100644
--- a/tests/test_init_command.py
+++ b/tests/test_init_command.py
@@ -21,10 +21,12 @@ def test_init_writes_key_from_env(tmp_path, monkeypatch):
 
 
 def test_init_writes_base_url_for_active_env(tmp_path, monkeypatch):
-    # The generated .env pins the app to the CLI's active environment host.
+    # The generated .env pins the app to the CLI's active environment hosts.
     monkeypatch.chdir(tmp_path)
     runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
-    assert "ASSEMBLYAI_BASE_URL=https://" in (tmp_path / "myapp" / ".env").read_text()
+    env = (tmp_path / "myapp" / ".env").read_text()
+    assert "ASSEMBLYAI_BASE_URL=https://" in env
+    assert "ASSEMBLYAI_LLM_GATEWAY_URL=https://" in env
 
 
 def test_init_placeholder_key_when_logged_out(tmp_path, monkeypatch):
diff --git a/tests/test_init_scaffold.py b/tests/test_init_scaffold.py
index ee8ae97d..514539bb 100644
--- a/tests/test_init_scaffold.py
+++ b/tests/test_init_scaffold.py
@@ -34,7 +34,17 @@ def test_scaffold_writes_base_url_when_given(tmp_path):
 def test_scaffold_omits_base_url_when_none(tmp_path):
     target = tmp_path / "app"
     scaffold.scaffold("transcribe", target, api_key="k")
-    assert "ASSEMBLYAI_BASE_URL" not in (target / ".env").read_text()
+    env = (target / ".env").read_text()
+    assert "ASSEMBLYAI_BASE_URL" not in env
+    assert "ASSEMBLYAI_LLM_GATEWAY_URL" not in env
+
+
+def test_scaffold_writes_llm_gateway_url_when_given(tmp_path):
+    target = tmp_path / "app"
+    scaffold.scaffold(
+        "transcribe", target, api_key="k", llm_gateway_url="https://llm.sb.example/v1"
+    )
+    assert "ASSEMBLYAI_LLM_GATEWAY_URL=https://llm.sb.example/v1" in (target / ".env").read_text()
 
 
 def test_scaffold_skips_pycache(tmp_path):
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index d1afb66f..3667fb6a 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -74,10 +74,31 @@ def test_page_explores_all_features_and_speakers():
         "entities",
         "auto_highlights_result",
         "speakerColor",
+        "/api/ask",  # the LLM Gateway Q&A panel
     ):
         assert token in html, token
 
 
+def test_ask_calls_llm_gateway_with_transcript_id(monkeypatch):
+    # Stub the OpenAI SDK before the template module imports it.
+    fake_openai = MagicMock()
+    msg = MagicMock()
+    msg.content = "It's about wildfires."
+    fake_openai.OpenAI.return_value.chat.completions.create.return_value = MagicMock(
+        choices=[MagicMock(message=msg)]
+    )
+    monkeypatch.setitem(sys.modules, "openai", fake_openai)
+
+    app, _aai, _api = _load_app(monkeypatch)
+    client = TestClient(app)
+    resp = client.post("/api/ask", json={"transcript_id": "t-1", "question": "What is this about?"})
+    assert resp.status_code == 200
+    assert "wildfires" in resp.json()["answer"]
+    # The gateway injects the transcript server-side via extra_body, not inline.
+    kwargs = fake_openai.OpenAI.return_value.chat.completions.create.call_args.kwargs
+    assert kwargs["extra_body"] == {"transcript_id": "t-1"}
+
+
 def test_index_route_serves_page(monkeypatch):
     app, _aai, _api = _load_app(monkeypatch)
     client = TestClient(app)

From 15238c82d23a22582a3a428073f12e3abefead77 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 17:25:57 -0700
Subject: [PATCH 29/32] fix(init): address code-review findings (error
 handling, dedup, robustness)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Correctness:
- Template transcribe/transcribe-url/status endpoints now catch SDK exceptions and
  return a clean 502 instead of a 500 traceback (esp. placeholder/invalid key).
- index.html: poll() failures are caught (no more stuck 'Transcribing…' button);
  speaker colors reset per transcription.
- aai init: when logged out, install runs but a 'launch: skipped — run aai login'
  step is reported instead of exiting silently.
- Template uploads are deleted after submit (no /tmp leak); assemblyai pinned
  (>=0.64,<1) to bound the internal-API surface it uses.

Cleanup / robustness:
- Extract shared aai_cli/steps.py (Step + render_steps(heading=...)); init and
  claude both use it (removes the duplicated TypedDict + render loop).
- init reuses the single has_uv() result for install and launch.
- Template registry guard now enforces both directions (registry <-> shipped dirs).
- Wheel excludes __pycache__/*.pyc so stale bytecode can't ship (verified).

Tests added for the 502 paths, the logged-out launch hint, and the shipped-but-
unregistered guard. 608 passed, ruff + format + mypy clean.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/claude.py                    | 31 +++++--------------
 aai_cli/commands/init.py                      | 23 +++++++++++---
 .../init/templates/transcribe/api/index.py    | 17 ++++++++--
 aai_cli/init/templates/transcribe/index.html  | 24 ++++++++------
 .../templates/transcribe/requirements.txt     |  2 +-
 aai_cli/{init => }/steps.py                   | 12 +++++--
 pyproject.toml                                |  4 +++
 tests/test_claude_render.py                   |  4 +--
 tests/test_init_command.py                    | 21 +++++++++++++
 tests/test_init_template_transcribe.py        | 18 +++++++++++
 tests/test_init_templates.py                  | 11 +++++++
 tests/{test_init_steps.py => test_steps.py}   | 12 ++++---
 12 files changed, 128 insertions(+), 51 deletions(-)
 rename aai_cli/{init => }/steps.py (50%)
 rename tests/{test_init_steps.py => test_steps.py} (56%)

diff --git a/aai_cli/commands/claude.py b/aai_cli/commands/claude.py
index ef8ccb09..dd21c315 100644
--- a/aai_cli/commands/claude.py
+++ b/aai_cli/commands/claude.py
@@ -4,14 +4,13 @@
 import shutil
 import subprocess
 from pathlib import Path
-from typing import TypedDict
 
 import typer
-from rich.markup import escape
 
-from aai_cli import output, theme
+from aai_cli import output
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import UsageError
+from aai_cli.steps import Step, render_steps
 
 app = typer.Typer(
     help="Wire up Claude Code for AssemblyAI (docs MCP + skill).",
@@ -22,14 +21,7 @@
 MCP_URL = "https://mcp.assemblyai.com/docs"
 SKILL_REPO = "AssemblyAI/assemblyai-skill"
 _VALID_SCOPES = ("user", "project", "local")
-
-
-class Step(TypedDict):
-    """One line of setup output: a named step, its status, and a human detail."""
-
-    name: str
-    status: str
-    detail: str
+_STEPS_HEADING = "AssemblyAI coding-agent setup:"
 
 
 def _run(cmd: list[str], *, timeout: float = 120) -> subprocess.CompletedProcess:
@@ -191,15 +183,8 @@ def _remove_skill() -> Step:
     return {"name": "skill", "status": "removed", "detail": str(_skill_dir())}
 
 
-def _render_steps(data: dict[str, list[Step]]) -> str:
-    lines = []
-    for s in data["steps"]:
-        style = theme.status_style(s["status"])
-        lines.append(
-            f"  {escape(s['name'])}: "
-            f"[{style}]{escape(s['status'])}[/{style}] — {escape(s['detail'])}"
-        )
-    return "[aai.heading]AssemblyAI coding-agent setup:[/aai.heading]\n" + "\n".join(lines)
+def _render(data: dict[str, list[Step]]) -> str:
+    return render_steps(data["steps"], heading=_STEPS_HEADING)
 
 
 @app.command()
@@ -224,7 +209,7 @@ def body(_state: AppState, json_mode: bool) -> None:
                 f"Invalid --scope '{scope}'. Choose one of: {', '.join(_VALID_SCOPES)}."
             )
         steps = [_install_mcp(scope, force), _install_skill(force)]
-        output.emit({"steps": steps}, _render_steps, json_mode=json_mode)
+        output.emit({"steps": steps}, _render, json_mode=json_mode)
         if any(s["status"] == "failed" for s in steps):
             raise typer.Exit(code=1)
 
@@ -240,7 +225,7 @@ def status(
 
     def body(_state: AppState, json_mode: bool) -> None:
         steps = [_mcp_status(), _skill_status()]
-        output.emit({"steps": steps}, _render_steps, json_mode=json_mode)
+        output.emit({"steps": steps}, _render, json_mode=json_mode)
 
     run_command(ctx, body, json=json_out)
 
@@ -266,7 +251,7 @@ def body(_state: AppState, json_mode: bool) -> None:
                 f"Invalid --scope '{scope}'. Choose one of: {', '.join(_VALID_SCOPES)}."
             )
         steps = [_remove_mcp(scope), _remove_skill()]
-        output.emit({"steps": steps}, _render_steps, json_mode=json_mode)
+        output.emit({"steps": steps}, _render, json_mode=json_mode)
         if any(s["status"] == "failed" for s in steps):
             raise typer.Exit(code=1)
 
diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index 8541dfd1..8dcf4e60 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -7,10 +7,10 @@
 import typer
 from rich.markup import escape
 
-from aai_cli import environments, output
+from aai_cli import environments, output, steps
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import CLIError
-from aai_cli.init import keys, runner, scaffold, steps, templates
+from aai_cli.init import keys, runner, scaffold, templates
 
 # Single-command sub-typer flattened to `aai init` (the exact pattern `aai transcribe`
 # uses): one @app.command() named `init`, registered via app.add_typer(init.app) with
@@ -127,11 +127,11 @@ def body(state: AppState, json_mode: bool) -> None:
                 }
             )
 
+        use_uv = runner.has_uv()
         will_launch = not no_install and api_key is not None
         if no_install:
             report.append({"name": "install", "status": "skipped", "detail": "--no-install"})
         else:
-            use_uv = runner.has_uv()
             setup = runner.run_setup(target, use_uv=use_uv)
             if setup.returncode != 0:
                 report.append(
@@ -151,7 +151,20 @@ def body(state: AppState, json_mode: bool) -> None:
                     }
                 )
 
-        output.emit(report, lambda d: steps.render_steps(d), json_mode=json_mode)
+        # Deps are installed but there's no key, so the server can't start — say so
+        # rather than exiting silently.
+        if not no_install and api_key is None:
+            report.append(
+                {
+                    "name": "launch",
+                    "status": "skipped",
+                    "detail": f"no API key; run `aai login`, then: cd {target} && uv run uvicorn api.index:app",
+                }
+            )
+
+        output.emit(
+            report, lambda d: steps.render_steps(d, heading="aai init:"), json_mode=json_mode
+        )
         if any(s["status"] == "failed" for s in report):
             raise typer.Exit(code=1)
 
@@ -163,7 +176,7 @@ def body(state: AppState, json_mode: bool) -> None:
                     f"[aai.heading]Starting[/aai.heading] {escape(url)}  (Ctrl-C to stop)"
                 )
             code = runner.launch_and_open(
-                target, port=chosen_port, use_uv=runner.has_uv(), open_browser=not no_open
+                target, port=chosen_port, use_uv=use_uv, open_browser=not no_open
             )
             if code:
                 raise typer.Exit(code=code)
diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/transcribe/api/index.py
index 8716b886..f8b4401e 100644
--- a/aai_cli/init/templates/transcribe/api/index.py
+++ b/aai_cli/init/templates/transcribe/api/index.py
@@ -60,7 +60,12 @@ def index() -> FileResponse:
 
 def _submit(audio: str) -> dict[str, str]:
     """Submit an audio reference (local file path or public URL); return its id."""
-    transcript = aai.Transcriber().submit(audio, config=CONFIG)
+    try:
+        transcript = aai.Transcriber().submit(audio, config=CONFIG)
+    except Exception as exc:  # missing/invalid key, network, etc. -> clean error, not a 500
+        raise HTTPException(
+            status_code=502, detail=f"Could not start transcription: {exc}"
+        ) from exc
     return {"id": transcript.id}
 
 
@@ -69,7 +74,10 @@ async def transcribe(file: UploadFile) -> dict[str, str]:
     suffix = Path(file.filename or "audio").suffix
     tmp = Path(tempfile.gettempdir()) / f"aai-{uuid.uuid4().hex}{suffix}"
     tmp.write_bytes(await file.read())
-    return _submit(str(tmp))
+    try:
+        return _submit(str(tmp))
+    finally:
+        tmp.unlink(missing_ok=True)  # the upload is sent during submit; don't leave it on disk
 
 
 @app.post("/api/transcribe-url")
@@ -104,7 +112,10 @@ def status(transcript_id: str) -> dict[str, object]:
     # finishes (it calls wait_for_completion) — wrong for a poll endpoint, and it
     # would time out on serverless. api.get_transcript does a single request and
     # uses the SDK's configured client (auth + region from aai.settings).
-    t = get_transcript(Client.get_default().http_client, transcript_id)
+    try:
+        t = get_transcript(Client.get_default().http_client, transcript_id)
+    except Exception as exc:  # missing key (ValueError), HTTP/network error -> clean 502
+        raise HTTPException(status_code=502, detail=f"Could not fetch transcript: {exc}") from exc
     if t.status == aai.TranscriptStatus.error:
         raise HTTPException(status_code=502, detail=t.error or "Transcription failed")
     if t.status == aai.TranscriptStatus.completed:
diff --git a/aai_cli/init/templates/transcribe/index.html b/aai_cli/init/templates/transcribe/index.html
index c27a0372..0ff894a3 100644
--- a/aai_cli/init/templates/transcribe/index.html
+++ b/aai_cli/init/templates/transcribe/index.html
@@ -164,10 +164,15 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
       tabsEl.innerHTML = viewEl.innerHTML = answerEl.textContent = "";
       askPanel.hidden = true;
       currentId = null;
+      speakerSeen = {};
       setStatus("Uploading…", "working");
-      const res = await submit();
-      if (!res.ok) return fail(await res.text());
-      poll((await res.json()).id);
+      try {
+        const res = await submit();
+        if (!res.ok) return fail(await res.text());
+        await poll((await res.json()).id);
+      } catch (e) {
+        fail(e.message || String(e));  // network/parse errors don't leave the UI stuck
+      }
     }
 
     async function poll(id) {
@@ -175,7 +180,8 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
       const res = await fetch("/api/status/" + id);
       if (!res.ok) return fail(await res.text());
       const data = await res.json();
-      if (data.status !== "completed") return void setTimeout(() => poll(id), 2000);
+      if (data.status !== "completed")
+        return void setTimeout(() => poll(id).catch((e) => fail(String(e))), 2000);
       setStatus("✓ Done", "done");
       busy(false);
       currentId = id;
@@ -200,12 +206,12 @@ <h1>🎧 Transcribe a pre-recorded file</h1>
       }
     }
 
-    // --- speaker colors --------------------------------------------------
+    // --- speaker colors (reset each transcription via start()) -----------
     const PALETTE = ["#4338ca", "#0d9488", "#b45309", "#be185d", "#15803d", "#7c3aed"];
-    const speakerColor = (() => {
-      const seen = {};
-      return (spk) => (seen[spk] ??= PALETTE[Object.keys(seen).length % PALETTE.length]);
-    })();
+    let speakerSeen = {};
+    function speakerColor(spk) {
+      return (speakerSeen[spk] ??= PALETTE[Object.keys(speakerSeen).length % PALETTE.length]);
+    }
 
     // --- build the tabbed explorer --------------------------------------
     function explore(t) {
diff --git a/aai_cli/init/templates/transcribe/requirements.txt b/aai_cli/init/templates/transcribe/requirements.txt
index 0a6b9dfc..67a3b4c6 100644
--- a/aai_cli/init/templates/transcribe/requirements.txt
+++ b/aai_cli/init/templates/transcribe/requirements.txt
@@ -1,6 +1,6 @@
 fastapi
 uvicorn
-assemblyai
+assemblyai>=0.64,<1
 python-dotenv
 python-multipart
 openai
diff --git a/aai_cli/init/steps.py b/aai_cli/steps.py
similarity index 50%
rename from aai_cli/init/steps.py
rename to aai_cli/steps.py
index a1159c2f..3172f223 100644
--- a/aai_cli/init/steps.py
+++ b/aai_cli/steps.py
@@ -1,4 +1,3 @@
-# aai_cli/init/steps.py
 from __future__ import annotations
 
 from typing import TypedDict
@@ -9,12 +8,19 @@
 
 
 class Step(TypedDict):
+    """One line of multi-step command output: a named step, its status, and a detail."""
+
     name: str
     status: str
     detail: str
 
 
-def render_steps(items: list[Step]) -> str:
+def render_steps(items: list[Step], *, heading: str) -> str:
+    """Render steps as a themed heading followed by one status-styled line each.
+
+    Shared by the multi-step commands (`aai init`, `aai claude`); each passes its
+    own heading.
+    """
     lines = []
     for s in items:
         style = theme.status_style(s["status"])
@@ -22,4 +28,4 @@ def render_steps(items: list[Step]) -> str:
             f"  {escape(s['name'])}: "
             f"[{style}]{escape(s['status'])}[/{style}] — {escape(s['detail'])}"
         )
-    return "[aai.heading]aai init:[/aai.heading]\n" + "\n".join(lines)
+    return f"[aai.heading]{escape(heading)}[/aai.heading]\n" + "\n".join(lines)
diff --git a/pyproject.toml b/pyproject.toml
index 07eab844..fe03da0b 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -67,7 +67,11 @@ aai = "aai_cli.main:run"
 
 [tool.hatch.build.targets.wheel]
 packages = ["aai_cli"]
+# Force-include the committed template files (incl. renamed dotfiles); the `**` glob
+# would otherwise also sweep in __pycache__/*.pyc left by importing a template during
+# tests, so exclude those from the wheel.
 artifacts = ["aai_cli/init/templates/**"]
+exclude = ["**/__pycache__", "**/*.pyc"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
diff --git a/tests/test_claude_render.py b/tests/test_claude_render.py
index 079299ff..ed90ae50 100644
--- a/tests/test_claude_render.py
+++ b/tests/test_claude_render.py
@@ -1,7 +1,7 @@
 import io
 
 from aai_cli import theme
-from aai_cli.commands.claude import _render_steps
+from aai_cli.commands.claude import _render
 
 
 def test_render_steps_colors_status():
@@ -11,7 +11,7 @@ def test_render_steps_colors_status():
             {"name": "skill", "status": "failed", "detail": "nope"},
         ]
     }
-    rendered = _render_steps(data)
+    rendered = _render(data)
     # The markup string carries the semantic style tags per status...
     assert "[aai.success]installed[/aai.success]" in rendered
     assert "[aai.error]failed[/aai.error]" in rendered
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
index dacbd89e..5f7719c8 100644
--- a/tests/test_init_command.py
+++ b/tests/test_init_command.py
@@ -20,6 +20,27 @@ def test_init_writes_key_from_env(tmp_path, monkeypatch):
     assert "ASSEMBLYAI_API_KEY=sk-from-env" in (tmp_path / "myapp" / ".env").read_text()
 
 
+def test_init_logged_out_installs_but_skips_launch_with_hint(tmp_path, monkeypatch):
+    # Logged out + install: deps install, but the server can't start without a key —
+    # the report must say so (and must not launch) rather than exiting silently.
+    import subprocess
+
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        "aai_cli.init.runner.run_setup",
+        lambda *a, **k: subprocess.CompletedProcess([], 0, "", ""),
+    )
+    launched = {"v": False}
+    monkeypatch.setattr(
+        "aai_cli.init.runner.launch_and_open",
+        lambda *a, **k: launched.__setitem__("v", True) or 0,
+    )
+    result = runner.invoke(app, ["init", "transcribe", "app"])  # no --no-install, logged out
+    assert result.exit_code == 0, result.output
+    assert launched["v"] is False
+    assert "aai login" in result.output
+
+
 def test_init_writes_base_url_for_active_env(tmp_path, monkeypatch):
     # The generated .env pins the app to the CLI's active environment hosts.
     monkeypatch.chdir(tmp_path)
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index 3667fb6a..7c3b32c1 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -163,3 +163,21 @@ def test_status_returns_502_on_error(monkeypatch):
     client = TestClient(app)
     resp = client.get("/api/status/t-bad")
     assert resp.status_code == 502
+
+
+def test_submit_surfaces_sdk_exception_as_502_not_500(monkeypatch):
+    # A missing/invalid key makes the SDK raise; the endpoint must return a clean 502,
+    # not let the exception bubble into a 500 traceback.
+    app, fake, _api = _load_app(monkeypatch)
+    fake.Transcriber.return_value.submit.side_effect = ValueError("Please provide an API key")
+    client = TestClient(app)
+    resp = client.post("/api/transcribe-url", json={"url": "https://example.com/a.mp3"})
+    assert resp.status_code == 502
+
+
+def test_status_surfaces_sdk_exception_as_502_not_500(monkeypatch):
+    app, _aai, fake_api = _load_app(monkeypatch)
+    fake_api.get_transcript.side_effect = RuntimeError("network down")
+    client = TestClient(app)
+    resp = client.get("/api/status/t-x")
+    assert resp.status_code == 502
diff --git a/tests/test_init_templates.py b/tests/test_init_templates.py
index bc0a9529..9f8670c5 100644
--- a/tests/test_init_templates.py
+++ b/tests/test_init_templates.py
@@ -25,6 +25,17 @@ def test_every_registered_template_has_a_directory():
         )
 
 
+def test_every_shipped_directory_is_registered():
+    # The other direction: a template dir that ships but isn't registered is invisible
+    # in the picker and unreachable via `aai init <id>`. Together with the test above
+    # this enforces registry == shipped directories.
+    for path in _TEMPLATES_ROOT.iterdir():
+        if path.is_dir() and not path.name.startswith("__"):
+            assert path.name in templates.TEMPLATES, (
+                f"aai_cli/init/templates/{path.name}/ ships but isn't registered in TEMPLATES"
+            )
+
+
 def test_title_for_known_and_unknown():
     assert "Transcribe" in templates.title_for("transcribe")
     assert templates.title_for("nope") == "nope"  # falls back to the raw id
diff --git a/tests/test_init_steps.py b/tests/test_steps.py
similarity index 56%
rename from tests/test_init_steps.py
rename to tests/test_steps.py
index 2be40d6a..915bc41b 100644
--- a/tests/test_init_steps.py
+++ b/tests/test_steps.py
@@ -1,4 +1,4 @@
-from aai_cli.init import steps
+from aai_cli import steps
 
 
 def test_render_steps_includes_name_status_detail():
@@ -6,7 +6,7 @@ def test_render_steps_includes_name_status_detail():
         {"name": "scaffold", "status": "created", "detail": "./my-app"},
         {"name": "install", "status": "skipped", "detail": "--no-install"},
     ]
-    out = steps.render_steps(data)
+    out = steps.render_steps(data, heading="aai init:")
     assert "scaffold" in out
     assert "created" in out
     assert "./my-app" in out
@@ -14,6 +14,8 @@ def test_render_steps_includes_name_status_detail():
     assert "skipped" in out
 
 
-def test_render_steps_has_heading():
-    out = steps.render_steps([{"name": "scaffold", "status": "created", "detail": "x"}])
-    assert "init" in out.lower() or "AssemblyAI" in out
+def test_render_steps_uses_given_heading():
+    out = steps.render_steps(
+        [{"name": "scaffold", "status": "created", "detail": "x"}], heading="aai init:"
+    )
+    assert "aai init:" in out

From 6318eabec3bdaef69fa6d311def3d014ef84bea9 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 17:41:21 -0700
Subject: [PATCH 30/32] feat(init): add stream (live captions) + agent (voice)
 templates

- stream: browser captures mic and connects directly to AssemblyAI Streaming v3
  (u3-rt-pro) with a one-time token from /api/token; live partial/final captions.
- agent: browser connects directly to the Voice Agent API (speech->LLM->speech) with
  a Bearer-auth one-time token; mic capture + base64 PCM playback with barge-in.
  Fix: reply.audio carries base64 in the data field (not audio) so TTS now plays;
  resume() the audio contexts in case they start suspended after getUserMedia.
- Generalize scaffold to write the active environment hosts (base/llm/streaming/
  agents) into .env via an env_vars dict; templates honor them, default to production.
- Registry ships transcribe (with built-in LLM chat), stream, agent (no separate
  llm template; that lives in transcribe).
- Tests: token endpoints for stream/agent incl. raw-key vs Bearer auth, reply.audio
  data-field guard; contract suite auto-covers all three templates. 624 passed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py                      |  15 +-
 aai_cli/init/scaffold.py                      |  14 +-
 aai_cli/init/templates.py                     |  15 +-
 aai_cli/init/templates/agent/README.md        |  29 +++
 aai_cli/init/templates/agent/api/index.py     |  49 +++++
 aai_cli/init/templates/agent/env.example      |   3 +
 aai_cli/init/templates/agent/gitignore        |   3 +
 aai_cli/init/templates/agent/index.html       | 191 ++++++++++++++++++
 aai_cli/init/templates/agent/requirements.txt |   4 +
 aai_cli/init/templates/agent/vercel.json      |   6 +
 aai_cli/init/templates/stream/README.md       |  28 +++
 aai_cli/init/templates/stream/api/index.py    |  49 +++++
 aai_cli/init/templates/stream/env.example     |   3 +
 aai_cli/init/templates/stream/gitignore       |   3 +
 aai_cli/init/templates/stream/index.html      | 137 +++++++++++++
 .../init/templates/stream/requirements.txt    |   4 +
 aai_cli/init/templates/stream/vercel.json     |   6 +
 pyproject.toml                                |   2 +-
 tests/test_init_command.py                    |  10 +-
 tests/test_init_scaffold.py                   |  26 +--
 tests/test_init_template_agent.py             |  65 ++++++
 tests/test_init_template_stream.py            |  58 ++++++
 22 files changed, 678 insertions(+), 42 deletions(-)
 create mode 100644 aai_cli/init/templates/agent/README.md
 create mode 100644 aai_cli/init/templates/agent/api/index.py
 create mode 100644 aai_cli/init/templates/agent/env.example
 create mode 100644 aai_cli/init/templates/agent/gitignore
 create mode 100644 aai_cli/init/templates/agent/index.html
 create mode 100644 aai_cli/init/templates/agent/requirements.txt
 create mode 100644 aai_cli/init/templates/agent/vercel.json
 create mode 100644 aai_cli/init/templates/stream/README.md
 create mode 100644 aai_cli/init/templates/stream/api/index.py
 create mode 100644 aai_cli/init/templates/stream/env.example
 create mode 100644 aai_cli/init/templates/stream/gitignore
 create mode 100644 aai_cli/init/templates/stream/index.html
 create mode 100644 aai_cli/init/templates/stream/requirements.txt
 create mode 100644 aai_cli/init/templates/stream/vercel.json
 create mode 100644 tests/test_init_template_agent.py
 create mode 100644 tests/test_init_template_stream.py

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index 8dcf4e60..f263f84f 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -107,13 +107,14 @@ def body(state: AppState, json_mode: bool) -> None:
         # Pin the app to the active environment's hosts so a sandbox key (minted by
         # `aai login` against a non-prod env) isn't rejected by the production defaults.
         env = environments.active()
-        scaffold.scaffold(
-            chosen,
-            target,
-            api_key=api_key,
-            base_url=env.api_base,
-            llm_gateway_url=env.llm_gateway_base,
-        )
+        env_vars = {
+            "ASSEMBLYAI_BASE_URL": env.api_base,
+            "ASSEMBLYAI_LLM_GATEWAY_URL": env.llm_gateway_base,
+            "ASSEMBLYAI_STREAMING_HOST": env.streaming_host,
+            # Voice Agent host mirrors the streaming host's naming across environments.
+            "ASSEMBLYAI_AGENTS_HOST": env.streaming_host.replace("streaming", "agents", 1),
+        }
+        scaffold.scaffold(chosen, target, api_key=api_key, env_vars=env_vars)
 
         report: list[steps.Step] = [
             {"name": "scaffold", "status": "created", "detail": str(target)}
diff --git a/aai_cli/init/scaffold.py b/aai_cli/init/scaffold.py
index f103b49e..cb412a37 100644
--- a/aai_cli/init/scaffold.py
+++ b/aai_cli/init/scaffold.py
@@ -69,22 +69,18 @@ def scaffold(
     target: Path,
     *,
     api_key: str | None,
-    base_url: str | None = None,
-    llm_gateway_url: str | None = None,
+    env_vars: dict[str, str] | None = None,
 ) -> Path:
     """Copy the template into `target` and write `.env`. Returns `target`.
 
-    `base_url`/`llm_gateway_url`, when given, pin the generated app to the same
-    AssemblyAI environment the key was minted for (e.g. a sandbox) — otherwise a
-    sandbox key would be rejected by the production defaults.
+    `env_vars` (the active environment's hosts) are appended to `.env` so the generated
+    app targets the same AssemblyAI environment the key was minted for — otherwise a
+    sandbox key would be rejected by the production defaults the templates fall back to.
     """
     root = _template_root(template)
     target.mkdir(parents=True, exist_ok=True)
     _copy_tree(root, target)
     lines = [f"ASSEMBLYAI_API_KEY={api_key or PLACEHOLDER_KEY}"]
-    if base_url:
-        lines.append(f"ASSEMBLYAI_BASE_URL={base_url}")
-    if llm_gateway_url:
-        lines.append(f"ASSEMBLYAI_LLM_GATEWAY_URL={llm_gateway_url}")
+    lines += [f"{k}={v}" for k, v in (env_vars or {}).items()]
     (target / ".env").write_text("\n".join(lines) + "\n")
     return target
diff --git a/aai_cli/init/templates.py b/aai_cli/init/templates.py
index 27238135..912ef1e0 100644
--- a/aai_cli/init/templates.py
+++ b/aai_cli/init/templates.py
@@ -2,17 +2,16 @@
 
 # id -> human-facing title shown in the picker. Ids mirror the CLI's commands.
 #
-# Only list templates whose directory actually ships under templates/<id>/ — the
-# picker must never advertise a template that would crash on scaffold. The design
-# covers four (transcribe, stream, agent, llm); the latter three are added here as
-# their template directories land in follow-on PRs. A test enforces registry ==
-# shipped directories.
+# Every id here MUST have a directory under templates/<id>/ (a test enforces both
+# directions) — the picker must never advertise a template that would crash on scaffold.
 TEMPLATES: dict[str, str] = {
-    "transcribe": "Transcribe a pre-recorded file",
+    "transcribe": "Transcribe a pre-recorded file (+ chat with it via LLM Gateway)",
+    "stream": "Live captions (mic → browser)",
+    "agent": "Talk to a voice agent",
 }
 
-# Display order for the picker and `--help`.
-TEMPLATE_ORDER: tuple[str, ...] = ("transcribe",)
+# Display order for the picker and `--help`, matching the CLI's command order.
+TEMPLATE_ORDER: tuple[str, ...] = ("transcribe", "stream", "agent")
 
 
 def is_template(name: str) -> bool:
diff --git a/aai_cli/init/templates/agent/README.md b/aai_cli/init/templates/agent/README.md
new file mode 100644
index 00000000..e57a5548
--- /dev/null
+++ b/aai_cli/init/templates/agent/README.md
@@ -0,0 +1,29 @@
+# Talk to a voice agent — AssemblyAI Voice Agent starter
+
+Click connect and talk to a voice agent: speech in → LLM → speech out, with built-in
+turn detection, TTS, and barge-in. The browser connects **directly** to AssemblyAI's
+Voice Agent WebSocket using a one-time token minted by the backend, so your API key
+never reaches the client and no audio is proxied through your server.
+
+## Run locally
+
+```sh
+uvicorn api.index:app --reload --port 3000
+# open http://localhost:3000  (allow microphone access; headphones recommended)
+```
+
+`ASSEMBLYAI_API_KEY` is read from `.env` (created for you if you ran `aai init`).
+The Voice Agent API requires a plan with access enabled.
+
+## Deploy to Vercel
+
+Push this folder to a Git repo and import it on Vercel. Set `ASSEMBLYAI_API_KEY` as a
+Vercel environment variable (the local `.env` is git-ignored). The backend is just the
+`/api/token` function; the WebSocket runs browser → AssemblyAI, so nothing long-running
+is needed.
+
+## Ideas to extend
+
+- Change the `greeting`, `system_prompt`, or `voice` in `index.html`'s `session.update`.
+- Add tools (function calling) so the agent can look things up or take actions.
+- Tune `input.turn_detection` (`min_silence`/`max_silence`) for your use case.
diff --git a/aai_cli/init/templates/agent/api/index.py b/aai_cli/init/templates/agent/api/index.py
new file mode 100644
index 00000000..452d0488
--- /dev/null
+++ b/aai_cli/init/templates/agent/api/index.py
@@ -0,0 +1,49 @@
+"""Talk to a voice agent — AssemblyAI Voice Agent starter (FastAPI).
+
+The browser connects directly to AssemblyAI's Voice Agent WebSocket (speech-in → LLM →
+speech-out, with built-in turn detection and TTS) using a short-lived, single-use token
+minted here — so your API key never reaches the client.
+
+  POST /api/token -> {"token": ..., "ws_url": "wss://.../v1/ws"}
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import httpx
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+
+load_dotenv()
+API_KEY = os.environ.get("ASSEMBLYAI_API_KEY", "")
+# `aai init` writes this for you; defaults to production. (No scheme — host only.)
+AGENTS_HOST = os.environ.get("ASSEMBLYAI_AGENTS_HOST", "agents.assemblyai.com")
+
+ROOT = Path(__file__).resolve().parent.parent
+app = FastAPI()
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(ROOT / "index.html")
+
+
+@app.post("/api/token")
+def token() -> dict[str, str]:
+    """Mint a one-time Voice Agent token. The browser uses it to open the WebSocket."""
+    # NOTE: the Voice Agent token uses Bearer auth (unlike the streaming token).
+    try:
+        resp = httpx.get(
+            f"https://{AGENTS_HOST}/v1/token",
+            params={"expires_in_seconds": 60},
+            headers={"Authorization": f"Bearer {API_KEY}"},
+        )
+        resp.raise_for_status()
+    except Exception as exc:  # missing/invalid key, network -> clean 502, not a 500
+        raise HTTPException(
+            status_code=502, detail=f"Could not mint voice-agent token: {exc}"
+        ) from exc
+    return {"token": resp.json()["token"], "ws_url": f"wss://{AGENTS_HOST}/v1/ws"}
diff --git a/aai_cli/init/templates/agent/env.example b/aai_cli/init/templates/agent/env.example
new file mode 100644
index 00000000..1a4621d3
--- /dev/null
+++ b/aai_cli/init/templates/agent/env.example
@@ -0,0 +1,3 @@
+ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
+# Optional — target a non-production AssemblyAI environment (aai init fills this in):
+# ASSEMBLYAI_AGENTS_HOST=agents.assemblyai.com
diff --git a/aai_cli/init/templates/agent/gitignore b/aai_cli/init/templates/agent/gitignore
new file mode 100644
index 00000000..5b01785a
--- /dev/null
+++ b/aai_cli/init/templates/agent/gitignore
@@ -0,0 +1,3 @@
+.env
+.venv
+__pycache__/
diff --git a/aai_cli/init/templates/agent/index.html b/aai_cli/init/templates/agent/index.html
new file mode 100644
index 00000000..d59935f0
--- /dev/null
+++ b/aai_cli/init/templates/agent/index.html
@@ -0,0 +1,191 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Talk to a voice agent · AssemblyAI</title>
+  <style>
+    :root { --accent: #4338ca; --line: #e5e7eb; --muted: #6b7280; --bg: #f8fafc; }
+    * { box-sizing: border-box; }
+    body { font: 15px/1.6 -apple-system, system-ui, sans-serif; color: #111827;
+           background: var(--bg); margin: 0; padding: 48px 16px; }
+    main { max-width: 720px; margin: 0 auto; }
+    h1 { font-size: 22px; margin: 0 0 4px; }
+    .sub { color: var(--muted); margin: 0 0 24px; }
+    button { background: var(--accent); color: #fff; border: 0; border-radius: 9px;
+             padding: 11px 20px; font-size: 14px; font-weight: 600; cursor: pointer; }
+    button.live { background: #dc2626; }
+    #status { display: inline-block; margin-left: 12px; font-size: 13px; font-weight: 600;
+              padding: 5px 12px; border-radius: 999px; }
+    #status:empty { display: none; }
+    #status.live { background: #dcfce7; color: #166534; }
+    #status.idle { background: #f3f4f6; color: #4b5563; }
+    #status.error { background: #fee2e2; color: #991b1b; }
+    #log { margin-top: 24px; }
+    .turn { padding: 8px 0 8px 12px; border-left: 3px solid var(--line); margin: 8px 0; }
+    .turn.you { border-left-color: #0d9488; }
+    .turn.agent { border-left-color: var(--accent); }
+    .who { font-weight: 700; }
+    .turn.you .who { color: #0d9488; }
+    .turn.agent .who { color: var(--accent); }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>🗣️ Talk to a voice agent</h1>
+    <p class="sub">Click connect and just talk — speech in, LLM reply, speech out, with built-in turn detection and barge-in. The browser connects straight to AssemblyAI's Voice Agent API with a one-time token; your API key stays on the server. (Use headphones for the cleanest result.)</p>
+
+    <button id="conn">● Connect</button>
+    <span id="status"></span>
+
+    <div id="log"></div>
+  </main>
+
+  <script>
+    const connBtn = document.getElementById("conn");
+    const statusEl = document.getElementById("status");
+    const logEl = document.getElementById("log");
+
+    let ws = null, micStream = null, micCtx = null, micProc = null;
+    let playCtx = null, playHead = 0, sources = [];
+    let connected = false;
+
+    connBtn.addEventListener("click", () => (connected ? hangup() : connect().catch(fail)));
+    function setStatus(msg, state) { statusEl.textContent = msg; statusEl.className = state; }
+
+    async function connect() {
+      setStatus("Connecting…", "idle");
+      const res = await fetch("/api/token", { method: "POST" });
+      if (!res.ok) return fail(await res.text());
+      const { token, ws_url } = await res.json();
+
+      ws = new WebSocket(`${ws_url}?token=${encodeURIComponent(token)}`);
+      ws.onopen = () => {
+        ws.send(JSON.stringify({
+          type: "session.update",
+          session: {
+            system_prompt: "You are a friendly, concise voice assistant. Keep replies short and conversational.",
+            greeting: "Hi! I'm your AssemblyAI voice agent. What can I help you with?",
+            input: { format: { encoding: "audio/pcm" } },
+            output: { voice: "ivy", format: { encoding: "audio/pcm" } },
+          },
+        }));
+        startMic().catch(fail);
+      };
+      ws.onmessage = (e) => onEvent(JSON.parse(e.data));
+      ws.onerror = () => fail("WebSocket error");
+      ws.onclose = () => { if (connected) hangup(); };
+    }
+
+    async function startMic() {
+      micStream = await navigator.mediaDevices.getUserMedia({
+        audio: { echoCancellation: true, noiseSuppression: false },  // server runs its own voice focus
+      });
+      micCtx = new (window.AudioContext || window.webkitAudioContext)();
+      playCtx = new (window.AudioContext || window.webkitAudioContext)({ sampleRate: 24000 });
+      // Contexts can start suspended after the await above; resume so audio flows.
+      micCtx.resume();
+      playCtx.resume();
+      const source = micCtx.createMediaStreamSource(micStream);
+      micProc = micCtx.createScriptProcessor(4096, 1, 1);
+      source.connect(micProc);
+      micProc.connect(micCtx.destination);
+      micProc.onaudioprocess = (e) => {
+        if (!ws || ws.readyState !== WebSocket.OPEN) return;
+        const pcm = downsampleToPCM(e.inputBuffer.getChannelData(0), micCtx.sampleRate, 24000);
+        ws.send(JSON.stringify({ type: "input.audio", audio: bytesToB64(pcm) }));
+      };
+      connected = true;
+      connBtn.textContent = "■ Hang up";
+      connBtn.classList.add("live");
+      setStatus("● Connected — just talk", "live");
+    }
+
+    function onEvent(ev) {
+      switch (ev.type) {
+        case "transcript.user": return addTurn("you", "You", ev.text);
+        case "transcript.agent": return addTurn("agent", "Agent", ev.text);
+        case "reply.audio": return playChunk(ev.data);  // base64 PCM16 lives in `data`
+        case "input.speech.started": return bargeIn();  // user interrupted — drop queued agent audio
+        case "reply.done": if (ev.status === "interrupted") bargeIn(); return;
+        case "session.error": return fail(ev.message || "session error");
+      }
+    }
+
+    // --- agent audio playback (24 kHz PCM) -------------------------------
+    function playChunk(b64) {
+      const int16 = b64ToInt16(b64);
+      const buf = playCtx.createBuffer(1, int16.length, 24000);
+      const ch = buf.getChannelData(0);
+      for (let i = 0; i < int16.length; i++) ch[i] = int16[i] / 0x8000;
+      const src = playCtx.createBufferSource();
+      src.buffer = buf;
+      src.connect(playCtx.destination);
+      const startAt = Math.max(playCtx.currentTime, playHead);
+      src.start(startAt);
+      playHead = startAt + buf.duration;
+      sources.push(src);
+      src.onended = () => (sources = sources.filter((s) => s !== src));
+    }
+
+    function bargeIn() {
+      sources.forEach((s) => { try { s.stop(); } catch (_) {} });
+      sources = [];
+      playHead = 0;
+    }
+
+    function addTurn(cls, who, text) {
+      if (!text) return;
+      const div = document.createElement("div");
+      div.className = "turn " + cls;
+      div.innerHTML = `<span class="who">${who}:</span> `;
+      div.appendChild(document.createTextNode(text));
+      logEl.appendChild(div);
+      div.scrollIntoView({ block: "end" });
+    }
+
+    function hangup() {
+      connected = false;
+      connBtn.textContent = "● Connect";
+      connBtn.classList.remove("live");
+      setStatus("Disconnected", "idle");
+      bargeIn();
+      if (ws && ws.readyState === WebSocket.OPEN) ws.close();
+      if (micProc) micProc.disconnect();
+      if (micStream) micStream.getTracks().forEach((t) => t.stop());
+      if (micCtx) micCtx.close();
+      if (playCtx) playCtx.close();
+      ws = micProc = micStream = micCtx = playCtx = null;
+    }
+
+    function fail(msg) {
+      setStatus("Error: " + msg, "error");
+      if (connected) hangup();
+    }
+
+    // --- audio helpers ---------------------------------------------------
+    function downsampleToPCM(input, inRate, outRate) {
+      const ratio = inRate / outRate;
+      const outLen = Math.floor(input.length / ratio);
+      const out = new Int16Array(outLen);
+      for (let i = 0; i < outLen; i++) {
+        const s = Math.max(-1, Math.min(1, input[Math.floor(i * ratio)]));
+        out[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+      }
+      return out.buffer;
+    }
+    function bytesToB64(buf) {
+      let bin = "";
+      const bytes = new Uint8Array(buf);
+      for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i]);
+      return btoa(bin);
+    }
+    function b64ToInt16(b64) {
+      const bin = atob(b64);
+      const bytes = new Uint8Array(bin.length);
+      for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+      return new Int16Array(bytes.buffer);
+    }
+  </script>
+</body>
+</html>
diff --git a/aai_cli/init/templates/agent/requirements.txt b/aai_cli/init/templates/agent/requirements.txt
new file mode 100644
index 00000000..3263361e
--- /dev/null
+++ b/aai_cli/init/templates/agent/requirements.txt
@@ -0,0 +1,4 @@
+fastapi
+uvicorn
+httpx
+python-dotenv
diff --git a/aai_cli/init/templates/agent/vercel.json b/aai_cli/init/templates/agent/vercel.json
new file mode 100644
index 00000000..7f1e3652
--- /dev/null
+++ b/aai_cli/init/templates/agent/vercel.json
@@ -0,0 +1,6 @@
+{
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/index" },
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
diff --git a/aai_cli/init/templates/stream/README.md b/aai_cli/init/templates/stream/README.md
new file mode 100644
index 00000000..b618af19
--- /dev/null
+++ b/aai_cli/init/templates/stream/README.md
@@ -0,0 +1,28 @@
+# Live captions — AssemblyAI Streaming starter
+
+Click record and speak — your microphone streams to AssemblyAI's Streaming v3 API and
+transcribes in real time. The browser captures audio and connects **directly** to
+AssemblyAI using a one-time token minted by the backend, so your API key never reaches
+the client (and no audio is proxied through your server).
+
+## Run locally
+
+```sh
+uvicorn api.index:app --reload --port 3000
+# open http://localhost:3000  (allow microphone access)
+```
+
+`ASSEMBLYAI_API_KEY` is read from `.env` (created for you if you ran `aai init`).
+
+## Deploy to Vercel
+
+Push this folder to a Git repo and import it on Vercel. Set `ASSEMBLYAI_API_KEY` as a
+Vercel environment variable (the local `.env` is git-ignored). The backend is just the
+`/api/token` function; the WebSocket runs browser → AssemblyAI, so nothing long-running
+is needed. `vercel.json` routes the page and the function.
+
+## Ideas to extend
+
+- Add `keyterms_prompt` or a `prompt` for domain vocabulary (the demo uses `u3-rt-pro`).
+- Add `format_turns`/punctuation toggles, or speaker labels (`speaker_labels=true`).
+- Persist the final transcript, or pipe each finalized turn into the LLM Gateway.
diff --git a/aai_cli/init/templates/stream/api/index.py b/aai_cli/init/templates/stream/api/index.py
new file mode 100644
index 00000000..fc12a7fd
--- /dev/null
+++ b/aai_cli/init/templates/stream/api/index.py
@@ -0,0 +1,49 @@
+"""Live captions — AssemblyAI Streaming starter (FastAPI).
+
+The browser streams microphone audio directly to AssemblyAI's Streaming v3 WebSocket
+using a short-lived, single-use token minted here — so your API key never reaches the
+client.
+
+  POST /api/token -> {"token": ..., "ws_url": "wss://.../v3/ws"}
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import httpx
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from fastapi.responses import FileResponse
+
+load_dotenv()
+API_KEY = os.environ.get("ASSEMBLYAI_API_KEY", "")
+# `aai init` writes this for you; defaults to production. (No scheme — host only.)
+STREAMING_HOST = os.environ.get("ASSEMBLYAI_STREAMING_HOST", "streaming.assemblyai.com")
+
+ROOT = Path(__file__).resolve().parent.parent
+app = FastAPI()
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(ROOT / "index.html")
+
+
+@app.post("/api/token")
+def token() -> dict[str, str]:
+    """Mint a one-time streaming token. The browser uses it to open the WebSocket."""
+    # NOTE: the streaming token uses the raw API key as Authorization (no 'Bearer').
+    try:
+        resp = httpx.get(
+            f"https://{STREAMING_HOST}/v3/token",
+            params={"expires_in_seconds": 60},
+            headers={"Authorization": API_KEY},
+        )
+        resp.raise_for_status()
+    except Exception as exc:  # missing/invalid key, network -> clean 502, not a 500
+        raise HTTPException(
+            status_code=502, detail=f"Could not mint streaming token: {exc}"
+        ) from exc
+    return {"token": resp.json()["token"], "ws_url": f"wss://{STREAMING_HOST}/v3/ws"}
diff --git a/aai_cli/init/templates/stream/env.example b/aai_cli/init/templates/stream/env.example
new file mode 100644
index 00000000..ac8149ae
--- /dev/null
+++ b/aai_cli/init/templates/stream/env.example
@@ -0,0 +1,3 @@
+ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
+# Optional — target a non-production AssemblyAI environment (aai init fills this in):
+# ASSEMBLYAI_STREAMING_HOST=streaming.assemblyai.com
diff --git a/aai_cli/init/templates/stream/gitignore b/aai_cli/init/templates/stream/gitignore
new file mode 100644
index 00000000..5b01785a
--- /dev/null
+++ b/aai_cli/init/templates/stream/gitignore
@@ -0,0 +1,3 @@
+.env
+.venv
+__pycache__/
diff --git a/aai_cli/init/templates/stream/index.html b/aai_cli/init/templates/stream/index.html
new file mode 100644
index 00000000..bfa09698
--- /dev/null
+++ b/aai_cli/init/templates/stream/index.html
@@ -0,0 +1,137 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Live captions · AssemblyAI</title>
+  <style>
+    :root { --accent: #4338ca; --line: #e5e7eb; --muted: #6b7280; --bg: #f8fafc; }
+    * { box-sizing: border-box; }
+    body { font: 15px/1.6 -apple-system, system-ui, sans-serif; color: #111827;
+           background: var(--bg); margin: 0; padding: 48px 16px; }
+    main { max-width: 720px; margin: 0 auto; }
+    h1 { font-size: 22px; margin: 0 0 4px; }
+    .sub { color: var(--muted); margin: 0 0 24px; }
+    button { background: var(--accent); color: #fff; border: 0; border-radius: 9px;
+             padding: 11px 20px; font-size: 14px; font-weight: 600; cursor: pointer; }
+    button.rec { background: #dc2626; }
+    button:disabled { opacity: .55; cursor: default; }
+    #status { display: inline-block; margin-left: 12px; font-size: 13px; font-weight: 600;
+              padding: 5px 12px; border-radius: 999px; }
+    #status:empty { display: none; }
+    #status.live { background: #fee2e2; color: #991b1b; }
+    #status.idle { background: #f3f4f6; color: #4b5563; }
+    #status.error { background: #fee2e2; color: #991b1b; }
+    .caption { margin-top: 24px; font-size: 19px; line-height: 1.7; min-height: 120px;
+               background: #fff; border: 1px solid var(--line); border-radius: 12px; padding: 18px; }
+    .final { color: #111827; }
+    .partial { color: var(--muted); }
+  </style>
+</head>
+<body>
+  <main>
+    <h1>🎙️ Live captions</h1>
+    <p class="sub">Click record and talk — your mic streams to AssemblyAI and transcribes in real time. Audio goes straight from the browser to AssemblyAI with a one-time token; your API key stays on the server.</p>
+
+    <button id="rec">● Record</button>
+    <span id="status"></span>
+
+    <div class="caption"><span id="final" class="final"></span><span id="partial" class="partial"></span></div>
+  </main>
+
+  <script>
+    const recBtn = document.getElementById("rec");
+    const statusEl = document.getElementById("status");
+    const finalEl = document.getElementById("final");
+    const partialEl = document.getElementById("partial");
+
+    let ws = null;
+    let audioCtx = null;
+    let mediaStream = null;
+    let processor = null;
+    let recording = false;
+
+    recBtn.addEventListener("click", () => (recording ? stop() : start().catch(fail)));
+
+    function setStatus(msg, state) { statusEl.textContent = msg; statusEl.className = state; }
+
+    async function start() {
+      setStatus("Connecting…", "idle");
+      const res = await fetch("/api/token", { method: "POST" });
+      if (!res.ok) return fail(await res.text());
+      const { token, ws_url } = await res.json();
+
+      mediaStream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      audioCtx = new (window.AudioContext || window.webkitAudioContext)();
+      const source = audioCtx.createMediaStreamSource(mediaStream);
+      processor = audioCtx.createScriptProcessor(4096, 1, 1);
+
+      const params = new URLSearchParams({
+        token,
+        sample_rate: "16000",
+        encoding: "pcm_s16le",
+        speech_model: "u3-rt-pro",
+        format_turns: "true",
+      });
+      ws = new WebSocket(`${ws_url}?${params}`);
+      ws.binaryType = "arraybuffer";
+
+      ws.onopen = () => {
+        recording = true;
+        recBtn.textContent = "■ Stop";
+        recBtn.classList.add("rec");
+        setStatus("● Live", "live");
+        source.connect(processor);
+        processor.connect(audioCtx.destination);
+        processor.onaudioprocess = (e) => {
+          if (ws && ws.readyState === WebSocket.OPEN) {
+            ws.send(downsampleTo16kPCM(e.inputBuffer.getChannelData(0), audioCtx.sampleRate));
+          }
+        };
+      };
+      ws.onmessage = (e) => onMessage(JSON.parse(e.data));
+      ws.onerror = () => fail("WebSocket error");
+      ws.onclose = () => { if (recording) stop(); };
+    }
+
+    function onMessage(msg) {
+      if (msg.type !== "Turn") return;
+      if (msg.end_of_turn) {
+        finalEl.textContent += (msg.transcript || "") + " ";
+        partialEl.textContent = "";
+      } else {
+        partialEl.textContent = msg.transcript || "";
+      }
+    }
+
+    function stop() {
+      recording = false;
+      recBtn.textContent = "● Record";
+      recBtn.classList.remove("rec");
+      setStatus("Stopped", "idle");
+      if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "Terminate" }));
+      if (processor) processor.disconnect();
+      if (mediaStream) mediaStream.getTracks().forEach((t) => t.stop());
+      if (audioCtx) audioCtx.close();
+      ws = processor = mediaStream = audioCtx = null;
+    }
+
+    // Web Audio gives Float32 at the device rate (often 48k); the API wants 16k PCM16.
+    function downsampleTo16kPCM(input, inRate) {
+      const ratio = inRate / 16000;
+      const outLen = Math.floor(input.length / ratio);
+      const out = new Int16Array(outLen);
+      for (let i = 0; i < outLen; i++) {
+        const s = Math.max(-1, Math.min(1, input[Math.floor(i * ratio)]));
+        out[i] = s < 0 ? s * 0x8000 : s * 0x7fff;
+      }
+      return out.buffer;
+    }
+
+    function fail(msg) {
+      setStatus("Error: " + msg, "error");
+      if (recording) stop();
+    }
+  </script>
+</body>
+</html>
diff --git a/aai_cli/init/templates/stream/requirements.txt b/aai_cli/init/templates/stream/requirements.txt
new file mode 100644
index 00000000..3263361e
--- /dev/null
+++ b/aai_cli/init/templates/stream/requirements.txt
@@ -0,0 +1,4 @@
+fastapi
+uvicorn
+httpx
+python-dotenv
diff --git a/aai_cli/init/templates/stream/vercel.json b/aai_cli/init/templates/stream/vercel.json
new file mode 100644
index 00000000..7f1e3652
--- /dev/null
+++ b/aai_cli/init/templates/stream/vercel.json
@@ -0,0 +1,6 @@
+{
+  "rewrites": [
+    { "source": "/api/(.*)", "destination": "/api/index" },
+    { "source": "/(.*)", "destination": "/index.html" }
+  ]
+}
diff --git a/pyproject.toml b/pyproject.toml
index fe03da0b..5bd62099 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -107,4 +107,4 @@ ignore = ["E501", "B008", "S603", "S607"]
 
 [tool.ruff.lint.per-file-ignores]
 # Tests assert freely, use throwaway args/temp paths, and don't need pathlib/security lints.
-"tests/**" = ["S101", "S105", "S106", "S108", "ARG001", "ARG002", "ARG005", "PTH123", "SIM117"]
+"tests/**" = ["S101", "S105", "S106", "S107", "S108", "ARG001", "ARG002", "ARG005", "PTH123", "SIM117"]
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
index 5f7719c8..b9113f7c 100644
--- a/tests/test_init_command.py
+++ b/tests/test_init_command.py
@@ -124,10 +124,10 @@ def test_init_json_output_is_machine_readable(tmp_path, monkeypatch):
     assert any(step["name"] == "scaffold" and step["status"] == "created" for step in payload)
 
 
-def test_init_unshipped_template_errors_cleanly(tmp_path, monkeypatch):
-    # `stream` is in the design but its template doesn't ship yet, so it must not be
-    # registered — and picking it must give a clean error, not a FileNotFoundError.
+def test_init_unregistered_template_errors_cleanly(tmp_path, monkeypatch):
+    # `llm` isn't a separate template (it's folded into transcribe), so picking it must
+    # give a clean error, not a FileNotFoundError.
     monkeypatch.chdir(tmp_path)
-    result = runner.invoke(app, ["init", "stream", "s", "--no-install"])
+    result = runner.invoke(app, ["init", "llm", "x", "--no-install"])
     assert result.exit_code == 1
-    assert "stream" in result.output
+    assert "llm" in result.output
diff --git a/tests/test_init_scaffold.py b/tests/test_init_scaffold.py
index 514539bb..f60f6a7c 100644
--- a/tests/test_init_scaffold.py
+++ b/tests/test_init_scaffold.py
@@ -25,13 +25,23 @@ def test_scaffold_writes_env_with_key(tmp_path):
     assert "ASSEMBLYAI_API_KEY=sk-real-key" in env
 
 
-def test_scaffold_writes_base_url_when_given(tmp_path):
+def test_scaffold_writes_env_vars(tmp_path):
     target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key="k", base_url="https://api.sb.example")
-    assert "ASSEMBLYAI_BASE_URL=https://api.sb.example" in (target / ".env").read_text()
+    scaffold.scaffold(
+        "transcribe",
+        target,
+        api_key="k",
+        env_vars={
+            "ASSEMBLYAI_BASE_URL": "https://api.sb.example",
+            "ASSEMBLYAI_LLM_GATEWAY_URL": "https://llm.sb.example/v1",
+        },
+    )
+    env = (target / ".env").read_text()
+    assert "ASSEMBLYAI_BASE_URL=https://api.sb.example" in env
+    assert "ASSEMBLYAI_LLM_GATEWAY_URL=https://llm.sb.example/v1" in env
 
 
-def test_scaffold_omits_base_url_when_none(tmp_path):
+def test_scaffold_omits_env_vars_when_none(tmp_path):
     target = tmp_path / "app"
     scaffold.scaffold("transcribe", target, api_key="k")
     env = (target / ".env").read_text()
@@ -39,14 +49,6 @@ def test_scaffold_omits_base_url_when_none(tmp_path):
     assert "ASSEMBLYAI_LLM_GATEWAY_URL" not in env
 
 
-def test_scaffold_writes_llm_gateway_url_when_given(tmp_path):
-    target = tmp_path / "app"
-    scaffold.scaffold(
-        "transcribe", target, api_key="k", llm_gateway_url="https://llm.sb.example/v1"
-    )
-    assert "ASSEMBLYAI_LLM_GATEWAY_URL=https://llm.sb.example/v1" in (target / ".env").read_text()
-
-
 def test_scaffold_skips_pycache(tmp_path):
     # Importing a template's api/index.py during our own test run leaves a
     # __pycache__ next to it; the scaffolder must not copy that into the project.
diff --git a/tests/test_init_template_agent.py b/tests/test_init_template_agent.py
new file mode 100644
index 00000000..208b29f7
--- /dev/null
+++ b/tests/test_init_template_agent.py
@@ -0,0 +1,65 @@
+import importlib.util
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from fastapi.testclient import TestClient
+
+TEMPLATE_DIR = Path("aai_cli/init/templates/agent")
+
+
+def _load_app():
+    spec = importlib.util.spec_from_file_location("_tmpl_agent", TEMPLATE_DIR / "api" / "index.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _ok_response(token="tok-123"):
+    resp = MagicMock()
+    resp.json.return_value = {"token": token}
+    resp.raise_for_status.return_value = None
+    return resp
+
+
+def test_token_returns_token_and_agent_ws_url(monkeypatch):
+    mod = _load_app()
+    monkeypatch.setattr(mod.httpx, "get", lambda *a, **k: _ok_response())
+    resp = TestClient(mod.app).post("/api/token")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["token"] == "tok-123"
+    assert body["ws_url"].startswith("wss://") and body["ws_url"].endswith("/v1/ws")
+
+
+def test_token_uses_bearer_authorization_header(monkeypatch):
+    # The Voice Agent token uses Bearer auth (unlike the streaming token).
+    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "sk-test")
+    mod = _load_app()
+    captured = {}
+
+    def fake_get(url, params=None, headers=None):
+        captured.update(url=url, headers=headers)
+        return _ok_response()
+
+    monkeypatch.setattr(mod.httpx, "get", fake_get)
+    TestClient(mod.app).post("/api/token")
+    assert captured["headers"]["Authorization"] == "Bearer sk-test"
+    assert "/v1/token" in captured["url"]
+
+
+def test_page_reads_reply_audio_from_data_field():
+    # reply.audio carries the base64 PCM in `data` (not `audio`); guard the regression.
+    html = (TEMPLATE_DIR / "index.html").read_text()
+    assert "reply.audio" in html
+    assert "ev.data" in html
+
+
+def test_token_surfaces_error_as_502(monkeypatch):
+    mod = _load_app()
+
+    def boom(*a, **k):
+        raise RuntimeError("network down")
+
+    monkeypatch.setattr(mod.httpx, "get", boom)
+    resp = TestClient(mod.app).post("/api/token")
+    assert resp.status_code == 502
diff --git a/tests/test_init_template_stream.py b/tests/test_init_template_stream.py
new file mode 100644
index 00000000..1e8f2632
--- /dev/null
+++ b/tests/test_init_template_stream.py
@@ -0,0 +1,58 @@
+import importlib.util
+from pathlib import Path
+from unittest.mock import MagicMock
+
+from fastapi.testclient import TestClient
+
+TEMPLATE_DIR = Path("aai_cli/init/templates/stream")
+
+
+def _load_app():
+    spec = importlib.util.spec_from_file_location("_tmpl_stream", TEMPLATE_DIR / "api" / "index.py")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+def _ok_response(token="tok-123"):
+    resp = MagicMock()
+    resp.json.return_value = {"token": token}
+    resp.raise_for_status.return_value = None
+    return resp
+
+
+def test_token_returns_token_and_streaming_ws_url(monkeypatch):
+    mod = _load_app()
+    monkeypatch.setattr(mod.httpx, "get", lambda *a, **k: _ok_response())
+    resp = TestClient(mod.app).post("/api/token")
+    assert resp.status_code == 200
+    body = resp.json()
+    assert body["token"] == "tok-123"
+    assert body["ws_url"].startswith("wss://") and body["ws_url"].endswith("/v3/ws")
+
+
+def test_token_uses_raw_authorization_header(monkeypatch):
+    # The streaming token uses the raw key as Authorization (NOT Bearer).
+    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "sk-test")
+    mod = _load_app()
+    captured = {}
+
+    def fake_get(url, params=None, headers=None):
+        captured.update(url=url, headers=headers)
+        return _ok_response()
+
+    monkeypatch.setattr(mod.httpx, "get", fake_get)
+    TestClient(mod.app).post("/api/token")
+    assert captured["headers"]["Authorization"] == "sk-test"
+    assert "/v3/token" in captured["url"]
+
+
+def test_token_surfaces_error_as_502(monkeypatch):
+    mod = _load_app()
+
+    def boom(*a, **k):
+        raise RuntimeError("network down")
+
+    monkeypatch.setattr(mod.httpx, "get", boom)
+    resp = TestClient(mod.app).post("/api/token")
+    assert resp.status_code == 502

From b1e2e9fdc3e5f9e978d369682960ed1767d527d0 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 17:43:47 -0700
Subject: [PATCH 31/32] feat(init): Vercel-style 'AssemblyAI CLI <version>'
 banner on run

Printed at the top of an interactive aai init run (human output only; suppressed
in --json/agentic mode). Guard test included.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 aai_cli/commands/init.py   | 7 ++++++-
 tests/test_init_command.py | 9 +++++++++
 2 files changed, 15 insertions(+), 1 deletion(-)

diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index f263f84f..b983a971 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -7,7 +7,7 @@
 import typer
 from rich.markup import escape
 
-from aai_cli import environments, output, steps
+from aai_cli import __version__, environments, output, steps
 from aai_cli.context import AppState, run_command
 from aai_cli.errors import CLIError
 from aai_cli.init import keys, runner, scaffold, templates
@@ -77,6 +77,11 @@ def init(
     """Pick a template, scaffold it, install deps, launch the server, open the browser."""
 
     def body(state: AppState, json_mode: bool) -> None:
+        if not json_mode:
+            # Vercel-style banner at the top of the run.
+            output.console.print(
+                f"[aai.heading]AssemblyAI CLI[/aai.heading] [aai.muted]{__version__}[/aai.muted]"
+            )
         chosen = template
         if chosen is None:
             chosen = _pick_template()
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
index b9113f7c..944ae0cd 100644
--- a/tests/test_init_command.py
+++ b/tests/test_init_command.py
@@ -97,6 +97,15 @@ def test_init_appears_in_help():
     assert "init" in result.output
 
 
+def test_init_prints_cli_banner_in_human_mode(tmp_path, monkeypatch):
+    # Vercel-style header at the top of an interactive run (human output only).
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr("aai_cli.output._is_agentic", lambda: False)
+    result = runner.invoke(app, ["init", "transcribe", "x", "--no-install"])
+    assert result.exit_code == 0, result.output
+    assert "AssemblyAI CLI" in result.output
+
+
 def test_init_here_scaffolds_into_cwd(tmp_path, monkeypatch):
     work = tmp_path / "work"  # a fresh empty dir (tmp_path itself holds the test config/)
     work.mkdir()

From 5d5f95b73e7ce51023cf4f5737f79a87c9b5fdbb Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Thu, 4 Jun 2026 17:47:43 -0700
Subject: [PATCH 32/32] chore: remove specs/ design+plan docs from the repo

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 specs/2026-06-04-aai-init-design.md           |  229 ---
 ...2026-06-04-aai-init-core-and-transcribe.md | 1589 -----------------
 2 files changed, 1818 deletions(-)
 delete mode 100644 specs/2026-06-04-aai-init-design.md
 delete mode 100644 specs/plans/2026-06-04-aai-init-core-and-transcribe.md

diff --git a/specs/2026-06-04-aai-init-design.md b/specs/2026-06-04-aai-init-design.md
deleted file mode 100644
index 83cafbb6..00000000
--- a/specs/2026-06-04-aai-init-design.md
+++ /dev/null
@@ -1,229 +0,0 @@
-# `aai init` — interactive project scaffolder
-
-**Status:** Approved (design)
-**Date:** 2026-06-04
-
-## Summary
-
-Add an `aai init` command: a Vercel-style scaffolder that lets a user pick from
-four templates, then **copies a real, runnable Python web project**, installs its
-dependencies, starts a local server, and opens the browser — so the user can
-interact with an AssemblyAI capability immediately and then keep building.
-
-The generated project's prime directive: **the files must be as simple as
-possible** so a human (or Claude Code) can read and extend them right after
-creation. No build step, no framework magic — two files carry the real logic.
-
-## Goals
-
-- One command (`aai init`) takes a user from nothing to a running, browser-based
-  AssemblyAI demo.
-- Four templates covering the CLI's core capabilities: `transcribe`, `stream`,
-  `agent`, `llm`.
-- Generated code is flat, plain, and immediately editable.
-- The browser **never** receives the real API key.
-- Each template is **structured so Vercel can deploy it as-is** (static frontend +
-  a thin stateless backend). We add the conventional layout + a `vercel.json`, but
-  build **no** deploy tooling of our own (no Dockerfiles, deploy buttons, or
-  Cloudflare functions) — that would only overlap with what Vercel already does.
-
-## Non-goals
-
-- Replacing `aai samples create` (it coexists — see below).
-- A Node/JavaScript toolchain. Templates are Python backend + a single vanilla
-  HTML/JS page.
-- A reusable framework or component library. Each template is self-contained.
-
-## Relationship to existing commands
-
-- **`aai samples create`** stays as-is: the quick **single-script** scaffolder
-  (one `.py` file, terminal output, no browser). `aai init` is the **full
-  interactive project + browser** experience. Clear split: *samples = snippet,
-  init = app.*
-- Template `api/index.py` logic is kept consistent with `aai_cli/code_gen`'s
-  generators (same AssemblyAI call patterns), verified by a test. `code_gen`
-  remains the reference; templates are committed real files (Approach A below).
-
-## Architecture decision: ship real template projects (Approach A)
-
-The four templates live as **actual, committed, runnable project directories**
-inside the package (`aai_cli/init/templates/<id>/`). `aai init` *copies* the
-chosen one rather than rendering it from string templates.
-
-- The generated output **is** the files we hand-wrote and tested — no
-  template-rendering indirection between what we verify and what the user gets.
-  This is the simplest possible output, which is the core constraint.
-- Templates are runnable in-repo, so they are easy to test and dogfood.
-- Trade-off: some AssemblyAI call logic overlaps with `code_gen`. We keep them
-  honest with a smoke test that loads each template and an optional
-  reference-consistency check.
-
-(Rejected: generating everything from `code_gen` + a web shell. String
-templating produces more abstract/indirected code — the opposite of the
-"simple files Claude can improve" goal.)
-
-## Command surface
-
-```
-aai init [TEMPLATE] [DIRECTORY] [options]
-```
-
-- **No args** → arrow-key picker (`questionary`) for the template, then a prompt
-  for the directory (default `./<template>-app`).
-- **TEMPLATE** ids mirror the CLI commands for memorability: `transcribe`,
-  `stream`, `agent`, `llm`. Descriptive titles shown in the picker.
-- **Options:**
-  - `--no-install` — scaffold only; skip env creation, install, launch, open.
-  - `--no-open` — install + launch, but don't open the browser.
-  - `--force` — overwrite a non-empty target directory.
-  - `--here` — scaffold into the current directory.
-  - `--port` — server port (default `3000`; auto-increments if taken).
-  - `--json` — machine-readable step output.
-
-**Default behavior (no skip flags):** scaffold → install deps → launch server →
-open browser. Vercel-style "it just opens."
-
-## Scaffold layout (per template)
-
-Templates adopt **Vercel's conventional layout** so the exact same files run
-locally (via `uvicorn`) and deploy to Vercel untouched — see Deployment below.
-
-```
-<dir>/
-  api/index.py      # FastAPI ASGI app: loads key, mints temp tokens (+ upload/poll for transcribe & llm)
-  index.html        # one vanilla-JS page, no build step
-  vercel.json       # routes "/" to index.html and "/api/*" to the FastAPI function
-  requirements.txt  # fastapi, assemblyai, python-dotenv (uvicorn for local run)
-  .env              # ASSEMBLYAI_API_KEY=…   (written by init, gitignored)
-  .env.example      # ASSEMBLYAI_API_KEY=
-  .gitignore        # .env, .venv, __pycache__
-  README.md         # what it is, how to run, deploy-to-Vercel note, "ideas to extend" hints
-```
-
-Only `api/index.py` and `index.html` carry real logic; the rest is boilerplate.
-
-## Template behavior
-
-Two backend shapes. **`stream` and `agent` are architecturally identical**: the
-backend only mints a short-lived temp token and the **browser holds the WebSocket
-directly to AssemblyAI** — no audio ever passes through the backend.
-**`transcribe` and `llm`** need a thin backend proxy (file upload + transcript
-polling) because the REST/upload endpoints aren't temp-token authorized.
-
-- **transcribe** — drop/pick an audio or video file → backend uploads to
-  AssemblyAI, creates the transcript, and the browser polls a short `/api/status`
-  call until done → page renders the JSON (speaker labels, chapters, sentiment,
-  entities, highlights). The split into create + poll keeps each backend call
-  short, which is also what makes it serverless-friendly.
-- **stream** (live captions) — browser captures mic audio and connects to
-  AssemblyAI Streaming v3 **directly using a short-lived temp token** minted by
-  the backend `/api/token` route; renders partial → final turns live.
-- **agent** (voice agent) — same pattern as `stream`: backend `/api/token` mints
-  a token (`GET /v1/token`, with `expires_in_seconds` / `max_session_duration_seconds`),
-  and the browser opens its own WebSocket directly to
-  `wss://agents.assemblyai.com/v1/ws?token=…`, streaming mic audio up and playing
-  agent audio back. No backend audio proxy, no persistent server WebSocket.
-- **llm** (chat with audio) — transcribe a file (same create+poll path as the
-  transcribe template), then a chat box posts questions to `/api/chat`, which
-  calls the LLM Gateway over the transcript and returns answers.
-
-## API key handling & browser safety (invariant)
-
-- `aai init` resolves the key via the **CLI's existing resolution chain**
-  (`ASSEMBLYAI_API_KEY` env → OS keyring) and writes it to the **gitignored**
-  `.env`. The backend loads it with `python-dotenv`.
-- **The browser never receives the real key.** File uploads and LLM calls go
-  through the backend (`transcribe`/`llm`); `stream` and `agent` use the backend's
-  `/api/token` endpoint, which mints a short-lived AssemblyAI temporary token for
-  the browser. For every template the API key stays server-side.
-- **No key resolvable** → scaffold anyway, write `.env` with a placeholder value,
-  warn the user, and **skip auto-launch** (the server would fail without a key).
-
-**Noted tension:** this is the one place the system diverges from the CLI's
-"never write the key to a plaintext dotfile" rule. Justification: the scaffold is
-a *separate generated project* (not the CLI's own credential store), `.env` is
-gitignored, and `.env` is the universal web-dev convention. Accepted deliberately.
-
-## Install / launch flow
-
-Reuses the "steps with status" rendering pattern from `aai claude` (themed step
-lines, `--json` support).
-
-1. Resolve template + target dir. Conflict (non-empty dir) → error unless
-   `--force`/`--here`.
-2. Copy template files; write `.env` (from resolved key), `.env.example`,
-   `.gitignore`.
-3. Create the environment: `uv venv` if `uv` is on PATH, else stdlib
-   `python -m venv`; install `requirements.txt` (`uv pip install` / `pip
-   install`). *(skipped on `--no-install`)*
-4. Launch the server as a subprocess — `uvicorn api.index:app --port <port>` (via
-   `uv run` or the created venv) — wait for the port to accept connections, open
-   the browser. *(skipped on `--no-install`/`--no-open`)*
-5. Print the URL and next steps. Ctrl-C stops the server cleanly (exit 0).
-
-## Deployment (Vercel-ready, no extra tooling)
-
-Each template uses Vercel's conventional layout (`api/index.py` + `index.html` +
-`vercel.json`), so the **same files run locally and deploy to Vercel untouched**:
-the user pushes the generated directory to a Git repo, imports it on Vercel, and
-sets `ASSEMBLYAI_API_KEY` as a Vercel environment variable (the local `.env` is
-git-ignored and never deployed). The README includes a short "Deploy to Vercel"
-note.
-
-- All four templates are Vercel-deployable because every backend is **thin and
-  stateless**: `stream`/`agent` only mint a temp token, and `transcribe`/`llm`
-  split work into short create + poll calls — no persistent WebSocket server and
-  no long-running request.
-- We deliberately ship **no deploy tooling of our own** — no Dockerfiles, deploy
-  buttons, CI config, or Cloudflare functions. That would only duplicate what
-  Vercel already provides. Our responsibility ends at producing a layout Vercel
-  can deploy.
-- Cloudflare is explicitly out of scope (no production Python runtime; would
-  require a JS rewrite).
-
-## Error handling
-
-- `uv` missing → fall back to stdlib `venv` + `pip` (shown in the step detail).
-- Install failure → leave scaffolded files in place, print manual run steps, exit
-  non-zero.
-- Port in use → increment to the next free port (or honor `--port`).
-- Target dir exists & non-empty → error unless `--force`.
-- No key → warn, scaffold anyway, do not auto-launch.
-- Ctrl-C during the running server → clean shutdown, exit 0 (mirrors the CLI's
-  existing closed-pipe / signal handling posture).
-
-## Code organization
-
-- `aai_cli/commands/init.py` — the Typer command; registered in `_COMMAND_ORDER`
-  in `main.py` (placed near `samples`).
-- `aai_cli/init/` package:
-  - `scaffold.py` — copy template files, write `.env`/`.env.example`/`.gitignore`.
-  - `runner.py` — environment setup, dependency install, server launch, browser
-    open, port selection.
-  - `templates/<id>/…` — the four real template projects, shipped as package data.
-- New CLI dependency: `questionary` (arrow-key picker).
-- `fastapi` / `uvicorn` / `python-dotenv` are dependencies of the **generated**
-  `requirements.txt`, **not** of the CLI itself.
-- `pyproject.toml` — include `aai_cli/init/templates/**` (all template files,
-  incl. `vercel.json`, `.env.example`, dotfiles) as package data.
-
-## Testing (TDD)
-
-- **Unit:** template/dir argument resolution, picker default-dir logic,
-  target-dir conflict handling, key → `.env` writing (assert the committed
-  template fixtures contain **no** real key), step rendering, `--json` output.
-- **Template integrity:** each template loads via FastAPI `TestClient`; `GET /`
-  returns 200 and serves the page; `/api/token` mints a token (AssemblyAI mocked)
-  for `stream`/`agent`. Each template directory contains the required files
-  (incl. `vercel.json`).
-- **Install flow:** with **mocked** subprocess — assert correct `uv`/`venv`/`pip`
-  commands, the uv→venv fallback path, and that `--no-install`/`--no-open` skip
-  their steps. No real network or pip in tests.
-- **Reference consistency (light):** each template's core AssemblyAI call matches
-  the corresponding `code_gen` reference pattern.
-
-## Open questions
-
-None blocking. Future follow-ups (out of scope for v1): additional templates,
-a `--template-url` for community templates, and first-class Cloudflare support
-(would require JS-based edge functions).
diff --git a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md b/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
deleted file mode 100644
index 8c9f79ca..00000000
--- a/specs/plans/2026-06-04-aai-init-core-and-transcribe.md
+++ /dev/null
@@ -1,1589 +0,0 @@
-# `aai init` Core Machinery + `transcribe` Template — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add an `aai init` command that interactively picks a template, copies a real, Vercel-deployable Python web project, installs its dependencies, launches a local server, and opens the browser — implemented end-to-end for the `transcribe` template.
-
-**Architecture:** A new `aai_cli/commands/init.py` Typer command drives three small, independently testable units under a new `aai_cli/init/` package: a template registry, a `scaffold` step (copy committed template files + write `.env`), and a `runner` step (detect `uv`/`venv`, install deps, pick a free port, launch `uvicorn`, open the browser). Templates are committed real projects under `aai_cli/init/templates/<id>/` and copied verbatim (Approach A from the spec) — the generated output *is* the files we hand-wrote and test. Progress is reported with the same "steps with status" pattern as `aai claude`.
-
-**Tech Stack:** Python 3.10+, Typer/Click (vendored in typer), `questionary` (new dep, arrow-key picker), `importlib.resources` (locate packaged template files), `uv`/`venv`+`pip` (env setup for the generated app), FastAPI + uvicorn + python-dotenv (dependencies of the *generated* app only), pytest + Typer `CliRunner` + FastAPI `TestClient` (tests).
-
-**Spec:** `specs/2026-06-04-aai-init-design.md`
-
----
-
-## Scope & follow-on plans
-
-This plan delivers the **full `aai init` machinery** plus **one template (`transcribe`)** as a complete, working vertical slice. The remaining three templates from the spec are **separate sibling plans**, each additive and of the same shape (add `aai_cli/init/templates/<id>/`, register the id, add an integrity test):
-
-- `2026-06-XX-aai-init-stream-template.md` — live captions; backend `/api/token` only, browser holds the AssemblyAI Streaming WS directly.
-- `2026-06-XX-aai-init-agent-template.md` — voice agent; same token-only backend shape as `stream` (`GET /v1/token` → `wss://agents.assemblyai.com/v1/ws`).
-- `2026-06-XX-aai-init-llm-template.md` — chat with audio; transcribe create+poll, then `/api/chat` over the transcript via LLM Gateway.
-
-Splitting this way keeps each plan focused and lets the template plans build on the *proven* machinery from this one. The picker and registry are written to make adding a template a one-line registration plus a template directory.
-
-## File structure
-
-**New files (CLI package):**
-- `aai_cli/init/__init__.py` — package marker; re-exports the public surface (`TEMPLATES`, `TEMPLATE_ORDER`, `scaffold`, `resolve_optional_api_key`).
-- `aai_cli/init/templates.py` — the template registry: `TEMPLATES` (id → human title), `TEMPLATE_ORDER` (display order), `title_for`, `is_template`.
-- `aai_cli/init/keys.py` — `resolve_optional_api_key(profile)`: the CLI's key chain (env → keyring) but returning `None` instead of raising when absent.
-- `aai_cli/init/scaffold.py` — `scaffold(template, target_dir, api_key)`: copy the packaged template tree (renaming dotfile templates) and write `.env`; plus `target_conflict(dir)` and `template_files(template)` helpers.
-- `aai_cli/init/runner.py` — pure command builders + IO helpers: `has_uv`, `venv_python`, `env_setup_commands`, `serve_command`, `find_free_port`, `wait_for_port`, `launch_and_open`.
-- `aai_cli/init/steps.py` — `Step` TypedDict + `render_steps(steps)` (same shape as `aai_cli/commands/claude.py`, kept local to `init`).
-- `aai_cli/commands/init.py` — the Typer command wiring picker → scaffold → runner → step output.
-
-**New files (the `transcribe` template, committed real project):**
-- `aai_cli/init/templates/transcribe/api/index.py` — FastAPI app: serve `index.html`, `POST /api/transcribe` (submit), `GET /api/status/{id}` (poll).
-- `aai_cli/init/templates/transcribe/index.html` — one vanilla-JS page: file picker → submit → poll → render transcript + audio-intelligence chips.
-- `aai_cli/init/templates/transcribe/vercel.json` — route `/` to the page and `/api/*` to the function.
-- `aai_cli/init/templates/transcribe/requirements.txt` — `fastapi`, `assemblyai`, `python-dotenv`, `uvicorn`, `python-multipart`.
-- `aai_cli/init/templates/transcribe/README.md` — what it is, run locally, deploy to Vercel, "ideas to extend".
-- `aai_cli/init/templates/transcribe/gitignore` — packaged WITHOUT a leading dot; scaffold renames to `.gitignore`.
-- `aai_cli/init/templates/transcribe/env.example` — packaged without a leading dot; scaffold renames to `.env.example`.
-
-**Modified files:**
-- `pyproject.toml` — add `questionary` to `dependencies`; ensure the template tree (incl. non-`.py` files) is included in the wheel.
-- `aai_cli/main.py` — import and register the `init` command; add `"init"` to `_COMMAND_ORDER`.
-- `tests/` — new test modules per task.
-
-**Design note on dotfiles:** template dotfiles are stored under plain names (`gitignore`, `env.example`) so (a) the repo's own `.gitignore` can't accidentally ignore them, and (b) they're reliably included in the wheel. `scaffold` maps them to their dotted names on copy. The real `.env` is never committed in a template — it's written at scaffold time from the resolved key (or a placeholder).
-
----
-
-## Task 1: New dependency + package skeleton + packaging
-
-**Files:**
-- Modify: `pyproject.toml` (dependencies + wheel package data)
-- Create: `aai_cli/init/__init__.py`
-- Test: `tests/test_init_packaging.py`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_packaging.py
-import importlib
-
-
-def test_init_package_imports():
-    mod = importlib.import_module("aai_cli.init")
-    assert mod is not None
-
-
-def test_questionary_is_available():
-    # questionary is a runtime dependency of the CLI (the init picker).
-    assert importlib.import_module("questionary") is not None
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_packaging.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init'` (and possibly `questionary`).
-
-- [ ] **Step 3: Add the dependency and create the package**
-
-In `pyproject.toml`, add to the `dependencies` array (keep the existing list; add this line):
-
-```toml
-    "questionary>=2.0.1",
-```
-
-Then ensure the template tree ships in the wheel. The wheel target currently is:
-
-```toml
-[tool.hatch.build.targets.wheel]
-packages = ["aai_cli"]
-```
-
-Add an explicit artifacts include so non-`.py` template files (and renamed dotfiles) are always packaged:
-
-```toml
-[tool.hatch.build.targets.wheel]
-packages = ["aai_cli"]
-artifacts = ["aai_cli/init/templates/**"]
-```
-
-Create the package marker:
-
-```python
-# aai_cli/init/__init__.py
-from __future__ import annotations
-```
-
-- [ ] **Step 4: Sync the environment and run the test**
-
-Run: `uv sync --extra dev && uv run pytest tests/test_init_packaging.py -v`
-Expected: PASS (both tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add pyproject.toml uv.lock aai_cli/init/__init__.py tests/test_init_packaging.py
-git commit -m "feat(init): add questionary dep + init package skeleton"
-```
-
----
-
-## Task 2: Template registry
-
-**Files:**
-- Create: `aai_cli/init/templates.py`
-- Test: `tests/test_init_templates.py`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_templates.py
-from aai_cli.init import templates
-
-
-def test_all_four_template_ids_present():
-    assert set(templates.TEMPLATES) == {"transcribe", "stream", "agent", "llm"}
-
-
-def test_template_order_is_complete_and_stable():
-    # Display order mirrors the CLI's command order; every id appears exactly once.
-    assert templates.TEMPLATE_ORDER == ("transcribe", "stream", "agent", "llm")
-    assert set(templates.TEMPLATE_ORDER) == set(templates.TEMPLATES)
-
-
-def test_title_for_known_and_unknown():
-    assert "Transcribe" in templates.title_for("transcribe")
-    assert templates.title_for("nope") == "nope"  # falls back to the raw id
-
-
-def test_is_template():
-    assert templates.is_template("agent") is True
-    assert templates.is_template("nope") is False
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_templates.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.templates'`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```python
-# aai_cli/init/templates.py
-from __future__ import annotations
-
-# id -> human-facing title shown in the picker. Ids mirror the CLI's commands.
-TEMPLATES: dict[str, str] = {
-    "transcribe": "Transcribe & explore a file",
-    "stream": "Live captions (mic → browser)",
-    "agent": "Talk to a voice agent",
-    "llm": "Chat with your audio (LLM)",
-}
-
-# Display order for the picker and `--help`, matching the CLI's command order.
-TEMPLATE_ORDER: tuple[str, ...] = ("transcribe", "stream", "agent", "llm")
-
-
-def is_template(name: str) -> bool:
-    return name in TEMPLATES
-
-
-def title_for(name: str) -> str:
-    """The human title for a template id, or the raw id if unknown."""
-    return TEMPLATES.get(name, name)
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest tests/test_init_templates.py -v`
-Expected: PASS (4 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add aai_cli/init/templates.py tests/test_init_templates.py
-git commit -m "feat(init): template registry"
-```
-
----
-
-## Task 3: Optional API-key resolution
-
-**Files:**
-- Create: `aai_cli/init/keys.py`
-- Test: `tests/test_init_keys.py`
-
-The CLI's `config.resolve_api_key` raises `NotAuthenticated` when no key exists. `aai init` must still scaffold without a key (writing a placeholder), so it needs a non-raising variant.
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_keys.py
-from aai_cli import config
-from aai_cli.init import keys
-
-
-def test_resolves_from_env(monkeypatch):
-    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "env-key-123")
-    assert keys.resolve_optional_api_key(profile=None) == "env-key-123"
-
-
-def test_resolves_from_keyring(memory_keyring):
-    config.set_api_key("default", "stored-key-456")
-    assert keys.resolve_optional_api_key(profile=None) == "stored-key-456"
-
-
-def test_returns_none_when_absent():
-    # isolate_env strips the env var and memory_keyring starts empty.
-    assert keys.resolve_optional_api_key(profile=None) is None
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_keys.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.keys'`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```python
-# aai_cli/init/keys.py
-from __future__ import annotations
-
-from aai_cli import config
-from aai_cli.errors import NotAuthenticated
-
-
-def resolve_optional_api_key(*, profile: str | None) -> str | None:
-    """The CLI's key chain (env -> keyring), but None instead of raising when absent.
-
-    `aai init` scaffolds even without a key (writing a placeholder), so it must not
-    fail the way run commands do.
-    """
-    try:
-        return config.resolve_api_key(profile=profile)
-    except NotAuthenticated:
-        return None
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest tests/test_init_keys.py -v`
-Expected: PASS (3 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add aai_cli/init/keys.py tests/test_init_keys.py
-git commit -m "feat(init): optional API-key resolution (no raise when absent)"
-```
-
----
-
-## Task 4: The `transcribe` template files
-
-**Files:**
-- Create: `aai_cli/init/templates/transcribe/api/index.py`
-- Create: `aai_cli/init/templates/transcribe/index.html`
-- Create: `aai_cli/init/templates/transcribe/vercel.json`
-- Create: `aai_cli/init/templates/transcribe/requirements.txt`
-- Create: `aai_cli/init/templates/transcribe/README.md`
-- Create: `aai_cli/init/templates/transcribe/gitignore`
-- Create: `aai_cli/init/templates/transcribe/env.example`
-- Test: `tests/test_init_template_transcribe.py`
-
-This task writes the real, runnable template and a test that loads its FastAPI app via `TestClient` with the AssemblyAI SDK mocked. The template uses a **submit + poll** split (each backend call is short → serverless-friendly), per the spec.
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_template_transcribe.py
-import importlib.util
-import sys
-from pathlib import Path
-from unittest.mock import MagicMock
-
-from fastapi.testclient import TestClient
-
-TEMPLATE_DIR = Path("aai_cli/init/templates/transcribe")
-
-
-def _load_app(monkeypatch):
-    """Import the template's api/index.py as a module and return its FastAPI app.
-
-    The template is a standalone project (not part of aai_cli's import graph), so we
-    load it by file path. assemblyai is stubbed so no network/key is needed.
-    """
-    fake_aai = MagicMock()
-    fake_aai.TranscriptStatus.completed = "completed"
-    fake_aai.TranscriptStatus.error = "error"
-    submitted = MagicMock(id="t-123")
-    fake_aai.Transcriber.return_value.submit.return_value = submitted
-
-    # The template fetches status via the SDK's non-blocking api.get_transcript,
-    # so stub the assemblyai.api and assemblyai.client submodules too.
-    fake_api = MagicMock()
-    done = MagicMock(status="completed", error=None)
-    done.dict.return_value = {"text": "hello world", "utterances": []}
-    fake_api.get_transcript.return_value = done
-    fake_client = MagicMock()
-
-    monkeypatch.setitem(sys.modules, "assemblyai", fake_aai)
-    monkeypatch.setitem(sys.modules, "assemblyai.api", fake_api)
-    monkeypatch.setitem(sys.modules, "assemblyai.client", fake_client)
-
-    spec = importlib.util.spec_from_file_location(
-        "_tmpl_transcribe", TEMPLATE_DIR / "api" / "index.py"
-    )
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module.app, fake_aai, fake_api
-
-
-def test_required_files_exist():
-    for rel in ("api/index.py", "index.html", "vercel.json",
-                "requirements.txt", "README.md", "gitignore", "env.example"):
-        assert (TEMPLATE_DIR / rel).exists(), rel
-
-
-def test_template_ships_no_real_key():
-    # No committed file may contain a literal .env with a key; only env.example.
-    assert not (TEMPLATE_DIR / ".env").exists()
-    assert "your_assemblyai_api_key_here" in (TEMPLATE_DIR / "env.example").read_text()
-
-
-def test_index_route_serves_page(monkeypatch):
-    app, _aai, _api = _load_app(monkeypatch)
-    client = TestClient(app)
-    resp = client.get("/")
-    assert resp.status_code == 200
-    assert "<html" in resp.text.lower()
-
-
-def test_submit_returns_transcript_id(monkeypatch):
-    app, fake, _api = _load_app(monkeypatch)
-    client = TestClient(app)
-    resp = client.post("/api/transcribe", files={"file": ("a.mp3", b"\x00\x01", "audio/mpeg")})
-    assert resp.status_code == 200
-    assert resp.json() == {"id": "t-123"}
-    fake.Transcriber.return_value.submit.assert_called_once()
-
-
-def test_status_returns_completed_transcript(monkeypatch):
-    app, _aai, _api = _load_app(monkeypatch)
-    client = TestClient(app)
-    resp = client.get("/api/status/t-123")
-    assert resp.status_code == 200
-    body = resp.json()
-    assert body["status"] == "completed"
-    assert body["transcript"]["text"] == "hello world"
-
-
-def test_status_returns_processing_when_not_done(monkeypatch):
-    # A poll endpoint MUST report a non-terminal status without blocking. This guards
-    # against regressing to the blocking aai.Transcript.get_by_id() (which would only
-    # ever return completed/error, making this branch dead code).
-    app, _aai, fake_api = _load_app(monkeypatch)
-    fake_api.get_transcript.return_value = MagicMock(status="processing", error=None)
-    client = TestClient(app)
-    resp = client.get("/api/status/t-xyz")
-    assert resp.status_code == 200
-    assert resp.json() == {"status": "processing"}
-
-
-def test_status_returns_502_on_error(monkeypatch):
-    app, _aai, fake_api = _load_app(monkeypatch)
-    fake_api.get_transcript.return_value = MagicMock(status="error", error="bad audio")
-    client = TestClient(app)
-    resp = client.get("/api/status/t-bad")
-    assert resp.status_code == 502
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_template_transcribe.py -v`
-Expected: FAIL — the template files don't exist yet (`test_required_files_exist` fails; loaders error on missing path).
-
-- [ ] **Step 3: Create the backend `api/index.py`**
-
-```python
-# aai_cli/init/templates/transcribe/api/index.py
-"""Transcribe & explore — AssemblyAI starter (FastAPI).
-
-Two short endpoints so each request stays fast (serverless-friendly):
-  POST /api/transcribe  -> submit the upload, return {"id": ...}
-  GET  /api/status/{id} -> poll; returns the full transcript JSON when complete
-
-The browser (index.html) submits a file, then polls status until done.
-Your API key stays on the server — the browser never sees it.
-"""
-from __future__ import annotations
-
-import os
-import tempfile
-import uuid
-from pathlib import Path
-
-import assemblyai as aai
-from assemblyai.api import get_transcript  # single non-blocking GET (see status())
-from assemblyai.client import Client
-from dotenv import load_dotenv
-from fastapi import FastAPI, HTTPException, UploadFile
-from fastapi.responses import FileResponse
-
-load_dotenv()
-aai.settings.api_key = os.environ.get("ASSEMBLYAI_API_KEY", "")
-
-# Audio-intelligence features to showcase. Tweak these — that's the point of a starter.
-CONFIG = aai.TranscriptionConfig(
-    speaker_labels=True,
-    auto_chapters=True,
-    sentiment_analysis=True,
-    entity_detection=True,
-    auto_highlights=True,
-)
-
-ROOT = Path(__file__).resolve().parent.parent
-app = FastAPI()
-
-
-@app.get("/")
-def index() -> FileResponse:
-    return FileResponse(ROOT / "index.html")
-
-
-@app.post("/api/transcribe")
-async def transcribe(file: UploadFile) -> dict[str, str]:
-    suffix = Path(file.filename or "audio").suffix
-    tmp = Path(tempfile.gettempdir()) / f"aai-{uuid.uuid4().hex}{suffix}"
-    tmp.write_bytes(await file.read())
-    transcript = aai.Transcriber().submit(str(tmp), config=CONFIG)
-    return {"id": transcript.id}
-
-
-@app.get("/api/status/{transcript_id}")
-def status(transcript_id: str) -> dict[str, object]:
-    # One non-blocking GET. NOTE: aai.Transcript.get_by_id() BLOCKS until the job
-    # finishes (it calls wait_for_completion) — wrong for a poll endpoint, and it
-    # would time out on serverless. api.get_transcript does a single request and
-    # uses the SDK's configured client (auth + region from aai.settings).
-    t = get_transcript(Client.get_default().http_client, transcript_id)
-    if t.status == aai.TranscriptStatus.error:
-        raise HTTPException(status_code=502, detail=t.error or "Transcription failed")
-    if t.status == aai.TranscriptStatus.completed:
-        return {"status": "completed", "transcript": t.dict()}
-    return {"status": str(getattr(t.status, "value", t.status))}
-```
-
-- [ ] **Step 4: Create the frontend `index.html`**
-
-```html
-<!-- aai_cli/init/templates/transcribe/index.html -->
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Transcribe &amp; explore · AssemblyAI</title>
-  <style>
-    body { font: 15px/1.6 system-ui, sans-serif; max-width: 760px; margin: 40px auto; padding: 0 16px; }
-    h1 { font-size: 20px; }
-    #drop { border: 2px dashed #bbb; border-radius: 10px; padding: 28px; text-align: center; cursor: pointer; }
-    #drop.busy { opacity: .6; pointer-events: none; }
-    .chips span { display: inline-block; background: #eef; border-radius: 99px; padding: 3px 10px; margin: 2px; font-size: 12px; }
-    .turn { margin: 6px 0; }
-    .spk { font-weight: 600; }
-    pre { white-space: pre-wrap; }
-  </style>
-</head>
-<body>
-  <h1>🎧 Transcribe &amp; explore</h1>
-  <p>Pick an audio or video file. The server transcribes it with AssemblyAI and returns speakers, chapters, sentiment, entities, and highlights.</p>
-
-  <label id="drop">
-    <input id="file" type="file" accept="audio/*,video/*" hidden />
-    <span id="droplabel">Click to choose a file</span>
-  </label>
-
-  <p id="status"></p>
-  <div id="result"></div>
-
-  <script>
-    const fileInput = document.getElementById("file");
-    const drop = document.getElementById("drop");
-    const statusEl = document.getElementById("status");
-    const result = document.getElementById("result");
-
-    drop.addEventListener("click", () => fileInput.click());
-    fileInput.addEventListener("change", () => fileInput.files[0] && upload(fileInput.files[0]));
-
-    async function upload(file) {
-      drop.classList.add("busy");
-      result.innerHTML = "";
-      statusEl.textContent = "Uploading…";
-      const body = new FormData();
-      body.append("file", file);
-      const res = await fetch("/api/transcribe", { method: "POST", body });
-      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
-      const { id } = await res.json();
-      poll(id);
-    }
-
-    async function poll(id) {
-      statusEl.textContent = "Transcribing…";
-      const res = await fetch("/api/status/" + id);
-      if (!res.ok) { statusEl.textContent = "Error: " + (await res.text()); drop.classList.remove("busy"); return; }
-      const data = await res.json();
-      if (data.status !== "completed") { setTimeout(() => poll(id), 2000); return; }
-      statusEl.textContent = "Done.";
-      drop.classList.remove("busy");
-      render(data.transcript);
-    }
-
-    function render(t) {
-      const chips = [];
-      if (t.chapters) chips.push("Chapters");
-      if (t.sentiment_analysis_results) chips.push("Sentiment");
-      if (t.entities) chips.push("Entities");
-      if (t.auto_highlights_result) chips.push("Highlights");
-      const utterances = (t.utterances || []).map(
-        (u) => `<div class="turn"><span class="spk">Speaker ${u.speaker}:</span> ${escapeHtml(u.text)}</div>`
-      ).join("");
-      result.innerHTML =
-        `<div class="chips">${chips.map((c) => `<span>${c}</span>`).join("")}</div>` +
-        (utterances || `<pre>${escapeHtml(t.text || "")}</pre>`);
-    }
-
-    function escapeHtml(s) {
-      return (s || "").replace(/[&<>]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;" }[c]));
-    }
-  </script>
-</body>
-</html>
-```
-
-- [ ] **Step 5: Create `vercel.json`, `requirements.txt`, `README.md`, `gitignore`, `env.example`**
-
-```json
-// aai_cli/init/templates/transcribe/vercel.json
-{
-  "rewrites": [
-    { "source": "/api/(.*)", "destination": "/api/index" },
-    { "source": "/(.*)", "destination": "/index.html" }
-  ]
-}
-```
-
-```text
-# aai_cli/init/templates/transcribe/requirements.txt
-fastapi
-uvicorn
-assemblyai
-python-dotenv
-python-multipart
-```
-
-```markdown
-<!-- aai_cli/init/templates/transcribe/README.md -->
-# Transcribe & explore — AssemblyAI starter
-
-Upload an audio/video file and see the transcript with speaker labels, chapters,
-sentiment, entities, and highlights. Built with FastAPI + a single HTML page.
-
-## Run locally
-
-```sh
-uvicorn api.index:app --reload --port 3000
-# open http://localhost:3000
-```
-
-`ASSEMBLYAI_API_KEY` is read from `.env` (already created for you if you ran `aai init`).
-
-## Deploy to Vercel
-
-Push this folder to a Git repo and import it on Vercel. Set `ASSEMBLYAI_API_KEY`
-as a Vercel environment variable (the local `.env` is git-ignored and not deployed).
-No extra config — `vercel.json` routes the page and the `/api` function.
-
-## Ideas to extend
-
-- Show chapter summaries and highlight timestamps.
-- Add a waveform / audio player synced to the transcript.
-- Swap the analysis features in `CONFIG` (api/index.py).
-```
-
-```text
-# aai_cli/init/templates/transcribe/gitignore
-.env
-.venv
-__pycache__/
-```
-
-```text
-# aai_cli/init/templates/transcribe/env.example
-ASSEMBLYAI_API_KEY=your_assemblyai_api_key_here
-```
-
-- [ ] **Step 6: Add `python-multipart` to the dev env so the test client can post files**
-
-`fastapi`/`uvicorn`/`python-multipart` are runtime deps of the *generated* app, not the CLI. The test loads the template app in-process, so they must be available in the dev environment. Add them to the `dev` optional-dependencies in `pyproject.toml`:
-
-```toml
-dev = [
-    "pytest>=9.0.3",
-    "pytest-cov>=7.1.0",
-    "hypothesis>=6.155.1",
-    "ruff>=0.15.15",
-    "mypy>=2.1.0",
-    "pre-commit>=4.6.0",
-    "fastapi>=0.115.0",
-    "uvicorn>=0.30.0",
-    "python-dotenv>=1.0.0",
-    "python-multipart>=0.0.9",
-]
-```
-
-Then: `uv sync --extra dev`
-
-- [ ] **Step 7: Run the tests to verify they pass**
-
-Run: `uv run pytest tests/test_init_template_transcribe.py -v`
-Expected: PASS (7 tests).
-
-- [ ] **Step 8: Commit**
-
-```bash
-git add aai_cli/init/templates/transcribe pyproject.toml uv.lock tests/test_init_template_transcribe.py
-git commit -m "feat(init): transcribe template (FastAPI submit+poll, Vercel-ready)"
-```
-
----
-
-## Task 5: Scaffold (copy template + write `.env`)
-
-**Files:**
-- Create: `aai_cli/init/scaffold.py`
-- Test: `tests/test_init_scaffold.py`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_scaffold.py
-import pytest
-
-from aai_cli.errors import CLIError
-from aai_cli.init import scaffold
-
-
-def test_scaffold_copies_files_and_renames_dotfiles(tmp_path):
-    target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
-    assert (target / "api" / "index.py").exists()
-    assert (target / "index.html").exists()
-    assert (target / "vercel.json").exists()
-    # dotfile templates are renamed to their dotted names
-    assert (target / ".gitignore").exists()
-    assert (target / ".env.example").exists()
-    # the plain-named source files are NOT copied verbatim
-    assert not (target / "gitignore").exists()
-    assert not (target / "env.example").exists()
-
-
-def test_scaffold_writes_env_with_key(tmp_path):
-    target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
-    env = (target / ".env").read_text()
-    assert "ASSEMBLYAI_API_KEY=sk-real-key" in env
-
-
-def test_scaffold_skips_pycache(tmp_path):
-    # Importing a template's api/index.py during our own test run leaves a
-    # __pycache__ next to it; the scaffolder must not copy that into the project.
-    target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key=None)
-    assert not list(target.rglob("__pycache__"))
-    assert not list(target.rglob("*.pyc"))
-
-
-def test_scaffold_writes_placeholder_when_no_key(tmp_path):
-    target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key=None)
-    env = (target / ".env").read_text()
-    assert scaffold.PLACEHOLDER_KEY in env
-
-
-def test_scaffold_unknown_template_raises(tmp_path):
-    with pytest.raises(CLIError):
-        scaffold.scaffold("nope", tmp_path / "app", api_key=None)
-
-
-def test_target_conflict_detects_nonempty_dir(tmp_path):
-    empty = tmp_path / "empty"
-    empty.mkdir()
-    assert scaffold.target_conflict(empty) is False
-    assert scaffold.target_conflict(tmp_path / "missing") is False
-    nonempty = tmp_path / "full"
-    nonempty.mkdir()
-    (nonempty / "x.txt").write_text("hi")
-    assert scaffold.target_conflict(nonempty) is True
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_scaffold.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.scaffold'`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```python
-# aai_cli/init/scaffold.py
-from __future__ import annotations
-
-from importlib import resources
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-from aai_cli.errors import CLIError
-from aai_cli.init import templates
-
-if TYPE_CHECKING:
-    # Annotations only (PEP 563 strings), so no runtime import — `Traversable`'s
-    # module location differs across 3.10/3.11 but that never matters at runtime.
-    from importlib.resources.abc import Traversable
-
-PLACEHOLDER_KEY = "your_assemblyai_api_key_here"
-
-# Template files stored under plain names -> their real dotted names on copy.
-_DOTFILE_RENAMES = {"gitignore": ".gitignore", "env.example": ".env.example"}
-
-# Never copy build/test detritus into the user's fresh project. (Loading a template's
-# api/index.py during our own tests leaves a __pycache__ next to it.)
-_SKIP_NAMES = {"__pycache__"}
-
-
-def _template_root(template: str) -> Traversable:
-    if not templates.is_template(template):
-        raise CLIError(
-            f"Unknown template {template!r}. Choose one of: "
-            f"{', '.join(templates.TEMPLATE_ORDER)}.",
-            error_type="unknown_template",
-            exit_code=1,
-        )
-    # Navigate from the `aai_cli.init` package (templates/ has no __init__.py, so it
-    # is not itself an importable package).
-    return resources.files("aai_cli.init") / "templates" / template
-
-
-def target_conflict(target: Path) -> bool:
-    """True when the target exists and is a non-empty directory."""
-    return target.is_dir() and any(target.iterdir())
-
-
-def _copy_tree(node: Traversable, dest: Path) -> None:
-    for child in node.iterdir():
-        if child.name in _SKIP_NAMES or child.name.endswith(".pyc"):
-            continue
-        name = _DOTFILE_RENAMES.get(child.name, child.name)
-        out = dest / name
-        if child.is_dir():
-            out.mkdir(parents=True, exist_ok=True)
-            _copy_tree(child, out)
-        else:
-            out.parent.mkdir(parents=True, exist_ok=True)
-            out.write_bytes(child.read_bytes())
-
-
-def scaffold(template: str, target: Path, *, api_key: str | None) -> Path:
-    """Copy the template into `target` and write `.env`. Returns `target`."""
-    root = _template_root(template)
-    target.mkdir(parents=True, exist_ok=True)
-    _copy_tree(root, target)
-    key = api_key or PLACEHOLDER_KEY
-    (target / ".env").write_text(f"ASSEMBLYAI_API_KEY={key}\n")
-    return target
-```
-
-> The `Traversable` import is under `TYPE_CHECKING` and used only in annotations
-> (which `from __future__ import annotations` keeps as strings), so it never runs at
-> runtime — that sidesteps its differing module location on 3.10 vs 3.11+. Verified:
-> `resources.files("aai_cli.init") / "templates" / <id>` works at runtime (3.11) and
-> `mypy --python-version 3.10` is clean.
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest tests/test_init_scaffold.py -v`
-Expected: PASS (6 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add aai_cli/init/scaffold.py tests/test_init_scaffold.py
-git commit -m "feat(init): scaffold (copy template tree + write .env)"
-```
-
----
-
-## Task 6: Runner — command builders + port/launch helpers
-
-**Files:**
-- Create: `aai_cli/init/runner.py`
-- Test: `tests/test_init_runner.py`
-
-The pure command builders and port finder are unit-tested directly; the subprocess launch is exercised in Task 7 with mocks.
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_runner.py
-import socket
-import sys
-from pathlib import Path
-
-from aai_cli.init import runner
-
-
-def test_has_uv_reflects_path(monkeypatch):
-    monkeypatch.setattr(runner.shutil, "which", lambda name: "/usr/bin/uv")
-    assert runner.has_uv() is True
-    monkeypatch.setattr(runner.shutil, "which", lambda name: None)
-    assert runner.has_uv() is False
-
-
-def test_venv_python_path_per_platform(monkeypatch):
-    target = Path("/proj")
-    monkeypatch.setattr(runner.os, "name", "posix")
-    assert runner.venv_python(target) == target / ".venv" / "bin" / "python"
-    monkeypatch.setattr(runner.os, "name", "nt")
-    assert runner.venv_python(target) == target / ".venv" / "Scripts" / "python.exe"
-
-
-def test_env_setup_commands_uv():
-    cmds = runner.env_setup_commands(Path("/proj"), use_uv=True)
-    assert cmds == [["uv", "venv"], ["uv", "pip", "install", "-r", "requirements.txt"]]
-
-
-def test_env_setup_commands_venv():
-    target = Path("/proj")
-    cmds = runner.env_setup_commands(target, use_uv=False)
-    py = str(runner.venv_python(target))
-    assert cmds == [
-        [sys.executable, "-m", "venv", ".venv"],
-        [py, "-m", "pip", "install", "-r", "requirements.txt"],
-    ]
-
-
-def test_serve_command_uv_and_venv():
-    target = Path("/proj")
-    assert runner.serve_command(target, port=3000, use_uv=True) == [
-        "uv", "run", "uvicorn", "api.index:app", "--port", "3000",
-    ]
-    py = str(runner.venv_python(target))
-    assert runner.serve_command(target, port=3000, use_uv=False) == [
-        py, "-m", "uvicorn", "api.index:app", "--port", "3000",
-    ]
-
-
-def test_find_free_port_returns_preferred_when_open():
-    # Bind nothing on a high port we expect to be free.
-    port = runner.find_free_port(0)  # 0 -> OS assigns a free port
-    assert isinstance(port, int) and port > 0
-
-
-def test_find_free_port_skips_taken_port():
-    s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-    s.bind(("127.0.0.1", 0))
-    taken = s.getsockname()[1]
-    s.listen(1)
-    try:
-        chosen = runner.find_free_port(taken)
-        assert chosen != taken
-    finally:
-        s.close()
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_runner.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.runner'`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```python
-# aai_cli/init/runner.py
-from __future__ import annotations
-
-import os
-import shutil
-import socket
-import subprocess
-import time
-import webbrowser
-from pathlib import Path
-
-
-def has_uv() -> bool:
-    return shutil.which("uv") is not None
-
-
-def venv_python(target: Path) -> Path:
-    if os.name == "nt":
-        return target / ".venv" / "Scripts" / "python.exe"
-    return target / ".venv" / "bin" / "python"
-
-
-def env_setup_commands(target: Path, *, use_uv: bool) -> list[list[str]]:
-    """Commands (run with cwd=target) to create a venv and install requirements."""
-    if use_uv:
-        return [["uv", "venv"], ["uv", "pip", "install", "-r", "requirements.txt"]]
-    import sys
-
-    py = str(venv_python(target))
-    return [
-        [sys.executable, "-m", "venv", ".venv"],
-        [py, "-m", "pip", "install", "-r", "requirements.txt"],
-    ]
-
-
-def serve_command(target: Path, *, port: int, use_uv: bool) -> list[str]:
-    if use_uv:
-        return ["uv", "run", "uvicorn", "api.index:app", "--port", str(port)]
-    return [str(venv_python(target)), "-m", "uvicorn", "api.index:app", "--port", str(port)]
-
-
-def _port_open(port: int) -> bool:
-    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-        return s.connect_ex(("127.0.0.1", port)) == 0
-
-
-def find_free_port(preferred: int, *, tries: int = 20) -> int:
-    """The preferred port if free, else the next free port; OS-assigned when preferred is 0."""
-    if preferred == 0:
-        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
-            s.bind(("127.0.0.1", 0))
-            return int(s.getsockname()[1])
-    for candidate in range(preferred, preferred + tries):
-        if not _port_open(candidate):
-            return candidate
-    return preferred
-
-
-def wait_for_port(port: int, *, timeout: float = 30.0) -> bool:
-    deadline = time.monotonic() + timeout
-    while time.monotonic() < deadline:
-        if _port_open(port):
-            return True
-        time.sleep(0.2)
-    return False
-
-
-def run_setup(target: Path, *, use_uv: bool) -> subprocess.CompletedProcess:
-    """Run env-setup commands in order; return the first failure or the last success."""
-    last = subprocess.CompletedProcess(args=[], returncode=0, stdout="", stderr="")
-    for cmd in env_setup_commands(target, use_uv=use_uv):
-        last = subprocess.run(cmd, cwd=target, capture_output=True, text=True)
-        if last.returncode != 0:
-            return last
-    return last
-
-
-def launch_and_open(target: Path, *, port: int, use_uv: bool, open_browser: bool) -> int:
-    """Start the dev server, wait for it, open the browser, and block until Ctrl-C.
-
-    Returns the process exit code (0 on a clean Ctrl-C shutdown).
-    """
-    proc = subprocess.Popen(serve_command(target, port=port, use_uv=use_uv), cwd=target)
-    try:
-        if wait_for_port(port) and open_browser:
-            webbrowser.open(f"http://localhost:{port}")
-        proc.wait()
-    except KeyboardInterrupt:
-        proc.terminate()
-        proc.wait()
-        return 0
-    return proc.returncode
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest tests/test_init_runner.py -v`
-Expected: PASS (7 tests).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add aai_cli/init/runner.py tests/test_init_runner.py
-git commit -m "feat(init): runner command builders + port/launch helpers"
-```
-
----
-
-## Task 7: Step rendering helper
-
-**Files:**
-- Create: `aai_cli/init/steps.py`
-- Test: `tests/test_init_steps.py`
-
-Mirrors the `Step`/`_render_steps` shape in `aai_cli/commands/claude.py`, kept local to `init`.
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_steps.py
-from aai_cli.init import steps
-
-
-def test_render_steps_includes_name_status_detail():
-    data = [
-        {"name": "scaffold", "status": "created", "detail": "./my-app"},
-        {"name": "install", "status": "skipped", "detail": "--no-install"},
-    ]
-    out = steps.render_steps(data)
-    assert "scaffold" in out
-    assert "created" in out
-    assert "./my-app" in out
-    assert "install" in out
-    assert "skipped" in out
-
-
-def test_render_steps_has_heading():
-    out = steps.render_steps([{"name": "scaffold", "status": "created", "detail": "x"}])
-    assert "init" in out.lower() or "AssemblyAI" in out
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_steps.py -v`
-Expected: FAIL — `ModuleNotFoundError: No module named 'aai_cli.init.steps'`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```python
-# aai_cli/init/steps.py
-from __future__ import annotations
-
-from typing import TypedDict
-
-from rich.markup import escape
-
-from aai_cli import theme
-
-
-class Step(TypedDict):
-    name: str
-    status: str
-    detail: str
-
-
-def render_steps(items: list[Step]) -> str:
-    lines = []
-    for s in items:
-        style = theme.status_style(s["status"])
-        lines.append(
-            f"  {escape(s['name'])}: "
-            f"[{style}]{escape(s['status'])}[/{style}] — {escape(s['detail'])}"
-        )
-    return "[aai.heading]aai init:[/aai.heading]\n" + "\n".join(lines)
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `uv run pytest tests/test_init_steps.py -v`
-Expected: PASS (2 tests).
-
-> If `theme.status_style` doesn't recognize a status string it should already
-> return a safe default (it does for `aai claude`). Confirm by reading
-> `aai_cli/theme.py`; reuse the same status vocabulary
-> (`created`/`installed`/`skipped`/`failed`/`already`).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add aai_cli/init/steps.py tests/test_init_steps.py
-git commit -m "feat(init): step-status rendering helper"
-```
-
----
-
-## Task 8: The `init` command (wire everything) + registration
-
-**Files:**
-- Create: `aai_cli/commands/init.py`
-- Modify: `aai_cli/main.py` (import, register, `_COMMAND_ORDER`)
-- Modify: `aai_cli/init/__init__.py` (re-export public surface)
-- Test: `tests/test_init_command.py`
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_command.py
-from pathlib import Path
-
-from typer.testing import CliRunner
-
-from aai_cli.main import app
-
-runner = CliRunner()
-
-
-def test_init_scaffold_only_creates_project(tmp_path, monkeypatch):
-    monkeypatch.chdir(tmp_path)
-    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
-    assert result.exit_code == 0, result.output
-    assert (tmp_path / "myapp" / "api" / "index.py").exists()
-    assert (tmp_path / "myapp" / ".env").exists()
-
-
-def test_init_writes_key_from_env(tmp_path, monkeypatch):
-    monkeypatch.chdir(tmp_path)
-    monkeypatch.setenv("ASSEMBLYAI_API_KEY", "sk-from-env")
-    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
-    assert "ASSEMBLYAI_API_KEY=sk-from-env" in (tmp_path / "myapp" / ".env").read_text()
-
-
-def test_init_placeholder_key_when_logged_out(tmp_path, monkeypatch):
-    monkeypatch.chdir(tmp_path)
-    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
-    env = (tmp_path / "myapp" / ".env").read_text()
-    assert "your_assemblyai_api_key_here" in env
-
-
-def test_init_unknown_template_errors(tmp_path, monkeypatch):
-    monkeypatch.chdir(tmp_path)
-    result = runner.invoke(app, ["init", "nope", "myapp", "--no-install"])
-    assert result.exit_code == 1
-
-
-def test_init_refuses_nonempty_dir_without_force(tmp_path, monkeypatch):
-    monkeypatch.chdir(tmp_path)
-    assert runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"]).exit_code == 0
-    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
-    assert result.exit_code == 1
-
-
-def test_init_force_overwrites(tmp_path, monkeypatch):
-    monkeypatch.chdir(tmp_path)
-    assert runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"]).exit_code == 0
-    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install", "--force"])
-    assert result.exit_code == 0
-
-
-def test_init_no_template_non_interactive_errors(tmp_path, monkeypatch):
-    # CliRunner has no TTY, so the picker can't run; bare `aai init` must error helpfully.
-    monkeypatch.chdir(tmp_path)
-    result = runner.invoke(app, ["init"])
-    assert result.exit_code != 0
-    assert "transcribe" in result.output  # lists the available templates
-
-
-def test_init_default_dir_is_template_app(tmp_path, monkeypatch):
-    monkeypatch.chdir(tmp_path)
-    result = runner.invoke(app, ["init", "transcribe", "--no-install"])
-    assert result.exit_code == 0, result.output
-    assert (tmp_path / "transcribe-app" / "api" / "index.py").exists()
-
-
-def test_init_appears_in_help():
-    result = runner.invoke(app, ["--help"])
-    assert "init" in result.output
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `uv run pytest tests/test_init_command.py -v`
-Expected: FAIL — `init` is not a registered command (non-zero exit / usage error).
-
-- [ ] **Step 3: Implement the command**
-
-```python
-# aai_cli/commands/init.py
-from __future__ import annotations
-
-import sys
-from pathlib import Path
-
-import typer
-from rich.markup import escape
-
-from aai_cli import output
-from aai_cli.context import AppState, run_command
-from aai_cli.errors import CLIError
-from aai_cli.init import keys, runner, scaffold, steps, templates
-
-# Single-command sub-typer flattened to `aai init` (the exact pattern `aai transcribe`
-# uses): one @app.command() named `init`, registered via app.add_typer(init.app) with
-# no name. Bare `aai init` runs the command with template=None -> the interactive picker.
-app = typer.Typer()
-
-
-def _pick_template() -> str:
-    """Interactive picker; raises a usage error when there's no TTY to prompt on."""
-    if not sys.stdin.isatty() or not sys.stdout.isatty():
-        raise CLIError(
-            "No template given and not running interactively. "
-            f"Pass one of: {', '.join(templates.TEMPLATE_ORDER)}.",
-            error_type="usage_error",
-            exit_code=1,
-        )
-    import questionary
-
-    choice = questionary.select(
-        "Pick a template",
-        choices=[
-            questionary.Choice(title=templates.title_for(t), value=t)
-            for t in templates.TEMPLATE_ORDER
-        ],
-    ).ask()
-    if choice is None:  # user pressed Ctrl-C
-        raise typer.Exit(code=130)
-    return str(choice)
-
-
-def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
-    if here:
-        return Path.cwd()
-    if directory:
-        return Path(directory)
-    return Path.cwd() / f"{template}-app"
-
-
-@app.command()
-def init(
-    ctx: typer.Context,
-    template: str = typer.Argument(None, help="Template id: transcribe, stream, agent, llm."),
-    directory: str = typer.Argument(None, help="Target directory (default: <template>-app)."),
-    no_install: bool = typer.Option(False, "--no-install", help="Scaffold only; don't install or launch."),
-    no_open: bool = typer.Option(False, "--no-open", help="Install + launch, but don't open the browser."),
-    force: bool = typer.Option(False, "--force", help="Overwrite a non-empty target directory."),
-    here: bool = typer.Option(False, "--here", help="Scaffold into the current directory."),
-    port: int = typer.Option(3000, "--port", help="Local server port."),
-    json_out: bool = typer.Option(False, "--json", help="Output raw JSON."),
-) -> None:
-    """Pick a template, scaffold it, install deps, launch the server, open the browser."""
-
-    def body(state: AppState, json_mode: bool) -> None:
-        chosen = template
-        if chosen is None:
-            chosen = _pick_template()
-        if not templates.is_template(chosen):
-            raise CLIError(
-                f"Unknown template {chosen!r}. Choose one of: "
-                f"{', '.join(templates.TEMPLATE_ORDER)}.",
-                error_type="usage_error",
-                exit_code=1,
-            )
-
-        target = _resolve_dir(directory, chosen, here=here)
-        if scaffold.target_conflict(target) and not force:
-            raise CLIError(
-                f"{target} already exists and is not empty. "
-                f"Use --force to overwrite or pick another directory.",
-                error_type="usage_error",
-                exit_code=1,
-            )
-
-        api_key = keys.resolve_optional_api_key(profile=state.profile)
-        scaffold.scaffold(chosen, target, api_key=api_key)
-
-        report: list[steps.Step] = [
-            {"name": "scaffold", "status": "created", "detail": str(target)}
-        ]
-        if api_key is None:
-            report.append(
-                {"name": "key", "status": "skipped",
-                 "detail": "no API key found; wrote a placeholder to .env (run `aai login`)"}
-            )
-
-        will_launch = not no_install and api_key is not None
-        if no_install:
-            report.append({"name": "install", "status": "skipped", "detail": "--no-install"})
-        else:
-            use_uv = runner.has_uv()
-            setup = runner.run_setup(target, use_uv=use_uv)
-            if setup.returncode != 0:
-                report.append(
-                    {"name": "install", "status": "failed",
-                     "detail": (setup.stderr or setup.stdout).strip()[:300]}
-                )
-                will_launch = False
-            else:
-                report.append(
-                    {"name": "install", "status": "installed",
-                     "detail": "uv" if use_uv else "venv + pip"}
-                )
-
-        output.emit(report, lambda d: steps.render_steps(d), json_mode=json_mode)
-        if any(s["status"] == "failed" for s in report):
-            raise typer.Exit(code=1)
-
-        if will_launch:
-            chosen_port = runner.find_free_port(port)
-            url = f"http://localhost:{chosen_port}"
-            if not json_mode:
-                output.console.print(f"[aai.heading]Starting[/aai.heading] {escape(url)}  (Ctrl-C to stop)")
-            runner.launch_and_open(
-                target, port=chosen_port, use_uv=runner.has_uv(), open_browser=not no_open
-            )
-
-    run_command(ctx, body, json=json_out)
-```
-
-- [ ] **Step 4: Register the command in `main.py`**
-
-In `aai_cli/main.py`, add `init` to the imports:
-
-```python
-from aai_cli.commands import (
-    agent,
-    claude,
-    doctor,
-    init,
-    llm,
-    login,
-    samples,
-    stream,
-    transcribe,
-    transcripts,
-)
-```
-
-Add `"init"` to `_COMMAND_ORDER` (place it after `samples`, with tooling commands):
-
-```python
-_COMMAND_ORDER = (
-    "transcribe",
-    "stream",
-    "transcripts",
-    "agent",
-    "llm",
-    "login",
-    "logout",
-    "whoami",
-    "doctor",
-    "samples",
-    "init",
-    "claude",
-    "version",
-)
-```
-
-Register the typer app (near the other `add_typer` calls) — **no `name=`**, so the
-single `init` command flattens to `aai init` (same as `app.add_typer(transcribe.app)`):
-
-```python
-app.add_typer(init.app)
-```
-
-If `tests/test_smoke.py` asserts the exact set/order of top-level commands, add
-`"init"` to that expected list too (placed after `samples`, matching `_COMMAND_ORDER`).
-
-- [ ] **Step 5: Keep `aai_cli/init/__init__.py` minimal**
-
-Do NOT re-export submodule members from the package `__init__`. Consumers import the
-submodules directly (`from aai_cli.init import scaffold` → the module, then
-`scaffold.scaffold(...)`), and re-exporting a function named `scaffold` here would
-shadow the `scaffold` submodule. Leave `__init__.py` as the minimal marker created in
-Task 1:
-
-```python
-# aai_cli/init/__init__.py
-# Submodules (templates, keys, scaffold, runner, steps) are imported directly by
-# consumers (e.g. `from aai_cli.init import scaffold`); re-exporting their members
-# here would shadow the same-named submodule (notably `scaffold`), so we don't.
-from __future__ import annotations
-```
-
-> Note on error type: these raises use `CLIError(error_type="usage_error", exit_code=1)`
-> rather than `UsageError` (which forces exit code 2). Exit code **1** matches the
-> existing `aai samples` scaffolder's convention for "unknown name"/"file exists" and
-> the test assertions. `run_command` renders any `CLIError` cleanly.
-
-- [ ] **Step 6: Run the tests to verify they pass**
-
-Run: `uv run pytest tests/test_init_command.py -v`
-Expected: PASS (9 tests).
-
-> This mirrors the verified `aai transcribe` registration (`typer.Typer()` + a single
-> `@app.command()` + `app.add_typer(...)` with no name), which renders as
-> `aai transcribe [OPTIONS] [SOURCE]` — a flat leaf command with positional args. So
-> `aai init [OPTIONS] [TEMPLATE] [DIRECTORY]` binds the positionals the same way; bare
-> `aai init` runs the command with `template=None` and falls into the picker (which
-> errors helpfully under CliRunner since there's no TTY).
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add aai_cli/commands/init.py aai_cli/main.py aai_cli/init/__init__.py tests/test_init_command.py
-git commit -m "feat(init): wire init command (picker, scaffold, install, launch) + register"
-```
-
----
-
-## Task 9: Full suite, lint, types, and README
-
-**Files:**
-- Modify: `README.md` (document `aai init`)
-- Test: full suite
-
-- [ ] **Step 1: Run the whole test suite**
-
-Run: `uv run pytest -q`
-Expected: PASS (all existing tests + the new `test_init_*` modules). Investigate and fix any regression before continuing.
-
-- [ ] **Step 2: Lint and type-check**
-
-Run: `uv run ruff check . && uv run ruff format --check . && uv run mypy`
-Expected: clean. Fix issues inline.
-
-> Likely ruff items: `S603`/`S607` (subprocess) are already ignored project-wide.
-> The `init` package may need `# noqa` only if a new lint surfaces — prefer fixing
-> over suppressing. The `importlib.resources` Traversable import may need the 3.10
-> fallback from Task 5.
-
-- [ ] **Step 3: Document the command in `README.md`**
-
-Add a short section after the Quick start (match the README's existing tone):
-
-````markdown
-## Scaffold a starter app
-
-```sh
-aai init                  # pick a template, scaffold it, install deps, open the browser
-aai init transcribe myapp # non-interactive: template + directory
-```
-
-`aai init` copies a small, self-contained FastAPI + HTML project you can run
-locally and deploy to Vercel as-is. Your key is written to a git-ignored `.env`
-(and is never sent to the browser). Use `--no-install` to scaffold only.
-````
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add README.md
-git commit -m "docs: document aai init"
-```
-
----
-
-## Task 10: Cross-template contract tests (keep every example working)
-
-**Files:**
-- Create: `tests/test_init_template_contract.py`
-
-**Why:** The templates are user-facing starter apps that drift from the SDK/API over
-time. A parametrized contract test — discovering every template directory on disk —
-catches the breakages a single smoke test misses, and **auto-covers the future
-`stream`/`agent`/`llm` templates** the moment their directories land. These are
-static-analysis checks (no app load, no network), so they're fast and robust.
-
-- [ ] **Step 1: Write the failing test**
-
-```python
-# tests/test_init_template_contract.py
-import ast
-import re
-from pathlib import Path
-
-import pytest
-
-TEMPLATES_ROOT = Path("aai_cli/init/templates")
-TEMPLATE_DIRS = sorted(
-    p for p in TEMPLATES_ROOT.iterdir() if p.is_dir() and not p.name.startswith("__")
-)
-# Map an import name to its PyPI distribution where they differ.
-_PKG_MAP = {"dotenv": "python-dotenv", "multipart": "python-multipart"}
-_STDLIB = {"os", "tempfile", "uuid", "pathlib", "__future__", "json", "typing"}
-
-
-@pytest.fixture(params=TEMPLATE_DIRS, ids=lambda p: p.name)
-def template_dir(request):
-    return request.param
-
-
-def test_required_files_present(template_dir):
-    for rel in ("api/index.py", "index.html", "vercel.json",
-                "requirements.txt", "README.md", "gitignore", "env.example"):
-        assert (template_dir / rel).exists(), f"{template_dir.name} missing {rel}"
-
-
-def test_no_committed_dotenv_or_real_key(template_dir):
-    assert not (template_dir / ".env").exists(), f"{template_dir.name} ships a real .env"
-    assert "your_assemblyai_api_key_here" in (template_dir / "env.example").read_text()
-
-
-def test_frontend_routes_exist_in_backend(template_dir):
-    """Every /api path the page fetches must be a route the backend registers."""
-    html = (template_dir / "index.html").read_text()
-    fetched = set(re.findall(r'fetch\(\s*["\'`](/api/[^"\'`?]+)', html))
-    # Also catch template-literal paths like fetch(`/api/status/${id}`) and "/api/x/" + id
-    fetched |= set(re.findall(r'["\'`](/api/[A-Za-z0-9_\-/]+?)(?:/?\$\{|/?["\'`]\s*\+)', html))
-    src = (template_dir / "api" / "index.py").read_text()
-    registered = set(re.findall(r'@app\.\w+\(\s*["\']([^"\']+)["\']', src))
-    registered_bases = {re.sub(r"/\{[^}]+\}$", "", r).rstrip("/") for r in registered}
-    for path in fetched:
-        base = path.rstrip("/")
-        assert any(base == r or base.startswith(r + "/") for r in registered_bases), (
-            f"{template_dir.name}: index.html fetches {path!r}, "
-            f"not registered in api/index.py (routes: {sorted(registered_bases)})"
-        )
-
-
-def test_requirements_cover_backend_imports(template_dir):
-    """Every third-party import in api/index.py appears in requirements.txt."""
-    tree = ast.parse((template_dir / "api" / "index.py").read_text())
-    imports: set[str] = set()
-    for node in ast.walk(tree):
-        if isinstance(node, ast.Import):
-            imports.add(node.names[0].name.split(".")[0])
-        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module:
-            imports.add(node.module.split(".")[0])
-    third_party = imports - _STDLIB
-    reqs = (template_dir / "requirements.txt").read_text().lower()
-    for pkg in third_party:
-        dist = _PKG_MAP.get(pkg, pkg)
-        assert dist in reqs, f"{template_dir.name}: import {pkg!r} ({dist}) missing from requirements.txt"
-
-
-def test_status_endpoint_does_not_block(template_dir):
-    """Guard against the blocking SDK call: a poll endpoint must not wait_for_completion."""
-    src = (template_dir / "api" / "index.py").read_text()
-    tree = ast.parse(src)
-    blocking = {"get_by_id", "wait_for_completion"}
-    called = {n.attr for n in ast.walk(tree) if isinstance(n, ast.Attribute)}
-    assert not (called & blocking), (
-        f"{template_dir.name}: uses blocking SDK call {called & blocking} — "
-        f"poll endpoints must do a single non-blocking fetch"
-    )
-```
-
-- [ ] **Step 2: Run test to verify it passes (transcribe already satisfies the contract)**
-
-Run: `uv run pytest tests/test_init_template_contract.py -v`
-Expected: PASS — 5 checks × however many templates exist (just `transcribe` for now).
-
-> If any check fails for `transcribe`, the contract found a real defect — fix the
-> template, not the test. (The route-regex and import-detection are intentionally
-> conservative; if a legitimate future template pattern trips them, widen the regex
-> rather than weakening the assertion.)
-
-- [ ] **Step 3: Commit**
-
-```bash
-git add tests/test_init_template_contract.py
-git commit -m "test(init): parametrized template contract tests (keep examples working)"
-```
-
----
-
-## Self-review (completed during planning)
-
-**Spec coverage (this plan's scope = machinery + transcribe):**
-- Command surface, options, default behavior → Task 8. ✓
-- Arrow-key picker + non-interactive fallback → Task 8 (`_pick_template`). ✓
-- Approach A (copy committed real templates) → Tasks 4, 5. ✓
-- Flat Vercel-ready layout (`api/index.py`, `index.html`, `vercel.json`) → Task 4. ✓
-- Key handling: env→keyring, gitignored `.env`, placeholder + skip-launch when absent, key never in browser → Tasks 3, 5, 8 + template design. ✓
-- Install/launch: uv→venv fallback, free-port, launch+open, Ctrl-C clean exit → Tasks 6, 8. ✓
-- Step-status rendering + `--json` → Tasks 7, 8. ✓
-- Packaging template files (incl. dotfiles) → Tasks 1, 4, 5. ✓
-- Testing approach (TestClient, mocked subprocess/SDK, no real network) → Tasks 4, 6, 8. ✓
-- `stream`/`agent`/`llm` templates → **out of scope; sibling plans** (stated up front). ✓ (intentional)
-
-**Placeholder scan:** none — every code/step block is concrete.
-
-**Type/name consistency:** `scaffold.scaffold(template, target, *, api_key)`, `scaffold.target_conflict`, `scaffold.PLACEHOLDER_KEY`, `runner.has_uv/venv_python/env_setup_commands/serve_command/find_free_port/run_setup/launch_and_open`, `steps.Step`/`steps.render_steps`, `templates.TEMPLATES/TEMPLATE_ORDER/is_template/title_for`, `keys.resolve_optional_api_key` — used consistently across tasks.