Documentation site: mdBook user + contributor guide (2.2)

An mdBook under docs/ rendering eight pages: introduction,
installation, first-run/config, downloading, an anti-bot guide that
captures the hard-won cookies/curl_cffi/POT/player-client knowledge,
troubleshooting (the nine error classes + non-download issues),
architecture (the two-front-ends/one-engine design, settings flow,
layout invariant, persistence), and packaging.

- .forgejo/workflows/docs.yml builds the book and publishes docs/book/
  to the `pages` branch for Codeberg Pages on docs/ changes.
- docs/book/ is gitignored (rendered output).
- README: fix the stale backup.directory comment — every platform nests
  under the one library root, not a channels/ sibling split.
- Add CLAUDE.md (repo guidance for Claude Code).

Builds clean with mdbook 0.5; intra-doc anchor links verified.

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

docs/src/downloading.md

@@ -0,0 +1,74 @@
+# Downloading
+
+## Starting a download
+
+Paste any supported URL into the download bar (desktop) or the ⬇
+Downloads modal (web). yt-offline classifies the URL by platform, routes
+it to the right folder, and starts yt-dlp. A channel/playlist URL pulls
+the whole thing; a single-video URL pulls just that one.
+
+**Quality picker:** Best / 1080p / 720p / 480p / 360p, or **Music mode**
+for audio-only extraction into `music/<artist>/`.
+
+**Fast mode** stops at the first already-downloaded video (quick routine
+re-checks). Turn it off for a full gap-filling scan.
+
+## Per-channel options
+
+Right-click a channel (or use the ⚙ on its sidebar row) for overrides
+that apply to scheduled re-checks and the "Check for new videos" action:
+
+- Quality cap, audio-only, bandwidth cap, min/max file size, date cutoff.
+- A free-form `--match-filter` (e.g. `duration > 60 & view_count > 100`).
+- Subtitle overrides, YouTube player-client override, post-download
+  convert mode — each defaulting to the global setting.
+- **Skip auth check** — silences yt-dlp's "playlists that require
+  authentication" warning for **public** channels (see
+  [Troubleshooting](./troubleshooting.md#the-youtubetab-authentication-warning)).
+
+Per-channel options ride along in library backup/restore.
+
+## Subtitles
+
+Global defaults (Settings → Subtitles) + per-channel overrides control:
+download on/off, auto-generated captions, embedding into the container,
+language filter, and format conversion (`srt` is the most
+Plex/player-compatible). Subtitles are written as sidecar files and
+optionally embedded.
+
+## Format conversion
+
+A post-download ffmpeg pass (Settings → Format conversion, or per
+channel):
+
+- **Remux → mp4** — instant container change, no re-encode (device/Plex
+  compatibility).
+- **Re-encode → H.264 mp4** — shrink large 4K files at a chosen CRF +
+  x264 preset.
+- **Extract audio** — mp3 / m4a / opus / flac.
+
+It runs as a distinct transcode job after the download. **Keep original**
+preserves `<name>.original.<ext>` alongside the converted file; otherwise
+the source is removed once the convert succeeds.
+
+## Resilience
+
+Downloads are hardened against YouTube's flakiness automatically:
+
+- **Retry + backoff** on connection resets (`--retries 30`, linear
+  retry-sleep).
+- **Jittered throttle** between videos so a long channel scan doesn't
+  look robotic and trip the captcha wall.
+- **Auto-retry** of transient (rate-limit / network / captcha) failures
+  after a cooldown, with adaptive slow-down for the rest of the batch.
+- **Hang watchdog** kills a job that produces no output for 5 minutes (a
+  wedged request) and re-queues it.
+
+Failures are classified and shown with a one-line suggested fix — see
+[Troubleshooting](./troubleshooting.md).
+
+## Scheduler
+
+Enable it (Settings → Auto-check channels) to re-check every channel for
+new uploads on an interval. Each channel uses its own stored options.
+There's also a per-folder "Check all" action.