From 27381fefcfa2415f055ca68dee16125005d35369 Mon Sep 17 00:00:00 2001
From: Ben Weeks <ben@agora.io>
Date: Thu, 16 Apr 2026 11:48:36 +0100
Subject: [PATCH 1/4] docs: add progressive disclosure documentation

add L0 repo card, 8 L1 structured summaries, 3 L2 deep dives,
and AGENTS.md entry point following the progressive disclosure standard
---
 AGENTS.md                                     |  41 ++++++
 CLAUDE.md                                     |   2 +
 docs/ai/L0_repo_card.md                       |  27 ++++
 docs/ai/L1/01_setup.md                        |  91 ++++++++++++
 docs/ai/L1/02_architecture.md                 | 106 ++++++++++++++
 docs/ai/L1/03_code_map.md                     |  83 +++++++++++
 docs/ai/L1/04_conventions.md                  |  93 +++++++++++++
 docs/ai/L1/05_workflows.md                    |  92 +++++++++++++
 docs/ai/L1/06_interfaces.md                   | 130 ++++++++++++++++++
 docs/ai/L1/07_gotchas.md                      |  84 +++++++++++
 docs/ai/L1/08_security.md                     |  81 +++++++++++
 docs/ai/L1/deep_dives/_index.md               |   7 +
 docs/ai/L1/deep_dives/build_pipeline.md       |  64 +++++++++
 docs/ai/L1/deep_dives/event_system.md         |  78 +++++++++++
 docs/ai/L1/deep_dives/rendering_controller.md |  72 ++++++++++
 15 files changed, 1051 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 docs/ai/L0_repo_card.md
 create mode 100644 docs/ai/L1/01_setup.md
 create mode 100644 docs/ai/L1/02_architecture.md
 create mode 100644 docs/ai/L1/03_code_map.md
 create mode 100644 docs/ai/L1/04_conventions.md
 create mode 100644 docs/ai/L1/05_workflows.md
 create mode 100644 docs/ai/L1/06_interfaces.md
 create mode 100644 docs/ai/L1/07_gotchas.md
 create mode 100644 docs/ai/L1/08_security.md
 create mode 100644 docs/ai/L1/deep_dives/_index.md
 create mode 100644 docs/ai/L1/deep_dives/build_pipeline.md
 create mode 100644 docs/ai/L1/deep_dives/event_system.md
 create mode 100644 docs/ai/L1/deep_dives/rendering_controller.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..69f76a8
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# AI Agent Instructions
+
+This repository uses progressive disclosure documentation. Docs live under
+`docs/ai/` in three levels.
+
+## How to Load
+
+1. Read [docs/ai/L0_repo_card.md](docs/ai/L0_repo_card.md) to identify the repo.
+2. Load ALL 8 files in `docs/ai/L1/`. They are small — load all upfront.
+3. Follow L2 deep-dive links only when L1 isn't detailed enough.
+
+## Git Conventions
+
+### Commit messages — conventional commits
+
+- **Format:** `type: description` or `type(scope): description`
+- **Types:** `feat:` (new feature), `fix:` (bug fix), `chore:` (maintenance, version bumps), `test:` (test additions/changes), `docs:` (documentation)
+- **Scoped variant:** `feat(scope):`, `fix(scope):` — e.g. `feat(auth): add token refresh`
+- **Lowercase after prefix** — `feat: add feature`, not `feat: Add feature`
+- **Present tense** — "add feature", not "added feature"
+
+### Branch names
+
+- **Format:** `type/short-description` — lowercase, hyphen-separated
+- **Types match commit types:** `feat/`, `fix/`, `chore/`, `test/`, `docs/`
+- **Examples:** `feat/token-refresh`, `fix/null-pointer`, `docs/progressive-disclosure`
+
+### General rules
+
+- **No AI tool names** — never mention claude, cursor, copilot, cody, aider, gemini, codex, chatgpt, or gpt-3/4
+- **No Co-Authored-By trailers** — omit AI attribution lines
+- **No --no-verify** — let git hooks run normally
+- **No git config changes** — do not modify user.name or user.email
+
+## Doc Commands
+
+| Command       | When to use                                   |
+| ------------- | --------------------------------------------- |
+| generate docs | no `docs/ai/` directory exists yet            |
+| update docs   | code changed since last `last_reviewed` date  |
+| test docs     | verify docs give agents the right context     |
diff --git a/CLAUDE.md b/CLAUDE.md
index b596914..9f09612 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,7 @@
 # CLAUDE.md
 
+Read @AGENTS.md for AI agent instructions, git conventions, and progressive disclosure docs.
+
 Guidelines for AI-assisted development in this repository.
 
 ## Package manager
