# EasyCat

> EasyCat is a Python voice bot framework: noise reduction -> VAD -> STT ->
> agent -> TTS, with pluggable providers at each stage and idiomatic bridges
> for OpenAI Agents SDK, PydanticAI, LangChain, LangGraph, LlamaAgents, the
> remote Responses API, or your own async workflow.

Machine-readable surfaces: `easycat docs --json` emits this route map with
command hints and audience labels; `easycat explain json-schema` documents the
standard `--json` envelope every CLI command shares. Bare `easycat` commands
use the installed CLI form; from this repository, prefix them with `uv run`.

Source: https://github.com/yisding/easycat

Command note: Bare easycat commands use installed CLI form; from this repo, prefix them with uv run. Commands already starting with uv run are repo-local and should run from the repository root. just commands are repo-local shortcuts; install just or use the raw command table in CONTRIBUTING.md. Replace uppercase or angle-bracket placeholders such as PATH, DIR, TEXT, TURN_ID, FILE, and <session_id> before running.

## Start here

- Path: README.md#choose-your-path
- URL: https://github.com/yisding/easycat/blob/main/README.md#choose-your-path
- Audience: all readers
- Diataxis: how-to
- Choose the right first route for quickstart, learning, examples, maintenance, or operations.

Commands:

```bash
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run --env-file .env python examples/openai_agents_voice.py
uv run easycat console --voice-demo
uv run python examples/journal_demo.py
uv run python docs/teaching/offline_spine.py --run --jobs 4
uv run easycat init --list-templates
uv run easycat init my-agent
uv run easycat docs --audience maintainers
uv run easycat docs --audience coding-agents
uv run easycat validate quick
easycat bundles list
uv sync --extra debugger --group dev
```

## Quickstart

- Path: README.md#install
- URL: https://github.com/yisding/easycat/blob/main/README.md#install
- Audience: new users
- Diataxis: tutorial
- Install EasyCat and run your first voice agent.

Commands:

```bash
uv sync --group dev
uv run easycat console --voice-demo
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python examples/openai_agents_voice.py
uv run --env-file .env python examples/openai_agents_voice.py
```

## Installation and extras

- Path: docs/install.md
- URL: https://github.com/yisding/easycat/blob/main/docs/install.md
- Audience: app builders
- Diataxis: reference
- Choose a portable dependency source and the smallest provider, transport, agent-framework, or processing extras for an application.

Commands:

```bash
uv sync --group dev
uv run easycat console --voice-demo
uv run easycat init my-agent --easycat-git https://github.com/yisding/easycat.git --easycat-git-rev <commit-sha>
uv sync --extra quickstart --group dev
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
```

## CLI and scaffolds

- Path: docs/cli.md
- URL: https://github.com/yisding/easycat/blob/main/docs/cli.md
- Audience: app builders
- Diataxis: how-to
- Scaffold projects, compare templates with base package requirements, extras, env requirements, optional env knobs, generated files, and copyable create/preflight/check/fix/docs/json-schema/run commands, and learn CLI JSON envelopes.

Commands:

```bash
easycat console
easycat console --voice-demo
easycat init --list-templates
easycat init --list-templates --json
easycat init my-agent
easycat init my-agent --easycat-git URL --easycat-git-rev REV
easycat doctor --json
easycat doctor --env-file .env --json
easycat docs
easycat docs --verbose
easycat docs --audience learners
easycat docs --audience learners --json
easycat docs --audience app-builders
easycat docs --audience app-builders --json
easycat docs --audience operators
easycat docs --audience operators --json
easycat docs --audience maintainers
easycat docs --audience maintainers --json
easycat docs --audience coding-agents
easycat docs --audience coding-agents --json
easycat docs --json
easycat explain json-schema
```

## Docs map

- Path: docs/README.md
- URL: https://github.com/yisding/easycat/blob/main/docs/README.md
- Audience: all readers
- Diataxis: reference
- Choose the maintained guide for your current task.

Commands:

