From 1172fff93504d68463801fd024aa684a342f5271 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 18 Sep 2026 19:24:38 +0000
Subject: [PATCH 1/8] Use `lk agent` for console, dev, and start

Match the Python starter: the README now documents `lk agent console`,
`lk agent dev`, and `lk agent start` for local runs, the `dev` script and the
taskfile hint run through the CLI, and the CLI install instructions moved into
Dev Setup so they come before the first command that needs them.

The `start` script stays a direct `node src/main.ts start`, because the
Dockerfile runs `pnpm start` and the container image doesn't include `lk`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 AGENTS.md     |  4 ++--
 README.md     | 54 ++++++++++++++++++++++++++++++++++-----------------
 package.json  |  2 +-
 taskfile.yaml |  2 +-
 4 files changed, 40 insertions(+), 22 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e9a49c0..06dfecc 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -6,9 +6,9 @@ The following is a guide for working with this project.
 
 ## Project structure
 
-This Node.js project uses the `pnpm` package manager. You should always use `pnpm` to install dependencies, run the agent, and run tests.
+This Node.js project uses the `pnpm` package manager. You should always use `pnpm` to install dependencies and run tests. To run the agent itself, use the LiveKit CLI: `lk agent console` to talk to it in the terminal, `lk agent dev` for a reloading development server, and `lk agent start` for production mode. See the [agent commands reference](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/) for the options each one accepts.
 