diff --git a/docs/ai/L0_repo_card.md b/docs/ai/L0_repo_card.md
new file mode 100644
index 0000000..7aab8fe
--- /dev/null
+++ b/docs/ai/L0_repo_card.md
@@ -0,0 +1,27 @@
+# agora-agent-client-toolkit — Repo Card
+
+> Framework-agnostic TypeScript SDK for integrating Agora Conversational AI into web applications, with optional React hooks.
+
+## Identity
+
+| Field         | Value                                              |
+| ------------- | -------------------------------------------------- |
+| Repo          | `AgoraIO-Conversational-AI/agent-client-toolkit-ts` |
+| Type          | `sdk-library`                                      |
+| Language      | TypeScript                                         |
+| Deploy Target | npm registry (CJS + ESM)                           |
+| Owner         | Agora Conversational AI                            |
+| Last Reviewed | 2026-04-16                                         |
+
+## L1 — Summaries
+
+| File                                     | Purpose                                              | Audience       |
+| ---------------------------------------- | ---------------------------------------------------- | -------------- |
+| [01_setup](L1/01_setup.md)               | Environment setup, quick commands, env vars          | Use & Maintain |
+| [02_architecture](L1/02_architecture.md) | System design, component diagram, data flow          | Maintain       |
+| [03_code_map](L1/03_code_map.md)         | Directory tree, module map, "where does X live?"     | Maintain       |
+| [04_conventions](L1/04_conventions.md)   | Naming, patterns, error handling, testing            | Maintain       |
+| [05_workflows](L1/05_workflows.md)       | Step-by-step: add feature, release, test             | Use            |
+| [06_interfaces](L1/06_interfaces.md)     | API contracts, event schemas, message formats        | Use & Maintain |
+| [07_gotchas](L1/07_gotchas.md)           | Critical gotchas, tribal knowledge, incident lessons | Maintain       |
+| [08_security](L1/08_security.md)         | Security model, trust boundaries, auth, secrets      | Maintain       |
diff --git a/docs/ai/L1/01_setup.md b/docs/ai/L1/01_setup.md
new file mode 100644
index 0000000..b9eb8a2
--- /dev/null
+++ b/docs/ai/L1/01_setup.md
@@ -0,0 +1,91 @@
+# 01 Setup
+
+> Environment setup, dependencies, build commands, and local development for the toolkit monorepo.
+
+## Prerequisites
+
+| Requirement | Version   | Notes                            |
+| ----------- | --------- | -------------------------------- |
+| Node.js     | ≥20       | CI tests on 20, 22, 24          |
+| pnpm        | ≥9        | Only supported package manager   |
+
+- npm and yarn lockfiles are rejected; pnpm only
+- No `.env` files required — this is a library, not a service
+
+## Install and Build
+
+```bash
+pnpm install
+pnpm build          # builds both core and react packages
+```
+
+## Quick Commands
+
+| Command              | What It Does                                    |
+| -------------------- | ----------------------------------------------- |
+| `pnpm install`       | Install all workspace dependencies              |
+| `pnpm build`         | Build core + react packages (tsup)              |
+| `pnpm test`          | Run all tests (vitest)                          |
+| `pnpm lint`          | Run ESLint across all packages                  |
+| `pnpm format`        | Run Prettier across all packages                |
+| `pnpm format:check`  | Check Prettier formatting without writing       |
+| `pnpm typecheck`     | Type-check all packages                         |
+
+## Package Manager
+
+- **pnpm only** — workspace uses `pnpm-workspace.yaml`
+- Workspaces: `packages/*` and `apps/*`
+- The `packages/conversational-ai` package references source in root `src/` (no source duplication)
+
+## Build System
+
+- **tsup** — bundles both packages to CJS + ESM + type declarations
+- Output: `dist/index.js`, `dist/index.mjs`, `dist/index.d.ts`, `dist/index.d.mts`
+- Tree-shakeable (`sideEffects: false`)
+
+## Running Demo Apps
+
+```bash
+cd apps/demo && pnpm dev        # Vanilla TS demo (Vite)
+cd apps/playground && pnpm dev  # React playground
+```
+
+Both apps require valid Agora App ID and token — see their respective README files.
+
+## CI Pipeline
+
+- GitHub Actions: `.github/workflows/ci.yml`
+- Matrix: Node 20, 22, 24 on Ubuntu
+- Steps: lint → format check → build → typecheck → test → coverage (Node 20 only)
+- Publish: triggered by tag push; publishes both packages to npm with provenance
+
+## Package Filter Names
+
+| Filter Name                          | Resolves To              |
+| ------------------------------------ | ------------------------ |
+| `agora-agent-client-toolkit`         | Core SDK package         |
+| `agora-agent-client-toolkit-react`   | React hooks package      |
+| `agora-conversational-ai-demo`       | Vanilla TS demo app      |
+
+Use with `pnpm --filter <name> <script>` to target a specific package.
+
+## Peer Dependencies (for consuming apps)
+
+| Package              | Version   | Required? |
+| -------------------- | --------- | --------- |
+| `agora-rtc-sdk-ng`   | ≥4.23.4   | Yes       |
+| `agora-rtm`          | ≥2.0.0    | Optional  |
+| `react`              | ≥18       | React only |
+| `agora-rtc-react`    | ≥2.0      | React only |
+
+## Common Setup Issues
+
+- **Wrong package manager** — `npm install` or `yarn install` will fail; use `pnpm install`
+- **Node version too low** — Node 18 may work but is not tested; use ≥20
+- **Missing peer deps in apps** — demo apps need `agora-rtc-sdk-ng` installed separately
+- **Workspace protocol errors** — if you see `workspace:*` resolution errors, run `pnpm install` from repo root
+- **Build order matters** — core package must build before react package; `pnpm build` handles this automatically
+
+## Related Deep Dives
+
+- [Build Pipeline](deep_dives/build_pipeline.md) — Multi-target builds, workspace structure, publish workflow
diff --git a/docs/ai/L1/02_architecture.md b/docs/ai/L1/02_architecture.md
new file mode 100644
index 0000000..3fd310f
--- /dev/null
+++ b/docs/ai/L1/02_architecture.md
@@ -0,0 +1,106 @@
+# 02 Architecture
+
+> System design overview: singleton lifecycle, event-driven rendering, and structural typing for Agora RTC/RTM integration.
+
+## High-Level Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                         User Application                            │
+│  (Vanilla JS / React / any framework)                               │
+└──────────┬────────────────────────────────────┬─────────────────────┘
+           │                                    │
+    ┌──────▼──────────┐              ┌──────────▼──────────┐
+    │  Core SDK        │              │  React Package       │
+    │  agora-agent-    │◄─────────────│  agora-agent-        │
+    │  client-toolkit  │  wraps       │  client-toolkit-     │
+    │                  │              │  react                │
+    └──────┬──────────┘              └─────────────────────┘
+           │
+    ┌──────▼──────────────────────────────────────────────┐
+    │                  AgoraVoiceAI (singleton)            │
+    │                                                      │
+    │  ┌─────────────┐  ┌──────────────┐  ┌────────────┐ │
+    │  │ Chunked      │  │ SubRender    │  │ Event      │ │
+    │  │ Message      │  │ Controller   │  │ Helper     │ │
+    │  │ Assembler    │  │ (TEXT/WORD/  │  │ (typed     │ │
+    │  │              │  │  CHUNK/AUTO) │  │  emitter)  │ │
+    │  └──────┬───────┘  └──────┬──────┘  └─────┬──────┘ │
+    └─────────┼─────────────────┼────────────────┼────────┘
+              │                 │                │
+    ┌─────────▼─────────────────▼────────────────▼────────┐
+    │          Agora Peer SDKs (structural contracts)      │
+    │  ┌──────────────┐          ┌──────────────┐         │
+    │  │ RTCEngine    │          │ RTMEngine    │         │
+    │  │ (required)   │          │ (optional)   │         │
+    │  └──────────────┘          └──────────────┘         │
+    └─────────────────────────────────────────────────────┘
+```
+
+## Package Structure
+
+| Package                            | Purpose                           | Dependencies          |
+| ---------------------------------- | --------------------------------- | --------------------- |
+| `agora-agent-client-toolkit`       | Core SDK — framework-agnostic     | Zero runtime deps     |
+| `agora-agent-client-toolkit-react` | React hooks wrapping core SDK     | Peer: react, core SDK |
+
+- Core package is usable standalone (Vanilla JS, Vue, Angular, etc.)
+- React package adds hooks and context; depends on core via workspace protocol
+
+## Singleton Lifecycle
+
+```
+init(config) ──► getInstance() ──► subscribeMessage(channel)
+                                          │
+                                   binds RTC listeners
+                                   binds RTM listeners (if present)
+                                   starts SubRenderController
+                                          │
+                                   ◄── events flow ──►
+                                          │
+                              unsubscribe() ──► destroy()
+```
+
+- `init()` is async; validates engine shape in dev mode
+- Calling `init()` while already initializing waits for first, then re-inits
+- `destroy()` is idempotent; resets singleton to null
+
+## Message Processing Pipeline
+
+```
+RTC stream-message ──► ChunkedMessageAssembler.assemble()
+                              │ (reassembles multi-part messages)
+                              ▼
+                       CovSubRenderController.handleMessage()
+                              │ (TEXT/WORD/CHUNK/AUTO mode)
+                              ▼
+                       SubRenderQueue (manages history)
+                              │
+                              ▼
+                       emit TRANSCRIPT_UPDATED
+```
+
+## Agent State Flow
+
+```
+RTM presence event ──► AgoraVoiceAI._handleRtmPresence()
+                              │
+                              ▼
+                       CovSubRenderController.handleAgentStatus()
+                              │
+                              ▼
+                       emit AGENT_STATE_CHANGED
+```
+
+## Key Design Decisions
+
+- **Structural typing** — RTC/RTM engines matched by method shape, not by importing peer SDK types; eliminates version coupling
+- **Optional RTM** — RTC-only mode works for receive-only use cases; RTM adds send/interrupt/state
+- **Pre-bound handlers** — event handlers stored as instance fields for reliable unbinding
+- **Callback wrapping** — each listener wrapped in try/catch so one error does not crash others
+- **Optional dependencies** — `@agora-js/report` and `jszip` dynamically imported with fallback
+
+## Related Deep Dives
+
+- [Rendering Controller](deep_dives/rendering_controller.md) — TEXT/WORD/CHUNK modes, PTS timing, queue system
+- [Event System](deep_dives/event_system.md) — Event types, listener management, error routing
diff --git a/docs/ai/L1/03_code_map.md b/docs/ai/L1/03_code_map.md
new file mode 100644
index 0000000..94da359
--- /dev/null
+++ b/docs/ai/L1/03_code_map.md
@@ -0,0 +1,83 @@
+# 03 Code Map
+
+> Directory structure, module responsibilities, and where to find things in the monorepo.
+
+## Top-Level Layout
+
+```
+repo-root/
+├── src/                          # Core SDK source (canonical)
+│   ├── core/                     # Singleton, config, types, events
+│   ├── rendering/                # Transcript rendering controller
+│   ├── messaging/                # Chunked message assembly
+│   ├── utils/                    # Debug logging, metrics reporters
+│   └── index.ts                  # Public export barrel
+├── packages/
+│   ├── conversational-ai/        # Core package (build config only)
+│   │   ├── __tests__/            # Core tests
+│   │   ├── __typetests__/        # Type-level tests
+│   │   ├── tsup.config.ts
+│   │   ├── vitest.config.ts
+│   │   └── package.json
+│   └── react/                    # React hooks package
+│       ├── src/                  # React source
+│       ├── __tests__/            # React tests
+│       ├── tsup.config.ts
+│       ├── vitest.config.ts
+│       └── package.json
+├── apps/
+│   ├── demo/                     # Vanilla TS demo (Vite)
+│   └── playground/               # React playground
+├── .github/workflows/ci.yml     # CI pipeline
+├── pnpm-workspace.yaml          # Workspace config
+└── package.json                  # Root workspace scripts
+```
+
+## Core SDK Modules (`src/`)
+
+| File                              | Responsibility                                          | Lines | Risk   |
+| --------------------------------- | ------------------------------------------------------- | ----- | ------ |
+| `core/conversational-ai.ts`      | `AgoraVoiceAI` singleton — lifecycle, RTC/RTM binding   | ~850  | High   |
+| `core/types.ts`                   | All type definitions, enums, error classes               | ~350  | Medium |
+| `core/events.ts`                  | `EventHelper` base class, event type definitions         | ~150  | Medium |
+| `core/config.ts`                  | Configuration types and defaults                         | ~90   | Low    |
+| `rendering/sub-render.ts`         | `CovSubRenderController` — transcript rendering          | ~740  | High   |
+| `rendering/sub-render-queue.ts`   | `SubRenderQueue` — chat history and queue management     | ~570  | High   |
+| `rendering/sub-render-pts.ts`     | `SubRenderPTS` — PTS-based word timing                   | ~100  | High   |
+| `messaging/chunked.ts`            | `ChunkedMessageAssembler` — multi-part message assembly  | ~200  | Medium |
+| `utils/debug.ts`                  | Debug logging utilities                                  | ~50   | Low    |
+| `utils/metrics.ts`                | Metrics reporters (Console + optional Agora)             | ~80   | Low    |
+| `index.ts`                        | Public export barrel                                     | ~60   | Low    |
+
+## React Package (`packages/react/src/`)
+
+| File                           | Responsibility                                      |
+| ------------------------------ | --------------------------------------------------- |
+| `use-conversational-ai.ts`     | Flagship hook — init, subscribe, event handling      |
+| `context.ts`                   | `ConversationalAIProvider` + standalone hooks         |
+| `use-transcript.ts`            | Standalone transcript hook (reads from context)      |
+| `use-agent-state.ts`           | Standalone agent state hook                          |
+| `use-agent-metrics.ts`         | Standalone metrics hook                              |
+| `index.ts`                     | Public export barrel                                 |
+
+## Key Observation
+
+- **Source lives in root `src/`** — the `packages/conversational-ai/` directory has build config and tests but no source files
+- This means the core package's `tsup.config.ts` points to `../../src/index.ts` as entry
+
+## Core Files by Task
+
+| Task                              | Start Here                                |
+| --------------------------------- | ----------------------------------------- |
+| Add a new event type              | `src/core/events.ts` + `src/core/types.ts` |
+| Modify transcript rendering       | `src/rendering/sub-render.ts`             |
+| Change message parsing            | `src/messaging/chunked.ts`                |
+| Add a React hook                  | `packages/react/src/`                     |
+| Update public API                 | `src/index.ts` + package `index.ts`       |
+| Add a new config option           | `src/core/config.ts` + `src/core/types.ts` |
+| Fix singleton lifecycle           | `src/core/conversational-ai.ts`           |
+| Update CI pipeline                | `.github/workflows/ci.yml`                |
+
+## Related Deep Dives
+
+- [Build Pipeline](deep_dives/build_pipeline.md) — How source maps to packages, dual CJS/ESM output
diff --git a/docs/ai/L1/04_conventions.md b/docs/ai/L1/04_conventions.md
new file mode 100644
index 0000000..bc6af12
--- /dev/null
+++ b/docs/ai/L1/04_conventions.md
@@ -0,0 +1,93 @@
+# 04 Conventions
+
+> Coding patterns, naming rules, error handling, and testing standards used across the toolkit.
+
+## TypeScript Rules
+
+- **Strict mode** — enforced across all packages
+- **No `any`** — use `unknown` with type guards instead
+- **No `@ts-ignore`** — except for documented unavoidable SDK private APIs
+- **Structural typing** — RTC/RTM engine contracts defined in toolkit (`RTCEngine`, `RTMEngine`), not imported from peer SDKs
+
+## Naming Conventions
+
+| Element             | Convention                   | Example                       |
+| ------------------- | ---------------------------- | ----------------------------- |
+| Classes             | PascalCase                   | `AgoraVoiceAI`                |
+| Interfaces/Types    | PascalCase                   | `RTCEngine`, `RTMConfig`      |
+| Enums               | PascalCase, UPPER_SNAKE vals | `AgentState.SPEAKING`         |
+| Methods (public)    | camelCase                    | `subscribeMessage()`          |
+| Methods (private)   | `_camelCase`                 | `_handleRtcStreamMessage()`   |
+| Event names         | UPPER_SNAKE_CASE             | `TRANSCRIPT_UPDATED`          |
+| Files               | kebab-case                   | `sub-render-queue.ts`         |
+| Test files           | `*.test.ts` / `*.test.tsx`  | `chunked.test.ts`             |
+
+## Module Organization
+
+- Exports concentrated in `index.ts` barrel files
+- Source in `src/`, tests in `__tests__/` (sibling to build config)
+- Type definitions centralized in `types.ts`
+- Type imports first, then regular imports
+
+## Error Handling
+
+- Custom errors extend `ConversationalAIError` base class
+- Error classes: `NotInitializedError`, `RTMRequiredError`
+- Descriptive messages include context (method name, trace ID)
+- Two event-based error channels:
+  - `AGENT_ERROR` — agent-side module failures (LLM, TTS, context)
+  - `MESSAGE_ERROR` — client-side RTM delivery failures
+  - Never conflate these; use separate handlers
+
+## Logging
+
+- Controlled by `enableLog` config flag (default: false)
+- Log levels: `NONE`, `ERRORS`, `DEBUG`
+- Lazy logging via `callMessagePrint()` guard — no string construction if logging disabled
+- Trace IDs attached for distributed tracing
+
+## Testing
+
+- **Framework:** vitest (jest-compatible syntax)
+- **Coverage thresholds (CI-enforced):**
+
+| Package | Lines | Functions | Branches |
+| ------- | ----- | --------- | -------- |
+| Core    | 40%   | 50%       | 65%      |
+| React   | 70%   | 70%       | 60%      |
+
+- React tests use `@testing-library/react`
+- Type-level tests in `__typetests__/` verify structural typing contracts
+
+## Performance Patterns
+
+- Pre-bound event handlers — stored as instance fields; avoids re-binding per event
+- Callback wrapping — each listener in try/catch for error isolation
+- Incremental transcript updates via queue system
+- Optional dependencies (`@agora-js/report`, `jszip`) loaded via dynamic import with try/catch
+
+## Code Style
+
+- **ESLint + Prettier** — enforced in CI
+- **JSDoc** — required on all public API methods with `@example`, `@remarks`, `@throws`
+- **No narrative prose in comments** — prefer self-documenting code; add comments only for non-obvious decisions
+
+## Structural Typing Pattern
+
+Engine contracts (`RTCEngine`, `RTMEngine`) are defined in the toolkit, not imported from peer SDKs:
+
+- Defined in `src/core/types.ts` — toolkit owns the contract shape
+- Apps pass their actual Agora SDK instances; TypeScript checks structural compatibility
+- This decouples the toolkit from specific peer SDK versions
+- Engine validation (method presence checks) runs in development mode only
+
+## Deprecation Pattern
+
+- Deprecated types are re-exported with `@deprecated` JSDoc tags
+- Example: `NotFoundError` is a deprecated alias for `NotInitializedError`
+- Migration guidance documented in `MIGRATION.md` per version
+- Breaking changes follow semver — major version bump required
+
+## Related Deep Dives
+
+- None
diff --git a/docs/ai/L1/05_workflows.md b/docs/ai/L1/05_workflows.md
new file mode 100644
index 0000000..69c9a4f
--- /dev/null
+++ b/docs/ai/L1/05_workflows.md
@@ -0,0 +1,92 @@
+# 05 Workflows
+
+> Step-by-step guides for common development tasks in the toolkit.
+
+## Add a New Event Type
+
+1. Define the event name in `src/core/events.ts` — add to `AgoraVoiceAIEvents` enum
+2. Add the handler signature to `AgoraVoiceAIEventHandlers` in `src/core/types.ts`
+3. Add the payload type to `src/core/types.ts`
+4. Emit the event in the appropriate handler in `src/core/conversational-ai.ts`
+5. Export any new types from `src/index.ts`
+6. If the event should be exposed in React, add a standalone hook in `packages/react/src/`
+7. Add tests in `packages/conversational-ai/__tests__/`
+
+## Add a New Config Option
+
+1. Add the field to `AgoraVoiceAIConfig` in `src/core/config.ts`
+2. Read it in `AgoraVoiceAI.init()` in `src/core/conversational-ai.ts`
+3. If React-specific, extend `UseConversationalAIConfig` in `packages/react/src/use-conversational-ai.ts`
+4. Document the option in README.md
+5. Add the type export to `src/index.ts` if a new type was created
+
+## Add a React Hook
+
+1. Create `packages/react/src/use-{name}.ts`
+2. Subscribe to the relevant `AgoraVoiceAI` event using `EventHelper.on()`
+3. Return typed state via React `useState`
+4. Export from `packages/react/src/index.ts`
+5. If it should work standalone (outside `useConversationalAI`), add context support in `packages/react/src/context.ts`
+6. Add tests in `packages/react/__tests__/`
+
+## Modify Message Parsing
+
+1. Edit `src/messaging/chunked.ts` — `ChunkedMessageAssembler.assemble()`
+2. Update wire format handling if message structure changed
+3. Run `pnpm test` — chunked tests cover edge cases extensively
+4. If the parsed object shape changed, update types in `src/core/types.ts`
+
+## Run Tests
+
+```bash
+pnpm test                              # all tests
+pnpm --filter conversational-ai test   # core tests only
+pnpm --filter react test               # react tests only
+```
+
+## Build and Verify
+
+```bash
+pnpm build           # build all packages
+pnpm typecheck       # verify type correctness
+pnpm lint            # check code quality
+pnpm format:check    # verify formatting
+```
+
+## Release a New Version
+
+1. Update version in `packages/conversational-ai/package.json` and `packages/react/package.json`
+2. Update `CHANGELOG.md` with changes
+3. Update `MIGRATION.md` if there are breaking changes
+4. Commit and tag: `git tag v{version}`
+5. Push tag — CI publishes to npm automatically
+6. CI creates GitHub Release with auto-generated notes
+
+## Add a Demo or Example
+
+1. Create directory under `apps/` or add to existing demo
+2. Add to `pnpm-workspace.yaml` if a new workspace
+3. Install peer deps: `agora-rtc-sdk-ng`, `agora-rtm` (optional)
+4. Reference core package via workspace protocol in `package.json`
+
+## Deprecate a Public API
+
+1. Add `@deprecated` JSDoc tag to the export in `src/core/types.ts` or relevant file
+2. Create a replacement API if applicable
+3. Re-export the deprecated symbol with the tag (do not remove yet)
+4. Document in `MIGRATION.md` with version and replacement instructions
+5. Remove the deprecated symbol in the next major version
+
+## Debug a Transcript Rendering Issue
+
+1. Enable debug logging: `enableLog: true` in config
+2. Check which render mode is active — `AUTO` infers from first message
+3. If WORD mode, verify `AgoraRTC.setParameter('ENABLE_AUDIO_PTS_METADATA', true)` was called before client creation
+4. Check browser console for `DEBUG_LOG` events
+5. Look for `turn_status` transitions: 0 (IN_PROGRESS) → 1 (END) or 2 (INTERRUPTED)
+6. If transcript is incomplete, check `ChunkedMessageAssembler` TTL (30s default) — slow networks may cause eviction
+
+## Related Deep Dives
+
+- [Build Pipeline](deep_dives/build_pipeline.md) — Publish workflow, dual CJS/ESM output
+- [Rendering Controller](deep_dives/rendering_controller.md) — Transcript mode debugging
diff --git a/docs/ai/L1/06_interfaces.md b/docs/ai/L1/06_interfaces.md
new file mode 100644
index 0000000..1b8bece
--- /dev/null
+++ b/docs/ai/L1/06_interfaces.md
@@ -0,0 +1,130 @@
+# 06 Interfaces
+
+> Public API surface, engine contracts, event schemas, and message wire formats.
+
+## Public API — Core Package
+
+### AgoraVoiceAI (singleton)
+
+| Method                            | Returns            | Notes                          |
+| --------------------------------- | ------------------ | ------------------------------ |
+| `init(config)`                    | `Promise<void>`    | Async; validates engines in dev |
+| `getInstance()`                   | `AgoraVoiceAI`     | Throws `NotInitializedError`   |
+| `subscribeMessage(channel)`       | `void`             | Binds RTC/RTM listeners        |
+| `unsubscribe()`                   | `void`             | Unbinds listeners              |
+| `destroy()`                       | `void`             | Idempotent; resets singleton   |
+| `chat(agentUserId, message)`      | `Promise<void>`    | Dispatches to send methods     |
+| `sendText(agentUserId, message)`  | `Promise<void>`    | Requires RTM                   |
+| `sendImage(agentUserId, message)` | `Promise<void>`    | Requires RTM                   |
+| `interrupt(agentUserId)`          | `Promise<void>`    | Requires RTM                   |
+
+### Configuration
+
+```typescript
+interface AgoraVoiceAIConfig {
+  rtcEngine: RTCEngine;           // required
+  rtmConfig?: RTMConfig;          // optional — enables messaging
+  renderMode?: TranscriptHelperMode;  // TEXT | WORD | CHUNK | AUTO (default)
+  enableLog?: boolean;            // default false
+  enableAgoraMetrics?: boolean;   // default false
+}
+```
+
+## Engine Contracts (Structural Types)
+
+### RTCEngine
+
+```typescript
+interface RTCEngine {
+  on(event: 'audio-pts', listener: (pts: number) => void): void;
+  on(event: 'stream-message', listener: (uid: number, data: Uint8Array) => void): void;
+  off(event: string, listener: Function): void;
+}
+```
+
+### RTMEngine
+
+```typescript
+interface RTMEngine {
+  publish(channel: string, message: string, options?: object): Promise<void>;
+  addEventListener(event: string, listener: Function): void;
+  removeEventListener(event: string, listener: Function): void;
+}
+```
+
+These are toolkit-owned contracts matched by shape; apps pass their actual Agora SDK instances.
+
+## Events
+
+| Event                      | Payload Type          | When Fired                               |
+| -------------------------- | --------------------- | ---------------------------------------- |
+| `TRANSCRIPT_UPDATED`       | Full transcript array | Any transcript change (full replacement) |
+| `AGENT_STATE_CHANGED`      | Agent state + user ID | Agent state transition via RTM           |
+| `AGENT_INTERRUPTED`        | Agent user ID         | Agent turn interrupted                   |
+| `AGENT_METRICS`            | Metrics object        | Performance data from agent modules      |
+| `AGENT_ERROR`              | Error object          | Agent-side module failure                |
+| `MESSAGE_RECEIPT_UPDATED`  | Receipt object        | Delivery/read receipt via RTM            |
+| `MESSAGE_ERROR`            | Error object          | RTM message delivery failure             |
+| `MESSAGE_SAL_STATUS`       | SAL status            | Speech Activity Level registration       |
+| `DEBUG_LOG`                | Log data              | Debug info (when `enableLog: true`)      |
+
+## RTC Stream Message Wire Format
+
+Multi-part chunked format: `msg_id|part_idx|part_sum|base64_data`
+
+- `part_idx` — 1-based on wire, normalized to 0-based internally
+- `part_sum` — total parts, or `"???"` for unknown
+- Assembled payload is JSON:
+
+```json
+{
+  "object": "user.transcription | assistant.transcription",
+  "text": "hello world",
+  "turn_id": 1,
+  "turn_seq_id": 1,
+  "turn_status": 0,
+  "final": true,
+  "words": [{ "word": "hello", "start_ms": 0, "duration_ms": 50, "stable": true }]
+}
+```
+
+## RTM Presence Event (Agent State)
+
+```json
+{
+  "publisher": "agent_uid",
+  "stateChanged": {
+    "state": "idle | listening | thinking | speaking | silent",
+    "turn_id": "1"
+  }
+}
+```
+
+## RTM Message (Agent Metrics)
+
+```json
+{
+  "object": "message.metrics",
+  "module": "llm | tts | context | mllm",
+  "metric_name": "response_time",
+  "latency_ms": 150,
+  "turn_id": 1
+}
+```
+
+## Public API — React Package
+
+| Export                         | Type      | Purpose                                    |
+| ------------------------------ | --------- | ------------------------------------------ |
+| `useConversationalAI(config)` | Hook      | Flagship hook — full lifecycle management  |
+| `ConversationalAIProvider`     | Component | Context provider for standalone hooks      |
+| `useTranscript()`              | Hook      | Transcript array from context              |
+| `useAgentState()`              | Hook      | Agent state + event from context           |
+| `useAgentError()`              | Hook      | Aggregated errors + clearError()           |
+| `useAgentMetrics()`            | Hook      | Metrics from context                       |
+| `useConversationalAIContext()` | Hook      | Controls (sendMessage, interrupt, instance) |
+
+## Related Deep Dives
+
+- [Event System](deep_dives/event_system.md) — Event lifecycle, listener management, error routing
+- [Rendering Controller](deep_dives/rendering_controller.md) — How transcript messages are processed
diff --git a/docs/ai/L1/07_gotchas.md b/docs/ai/L1/07_gotchas.md
new file mode 100644
index 0000000..3720fee
--- /dev/null
+++ b/docs/ai/L1/07_gotchas.md
@@ -0,0 +1,84 @@
+# 07 Gotchas
+
+> Critical gotchas, tribal knowledge, and non-obvious behaviors in the toolkit.
+
+## High-Risk Modules — Do Not Modify Without Explicit Task
+
+These files are battle-tested against real agent traffic. Silent failures in production are hard to debug:
+
+| File                            | Lines | Why It's High-Risk                            |
+| ------------------------------- | ----- | --------------------------------------------- |
+| `src/rendering/sub-render.ts`   | ~740  | Transcript rendering logic; subtle state bugs |
+| `src/rendering/sub-render-queue.ts` | ~570 | Queue ordering; race conditions possible   |
+| `src/rendering/sub-render-pts.ts`   | ~100 | PTS timing; audio sync sensitivity        |
+
+These files are intentionally large. Do not split without architectural justification.
+
+## Singleton Lifecycle Quirks
+
+- `getInstance()` throws `NotInitializedError` if called before `init()`
+- Calling `init()` while another `init()` is in-flight waits for the first, then re-inits
+- `destroy()` is idempotent — safe to call multiple times
+- React `StrictMode` double-invokes effects; the hook tracks a `cancelled` flag to handle this
+
+## RTM Is Optional but Silent
+
+- Three methods require RTM and throw `RTMRequiredError`: `sendText()`, `sendImage()`, `interrupt()`
+- RTM-dependent **events** (`AGENT_STATE_CHANGED`, `MESSAGE_RECEIPT_UPDATED`, `MESSAGE_ERROR`) simply do not fire if RTM is not configured — **no error thrown**
+- These events also require specific agent-side config: `enable_rtm: true`, `data_channel: "rtm"`, `enable_error_message: true`, `enable_metrics: true`
+
+## Transcript Mode Detection
+
+- `AUTO` mode (default) infers rendering mode from the first agent message
+- `WORD` mode requires `AgoraRTC.setParameter('ENABLE_AUDIO_PTS_METADATA', true)` **before** client creation
+- Switching modes after init requires full re-initialization
+
+## Chunked Message Assembly
+
+- Wire format is 1-based; `part_idx < 1` is rejected
+- `part_sum === "???"` treated as unknown (`-1`)
+- Deduplication by `part_idx` prevents replay attacks
+- TTL of 30 seconds; older incomplete messages auto-evicted
+- Cache cap of 1000 entries; oldest evicted when exceeded
+
+## Event Listener Limits
+
+- Default max 10 listeners per event (Node.js convention)
+- Exceeding the limit logs a warning; set `setMaxListeners(0)` to disable
+- Can indicate memory leaks — investigate before suppressing
+
+## React Config Stability
+
+- Dev-mode warning if config object changes identity without channel change
+- Wrap config in `useMemo([])` to maintain stable identity
+- Changing identity triggers unnecessary re-init cycle
+
+## Error Event Routing
+
+- `AGENT_ERROR` = agent-side module failures (LLM, TTS, context errors)
+- `MESSAGE_ERROR` = client-side RTM message delivery failures
+- **Never conflate these** — use different handlers
+- `AGENT_ERROR` requires `enable_error_message: true` in agent start params
+
+## Dev vs Production Behavior
+
+- Engine validation (method presence checks on RTCEngine/RTMEngine) runs **only in development**
+- Production skips validation for performance
+- If an engine is missing methods, dev will error; production will crash at runtime
+
+## Optional Dependencies
+
+- `@agora-js/report` — dynamically imported; falls back to `ConsoleMetricsReporter` if missing
+- `jszip` — dynamically imported; used in helper paths
+- Both guarded with try/catch on import; library continues working without them
+
+## Monorepo Gotcha
+
+- `packages/conversational-ai/` has **no source files** — all source lives in root `src/`
+- Build config (`tsup.config.ts`) points to `../../src/index.ts`
+- This is intentional; do not add source files to the package directory
+
+## Related Deep Dives
+
+- [Rendering Controller](deep_dives/rendering_controller.md) — Detailed rendering mode behavior and edge cases
+- [Event System](deep_dives/event_system.md) — Error routing details
diff --git a/docs/ai/L1/08_security.md b/docs/ai/L1/08_security.md
new file mode 100644
index 0000000..152973a
--- /dev/null
+++ b/docs/ai/L1/08_security.md
@@ -0,0 +1,81 @@
+# 08 Security
+
+> Security model, trust boundaries, credential handling, and input validation for the toolkit.
+
+## Trust Boundaries
+
+```
+┌─────────────────────────────────────┐
+│  User Application (trusted)         │
+│  - Holds Agora App ID and Token     │
+│  - Creates RTC/RTM engine instances │
+│  - Passes engines to toolkit        │
+└──────────────┬──────────────────────┘
+               │ structural contract
+┌──────────────▼──────────────────────┐
+│  Toolkit (this library)             │
+│  - Never stores credentials         │
+│  - Validates engine shape (dev only)│
+│  - Processes messages from RTC/RTM  │
+└──────────────┬──────────────────────┘
+               │ peer SDK calls
+┌──────────────▼──────────────────────┐
+│  Agora Peer SDKs (external)         │
+│  - RTC: audio streaming, PTS        │
+│  - RTM: messaging, presence         │
+│  - Handle network transport + auth  │
+└─────────────────────────────────────┘
+```
+
+## Credential Handling
+
+- **The toolkit never handles credentials directly** — it receives pre-initialized engine instances
+- Agora App ID, tokens, and channel names are the application's responsibility
+- No `.env` files, no secret storage, no token generation in this library
+- Token refresh is handled by the application and the peer SDKs
+
+## Input Validation
+
+- **Engine validation** — `AgoraVoiceAI.init()` validates that passed engines have required methods (dev mode only)
+- **Chunked message validation** — `ChunkedMessageAssembler` validates:
+  - Part index bounds (rejects `part_idx < 1`)
+  - NaN checks on numeric fields
+  - Deduplication by part index
+  - TTL-based eviction (30s) for incomplete messages
+  - Cache size cap (1000) to prevent unbounded growth
+- **No user input sanitization** — the toolkit processes messages from Agora infrastructure, not direct user input
+
+## Vulnerability Reporting
+
+- Security issues reported via GitHub private advisory (see `SECURITY.md`)
+- Scope: credentials handling, token patterns, SDK integration security
+- Response timeline: 48h acknowledgment, 7d resolution target
+
+## Dependency Security
+
+- **Zero runtime dependencies** — core package has no `dependencies` field
+- **Peer dependencies** — version-pinned minimums:
+  - `agora-rtc-sdk-ng` ≥4.23.4
+  - `agora-rtm` ≥2.0.0 (optional)
+- **Optional dependencies** — dynamically imported with try/catch:
+  - `@agora-js/report` ≥4.19.0
+  - `jszip` ≥3.0.0
+- **npm provenance** — CI publishes with `--provenance` flag for supply chain verification
+
+## Message Trust Model
+
+- RTC stream messages are received from Agora infrastructure (not directly from other users)
+- RTM messages are published via Agora's authenticated channels
+- The toolkit trusts message content from these channels — it does not re-validate or sanitize payloads
+- Message integrity is the responsibility of Agora's transport layer
+
+## Safe Defaults
+
+- Logging disabled by default (`enableLog: false`)
+- Metrics reporting disabled by default (`enableAgoraMetrics: false`)
+- RTM disabled by default (RTC-only mode)
+- No automatic network requests beyond what peer SDKs initiate
+
+## Related Deep Dives
+
+- None
diff --git a/docs/ai/L1/deep_dives/_index.md b/docs/ai/L1/deep_dives/_index.md
new file mode 100644
index 0000000..f166f2a
--- /dev/null
+++ b/docs/ai/L1/deep_dives/_index.md
@@ -0,0 +1,7 @@
+# Deep Dives Index
+
+| Document                                               | Summary                                            | Load When                                              |
+| ------------------------------------------------------ | -------------------------------------------------- | ------------------------------------------------------ |
+| [rendering_controller.md](rendering_controller.md)     | Transcript rendering modes, PTS timing, queue system | Modifying rendering logic or debugging transcript display |
+| [event_system.md](event_system.md)                     | Event types, listener management, error routing     | Adding events, debugging event flow, or modifying error handling |
+| [build_pipeline.md](build_pipeline.md)                 | Workspace structure, dual CJS/ESM builds, publish   | Changing build config, adding packages, or releasing    |
diff --git a/docs/ai/L1/deep_dives/build_pipeline.md b/docs/ai/L1/deep_dives/build_pipeline.md
new file mode 100644
index 0000000..87c56df
--- /dev/null
+++ b/docs/ai/L1/deep_dives/build_pipeline.md
@@ -0,0 +1,64 @@
+# Build Pipeline
+
+> **When to Read This:** Load this document when changing build configuration, adding new packages to the monorepo, or troubleshooting the publish workflow.
+
+## Overview
+
+The monorepo uses pnpm workspaces with tsup for bundling. Two packages are published to npm; two apps are for development only.
+
+## Workspace Structure
+
+```
+pnpm-workspace.yaml
+├── packages/
+│   ├── conversational-ai/    → published as agora-agent-client-toolkit
+│   └── react/                → published as agora-agent-client-toolkit-react
+└── apps/
+    ├── demo/                 → not published (Vite vanilla TS)
+    └── playground/           → not published (React playground)
+```
+
+## Source Location Quirk
+
+The core package (`packages/conversational-ai/`) contains **no source files**. All source lives in root `src/`. The package's `tsup.config.ts` entry point is `../../src/index.ts`.
+
+The React package is self-contained with source in `packages/react/src/`.
+
+## Build Output (Both Packages)
+
+| Output           | Format | Purpose        |
+| ---------------- | ------ | -------------- |
+| `dist/index.js`  | CJS    | CommonJS entry |
+| `dist/index.mjs` | ESM    | ES module entry |
+| `dist/index.d.ts` | Types | CJS type declarations |
+| `dist/index.d.mts` | Types | ESM type declarations |
+
+- `sideEffects: false` enables tree-shaking
+- Both packages export via `exports` field in `package.json`
+
+## CI Pipeline (`.github/workflows/ci.yml`)
+
+### Build + Test Job
+- Matrix: Node 20, 22, 24
+- Steps: lint → format check → build core → build react → typecheck → test → coverage
+
+### Publish Job
+- Trigger: tag push (`v*`) or manual workflow dispatch
+- Publishes both packages to npm with `--provenance`
+- Skips if version already published (checks npm registry)
+- Creates GitHub Release with auto-generated notes
+
+## Adding a New Package
+
+1. Create directory under `packages/` or `apps/`
+2. It's automatically included via `pnpm-workspace.yaml` globs
+3. Add `package.json` with `name`, `version`, build scripts
+4. Add `tsup.config.ts` for build configuration
+5. Add `vitest.config.ts` for tests
+6. Reference other workspace packages via `"workspace:*"` protocol
+7. Update CI if the new package should be published
+
+## See Also
+
+- [Back to Setup](../01_setup.md)
+- [Back to Code Map](../03_code_map.md)
diff --git a/docs/ai/L1/deep_dives/event_system.md b/docs/ai/L1/deep_dives/event_system.md
new file mode 100644
index 0000000..9efb699
--- /dev/null
+++ b/docs/ai/L1/deep_dives/event_system.md
@@ -0,0 +1,78 @@
+# Event System
+
+> **When to Read This:** Load this document when adding new event types, debugging event flow, or modifying error routing between agent-side and client-side errors.
+
+## Overview
+
+The event system is built on `EventHelper<T>`, a generic typed event emitter. `AgoraVoiceAI` extends it with specific event types for conversational AI.
+
+## EventHelper Base Class
+
+- Generic over handler map type `T`
+- Methods: `on(event, listener)`, `off(event, listener)`, `emit(event, ...args)`
+- Default max 10 listeners per event; configurable via `setMaxListeners(n)`
+- Exceeding limit logs a warning (potential memory leak indicator)
+- Each listener is wrapped in try/catch — one failing listener does not crash others
+
+## Event Types and Sources
+
+| Event                      | Source     | Requires RTM? | Requires Agent Config?          |
+| -------------------------- | ---------- | ------------- | ------------------------------- |
+| `TRANSCRIPT_UPDATED`       | RTC        | No            | No                              |
+| `AGENT_STATE_CHANGED`      | RTM        | Yes           | `enable_rtm: true`              |
+| `AGENT_INTERRUPTED`        | RTM        | Yes           | `enable_rtm: true`              |
+| `AGENT_METRICS`            | RTM        | Yes           | `enable_metrics: true`          |
+| `AGENT_ERROR`              | RTM        | Yes           | `enable_error_message: true`    |
+| `MESSAGE_RECEIPT_UPDATED`  | RTM        | Yes           | `enable_rtm: true`              |
+| `MESSAGE_ERROR`            | Client RTM | Yes           | No (client-side delivery error) |
+| `MESSAGE_SAL_STATUS`       | RTM        | Yes           | `enable_rtm: true`              |
+| `DEBUG_LOG`                | Internal   | No            | `enableLog: true`               |
+
+## Error Routing
+
+Two distinct error channels exist:
+
+### AGENT_ERROR
+- Fired when the AI agent's internal modules fail (LLM timeout, TTS error, context overflow)
+- Payload includes: `module` (which agent module), error details, `turn_id`
+- Requires `enable_error_message: true` in agent start parameters
+
+### MESSAGE_ERROR
+- Fired when the client's RTM message delivery fails
+- Payload includes: delivery failure details, message metadata
+- Client-side error — does not require agent config
+
+### React useAgentError() Hook
+- Aggregates both `AGENT_ERROR` and `MESSAGE_ERROR` into a discriminated union
+- `source: 'agent' | 'message'` distinguishes the two
+- `clearError()` resets the error state
+
+## Listener Lifecycle
+
+```
+AgoraVoiceAI.init(config)
+    │
+    ▼
+subscribeMessage(channel)
+    │ binds pre-bound handlers to RTC/RTM
+    │ stores handler references for later unbinding
+    ▼
+[events flow to registered listeners]
+    │
+    ▼
+unsubscribe()
+    │ unbinds handlers using stored references
+    ▼
+destroy()
+    │ removes all listeners
+    │ resets singleton
+```
+
+- Handlers are pre-bound as instance fields (not arrow functions in methods)
+- This allows `off()` to match the same function reference used in `on()`
+- React hooks register listeners in `useEffect` cleanup cycle
+
+## See Also
+
+- [Back to Interfaces](../06_interfaces.md)
+- [Back to Architecture](../02_architecture.md)
diff --git a/docs/ai/L1/deep_dives/rendering_controller.md b/docs/ai/L1/deep_dives/rendering_controller.md
new file mode 100644
index 0000000..41eaecb
--- /dev/null
+++ b/docs/ai/L1/deep_dives/rendering_controller.md
@@ -0,0 +1,72 @@
+# Rendering Controller
+
+> **When to Read This:** Load this document when modifying transcript rendering logic, debugging transcript display issues, or working with PTS-based word timing.
+
+## Overview
+
+The rendering controller (`CovSubRenderController`) processes incoming RTC stream messages and RTM presence events to produce a coherent transcript. It supports three rendering modes plus auto-detection.
+
+## Rendering Modes
+
+| Mode    | How It Works                                              | Use Case                      |
+| ------- | --------------------------------------------------------- | ----------------------------- |
+| `TEXT`  | Full text replacement per message                         | Simple, low-latency display   |
+| `WORD`  | Individual words timed to audio PTS                       | Lip-sync, karaoke-style       |
+| `CHUNK` | Streaming chunks assembled incrementally                  | Typewriter effect              |
+| `AUTO`  | Detects mode from first agent message; becomes one of above | Default — most apps use this |
+
+## Architecture
+
+```
+RTC stream-message
+    │
+    ▼
+CovSubRenderController.handleMessage(uid, data)
+    │
+    ├── TEXT mode: replaces current turn text
+    ├── WORD mode: queues words, releases via PTS timing
+    └── CHUNK mode: appends chunks to current turn
+    │
+    ▼
+SubRenderQueue.push(message)
+    │ manages chat history array
+    │ handles turn boundaries (turn_id, turn_status)
+    │ deduplicates by turn_seq_id
+    ▼
+emit TRANSCRIPT_UPDATED (full history array)
+```
+
+## SubRenderQueue
+
+- Maintains the complete conversation history as an ordered array
+- Handles turn lifecycle: IN_PROGRESS → END → INTERRUPTED
+- Deduplicates messages by `turn_seq_id` within a turn
+- Manages both user and agent transcriptions
+- Emits full history on every change (not incremental diffs)
+
+## SubRenderPTS (WORD Mode)
+
+- Receives PTS (Presentation Timestamp) values from RTC `audio-pts` events
+- Releases individual words when their `start_ms` matches current PTS
+- Words have `stable` flag — unstable words may be revised by later messages
+- Requires `AgoraRTC.setParameter('ENABLE_AUDIO_PTS_METADATA', true)` before client creation
+
+## Critical Constraints
+
+- These files are intentionally large (~740, ~570, ~100 lines); do not split without architectural justification
+- Silent failures in production — rendering bugs may not throw errors but produce incorrect transcripts
+- Queue ordering is sensitive to network jitter; the queue system handles out-of-order messages
+- PTS timing depends on audio stream continuity; gaps in audio cause word release delays
+
+## Turn Status Values
+
+| Value | Name          | Meaning                                 |
+| ----- | ------------- | --------------------------------------- |
+| 0     | IN_PROGRESS   | Agent or user still speaking            |
+| 1     | END           | Turn completed normally                 |
+| 2     | INTERRUPTED   | Turn interrupted by user or system      |
+
+## See Also
+
+- [Back to Architecture](../02_architecture.md)
+- [Back to Gotchas](../07_gotchas.md)

From 267c8e35a75dbb19387a8af98d2614d2569b478d Mon Sep 17 00:00:00 2001
From: Ben Weeks <ben@agora.io>
Date: Thu, 16 Apr 2026 12:33:04 +0100
Subject: [PATCH 2/4] docs: add test results for progressive disclosure docs

---
 docs/ai/test-results.md | 71 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)
 create mode 100644 docs/ai/test-results.md

diff --git a/docs/ai/test-results.md b/docs/ai/test-results.md
new file mode 100644
index 0000000..0e465f2
--- /dev/null
+++ b/docs/ai/test-results.md
@@ -0,0 +1,71 @@
+# PD Documentation Test Results
+
+Tested: 2026-04-16
+Agent: Claude Opus 4.6
+Repo: agent-client-toolkit-ts
+
+## Summary
+
+- Total questions: 10
+- Passed: 10 (correct answer, right level)
+- L1 gaps: 0
+- L2 gaps: 0
+- Cross-ref issues: 0
+- Structural checks: 24/24 passed
+
+## Structural Checks
+
+All checks passed:
+
+- L0 exists and is under 50 lines
+- All 8 L1 files exist (01_setup through 08_security)
+- Each L1 file is 80-200 lines
+- Each L1 file starts with a purpose statement
+- Each L1 file ends with `## Related Deep Dives`
+- Total L1 lines under 1,600
+- L2 `_index.md` exists and lists all L2 files
+- Each L2 file starts with `> **When to Read This:**`
+- All relative links resolve to existing files
+- AGENTS.md exists with How to Load, Git Conventions, Doc Commands
+- CLAUDE.md references @AGENTS.md
+
+## Results
+
+### Setup & Build
+
+| # | Question | Answer Correct? | Files Read | Level Loaded | Result |
+| --- | --- | --- | --- | --- | --- |
+| 1 | How do I install dependencies and build this project? | Yes | L0, 01_setup | L0+L1 | Pass |
+| 2 | What are the peer dependencies and how should consumers install them? | Yes | L0, 01_setup, 06_interfaces | L0+L1 | Pass |
+
+### Test & Run
+
+| # | Question | Answer Correct? | Files Read | Level Loaded | Result |
+| --- | --- | --- | --- | --- | --- |
+| 3 | How do I run the test suite? | Yes | L0, 01_setup | L0+L1 | Pass |
+| 4 | How do I start the project locally for development? | Yes | L0, 01_setup, 05_workflows | L0+L1 | Pass |
+
+### Conventions
+
+| # | Question | Answer Correct? | Files Read | Level Loaded | Result |
+| --- | --- | --- | --- | --- | --- |
+| 5 | What naming conventions does this project use? | Yes | L0, 04_conventions | L0+L1 | Pass |
+| 6 | How should I handle errors in this codebase? | Yes | L0, 04_conventions, 07_gotchas | L0+L1 | Pass |
+
+### Development
+
+| # | Question | Answer Correct? | Files Read | Level Loaded | Result |
+| --- | --- | --- | --- | --- | --- |
+| 7 | How would I add a new event type to the toolkit? | Yes | L0, 05_workflows, 06_interfaces, deep_dives/event_system | L0+L1+L2 | Pass |
+| 8 | How would I add a new rendering mode? | Yes | L0, 05_workflows, 02_architecture, deep_dives/rendering_controller | L0+L1+L2 | Pass |
+
+### Deep Dive
+
+| # | Question | Answer Correct? | Files Read | Level Loaded | Result |
+| --- | --- | --- | --- | --- | --- |
+| 9 | How does the SubRenderQueue handle chunked text assembly? | Yes | L0, 02_architecture, deep_dives/rendering_controller | L0+L1+L2 | Pass |
+| 10 | What are the edge cases in RTM message parsing? | Yes | L0, 07_gotchas, deep_dives/event_system | L0+L1+L2 | Pass |
+
+## Recommended Fixes
+
+None — all tests passed.