```bash
easycat docs
easycat docs --verbose
easycat docs --audience learners
easycat docs --audience app-builders
easycat docs --audience operators
easycat docs --audience maintainers
easycat docs --json
```

## Teaching ladder

- Path: docs/teaching/
- URL: https://github.com/yisding/easycat/tree/main/docs/teaching
- Audience: learners
- Diataxis: tutorial
- Learn voice pipelines chapter by chapter.

Commands:

```bash
uv sync --extra local --group dev
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run easycat docs --audience learners
uv run easycat docs --audience learners --json
uv run python docs/teaching/00-hello-audio/main.py
uv run python docs/teaching/offline_spine.py
uv run python docs/teaching/offline_spine.py --json
uv run python docs/teaching/offline_spine.py --run --jobs 4
uv run python docs/teaching/offline_spine.py --run --jobs 4 --json
uv run easycat validate quick
uv run easycat validate quick --json
uv run easycat validate report .easycat/validation/latest.json
uv run easycat validate report .easycat/validation/latest.json --json
```

## Progress worksheet

- Path: docs/teaching/PROGRESS.md
- URL: https://github.com/yisding/easycat/blob/main/docs/teaching/PROGRESS.md
- Audience: learners
- Diataxis: tutorial
- Track evidence-backed completion across all 16 teaching chapters.

Commands:

```bash
uv run python docs/teaching/00-hello-audio/format_boundaries.py
uv run python docs/teaching/offline_spine.py --run --jobs 4 --show-evidence
```

## First lesson

- Path: docs/teaching/00-hello-audio/
- URL: https://github.com/yisding/easycat/tree/main/docs/teaching/00-hello-audio
- Audience: learners
- Diataxis: tutorial
- Start with audio chunks before agents or providers.

Commands:

```bash
uv sync --extra local --group dev
uv run python docs/teaching/00-hello-audio/main.py
```

## EasyCat feature ladder

- Path: docs/using-easycat/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat
- Audience: learners
- Diataxis: tutorial
- Learn EasyCat's public features one app capability at a time.

Commands:

```bash
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run easycat docs --audience learners
uv run easycat docs --audience learners --json
uv run python docs/using-easycat/00-first-voice-app/main.py
uv run --env-file .env python docs/using-easycat/00-first-voice-app/main.py
```

## Feature first lesson

- Path: docs/using-easycat/00-first-voice-app/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/00-first-voice-app
- Audience: learners
- Diataxis: tutorial
- Build a local voice app with VoiceApp and automatic pipeline wiring.

Commands:

```bash
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python docs/using-easycat/00-first-voice-app/main.py
uv run --env-file .env python docs/using-easycat/00-first-voice-app/main.py
```

## Feature runtime modes

- Path: docs/using-easycat/01-runtime-modes/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/01-runtime-modes
- Audience: learners
- Diataxis: tutorial
- Run one VoiceApp locally, in a browser, over WebSocket, or on Twilio.

Commands:

```bash
uv sync --extra quickstart --extra webrtc --extra telephony --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python docs/using-easycat/01-runtime-modes/main.py local
uv run python docs/using-easycat/01-runtime-modes/main.py browser
uv run python docs/using-easycat/01-runtime-modes/main.py websocket
uv run python docs/using-easycat/01-runtime-modes/main.py twilio
uv run --env-file .env python docs/using-easycat/01-runtime-modes/main.py browser
```

## Feature providers and voices

- Path: docs/using-easycat/02-providers-and-voices/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/02-providers-and-voices
- Audience: learners
- Diataxis: tutorial
- Select STT and TTS providers, models, and provider-specific voices.

Commands:

```bash
uv sync --extra quickstart --extra deepgram --extra elevenlabs --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run easycat doctor --provider deepgram
uv run easycat doctor --provider elevenlabs
uv run python docs/using-easycat/02-providers-and-voices/main.py list
uv run python docs/using-easycat/02-providers-and-voices/main.py openai --voice alloy
uv run python docs/using-easycat/02-providers-and-voices/main.py deepgram-stt --voice nova
uv run python docs/using-easycat/02-providers-and-voices/main.py elevenlabs-voice
uv run --env-file .env python docs/using-easycat/02-providers-and-voices/main.py deepgram-stt
```