-All app-level code is in the `src/` directory. In general, simple agents can be constructed with a single `main.ts` file. Additional files can be added, but you must retain `main.ts` as the entrypoint (see the associated Dockerfile for how this is deployed).
+All app-level code is in the `src/` directory. In general, simple agents can be constructed with a single `main.ts` file. Additional files can be added, but you must retain `main.ts` as the entrypoint (the Dockerfile and the CLI's entrypoint detection both expect `src/main.ts`).
 
 Be sure to maintain code formatting. You can use the prettier formatter and eslint to format and lint the code. Scripts are available in `package.json`, including `pnpm format` and `pnpm lint`.
 
diff --git a/README.md b/README.md
index bddecb6..2e47529 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,24 @@ This starter app is compatible with any [custom web/mobile frontend](https://doc
 
 This project is designed to work with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/).
 
-For your convenience, LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) that can be used to browse and search its documentation. The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) (`lk docs`) works with any coding agent that can run shell commands. Install it for your platform:
+For your convenience, LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) that can be used to browse and search its documentation. The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) (`lk docs`) works with any coding agent that can run shell commands. See [Install the LiveKit CLI](#install-the-livekit-cli) below for installation instructions.
+
+Once installed, your coding agent can search and browse LiveKit documentation directly from the terminal:
+
+```console
+lk docs search "voice agents"
+lk docs get-page /agents/start/voice-ai-quickstart
+```
+
+See the [Coding agent support](https://docs.livekit.io/intro/coding-agents/) guide for more details, including MCP server setup.
+
+The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suit your needs. To learn more about this file, see [https://agents.md](https://agents.md).
+
+## Dev Setup
+
+### Install the LiveKit CLI
+
+The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) creates the project and runs the agent locally. Install it for your platform:
 
 **macOS:**
 
@@ -47,20 +64,11 @@ curl -sSL https://get.livekit.io/cli | bash
 winget install LiveKit.LiveKitCLI
 ```
 
-The `lk docs` subcommand requires version 2.15.0 or higher. Check your version with `lk --version` and update if needed. Once installed, your coding agent can search and browse LiveKit documentation directly from the terminal:
-
-```console
-lk docs search "voice agents"
-lk docs get-page /agents/start/voice-ai-quickstart
-```
-
-See the [Coding agent support](https://docs.livekit.io/intro/coding-agents/) guide for more details, including MCP server setup.
+Requires version 2.15.0 or higher. Check your version with `lk --version` and update if needed.
 
-The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suit your needs. To learn more about this file, see [https://agents.md](https://agents.md).
+### Create the project
 
-## Dev Setup
-
-Create a project from this template with the LiveKit CLI (recommended):
+Create a project from this template with the CLI (recommended):
 
 ```bash
 lk cloud auth
@@ -72,7 +80,7 @@ The CLI clones the template and configures your environment. Then follow the res
 This project uses [pnpm](https://pnpm.io/) as the package manager.
 
 <details>
-<summary>Alternative: Manual setup without the CLI</summary>
+<summary>Alternative: Set up the project manually</summary>
 
 Clone the repository and install dependencies:
 
@@ -98,18 +106,28 @@ lk app env -w -d .env.local
 
 ## Run the agent
 
-To run the agent during development, use the `dev` command:
+The `lk agent` commands run your agent on your own machine. Run them from the project root — the CLI finds `src/main.ts` on its own.
+
+Run this command to speak to your agent directly in your terminal:
 
 ```console
-pnpm run dev
+lk agent console
 ```
 
-In production, use the `start` command:
+To run the agent for use with a frontend or telephony, use the `dev` command, which reloads the agent whenever you change its source:
 
 ```console
-pnpm run start
+lk agent dev
 ```
 
+To run it in production mode, with clean logging and graceful shutdown, use the `start` command:
+
+```console
+lk agent start
+```
+
+The `dev` script in `package.json` runs `lk agent dev`, so `pnpm run dev` does the same thing. The `start` script runs the agent directly instead, because your deployed agent starts from the `CMD` in the [Dockerfile](Dockerfile) and the container image doesn't include `lk`. See [Server startup modes](https://docs.livekit.io/agents/server/startup-modes/) for the full set of options each command accepts.
+
 ## Frontend & Telephony
 
 Get started quickly with our pre-built frontend starter apps, or add telephony support:
diff --git a/package.json b/package.json
index 5ee3f8d..80501a6 100644
--- a/package.json
+++ b/package.json
@@ -11,7 +11,7 @@
     "format:check": "prettier --check \"**/*.{ts,js,json,md}\"",
     "test": "vitest --run",
     "test:watch": "vitest",
-    "dev": "node src/main.ts dev",
+    "dev": "lk agent dev",
     "start": "node src/main.ts start"
   },
   "engines": {
diff --git a/taskfile.yaml b/taskfile.yaml
index 9535de9..e308c77 100644
--- a/taskfile.yaml
+++ b/taskfile.yaml
@@ -15,7 +15,7 @@ tasks:
       - echo ''
       - echo '{{ indent .INDENT "cd" }} {{ .REL_PATH }}'
       - task: help_install_hint_if_needed
-      - echo '{{ indent .INDENT "pnpm dev" }}'
+      - echo '{{ indent .INDENT "lk agent dev" }}'
       - echo ''
       - task: help_open_web_console
       - echo 'To deploy your agent to LiveKit cloud:'

From 9ebbb7b716ce559727bdf62dc8bf3eca4650816f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 18 Sep 2026 20:31:50 +0000
Subject: [PATCH 2/8] Describe what dev mode adds, not just reload

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 2e47529..4cad0ae 100644
--- a/README.md
+++ b/README.md
@@ -114,7 +114,7 @@ Run this command to speak to your agent directly in your terminal:
 lk agent console
 ```
 
-To run the agent for use with a frontend or telephony, use the `dev` command, which reloads the agent whenever you change its source:
+To run the agent for use with a frontend or telephony, use the `dev` command, which adds hot reload on source changes and debug-level logging:
 
 ```console
 lk agent dev

From 4a7bf604cca21e58348b9aaa709753fc71dd3780 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 23 Sep 2026 18:35:59 +0000
Subject: [PATCH 3/8] Trim the README and AGENTS.md, and apply the docs style
 guide

Review feedback: drop guidance a coding agent can work out on its own
(project layout, where to run commands, the dev/start scripts), show the
direct `node src/main.ts start` for production since that's what the
Dockerfile runs, and use long flag names in human-facing commands.

Also a copy pass against the docs style guide: sentence-case headings,
no "we", no hyphens standing in for dashes, bulleted rather than numbered
non-sequential lists, and less filler throughout. Collapses the CLI install
block into a three-line list and links the update instructions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 AGENTS.md |  42 ++++++++---------
 README.md | 137 ++++++++++++++++++++----------------------------------
 2 files changed, 69 insertions(+), 110 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 06dfecc..0bc45c9 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,24 +1,20 @@
 # AGENTS.md
 
-This is a LiveKit Agents project. LiveKit Agents is a Node.js SDK for building voice AI agents. This project is intended to be used with LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem.
+This is a LiveKit Agents project. LiveKit Agents is a Node.js SDK for building voice AI agents, and this project is designed for LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem.
 
-The following is a guide for working with this project.
+## Tooling
 
-## Project structure
+This Node.js project uses the `pnpm` package manager.
 
-This Node.js project uses the `pnpm` package manager. You should always use `pnpm` to install dependencies and run tests. To run the agent itself, use the LiveKit CLI: `lk agent console` to talk to it in the terminal, `lk agent dev` for a reloading development server, and `lk agent start` for production mode. See the [agent commands reference](https://docs.livekit.io/reference/developer-tools/livekit-cli/agent/) for the options each one accepts.
+Be sure to maintain code formatting, using `pnpm format` and `pnpm lint`.
 
-All app-level code is in the `src/` directory. In general, simple agents can be constructed with a single `main.ts` file. Additional files can be added, but you must retain `main.ts` as the entrypoint (the Dockerfile and the CLI's entrypoint detection both expect `src/main.ts`).
+## LiveKit documentation
 
-Be sure to maintain code formatting. You can use the prettier formatter and eslint to format and lint the code. Scripts are available in `package.json`, including `pnpm format` and `pnpm lint`.
-
-## LiveKit Documentation
-
-LiveKit Agents is a fast-evolving project, and the documentation is updated frequently. You should always refer to the latest documentation when working with this project. For your convenience, LiveKit offers both a CLI and an MCP server that can be used to browse and search its documentation. If the developer has not yet installed the CLI, you should recommend that they install it.
+LiveKit Agents changes quickly, and its documentation is updated often. Always refer to the latest documentation when working with this project. LiveKit offers both a CLI and an MCP server for browsing and searching its documentation. If the developer hasn't installed the CLI yet, recommend that they install it.
 
 ### LiveKit CLI
 
-The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) `lk docs` subcommand gives full access to LiveKit documentation from the terminal. Requires CLI version 2.15.0+. Check with `lk --version`.
+The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) `lk docs` subcommand gives full access to LiveKit documentation from the terminal. It requires CLI version 2.15.0 or later. Check with `lk --version`.
 
 Install or update the CLI:
 
@@ -26,32 +22,32 @@ Install or update the CLI:
 - **Linux:** `curl -sSL https://get.livekit.io/cli | bash`
 - **Windows:** `winget install LiveKit.LiveKitCLI` (update: `winget upgrade LiveKit.LiveKitCLI`)
 
-Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, `lk docs submit-feedback`. Run `lk docs <command> --help` before using a command for the first time, as the help text includes advice on usage and interpreting results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, as docs pages are more up-to-date and provide better context than raw code.
+Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs <command> --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code.
 
-### LiveKit Docs MCP Server
+### LiveKit docs MCP server
 
-For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) with the same documentation access. It uses Streamable HTTP transport at `https://docs.livekit.io/mcp`. Refer to your IDE's documentation for how to add it.
+For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) with the same documentation access. It uses Streamable HTTP transport at `https://docs.livekit.io/mcp`. See your IDE's documentation for how to add it.
 
 ### Submit docs feedback to LiveKit
 
-If you use the LiveKit CLI or MCP Server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, to ensure you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps or any other documentation gap or issue.
+If you use the LiveKit CLI or MCP server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, so you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, or any other gap or issue in the docs.
 
 ## Handoffs ("workflows")
 
-Voice AI agents are highly sensitive to excessive latency. For this reason, it's important to design complex agents in a structured manner that minimizes the amount of irrelevant context and unnecessary tools present on requests to the LLM. LiveKit Agents supports handoffs (one agent hands control to another) to support building reliable workflows. You should make use of these features, instead of writing long instruction prompts that cover multiple phases of a conversation. Refer to the [documentation](https://docs.livekit.io/agents/build/workflows/) for more information.
+Voice AI agents are highly sensitive to latency. Design complex agents in a structured way that keeps irrelevant context and unneeded tools out of each LLM request. LiveKit Agents supports handoffs, where one agent hands control to another, for building reliable workflows. Use handoffs instead of long instruction prompts that cover several phases of a conversation. See the [workflows documentation](https://docs.livekit.io/agents/build/workflows/) for more information.
 
 ## Testing
 
-When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to main; read the [simulations documentation](https://docs.livekit.io/agents/start/testing/simulations/) before editing them.
+When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/agents/start/testing/simulations/) before editing them.
 
-For turn-level checks that don't need a live session, use the in-process [testing framework](https://docs.livekit.io/agents/start/testing/); `src/agent.test.ts` has a commented-out example. Run those with `pnpm test`.
+For turn-level checks that don't need a live session, use the in-process [testing framework](https://docs.livekit.io/agents/start/testing/). `src/agent.test.ts` has a commented-out example. Run those tests with `pnpm test`.
 
-Important: When modifying core agent behavior such as instructions, tool descriptions, and tasks/workflows/handoffs, never just guess what will work. Always use test-driven development (TDD) and begin by writing tests for the desired behavior. For instance, if you're planning to add a new tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass correctly. This will ensure you are able to produce a working, reliable agent for the user.
+Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent.
 
-## Feature parity with Python SDK
+## Feature parity with the Python SDK
 
-The Node.js SDK for LiveKit Agents has most, but not all, of the same features available in Python SDK for LiveKit Agents. You should always check the documentation for feature availability, and avoid using features that are not available in the Node.js SDK.
+The Node.js SDK for LiveKit Agents has most, but not all, of the features in the Python SDK. Always check the documentation for feature availability, and avoid features the Node.js SDK doesn't support.
 
-## LiveKit CLI
+## Other CLI commands
 
-Beyond documentation access, the LiveKit CLI (`lk`) supports other tasks such as managing SIP trunks for telephony-based agents. Run `lk --help` to explore available commands.
+Beyond documentation access, the LiveKit CLI (`lk`) handles tasks such as managing SIP trunks for telephony agents. Run `lk --help` to explore available commands.
diff --git a/README.md b/README.md
index 4cad0ae..fcffe44 100644
--- a/README.md
+++ b/README.md
@@ -2,135 +2,99 @@
   <img src="./.github/assets/livekit-mark.png" alt="LiveKit logo" width="100" height="100">
 </a>
 
-# LiveKit Agents Starter - Node.js
+# LiveKit Agents starter for Node.js
 
-A complete starter project for building voice AI apps with [LiveKit Agents for Node.js](https://github.com/livekit/agents-js) and [LiveKit Cloud](https://cloud.livekit.io/).
+A starter project for building voice AI apps with [LiveKit Agents for Node.js](https://github.com/livekit/agents-js) and [LiveKit Cloud](https://cloud.livekit.io/).
 
-The starter project includes:
+The starter includes:
 
-- A simple voice AI assistant, ready for extension and customization
-- A voice AI pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference), providing zero-configuration access to [models](https://docs.livekit.io/agents/models) from top labs
-  - Uses the fast, open-weight Gemma 4 31B model, [hosted by LiveKit](https://docs.livekit.io/agents/models/llm/livekit/) and tuned for optimal performance in voice AI, as the default LLM
-  - Uses Fish Audio S2.1 Pro for TTS, which renders the inline delivery markup that expressive mode relies on
-  - Supports more than 50 models from OpenAI, Cartesia, Deepgram, and other providers
-  - Access to a wide range of other models, including [Realtime models](https://docs.livekit.io/agents/models/realtime), through extensive plugin ecosystem
-- Expressive mode, enabled by default: the framework injects the TTS provider's markup guide into the LLM prompt, so the model emits inline delivery tags (emotion, pacing, non-verbal sounds) that the TTS renders and the transcript never shows
-- Eval suite based on the LiveKit Agents [testing & evaluation framework](https://docs.livekit.io/agents/start/testing)
-- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), an end-of-turn model that listens to the user's audio directly, combining semantic understanding with acoustic cues for state-of-the-art accuracy across 14 languages
-- [Background voice cancellation](https://docs.livekit.io/transport/media/noise-cancellation/)
-- Deep session insights from LiveKit [Agent Observability](https://docs.livekit.io/deploy/observability/)
-- A Dockerfile ready for [production deployment to LiveKit Cloud](https://docs.livekit.io/deploy/agents/)
+- A simple voice AI assistant to extend and customize.
+- A voice pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference), which gives you access to [models](https://docs.livekit.io/agents/models) from top labs with no extra configuration:
+  - The default LLM is Gemma 4 31B, an open-weight model [hosted by LiveKit](https://docs.livekit.io/agents/models/llm/livekit/) and tuned for voice AI.
+  - The default TTS is Fish Audio S2.1 Pro, which renders the inline delivery markup that expressive mode relies on.
+  - More than 50 other models are available from OpenAI, Cartesia, Deepgram, and other providers.
+  - [Realtime models](https://docs.livekit.io/agents/models/realtime) and many others are available through the plugin ecosystem.
+- Expressive mode, on by default. The framework adds the TTS provider's markup guide to the LLM prompt, so the model emits inline delivery tags (emotion, pacing, non-verbal sounds) that the TTS renders and the transcript omits.
+- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), an end-of-turn model that listens to the user's audio directly and combines semantic understanding with acoustic cues, in 14 languages.
+- [Background voice cancellation](https://docs.livekit.io/transport/media/noise-cancellation/).
+- Session insights from LiveKit [Agent Observability](https://docs.livekit.io/deploy/observability/).
+- [Simulations](https://docs.livekit.io/agents/start/testing/simulations/) that test full conversations with your agent, run in CI on every merge to `main`.
+- A `Dockerfile` for [deploying to LiveKit Cloud](https://docs.livekit.io/deploy/agents/).
 
-This starter app is compatible with any [custom web/mobile frontend](https://docs.livekit.io/frontends/) or [telephony](https://docs.livekit.io/telephony/).
+The starter works with any [custom web or mobile frontend](https://docs.livekit.io/frontends/) or with [telephony](https://docs.livekit.io/telephony/).
 
 ## Using coding agents
 
-This project is designed to work with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/).
+This project works with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/).
 
-For your convenience, LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) that can be used to browse and search its documentation. The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) (`lk docs`) works with any coding agent that can run shell commands. See [Install the LiveKit CLI](#install-the-livekit-cli) below for installation instructions.
-
-Once installed, your coding agent can search and browse LiveKit documentation directly from the terminal:
+LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) for browsing and searching its documentation. For example:
 
 ```console
-lk docs search "voice agents"
-lk docs get-page /agents/start/voice-ai-quickstart
+lk docs search "testing my agent"
 ```
 
-See the [Coding agent support](https://docs.livekit.io/intro/coding-agents/) guide for more details, including MCP server setup.
-
-The project includes a complete [AGENTS.md](AGENTS.md) file for these assistants. You can modify this file to suit your needs. To learn more about this file, see [https://agents.md](https://agents.md).
-
-## Dev Setup
+See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup.
 
-### Install the LiveKit CLI
+## Dev setup
 
-The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) creates the project and runs the agent locally. Install it for your platform:
+Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.15.0 or later:
 
-**macOS:**
+- **macOS:** `brew install livekit-cli`
+- **Linux:** `curl -sSL https://get.livekit.io/cli | bash`
+- **Windows:** `winget install LiveKit.LiveKitCLI`
 
-```console
-brew install livekit-cli
-```
+Check your version with `lk --version`. To update an existing install, see [Update the CLI](https://docs.livekit.io/reference/developer-tools/livekit-cli/#updates).
 
-**Linux:**
+Then create a project from this template. The CLI clones the template and configures your environment:
 
 ```console
-curl -sSL https://get.livekit.io/cli | bash
-```
-
-**Windows:**
-
-```console
-winget install LiveKit.LiveKitCLI
-```
-
-Requires version 2.15.0 or higher. Check your version with `lk --version` and update if needed.
-
-### Create the project
-
-Create a project from this template with the CLI (recommended):
-
-```bash
 lk cloud auth
 lk agent init my-agent --template agent-starter-node
 ```
 
-The CLI clones the template and configures your environment. Then follow the rest of this guide from [Run the agent](#run-the-agent).
-
-This project uses [pnpm](https://pnpm.io/) as the package manager.
-
 <details>
-<summary>Alternative: Set up the project manually</summary>
+<summary>Set up the project manually</summary>
 
-Clone the repository and install dependencies:
+Clone the repository and install dependencies with [pnpm](https://pnpm.io/):
 
 ```console
+git clone https://github.com/livekit-examples/agent-starter-node.git
 cd agent-starter-node
 pnpm install
 ```
 
-Sign up for [LiveKit Cloud](https://cloud.livekit.io/) then set up the environment by copying `.env.example` to `.env.local` and filling in the required keys:
-
-- `LIVEKIT_URL`
-- `LIVEKIT_API_KEY`
-- `LIVEKIT_API_SECRET`
+Sign up for [LiveKit Cloud](https://cloud.livekit.io/), then copy `.env.example` to `.env.local` and fill it in. To have the CLI write your project's URL and API keys into the file instead, run:
 
-You can load the LiveKit environment automatically using the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/):
-
-```bash
+```console
 lk cloud auth
-lk app env -w -d .env.local
+lk app env --write --destination .env.local
 ```
 
 </details>
 
 ## Run the agent
 
-The `lk agent` commands run your agent on your own machine. Run them from the project root — the CLI finds `src/main.ts` on its own.
-
-Run this command to speak to your agent directly in your terminal:
+The `lk agent console` and `lk agent dev` commands run your agent on your own machine. To talk to it in your terminal:
 
 ```console
 lk agent console
 ```
 
-To run the agent for use with a frontend or telephony, use the `dev` command, which adds hot reload on source changes and debug-level logging:
+To connect it to LiveKit Cloud so a frontend or phone call can reach it:
 
 ```console
 lk agent dev
 ```
 
-To run it in production mode, with clean logging and graceful shutdown, use the `start` command:
+In production, run the agent directly:
 
 ```console
-lk agent start
+node src/main.ts start
 ```
 
-The `dev` script in `package.json` runs `lk agent dev`, so `pnpm run dev` does the same thing. The `start` script runs the agent directly instead, because your deployed agent starts from the `CMD` in the [Dockerfile](Dockerfile) and the container image doesn't include `lk`. See [Server startup modes](https://docs.livekit.io/agents/server/startup-modes/) for the full set of options each command accepts.
+## Frontends and telephony
 
-## Frontend & Telephony
-
-Get started quickly with our pre-built frontend starter apps, or add telephony support:
+Pair the agent with a prebuilt frontend starter, or add telephony:
 
 | Platform         | Link                                                                                                                | Description                                        |
 | ---------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
@@ -142,36 +106,35 @@ Get started quickly with our pre-built frontend starter apps, or add telephony s
 | **Web Embed**    | [`livekit-examples/agent-starter-embed`](https://github.com/livekit-examples/agent-starter-embed)                   | Voice AI widget for any website                    |
 | **Telephony**    | [Documentation](https://docs.livekit.io/telephony/)                                                                 | Add inbound or outbound calling to your agent      |
 
-For advanced customization, see the [complete frontend guide](https://docs.livekit.io/frontends/).
+For more options, see the [frontend guide](https://docs.livekit.io/frontends/).
 
 ## Tests and evals
 
-Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in [`scenarios.yaml`](scenarios.yaml). Run them locally with the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/):
+Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in [`scenarios.yaml`](scenarios.yaml). Run them locally with the CLI:
 
 ```console
 lk agent simulate --scenarios scenarios.yaml
 ```
 
-The `Simulations` workflow in `.github/workflows/simulations.yml` runs the same file on every merge to `main` and on demand from the Actions tab. It runs there rather than on every pull request push because each run spends real inference. See the [simulations guide](https://docs.livekit.io/agents/start/testing/simulations/) for how to write scenarios and read results.
-
-For turn-level checks that don't need a live session, the LiveKit Agents [testing & evaluation framework](https://docs.livekit.io/agents/start/testing/) runs your agent in-process under `vitest`. A commented-out example lives in [`src/agent.test.ts`](src/agent.test.ts).
+The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/agents/start/testing/simulations/) for how to write scenarios and read results.
 
-## Using this template repo for your own project
+For turn-level checks that don't need a live session, the LiveKit Agents [testing and evaluation framework](https://docs.livekit.io/agents/start/testing/) runs your agent in-process under `vitest`. [`src/agent.test.ts`](src/agent.test.ts) has a commented-out example.
 
-Once you've started your own project based on this repo, you should:
+## Using this template for your own project
 
-1. **Check in your `pnpm-lock.yaml`**: This file is currently untracked for the template, but you should commit it to your repository for reproducible builds and proper configuration management. (The same applies to `livekit.toml`, if you run your agents in LiveKit Cloud)
+After you create your own project from this template:
 
-2. **Add your own repository secrets**: You must [add secrets](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions) for `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` so that the simulations can run in CI.
+- **Commit `pnpm-lock.yaml`.** The template doesn't track it, but your project should, for reproducible builds. If you deploy to LiveKit Cloud, commit `livekit.toml` too.
+- **Add repository secrets.** Add `LIVEKIT_URL`, `LIVEKIT_API_KEY`, and `LIVEKIT_API_SECRET` as [repository secrets](https://docs.github.com/en/actions/how-tos/writing-workflows/choosing-what-your-workflow-does/using-secrets-in-github-actions) so the simulations can run in CI.
 
 ## Deploying to production
 
-This project is production-ready and includes a working `Dockerfile`. To deploy it to LiveKit Cloud or another environment, see the [deploying to production](https://docs.livekit.io/deploy/agents/) guide.
+To deploy the agent to LiveKit Cloud or another environment with the included `Dockerfile`, see the [deployment guide](https://docs.livekit.io/deploy/agents/).
 
 ## Self-hosted LiveKit
 
-You can also self-host LiveKit instead of using LiveKit Cloud. See the [self-hosting](https://docs.livekit.io/transport/self-hosting/local/) guide for more information. If you choose to self-host, you'll need to also use [model plugins](https://docs.livekit.io/agents/models/#plugins) instead of LiveKit Inference and will need to remove the [LiveKit Cloud noise cancellation](https://docs.livekit.io/transport/media/noise-cancellation/) plugin.
+You can self-host LiveKit instead of using LiveKit Cloud. See the [self-hosting guide](https://docs.livekit.io/transport/self-hosting/local/). If you self-host, use [model plugins](https://docs.livekit.io/agents/models/#plugins) instead of LiveKit Inference, and remove the [LiveKit Cloud noise cancellation](https://docs.livekit.io/transport/media/noise-cancellation/) plugin.
 
 ## License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for details.

From 160d2435e6ce2f79503e6b2b315bd9acaed40725 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 23 Sep 2026 19:47:29 +0000
Subject: [PATCH 4/8] Sell outcomes in the feature list, and cover skills and
 debugging

The README feature list now says what each piece does for you and links
the docs for how: Fish Audio as an expressive, cost-effective default,
expressive mode, and adaptive interruption handling, which the starter
enables but the list never mentioned. "Using coding agents" points at the
bundled AGENTS.md and livekit-agents skill, and the testing section adds
Agent Console and `lk agent logs` for debugging.

AGENTS.md gains a section on the bundled skill (with a fallback path for
tools that do not load skills on their own) and a debugging checklist.
Links to the moved testing, observability, and workflows pages now point
at their current paths.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 AGENTS.md | 20 +++++++++++++++++---
 README.md | 29 ++++++++++++++++-------------
 2 files changed, 33 insertions(+), 16 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 0bc45c9..e01beca 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -32,18 +32,32 @@ For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.liv
 
 If you use the LiveKit CLI or MCP server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, so you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, or any other gap or issue in the docs.
 
+## LiveKit Agents skill
+
+This project includes the `livekit-agents` skill in `.claude/skills/` and `.agents/skills/`. It covers how to approach agent architecture, workflows, handoffs, tasks, and testing, and it defers to the live documentation for API details. If your tool doesn't load skills automatically, read `.agents/skills/livekit-agents/SKILL.md` before you design or restructure an agent.
+
 ## Handoffs ("workflows")
 
-Voice AI agents are highly sensitive to latency. Design complex agents in a structured way that keeps irrelevant context and unneeded tools out of each LLM request. LiveKit Agents supports handoffs, where one agent hands control to another, for building reliable workflows. Use handoffs instead of long instruction prompts that cover several phases of a conversation. See the [workflows documentation](https://docs.livekit.io/agents/build/workflows/) for more information.
+Voice AI agents are highly sensitive to latency. Design complex agents in a structured way that keeps irrelevant context and unneeded tools out of each LLM request. LiveKit Agents supports handoffs, where one agent hands control to another, for building reliable workflows. Use handoffs instead of long instruction prompts that cover several phases of a conversation. See the [workflows documentation](https://docs.livekit.io/agents/logic/workflows/) for more information.
 
 ## Testing
 
-When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/agents/start/testing/simulations/) before editing them.
+When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them.
 
-For turn-level checks that don't need a live session, use the in-process [testing framework](https://docs.livekit.io/agents/start/testing/). `src/agent.test.ts` has a commented-out example. Run those tests with `pnpm test`.
+For turn-level checks that don't need a live session, use the in-process [unit testing framework](https://docs.livekit.io/testing/unit-tests/). `src/agent.test.ts` has a commented-out example. Run those tests with `pnpm test`.
 
 Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent.
 
+## Debugging
+
+To investigate unexpected agent behavior:
+
+- Reproduce it in a unit test or simulation scenario first, so you have a repeatable case to iterate against.
+- Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent.
+- Run `lk agent logs` to stream logs from a deployed agent.
+- Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/), which shows events, tool calls, and model timing for a live session.
+- For sessions with real users, check [Agent Observability](https://docs.livekit.io/testing/observability/) for transcripts, traces, logs, and recordings.
+
 ## Feature parity with the Python SDK
 
 The Node.js SDK for LiveKit Agents has most, but not all, of the features in the Python SDK. Always check the documentation for feature availability, and avoid features the Node.js SDK doesn't support.
diff --git a/README.md b/README.md
index fcffe44..9ea7496 100644
--- a/README.md
+++ b/README.md
@@ -8,17 +8,18 @@ A starter project for building voice AI apps with [LiveKit Agents for Node.js](h
 
 The starter includes:
 
-- A simple voice AI assistant to extend and customize.
-- A voice pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference), which gives you access to [models](https://docs.livekit.io/agents/models) from top labs with no extra configuration:
+- A simple [voice AI assistant](https://docs.livekit.io/agents/start/voice-ai/) to extend and customize.
+- A voice pipeline built on [LiveKit Inference](https://docs.livekit.io/agents/models/inference/), which gives you access to [models](https://docs.livekit.io/agents/models/) from top labs with no extra configuration:
   - The default LLM is Gemma 4 31B, an open-weight model [hosted by LiveKit](https://docs.livekit.io/agents/models/llm/livekit/) and tuned for voice AI.
-  - The default TTS is Fish Audio S2.1 Pro, which renders the inline delivery markup that expressive mode relies on.
+  - The default TTS is [Fish Audio S2.1 Pro](https://docs.livekit.io/agents/models/tts/fishaudio/), an expressive and cost-effective voice.
   - More than 50 other models are available from OpenAI, Cartesia, Deepgram, and other providers.
-  - [Realtime models](https://docs.livekit.io/agents/models/realtime) and many others are available through the plugin ecosystem.
-- Expressive mode, on by default. The framework adds the TTS provider's markup guide to the LLM prompt, so the model emits inline delivery tags (emotion, pacing, non-verbal sounds) that the TTS renders and the transcript omits.
-- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), an end-of-turn model that listens to the user's audio directly and combines semantic understanding with acoustic cues, in 14 languages.
+  - [Realtime models](https://docs.livekit.io/agents/models/realtime/) and many others are available through the [plugin ecosystem](https://docs.livekit.io/agents/models/#plugins).
+- [Expressive mode](https://docs.livekit.io/agents/models/tts/expressive/), on by default, so your agent's voice carries emotion and pacing that fit the conversation.
+- [LiveKit Turn Detector](https://docs.livekit.io/agents/logic/turns/turn-detector/), which knows when the user has finished speaking, in 14 languages.
+- [Adaptive interruption handling](https://docs.livekit.io/agents/logic/turns/adaptive-interruption-handling/), which tells a real interruption from an "uh-huh" or background noise, so your agent doesn't stop talking when it shouldn't.
 - [Background voice cancellation](https://docs.livekit.io/transport/media/noise-cancellation/).
-- Session insights from LiveKit [Agent Observability](https://docs.livekit.io/deploy/observability/).
-- [Simulations](https://docs.livekit.io/agents/start/testing/simulations/) that test full conversations with your agent, run in CI on every merge to `main`.
+- Session transcripts, traces, and recordings from LiveKit [Agent Observability](https://docs.livekit.io/testing/observability/).
+- [Simulations](https://docs.livekit.io/testing/simulations/) that test full conversations with your agent, run in CI on every merge to `main`.
 - A `Dockerfile` for [deploying to LiveKit Cloud](https://docs.livekit.io/deploy/agents/).
 
 The starter works with any [custom web or mobile frontend](https://docs.livekit.io/frontends/) or with [telephony](https://docs.livekit.io/telephony/).
@@ -33,7 +34,7 @@ LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/
 lk docs search "testing my agent"
 ```
 
-See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup.
+The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing. See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill.
 
 ## Dev setup
 
@@ -80,7 +81,7 @@ The `lk agent console` and `lk agent dev` commands run your agent on your own ma
 lk agent console
 ```
 
-To connect it to LiveKit Cloud so a frontend or phone call can reach it:
+To connect it to LiveKit Cloud so a frontend, a phone call, or the [Agent Console](https://docs.livekit.io/testing/agent-console/) can reach it:
 
 ```console
 lk agent dev
@@ -108,7 +109,7 @@ Pair the agent with a prebuilt frontend starter, or add telephony:
 
 For more options, see the [frontend guide](https://docs.livekit.io/frontends/).
 
-## Tests and evals
+## Testing and debugging
 
 Simulations run full multi-turn conversations between a simulated user and your agent on LiveKit Cloud, then judge each transcript. The scenarios live in [`scenarios.yaml`](scenarios.yaml). Run them locally with the CLI:
 
@@ -116,9 +117,11 @@ Simulations run full multi-turn conversations between a simulated user and your
 lk agent simulate --scenarios scenarios.yaml
 ```
 
-The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/agents/start/testing/simulations/) for how to write scenarios and read results.
+The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/testing/simulations/) for how to write scenarios and read results.
 
-For turn-level checks that don't need a live session, the LiveKit Agents [testing and evaluation framework](https://docs.livekit.io/agents/start/testing/) runs your agent in-process under `vitest`. [`src/agent.test.ts`](src/agent.test.ts) has a commented-out example.
+For turn-level checks that don't need a live session, the LiveKit Agents [unit testing framework](https://docs.livekit.io/testing/unit-tests/) runs your agent in-process under `vitest`. [`src/agent.test.ts`](src/agent.test.ts) has a commented-out example.
+
+To debug a running agent, open it in the [Agent Console](https://docs.livekit.io/testing/agent-console/). It shows events, tool calls, and model timing as you talk to the agent. To stream logs from a deployed agent, run `lk agent logs`.
 
 ## Using this template for your own project
 

From 8420e495f2e755bd8c86b5c4769e94de6d9b06ae Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 23 Sep 2026 20:30:37 +0000
Subject: [PATCH 5/8] Restore the get-page example alongside search

Search returns short excerpts, so reading a result means fetching the
full page. Show both commands in the README, and tell coding agents in
AGENTS.md to fetch the page before acting on a search result.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 AGENTS.md | 2 +-
 README.md | 3 ++-
 2 files changed, 3 insertions(+), 2 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index e01beca..3e38aa6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -22,7 +22,7 @@ Install or update the CLI:
 - **Linux:** `curl -sSL https://get.livekit.io/cli | bash`
 - **Windows:** `winget install LiveKit.LiveKitCLI` (update: `winget upgrade LiveKit.LiveKitCLI`)
 
-Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs <command> --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code.
+Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs <command> --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code. Search results are short excerpts, so fetch the full page with `lk docs get-page` before you act on one.
 
 ### LiveKit docs MCP server
 
diff --git a/README.md b/README.md
index 9ea7496..a115c37 100644
--- a/README.md
+++ b/README.md
@@ -28,10 +28,11 @@ The starter works with any [custom web or mobile frontend](https://docs.livekit.
 
 This project works with coding agents like [Claude Code](https://claude.com/product/claude-code), [Cursor](https://www.cursor.com/), and [Codex](https://openai.com/codex/).
 
-LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) for browsing and searching its documentation. For example:
+LiveKit offers both a CLI and an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) for browsing and searching its documentation. Search returns short excerpts, so fetch the full page to read the details:
 
 ```console
 lk docs search "testing my agent"
+lk docs get-page /testing/unit-tests
 ```
 
 The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing. See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill.

From 8dcb92eee56cede1921af58270758f66f10e2660 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 24 Sep 2026 16:51:53 +0000
Subject: [PATCH 6/8] Add the agent debugger to the README and AGENTS.md

`lk agent debugger` shipped in CLI 2.18.8: it runs the agent in text mode
and lets a coding agent or script drive one turn at a time, printing the
tool calls and handoffs behind each reply.

README lists it under "Run the agent" and raises the CLI floor to 2.18.8.
AGENTS.md adapts the snippet from the coding agents guide so the agent
tries every change with the debugger, and the debugging checklist now
starts from reproducing the problem there. Agent Console stays the answer
for speech issues the text-only debugger cannot show.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 AGENTS.md | 11 +++++++----
 README.md | 14 +++++++++++---
 2 files changed, 18 insertions(+), 7 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3e38aa6..1049dd6 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,15 +48,18 @@ For turn-level checks that don't need a live session, use the in-process [unit t
 
 Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent.
 
+After changing the agent, try it with the [agent debugger](https://docs.livekit.io/testing/debugger/) (CLI 2.18.8 or later) before calling the change done. Start the agent with `lk agent debugger start`, send user turns with `lk agent debugger say "..."`, and read the tool calls in each turn as well as the reply. Run `lk agent debugger restart` after every code edit, since a running session keeps the old code, and `lk agent debugger stop` when you're done.
+
 ## Debugging
 
 To investigate unexpected agent behavior:
 
-- Reproduce it in a unit test or simulation scenario first, so you have a repeatable case to iterate against.
-- Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent.
+- Reproduce it with `lk agent debugger`: send the turns that trigger the problem and read the tool calls and errors in each one. Add `--logs` to `say` to see log lines, including tracebacks, next to the turn that produced them.
+- Add a unit test or simulation scenario once it's fixed, so a later change can't bring it back unnoticed.
+- Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent connected to LiveKit Cloud.
 - Run `lk agent logs` to stream logs from a deployed agent.
-- Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/), which shows events, tool calls, and model timing for a live session.
-- For sessions with real users, check [Agent Observability](https://docs.livekit.io/testing/observability/) for transcripts, traces, logs, and recordings.
+- Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/) for speech problems such as turn-taking, interruptions, or transcription, which the text-only debugger can't show. It shows events, tool calls, and model timing for a live session.
+- Check [Agent Observability](https://docs.livekit.io/testing/observability/) for transcripts, traces, logs, and recordings of sessions with real users.
 
 ## Feature parity with the Python SDK
 
diff --git a/README.md b/README.md
index a115c37..fbf6888 100644
--- a/README.md
+++ b/README.md
@@ -35,11 +35,11 @@ lk docs search "testing my agent"
 lk docs get-page /testing/unit-tests
 ```
 
-The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing. See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill.
+The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing, and tries its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill.
 
 ## Dev setup
 
-Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.15.0 or later:
+Install the [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/), version 2.18.8 or later:
 
 - **macOS:** `brew install livekit-cli`
 - **Linux:** `curl -sSL https://get.livekit.io/cli | bash`
@@ -76,7 +76,7 @@ lk app env --write --destination .env.local
 
 ## Run the agent
 
-The `lk agent console` and `lk agent dev` commands run your agent on your own machine. To talk to it in your terminal:
+The `lk agent console`, `lk agent dev`, and `lk agent debugger` commands run your agent on your own machine. To talk to it in your terminal:
 
 ```console
 lk agent console
@@ -88,6 +88,14 @@ To connect it to LiveKit Cloud so a frontend, a phone call, or the [Agent Consol
 lk agent dev
 ```
 
+To let a coding agent or a script test it one text turn at a time, use the [agent debugger](https://docs.livekit.io/testing/debugger/). Each turn prints the agent's reply along with the tool calls and handoffs behind it:
+
+```console
+lk agent debugger start
+lk agent debugger say "Hi, what can you do?"
+lk agent debugger stop
+```
+
 In production, run the agent directly:
 
 ```console

From 3af522611f16401ab81f4d9302823275698aeaf5 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Thu, 24 Sep 2026 21:47:15 +0000
Subject: [PATCH 7/8] Apply Jason's AGENTS.md review round, and point testing
 at the debugger

- Say the starter, not the SDK, is designed to run in LiveKit Cloud.
- Drop the lk docs intro, the command list, and the MCP transport
  details; running lk docs shows the help.
- Widen docs feedback to any LiveKit problem, keeping the to-do-list
  timing that has worked well.
- Stop advertising the unit testing framework. Scenarios are the tests,
  and the debugger is the loop for checking each change; the README
  testing section points there too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 AGENTS.md | 22 +++++++++-------------
 README.md |  2 +-
 2 files changed, 10 insertions(+), 14 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 1049dd6..ec647db 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This is a LiveKit Agents project. LiveKit Agents is a Node.js SDK for building voice AI agents, and this project is designed for LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem.
+This is a LiveKit Agents project. LiveKit Agents is a Node.js SDK for building voice AI agents. This starter is designed to run in LiveKit Cloud. See @README.md for more about the rest of the LiveKit ecosystem.
 
 ## Tooling
 
@@ -10,27 +10,25 @@ Be sure to maintain code formatting, using `pnpm format` and `pnpm lint`.
 
 ## LiveKit documentation
 
-LiveKit Agents changes quickly, and its documentation is updated often. Always refer to the latest documentation when working with this project. LiveKit offers both a CLI and an MCP server for browsing and searching its documentation. If the developer hasn't installed the CLI yet, recommend that they install it.
+Always refer to the latest documentation when working with this project. LiveKit offers both a CLI (`lk docs`) and an MCP server for browsing and searching its documentation.
 
 ### LiveKit CLI
 
-The [LiveKit CLI](https://docs.livekit.io/intro/basics/cli/) `lk docs` subcommand gives full access to LiveKit documentation from the terminal. It requires CLI version 2.15.0 or later. Check with `lk --version`.
-
 Install or update the CLI:
 
 - **macOS:** `brew install livekit-cli` (update: `brew update && brew upgrade livekit-cli`)
 - **Linux:** `curl -sSL https://get.livekit.io/cli | bash`
 - **Windows:** `winget install LiveKit.LiveKitCLI` (update: `winget upgrade LiveKit.LiveKitCLI`)
 
-Run `lk docs --help` to see all available commands. Key commands: `lk docs overview`, `lk docs search`, `lk docs get-page`, `lk docs code-search`, `lk docs changelog`, and `lk docs submit-feedback`. Run `lk docs <command> --help` before using a command for the first time, because the help text explains how to use it and how to interpret results. Prefer browsing (`overview`, `get-page`) over search, and prefer `search` over `code-search`, because docs pages are more current and give better context than raw code. Search results are short excerpts, so fetch the full page with `lk docs get-page` before you act on one.
+Run `lk docs` before your first docs lookup. Its help text explains how to use each command and how to interpret results.
 
 ### LiveKit docs MCP server
 
-For deeper IDE integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/) with the same documentation access. It uses Streamable HTTP transport at `https://docs.livekit.io/mcp`. See your IDE's documentation for how to add it.
+For deeper coding agent integration, LiveKit also offers an [MCP server](https://docs.livekit.io/reference/developer-tools/docs-mcp/).
 
-### Submit docs feedback to LiveKit
+### Submit feedback to LiveKit
 
-If you use the LiveKit CLI or MCP server to search or browse documentation, also submit constructive feedback to LiveKit with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool. Add this to your to-do list when planning work, so you file feedback after completing your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, or any other gap or issue in the docs.
+When you run into any problem with LiveKit, add it to your to-do list, then submit it with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool once you finish your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, broken features or implementations, and any other gap or issue in the LiveKit ecosystem.
 
 ## LiveKit Agents skill
 
@@ -42,11 +40,9 @@ Voice AI agents are highly sensitive to latency. Design complex agents in a stru
 
 ## Testing
 
-When possible, add tests for agent behavior. Add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. The scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them.
-
-For turn-level checks that don't need a live session, use the in-process [unit testing framework](https://docs.livekit.io/testing/unit-tests/). `src/agent.test.ts` has a commented-out example. Run those tests with `pnpm test`.
+To keep agent behavior from regressing, add a scenario to `scenarios.yaml` and run it with `lk agent simulate --scenarios scenarios.yaml`. Make sure the scenarios run in CI on every merge to `main`. Read the [simulations documentation](https://docs.livekit.io/testing/simulations/) before editing them.
 
-Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Use test-driven development (TDD) and start by writing tests for the desired behavior. For example, if you're adding a tool, write one or more tests for the tool's behavior, then iterate on the tool until the tests pass. This is how you produce a working, reliable agent.
+Important: when you modify core agent behavior such as instructions, tool descriptions, or tasks, workflows, and handoffs, never guess at what works. Start by writing a scenario for the desired behavior. For example, if you're adding a tool, write a scenario that exercises it, then iterate on the tool until the scenario passes. This is how you produce a working, reliable agent.
 
 After changing the agent, try it with the [agent debugger](https://docs.livekit.io/testing/debugger/) (CLI 2.18.8 or later) before calling the change done. Start the agent with `lk agent debugger start`, send user turns with `lk agent debugger say "..."`, and read the tool calls in each turn as well as the reply. Run `lk agent debugger restart` after every code edit, since a running session keeps the old code, and `lk agent debugger stop` when you're done.
 
@@ -55,7 +51,7 @@ After changing the agent, try it with the [agent debugger](https://docs.livekit.
 To investigate unexpected agent behavior:
 
 - Reproduce it with `lk agent debugger`: send the turns that trigger the problem and read the tool calls and errors in each one. Add `--logs` to `say` to see log lines, including tracebacks, next to the turn that produced them.
-- Add a unit test or simulation scenario once it's fixed, so a later change can't bring it back unnoticed.
+- Add a simulation scenario once it's fixed, so a later change can't bring it back unnoticed.
 - Run `lk agent dev --log-level DEBUG` for verbose logs from a local agent connected to LiveKit Cloud.
 - Run `lk agent logs` to stream logs from a deployed agent.
 - Ask the developer to open the [Agent Console](https://docs.livekit.io/testing/agent-console/) for speech problems such as turn-taking, interruptions, or transcription, which the text-only debugger can't show. It shows events, tool calls, and model timing for a live session.
diff --git a/README.md b/README.md
index fbf6888..0d8970a 100644
--- a/README.md
+++ b/README.md
@@ -128,7 +128,7 @@ lk agent simulate --scenarios scenarios.yaml
 
 The `Simulations` workflow in [`.github/workflows/simulations.yml`](.github/workflows/simulations.yml) runs the same file on every merge to `main`, and on demand from the Actions tab. It doesn't run on every pull request push because each run uses real inference. See the [simulations guide](https://docs.livekit.io/testing/simulations/) for how to write scenarios and read results.
 
-For turn-level checks that don't need a live session, the LiveKit Agents [unit testing framework](https://docs.livekit.io/testing/unit-tests/) runs your agent in-process under `vitest`. [`src/agent.test.ts`](src/agent.test.ts) has a commented-out example.
+To check a change turn by turn without a live session, use the [agent debugger](https://docs.livekit.io/testing/debugger/) shown in [Run the agent](#run-the-agent).
 
 To debug a running agent, open it in the [Agent Console](https://docs.livekit.io/testing/agent-console/). It shows events, tool calls, and model timing as you talk to the agent. To stream logs from a deployed agent, run `lk agent logs`.
 

From c85ade1f52a42daced6fc1bcd17d9e6c3328073c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Fri, 25 Sep 2026 02:55:29 +0000
Subject: [PATCH 8/8] Describe the seven bundled agent skills, not
 livekit-agents

The skills PR replaces the single livekit-agents skill with seven
focused ones, so the fallback path to its SKILL.md would no longer exist.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01U7yszNU7t5aCHJsKLmU4hv
---
 AGENTS.md | 4 ++--
 README.md | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index ec647db..fcb2a0a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -30,9 +30,9 @@ For deeper coding agent integration, LiveKit also offers an [MCP server](https:/
 
 When you run into any problem with LiveKit, add it to your to-do list, then submit it with `lk docs submit-feedback` or the MCP `submit_docs_feedback` tool once you finish your other tasks. Useful feedback includes incomplete documentation, broken examples, missing steps, broken features or implementations, and any other gap or issue in the LiveKit ecosystem.
 
-## LiveKit Agents skill
+## LiveKit agent skills
 
-This project includes the `livekit-agents` skill in `.claude/skills/` and `.agents/skills/`. It covers how to approach agent architecture, workflows, handoffs, tasks, and testing, and it defers to the live documentation for API details. If your tool doesn't load skills automatically, read `.agents/skills/livekit-agents/SKILL.md` before you design or restructure an agent.
+This project includes LiveKit's agent skills in `.claude/skills/` and `.agents/skills/`, one for each stage of the work: reading the docs, building, debugging, testing, writing scenarios, running simulations, and operating in production. They defer to the live documentation for API details. If your tool doesn't load skills automatically, read the matching `.agents/skills/<name>/SKILL.md` before you start that kind of task.
 
 ## Handoffs ("workflows")
 
diff --git a/README.md b/README.md
index 0d8970a..3b8c9cc 100644
--- a/README.md
+++ b/README.md
@@ -35,7 +35,7 @@ lk docs search "testing my agent"
 lk docs get-page /testing/unit-tests
 ```
 
-The project also includes an [`AGENTS.md`](AGENTS.md) file and the LiveKit Agents [skill](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing, and tries its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill.
+The project also includes an [`AGENTS.md`](AGENTS.md) file and LiveKit's [agent skills](https://docs.livekit.io/intro/coding-agents/#agent-skills), so your coding agent follows LiveKit's best practices for workflows, handoffs, and testing, and tries its changes with the [agent debugger](https://docs.livekit.io/testing/debugger/). See the [coding agents guide](https://docs.livekit.io/intro/coding-agents/) for more details, including MCP server setup and how to update the skill.
 
 ## Dev setup