From c3477cd724ffa1c72e15bf97802ffb393094ae5c Mon Sep 17 00:00:00 2001
From: Ben Weeks <ben@agora.io>
Date: Thu, 16 Apr 2026 13:30:27 +0100
Subject: [PATCH 3/4] docs: expand build pipeline release gate, add round 2
 test results

---
 docs/ai/L1/deep_dives/build_pipeline.md |  9 +++++---
 docs/ai/test-results.md                 | 29 ++++++++++++++++++++-----
 2 files changed, 30 insertions(+), 8 deletions(-)

diff --git a/docs/ai/L1/deep_dives/build_pipeline.md b/docs/ai/L1/deep_dives/build_pipeline.md
index 87c56df..c7e9ef8 100644
--- a/docs/ai/L1/deep_dives/build_pipeline.md
+++ b/docs/ai/L1/deep_dives/build_pipeline.md
@@ -38,11 +38,14 @@ The React package is self-contained with source in `packages/react/src/`.
 
 ## CI Pipeline (`.github/workflows/ci.yml`)
 
-### Build + Test Job
-- Matrix: Node 20, 22, 24
-- Steps: lint → format check → build core → build react → typecheck → test → coverage
+### Build + Test Job (Release Gate)
+- Matrix: Node 20, 22, 24 (`fail-fast: false` — all variants must pass)
+- Steps: lint → format check → build core → build react → typecheck → typecheck:interop → test → coverage
+- `typecheck:interop` type-checks `packages/conversational-ai/__typetests__/interop.ts` — a type-level test verifying structural typing contracts work with foreign SDK shapes. Catches breaking changes to engine contracts.
+- Coverage runs only on Node 20 and writes a GitHub Step Summary. Coverage thresholds are enforced by vitest config.
 
 ### Publish Job