## Feature conversation controls

- Path: docs/using-easycat/03-conversation-controls/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/03-conversation-controls
- Audience: learners
- Diataxis: tutorial
- Tune turn taking, signal cleanup, interruption, and push-to-talk.

Commands:

```bash
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python docs/using-easycat/03-conversation-controls/main.py balanced
uv run python docs/using-easycat/03-conversation-controls/main.py vad-only
uv run python docs/using-easycat/03-conversation-controls/main.py fast
uv run python docs/using-easycat/03-conversation-controls/main.py clean
uv run python docs/using-easycat/03-conversation-controls/main.py raw
uv run python docs/using-easycat/03-conversation-controls/push_to_talk.py
uv run --env-file .env python docs/using-easycat/03-conversation-controls/main.py fast
```

## Feature tools and actions

- Path: docs/using-easycat/04-tools-actions/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/04-tools-actions
- Audience: learners
- Diataxis: tutorial
- Separate agent tools, session actions, events, and spoken-output rules.

Commands:

```bash
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python docs/using-easycat/04-tools-actions/main.py preview
uv run python docs/using-easycat/04-tools-actions/main.py run
uv run --env-file .env python docs/using-easycat/04-tools-actions/main.py run
```

## Feature agent bridges

- Path: docs/using-easycat/05-agent-bridges/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/05-agent-bridges
- Audience: learners
- Diataxis: tutorial
- Choose a framework adapter or bring a custom workflow.

Commands:

```bash
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python docs/using-easycat/05-agent-bridges/main.py matrix
uv run python docs/using-easycat/05-agent-bridges/main.py run
uv run --env-file .env python docs/using-easycat/05-agent-bridges/main.py run
```

## Feature session control

- Path: docs/using-easycat/06-session-control/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/06-session-control
- Audience: learners
- Diataxis: tutorial
- Own session lifecycle, events, text turns, resets, and teardown.

Commands:

```bash
uv sync --extra quickstart --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python docs/using-easycat/06-session-control/main.py text
uv run python docs/using-easycat/06-session-control/main.py voice
uv run --env-file .env python docs/using-easycat/06-session-control/main.py voice
```

## Feature observability

- Path: docs/using-easycat/07-observability/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/07-observability
- Audience: learners
- Diataxis: tutorial
- Record, inspect, replay, and compare journals and debug bundles.

Commands:

```bash
uv sync --group dev
uv sync --extra debugger --group dev
uv run python docs/using-easycat/07-observability/main.py pair .easycat/tutorial/ch07
uv run easycat bundles show .easycat/tutorial/ch07/baseline.bundle --json
uv run easycat replay .easycat/tutorial/ch07/baseline.bundle --fidelity artifact --tool-policy deny --json
uv run easycat diff .easycat/tutorial/ch07/baseline.bundle .easycat/tutorial/ch07/candidate.bundle --json
```

## Feature testing and evals

- Path: docs/using-easycat/08-testing-evals/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/08-testing-evals
- Audience: learners
- Diataxis: tutorial
- Test offline turns, evaluation oracles, and latency budgets.

Commands:

```bash
uv sync --group dev
uv run python docs/using-easycat/08-testing-evals/main.py
uv run easycat latency .easycat/tutorial/ch07/baseline.bundle --json
uv run easycat doctor --json
uv run easycat validate latency --smoke --json
```

## Feature multi-caller servers

- Path: docs/using-easycat/09-multi-caller/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/09-multi-caller
- Audience: learners
- Diataxis: tutorial
- Serve isolated callers with auth, capacity limits, and draining.

Commands:

```bash
uv sync --group dev
uv run python docs/using-easycat/09-multi-caller/main.py
```

## Feature telephony

