docs: add AGENTS.md, CLAUDE.md, implementation plan; ignore downloaded media/transcript artifacts

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

.gitignore

@@ -26,3 +26,13 @@ htmlcov/
 *.mp3
 *.m4a
 cookies.txt
+
+# Downloaded outputs (artifacts, not source)
+*.mp4
+*.mov
+*.wav
+*.txt
+!requirements*.txt
+space_*.json
+space_*.txt
+.DS_Store

AGENTS.md

@@ -0,0 +1,27 @@
+# X Space Downloader
+
+Three-module CLI tool that wraps yt-dlp to download X/Twitter Space recordings as MP3.
+
+## Commands
+
+```bash
+pip install -e .                          # Install (editable)
+x-space-dl <URL>                          # Run the CLI
+python -m src.main <URL>                  # Alternative invocation
+pytest                                    # Run all tests
+pytest -m "not integration"               # Unit tests only
+pytest -m integration                     # Integration tests only
+pytest tests/test_validator.py::test_valid_x_url  # Single test
+```
+
+## Architecture
+
+- **`src/main.py`** -- Click CLI entry point. Validates URL via validator, delegates to downloader. Registered as `x-space-dl` console script.
+- **`src/validator.py`** -- `validate_space_url()` returns `(is_valid, space_id, error_message)`. Accepts both `x.com` and `twitter.com` domains.
+- **`src/downloader.py`** -- `download_space()` configures yt-dlp with `bestaudio/best` format and FFmpeg MP3 postprocessor. Output: `space_{SPACE_ID}.mp3`. Raises `DownloadError` on failure.
+
+## Dependencies
+
+Runtime: `yt-dlp`, `click`. System: `ffmpeg`. Dev: `pytest`, `pytest-mock`.
+
+Tests mock `yt_dlp.YoutubeDL` -- no network calls in unit tests. Integration tests use `@pytest.mark.integration`.

CLAUDE.md

@@ -0,0 +1,40 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Commands
+
+```bash
+# Install (editable)
+pip install -e .
+
+# Run the CLI
+x-space-dl <URL>
+python -m src.main <URL>
+
+# Run all tests
+pytest
+
+# Run a single test
+pytest tests/test_validator.py::test_valid_x_url
+
+# Run only unit tests (skip integration)
+pytest -m "not integration"
+
+# Run only integration tests
+pytest -m integration
+```
+
+## Architecture
+
+Three-module CLI tool that wraps yt-dlp to download X/Twitter Space recordings as MP3:
+
+- **`src/main.py`** — Click CLI entry point (`cli`). Validates URL via validator, then delegates to downloader. Registered as `x-space-dl` console script.
+- **`src/validator.py`** — `validate_space_url()` returns `(is_valid, space_id, error_message)` tuple. Accepts both `x.com` and `twitter.com` domains.
+- **`src/downloader.py`** — `download_space()` configures yt-dlp with `bestaudio/best` format and FFmpeg MP3 postprocessor. Output files are named `space_{SPACE_ID}.mp3`. Raises `DownloadError` on failure.
+
+Tests mock `yt_dlp.YoutubeDL` — no network calls in unit tests. Integration tests use the `@pytest.mark.integration` marker.
+
+## Dependencies
+
+Runtime: `yt-dlp`, `click`. System: `ffmpeg`. Dev: `pytest`, `pytest-mock`.