+- `needs: [build-and-test]` — ALL matrix variants must pass before publish proceeds. This makes `build-and-test` the hard release gate.
 - Trigger: tag push (`v*`) or manual workflow dispatch
 - Publishes both packages to npm with `--provenance`
 - Skips if version already published (checks npm registry)
diff --git a/docs/ai/test-results.md b/docs/ai/test-results.md
index 0e465f2..d34cd37 100644
--- a/docs/ai/test-results.md
+++ b/docs/ai/test-results.md
@@ -6,12 +6,12 @@ Repo: agent-client-toolkit-ts
 
 ## Summary
 
-- Total questions: 10
-- Passed: 10 (correct answer, right level)
+- Total questions: 14
+- Passed: 14 (correct answer, right level)
 - L1 gaps: 0
-- L2 gaps: 0
+- L2 gaps fixed: 1 (build_pipeline.md — release gate details)
 - Cross-ref issues: 0
-- Structural checks: 24/24 passed
+- Structural checks: 11/11 passed
 
 ## Structural Checks
 
@@ -66,6 +66,25 @@ All checks passed:
 | 9 | How does the SubRenderQueue handle chunked text assembly? | Yes | L0, 02_architecture, deep_dives/rendering_controller | L0+L1+L2 | Pass |
 | 10 | What are the edge cases in RTM message parsing? | Yes | L0, 07_gotchas, deep_dives/event_system | L0+L1+L2 | Pass |
 