- Path: docs/using-easycat/10-telephony/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/10-telephony
- Audience: learners
- Diataxis: tutorial
- Secure Twilio webhooks, media streams, callbacks, and call control.

Commands:

```bash
uv sync --group dev
uv run python docs/using-easycat/10-telephony/main.py
uv sync --extra openai --extra telephony --extra telephony-fastapi --extra openai-agents --group dev
uv run easycat doctor --env-file .env --json
uv run --env-file .env uvicorn examples.twilio_app:create_app --factory --host 0.0.0.0
```

## Feature production operations

- Path: docs/using-easycat/11-production-ops/
- URL: https://github.com/yisding/easycat/tree/main/docs/using-easycat/11-production-ops
- Audience: learners
- Diataxis: tutorial
- Validate, deploy, observe, preserve, and drain production services.

Commands:

```bash
uv sync --group dev
uv run python docs/using-easycat/11-production-ops/main.py
uv run python docs/using-easycat/11-production-ops/main.py --data-dir .easycat/tutorial/ch11
uv run easycat inspect .easycat/tutorial/ch11/journals/chapter-11-ops-checkpoint.sqlite --json
uv run easycat validate quick --json
uv run easycat validate report .easycat/validation/latest.json --json
uv run easycat validate release --json
```

## Examples

- Path: examples/README.md
- URL: https://github.com/yisding/easycat/blob/main/examples/README.md
- Audience: app builders
- Diataxis: how-to
- Find runnable local, browser, WebSocket, and telephony apps.

Commands:

```bash
uv run easycat init --list-templates
uv run easycat init my-agent
uv run easycat init --list-templates --json
uv run easycat doctor
uv run easycat doctor --json
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run python examples/journal_demo.py
uv run python examples/telephony_helpers.py
uv run python examples/openai_agents_voice.py
uv run --env-file .env python examples/openai_agents_voice.py
uv run easycat validate quick
uv run easycat validate quick --json
uv run easycat validate report .easycat/validation/latest.json
uv run easycat validate report .easycat/validation/latest.json --json
```

## Architecture

- Path: docs/architecture.md
- URL: https://github.com/yisding/easycat/blob/main/docs/architecture.md
- Audience: maintainers
- Diataxis: explanation
- Understand the pipeline, session collaborators, stages, providers, and agent bridges.

Commands:

```bash
uv run easycat docs --audience maintainers
uv run easycat docs --audience maintainers --json
```

## Maintainer guide

- Path: CLAUDE.md
- URL: https://github.com/yisding/easycat/blob/main/CLAUDE.md
- Audience: maintainers
- Diataxis: how-to
- Orient to the pipeline, packages, provider registries, lifecycle, and docs/onboarding guards.

Commands:

```bash
uv run easycat docs
uv run easycat docs --audience maintainers
uv run easycat docs --audience maintainers --json
uv run easycat docs --json
uv run easycat doctor --json
uv run easycat doctor --env-file .env --json
uv run easycat explain json-schema
uv run easycat bundles show PATH --json
uv run easycat bundles export PATH --output DIR --json
uv run easycat replay PATH --json
uv run pytest tests/install/test_install_guidance.py
just guard-docs
just guard-teaching
just guard-examples
just guard-contributing
just guard-validation
just guard-contracts
just guard-ops
uv run easycat validate quick
uv run easycat validate quick --json
uv run easycat validate contracts --json
uv run easycat validate release --json
uv run easycat validate report .easycat/validation/latest.json
uv run easycat validate report .easycat/validation/latest.json --json
```

## Coding agents

- Path: AGENTS.md
- URL: https://github.com/yisding/easycat/blob/main/AGENTS.md
- Audience: coding agents
- Diataxis: how-to
- Follow repo structure, development commands, docs/onboarding guards, and PR expectations.

Commands:

