docs: add project README

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

README.md

@@ -0,0 +1,257 @@
+# gallery-dl (Rust)
+
+`gallery-dl` is a command-line image and media downloader written in Rust.
+It supports a large extractor registry (hundreds of site modules), configurable download behavior, archive-based duplicate skipping, and optional post-processing.
+
+## Highlights
+
+- Works with many websites through a pluggable extractor registry
+- Concurrent downloads with retry/backoff, rate limits, and resume support
+- Duplicate protection with a SQLite download archive
+- Flexible output modes: direct download, URL/JSON dump, simulated runs
+- Post-processing options: metadata sidecars, ZIP/CBZ, exec hooks, ugoira conversion
+- Config files in JSON, YAML, or TOML
+
+## Installation
+
+### From source
+
+```bash
+cargo build --release
+```
+
+Binary path:
+
+- Unix/macOS: `target/release/gallery-dl`
+- Windows: `target\release\gallery-dl.exe`
+
+### Install via Cargo
+
+```bash
+cargo install --path .
+```
+
+Or install directly from GitHub:
+
+```bash
+cargo install --git https://github.com/mikf/gallery-dl-rs --locked
+```
+
+## Quick Start
+
+Download from one URL:
+
+```bash
+gallery-dl "https://example.com/post/123"
+```
+
+Download to a directory with a custom filename template:
+
+```bash
+gallery-dl -D downloads -f "{num}.{ext}" "https://example.com/post/123"
+```
+
+Dry-run (extract only, no file writes):
+
+```bash
+gallery-dl --simulate "https://example.com/post/123"
+```
+
+Read URLs from a file:
+
+```bash
+gallery-dl -i urls.txt
+```
+
+Read URLs and comment/remove successful entries:
+
+```bash
+gallery-dl -I urls.txt
+gallery-dl -x urls.txt
+```
+
+Discover supported modules and extractors:
+
+```bash
+gallery-dl --list-modules
+gallery-dl --list-extractors
+gallery-dl --list-extractors reddit pixiv
+```
+
+## Common Workflows
+
+Only print resolved media URLs:
+
+```bash
+gallery-dl -g "https://example.com/post/123"
+```
+
+Output lightweight JSON records:
+
+```bash
+gallery-dl -j "https://example.com/post/123"
+```
+
+Save metadata sidecars:
+
+```bash
+gallery-dl --write-infojson --write-metadata --write-tags "https://example.com/post/123"
+```
+
+Enable archive-based duplicate skipping:
+
+```bash
+gallery-dl --download-archive-skip-duplicates "https://example.com/post/123"
+```
+
+Or choose an explicit archive path:
+
+```bash
+gallery-dl --download-archive ./archive.db "https://example.com/post/123"
+```
+
+## Configuration
+
+Create a starter config:
+
+```bash
+gallery-dl --config-create
+```
+
+Check loaded/default config locations:
+
+```bash
+gallery-dl --config-status
+```
+
+Open your main config file with the system default app:
+
+```bash
+gallery-dl --config-open
+```
+
+Default config search paths:
+
+- Linux: `~/.config/gallery-dl/config.json`, `~/.gallery-dl.conf`, `/etc/gallery-dl.conf`
+- macOS: `~/Library/Application Support/gallery-dl/config.json`
+- Windows: `%APPDATA%\gallery-dl\config.json`
+
+Example `config.json`:
+
+```json
+{
+  "extractor": {
+    "timeout": 30,
+    "user_agent": "gallery-dl-rs/1.0"
+  },
+  "downloader": {
+    "directory": "downloads",
+    "parallel": 4,
+    "retry": 3
+  },
+  "output": {
+    "log": "gallery-dl.log"
+  }
+}
+```
+
+Override config values from CLI:
+
+```bash
+gallery-dl -o downloader.parallel=8 -o extractor.timeout=45 "https://example.com/post/123"
+```
+
+## Authentication
+
+Use Netscape cookies file:
+
+```bash
+gallery-dl -C cookies.txt "https://example.com/protected"
+```
+
+Extract cookies from a browser profile (currently `firefox`, `chrome`, `chromium`):
+
+```bash
+gallery-dl --cookies-from-browser firefox "https://example.com/protected"
+```
+
+Use username/password or `.netrc`:
+
+```bash
+gallery-dl -u USER -p PASS "https://example.com/protected"
+gallery-dl --netrc "https://example.com/protected"
+```
+
+## Filtering and Selection
+
+Filter by size and type:
+
+```bash
+gallery-dl --filesize-min 200kb --filesize-max 20mb --filter-type "image/jpeg,image/png,image/webp" URL
+```
+
+Select ranges and message-level filters:
+
+```bash
+gallery-dl --range "1-20" --filter "kind == 'url'" URL
+gallery-dl --file-range "1-5" --file-filter "extension == 'jpg'" URL
+```
+
+## Post-Processing
+
+Create ZIP/CBZ archives:
+
+```bash
+gallery-dl --zip downloads.zip URL
+gallery-dl --cbz URL
+```
+
+Run a command for each downloaded file:
+
+```bash
+gallery-dl --exec echo "{}" URL
+```
+
+Ugoira handling:
+
+```bash
+gallery-dl --ugoira webm URL
+gallery-dl --ugoira mp4 URL
+```
+
+Disable post-processors entirely:
+
+```bash
+gallery-dl --no-postprocessors URL
+```
+
+## Logging and Debugging
+
+- Increase verbosity: `-v`, `-vv`
+- Quiet mode: `-q`, `-qq`
+- Log HTTP traffic: `--print-traffic`
+- Write logs to file: `--write-log gallery-dl.log`
+- Capture failures: `--error-file failed.txt`, `--write-unsupported unsupported.txt`
+
+## Development
+
+Run tests:
+
+```bash
+cargo test --all-targets --all-features
+```
+
+Run locally:
+
+```bash
+cargo run -- --help
+```
+
+## Notes
+
+- Use this tool responsibly and follow the terms of service/copyright rules of the sites you download from.
+- Some sites require authentication cookies or account-specific access.
+
+## License
+
+GPL-2.0. See `LICENSE`.