+### Round 2 — Targeted Coverage (Higher-Risk Contracts)
+
+| # | Question (short) | Answer Correct? | Files Read | Level Loaded | Result |
+| --- | --- | --- | --- | --- | --- |
+| 11 | What works without RTM, what fails/goes silent? | Yes | L1/06_interfaces, L1/07_gotchas, L1/02_architecture | L0+L1 | Pass |
+| 12 | How to enable agent metrics, what if @agora-js/report missing? | Yes | L1/06_interfaces, L1/07_gotchas, L1/04_conventions, L1/08_security | L0+L1 | Pass |
+| 13 | Adapt toolkit to addEventListener/removeEventListener RTM client? | Yes | L1/04_conventions, L1/06_interfaces, L1/02_architecture | L0+L1 | Pass |
+| 14 | Validate across Node versions, which CI step is release gate? | Yes (after fix) | L1/01_setup, L1/05_workflows, L2/build_pipeline | L0+L1+L2 | Pass |
+
+Round 2 initially found Q14 failed: L2 `build_pipeline.md` was missing the `needs: [build-and-test]` release gate dependency and `typecheck:interop` step. Fixed and retested.
+
+## Summary (Updated)
+
+- Total questions: 14
+- Passed: 14
+- L1 gaps: 0
+- L2 gaps: 0 (after fix to build_pipeline.md)
+- Cross-ref issues: 0
+
 ## Recommended Fixes
 