```bash
uv run easycat docs
uv run easycat docs --audience coding-agents
uv run easycat docs --audience coding-agents --json
uv run easycat docs --json
uv run easycat doctor --json
uv run easycat doctor --env-file .env --json
uv run easycat explain json-schema
uv run easycat bundles show PATH --json
uv run easycat bundles export PATH --output DIR --json
uv run easycat replay PATH --json
just guard-docs
just guard-teaching
just guard-examples
just guard-contributing
just guard-validation
just guard-contracts
just guard-ops
uv run easycat validate quick
uv run easycat validate quick --json
uv run easycat validate contracts --json
uv run easycat validate release --json
uv run easycat validate report .easycat/validation/latest.json
uv run easycat validate report .easycat/validation/latest.json --json
```

## Developer textbook

- Path: docs/development/
- URL: https://github.com/yisding/easycat/tree/main/docs/development
- Audience: maintainers
- Diataxis: explanation
- Work through the chapter-by-chapter source, test, decision, and change-recipe tour for new maintainers.

Commands:

```bash
uv run easycat docs --audience maintainers
uv run python scripts/regen_llms_txt.py
just guard-docs
just guard-contributing
```

## Session graduation

- Path: docs/from-easyconfig-to-session.md
- URL: https://github.com/yisding/easycat/blob/main/docs/from-easyconfig-to-session.md
- Audience: app builders
- Diataxis: how-to
- Graduate from the EasyConfig quickstart to the production Session API: lifecycle, events, text turns, session actions, and replayable debug bundles.

Commands:

```bash
uv run easycat docs --audience app-builders
uv run easycat docs --audience app-builders --json
uv run easycat replay PATH
uv run easycat replay PATH --json
uv run easycat inspect .easycat/journals/<session_id>.sqlite
```

## Testing and evals

- Path: docs/testing-and-evals.md
- URL: https://github.com/yisding/easycat/blob/main/docs/testing-and-evals.md
- Audience: app builders
- Diataxis: how-to
- Climb the eval ladder: bundle fixtures, offline text turns, latency budgets and LLM-as-judge, then live audio validation.

Commands:

```bash
uv run pytest tests/debug/test_testing_helpers.py
uv run python docs/teaching/12-evals-and-latency/llm_judge.py docs/teaching/12-evals-and-latency/bundles/turn_01_fast.bundle
uv run easycat doctor --env-file .env
uv run easycat doctor --env-file .env --json
uv run easycat validate latency --smoke
uv run --env-file .env easycat validate latency --smoke
uv run easycat validate live --provider openai
uv run --env-file .env easycat validate live --provider openai --strict
uv run easycat validate report .easycat/validation/latest.json
```

## Events reference

- Path: docs/reference/events.md
- URL: https://github.com/yisding/easycat/blob/main/docs/reference/events.md
- Audience: app builders
- Diataxis: reference
- Look up every public session event type and when it is emitted.

Commands:

```bash
uv run easycat explain events
uv run easycat docs --audience app-builders
```

## Journal records reference

- Path: docs/reference/journal-records.md
- URL: https://github.com/yisding/easycat/blob/main/docs/reference/journal-records.md
- Audience: app builders
- Diataxis: reference
- Look up stable built-in journal record names, kinds, and data-key contracts.

Commands:

```bash
uv run easycat explain journal
uv run easycat docs --audience app-builders
```

## EasyConfig reference

- Path: docs/reference/easyconfig.md
- URL: https://github.com/yisding/easycat/blob/main/docs/reference/easyconfig.md
- Audience: app builders
- Diataxis: reference
- Look up every EasyConfig construction field.

Commands:

```bash
uv run easycat docs --audience app-builders
```

## Session lifecycle

- Path: docs/reference/session-lifecycle.md
- URL: https://github.com/yisding/easycat/blob/main/docs/reference/session-lifecycle.md
- Audience: app builders
- Diataxis: reference
- Start, stop, force-stop, and read the journal after teardown.

Commands:

```bash
uv run easycat explain journal
```

## Browser playground

- Path: docs/browser-playground.md
- URL: https://github.com/yisding/easycat/blob/main/docs/browser-playground.md
- Audience: app builders
- Diataxis: how-to
- Talk to a bot in the browser with one command, and read the WebSocket/WebRTC wire protocol behind the playground page.

