langlearn-tts: Instructions file for Claude Code

CLAUDE.md

No "Pre-existing" Excuse

There is no such thing as a "pre-existing" issue. If you see a problem — in code you wrote, code a reviewer flagged, or code you happen to be reading — you fix it. Do not classify issues as "pre-existing" to justify ignoring them. Do not suggest that something is "outside the scope of this change." If it is broken and you can see it, it is your problem now.

Project Overview

TTS MCP server and CLI for language learning. Supports ElevenLabs (premium), AWS Polly, and OpenAI TTS.

• Package: punt-langlearn-tts
• CLI: langlearn-tts
• MCP server: langlearn-tts-server
• Python: 3.13+, managed with uv

Build & Run

# Install with dev dependencies
uv sync --all-extras

# CLI
uv run langlearn-tts --help
uv run langlearn-tts doctor

# MCP server (stdio transport)
uv run langlearn-tts-server

Scratch Files

Use .tmp/ at the project root for scratch and temporary files — never /tmp. The TMPDIR environment variable is set via .envrc so that tempfile and subprocesses automatically use it. Contents are gitignored; only .gitkeep is tracked.

Quality Gates

Run after every code change. All must pass with zero violations.

uv run ruff check src/ tests/        # Lint
uv run ruff format --check src/ tests/ # Format check
uv run mypy src/ tests/               # Type check (strict)
uv run pyright src/ tests/            # Type check (strict)
uv run pytest tests/ -v               # All tests pass

Build validation:

uv build
uvx twine check dist/*

Architecture

langlearn-tts is a thin bridge over punt-vox. The TTS engine (types, core, providers) lives in punt-vox; langlearn-tts adds langlearn-specific output path resolution, branding, and the AudioProvider protocol from langlearn-types.

Module structure under src/langlearn_tts/:

Module	Responsibility
types.py	Re-exports from punt_vox.types (TTSProvider, HealthCheck, SynthesisRequest, SynthesisResult, MergeStrategy, etc.) plus AudioProvider protocol from langlearn_types for the orchestrator boundary
core.py	Re-exports TTSClient, split_text, stitch_audio from punt_vox.core
output.py	langlearn-specific output path resolution: TTS_OUTPUT_DIR env var → ~/langlearn-audio default
cli.py	Click CLI — --provider flag, voice settings flags, synthesize, batch, pair, pair-batch, doctor, install
server.py	FastMCP server — exposes same operations as MCP tools
providers/__init__.py	Provider registry, get_provider(), auto-detection (ElevenLabs > Polly)
providers/polly.py	Thin subclass of punt_vox.providers.polly.PollyProvider — overrides generate_audio/generate_audios for langlearn output path resolution
providers/openai.py	Thin subclass of punt_vox.providers.openai.OpenAIProvider — same pattern
providers/elevenlabs.py	Thin subclass of punt_vox.providers.elevenlabs.ElevenLabsProvider — same pattern