-None — all tests passed.
+All applied — `deep_dives/build_pipeline.md` expanded with release gate details and `typecheck:interop` step.

From e52341130ee43cde5610e80d0df5acc1c8e51b4c Mon Sep 17 00:00:00 2001
From: Ben Weeks <ben@agora.io>
Date: Fri, 17 Apr 2026 10:56:52 +0100
Subject: [PATCH 4/4] docs: rename deep_dives/ to L2/ for clarity

---
 docs/ai/L1/01_setup.md                                |  2 +-
 docs/ai/L1/02_architecture.md                         |  4 ++--
 docs/ai/L1/03_code_map.md                             |  2 +-
 docs/ai/L1/05_workflows.md                            |  4 ++--
 docs/ai/L1/06_interfaces.md                           |  4 ++--
 docs/ai/L1/07_gotchas.md                              |  4 ++--
 docs/ai/L1/{deep_dives => L2}/_index.md               |  0
 docs/ai/L1/{deep_dives => L2}/build_pipeline.md       |  0
 docs/ai/L1/{deep_dives => L2}/event_system.md         |  0
 docs/ai/L1/{deep_dives => L2}/rendering_controller.md |  0
 docs/ai/test-results.md                               | 10 +++++-----
 11 files changed, 15 insertions(+), 15 deletions(-)
 rename docs/ai/L1/{deep_dives => L2}/_index.md (100%)
 rename docs/ai/L1/{deep_dives => L2}/build_pipeline.md (100%)
 rename docs/ai/L1/{deep_dives => L2}/event_system.md (100%)
 rename docs/ai/L1/{deep_dives => L2}/rendering_controller.md (100%)