Commands:

```bash
uv sync --extra quickstart --extra webrtc --group dev
uv run easycat doctor
uv run easycat doctor --json
uv run easycat serve
uv run python examples/webrtc_server.py
uv run pytest tests/transports/test_webrtc_auth_browser_playground.py
```

## Public API

- Path: docs/public-api.md
- URL: https://github.com/yisding/easycat/blob/main/docs/public-api.md
- Audience: maintainers
- Diataxis: reference
- Review the stable import surface before changing exports.

Commands:

```bash
uv run easycat docs
uv run easycat docs --audience maintainers
uv run easycat docs --json
uv run easycat docs --audience maintainers --json
uv run easycat explain json-schema
uv run pytest tests/test_public_api.py
just guard-docs
```

## Provider contracts

- Path: tests/contracts/README.md
- URL: https://github.com/yisding/easycat/blob/main/tests/contracts/README.md
- Audience: provider maintainers
- Diataxis: how-to
- Maintain offline provider, protocol, cassette, and bridge contract coverage.

Commands:

```bash
uv run easycat docs --audience provider-maintainers
uv run easycat docs --audience provider-maintainers --json
uv run easycat validate contracts
uv run easycat validate contracts --json
uv run pytest tests/contracts
uv run pytest tests/contracts/test_provider_session_matrix.py
```

## Extending providers

- Path: docs/extending/
- URL: https://github.com/yisding/easycat/tree/main/docs/extending
- Audience: provider maintainers
- Diataxis: how-to
- Build custom STT, TTS, VAD, transport, and agent-bridge providers out of tree and verify conformance.

Commands:

```bash
uv run easycat docs --audience provider-maintainers
uv run easycat docs --audience provider-maintainers --json
uv run easycat init my-stt --template provider-stt
uv run easycat init my-tts --template provider-tts
uv run easycat init my-vad --template provider
uv run python examples/custom_transport.py
uv run pytest tests/test_public_api.py
uv run pytest tests/contracts
```

## Contributing

- Path: CONTRIBUTING.md
- URL: https://github.com/yisding/easycat/blob/main/CONTRIBUTING.md
- Audience: contributors
- Diataxis: how-to
- Follow the development loop, docs/onboarding guards, and validation slices.

Commands:

```bash
just guard-docs
just guard-teaching
just guard-examples
just guard-contributing
just guard-validation
just guard-contracts
just guard-ops
uv run easycat docs --audience contributors
uv run easycat docs --audience contributors --json
uv run pytest
uv run ruff check .
uv run easycat validate quick
uv run easycat validate socket
uv run easycat validate stress
uv run easycat validate contracts
uv run easycat validate latency --smoke
uv run easycat validate live --provider openai
uv run easycat validate release
uv run easycat validate report .easycat/validation/latest.json
uv run easycat validate quick --json
uv run easycat validate contracts --json
uv run easycat validate release --json
uv run easycat validate report .easycat/validation/latest.json --json
```

## Deployment

- Path: docs/deployment/docker.md
- URL: https://github.com/yisding/easycat/blob/main/docs/deployment/docker.md
- Audience: operators
- Diataxis: how-to
- Package the WebSocket example for container deployment.

Commands:

```bash
uv run easycat docs --audience operators
uv run easycat docs --audience operators --json
docker compose -f docker/compose.yaml up --build
python -m http.server 8080 --directory examples
docker compose --env-file docker/.env -f docker/compose.yaml up --build
docker compose -f docker/compose.yaml down
```

## Production servers

- Path: docs/deployment/production-servers.md
- URL: https://github.com/yisding/easycat/blob/main/docs/deployment/production-servers.md
- Audience: operators
- Diataxis: how-to
- Run multi-client WebSocket, WebRTC, WebTransport, and Twilio servers with one isolated EasyCat session per client or call.

Commands:

