From 249a93253840e9c891b6a6fc3b1de6f3620abfa5 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Fri, 5 Jun 2026 12:04:47 -0700
Subject: [PATCH 1/5] Add macOS system audio streaming

---
 CLAUDE.md                                     |   2 +-
 README.md                                     |  14 +-
 aai_cli/commands/init.py                      |  13 +-
 aai_cli/commands/stream.py                    | 224 +++++++---
 aai_cli/init/templates.py                     |  13 +-
 aai_cli/init/templates/agent/index.html       |  23 --
 .../init/templates/agent/static/styles.css    |  42 --
 .../AGENTS.md                                 |   6 +-
 .../README.md                                 |   0
 .../api/__init__.py                           |   0
 .../api/index.py                              |   0
 .../api/settings.py                           |   0
 .../env.example                               |   0
 .../{agent => audio-transcription}/gitignore  |   0
 .../templates/audio-transcription/index.html  |  45 +++
 .../requirements.txt                          |   0
 .../static/app.js                             |  31 +-
 .../audio-transcription/static/styles.css     | 381 ++++++++++++++++++
 .../vercel.json                               |   0
 .../{stream => live-captions}/AGENTS.md       |   6 +-
 .../{stream => live-captions}/README.md       |   0
 .../{stream => live-captions}/api/__init__.py |   0
 .../{stream => live-captions}/api/index.py    |   0
 .../{stream => live-captions}/api/settings.py |   0
 .../{stream => live-captions}/env.example     |   0
 .../{stream => live-captions}/gitignore       |   0
 .../init/templates/live-captions/index.html   |  29 ++
 .../{agent => live-captions}/requirements.txt |   0
 .../{stream => live-captions}/static/app.js   |   6 +-
 .../{stream => live-captions}/static/audio.js |   0
 .../templates/live-captions/static/styles.css | 179 ++++++++
 .../{stream => live-captions}/vercel.json     |   0
 aai_cli/init/templates/stream/index.html      |  23 --
 .../init/templates/stream/static/styles.css   |  48 ---
 aai_cli/init/templates/transcribe/index.html  |  43 --
 .../templates/transcribe/static/styles.css    | 117 ------
 .../{agent => voice-agent}/AGENTS.md          |   6 +-
 .../{agent => voice-agent}/README.md          |   0
 .../api/__init__.py                           |   0
 .../{agent => voice-agent}/api/index.py       |   0
 .../{agent => voice-agent}/api/settings.py    |   0
 .../{agent => voice-agent}/env.example        |   0
 .../{transcribe => voice-agent}/gitignore     |   0
 aai_cli/init/templates/voice-agent/index.html |  27 ++
 .../{stream => voice-agent}/requirements.txt  |   0
 .../{agent => voice-agent}/static/app.js      |  13 +-
 .../{agent => voice-agent}/static/audio.js    |   0
 .../templates/voice-agent/static/styles.css   | 186 +++++++++
 .../{transcribe => voice-agent}/vercel.json   |   0
 aai_cli/streaming/macos.py                    | 254 ++++++++++++
 aai_cli/streaming/macos_system_audio.swift    | 347 ++++++++++++++++
 aai_cli/streaming/render.py                   | 134 ++++--
 pyproject.toml                                |   2 +-
 scripts/check.sh                              |  33 ++
 scripts/template_contract_gate.py             |   2 +-
 .../test_cli_output_snapshots.ambr            |  18 +-
 tests/test_init_command.py                    |  39 +-
 tests/test_init_scaffold.py                   |  12 +-
 tests/test_init_template_agent.py             |   2 +-
 tests/test_init_template_contract.py          |   2 +-
 tests/test_init_template_stream.py            |   2 +-
 tests/test_init_template_transcribe.py        |   2 +-
 tests/test_init_templates.py                  |  10 +-
 tests/test_macos_audio_source.py              | 245 +++++++++++
 tests/test_stream_command.py                  | 143 +++++++
 tests/test_streaming_render.py                |  28 ++
 66 files changed, 2290 insertions(+), 462 deletions(-)
 delete mode 100644 aai_cli/init/templates/agent/index.html
 delete mode 100644 aai_cli/init/templates/agent/static/styles.css
 rename aai_cli/init/templates/{transcribe => audio-transcription}/AGENTS.md (71%)
 rename aai_cli/init/templates/{transcribe => audio-transcription}/README.md (100%)
 rename aai_cli/init/templates/{agent => audio-transcription}/api/__init__.py (100%)
 rename aai_cli/init/templates/{transcribe => audio-transcription}/api/index.py (100%)
 rename aai_cli/init/templates/{transcribe => audio-transcription}/api/settings.py (100%)
 rename aai_cli/init/templates/{transcribe => audio-transcription}/env.example (100%)
 rename aai_cli/init/templates/{agent => audio-transcription}/gitignore (100%)
 create mode 100644 aai_cli/init/templates/audio-transcription/index.html
 rename aai_cli/init/templates/{transcribe => audio-transcription}/requirements.txt (100%)
 rename aai_cli/init/templates/{transcribe => audio-transcription}/static/app.js (83%)
 create mode 100644 aai_cli/init/templates/audio-transcription/static/styles.css
 rename aai_cli/init/templates/{agent => audio-transcription}/vercel.json (100%)
 rename aai_cli/init/templates/{stream => live-captions}/AGENTS.md (73%)
 rename aai_cli/init/templates/{stream => live-captions}/README.md (100%)
 rename aai_cli/init/templates/{stream => live-captions}/api/__init__.py (100%)
 rename aai_cli/init/templates/{stream => live-captions}/api/index.py (100%)
 rename aai_cli/init/templates/{stream => live-captions}/api/settings.py (100%)
 rename aai_cli/init/templates/{stream => live-captions}/env.example (100%)
 rename aai_cli/init/templates/{stream => live-captions}/gitignore (100%)
 create mode 100644 aai_cli/init/templates/live-captions/index.html
 rename aai_cli/init/templates/{agent => live-captions}/requirements.txt (100%)
 rename aai_cli/init/templates/{stream => live-captions}/static/app.js (95%)
 rename aai_cli/init/templates/{stream => live-captions}/static/audio.js (100%)
 create mode 100644 aai_cli/init/templates/live-captions/static/styles.css
 rename aai_cli/init/templates/{stream => live-captions}/vercel.json (100%)
 delete mode 100644 aai_cli/init/templates/stream/index.html
 delete mode 100644 aai_cli/init/templates/stream/static/styles.css
 delete mode 100644 aai_cli/init/templates/transcribe/index.html
 delete mode 100644 aai_cli/init/templates/transcribe/static/styles.css
 rename aai_cli/init/templates/{agent => voice-agent}/AGENTS.md (75%)
 rename aai_cli/init/templates/{agent => voice-agent}/README.md (100%)
 rename aai_cli/init/templates/{transcribe => voice-agent}/api/__init__.py (100%)
 rename aai_cli/init/templates/{agent => voice-agent}/api/index.py (100%)
 rename aai_cli/init/templates/{agent => voice-agent}/api/settings.py (100%)
 rename aai_cli/init/templates/{agent => voice-agent}/env.example (100%)
 rename aai_cli/init/templates/{transcribe => voice-agent}/gitignore (100%)
 create mode 100644 aai_cli/init/templates/voice-agent/index.html
 rename aai_cli/init/templates/{stream => voice-agent}/requirements.txt (100%)
 rename aai_cli/init/templates/{agent => voice-agent}/static/app.js (93%)
 rename aai_cli/init/templates/{agent => voice-agent}/static/audio.js (100%)
 create mode 100644 aai_cli/init/templates/voice-agent/static/styles.css
 rename aai_cli/init/templates/{transcribe => voice-agent}/vercel.json (100%)
 create mode 100644 aai_cli/streaming/macos.py
 create mode 100644 aai_cli/streaming/macos_system_audio.swift
 create mode 100644 tests/test_macos_audio_source.py