diff --git a/docs/ai/L1/01_setup.md b/docs/ai/L1/01_setup.md
index b9eb8a2..f8bb5ae 100644
--- a/docs/ai/L1/01_setup.md
+++ b/docs/ai/L1/01_setup.md
@@ -88,4 +88,4 @@ Use with `pnpm --filter <name> <script>` to target a specific package.
 
 ## Related Deep Dives
 
-- [Build Pipeline](deep_dives/build_pipeline.md) — Multi-target builds, workspace structure, publish workflow
+- [Build Pipeline](L2/build_pipeline.md) — Multi-target builds, workspace structure, publish workflow
diff --git a/docs/ai/L1/02_architecture.md b/docs/ai/L1/02_architecture.md
index 3fd310f..8ff7ebd 100644
--- a/docs/ai/L1/02_architecture.md
+++ b/docs/ai/L1/02_architecture.md
@@ -102,5 +102,5 @@ RTM presence event ──► AgoraVoiceAI._handleRtmPresence()
 
 ## Related Deep Dives
 
-- [Rendering Controller](deep_dives/rendering_controller.md) — TEXT/WORD/CHUNK modes, PTS timing, queue system
-- [Event System](deep_dives/event_system.md) — Event types, listener management, error routing
+- [Rendering Controller](L2/rendering_controller.md) — TEXT/WORD/CHUNK modes, PTS timing, queue system
+- [Event System](L2/event_system.md) — Event types, listener management, error routing
diff --git a/docs/ai/L1/03_code_map.md b/docs/ai/L1/03_code_map.md
index 94da359..efca576 100644
--- a/docs/ai/L1/03_code_map.md
+++ b/docs/ai/L1/03_code_map.md
@@ -80,4 +80,4 @@ repo-root/
 
 ## Related Deep Dives
 