```bash
uv run easycat docs --audience operators
uv run easycat docs --audience operators --json
uv run python examples/ws_server.py
uv run python examples/webrtc_server.py
uv run python examples/webtransport_server.py
uv run uvicorn examples.twilio_app:create_app --factory --host 0.0.0.0
uv run pytest tests/transports/test_websocket_session_server.py
uv run pytest tests/transports/test_webrtc_config.py
uv run pytest tests/transports/test_webrtc_lifecycle_server.py
uv run pytest tests/transports/test_webtransport_session.py
```

## Observability

- Path: docs/observability.md
- URL: https://github.com/yisding/easycat/blob/main/docs/observability.md
- Audience: operators
- Diataxis: how-to
- Inspect journals, debug bundles, the debugger UI, metrics, and traces.

Commands:

```bash
uv run easycat docs --audience operators
uv run easycat docs --audience operators --json
easycat bundles list
easycat bundles list --json
easycat bundles show PATH
easycat bundles show PATH --json
easycat debugger serve PATH
easycat debugger serve PATH --no-open-browser
easycat inspect PATH
easycat inspect PATH --json
easycat replay PATH
easycat replay PATH --json
easycat latency PATH
easycat latency PATH --json
easycat diff PATH PATH
easycat journal grep PATH --query TEXT
easycat journal follow PATH
easycat journal promote PATH TURN_ID --out FILE
easycat tail PATH
easycat bundles export PATH
easycat bundles export PATH --output DIR --json
uv sync --extra debugger --group dev
```

## Latency

- Path: docs/latency.md
- URL: https://github.com/yisding/easycat/blob/main/docs/latency.md
- Audience: operators
- Diataxis: how-to
- Answer "why was that turn slow?" with per-turn CLI waterfalls and the table of latency-adding defaults.

Commands:

```bash
uv run easycat docs --audience operators
easycat bundles show PATH --json
easycat inspect PATH --json
easycat latency PATH
easycat latency PATH --json
uv run easycat validate latency --smoke
```

## Journal durability

- Path: src/easycat/runtime/DURABILITY.md
- URL: https://github.com/yisding/easycat/blob/main/src/easycat/runtime/DURABILITY.md
- Audience: operators and maintainers
- Diataxis: explanation
- Understand SQLite journal persistence, recovery, and storage layout.

Commands:

```bash
uv run easycat docs --audience operators-and-maintainers
uv run easycat docs --audience operators-and-maintainers --json
uv run pytest tests/runtime/test_sqlite_journal.py
uv run easycat inspect .easycat/journals/<session_id>.sqlite
uv run easycat inspect .easycat/journals/<session_id>.sqlite --json
uv run easycat inspect .easycat/crash-dumps/<session_id>.sqlite --json
```

## Validation

- Path: docs/validation.md
- URL: https://github.com/yisding/easycat/blob/main/docs/validation.md
- Audience: contributors
- Diataxis: how-to
- Run docs/onboarding guards, the right validation lane, and inspect .easycat/validation/latest.json.

Commands:

```bash
just guard-docs
just guard-teaching
just guard-examples
just guard-contributing
just guard-validation
just guard-contracts
just guard-ops
uv run easycat validate quick
uv run easycat validate socket
uv run easycat validate stress
uv run easycat validate contracts
uv run easycat validate latency --smoke
uv run easycat validate live
uv run easycat validate release
uv run easycat validate report .easycat/validation/latest.json
uv run easycat validate quick --json
uv run easycat validate contracts --json
uv run easycat validate release --json
uv run easycat validate report .easycat/validation/latest.json --json
```

## Validation reference

- Path: docs/reference/validation-vocabulary.md
- URL: https://github.com/yisding/easycat/blob/main/docs/reference/validation-vocabulary.md
- Audience: release maintainers
- Diataxis: reference
- Read provider and report vocabulary used by validation.

Commands:

```bash
easycat docs --audience release-maintainers
easycat docs --audience release-maintainers --json
easycat validate quick --json
easycat validate contracts --json
easycat validate release --json
easycat validate report .easycat/validation/latest.json --json
```
