docs: add comprehensive README with usage and installation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

README.md

@@ -0,0 +1,162 @@
+# X Space Downloader
+
+A Python CLI tool that downloads X (Twitter) Space recordings and outputs them as MP3 files.
+
+## Features
+
+- Download X Space recordings as MP3 files
+- Support for authenticated downloads using cookies
+- Simple command-line interface
+- Clear error messages
+
+## Installation
+
+### Prerequisites
+
+- Python 3.8 or higher
+- ffmpeg (required by yt-dlp for audio conversion)
+
+Install ffmpeg:
+```bash
+# macOS
+brew install ffmpeg
+
+# Ubuntu/Debian
+sudo apt install ffmpeg
+
+# Windows
+# Download from https://ffmpeg.org/download.html
+```
+
+### Install the tool
+
+```bash
+git clone https://github.com/synapz-org/x-space-downloader.git
+cd x-space-downloader
+pip install -e .
+```
+
+## Usage
+
+### Basic usage
+
+```bash
+x-space-dl https://x.com/i/spaces/1ZkKzZWnVRRKv
+```
+
+This will download the Space recording and save it as `space_1ZkKzZWnVRRKv.mp3` in the current directory.
+
+### With authentication (recommended)
+
+For better reliability and access to private Spaces, provide cookies from your logged-in X session:
+
+```bash
+x-space-dl --cookies cookies.txt https://x.com/i/spaces/1ZkKzZWnVRRKv
+```
+
+### Specify output directory
+
+```bash
+x-space-dl --output ~/Downloads https://x.com/i/spaces/1ZkKzZWnVRRKv
+```
+
+### Full options
+
+```bash
+x-space-dl --help
+```
+
+## Exporting Cookies
+
+To download Spaces that require authentication, you need to export cookies from your logged-in X session.
+
+### Method 1: Browser Extension (Easiest)
+
+1. Install a cookie export extension:
+   - Chrome/Edge: [Get cookies.txt LOCALLY](https://chrome.google.com/webstore/detail/get-cookiestxt-locally/cclelndahbckbenkjhflpdbgdldlbecc)
+   - Firefox: [cookies.txt](https://addons.mozilla.org/en-US/firefox/addon/cookies-txt/)
+
+2. Log in to X (twitter.com or x.com)
+3. Click the extension icon and export cookies
+4. Save as `cookies.txt`
+
+### Method 2: Manual Export (Advanced)
+
+1. Log in to X
+2. Open Developer Tools (F12)
+3. Go to Application/Storage → Cookies
+4. Copy cookies in Netscape format to a file
+
+## Requirements
+
+- Python 3.8+
+- yt-dlp
+- click
+- ffmpeg (system dependency)
+
+## Supported URLs
+
+The tool supports X Space URLs in these formats:
+
+- `https://x.com/i/spaces/{SPACE_ID}`
+- `https://twitter.com/i/spaces/{SPACE_ID}`
+
+**Note:** Only recordings are supported. Live Spaces must be recorded before downloading.
+
+## Error Messages
+
+| Error | Meaning |
+|-------|---------|
+| "Invalid URL format" | URL doesn't match X Space format |
+| "Failed to download Space" | Recording not found or network error |
+| "Authentication required" | Space requires login (use --cookies) |
+
+## Development
+
+### Running tests
+
+```bash
+pip install pytest pytest-mock
+pytest
+```
+
+### Project structure
+
+```
+x-space-downloader/
+├── src/
+│   ├── main.py          # CLI entry point
+│   ├── downloader.py    # yt-dlp wrapper
+│   └── validator.py     # URL validation
+├── tests/
+│   ├── test_main.py
+│   ├── test_downloader.py
+│   └── test_validator.py
+└── docs/
+    └── plans/           # Design documents
+```
+
+## License
+
+MIT License - See LICENSE file for details
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request.
+
+## Troubleshooting
+
+### "ffmpeg not found"
+Install ffmpeg using your system's package manager (see Installation section).
+
+### "Video unavailable"
+The Space recording may have been deleted or is private. Try using the --cookies option.
+
+### "Authentication required"
+Export cookies from your logged-in X session and use the --cookies option.
+
+## Acknowledgments
+
+Built with:
+- [yt-dlp](https://github.com/yt-dlp/yt-dlp) - Media downloader
+- [Click](https://click.palletsprojects.com/) - CLI framework