-- [Build Pipeline](deep_dives/build_pipeline.md) — How source maps to packages, dual CJS/ESM output
+- [Build Pipeline](L2/build_pipeline.md) — How source maps to packages, dual CJS/ESM output
diff --git a/docs/ai/L1/05_workflows.md b/docs/ai/L1/05_workflows.md
index 69c9a4f..e05c438 100644
--- a/docs/ai/L1/05_workflows.md
+++ b/docs/ai/L1/05_workflows.md
@@ -88,5 +88,5 @@ pnpm format:check    # verify formatting
 
 ## Related Deep Dives
 
-- [Build Pipeline](deep_dives/build_pipeline.md) — Publish workflow, dual CJS/ESM output
-- [Rendering Controller](deep_dives/rendering_controller.md) — Transcript mode debugging
+- [Build Pipeline](L2/build_pipeline.md) — Publish workflow, dual CJS/ESM output
+- [Rendering Controller](L2/rendering_controller.md) — Transcript mode debugging
diff --git a/docs/ai/L1/06_interfaces.md b/docs/ai/L1/06_interfaces.md
index 1b8bece..115bd86 100644
--- a/docs/ai/L1/06_interfaces.md
+++ b/docs/ai/L1/06_interfaces.md
@@ -126,5 +126,5 @@ Multi-part chunked format: `msg_id|part_idx|part_sum|base64_data`
 
 ## Related Deep Dives
 
-- [Event System](deep_dives/event_system.md) — Event lifecycle, listener management, error routing
-- [Rendering Controller](deep_dives/rendering_controller.md) — How transcript messages are processed
+- [Event System](L2/event_system.md) — Event lifecycle, listener management, error routing
+- [Rendering Controller](L2/rendering_controller.md) — How transcript messages are processed
diff --git a/docs/ai/L1/07_gotchas.md b/docs/ai/L1/07_gotchas.md
index 3720fee..4c4eea7 100644
--- a/docs/ai/L1/07_gotchas.md
+++ b/docs/ai/L1/07_gotchas.md
@@ -80,5 +80,5 @@ These files are intentionally large. Do not split without architectural justific
 
 ## Related Deep Dives
 
-- [Rendering Controller](deep_dives/rendering_controller.md) — Detailed rendering mode behavior and edge cases
-- [Event System](deep_dives/event_system.md) — Error routing details
+- [Rendering Controller](L2/rendering_controller.md) — Detailed rendering mode behavior and edge cases
+- [Event System](L2/event_system.md) — Error routing details
diff --git a/docs/ai/L1/deep_dives/_index.md b/docs/ai/L1/L2/_index.md
similarity index 100%
rename from docs/ai/L1/deep_dives/_index.md
rename to docs/ai/L1/L2/_index.md
diff --git a/docs/ai/L1/deep_dives/build_pipeline.md b/docs/ai/L1/L2/build_pipeline.md
similarity index 100%
rename from docs/ai/L1/deep_dives/build_pipeline.md
rename to docs/ai/L1/L2/build_pipeline.md
diff --git a/docs/ai/L1/deep_dives/event_system.md b/docs/ai/L1/L2/event_system.md
similarity index 100%
rename from docs/ai/L1/deep_dives/event_system.md
rename to docs/ai/L1/L2/event_system.md
diff --git a/docs/ai/L1/deep_dives/rendering_controller.md b/docs/ai/L1/L2/rendering_controller.md
similarity index 100%
rename from docs/ai/L1/deep_dives/rendering_controller.md
rename to docs/ai/L1/L2/rendering_controller.md
diff --git a/docs/ai/test-results.md b/docs/ai/test-results.md
index d34cd37..65a2c94 100644
--- a/docs/ai/test-results.md
+++ b/docs/ai/test-results.md
@@ -56,15 +56,15 @@ All checks passed:
 
 | # | Question | Answer Correct? | Files Read | Level Loaded | Result |
 | --- | --- | --- | --- | --- | --- |
-| 7 | How would I add a new event type to the toolkit? | Yes | L0, 05_workflows, 06_interfaces, deep_dives/event_system | L0+L1+L2 | Pass |
-| 8 | How would I add a new rendering mode? | Yes | L0, 05_workflows, 02_architecture, deep_dives/rendering_controller | L0+L1+L2 | Pass |
+| 7 | How would I add a new event type to the toolkit? | Yes | L0, 05_workflows, 06_interfaces, L2/event_system | L0+L1+L2 | Pass |
+| 8 | How would I add a new rendering mode? | Yes | L0, 05_workflows, 02_architecture, L2/rendering_controller | L0+L1+L2 | Pass |
 
 ### Deep Dive
 
 | # | Question | Answer Correct? | Files Read | Level Loaded | Result |
 | --- | --- | --- | --- | --- | --- |
-| 9 | How does the SubRenderQueue handle chunked text assembly? | Yes | L0, 02_architecture, deep_dives/rendering_controller | L0+L1+L2 | Pass |
-| 10 | What are the edge cases in RTM message parsing? | Yes | L0, 07_gotchas, deep_dives/event_system | L0+L1+L2 | Pass |
+| 9 | How does the SubRenderQueue handle chunked text assembly? | Yes | L0, 02_architecture, L2/rendering_controller | L0+L1+L2 | Pass |
+| 10 | What are the edge cases in RTM message parsing? | Yes | L0, 07_gotchas, L2/event_system | L0+L1+L2 | Pass |
 
 ### Round 2 — Targeted Coverage (Higher-Risk Contracts)
 
@@ -87,4 +87,4 @@ Round 2 initially found Q14 failed: L2 `build_pipeline.md` was missing the `need
 
 ## Recommended Fixes
 
-All applied — `deep_dives/build_pipeline.md` expanded with release gate details and `typecheck:interop` step.
+All applied — `L2/build_pipeline.md` expanded with release gate details and `typecheck:interop` step.