diff --git a/CLAUDE.md b/CLAUDE.md
index 0756f0a1..5a9d3558 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -62,7 +62,7 @@ Each file in `aai_cli/commands/` is a Typer sub-app (`transcribe`, `stream`, `tr
 - **`agent/`** — full-duplex voice agent (mic in, TTS out via `voices.py`).
 - **`code_gen/`** — backs `--show-code` on `transcribe`/`stream`/`agent`: builds a ready-to-run Python SDK script from exactly the flags passed (no API key needed; generated code reads `ASSEMBLYAI_API_KEY`).
 - **`auth/`** — browser-assisted `aai login` via AMS + **Stytch B2B OAuth discovery** (`discovery.py`, `flow.py`, `loopback.py`, `ams.py`). Not Stytch Connected Apps.
-- **`init/`** — scaffolds a self-contained FastAPI + HTML starter (`transcribe`/`stream`/`agent` templates), optionally installs deps and opens the browser; writes the key to a git-ignored `.env`.
+- **`init/`** — scaffolds a self-contained FastAPI + HTML starter (`audio-transcription`/`live-captions`/`voice-agent` templates), optionally installs deps and opens the browser; writes the key to a git-ignored `.env`.
 - **`commands/claude.py`** — `aai claude install/status/remove` shells out to `claude mcp add` (the `assemblyai-docs` MCP) and `npx skills add` (the AssemblyAI skill). Missing `claude`/`npx` is reported and skipped, not an error.
 
 ## Conventions
diff --git a/README.md b/README.md
index 70f255fc..7981bf12 100644
--- a/README.md
+++ b/README.md
@@ -31,8 +31,8 @@ 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                            # pick a template, scaffold it, install deps, open the browser
+aai init audio-transcription myapp  # non-interactive: template + directory
 ```
 
 `aai init` copies a small, self-contained FastAPI + HTML project you can run locally
@@ -183,6 +183,8 @@ aai stream path/to/audio.wav   # 16 kHz mono WAV streams directly
 aai stream path/to/audio.mp3   # other formats need ffmpeg on PATH
 aai stream https://…/clip.mp3  # a URL works too (decoded via ffmpeg)
 aai stream                     # from the microphone; Ctrl-C to stop
+aai stream --system-audio      # macOS: system/app audio + mic as separate sessions
+aai stream --system-audio-only # macOS: system/app audio without the mic
 ```
 
 `aai stream` exposes the full `StreamingParameters` surface as curated flags:
@@ -208,6 +210,14 @@ aai stream --sample \
   --config vad_threshold=0.7
 ```
 
+On macOS, `--system-audio` uses ScreenCaptureKit to capture system/app audio
+without a loopback driver and streams it in a separate Streaming session from
+the microphone. The default terminal UI labels finalized turns as `You:` or
+`System:`. The first run may ask for Screen & System Audio Recording and
+Microphone permissions. The helper does not record screen frames, but macOS
+still uses that combined permission label for native system audio capture.
+`--system-audio-only` skips the microphone.
+
 ## Live transcript → live LLM
 
 `aai stream --llm "PROMPT"` runs a prompt over the live transcript through LLM Gateway,
diff --git a/aai_cli/commands/init.py b/aai_cli/commands/init.py
index a6dff8cb..b1f0c726 100644
--- a/aai_cli/commands/init.py
+++ b/aai_cli/commands/init.py
@@ -56,7 +56,7 @@ def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
         return Path.cwd()
     if directory:
         return Path(directory)
-    return Path.cwd() / f"{template}-app"
+    return Path.cwd() / template
 
 
 @app.command(
@@ -64,8 +64,11 @@ def _resolve_dir(directory: str | None, template: str, *, here: bool) -> Path:
     epilog=examples_epilog(
         [
             ("Scaffold a new app interactively", "aai init"),
-            ("Scaffold a transcribe app into ./my-app", "aai init transcribe my-app"),
-            ("Scaffold into the current directory", "aai init transcribe --here"),
+            (
+                "Scaffold an audio transcription app into ./my-app",
+                "aai init audio-transcription my-app",
+            ),
+            ("Scaffold into the current directory", "aai init audio-transcription --here"),
         ]
     ),
 )
@@ -74,9 +77,7 @@ def init(
     template: str | None = typer.Argument(
         None, help="Template to scaffold (omit to pick interactively)."
     ),
-    directory: str | None = typer.Argument(
-        None, help="Target directory (default: <template>-app)."
-    ),
+    directory: str | None = typer.Argument(None, help="Target directory (default: <template>)."),
     no_install: bool = typer.Option(
         False, "--no-install", help="Scaffold only; don't install or launch."
     ),
diff --git a/aai_cli/commands/stream.py b/aai_cli/commands/stream.py
index a7ef890e..57fcf607 100644
--- a/aai_cli/commands/stream.py
+++ b/aai_cli/commands/stream.py
@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+import queue
 import tempfile
+import threading
+from collections.abc import Iterable
 from pathlib import Path
 
 import typer
@@ -12,6 +15,7 @@
 from aai_cli.follow import FollowRenderer
 from aai_cli.help_text import examples_epilog
 from aai_cli.microphone import MicrophoneSource
+from aai_cli.streaming.macos import MacSystemAudioSource
 from aai_cli.streaming.render import StreamRenderer
 from aai_cli.streaming.sources import TARGET_RATE, FileSource, StdinSource
 
@@ -25,6 +29,7 @@
     epilog=examples_epilog(
         [
             ("Stream from your microphone", "aai stream"),
+            ("Stream mic + system audio on macOS", "aai stream --system-audio"),
             ("Stream the hosted sample", "aai stream --sample"),
             (
                 "Summarize action items live as you talk",
@@ -47,6 +52,16 @@ def stream(
         help="Force a microphone capture rate in Hz (default: device native).",
     ),
     device: int | None = typer.Option(None, "--device", help="Microphone device index."),
+    system_audio: bool = typer.Option(
+        False,
+        "--system-audio",
+        help="macOS only: stream system/app audio and microphone as separate sessions.",
+    ),
+    system_audio_only: bool = typer.Option(
+        False,
+        "--system-audio-only",
+        help="macOS only: stream system/app audio without the microphone.",
+    ),
     # model & input
     speech_model: str = typer.Option(
         DEFAULT_SPEECH_MODEL, "--speech-model", help="Streaming speech model."
@@ -141,6 +156,9 @@ def stream(
 
     def body(state: AppState, json_mode: bool) -> None:
         text_mode, json_mode = output.stream_output_modes(output_field, json_mode=json_mode)
+        from_stdin = source == "-"
+        from_file = bool(source) or sample
+        from_system_audio = system_audio or system_audio_only
 
         def make_flags(rate: int) -> dict[str, object]:
             flags: dict[str, object] = {
@@ -175,6 +193,8 @@ def make_flags(rate: int) -> dict[str, object]:
             # Print-only: emit the canonical microphone-streaming script (16 kHz) from
             # the flags and exit without opening audio or authenticating. Raw stdout so
             # `--show-code > script.py` yields a runnable file.
+            if from_system_audio:
+                raise UsageError("--show-code does not support macOS system audio capture yet.")
             merged = config_builder.merge_streaming_params(
                 flags=make_flags(TARGET_RATE),
                 overrides=list(config_kv or []),
@@ -185,9 +205,18 @@ def make_flags(rate: int) -> dict[str, object]:
             return
 
         api_key = config.resolve_api_key(profile=state.profile)
-        from_stdin = source == "-"
-        from_file = bool(source) or sample
-        if from_stdin:
+        if system_audio and system_audio_only:
+            raise UsageError("Use either --system-audio or --system-audio-only, not both.")
+        if from_system_audio:
+            if from_file:
+                raise UsageError(
+                    "--system-audio cannot be combined with an audio source or --sample."
+                )
+            if system_audio_only and (sample_rate is not None or device is not None):
+                raise UsageError(
+                    "--sample-rate and --device require microphone input; use --system-audio."
+                )
+        elif from_stdin:
             if device is not None:
                 raise UsageError("--device applies only to microphone input.")
         elif from_file and (sample_rate is not None or device is not None):
@@ -205,65 +234,158 @@ def make_flags(rate: int) -> dict[str, object]:
         llm_prompts = list(llm_prompt or [])
         follow = FollowRenderer(json_mode=json_mode) if llm_prompts else None
         transcript: list[str] = []
+        callback_lock = threading.RLock()
+        listening_lock = threading.Lock()
+        listening_started = False
 
-        def on_turn(event: object) -> None:
-            if follow is None:
-                renderer.turn(event)
-                return
-            # Live LLM mode: re-run the prompt chain over the growing transcript on every
-            # finalized turn, refreshing one evolving answer (partials are ignored).
-            if not getattr(event, "end_of_turn", False):
-                return
-            text = getattr(event, "transcript", "") or ""
-            if not text:
-                return
-            transcript.append(text)
-            answer = llm.run_chain(
-                api_key,
-                llm_prompts,
-                transcript_text=" ".join(transcript),
-                model=model,
-                max_tokens=max_tokens,
-            )
-            follow(answer, len(transcript))
+        def listening_once() -> None:
+            nonlocal listening_started
+            with listening_lock:
+                if listening_started:
+                    return
+                listening_started = True
+            renderer.listening()
+
+        def on_turn(event: object, *, source_label: str | None = None) -> None:
+            with callback_lock:
+                if follow is None:
+                    renderer.turn(event, source=source_label)
+                    return
+                # Live LLM mode: re-run the prompt chain over the growing transcript on every
+                # finalized turn, refreshing one evolving answer (partials are ignored).
+                if not getattr(event, "end_of_turn", False):
+                    return
+                text = getattr(event, "transcript", "") or ""
+                if not text:
+                    return
+                if source_label is not None:
+                    display_source = {"system": "System", "you": "You"}.get(
+                        source_label,
+                        source_label,
+                    )
+                    text = f"{display_source}: {text}"
+                transcript.append(text)
+                answer = llm.run_chain(
+                    api_key,
+                    llm_prompts,
+                    transcript_text=" ".join(transcript),
+                    model=model,
+                    max_tokens=max_tokens,
+                )
+                follow(answer, len(transcript))
 
-        def run(audio: FileSource | MicrophoneSource | StdinSource, rate: int) -> None:
+        def stream_one(
+            audio: Iterable[bytes],
+            rate: int,
+            *,
+            source_label: str | None = None,
+        ) -> None:
             merged = config_builder.merge_streaming_params(
                 flags=make_flags(rate), overrides=list(config_kv or []), config_file=config_file
             )
             params = config_builder.construct_streaming_params(merged)
+            client.stream_audio(
+                api_key,
+                audio,
+                params=params,
+                on_begin=(
+                    None
+                    if follow is not None
+                    else lambda event: renderer.begin(event, source=source_label)
+                ),
+                on_turn=lambda event: on_turn(event, source_label=source_label),
+                on_termination=(
+                    None
+                    if follow is not None
+                    else lambda event: renderer.termination(event, source=source_label)
+                ),
+            )
 
-            def drive() -> None:
+        def run(audio: Iterable[bytes], rate: int, *, source_label: str | None = None) -> None:
+            try:
+                # The FollowRenderer is a context manager (it owns the live panel); enter it
+                # around the whole session so it stops cleanly and prints the final answer.
+                if follow is not None:
+                    with follow:
+                        stream_one(audio, rate, source_label=source_label)
+                else:
+                    stream_one(audio, rate, source_label=source_label)
+            except KeyboardInterrupt:
+                # Ctrl-C is a normal "user stopped" signal -> exit 0.
+                if follow is None:
+                    renderer.close()
+                    renderer.stopped()
+            except BrokenPipeError:
+                # Downstream consumer (e.g. `| head`) closed the pipe; stop quietly.
+                raise typer.Exit(code=0) from None
+            finally:
+                if follow is None:
+                    renderer.close()
+
+        def run_parallel(streams: list[tuple[str, Iterable[bytes], int]]) -> None:
+            errors: queue.Queue[Exception] = queue.Queue()
+
+            def worker(source_label: str, audio: Iterable[bytes], rate: int) -> None:
                 try:
-                    client.stream_audio(
-                        api_key,
-                        audio,
-                        params=params,
-                        on_begin=None if follow is not None else renderer.begin,
-                        on_turn=on_turn,
-                        on_termination=None if follow is not None else renderer.termination,
+                    stream_one(audio, rate, source_label=source_label)
+                except Exception as exc:  # noqa: BLE001 - propagate worker failures on main thread
+                    errors.put(exc)
+
+            def drive() -> None:
+                threads = [
+                    threading.Thread(
+                        target=worker,
+                        args=(source_label, audio, rate),
+                        daemon=True,
                     )
-                except KeyboardInterrupt:
-                    # Ctrl-C is a normal "user stopped" signal -> exit 0.
-                    if follow is None:
-                        renderer.close()
-                        renderer.stopped()
-                except BrokenPipeError:
-                    # Downstream consumer (e.g. `| head`) closed the pipe; stop quietly.
-                    raise typer.Exit(code=0) from None
-                finally:
-                    if follow is None:
-                        renderer.close()
+                    for source_label, audio, rate in streams
+                ]
+                for thread in threads:
+                    thread.start()
+                while any(thread.is_alive() for thread in threads):
+                    for thread in threads:
+                        thread.join(timeout=0.1)
+                    if not errors.empty():
+                        raise errors.get()
+                if not errors.empty():
+                    raise errors.get()
 
-            # The FollowRenderer is a context manager (it owns the live panel); enter it
-            # around the whole session so it stops cleanly and prints the final answer.
-            if follow is not None:
-                with follow:
+            try:
+                if follow is not None:
+                    with follow:
+                        drive()
+                else:
                     drive()
-            else:
-                drive()
+            except KeyboardInterrupt:
+                if follow is None:
+                    renderer.close()
+                    renderer.stopped()
+            except BrokenPipeError:
+                raise typer.Exit(code=0) from None
+            finally:
+                if follow is None:
+                    renderer.close()
 
-        if from_stdin:
+        if from_system_audio:
+            system = MacSystemAudioSource(
+                on_open=(lambda: None) if follow is not None else listening_once,
+            )
+            if system_audio_only:
+                run(system, system.sample_rate, source_label="system")
+            else:
+                mic = MicrophoneSource(
+                    target_rate=TARGET_RATE,
+                    device=device,
+                    capture_rate=sample_rate,
+                    on_open=(lambda: None) if follow is not None else listening_once,
+                )
+                run_parallel(
+                    [
+                        ("system", system, system.sample_rate),
+                        ("you", mic, mic.sample_rate),
+                    ]
+                )
+        elif from_stdin:
             # Raw PCM16 mono piped on stdin (e.g. `ffmpeg … -f s16le - | aai stream -`).
             stdin_src = StdinSource(sample_rate=sample_rate or TARGET_RATE)
             run(stdin_src, stdin_src.sample_rate)
@@ -284,7 +406,7 @@ def drive() -> None:
                 device=device,
                 capture_rate=sample_rate,
                 # In --llm mode the FollowRenderer owns the screen, so skip the notice.
-                on_open=(lambda: None) if follow is not None else renderer.listening,
+                on_open=(lambda: None) if follow is not None else listening_once,
             )
             run(mic, mic.sample_rate)
 
diff --git a/aai_cli/init/templates.py b/aai_cli/init/templates.py
index 912ef1e0..a16ee625 100644
--- a/aai_cli/init/templates.py
+++ b/aai_cli/init/templates.py
@@ -1,17 +1,18 @@
 from __future__ import annotations
 
-# id -> human-facing title shown in the picker. Ids mirror the CLI's commands.
+# id -> human-facing title shown in the picker. Ids are Vercel-style
+# project/example slugs rather than CLI command names.
 #
 # 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 (+ chat with it via LLM Gateway)",
-    "stream": "Live captions (mic → browser)",
-    "agent": "Talk to a voice agent",
+    "audio-transcription": "Audio Transcription",
+    "live-captions": "Live Captions",
+    "voice-agent": "Voice Agent",
 }
 
-# Display order for the picker and `--help`, matching the CLI's command order.
-TEMPLATE_ORDER: tuple[str, ...] = ("transcribe", "stream", "agent")
+# Display order for the picker and `--help`.
+TEMPLATE_ORDER: tuple[str, ...] = ("audio-transcription", "live-captions", "voice-agent")
 
 
 def is_template(name: str) -> bool:
diff --git a/aai_cli/init/templates/agent/index.html b/aai_cli/init/templates/agent/index.html
deleted file mode 100644
index 99ff3ee4..00000000
--- a/aai_cli/init/templates/agent/index.html
+++ /dev/null
@@ -1,23 +0,0 @@
-<!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>
-  <link rel="stylesheet" href="/static/styles.css" />
-</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 src="/static/audio.js"></script>
-  <script src="/static/app.js"></script>
-</body>
-</html>
diff --git a/aai_cli/init/templates/agent/static/styles.css b/aai_cli/init/templates/agent/static/styles.css
deleted file mode 100644
index c14fc1ee..00000000
--- a/aai_cli/init/templates/agent/static/styles.css
+++ /dev/null
@@ -1,42 +0,0 @@
-: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: 8px;
-  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); }
diff --git a/aai_cli/init/templates/transcribe/AGENTS.md b/aai_cli/init/templates/audio-transcription/AGENTS.md
similarity index 71%
rename from aai_cli/init/templates/transcribe/AGENTS.md
rename to aai_cli/init/templates/audio-transcription/AGENTS.md
index 928a66b1..da68c6b4 100644
--- a/aai_cli/init/templates/transcribe/AGENTS.md
+++ b/aai_cli/init/templates/audio-transcription/AGENTS.md
@@ -11,8 +11,8 @@ uvicorn api.index:app --reload --port 3000
 - `api/settings.py`: backend customization for AssemblyAI config, sample URL, and LLM Gateway model.
 - `api/index.py`: server routes. Keep `ASSEMBLYAI_API_KEY` here on the server.
 - `static/app.js`: browser workflow, polling, tab rendering, and transcript Q&A UI.
-- `static/styles.css`: visual styling only.
-- `index.html`: page structure and static asset links.
+- `static/styles.css`: visual styling only; the top `:root` block is the primary theme/layout edit point.
+- `index.html`: page structure and static asset links. IDs are JavaScript hooks; classes are styling hooks.
 
 ## Change Points
 
@@ -20,6 +20,8 @@ uvicorn api.index:app --reload --port 3000
 - Sample audio URL: edit `SAMPLE_URL` in `api/settings.py` and the matching input value in `index.html`.
 - LLM answer behavior: edit `LLM_MODEL` in `api/settings.py` or the `/api/ask` prompt in `api/index.py`.
 - Transcript display: edit renderer functions in `static/app.js`.
+- Visual theme/layout: edit the monotone Vercel-style tokens in `static/styles.css` before changing component rules.
+- UI state styling: status, tabs, and sentiment use `data-state`, `.is-active`, or `data-sentiment`; prefer CSS changes over JS class rewrites.
 
 ## Invariants
 
diff --git a/aai_cli/init/templates/transcribe/README.md b/aai_cli/init/templates/audio-transcription/README.md
similarity index 100%
rename from aai_cli/init/templates/transcribe/README.md
rename to aai_cli/init/templates/audio-transcription/README.md
diff --git a/aai_cli/init/templates/agent/api/__init__.py b/aai_cli/init/templates/audio-transcription/api/__init__.py
similarity index 100%
rename from aai_cli/init/templates/agent/api/__init__.py
rename to aai_cli/init/templates/audio-transcription/api/__init__.py
diff --git a/aai_cli/init/templates/transcribe/api/index.py b/aai_cli/init/templates/audio-transcription/api/index.py
similarity index 100%
rename from aai_cli/init/templates/transcribe/api/index.py
rename to aai_cli/init/templates/audio-transcription/api/index.py
diff --git a/aai_cli/init/templates/transcribe/api/settings.py b/aai_cli/init/templates/audio-transcription/api/settings.py
similarity index 100%
rename from aai_cli/init/templates/transcribe/api/settings.py
rename to aai_cli/init/templates/audio-transcription/api/settings.py
diff --git a/aai_cli/init/templates/transcribe/env.example b/aai_cli/init/templates/audio-transcription/env.example
similarity index 100%
rename from aai_cli/init/templates/transcribe/env.example
rename to aai_cli/init/templates/audio-transcription/env.example
diff --git a/aai_cli/init/templates/agent/gitignore b/aai_cli/init/templates/audio-transcription/gitignore
similarity index 100%
rename from aai_cli/init/templates/agent/gitignore
rename to aai_cli/init/templates/audio-transcription/gitignore
diff --git a/aai_cli/init/templates/audio-transcription/index.html b/aai_cli/init/templates/audio-transcription/index.html
new file mode 100644
index 00000000..8ad004ba
--- /dev/null
+++ b/aai_cli/init/templates/audio-transcription/index.html
@@ -0,0 +1,45 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Transcribe a pre-recorded file · AssemblyAI</title>
+  <link rel="stylesheet" href="/static/styles.css" />
+</head>
+<body class="template-page audio-transcription-template">
+  <main class="app-shell">
+    <header class="page-header">
+      <h1 class="page-title">Transcribe a pre-recorded file</h1>
+      <p class="page-subtitle">Transcribe an audio or video URL (or upload a file), then explore speakers, chapters, sentiment, entities, and highlights.</p>
+    </header>
+
+    <section class="panel upload-panel">
+      <div class="control-row">
+        <input id="url" class="text-input url-input" type="url" value="https://assembly.ai/wildfires.mp3"
+               placeholder="https://example.com/audio.mp3" />
+        <button id="go" class="button button-primary">Transcribe</button>
+      </div>
+      <div class="divider">or</div>
+      <label class="upload-dropzone">
+        <input id="file" type="file" accept="audio/*,video/*" hidden />
+        Upload an audio or video file
+      </label>
+    </section>
+
+    <p id="status" class="status-pill" aria-live="polite"></p>
+
+    <section id="ask" class="panel qa-panel" hidden>
+      <div class="question-row">
+        <input id="q" class="text-input question-input" type="text" placeholder="Ask a question about this transcript..." />
+        <button id="askBtn" class="button button-primary">Ask</button>
+      </div>
+      <div id="answer" class="answer-panel"></div>
+    </section>
+
+    <nav id="tabs" class="tab-list" aria-label="Transcript views"></nav>
+    <div id="view" class="result-view"></div>
+  </main>
+
+  <script src="/static/app.js"></script>
+</body>
+</html>
diff --git a/aai_cli/init/templates/transcribe/requirements.txt b/aai_cli/init/templates/audio-transcription/requirements.txt
similarity index 100%
rename from aai_cli/init/templates/transcribe/requirements.txt
rename to aai_cli/init/templates/audio-transcription/requirements.txt
diff --git a/aai_cli/init/templates/transcribe/static/app.js b/aai_cli/init/templates/audio-transcription/static/app.js
similarity index 83%
rename from aai_cli/init/templates/transcribe/static/app.js
rename to aai_cli/init/templates/audio-transcription/static/app.js
index 0196047f..e42c8e73 100644
--- a/aai_cli/init/templates/transcribe/static/app.js
+++ b/aai_cli/init/templates/audio-transcription/static/app.js
@@ -1,7 +1,7 @@
 const APP_CONFIG = {
   sampleUrl: "https://assembly.ai/wildfires.mp3",
   pollIntervalMs: 2000,
-  speakerPalette: ["#4338ca", "#0d9488", "#b45309", "#be185d", "#15803d", "#7c3aed"],
+  speakerPalette: ["#171717", "#525252", "#737373", "#262626", "#404040", "#a3a3a3"],
 };
 
 const els = {
@@ -136,10 +136,11 @@ function renderTabs(views) {
   els.tabs.replaceChildren();
   for (const [index, view] of views.entries()) {
     const button = document.createElement("button");
+    button.className = "tab-button";
     button.textContent = view.label;
     button.addEventListener("click", () => {
       els.view.replaceChildren(view.render());
-      for (const child of els.tabs.children) child.classList.toggle("active", child === button);
+      for (const child of els.tabs.children) child.classList.toggle("is-active", child === button);
     });
     els.tabs.appendChild(button);
     if (index === 0) button.click();
@@ -151,14 +152,14 @@ function renderTranscript(transcript) {
   if (turns.length) {
     return fragment(turns.map((turn) => turnNode(turn.speaker, turn.text)));
   }
-  return element("pre", {}, transcript.text || "");
+  return element("pre", { className: "transcript-pre" }, transcript.text || "");
 }
 
 function renderSentiment(results) {
   return fragment(results.map((item) => {
-    const pill = element("span", { className: "sent" }, item.sentiment || "");
+    const pill = element("span", { className: "sentiment-pill" }, item.sentiment || "");
     if (["POSITIVE", "NEGATIVE", "NEUTRAL"].includes(item.sentiment)) {
-      pill.classList.add(item.sentiment);
+      pill.dataset.sentiment = item.sentiment.toLowerCase();
     }
     return turnNode(item.speaker || "?", item.text, pill);
   }));
@@ -166,11 +167,11 @@ function renderSentiment(results) {
 
 function renderChapters(chapters) {
   return fragment(chapters.map((chapter) => {
-    const node = element("div", { className: "chapter" });
+    const node = element("article", { className: "chapter-card" });
     node.append(
       element("h4", {}, chapter.headline || chapter.gist || "Chapter"),
-      element("span", { className: "time" }, `${fmt(chapter.start)} - ${fmt(chapter.end)}`),
-      element("p", {}, chapter.summary || chapter.gist || "")
+      element("span", { className: "timestamp" }, `${fmt(chapter.start)} - ${fmt(chapter.end)}`),
+      element("p", { className: "chapter-summary" }, chapter.summary || chapter.gist || "")
     );
     return node;
   }));
@@ -182,9 +183,9 @@ function renderEntities(entities) {
     (groups[entity.entity_type] ??= []).push(entity.text);
   }
   return fragment(Object.entries(groups).map(([type, items]) => {
-    const group = element("div", { className: "egroup" }, element("div", { className: "elabel" }, type));
+    const group = element("section", { className: "entity-group" }, element("div", { className: "entity-label" }, type));
     for (const text of new Set(items)) {
-      group.appendChild(element("span", { className: "etag" }, text));
+      group.appendChild(element("span", { className: "entity-tag" }, text));
     }
     return group;
   }));
@@ -192,20 +193,20 @@ function renderEntities(entities) {
 
 function renderHighlights(results) {
   return fragment([...results].sort((a, b) => b.rank - a.rank).map((highlight) =>
-    element("div", { className: "hl" }, element("span", { className: "count" }, `${highlight.count}x`), " ", highlight.text)
+    element("div", { className: "highlight-row" }, element("span", { className: "highlight-count" }, `${highlight.count}x`), " ", highlight.text)
   ));
 }
 
 function turnNode(speaker, text, extra = null) {
   const color = speakerColor(speaker);
-  const node = element("div", { className: "turn" });
+  const node = element("article", { className: "transcript-turn" });
   node.style.borderLeftColor = color;
 
-  const name = element("span", { className: "spk" }, `Speaker ${speaker}`);
+  const name = element("span", { className: "speaker-label" }, `Speaker ${speaker}`);
   name.style.color = color;
   node.append(name);
   if (extra) node.append(extra);
-  node.append(element("div", { className: "t" }, text));
+  node.append(element("div", { className: "transcript-text" }, text));
   return node;
 }
 
@@ -220,7 +221,7 @@ function busy(on) {
 
 function setStatus(message, state) {
   els.status.textContent = message;
-  els.status.className = state;
+  els.status.dataset.state = state;
 }
 
 function fail(message) {
diff --git a/aai_cli/init/templates/audio-transcription/static/styles.css b/aai_cli/init/templates/audio-transcription/static/styles.css
new file mode 100644
index 00000000..b5b29b4c
--- /dev/null
+++ b/aai_cli/init/templates/audio-transcription/static/styles.css
@@ -0,0 +1,381 @@
+/* THEME TOKENS: edit this block first for monotone colors, spacing, radii, and width. */
+:root {
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  --background: oklch(0.985 0 0);
+  --foreground: oklch(0.12 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.12 0 0);
+  --primary: oklch(0.12 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.965 0 0);
+  --secondary-foreground: oklch(0.38 0 0);
+  --muted: oklch(0.94 0 0);
+  --muted-foreground: oklch(0.58 0 0);
+  --accent: oklch(0.965 0 0);
+  --accent-foreground: oklch(0.12 0 0);
+  --border: oklch(0.9 0 0);
+  --input: oklch(0.9 0 0);
+  --ring: oklch(0.5 0 0);
+  --shadow-panel: 0 1px 3px oklch(0 0 0 / 0.05), 0 1px 1px oklch(0 0 0 / 0.03);
+  --shadow-focus: 0 0 0 1px oklch(0 0 0 / 0.08), 0 2px 8px -2px oklch(0 0 0 / 0.08);
+  --color-bg: var(--background);
+  --color-surface: var(--card);
+  --color-text: var(--foreground);
+  --color-text-muted: var(--muted-foreground);
+  --color-text-soft: var(--secondary-foreground);
+  --color-border: var(--border);
+  --color-accent: var(--primary);
+  --color-accent-contrast: var(--primary-foreground);
+  --color-accent-soft: var(--secondary);
+  --color-accent-tint: var(--muted);
+  --color-success: var(--foreground);
+  --color-success-soft: var(--secondary);
+  --color-danger: var(--foreground);
+  --color-danger-soft: var(--secondary);
+  --color-neutral: var(--secondary-foreground);
+  --color-neutral-soft: var(--secondary);
+  --radius-panel: 8px;
+  --radius-control: 8px;
+  --radius-pill: 999px;
+  --space-page-block: 48px;
+  --space-page-inline: 16px;
+  --space-panel: 20px;
+  --content-width: 760px;
+}
+
+/* BASE */
+* { box-sizing: border-box; }
+
+body {
+  min-height: 100vh;
+  margin: 0;
+  padding: var(--space-page-block) var(--space-page-inline);
+  background: var(--color-bg);
+  color: var(--color-text);
+  font: 15px/1.6 var(--font-sans);
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+button,
+input {
+  font: inherit;
+}
+
+button {
+  appearance: none;
+}
+
+[hidden] {
+  display: none !important;
+}
+
+/* LAYOUT */
+.app-shell {
+  max-width: var(--content-width);
+  margin: 0 auto;
+}
+
+.page-header {
+  margin-bottom: 24px;
+}
+
+.page-title {
+  margin: 0 0 4px;
+  font-size: 22px;
+  line-height: 1.25;
+}
+
+.page-subtitle {
+  max-width: 68ch;
+  margin: 0;
+  color: var(--color-text-muted);
+}
+
+.panel {
+  background: var(--color-surface);
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-panel);
+  box-shadow: var(--shadow-panel);
+  padding: var(--space-panel);
+}
+
+.qa-panel {
+  margin-bottom: 18px;
+}
+
+/* CONTROLS */
+.control-row,
+.question-row {
+  display: flex;
+  gap: 8px;
+}
+
+.text-input {
+  flex: 1;
+  min-width: 0;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-control);
+  padding: 11px 13px;
+  background: var(--color-surface);
+  color: var(--color-text);
+  font-size: 14px;
+}
+
+.text-input:focus {
+  border-color: var(--color-accent);
+  box-shadow: var(--shadow-focus);
+  outline: none;
+}
+
+.button {
+  --button-bg: var(--color-accent);
+  --button-fg: var(--color-accent-contrast);
+  display: inline-flex;
+  min-height: 44px;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: var(--radius-control);
+  background: var(--button-bg);
+  color: var(--button-fg);
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 600;
+  padding: 0 18px;
+  white-space: nowrap;
+}
+
+.button:hover:not(:disabled) {
+  filter: brightness(0.96);
+}
+
+.button:focus-visible,
+.tab-button:focus-visible,
+.upload-dropzone:focus-within {
+  box-shadow: var(--shadow-focus);
+  outline: none;
+}
+
+.button:disabled {
+  cursor: default;
+  opacity: 0.55;
+}
+
+.divider {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  margin: 16px 0;
+  color: var(--color-text-muted);
+  font-size: 13px;
+}
+
+.divider::before,
+.divider::after {
+  content: "";
+  flex: 1;
+  height: 1px;
+  background: var(--color-border);
+}
+
+.upload-dropzone {
+  display: block;
+  border: 1.5px dashed var(--color-border);
+  border-radius: var(--radius-control);
+  color: var(--color-text-muted);
+  cursor: pointer;
+  font-size: 14px;
+  padding: 16px;
+  text-align: center;
+}
+
+.upload-dropzone:hover {
+  border-color: var(--color-accent);
+  color: var(--color-accent);
+}
+
+/* STATUS STATES */
+.status-pill {
+  display: inline-block;
+  margin: 18px 0;
+  border-radius: var(--radius-pill);
+  font-size: 13px;
+  font-weight: 600;
+  padding: 6px 13px;
+}
+
+.status-pill:empty {
+  display: none;
+}
+
+.status-pill[data-state="working"] {
+  background: var(--color-accent-soft);
+  color: var(--color-accent);
+}
+
+.status-pill[data-state="done"] {
+  background: var(--color-success-soft);
+  color: var(--color-success);
+}
+
+.status-pill[data-state="error"] {
+  background: var(--color-danger-soft);
+  color: var(--color-danger);
+}
+
+/* TRANSCRIPT Q&A */
+.answer-panel {
+  margin-top: 12px;
+  border-radius: var(--radius-control);
+  background: var(--color-accent-tint);
+  color: var(--color-text);
+  padding: 12px 14px;
+  white-space: pre-wrap;
+}
+
+.answer-panel:empty {
+  display: none;
+}
+
+/* TABS */
+.tab-list {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin-bottom: 14px;
+}
+
+.tab-button {
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-pill);
+  background: var(--color-surface);
+  color: var(--color-text-soft);
+  cursor: pointer;
+  font-size: 13px;
+  font-weight: 600;
+  padding: 6px 14px;
+}
+
+.tab-button.is-active {
+  border-color: var(--color-accent);
+  background: var(--color-accent);
+  color: var(--color-accent-contrast);
+}
+
+/* RESULT VIEWS */
+.timestamp {
+  color: var(--color-text-muted);
+  font-size: 12px;
+  font-variant-numeric: tabular-nums;
+}
+
+.transcript-turn {
+  margin: 8px 0;
+  border-left: 3px solid var(--color-border);
+  padding: 8px 0 8px 12px;
+}
+
+.speaker-label {
+  font-weight: 700;
+}
+
+.transcript-text {
+  color: var(--color-text-soft);
+  overflow-wrap: anywhere;
+}
+
+.chapter-card,
+.entity-group {
+  border-top: 1px solid var(--color-border);
+  padding: 12px 0;
+}
+
+.chapter-card h4 {
+  margin: 0 0 2px;
+  font-size: 15px;
+}
+
+.chapter-summary {
+  margin: 4px 0 0;
+  color: var(--color-text-soft);
+}
+
+.entity-label {
+  color: var(--color-text-muted);
+  font-size: 11px;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+
+.entity-tag {
+  display: inline-block;
+  margin: 4px 4px 0 0;
+  border-radius: var(--radius-pill);
+  background: var(--color-accent-soft);
+  color: var(--color-accent);
+  font-size: 13px;
+  padding: 2px 10px;
+}
+
+.highlight-row {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  border-top: 1px solid var(--color-border);
+  padding: 8px 0;
+}
+
+.highlight-count {
+  border-radius: var(--radius-pill);
+  background: var(--color-accent-soft);
+  color: var(--color-accent);
+  font-size: 12px;
+  font-weight: 700;
+  padding: 2px 9px;
+}
+
+.sentiment-pill {
+  margin-left: 8px;
+  border-radius: var(--radius-pill);
+  font-size: 11px;
+  font-weight: 700;
+  padding: 1px 8px;
+}
+
+.sentiment-pill[data-sentiment="positive"] {
+  background: var(--color-success-soft);
+  color: var(--color-success);
+}
+
+.sentiment-pill[data-sentiment="negative"] {
+  background: var(--color-danger-soft);
+  color: var(--color-danger);
+}
+
+.sentiment-pill[data-sentiment="neutral"] {
+  background: var(--color-neutral-soft);
+  color: var(--color-neutral);
+}
+
+.transcript-pre {
+  margin: 0;
+  font: inherit;
+  white-space: pre-wrap;
+}
+
+@media (max-width: 640px) {
+  :root {
+    --space-page-block: 32px;
+  }
+
+  .control-row,
+  .question-row {
+    flex-direction: column;
+  }
+
+  .button {
+    width: 100%;
+  }
+}
diff --git a/aai_cli/init/templates/agent/vercel.json b/aai_cli/init/templates/audio-transcription/vercel.json
similarity index 100%
rename from aai_cli/init/templates/agent/vercel.json
rename to aai_cli/init/templates/audio-transcription/vercel.json
diff --git a/aai_cli/init/templates/stream/AGENTS.md b/aai_cli/init/templates/live-captions/AGENTS.md
similarity index 73%
rename from aai_cli/init/templates/stream/AGENTS.md
rename to aai_cli/init/templates/live-captions/AGENTS.md
index 5ee0cdee..038971b4 100644
--- a/aai_cli/init/templates/stream/AGENTS.md
+++ b/aai_cli/init/templates/live-captions/AGENTS.md
@@ -12,8 +12,8 @@ uvicorn api.index:app --reload --port 3000
 - `api/index.py`: `/api/token` route. Keep `ASSEMBLYAI_API_KEY` here on the server.
 - `static/app.js`: browser state, WebSocket lifecycle, and Streaming API params.
 - `static/audio.js`: microphone pipeline and PCM downsampling helpers.
-- `static/styles.css`: visual styling only.
-- `index.html`: page structure and static asset links.
+- `static/styles.css`: visual styling only; the top `:root` block is the primary theme/layout edit point.
+- `index.html`: page structure and static asset links. IDs are JavaScript hooks; classes are styling hooks.
 
 ## Change Points
 
@@ -21,6 +21,8 @@ uvicorn api.index:app --reload --port 3000
 - Backend token lifetime or non-production hosts: edit `api/settings.py`.
 - Caption rendering: edit `onMessage` in `static/app.js`.
 - Microphone/downsampling behavior: edit `static/audio.js`.
+- Visual theme/layout: edit the monotone Vercel-style tokens in `static/styles.css` before changing component rules.
+- UI state styling: record and status state use `data-state`; prefer CSS changes over JS class rewrites.
 
 ## Invariants
 
diff --git a/aai_cli/init/templates/stream/README.md b/aai_cli/init/templates/live-captions/README.md
similarity index 100%
rename from aai_cli/init/templates/stream/README.md
rename to aai_cli/init/templates/live-captions/README.md
diff --git a/aai_cli/init/templates/stream/api/__init__.py b/aai_cli/init/templates/live-captions/api/__init__.py
similarity index 100%
rename from aai_cli/init/templates/stream/api/__init__.py
rename to aai_cli/init/templates/live-captions/api/__init__.py
diff --git a/aai_cli/init/templates/stream/api/index.py b/aai_cli/init/templates/live-captions/api/index.py
similarity index 100%
rename from aai_cli/init/templates/stream/api/index.py
rename to aai_cli/init/templates/live-captions/api/index.py
diff --git a/aai_cli/init/templates/stream/api/settings.py b/aai_cli/init/templates/live-captions/api/settings.py
similarity index 100%
rename from aai_cli/init/templates/stream/api/settings.py
rename to aai_cli/init/templates/live-captions/api/settings.py
diff --git a/aai_cli/init/templates/stream/env.example b/aai_cli/init/templates/live-captions/env.example
similarity index 100%
rename from aai_cli/init/templates/stream/env.example
rename to aai_cli/init/templates/live-captions/env.example
diff --git a/aai_cli/init/templates/stream/gitignore b/aai_cli/init/templates/live-captions/gitignore
similarity index 100%
rename from aai_cli/init/templates/stream/gitignore
rename to aai_cli/init/templates/live-captions/gitignore
diff --git a/aai_cli/init/templates/live-captions/index.html b/aai_cli/init/templates/live-captions/index.html
new file mode 100644
index 00000000..82d9a81e
--- /dev/null
+++ b/aai_cli/init/templates/live-captions/index.html
@@ -0,0 +1,29 @@
+<!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>
+  <link rel="stylesheet" href="/static/styles.css" />
+</head>
+<body class="template-page live-captions-template">
+  <main class="app-shell">
+    <header class="page-header">
+      <h1 class="page-title">Live captions</h1>
+      <p class="page-subtitle">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>
+    </header>
+
+    <div class="control-bar">
+      <button id="rec" class="button record-button" data-state="idle">● Record</button>
+      <span id="status" class="status-pill" aria-live="polite"></span>
+    </div>
+
+    <div class="caption-output" aria-live="polite">
+      <span id="final" class="caption-final"></span><span id="partial" class="caption-partial"></span>
+    </div>
+  </main>
+
+  <script src="/static/audio.js"></script>
+  <script src="/static/app.js"></script>
+</body>
+</html>
diff --git a/aai_cli/init/templates/agent/requirements.txt b/aai_cli/init/templates/live-captions/requirements.txt
similarity index 100%
rename from aai_cli/init/templates/agent/requirements.txt
rename to aai_cli/init/templates/live-captions/requirements.txt
diff --git a/aai_cli/init/templates/stream/static/app.js b/aai_cli/init/templates/live-captions/static/app.js
similarity index 95%
rename from aai_cli/init/templates/stream/static/app.js
rename to aai_cli/init/templates/live-captions/static/app.js
index 5d2c653c..7138f8c4 100644
--- a/aai_cli/init/templates/stream/static/app.js
+++ b/aai_cli/init/templates/live-captions/static/app.js
@@ -19,7 +19,7 @@ recBtn.addEventListener("click", () => (recording ? stop() : start().catch(fail)
 
 function setStatus(message, state) {
   statusEl.textContent = message;
-  statusEl.className = state;
+  statusEl.dataset.state = state;
 }
 
 async function start() {
@@ -46,7 +46,7 @@ async function start() {
   ws.onopen = () => {
     recording = true;
     recBtn.textContent = "■ Stop";
-    recBtn.classList.add("rec");
+    recBtn.dataset.state = "recording";
     setStatus("● Live", "live");
     audioPipeline.connect((frame, sampleRate) => {
       if (ws && ws.readyState === WebSocket.OPEN) {
@@ -74,7 +74,7 @@ function onMessage(message) {
 function stop() {
   recording = false;
   recBtn.textContent = "● Record";
-  recBtn.classList.remove("rec");
+  recBtn.dataset.state = "idle";
   setStatus("Stopped", "idle");
   if (ws && ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ type: "Terminate" }));
   if (audioPipeline) audioPipeline.close();
diff --git a/aai_cli/init/templates/stream/static/audio.js b/aai_cli/init/templates/live-captions/static/audio.js
similarity index 100%
rename from aai_cli/init/templates/stream/static/audio.js
rename to aai_cli/init/templates/live-captions/static/audio.js
diff --git a/aai_cli/init/templates/live-captions/static/styles.css b/aai_cli/init/templates/live-captions/static/styles.css
new file mode 100644
index 00000000..d7707f65
--- /dev/null
+++ b/aai_cli/init/templates/live-captions/static/styles.css
@@ -0,0 +1,179 @@
+/* THEME TOKENS: edit this block first for monotone colors, spacing, radii, and width. */
+:root {
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  --background: oklch(0.985 0 0);
+  --foreground: oklch(0.12 0 0);
+  --card: oklch(1 0 0);
+  --primary: oklch(0.12 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.965 0 0);
+  --secondary-foreground: oklch(0.38 0 0);
+  --muted-foreground: oklch(0.58 0 0);
+  --border: oklch(0.9 0 0);
+  --ring: oklch(0.5 0 0);
+  --shadow-panel: 0 1px 3px oklch(0 0 0 / 0.05), 0 1px 1px oklch(0 0 0 / 0.03);
+  --shadow-focus: 0 0 0 1px oklch(0 0 0 / 0.08), 0 2px 8px -2px oklch(0 0 0 / 0.08);
+  --color-bg: var(--background);
+  --color-surface: var(--card);
+  --color-text: var(--foreground);
+  --color-text-muted: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-accent: var(--primary);
+  --color-accent-contrast: var(--primary-foreground);
+  --color-danger: var(--foreground);
+  --color-danger-strong: var(--foreground);
+  --color-danger-soft: var(--secondary);
+  --color-neutral: var(--secondary-foreground);
+  --color-neutral-soft: var(--secondary);
+  --radius-panel: 8px;
+  --radius-control: 8px;
+  --radius-pill: 999px;
+  --space-page-block: 48px;
+  --space-page-inline: 16px;
+  --content-width: 720px;
+}
+
+/* BASE */
+* { box-sizing: border-box; }
+
+body {
+  min-height: 100vh;
+  margin: 0;
+  padding: var(--space-page-block) var(--space-page-inline);
+  background: var(--color-bg);
+  color: var(--color-text);
+  font: 15px/1.6 var(--font-sans);
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+button {
+  appearance: none;
+  font: inherit;
+}
+
+/* LAYOUT */
+.app-shell {
+  max-width: var(--content-width);
+  margin: 0 auto;
+}
+
+.page-header {
+  margin-bottom: 24px;
+}
+
+.page-title {
+  margin: 0 0 4px;
+  font-size: 22px;
+  line-height: 1.25;
+}
+
+.page-subtitle {
+  max-width: 68ch;
+  margin: 0;
+  color: var(--color-text-muted);
+}
+
+.control-bar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+/* CONTROLS */
+.button {
+  --button-bg: var(--color-accent);
+  --button-fg: var(--color-accent-contrast);
+  display: inline-flex;
+  min-height: 44px;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: var(--radius-control);
+  background: var(--button-bg);
+  color: var(--button-fg);
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 600;
+  padding: 0 20px;
+  white-space: nowrap;
+}
+
+.button:hover:not(:disabled) {
+  filter: brightness(0.96);
+}
+
+.button:focus-visible {
+  box-shadow: var(--shadow-focus);
+  outline: none;
+}
+
+.button:disabled {
+  cursor: default;
+  opacity: 0.55;
+}
+
+.record-button[data-state="recording"] {
+  --button-bg: var(--color-danger-strong);
+}
+
+/* STATUS STATES */
+.status-pill {
+  display: inline-block;
+  border-radius: var(--radius-pill);
+  font-size: 13px;
+  font-weight: 600;
+  padding: 5px 12px;
+}
+
+.status-pill:empty {
+  display: none;
+}
+
+.status-pill[data-state="live"],
+.status-pill[data-state="error"] {
+  background: var(--color-danger-soft);
+  color: var(--color-danger);
+}
+
+.status-pill[data-state="idle"] {
+  background: var(--color-neutral-soft);
+  color: var(--color-neutral);
+}
+
+/* CAPTION VIEW */
+.caption-output {
+  min-height: 120px;
+  margin-top: 24px;
+  border: 1px solid var(--color-border);
+  border-radius: var(--radius-panel);
+  background: var(--color-surface);
+  box-shadow: var(--shadow-panel);
+  font-size: 19px;
+  line-height: 1.7;
+  padding: 18px;
+}
+
+.caption-final {
+  color: var(--color-text);
+}
+
+.caption-partial {
+  color: var(--color-text-muted);
+}
+
+@media (max-width: 640px) {
+  :root {
+    --space-page-block: 32px;
+  }
+
+  .button {
+    width: 100%;
+  }
+
+  .status-pill {
+    width: 100%;
+  }
+}
diff --git a/aai_cli/init/templates/stream/vercel.json b/aai_cli/init/templates/live-captions/vercel.json
similarity index 100%
rename from aai_cli/init/templates/stream/vercel.json
rename to aai_cli/init/templates/live-captions/vercel.json
diff --git a/aai_cli/init/templates/stream/index.html b/aai_cli/init/templates/stream/index.html
deleted file mode 100644
index 5fba1d40..00000000
--- a/aai_cli/init/templates/stream/index.html
+++ /dev/null
@@ -1,23 +0,0 @@
-<!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>
-  <link rel="stylesheet" href="/static/styles.css" />
-</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 src="/static/audio.js"></script>
-  <script src="/static/app.js"></script>
-</body>
-</html>
diff --git a/aai_cli/init/templates/stream/static/styles.css b/aai_cli/init/templates/stream/static/styles.css
deleted file mode 100644
index bf689671..00000000
--- a/aai_cli/init/templates/stream/static/styles.css
+++ /dev/null
@@ -1,48 +0,0 @@
-: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: 8px;
-  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: 8px;
-  padding: 18px;
-}
-.final { color: #111827; }
-.partial { color: var(--muted); }
diff --git a/aai_cli/init/templates/transcribe/index.html b/aai_cli/init/templates/transcribe/index.html
deleted file mode 100644
index 5e9f1ed8..00000000
--- a/aai_cli/init/templates/transcribe/index.html
+++ /dev/null
@@ -1,43 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8" />
-  <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <title>Transcribe a pre-recorded file · AssemblyAI</title>
-  <link rel="stylesheet" href="/static/styles.css" />
-</head>
-<body>
-  <main>
-    <h1>🎧 Transcribe a pre-recorded file</h1>
-    <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">
-        <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="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>
-
-  <script src="/static/app.js"></script>
-</body>
-</html>
diff --git a/aai_cli/init/templates/transcribe/static/styles.css b/aai_cli/init/templates/transcribe/static/styles.css
deleted file mode 100644
index 3b481928..00000000
--- a/aai_cli/init/templates/transcribe/static/styles.css
+++ /dev/null
@@ -1,117 +0,0 @@
-: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: 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: 8px; padding: 20px; }
-.row { display: flex; gap: 8px; }
-input[type=url],
-#ask input {
-  flex: 1;
-  min-width: 0;
-  padding: 11px 13px;
-  border: 1px solid var(--line);
-  border-radius: 8px;
-  font-size: 14px;
-}
-input[type=url]:focus,
-#ask input:focus { outline: none; border-color: var(--accent); }
-button {
-  background: var(--accent);
-  color: #fff;
-  border: 0;
-  border-radius: 8px;
-  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: 8px;
-  color: var(--muted);
-  cursor: pointer;
-  font-size: 14px;
-}
-.upload:hover { border-color: var(--accent); 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; }
-#ask { margin: 0 0 18px; }
-#ask .q { display: flex; gap: 8px; }
-.answer {
-  margin-top: 12px;
-  padding: 12px 14px;
-  background: #f5f3ff;
-  border-radius: 8px;
-  white-space: pre-wrap;
-  color: #1e1b4b;
-}
-.answer:empty { display: none; }
-.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; }
-.turn { padding: 8px 0 8px 12px; border-left: 3px solid var(--line); margin: 8px 0; }
-.spk { font-weight: 700; }
-.turn .t { color: #374151; }
-.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; }
-.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;
-}
-.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; }
-.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; }
diff --git a/aai_cli/init/templates/agent/AGENTS.md b/aai_cli/init/templates/voice-agent/AGENTS.md
similarity index 75%
rename from aai_cli/init/templates/agent/AGENTS.md
rename to aai_cli/init/templates/voice-agent/AGENTS.md
index a9cda2b4..6719c1c7 100644
--- a/aai_cli/init/templates/agent/AGENTS.md
+++ b/aai_cli/init/templates/voice-agent/AGENTS.md
@@ -12,8 +12,8 @@ uvicorn api.index:app --reload --port 3000
 - `api/index.py`: `/api/token` route. Keep `ASSEMBLYAI_API_KEY` here on the server.
 - `static/app.js`: Voice Agent session config, WebSocket lifecycle, UI state, and event handling.
 - `static/audio.js`: microphone pipeline, PCM conversion, playback queue, and barge-in helpers.
-- `static/styles.css`: visual styling only.
-- `index.html`: page structure and static asset links.
+- `static/styles.css`: visual styling only; the top `:root` block is the primary theme/layout edit point.
+- `index.html`: page structure and static asset links. IDs are JavaScript hooks; classes are styling hooks.
 
 ## Change Points
 
@@ -21,6 +21,8 @@ uvicorn api.index:app --reload --port 3000
 - Backend token lifetime or non-production hosts: edit `api/settings.py`.
 - Transcript log rendering: edit `addTurn` in `static/app.js`.
 - Playback, barge-in, or PCM conversion: edit `static/audio.js`.
+- Visual theme/layout: edit the monotone Vercel-style tokens in `static/styles.css` before changing component rules.
+- UI state styling: connection, status, and speaker state use `data-state` or `data-speaker`; prefer CSS changes over JS class rewrites.
 
 ## Invariants
 
diff --git a/aai_cli/init/templates/agent/README.md b/aai_cli/init/templates/voice-agent/README.md
similarity index 100%
rename from aai_cli/init/templates/agent/README.md
rename to aai_cli/init/templates/voice-agent/README.md
diff --git a/aai_cli/init/templates/transcribe/api/__init__.py b/aai_cli/init/templates/voice-agent/api/__init__.py
similarity index 100%
rename from aai_cli/init/templates/transcribe/api/__init__.py
rename to aai_cli/init/templates/voice-agent/api/__init__.py
diff --git a/aai_cli/init/templates/agent/api/index.py b/aai_cli/init/templates/voice-agent/api/index.py
similarity index 100%
rename from aai_cli/init/templates/agent/api/index.py
rename to aai_cli/init/templates/voice-agent/api/index.py
diff --git a/aai_cli/init/templates/agent/api/settings.py b/aai_cli/init/templates/voice-agent/api/settings.py
similarity index 100%
rename from aai_cli/init/templates/agent/api/settings.py
rename to aai_cli/init/templates/voice-agent/api/settings.py
diff --git a/aai_cli/init/templates/agent/env.example b/aai_cli/init/templates/voice-agent/env.example
similarity index 100%
rename from aai_cli/init/templates/agent/env.example
rename to aai_cli/init/templates/voice-agent/env.example
diff --git a/aai_cli/init/templates/transcribe/gitignore b/aai_cli/init/templates/voice-agent/gitignore
similarity index 100%
rename from aai_cli/init/templates/transcribe/gitignore
rename to aai_cli/init/templates/voice-agent/gitignore
diff --git a/aai_cli/init/templates/voice-agent/index.html b/aai_cli/init/templates/voice-agent/index.html
new file mode 100644
index 00000000..8c5f7e6b
--- /dev/null
+++ b/aai_cli/init/templates/voice-agent/index.html
@@ -0,0 +1,27 @@
+<!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>
+  <link rel="stylesheet" href="/static/styles.css" />
+</head>
+<body class="template-page voice-agent-template">
+  <main class="app-shell">
+    <header class="page-header">
+      <h1 class="page-title">Talk to a voice agent</h1>
+      <p class="page-subtitle">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>
+    </header>
+
+    <div class="control-bar">
+      <button id="conn" class="button connection-button" data-state="idle">● Connect</button>
+      <span id="status" class="status-pill" aria-live="polite"></span>
+    </div>
+
+    <div id="log" class="conversation-log"></div>
+  </main>
+
+  <script src="/static/audio.js"></script>
+  <script src="/static/app.js"></script>
+</body>
+</html>
diff --git a/aai_cli/init/templates/stream/requirements.txt b/aai_cli/init/templates/voice-agent/requirements.txt
similarity index 100%
rename from aai_cli/init/templates/stream/requirements.txt
rename to aai_cli/init/templates/voice-agent/requirements.txt
diff --git a/aai_cli/init/templates/agent/static/app.js b/aai_cli/init/templates/voice-agent/static/app.js
similarity index 93%
rename from aai_cli/init/templates/agent/static/app.js
rename to aai_cli/init/templates/voice-agent/static/app.js
index aa57a55c..044886e5 100644
--- a/aai_cli/init/templates/agent/static/app.js
+++ b/aai_cli/init/templates/voice-agent/static/app.js
@@ -22,7 +22,7 @@ connBtn.addEventListener("click", () => (connected ? hangup() : connect().catch(
 
 function setStatus(message, state) {
   statusEl.textContent = message;
-  statusEl.className = state;
+  statusEl.dataset.state = state;
 }
 
 async function connect() {
@@ -67,7 +67,7 @@ async function startMic() {
 
   connected = true;
   connBtn.textContent = "■ Hang up";
-  connBtn.classList.add("live");
+  connBtn.dataset.state = "connected";
   setStatus("● Connected - just talk", "live");
 }
 
@@ -93,12 +93,13 @@ function bargeIn() {
   if (player) player.stopQueuedAudio();
 }
 
-function addTurn(className, speaker, text) {
+function addTurn(speakerKind, speaker, text) {
   if (!text) return;
   const turn = document.createElement("div");
-  turn.className = "turn " + className;
+  turn.className = "conversation-turn";
+  turn.dataset.speaker = speakerKind;
   const who = document.createElement("span");
-  who.className = "who";
+  who.className = "turn-speaker";
   who.textContent = speaker + ": ";
   turn.append(who, document.createTextNode(text));
   logEl.appendChild(turn);
@@ -108,7 +109,7 @@ function addTurn(className, speaker, text) {
 function hangup() {
   connected = false;
   connBtn.textContent = "● Connect";
-  connBtn.classList.remove("live");
+  connBtn.dataset.state = "idle";
   setStatus("Disconnected", "idle");
   bargeIn();
   if (ws && ws.readyState === WebSocket.OPEN) ws.close();
diff --git a/aai_cli/init/templates/agent/static/audio.js b/aai_cli/init/templates/voice-agent/static/audio.js
similarity index 100%
rename from aai_cli/init/templates/agent/static/audio.js
rename to aai_cli/init/templates/voice-agent/static/audio.js
diff --git a/aai_cli/init/templates/voice-agent/static/styles.css b/aai_cli/init/templates/voice-agent/static/styles.css
new file mode 100644
index 00000000..75d997d9
--- /dev/null
+++ b/aai_cli/init/templates/voice-agent/static/styles.css
@@ -0,0 +1,186 @@
+/* THEME TOKENS: edit this block first for monotone colors, spacing, radii, and width. */
+:root {
+  --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", system-ui, sans-serif;
+  --background: oklch(0.985 0 0);
+  --foreground: oklch(0.12 0 0);
+  --card: oklch(1 0 0);
+  --primary: oklch(0.12 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.965 0 0);
+  --secondary-foreground: oklch(0.38 0 0);
+  --muted-foreground: oklch(0.58 0 0);
+  --border: oklch(0.9 0 0);
+  --shadow-focus: 0 0 0 1px oklch(0 0 0 / 0.08), 0 2px 8px -2px oklch(0 0 0 / 0.08);
+  --color-bg: var(--background);
+  --color-surface: var(--card);
+  --color-text: var(--foreground);
+  --color-text-muted: var(--muted-foreground);
+  --color-border: var(--border);
+  --color-accent: var(--primary);
+  --color-accent-contrast: var(--primary-foreground);
+  --color-user: oklch(0.42 0 0);
+  --color-success: var(--foreground);
+  --color-success-soft: var(--secondary);
+  --color-danger: var(--foreground);
+  --color-danger-strong: var(--foreground);
+  --color-danger-soft: var(--secondary);
+  --color-neutral: var(--secondary-foreground);
+  --color-neutral-soft: var(--secondary);
+  --radius-control: 8px;
+  --radius-pill: 999px;
+  --space-page-block: 48px;
+  --space-page-inline: 16px;
+  --content-width: 720px;
+}
+
+/* BASE */
+* { box-sizing: border-box; }
+
+body {
+  min-height: 100vh;
+  margin: 0;
+  padding: var(--space-page-block) var(--space-page-inline);
+  background: var(--color-bg);
+  color: var(--color-text);
+  font: 15px/1.6 var(--font-sans);
+  -moz-osx-font-smoothing: grayscale;
+  -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
+}
+
+button {
+  appearance: none;
+  font: inherit;
+}
+
+/* LAYOUT */
+.app-shell {
+  max-width: var(--content-width);
+  margin: 0 auto;
+}
+
+.page-header {
+  margin-bottom: 24px;
+}
+
+.page-title {
+  margin: 0 0 4px;
+  font-size: 22px;
+  line-height: 1.25;
+}
+
+.page-subtitle {
+  max-width: 68ch;
+  margin: 0;
+  color: var(--color-text-muted);
+}
+
+.control-bar {
+  display: flex;
+  align-items: center;
+  flex-wrap: wrap;
+  gap: 12px;
+}
+
+/* CONTROLS */
+.button {
+  --button-bg: var(--color-accent);
+  --button-fg: var(--color-accent-contrast);
+  display: inline-flex;
+  min-height: 44px;
+  align-items: center;
+  justify-content: center;
+  border: 0;
+  border-radius: var(--radius-control);
+  background: var(--button-bg);
+  color: var(--button-fg);
+  cursor: pointer;
+  font-size: 14px;
+  font-weight: 600;
+  padding: 0 20px;
+  white-space: nowrap;
+}
+
+.button:hover:not(:disabled) {
+  filter: brightness(0.96);
+}
+
+.button:focus-visible {
+  box-shadow: var(--shadow-focus);
+  outline: none;
+}
+
+.connection-button[data-state="connected"] {
+  --button-bg: var(--color-danger-strong);
+}
+
+/* STATUS STATES */
+.status-pill {
+  display: inline-block;
+  border-radius: var(--radius-pill);
+  font-size: 13px;
+  font-weight: 600;
+  padding: 5px 12px;
+}
+
+.status-pill:empty {
+  display: none;
+}
+
+.status-pill[data-state="live"] {
+  background: var(--color-success-soft);
+  color: var(--color-success);
+}
+
+.status-pill[data-state="idle"] {
+  background: var(--color-neutral-soft);
+  color: var(--color-neutral);
+}
+
+.status-pill[data-state="error"] {
+  background: var(--color-danger-soft);
+  color: var(--color-danger);
+}
+
+/* CONVERSATION VIEW */
+.conversation-log {
+  margin-top: 24px;
+}
+
+.conversation-turn {
+  margin: 8px 0;
+  border-left: 3px solid var(--color-border);
+  padding: 8px 0 8px 12px;
+  overflow-wrap: anywhere;
+}
+
+.conversation-turn[data-speaker="you"] {
+  border-left-color: var(--color-user);
+}
+
+.conversation-turn[data-speaker="agent"] {
+  border-left-color: var(--color-accent);
+}
+
+.turn-speaker {
+  font-weight: 700;
+}
+
+.conversation-turn[data-speaker="you"] .turn-speaker {
+  color: var(--color-user);
+}
+
+.conversation-turn[data-speaker="agent"] .turn-speaker {
+  color: var(--color-accent);
+}
+
+@media (max-width: 640px) {
+  :root {
+    --space-page-block: 32px;
+  }
+
+  .button,
+  .status-pill {
+    width: 100%;
+  }
+}
diff --git a/aai_cli/init/templates/transcribe/vercel.json b/aai_cli/init/templates/voice-agent/vercel.json
similarity index 100%
rename from aai_cli/init/templates/transcribe/vercel.json
rename to aai_cli/init/templates/voice-agent/vercel.json
diff --git a/aai_cli/streaming/macos.py b/aai_cli/streaming/macos.py
new file mode 100644
index 00000000..810278e0
--- /dev/null
+++ b/aai_cli/streaming/macos.py
@@ -0,0 +1,254 @@
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import io
+import shutil
+import signal
+import subprocess
+import sys
+from collections.abc import Callable, Generator, Sequence
+from importlib import resources
+from pathlib import Path
+from typing import IO, Protocol, TypeAlias
+
+from platformdirs import user_cache_path
+
+from aai_cli.errors import APIError, CLIError
+from aai_cli.streaming.sources import CHUNK_BYTES, TARGET_RATE
+
+_HELPER_RESOURCE = "macos_system_audio.swift"
+_CACHE_DIR = "macos-system-audio"
+_HELPER_PREFIX = "aai-macos-audio"
+_Pipe: TypeAlias = IO[bytes] | io.BytesIO
+
+
+class _CaptureProcess(Protocol):
+    @property
+    def stdout(self) -> _Pipe | None: ...
+
+    @property
+    def stderr(self) -> _Pipe | None: ...
+
+    @property
+    def returncode(self) -> int | None: ...
+
+    def poll(self) -> int | None: ...
+
+    def terminate(self) -> None: ...
+
+    def kill(self) -> None: ...
+
+    def wait(self, timeout: float | None = None) -> int | None: ...
+
+
+def _unsupported_platform() -> CLIError:
+    return CLIError(
+        "macOS system audio capture is only available on macOS.",
+        error_type="mac_system_audio_unavailable",
+        exit_code=2,
+    )
+
+
+def _missing_swiftc() -> CLIError:
+    return CLIError(
+        "macOS system audio capture needs Apple's Swift compiler.",
+        error_type="mac_system_audio_unavailable",
+        exit_code=2,
+        suggestion="Install Xcode Command Line Tools: xcode-select --install",
+    )
+
+
+def _resource_bytes() -> bytes:
+    return resources.files("aai_cli.streaming").joinpath(_HELPER_RESOURCE).read_bytes()
+
+
+def build_helper() -> Path:
+    """Compile the bundled ScreenCaptureKit helper once and return its executable path."""
+    if sys.platform != "darwin":
+        raise _unsupported_platform()
+    swiftc = shutil.which("swiftc")
+    if swiftc is None:
+        raise _missing_swiftc()
+
+    source = _resource_bytes()
+    digest = hashlib.sha256(source).hexdigest()[:16]
+    cache_dir = user_cache_path("aai-cli") / _CACHE_DIR
+    helper = cache_dir / f"{_HELPER_PREFIX}-{digest}"
+    if helper.exists():
+        return helper
+
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    module_cache = cache_dir / "swift-module-cache"
+    module_cache.mkdir(parents=True, exist_ok=True)
+    source_path = cache_dir / f"{_HELPER_PREFIX}-{digest}.swift"
+    source_path.write_bytes(source)
+    tmp_helper = helper.with_suffix(".tmp")
+    result = subprocess.run(
+        [
+            swiftc,
+            "-parse-as-library",
+            "-module-cache-path",
+            str(module_cache),
+            str(source_path),
+            "-O",
+            "-framework",
+            "ScreenCaptureKit",
+            "-framework",
+            "AVFoundation",
+            "-framework",
+            "CoreMedia",
+            "-framework",
+            "CoreGraphics",
+            "-o",
+            str(tmp_helper),
+        ],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if result.returncode != 0:
+        detail = (result.stderr or result.stdout).strip()
+        raise CLIError(
+            "Could not build the macOS system audio helper.",
+            error_type="mac_system_audio_unavailable",
+            exit_code=2,
+            suggestion=detail or "Install Xcode Command Line Tools: xcode-select --install",
+        )
+    tmp_helper.replace(helper)
+    return helper
+
+
+def _read_stderr(stderr: _Pipe | None) -> str:
+    if stderr is None:
+        return ""
+    try:
+        data = stderr.read()
+        return data.decode("utf-8", "replace").strip()
+    finally:
+        with contextlib.suppress(Exception):
+            stderr.close()
+
+
+def _open_process(command: Sequence[str]) -> _CaptureProcess:
+    return subprocess.Popen(
+        command,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+    )
+
+
+def _require_stdout(proc: _CaptureProcess) -> _Pipe:
+    stdout = proc.stdout
+    if stdout is None:
+        raise APIError("macOS system audio helper did not expose an output stream.")
+    return stdout
+
+
+def _cleanup_process(proc: _CaptureProcess, stdout: _Pipe, *, completed: bool) -> None:
+    if not completed and proc.poll() is None:
+        proc.terminate()
+    with contextlib.suppress(Exception):
+        stdout.close()
+    try:
+        proc.wait(timeout=2.0)
+    except subprocess.TimeoutExpired:
+        proc.kill()
+        proc.wait(timeout=2.0)
+    if not completed and proc.stderr is not None:
+        with contextlib.suppress(Exception):
+            proc.stderr.close()
+
+
+def _returncode_detail(returncode: int | None) -> str:
+    if returncode is None:
+        return "unknown exit"
+    if returncode >= 0:
+        return f"exit {returncode}"
+    signum = -returncode
+    try:
+        name = signal.Signals(signum).name
+    except ValueError:
+        name = f"signal {signum}"
+    return f"{name} ({returncode})"
+
+
+def _raise_helper_exit(proc: _CaptureProcess) -> None:
+    detail = _read_stderr(proc.stderr)
+    if proc.returncode:
+        raise CLIError(
+            f"Could not capture macOS system audio: {detail or _returncode_detail(proc.returncode)}",
+            error_type="mac_system_audio_error",
+            suggestion=(
+                "Grant Screen & System Audio Recording and Microphone permissions "
+                "to your terminal, then run the command again."
+            ),
+        )
+    raise CLIError(
+        "macOS system audio capture ended unexpectedly.",
+        error_type="mac_system_audio_error",
+        suggestion=detail or "Run the command again and check macOS privacy permissions.",
+    )
+
+
+class MacSystemAudioSource:
+    """Streams macOS system/app audio as PCM16 mono.
+
+    A tiny bundled Swift helper owns the native macOS ScreenCaptureKit APIs.
+    Python treats the helper's stdout exactly like any other raw PCM stream.
+    """
+
+    def __init__(
+        self,
+        *,
+        on_open: Callable[[], None] | None = None,
+        helper: Path | None = None,
+        popen: Callable[[Sequence[str]], _CaptureProcess] = _open_process,
+    ) -> None:
+        self.source = "macos-system-audio"
+        self.sample_rate = TARGET_RATE
+        self._on_open = on_open
+        self._helper = helper or build_helper()
+        self._popen = popen
+
+    def _command(self) -> list[str]:
+        command = [
+            str(self._helper),
+            "--sample-rate",
+            str(self.sample_rate),
+            "--chunk-frames",
+            str(self.sample_rate // 10),
+        ]
+        command.append("--system-only")
+        return command
+
+    def _start(self) -> _CaptureProcess:
+        try:
+            return self._popen(self._command())
+        except OSError as exc:
+            raise CLIError(
+                f"Could not start macOS system audio capture: {exc}",
+                error_type="mac_system_audio_error",
+            ) from exc
+
+    def __iter__(self) -> Generator[bytes, None, None]:
+        proc = self._start()
+        stdout = _require_stdout(proc)
+        opened = False
+        completed = False
+        try:
+            while True:
+                data = stdout.read(CHUNK_BYTES)
+                if not data:
+                    break
+                if not opened:
+                    opened = True
+                    if self._on_open is not None:
+                        self._on_open()
+                yield bytes(data)
+            completed = True
+        finally:
+            _cleanup_process(proc, stdout, completed=completed)
+
+        _raise_helper_exit(proc)
diff --git a/aai_cli/streaming/macos_system_audio.swift b/aai_cli/streaming/macos_system_audio.swift
new file mode 100644
index 00000000..5e0ee808
--- /dev/null
+++ b/aai_cli/streaming/macos_system_audio.swift
@@ -0,0 +1,347 @@
+import AVFoundation
+import CoreMedia
+import Darwin
+import Foundation
+import ScreenCaptureKit
+
+let debugEnabled = ProcessInfo.processInfo.environment["AAI_MACOS_AUDIO_DEBUG"] == "1"
+
+func debugLog(_ message: String) {
+    if debugEnabled {
+        fputs("[aai-macos-audio] \(message)\n", stderr)
+    }
+}
+
+enum CaptureError: Error, CustomStringConvertible {
+    case noDisplay
+    case screenAudioPermissionDenied
+    case conversionFailed(String)
+
+    var description: String {
+        switch self {
+        case .noDisplay:
+            return "No display is available for ScreenCaptureKit audio capture."
+        case .screenAudioPermissionDenied:
+            return "Screen & System Audio Recording permission is required for system audio capture."
+        case .conversionFailed(let message):
+            return message
+        }
+    }
+}
+
+struct Options {
+    var sampleRate = 16_000
+    var chunkFrames = 1_600
+
+    static func parse() throws -> Options {
+        var options = Options()
+        var args = Array(CommandLine.arguments.dropFirst())
+        while let arg = args.first {
+            args.removeFirst()
+            switch arg {
+            case "--sample-rate":
+                guard let value = args.first, let rate = Int(value), rate > 0 else {
+                    throw CaptureError.conversionFailed("--sample-rate expects a positive integer.")
+                }
+                args.removeFirst()
+                options.sampleRate = rate
+            case "--chunk-frames":
+                guard let value = args.first, let frames = Int(value), frames > 0 else {
+                    throw CaptureError.conversionFailed("--chunk-frames expects a positive integer.")
+                }
+                args.removeFirst()
+                options.chunkFrames = frames
+            case "--system-only":
+                continue
+            default:
+                throw CaptureError.conversionFailed("Unknown argument: \(arg)")
+            }
+        }
+        return options
+    }
+}
+
+final class SampleRing {
+    private var samples: [Float] = []
+    private let lock = NSLock()
+    private let maxSamples: Int
+
+    init(sampleRate: Int, maxSeconds: Double = 5.0) {
+        self.maxSamples = max(1, Int(Double(sampleRate) * maxSeconds))
+    }
+
+    func append(_ newSamples: [Float]) {
+        guard !newSamples.isEmpty else { return }
+        lock.lock()
+        samples.append(contentsOf: newSamples)
+        if samples.count > maxSamples {
+            samples.removeFirst(samples.count - maxSamples)
+        }
+        lock.unlock()
+    }
+
+    func take(_ count: Int) -> [Float] {
+        lock.lock()
+        let available = min(count, samples.count)
+        var output = [Float](repeating: 0, count: count)
+        if available > 0 {
+            output.replaceSubrange(0..<available, with: samples.prefix(available))
+            samples.removeFirst(available)
+        }
+        lock.unlock()
+        return output
+    }
+}
+
+final class PCMConverter {
+    private let outputFormat: AVAudioFormat
+
+    init(sampleRate: Int) throws {
+        guard let outputFormat = AVAudioFormat(
+            commonFormat: .pcmFormatFloat32,
+            sampleRate: Double(sampleRate),
+            channels: 1,
+            interleaved: false
+        ) else {
+            throw CaptureError.conversionFailed(
+                "Could not create a \(sampleRate) Hz mono float audio format."
+            )
+        }
+        self.outputFormat = outputFormat
+    }
+
+    func convert(_ input: AVAudioPCMBuffer) throws -> [Float] {
+        if input.frameLength == 0 {
+            return []
+        }
+        guard let converter = AVAudioConverter(from: input.format, to: outputFormat) else {
+            throw CaptureError.conversionFailed("Could not create an audio converter.")
+        }
+        let ratio = outputFormat.sampleRate / input.format.sampleRate
+        let capacity = AVAudioFrameCount((Double(input.frameLength) * ratio).rounded(.up)) + 512
+        guard let output = AVAudioPCMBuffer(pcmFormat: outputFormat, frameCapacity: capacity) else {
+            throw CaptureError.conversionFailed("Could not allocate a converted audio buffer.")
+        }
+        var suppliedInput = false
+        var error: NSError?
+        let status = converter.convert(to: output, error: &error) { _, outStatus in
+            if suppliedInput {
+                outStatus.pointee = .noDataNow
+                return nil
+            }
+            suppliedInput = true
+            outStatus.pointee = .haveData
+            return input
+        }
+        if status == .error {
+            throw error ?? CaptureError.conversionFailed("Audio conversion failed.")
+        }
+        guard let channel = output.floatChannelData?[0] else {
+            return []
+        }
+        return Array(UnsafeBufferPointer(start: channel, count: Int(output.frameLength)))
+    }
+}
+
+func audioFormat(for sampleBuffer: CMSampleBuffer) -> AVAudioFormat? {
+    guard
+        let formatDescription = CMSampleBufferGetFormatDescription(sampleBuffer),
+        let streamDescription = CMAudioFormatDescriptionGetStreamBasicDescription(formatDescription)
+    else {
+        return nil
+    }
+    return AVAudioFormat(streamDescription: streamDescription)
+}
+
+func peak(_ samples: [Float]) -> Float {
+    var result: Float = 0
+    for sample in samples {
+        result = max(result, abs(sample))
+    }
+    return result
+}
+
+final class Mixer {
+    private let systemRing: SampleRing
+    private let sampleRate: Int
+    private let chunkFrames: Int
+    private let queue = DispatchQueue(label: "aai.macos-audio.mixer", qos: .userInteractive)
+    private var timer: DispatchSourceTimer?
+    private var wroteFirstChunk = false
+
+    init(sampleRate: Int, chunkFrames: Int) {
+        self.systemRing = SampleRing(sampleRate: sampleRate)
+        self.sampleRate = sampleRate
+        self.chunkFrames = chunkFrames
+    }
+
+    func appendSystem(_ samples: [Float]) {
+        systemRing.append(samples)
+    }
+
+    func start() {
+        let timer = DispatchSource.makeTimerSource(queue: queue)
+        let intervalNanoseconds = UInt64(Double(chunkFrames) / Double(sampleRate) * 1_000_000_000)
+        timer.schedule(deadline: .now(), repeating: .nanoseconds(Int(intervalNanoseconds)))
+        timer.setEventHandler { [weak self] in
+            self?.writeChunk()
+        }
+        self.timer = timer
+        timer.resume()
+    }
+
+    private func writeChunk() {
+        let system = systemRing.take(chunkFrames)
+        var data = Data(capacity: chunkFrames * 2)
+        for index in 0..<chunkFrames {
+            let clamped = max(-1.0, min(1.0, system[index]))
+            let sample = Int16(max(Double(Int16.min), min(Double(Int16.max), Double(clamped) * 32767.0)))
+            var littleEndian = sample.littleEndian
+            withUnsafeBytes(of: &littleEndian) { bytes in
+                data.append(contentsOf: bytes)
+            }
+        }
+        if !wroteFirstChunk {
+            debugLog("writing first PCM chunk")
+            wroteFirstChunk = true
+        }
+        writeStdout(data)
+    }
+
+    private func writeStdout(_ data: Data) {
+        data.withUnsafeBytes { rawBuffer in
+            guard let baseAddress = rawBuffer.baseAddress else { return }
+            var offset = 0
+            while offset < rawBuffer.count {
+                let written = Darwin.write(
+                    STDOUT_FILENO,
+                    baseAddress.advanced(by: offset),
+                    rawBuffer.count - offset
+                )
+                if written <= 0 {
+                    exit(0)
+                }
+                offset += written
+            }
+        }
+    }
+}
+
+final class SystemAudioCapture: NSObject, SCStreamOutput, SCStreamDelegate {
+    private let mixer: Mixer
+    private let converter: PCMConverter
+    private let queue = DispatchQueue(label: "aai.macos-audio.system", qos: .userInteractive)
+    private var stream: SCStream?
+    private var sawSystemAudio = false
+    private var loggedSystemLevel = false
+
+    init(mixer: Mixer, sampleRate: Int) throws {
+        self.mixer = mixer
+        self.converter = try PCMConverter(sampleRate: sampleRate)
+    }
+
+    func start(sampleRate: Int) async throws {
+        debugLog("loading shareable content")
+        let content = try await SCShareableContent.excludingDesktopWindows(
+            false,
+            onScreenWindowsOnly: true
+        )
+        debugLog("shareable content loaded: displays=\(content.displays.count)")
+        guard let display = content.displays.first else {
+            throw CaptureError.noDisplay
+        }
+        let filter = SCContentFilter(display: display, excludingWindows: [])
+        let configuration = SCStreamConfiguration()
+        configuration.width = 2
+        configuration.height = 2
+        configuration.minimumFrameInterval = CMTime(value: 1, timescale: 1)
+        configuration.queueDepth = 3
+        configuration.showsCursor = false
+        configuration.capturesAudio = true
+        configuration.excludesCurrentProcessAudio = true
+        configuration.sampleRate = sampleRate
+        configuration.channelCount = 1
+
+        let stream = SCStream(filter: filter, configuration: configuration, delegate: self)
+        debugLog("adding audio output")
+        try stream.addStreamOutput(self, type: .audio, sampleHandlerQueue: queue)
+        debugLog("starting ScreenCaptureKit capture")
+        try await stream.startCapture()
+        debugLog("ScreenCaptureKit capture started")
+        self.stream = stream
+    }
+
+    func stream(
+        _ stream: SCStream,
+        didOutputSampleBuffer sampleBuffer: CMSampleBuffer,
+        of outputType: SCStreamOutputType
+    ) {
+        guard outputType == .audio, sampleBuffer.isValid else {
+            return
+        }
+        handleSystem(sampleBuffer)
+    }
+
+    private func handleSystem(_ sampleBuffer: CMSampleBuffer) {
+        if !sawSystemAudio {
+            debugLog("received first system audio sample")
+            sawSystemAudio = true
+        }
+        do {
+            try sampleBuffer.withAudioBufferList { audioBufferList, _ in
+                guard
+                    let format = audioFormat(for: sampleBuffer),
+                    let pcmBuffer = AVAudioPCMBuffer(
+                        pcmFormat: format,
+                        bufferListNoCopy: audioBufferList.unsafePointer
+                    )
+                else {
+                    return
+                }
+                let samples = try converter.convert(pcmBuffer)
+                if !loggedSystemLevel {
+                    debugLog("system peak=\(peak(samples)) samples=\(samples.count)")
+                    loggedSystemLevel = true
+                }
+                mixer.appendSystem(samples)
+            }
+        } catch {
+            fputs("System audio conversion failed: \(error)\n", stderr)
+        }
+    }
+
+    func stream(_ stream: SCStream, didStopWithError error: Error) {
+        fputs("ScreenCaptureKit stopped: \(error)\n", stderr)
+        exit(1)
+    }
+}
+
+@main
+struct Main {
+    static func main() async {
+        do {
+            debugLog("helper starting")
+            let options = try Options.parse()
+            debugLog(
+                "parsed options: sampleRate=\(options.sampleRate) "
+                    + "chunkFrames=\(options.chunkFrames)"
+            )
+            let mixer = Mixer(
+                sampleRate: options.sampleRate,
+                chunkFrames: options.chunkFrames
+            )
+            let system = try SystemAudioCapture(mixer: mixer, sampleRate: options.sampleRate)
+
+            try await system.start(sampleRate: options.sampleRate)
+            debugLog("starting mixer")
+            mixer.start()
+            while true {
+                _ = system
+                try await Task.sleep(nanoseconds: 1_000_000_000)
+            }
+        } catch {
+            fputs("\(error)\n", stderr)
+            exit(1)
+        }
+    }
+}
diff --git a/aai_cli/streaming/render.py b/aai_cli/streaming/render.py
index 660493d3..420c9f99 100644
--- a/aai_cli/streaming/render.py
+++ b/aai_cli/streaming/render.py
@@ -1,5 +1,9 @@
 from __future__ import annotations
 
+import threading
+from typing import TextIO
+
+from rich.console import Console
 from rich.text import Text
 
 from aai_cli.render import BaseRenderer
@@ -17,43 +21,113 @@ class StreamRenderer(BaseRenderer):
     Construction and the json/text/human plumbing live in BaseRenderer.
     """
 
-    def begin(self, event: object) -> None:
+    def __init__(
+        self,
+        *,
+        json_mode: bool,
+        out: TextIO | None = None,
+        console: Console | None = None,
+        text_mode: bool = False,
+        err: TextIO | None = None,
+    ) -> None:
+        super().__init__(
+            json_mode=json_mode,
+            out=out,
+            console=console,
+            text_mode=text_mode,
+            err=err,
+        )
+        self._lock = threading.RLock()
+
+    @staticmethod
+    def _with_source(payload: dict[str, object], source: str | None) -> dict[str, object]:
+        if source is not None:
+            payload["source"] = source
+        return payload
+
+    @staticmethod
+    def _source_label(source: str) -> tuple[str, str]:
+        labels = {
+            "system": ("System", "aai.agent"),
+            "you": ("You", "aai.you"),
+        }
+        return labels.get(source, (source, "aai.label"))
+
+    @classmethod
+    def _label(cls, text: str, source: str | None) -> str:
+        if source is None:
+            return text
+        label, _style = cls._source_label(source)
+        return f"{label}: {text}"
+
+    @classmethod
+    def _styled_label(cls, text: str, source: str | None) -> str | Text:
+        if source is None:
+            return text
+        label, style = cls._source_label(source)
+        rendered = Text()
+        rendered.append(f"{label}: ", style=style)
+        rendered.append(text)
+        return rendered
+
+    def begin(self, event: object, *, source: str | None = None) -> None:
         # The "Listening…" notice waits for the mic (see listening()); opening the
         # session only emits the protocol event for JSON consumers.
-        if self.json_mode:
-            self._emit({"type": "begin", "id": getattr(event, "id", None)})
+        with self._lock:
+            if self.json_mode:
+                self._emit(
+                    self._with_source({"type": "begin", "id": getattr(event, "id", None)}, source)
+                )
 
     def listening(self) -> None:
         """Announce capture has started — called once the mic is open and recording."""
-        if self.text_mode:
-            self._status("Listening… (Ctrl-C to stop)")
-        elif not self.json_mode:
-            self._line(Text("Listening… (Ctrl-C to stop)", style="aai.muted"))
+        with self._lock:
+            if self.text_mode:
+                self._status("Listening… (Ctrl-C to stop)")
+            elif not self.json_mode:
+                self._line(Text("Listening… (Ctrl-C to stop)", style="aai.muted"))
 
-    def turn(self, event: object) -> None:
+    def turn(self, event: object, *, source: str | None = None) -> None:
         text = getattr(event, "transcript", "") or ""
         end = bool(getattr(event, "end_of_turn", False))
-        if self.json_mode:
-            self._emit({"type": "turn", "transcript": text, "end_of_turn": end})
-        elif self.text_mode:
-            if end and text:
-                self._write(text + "\n")  # plain finalized line, pipe-friendly
-        elif end:
-            self._finalize_line(text)
-        else:
-            self._update_line(text)
-
-    def termination(self, event: object) -> None:
-        if self.json_mode:
-            self._emit(
-                {
-                    "type": "termination",
-                    "audio_duration_seconds": getattr(event, "audio_duration_seconds", None),
-                }
-            )
+        with self._lock:
+            if self.json_mode:
+                self._emit(
+                    self._with_source(
+                        {"type": "turn", "transcript": text, "end_of_turn": end},
+                        source,
+                    )
+                )
+            elif self.text_mode:
+                if end and text:
+                    self._write(self._label(text, source) + "\n")  # plain finalized line
+            elif end:
+                self._finalize_line(self._styled_label(text, source))
+            else:
+                self._update_line(self._styled_label(text, source))
+
+    def termination(self, event: object, *, source: str | None = None) -> None:
+        with self._lock:
+            if self.json_mode:
+                self._emit(
+                    self._with_source(
+                        {
+                            "type": "termination",
+                            "audio_duration_seconds": getattr(
+                                event, "audio_duration_seconds", None
+                            ),
+                        },
+                        source,
+                    )
+                )
 
     def stopped(self) -> None:
-        if self.text_mode:
-            self._status("Stopped.")
-        else:
-            super().stopped()
+        with self._lock:
+            if self.text_mode:
+                self._status("Stopped.")
+            else:
+                super().stopped()
+
+    def close(self) -> None:
+        with self._lock:
+            super().close()
diff --git a/pyproject.toml b/pyproject.toml
index 84b401d7..a6fde983 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -94,7 +94,7 @@ 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/**"]
+artifacts = ["aai_cli/init/templates/**", "aai_cli/streaming/macos_system_audio.swift"]
 exclude = ["**/__pycache__", "**/*.pyc"]
 
 [tool.pytest.ini_options]
diff --git a/scripts/check.sh b/scripts/check.sh
index d5abd825..78271a75 100755
--- a/scripts/check.sh
+++ b/scripts/check.sh
@@ -61,6 +61,39 @@ echo "==> xenon (cyclomatic complexity gate, src only)"
 # Tests are excluded (not shipped); only the aai_cli package is gated.
 uv run xenon --max-absolute B --max-modules B --max-average A aai_cli
 
+echo "==> swiftlint (macOS audio helper)"
+if command -v swiftlint >/dev/null 2>&1; then
+  swiftlint lint --no-cache --strict aai_cli/streaming/macos_system_audio.swift
+else
+  echo "   swiftlint not found; skipping (install with: brew install swiftlint)"
+fi
+
+echo "==> swift compile (macOS audio helper)"
+if command -v swiftc >/dev/null 2>&1; then
+  swift_module_cache="$(mktemp -d)"
+  swift_helper="$swift_module_cache/aai-macos-audio-check"
+  swift_error="$swift_module_cache/aai-macos-audio-check.err"
+  swiftc -parse-as-library aai_cli/streaming/macos_system_audio.swift \
+    -module-cache-path "$swift_module_cache" \
+    -O \
+    -framework ScreenCaptureKit \
+    -framework AVFoundation \
+    -framework CoreMedia \
+    -framework CoreGraphics \
+    -o "$swift_helper"
+  if "$swift_helper" --unknown-check-flag 2>"$swift_error"; then
+    echo "   expected Swift helper argument validation to fail"
+    exit 1
+  fi
+  if ! grep -q "Unknown argument: --unknown-check-flag" "$swift_error"; then
+    cat "$swift_error"
+    exit 1
+  fi
+  rm -rf "$swift_module_cache"
+else
+  echo "   swiftc not found; skipping (macOS system audio builds on first use)"
+fi
+
 echo "==> markdownlint (docs/ is generated, so excluded)"
 markdownlint "**/*.md" --ignore docs --ignore node_modules --ignore .pytest_cache
 
diff --git a/scripts/template_contract_gate.py b/scripts/template_contract_gate.py
index 116efd31..0a709e23 100644
--- a/scripts/template_contract_gate.py
+++ b/scripts/template_contract_gate.py
@@ -52,7 +52,7 @@ def _required_files(template: str, path: Path) -> None:
     for rel in _REQUIRED_FILES:
         if not (path / rel).exists():
             _fail(f"{template}: missing {rel}")
-    if template in {"stream", "agent"} and not (path / "static/audio.js").exists():
+    if template in {"live-captions", "voice-agent"} and not (path / "static/audio.js").exists():
         _fail(f"{template}: missing static/audio.js")
 
 
diff --git a/tests/__snapshots__/test_cli_output_snapshots.ambr b/tests/__snapshots__/test_cli_output_snapshots.ambr
index 79b30d28..5a49985a 100644
--- a/tests/__snapshots__/test_cli_output_snapshots.ambr
+++ b/tests/__snapshots__/test_cli_output_snapshots.ambr
@@ -203,7 +203,7 @@
   ╭─ Arguments ──────────────────────────────────────────────────────────────────╮
   │   template       [TEMPLATE]   Template to scaffold (omit to pick             │
   │                               interactively).                                │
-  │   directory      [DIRECTORY]  Target directory (default: <template>-app).    │
+  │   directory      [DIRECTORY]  Target directory (default: <template>).        │
   ╰──────────────────────────────────────────────────────────────────────────────╯
   ╭─ Options ────────────────────────────────────────────────────────────────────╮
   │ --no-install                 Scaffold only; don't install or launch.         │
@@ -218,10 +218,10 @@
    Examples
    Scaffold a new app interactively
    $ aai init
-   Scaffold a transcribe app into ./my-app
-   $ aai init transcribe my-app
+   Scaffold an audio transcription app into ./my-app
+   $ aai init audio-transcription my-app
    Scaffold into the current directory
-   $ aai init transcribe --here
+   $ aai init audio-transcription --here
   
   
   
@@ -527,6 +527,14 @@
   │                                                         native).             │
   │ --device                                       INTEGER  Microphone device    │
   │                                                         index.               │
+  │ --system-audio                                          macOS only: stream   │
+  │                                                         system/app audio and │
+  │                                                         microphone as        │
+  │                                                         separate sessions.   │
+  │ --system-audio-only                                     macOS only: stream   │
+  │                                                         system/app audio     │
+  │                                                         without the          │
+  │                                                         microphone.          │
   │ --speech-model                                 TEXT     Streaming speech     │
   │                                                         model.               │
   │                                                         [default: u3-rt-pro] │
@@ -608,6 +616,8 @@
    Examples
    Stream from your microphone
    $ aai stream
+   Stream mic + system audio on macOS
+   $ aai stream --system-audio
    Stream the hosted sample
    $ aai stream --sample
    Summarize action items live as you talk
diff --git a/tests/test_init_command.py b/tests/test_init_command.py
index 944ae0cd..a33b6cf7 100644
--- a/tests/test_init_command.py
+++ b/tests/test_init_command.py
@@ -3,11 +3,12 @@
 from aai_cli.main import app
 
 runner = CliRunner()
+TEMPLATE = "audio-transcription"
 
 
 def test_init_scaffold_only_creates_project(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
-    result = runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    result = runner.invoke(app, ["init", TEMPLATE, "myapp", "--no-install"])
     assert result.exit_code == 0, result.output
     assert (tmp_path / "myapp" / "api" / "index.py").exists()
     assert (tmp_path / "myapp" / ".env").exists()
@@ -16,7 +17,7 @@ def test_init_scaffold_only_creates_project(tmp_path, monkeypatch):
 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"])
+    runner.invoke(app, ["init", TEMPLATE, "myapp", "--no-install"])
     assert "ASSEMBLYAI_API_KEY=sk-from-env" in (tmp_path / "myapp" / ".env").read_text()
 
 
@@ -35,7 +36,7 @@ def test_init_logged_out_installs_but_skips_launch_with_hint(tmp_path, monkeypat
         "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
+    result = runner.invoke(app, ["init", TEMPLATE, "app"])  # no --no-install, logged out
     assert result.exit_code == 0, result.output
     assert launched["v"] is False
     assert "aai login" in result.output
@@ -44,7 +45,7 @@ def test_init_logged_out_installs_but_skips_launch_with_hint(tmp_path, monkeypat
 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)
-    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    runner.invoke(app, ["init", TEMPLATE, "myapp", "--no-install"])
     env = (tmp_path / "myapp" / ".env").read_text()
     assert "ASSEMBLYAI_BASE_URL=https://" in env
     assert "ASSEMBLYAI_LLM_GATEWAY_URL=https://" in env
@@ -52,7 +53,7 @@ def test_init_writes_base_url_for_active_env(tmp_path, monkeypatch):
 
 def test_init_placeholder_key_when_logged_out(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
-    runner.invoke(app, ["init", "transcribe", "myapp", "--no-install"])
+    runner.invoke(app, ["init", TEMPLATE, "myapp", "--no-install"])
     env = (tmp_path / "myapp" / ".env").read_text()
     assert "your_assemblyai_api_key_here" in env
 
@@ -65,15 +66,15 @@ def test_init_unknown_template_errors(tmp_path, monkeypatch):
 
 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 runner.invoke(app, ["init", TEMPLATE, "myapp", "--no-install"]).exit_code == 0
+    result = runner.invoke(app, ["init", TEMPLATE, "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 runner.invoke(app, ["init", TEMPLATE, "myapp", "--no-install"]).exit_code == 0
+    result = runner.invoke(app, ["init", TEMPLATE, "myapp", "--no-install", "--force"])
     assert result.exit_code == 0
 
 
@@ -82,14 +83,14 @@ def test_init_no_template_non_interactive_errors(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
     result = runner.invoke(app, ["init"])
     assert result.exit_code != 0
-    assert "transcribe" in result.output  # lists the available templates
+    assert TEMPLATE in result.output  # lists the available templates
 
 
-def test_init_default_dir_is_template_app(tmp_path, monkeypatch):
+def test_init_default_dir_is_template_slug(tmp_path, monkeypatch):
     monkeypatch.chdir(tmp_path)
-    result = runner.invoke(app, ["init", "transcribe", "--no-install"])
+    result = runner.invoke(app, ["init", TEMPLATE, "--no-install"])
     assert result.exit_code == 0, result.output
-    assert (tmp_path / "transcribe-app" / "api" / "index.py").exists()
+    assert (tmp_path / TEMPLATE / "api" / "index.py").exists()
 
 
 def test_init_appears_in_help():
@@ -101,7 +102,7 @@ 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"])
+    result = runner.invoke(app, ["init", TEMPLATE, "x", "--no-install"])
     assert result.exit_code == 0, result.output
     assert "AssemblyAI CLI" in result.output
 
@@ -110,7 +111,7 @@ 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"])
+    result = runner.invoke(app, ["init", TEMPLATE, "--here", "--no-install"])
     assert result.exit_code == 0, result.output
     assert (work / "api" / "index.py").exists()  # scaffolded into cwd, no subdir
 
@@ -119,7 +120,7 @@ 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"])
+    result = runner.invoke(app, ["init", TEMPLATE, "mydir", "--here", "--no-install"])
     assert result.exit_code != 0  # ambiguous: directory AND --here both given
 
 
@@ -127,15 +128,15 @@ 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"])
+    result = runner.invoke(app, ["init", TEMPLATE, "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_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.
+    # `llm` isn't a separate template (it's folded into audio-transcription), so
+    # picking it must give a clean error, not a FileNotFoundError.
     monkeypatch.chdir(tmp_path)
     result = runner.invoke(app, ["init", "llm", "x", "--no-install"])
     assert result.exit_code == 1
diff --git a/tests/test_init_scaffold.py b/tests/test_init_scaffold.py
index f60f6a7c..abf9cdec 100644
--- a/tests/test_init_scaffold.py
+++ b/tests/test_init_scaffold.py
@@ -6,7 +6,7 @@
 
 def test_scaffold_copies_files_and_renames_dotfiles(tmp_path):
     target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
+    scaffold.scaffold("audio-transcription", target, api_key="sk-real-key")
     assert (target / "api" / "index.py").exists()
     assert (target / "index.html").exists()
     assert (target / "vercel.json").exists()
@@ -20,7 +20,7 @@ def test_scaffold_copies_files_and_renames_dotfiles(tmp_path):
 
 def test_scaffold_writes_env_with_key(tmp_path):
     target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key="sk-real-key")
+    scaffold.scaffold("audio-transcription", target, api_key="sk-real-key")
     env = (target / ".env").read_text()
     assert "ASSEMBLYAI_API_KEY=sk-real-key" in env
 
@@ -28,7 +28,7 @@ def test_scaffold_writes_env_with_key(tmp_path):
 def test_scaffold_writes_env_vars(tmp_path):
     target = tmp_path / "app"
     scaffold.scaffold(
-        "transcribe",
+        "audio-transcription",
         target,
         api_key="k",
         env_vars={
@@ -43,7 +43,7 @@ def test_scaffold_writes_env_vars(tmp_path):
 
 def test_scaffold_omits_env_vars_when_none(tmp_path):
     target = tmp_path / "app"
-    scaffold.scaffold("transcribe", target, api_key="k")
+    scaffold.scaffold("audio-transcription", target, api_key="k")
     env = (target / ".env").read_text()
     assert "ASSEMBLYAI_BASE_URL" not in env
     assert "ASSEMBLYAI_LLM_GATEWAY_URL" not in env
@@ -53,14 +53,14 @@ 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)
+    scaffold.scaffold("audio-transcription", 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)
+    scaffold.scaffold("audio-transcription", target, api_key=None)
     env = (target / ".env").read_text()
     assert scaffold.PLACEHOLDER_KEY in env
 
diff --git a/tests/test_init_template_agent.py b/tests/test_init_template_agent.py
index e443119a..5b26dbec 100644
--- a/tests/test_init_template_agent.py
+++ b/tests/test_init_template_agent.py
@@ -5,7 +5,7 @@
 
 from fastapi.testclient import TestClient
 
-TEMPLATE_DIR = Path("aai_cli/init/templates/agent")
+TEMPLATE_DIR = Path("aai_cli/init/templates/voice-agent")
 
 
 def _load_app(monkeypatch):
diff --git a/tests/test_init_template_contract.py b/tests/test_init_template_contract.py
index bc9f1a8e..c0b4743a 100644
--- a/tests/test_init_template_contract.py
+++ b/tests/test_init_template_contract.py
@@ -38,7 +38,7 @@ def test_required_files_present(template_dir):
 
 
 def test_realtime_templates_have_audio_helpers(template_dir):
-    if template_dir.name in {"stream", "agent"}:
+    if template_dir.name in {"live-captions", "voice-agent"}:
         assert (template_dir / "static" / "audio.js").exists()
 
 
diff --git a/tests/test_init_template_stream.py b/tests/test_init_template_stream.py
index a617e0f6..e7900e64 100644
--- a/tests/test_init_template_stream.py
+++ b/tests/test_init_template_stream.py
@@ -5,7 +5,7 @@
 
 from fastapi.testclient import TestClient
 
-TEMPLATE_DIR = Path("aai_cli/init/templates/stream")
+TEMPLATE_DIR = Path("aai_cli/init/templates/live-captions")
 
 
 def _load_app(monkeypatch):
diff --git a/tests/test_init_template_transcribe.py b/tests/test_init_template_transcribe.py
index 4d22b155..512a86c3 100644
--- a/tests/test_init_template_transcribe.py
+++ b/tests/test_init_template_transcribe.py
@@ -5,7 +5,7 @@
 
 from fastapi.testclient import TestClient
 
-TEMPLATE_DIR = Path("aai_cli/init/templates/transcribe")
+TEMPLATE_DIR = Path("aai_cli/init/templates/audio-transcription")
 
 
 def _load_app(monkeypatch):
diff --git a/tests/test_init_templates.py b/tests/test_init_templates.py
index 9f8670c5..f4cc94d2 100644
--- a/tests/test_init_templates.py
+++ b/tests/test_init_templates.py
@@ -5,9 +5,9 @@
 _TEMPLATES_ROOT = Path("aai_cli/init/templates")
 
 
-def test_transcribe_is_registered():
-    assert "transcribe" in templates.TEMPLATES
-    assert "transcribe" in templates.TEMPLATE_ORDER
+def test_audio_transcription_is_registered():
+    assert "audio-transcription" in templates.TEMPLATES
+    assert "audio-transcription" in templates.TEMPLATE_ORDER
 
 
 def test_order_matches_registry():
@@ -37,10 +37,10 @@ def test_every_shipped_directory_is_registered():
 
 
 def test_title_for_known_and_unknown():
-    assert "Transcribe" in templates.title_for("transcribe")
+    assert "Audio Transcription" in templates.title_for("audio-transcription")
     assert templates.title_for("nope") == "nope"  # falls back to the raw id
 
 
 def test_is_template():
-    assert templates.is_template("transcribe") is True
+    assert templates.is_template("audio-transcription") is True
     assert templates.is_template("nope") is False
diff --git a/tests/test_macos_audio_source.py b/tests/test_macos_audio_source.py
new file mode 100644
index 00000000..463915b7
--- /dev/null
+++ b/tests/test_macos_audio_source.py
@@ -0,0 +1,245 @@
+import io
+import types
+from pathlib import Path
+
+import pytest
+
+from aai_cli.errors import APIError, CLIError
+from aai_cli.streaming import macos
+from aai_cli.streaming.sources import CHUNK_BYTES
+
+
+class _FakeProc:
+    def __init__(
+        self,
+        *,
+        stdout: bytes | None = b"",
+        stderr: bytes | None = b"",
+        returncode: int | None = None,
+    ):
+        self.stdout = io.BytesIO(stdout) if stdout is not None else None
+        self.stderr = io.BytesIO(stderr) if stderr is not None else None
+        self.returncode = returncode
+        self.terminated = False
+        self.killed = False
+        self.waited = False
+
+    def poll(self):
+        return self.returncode
+
+    def terminate(self):
+        self.terminated = True
+        self.returncode = -15
+
+    def kill(self):
+        self.killed = True
+        self.returncode = -9
+
+    def wait(self, timeout=None):
+        self.waited = True
+        return self.returncode
+
+
+def test_build_helper_rejects_non_macos(monkeypatch):
+    monkeypatch.setattr(macos.sys, "platform", "linux")
+    with pytest.raises(CLIError) as exc:
+        macos.build_helper()
+    assert exc.value.error_type == "mac_system_audio_unavailable"
+    assert exc.value.exit_code == 2
+
+
+def test_build_helper_requires_swiftc(monkeypatch):
+    monkeypatch.setattr(macos.sys, "platform", "darwin")
+    monkeypatch.setattr(macos.shutil, "which", lambda _tool: None)
+    with pytest.raises(CLIError) as exc:
+        macos.build_helper()
+    assert "xcode-select" in (exc.value.suggestion or "")
+
+
+def test_build_helper_compiles_to_cache(monkeypatch, tmp_path):
+    monkeypatch.setattr(macos.sys, "platform", "darwin")
+    monkeypatch.setattr(macos.shutil, "which", lambda _tool: "/usr/bin/swiftc")
+    monkeypatch.setattr(macos, "_resource_bytes", lambda: b"swift source")
+    monkeypatch.setattr(macos, "user_cache_path", lambda _app: tmp_path)
+    seen = {}
+
+    def fake_run(cmd, **kwargs):
+        seen["cmd"] = cmd
+        Path(cmd[-1]).write_bytes(b"binary")
+        return types.SimpleNamespace(returncode=0, stderr="", stdout="")
+
+    monkeypatch.setattr(macos.subprocess, "run", fake_run)
+    helper = macos.build_helper()
+    assert helper.read_bytes() == b"binary"
+    assert "-parse-as-library" in seen["cmd"]
+    assert "ScreenCaptureKit" in seen["cmd"]
+
+
+def test_build_helper_reuses_cached_binary(monkeypatch, tmp_path):
+    source = b"swift source"
+    digest = macos.hashlib.sha256(source).hexdigest()[:16]
+    helper = tmp_path / "macos-system-audio" / f"aai-macos-audio-{digest}"
+    helper.parent.mkdir(parents=True)
+    helper.write_bytes(b"cached")
+    monkeypatch.setattr(macos.sys, "platform", "darwin")
+    monkeypatch.setattr(macos.shutil, "which", lambda _tool: "/usr/bin/swiftc")
+    monkeypatch.setattr(macos, "_resource_bytes", lambda: source)
+    monkeypatch.setattr(macos, "user_cache_path", lambda _app: tmp_path)
+    monkeypatch.setattr(
+        macos.subprocess,
+        "run",
+        lambda *a, **k: (_ for _ in ()).throw(AssertionError("must not compile")),
+    )
+    assert macos.build_helper() == helper
+
+
+def test_build_helper_compile_failure_surfaces_stderr(monkeypatch, tmp_path):
+    monkeypatch.setattr(macos.sys, "platform", "darwin")
+    monkeypatch.setattr(macos.shutil, "which", lambda _tool: "/usr/bin/swiftc")
+    monkeypatch.setattr(macos, "_resource_bytes", lambda: b"swift source")
+    monkeypatch.setattr(macos, "user_cache_path", lambda _app: tmp_path)
+    monkeypatch.setattr(
+        macos.subprocess,
+        "run",
+        lambda *a, **k: types.SimpleNamespace(returncode=1, stderr="compile broke", stdout=""),
+    )
+    with pytest.raises(CLIError) as exc:
+        macos.build_helper()
+    assert exc.value.error_type == "mac_system_audio_unavailable"
+    assert exc.value.suggestion == "compile broke"
+
+
+def test_resource_bytes_reads_bundled_swift_source():
+    assert b"ScreenCaptureKit" in macos._resource_bytes()
+
+
+def test_read_stderr_none_is_empty():
+    assert macos._read_stderr(None) == ""
+
+
+def test_open_process_exposes_stdout():
+    proc = macos._open_process(["/bin/echo", "ok"])
+    assert proc.stdout is not None
+    try:
+        assert proc.stdout.read().strip() == b"ok"
+        proc.wait(timeout=2.0)
+    finally:
+        proc.stdout.close()
+        if proc.stderr is not None:
+            proc.stderr.close()
+
+
+def test_require_stdout_rejects_missing_pipe():
+    proc = _FakeProc(stdout=None)
+    with pytest.raises(APIError):
+        macos._require_stdout(proc)
+
+
+def test_cleanup_process_kills_after_wait_timeout():
+    class TimeoutProc(_FakeProc):
+        def __init__(self):
+            super().__init__(stdout=b"")
+            self.waits = 0
+
+        def wait(self, timeout=None):
+            self.waits += 1
+            if self.waits == 1:
+                raise macos.subprocess.TimeoutExpired("helper", timeout or 0.0)
+            return self.returncode
+
+    proc = TimeoutProc()
+    assert proc.stdout is not None
+    macos._cleanup_process(proc, proc.stdout, completed=True)
+    assert proc.killed is True
+    assert proc.waits == 2
+
+
+def test_raise_helper_exit_handles_clean_eof():
+    proc = _FakeProc(stdout=b"", stderr=b"permission hint", returncode=0)
+    with pytest.raises(CLIError) as exc:
+        macos._raise_helper_exit(proc)
+    assert "ended unexpectedly" in exc.value.message
+    assert exc.value.suggestion == "permission hint"
+
+
+def test_returncode_detail_names_signals():
+    assert macos._returncode_detail(-5) == "SIGTRAP (-5)"
+    assert macos._returncode_detail(2) == "exit 2"
+    assert macos._returncode_detail(None) == "unknown exit"
+
+
+def test_raise_helper_exit_names_signal_without_stderr():
+    proc = _FakeProc(stdout=b"", stderr=b"", returncode=-5)
+    with pytest.raises(CLIError) as exc:
+        macos._raise_helper_exit(proc)
+    assert "SIGTRAP" in exc.value.message
+
+
+def test_source_starts_helper_and_yields_pcm(tmp_path):
+    helper = tmp_path / "helper"
+    helper.write_text("")
+    events = []
+    procs = []
+    commands = []
+
+    def fake_popen(cmd):
+        commands.append(cmd)
+        proc = _FakeProc(stdout=b"\x01" * CHUNK_BYTES + b"\x02" * CHUNK_BYTES)
+        procs.append(proc)
+        return proc
+
+    src = macos.MacSystemAudioSource(
+        helper=helper,
+        on_open=lambda: events.append("open"),
+        popen=fake_popen,
+    )
+    gen = src.__iter__()
+    assert next(gen) == b"\x01" * CHUNK_BYTES
+    assert next(gen) == b"\x02" * CHUNK_BYTES
+    gen.close()
+    assert events == ["open"]
+    assert "--system-only" in commands[0]
+    assert procs[0].terminated is True
+
+
+def test_source_start_failure_is_cli_error(tmp_path):
+    helper = tmp_path / "helper"
+    helper.write_text("")
+
+    def fail(_cmd):
+        raise OSError("not executable")
+
+    src = macos.MacSystemAudioSource(helper=helper, popen=fail)
+    with pytest.raises(CLIError) as exc:
+        list(src)
+    assert "not executable" in exc.value.message
+
+
+def test_source_system_audio_only_flag(tmp_path):
+    helper = tmp_path / "helper"
+    helper.write_text("")
+    commands = []
+
+    def fake_popen(cmd):
+        commands.append(cmd)
+        return _FakeProc(stdout=b"\x00" * CHUNK_BYTES)
+
+    src = macos.MacSystemAudioSource(helper=helper, popen=fake_popen)
+    gen = src.__iter__()
+    next(gen)
+    gen.close()
+    assert "--system-only" in commands[0]
+
+
+def test_source_surfaces_helper_failure(tmp_path):
+    helper = tmp_path / "helper"
+    helper.write_text("")
+
+    def fake_popen(cmd):
+        return _FakeProc(stdout=b"", stderr=b"permission denied", returncode=1)
+
+    src = macos.MacSystemAudioSource(helper=helper, popen=fake_popen)
+    with pytest.raises(CLIError) as exc:
+        list(src)
+    assert exc.value.error_type == "mac_system_audio_error"
+    assert "permission denied" in exc.value.message
diff --git a/tests/test_stream_command.py b/tests/test_stream_command.py
index 788a7cc0..c6e56d66 100644
--- a/tests/test_stream_command.py
+++ b/tests/test_stream_command.py
@@ -508,6 +508,149 @@ def test_stream_stdin_rejects_device(monkeypatch):
     assert result.exit_code == 2  # --device applies only to the microphone
 
 
+def test_stream_system_audio_uses_macos_source(monkeypatch):
+    config.set_api_key("default", "sk_live")
+    seen = {"source_types": []}
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            seen["system_on_open"] = on_open
+            self.sample_rate = 16000
+
+        def __iter__(self):
+            if seen["system_on_open"]:
+                seen["system_on_open"]()
+            return iter([b"system"])
+
+    class FakeMic:
+        def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
+            seen["mic_target_rate"] = target_rate
+            seen["mic_device"] = device
+            seen["mic_capture_rate"] = capture_rate
+            seen["mic_on_open"] = on_open
+            self.sample_rate = 16000
+
+        def __iter__(self):
+            if seen["mic_on_open"]:
+                seen["mic_on_open"]()
+            return iter([b"mic"])
+
+    def fake_stream_audio(api_key, source, *, params, on_begin=None, on_turn=None, **_kwargs):
+        source_type = type(source).__name__
+        seen["source_types"].append(source_type)
+        seen.setdefault("rates", []).append(params.sample_rate)
+        if on_begin:
+            on_begin(types.SimpleNamespace(id=source_type))
+        list(source)
+        if on_turn:
+            on_turn(types.SimpleNamespace(transcript=source_type, end_of_turn=True))
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", FakeMic)
+    monkeypatch.setattr("aai_cli.commands.stream.client.stream_audio", fake_stream_audio)
+    result = runner.invoke(app, ["stream", "--system-audio", "--json"])
+    assert result.exit_code == 0
+    assert set(seen["source_types"]) == {"FakeSystemAudio", "FakeMic"}
+    assert seen["rates"] == [16000, 16000]
+    assert seen["mic_target_rate"] == 16000
+    lines = [json.loads(x) for x in result.output.splitlines() if x.strip()]
+    assert {
+        "type": "turn",
+        "transcript": "FakeSystemAudio",
+        "end_of_turn": True,
+        "source": "system",
+    } in lines
+    assert {"type": "turn", "transcript": "FakeMic", "end_of_turn": True, "source": "you"} in lines
+
+
+def test_stream_system_audio_only_disables_mic(monkeypatch):
+    config.set_api_key("default", "sk_live")
+    seen = {}
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            self.sample_rate = 16000
+
+        def __iter__(self):
+            return iter([b"\x00\x00"])
+
+    def fail_mic(**_kwargs):
+        raise AssertionError("system-audio-only must not open the microphone")
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", fail_mic)
+    monkeypatch.setattr("aai_cli.commands.stream.client.stream_audio", _capture_source(seen))
+    result = runner.invoke(app, ["stream", "--system-audio-only", "--json"])
+    assert result.exit_code == 0
+    assert type(seen["source"]).__name__ == "FakeSystemAudio"
+
+
+def test_stream_system_audio_rejects_other_sources():
+    config.set_api_key("default", "sk_live")
+    result = runner.invoke(app, ["stream", "--system-audio", "--sample"])
+    assert result.exit_code == 2
+    assert "cannot be combined" in result.output
+
+
+def test_stream_system_audio_forwards_mic_device_flags(monkeypatch):
+    config.set_api_key("default", "sk_live")
+    seen = {}
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            self.sample_rate = 16000
+
+        def __iter__(self):
+            return iter([b"system"])
+
+    class FakeMic:
+        def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
+            seen["target_rate"] = target_rate
+            seen["device"] = device
+            seen["capture_rate"] = capture_rate
+            self.sample_rate = target_rate
+
+        def __iter__(self):
+            return iter([b"mic"])
+
+    def fake_stream_audio(api_key, source, *, params, **_kwargs):
+        list(source)
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", FakeMic)
+    monkeypatch.setattr("aai_cli.commands.stream.client.stream_audio", fake_stream_audio)
+    result = runner.invoke(
+        app,
+        ["stream", "--system-audio", "--device", "2", "--sample-rate", "44100", "--json"],
+    )
+    assert result.exit_code == 0
+    assert seen == {"target_rate": 16000, "device": 2, "capture_rate": 44100}
+
+
+def test_stream_system_audio_only_rejects_mic_device_flags():
+    config.set_api_key("default", "sk_live")
+    result = runner.invoke(app, ["stream", "--system-audio-only", "--device", "2"])
+    assert result.exit_code == 2
+    assert "--device" in result.output
+
+    result = runner.invoke(app, ["stream", "--system-audio-only", "--sample-rate", "44100"])
+    assert result.exit_code == 2
+    assert "--sample-rate" in result.output
+
+
+def test_stream_system_audio_rejects_both_modes():
+    config.set_api_key("default", "sk_live")
+    result = runner.invoke(app, ["stream", "--system-audio", "--system-audio-only"])
+    assert result.exit_code == 2
+    assert "either --system-audio" in result.output
+
+
+def test_stream_show_code_rejects_system_audio():
+    result = runner.invoke(app, ["stream", "--system-audio", "--show-code"])
+    assert result.exit_code == 2
+    assert "--show-code" in result.output
+
+
 def test_stream_output_text_emits_plain_finalized_turns(monkeypatch):
     # `-o text` -> only finalized transcripts as plain stdout lines (pipe into aai llm).
     config.set_api_key("default", "sk_live")
diff --git a/tests/test_streaming_render.py b/tests/test_streaming_render.py
index 4b8ccaa4..8d4439f4 100644
--- a/tests/test_streaming_render.py
+++ b/tests/test_streaming_render.py
@@ -38,6 +38,19 @@ def test_human_turn_shows_and_finalizes_text():
     assert "hello world" in buf.getvalue()
 
 
+def test_human_turn_labels_parallel_sources():
+    r, buf = _human(color_system="truecolor")
+    r.turn(_turn("hello from me", True), source="you")
+    r.turn(_turn("hello from audio", True), source="system")
+    r.close()
+    out = buf.getvalue()
+    assert "You:" in out
+    assert "hello from me" in out
+    assert "System:" in out
+    assert "hello from audio" in out
+    assert "\x1b[" in out
+
+
 def test_human_begin_is_silent_until_mic_opens():
     # The session opening (Begin) no longer prints "Listening…"; that waits for
     # the mic to actually open and start recording (renderer.listening()).
@@ -86,6 +99,21 @@ def test_json_mode_emits_ndjson_events():
     assert lines[1] == {"type": "turn", "transcript": "hi", "end_of_turn": True}
 
 
+def test_json_mode_emits_source_when_labeled():
+    out = io.StringIO()
+    r = StreamRenderer(json_mode=True, out=out)
+    r.begin(types.SimpleNamespace(id="sess_1"), source="system")
+    r.turn(_turn("hi", True), source="you")
+    lines = [json.loads(line) for line in out.getvalue().splitlines()]
+    assert lines[0] == {"type": "begin", "id": "sess_1", "source": "system"}
+    assert lines[1] == {
+        "type": "turn",
+        "transcript": "hi",
+        "end_of_turn": True,
+        "source": "you",
+    }
+
+
 def test_termination_json_emits_duration():
     out = io.StringIO()
     r = StreamRenderer(json_mode=True, out=out)

From 6e58e261f749f2620151dfc87d1285d5002f9bdc Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Fri, 5 Jun 2026 12:17:03 -0700
Subject: [PATCH 2/5] Fix system audio CI checks

---
 aai_cli/commands/stream.py       |   4 +-
 pyproject.toml                   |   2 +
 tests/test_macos_audio_source.py |   1 +
 tests/test_stream_command.py     | 197 ++++++++++++++++++++++++++++---
 tests/test_streaming_render.py   |  12 ++
 5 files changed, 199 insertions(+), 17 deletions(-)

diff --git a/aai_cli/commands/stream.py b/aai_cli/commands/stream.py
index 57fcf607..7655411d 100644
--- a/aai_cli/commands/stream.py
+++ b/aai_cli/commands/stream.py
@@ -11,7 +11,7 @@
 
 from aai_cli import client, code_gen, config, config_builder, help_panels, llm, output, youtube
 from aai_cli.context import AppState, run_command
-from aai_cli.errors import UsageError
+from aai_cli.errors import CLIError, UsageError
 from aai_cli.follow import FollowRenderer
 from aai_cli.help_text import examples_epilog
 from aai_cli.microphone import MicrophoneSource
@@ -328,7 +328,7 @@ def run_parallel(streams: list[tuple[str, Iterable[bytes], int]]) -> None:
             def worker(source_label: str, audio: Iterable[bytes], rate: int) -> None:
                 try:
                     stream_one(audio, rate, source_label=source_label)
-                except Exception as exc:  # noqa: BLE001 - propagate worker failures on main thread
+                except (CLIError, BrokenPipeError) as exc:
                     errors.put(exc)
 
             def drive() -> None:
diff --git a/pyproject.toml b/pyproject.toml
index a6fde983..c48210d8 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -114,6 +114,8 @@ markers = [
 [tool.mypy]
 python_version = "3.11"
 files = ["aai_cli", "tests"]
+# Init templates are packaged scaffold assets, not importable package modules.
+exclude = ["^aai_cli/init/templates/"]
 # Third-party deps (assemblyai, sounddevice) ship no type stubs.
 ignore_missing_imports = true
 disallow_untyped_defs = true
diff --git a/tests/test_macos_audio_source.py b/tests/test_macos_audio_source.py
index 463915b7..1afadfef 100644
--- a/tests/test_macos_audio_source.py
+++ b/tests/test_macos_audio_source.py
@@ -164,6 +164,7 @@ def test_raise_helper_exit_handles_clean_eof():
 
 def test_returncode_detail_names_signals():
     assert macos._returncode_detail(-5) == "SIGTRAP (-5)"
+    assert macos._returncode_detail(-99999) == "signal 99999 (-99999)"
     assert macos._returncode_detail(2) == "exit 2"
     assert macos._returncode_detail(None) == "unknown exit"
 
diff --git a/tests/test_stream_command.py b/tests/test_stream_command.py
index c6e56d66..7bfdf393 100644
--- a/tests/test_stream_command.py
+++ b/tests/test_stream_command.py
@@ -1,10 +1,13 @@
 import json
+import time
 import types
+from collections.abc import Callable
 
 from typer.testing import CliRunner
 
 from aai_cli import config
 from aai_cli.auth.flow import LoginResult
+from aai_cli.errors import APIError
 from aai_cli.main import app
 
 runner = CliRunner()
@@ -510,35 +513,37 @@ def test_stream_stdin_rejects_device(monkeypatch):
 
 def test_stream_system_audio_uses_macos_source(monkeypatch):
     config.set_api_key("default", "sk_live")
-    seen = {"source_types": []}
+    source_types: list[str] = []
+    rates: list[int] = []
+    mic_target_rate: list[int | None] = [None]
+    system_on_open: list[Callable[[], None] | None] = [None]
+    mic_on_open: list[Callable[[], None] | None] = [None]
 
     class FakeSystemAudio:
         def __init__(self, *, on_open=None):
-            seen["system_on_open"] = on_open
+            system_on_open[0] = on_open
             self.sample_rate = 16000
 
         def __iter__(self):
-            if seen["system_on_open"]:
-                seen["system_on_open"]()
+            if system_on_open[0] is not None:
+                system_on_open[0]()
             return iter([b"system"])
 
     class FakeMic:
         def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
-            seen["mic_target_rate"] = target_rate
-            seen["mic_device"] = device
-            seen["mic_capture_rate"] = capture_rate
-            seen["mic_on_open"] = on_open
+            mic_target_rate[0] = target_rate
+            mic_on_open[0] = on_open
             self.sample_rate = 16000
 
         def __iter__(self):
-            if seen["mic_on_open"]:
-                seen["mic_on_open"]()
+            if mic_on_open[0] is not None:
+                mic_on_open[0]()
             return iter([b"mic"])
 
     def fake_stream_audio(api_key, source, *, params, on_begin=None, on_turn=None, **_kwargs):
         source_type = type(source).__name__
-        seen["source_types"].append(source_type)
-        seen.setdefault("rates", []).append(params.sample_rate)
+        source_types.append(source_type)
+        rates.append(params.sample_rate)
         if on_begin:
             on_begin(types.SimpleNamespace(id=source_type))
         list(source)
@@ -550,9 +555,9 @@ def fake_stream_audio(api_key, source, *, params, on_begin=None, on_turn=None, *
     monkeypatch.setattr("aai_cli.commands.stream.client.stream_audio", fake_stream_audio)
     result = runner.invoke(app, ["stream", "--system-audio", "--json"])
     assert result.exit_code == 0
-    assert set(seen["source_types"]) == {"FakeSystemAudio", "FakeMic"}
-    assert seen["rates"] == [16000, 16000]
-    assert seen["mic_target_rate"] == 16000
+    assert set(source_types) == {"FakeSystemAudio", "FakeMic"}
+    assert rates == [16000, 16000]
+    assert mic_target_rate[0] == 16000
     lines = [json.loads(x) for x in result.output.splitlines() if x.strip()]
     assert {
         "type": "turn",
@@ -627,6 +632,168 @@ def fake_stream_audio(api_key, source, *, params, **_kwargs):
     assert seen == {"target_rate": 16000, "device": 2, "capture_rate": 44100}
 
 
+def test_stream_system_audio_llm_prefixes_sources(monkeypatch):
+    config.set_api_key("default", "sk_live")
+    transcript_inputs = []
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            self.sample_rate = 16000
+
+        def __iter__(self):
+            return iter([b"system"])
+
+    class FakeMic:
+        def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
+            self.sample_rate = target_rate
+
+        def __iter__(self):
+            return iter([b"mic"])
+
+    def fake_stream_audio(api_key, source, *, params, on_turn=None, **_kwargs):
+        if on_turn:
+            on_turn(types.SimpleNamespace(transcript="", end_of_turn=True))
+            on_turn(types.SimpleNamespace(transcript=type(source).__name__, end_of_turn=True))
+
+    def fake_run_chain(api_key, prompts, *, transcript_text, model, max_tokens):
+        transcript_inputs.append(transcript_text)
+        return "summary"
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", FakeMic)
+    monkeypatch.setattr("aai_cli.commands.stream.client.stream_audio", fake_stream_audio)
+    monkeypatch.setattr("aai_cli.commands.stream.llm.run_chain", fake_run_chain)
+    result = runner.invoke(app, ["stream", "--system-audio", "--llm", "summarize", "--json"])
+    assert result.exit_code == 0
+    assert any("System: FakeSystemAudio" in value for value in transcript_inputs)
+    assert any("You: FakeMic" in value for value in transcript_inputs)
+
+
+def test_stream_system_audio_parallel_worker_error_surfaces(monkeypatch):
+    config.set_api_key("default", "sk_live")
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            self.sample_rate = 16000
+
+        def __iter__(self):
+            return iter([b"system"])
+
+    class FakeMic:
+        def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
+            self.sample_rate = target_rate
+
+        def __iter__(self):
+            return iter([b"mic"])
+
+    def fake_stream_audio(api_key, source, *, params, **_kwargs):
+        if type(source).__name__ == "FakeMic":
+            raise APIError("mic failed")
+        time.sleep(0.2)
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", FakeMic)
+    monkeypatch.setattr("aai_cli.commands.stream.client.stream_audio", fake_stream_audio)
+    result = runner.invoke(app, ["stream", "--system-audio", "--json"])
+    assert result.exit_code == 1
+    assert "mic failed" in result.output
+
+
+def test_stream_system_audio_parallel_final_worker_error_surfaces(monkeypatch):
+    config.set_api_key("default", "sk_live")
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            self.sample_rate = 16000
+
+        def __iter__(self):
+            return iter([b"system"])
+
+    class FakeMic:
+        def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
+            self.sample_rate = target_rate
+
+        def __iter__(self):
+            return iter([b"mic"])
+
+    class ImmediateThread:
+        def __init__(self, *, target, args, daemon):
+            self._target = target
+            self._args = args
+
+        def start(self):
+            self._target(*self._args)
+
+        def is_alive(self):
+            return False
+
+        def join(self, timeout=None):
+            return None
+
+    def fake_stream_audio(api_key, source, *, params, **_kwargs):
+        raise APIError(f"{type(source).__name__} failed")
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", FakeMic)
+    monkeypatch.setattr("aai_cli.commands.stream.client.stream_audio", fake_stream_audio)
+    monkeypatch.setattr("aai_cli.commands.stream.threading.Thread", ImmediateThread)
+    result = runner.invoke(app, ["stream", "--system-audio", "--json"])
+    assert result.exit_code == 1
+    assert "failed" in result.output
+
+
+def test_stream_system_audio_parallel_keyboard_interrupt_exits_cleanly(monkeypatch):
+    config.set_api_key("default", "sk_live")
+    monkeypatch.setattr("aai_cli.output.resolve_json", lambda *, explicit: False)
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            self.sample_rate = 16000
+
+    class FakeMic:
+        def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
+            self.sample_rate = target_rate
+
+    class InterruptingThread:
+        def __init__(self, *, target, args, daemon):
+            pass
+
+        def start(self):
+            raise KeyboardInterrupt
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", FakeMic)
+    monkeypatch.setattr("aai_cli.commands.stream.threading.Thread", InterruptingThread)
+    result = runner.invoke(app, ["stream", "--system-audio"])
+    assert result.exit_code == 0
+    assert "Stopped." in result.output
+
+
+def test_stream_system_audio_parallel_broken_pipe_exits_zero(monkeypatch):
+    config.set_api_key("default", "sk_live")
+
+    class FakeSystemAudio:
+        def __init__(self, *, on_open=None):
+            self.sample_rate = 16000
+
+    class FakeMic:
+        def __init__(self, *, target_rate=None, device=None, capture_rate=None, on_open=None):
+            self.sample_rate = target_rate
+
+    class BrokenPipeThread:
+        def __init__(self, *, target, args, daemon):
+            pass
+
+        def start(self):
+            raise BrokenPipeError
+
+    monkeypatch.setattr("aai_cli.commands.stream.MacSystemAudioSource", FakeSystemAudio)
+    monkeypatch.setattr("aai_cli.commands.stream.MicrophoneSource", FakeMic)
+    monkeypatch.setattr("aai_cli.commands.stream.threading.Thread", BrokenPipeThread)
+    result = runner.invoke(app, ["stream", "--system-audio"])
+    assert result.exit_code == 0
+
+
 def test_stream_system_audio_only_rejects_mic_device_flags():
     config.set_api_key("default", "sk_live")
     result = runner.invoke(app, ["stream", "--system-audio-only", "--device", "2"])
diff --git a/tests/test_streaming_render.py b/tests/test_streaming_render.py
index 8d4439f4..97934edf 100644
--- a/tests/test_streaming_render.py
+++ b/tests/test_streaming_render.py
@@ -51,6 +51,18 @@ def test_human_turn_labels_parallel_sources():
     assert "\x1b[" in out
 
 
+def test_text_mode_labels_sources_and_statuses_to_stderr():
+    out = io.StringIO()
+    err = io.StringIO()
+    r = StreamRenderer(json_mode=False, text_mode=True, out=out, err=err)
+    r.listening()
+    r.turn(_turn("hello from me", True), source="you")
+    r.stopped()
+    assert out.getvalue() == "You: hello from me\n"
+    assert "Listening" in err.getvalue()
+    assert "Stopped." in err.getvalue()
+
+
 def test_human_begin_is_silent_until_mic_opens():
     # The session opening (Begin) no longer prints "Listening…"; that waits for
     # the mic to actually open and start recording (renderer.listening()).

From ea8ec3466ca44ba3cbce551568f1892a0dc88215 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Fri, 5 Jun 2026 12:23:06 -0700
Subject: [PATCH 3/5] Fix Linux mypy platform guard

---
 aai_cli/streaming/macos.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/aai_cli/streaming/macos.py b/aai_cli/streaming/macos.py
index 810278e0..13525e89 100644
--- a/aai_cli/streaming/macos.py
+++ b/aai_cli/streaming/macos.py
@@ -63,9 +63,13 @@ def _resource_bytes() -> bytes:
     return resources.files("aai_cli.streaming").joinpath(_HELPER_RESOURCE).read_bytes()
 
 
+def _is_macos() -> bool:
+    return sys.platform == "darwin"
+
+
 def build_helper() -> Path:
     """Compile the bundled ScreenCaptureKit helper once and return its executable path."""
-    if sys.platform != "darwin":
+    if not _is_macos():
         raise _unsupported_platform()
     swiftc = shutil.which("swiftc")
     if swiftc is None:

From b6894d2217b4caa4f4ae34f6d9f20300103e57c6 Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Fri, 5 Jun 2026 12:25:36 -0700
Subject: [PATCH 4/5] Skip macOS Swift compile on Linux

---
 scripts/check.sh | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/scripts/check.sh b/scripts/check.sh
index 78271a75..2d2e8498 100755
--- a/scripts/check.sh
+++ b/scripts/check.sh
@@ -69,7 +69,9 @@ else
 fi
 
 echo "==> swift compile (macOS audio helper)"
-if command -v swiftc >/dev/null 2>&1; then
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  echo "   not macOS; skipping compile for macOS-only frameworks"
+elif command -v swiftc >/dev/null 2>&1; then
   swift_module_cache="$(mktemp -d)"
   swift_helper="$swift_module_cache/aai-macos-audio-check"
   swift_error="$swift_module_cache/aai-macos-audio-check.err"

From 08c4db83a0bebc84902c60424dcc8273e97e898c Mon Sep 17 00:00:00 2001
From: Alex Kroman <alex@assemblyai.com>
Date: Fri, 5 Jun 2026 12:27:05 -0700
Subject: [PATCH 5/5] Avoid duplicate CI runs on PR branch pushes

---
 .github/workflows/ci.yml | 1 +
 1 file changed, 1 insertion(+)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9574103a..161e6542 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -3,6 +3,7 @@ name: CI
 on:
   pull_request:
     branches: [main]
+    types: [opened, reopened, ready_for_review]
   push:
 
 # Least privilege: CI only needs to read the repo. Actions are pinned to commit