init: media-acquisition pipeline scaffold

Self-hosted BitTorrent + arr-stack + catalog-update pipeline targeting nullstone (Debian 13). Replaces the legacy onyx -> rsync -> import round-trip. Contents: - README.md headline + ASCII architecture diagram + quickstart - CLAUDE.md project rules (mirrors beta-flix style) - .gitignore secrets dirs (.env, gluetun, qbt config, ssh keys) - .gitleaksignore allowlist nullstone LAN addr + Tailscale CGNAT - docs/architecture.md the plan in detail (gluetun + qbt + arr + catalog) - docs/migration.md onyx-qbt -> nullstone-qbt runbook (3 phases) - docs/trackers.md tracker schema + IP-pinning + ratio notes (user-curated) - compose/docker-compose.yml gluetun v3.40 + qbt 5.0.5 (netns=gluetun) + sonarr/radarr/prowlarr (hotio) + betaflix-catalog - compose/.env.example documented env-var template (no secrets) - compose/traefik/arr.yml file-provider for qbt/sonarr/radarr/prowlarr .s8n.ru subdomains, LAN+TS only via trusted-only@file + authentik-forwardauth@file - catalog/catalog.py Flask service, ~340 LoC, /sonarr + /radarr + /healthz; pulls beta-flix, inserts alphabetic row into MEDIA-LIST.md, writes run log, commits + pushes as obsidian-ai. Idempotent via payload-hash cache. - catalog/Dockerfile python:3.12-slim + git + tini - catalog/requirements.txt flask + jinja2 + requests + gitpython + pyyaml (pinned) - catalog/templates/*.j2 run log + catalog row Jinja templates - catalog/README.md service docs - scripts/migrate-onyx.sh phase-2 helper (rsync + .torrent ship, dry-run by default) - scripts/add-tracker.sh Prowlarr API helper - scripts/killswitch-test.sh gluetun kill-switch verification (3 steps) Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-20 01:15:43 +01:00 · 2026-05-20 01:15:43 +01:00 · d300d83ce1
commit d300d83ce1
19 changed files with 1758 additions and 0 deletions
--- a/.gitignore
+++ b/.gitignore
@ -0,0 +1,43 @@
 # --- Secrets ---
 .env
 .env.local
 *.key
 *.pem
 *.crt
 catalog/ssh/
 compose/gluetun/
 compose/qbittorrent/config/
 compose/sonarr/
 compose/radarr/
 compose/prowlarr/
 compose/catalog/ssh/
 # --- Caches / runtime ---
 __pycache__/
 *.pyc
 *.pyo
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
 *.sqlite
 *.sqlite-journal
 seen-imports.json
 # --- Editor ---
 .vscode/
 .idea/
 *.swp
 *.swo
 *~
 .DS_Store
 # --- Build artefacts ---
 *.tar
 *.tar.gz
 dist/
 build/
 *.egg-info/
 # --- Logs ---
 *.log
 logs/
--- a/.gitleaksignore
+++ b/.gitleaksignore
@ -0,0 +1,27 @@
 # Allowlist false-positive LAN-IP / tailnet-IP hits in docs + compose.
 # These are the documented nullstone LAN address, the LAN/CGNAT
 # allowed-egress subnets baked into gluetun config, and Proton WG client
 # addresses — all infrastructure facts, not credentials.
 # The lan-ip-rfc1918 rule is low-confidence by design — see ~/.config/git/.gitleaks.toml
 # CLAUDE.md — header references nullstone LAN IP.
 CLAUDE.md:lan-ip-rfc1918:9
 # docs/architecture.md — header + § "Current State" reference live nullstone host.
 docs/architecture.md:lan-ip-rfc1918:3
 docs/architecture.md:lan-ip-rfc1918:30
 # docs/migration.md — ssh + rsync targets to nullstone.
 docs/migration.md:lan-ip-rfc1918:22
 docs/migration.md:lan-ip-rfc1918:32
 docs/migration.md:lan-ip-rfc1918:81
 # scripts/migrate-onyx.sh — default NULLSTONE_SSH and ssh target.
 scripts/migrate-onyx.sh:lan-ip-rfc1918:27
 scripts/migrate-onyx.sh:lan-ip-rfc1918:35
 # compose/docker-compose.yml — FIREWALL_OUTBOUND_SUBNETS allows LAN +
 # RFC1918 + the Tailscale CGNAT range for webui reachability from
 # trusted networks. These are public, well-known subnet constants.
 compose/docker-compose.yml:lan-ip-rfc1918:26
 compose/docker-compose.yml:tailnet-ip:26
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -0,0 +1,109 @@
 # CLAUDE.md — media-acquisition
 Read this at session start. Rules for managing the nullstone media-acquisition
 pipeline.
 ## What this repo is
 The BitTorrent + arr-stack + catalog-update pipeline that feeds the ARRFLIX
 library on **nullstone** (Debian 13, `192.168.0.100`). Consumed by:
 - **Jellyfin** at `tv.s8n.ru` (container `jellyfin-stock`).
 - **Catalog** at `git.s8n.ru/s8n/beta-flix` → `playbooks/import-media/MEDIA-LIST.md`.
 ## Source map
 ```
 docs/architecture.md         Plan + reasoning. Read this BEFORE editing compose.
 docs/migration.md            onyx-qbt → nullstone-qbt migration runbook.
 docs/trackers.md             Tracker schema + IP-pinning risks (user-curated).
 compose/docker-compose.yml   gluetun + qbt + sonarr + radarr + prowlarr + catalog.
 compose/.env.example         Env template — secrets live in .env (gitignored).
 compose/traefik/arr.yml      File-provider routing for arr stack.
 catalog/                     betaflix-catalog Python service (Flask + webhooks).
 scripts/                     migrate-onyx.sh, add-tracker.sh, killswitch-test.sh.
 ```
 ## Deploy lifecycle
 1. **Edit** files locally under `/home/admin/projects/media-acquisition/`.
 2. **Push to Forgejo** (this repo's authoritative remote is
   `git.s8n.ru/s8n/media-acquisition.git`).
 3. **On nullstone**: `cd /opt/docker/media-acquisition && git pull && docker compose up -d`.
 4. **CRITICAL — verify kill-switch after every gluetun change**:
   `bash scripts/killswitch-test.sh`. If the second curl succeeds, you have a leak;
   tear down before re-trying.
 ## Rules paid for in blood (mirrored from beta-flix where applicable)
 ### Rule 1 — SSH user
 `user@nullstone`. **NOT** `admin@nullstone`. AllowUsers was tightened
 2026-05-03; uid 1000 only. Memory: `[[feedback_nullstone_ssh_user]]`.
 ### Rule 2 — Commit + push to **my git**
 Authoritative remote is `git.s8n.ru/s8n/media-acquisition.git` (Forgejo).
 No GitHub mirror. Always `git remote -v` before push. Memory:
 `[[feedback_always_commit_to_my_git]]`, `[[feedback_check_remote_before_push]]`,
 `[[feedback_my_git_is_forgejo]]`.
 ### Rule 3 — Commit identity
 - Human commits: `s8n <admin@s8n.ru>`.
 - Bot/automation commits (e.g. catalog service, scripted edits): `obsidian-ai <obsidian-ai@s8n.ru>`.
 Memory: `[[user_git_identity]]`.
 ### Rule 4 — Kill-switch is non-negotiable
 Every change to `gluetun` service or VPN env vars MUST be followed by
 `scripts/killswitch-test.sh`. A torrent client leaking outside the VPN is the
 single failure mode that defines this project — do not "trust" the firewall
 based on config inspection. Run the test.
 ### Rule 5 — No secrets in repo
 `.env`, WireGuard keys, Forgejo PATs, deploy keys: all gitignored. Use
 `.env.example` to document variable names with placeholders. If you commit a
 secret by accident, rotate it (Proton WG: regenerate key, update gluetun;
 Forgejo PAT: revoke at `git.s8n.ru/-/user/settings/applications`).
 ### Rule 6 — Tracker IP pinning
 Private trackers may pin sessions to a single source IP. Switching from
 onyx public IP → Proton exit IP will trip them. Before adding a new tracker
 or migrating an old torrent, check `docs/trackers.md` for the per-tracker
 policy. Update `docs/trackers.md` whenever a new tracker is on-boarded.
 ### Rule 7 — XFS reflinks / hardlinks
 `/home/user/media` is XFS, single device. Sonarr/Radarr "Use Hardlinks
 instead of Copy" = ON. Catalog service may use `cp --reflink=always` for
 divergent-perm scenarios (free inodes, zero block cost). Never `cp` plain;
 that doubles disk usage and breaks seeding atomicity.
 ## Canonical naming
 Catalog rows pushed to `beta-flix/playbooks/import-media/MEDIA-LIST.md` follow
 the ARRFLIX house style:
 - TV: `Series Title (Year)` — alphabetic by title, year tiebreaker.
 - Movies: `Movie Title (Year)` — alphabetic by title.
 - "Source / Version" column = raw Sonarr/Radarr `sourceTitle` (release name).
  Human edits to "Why on arrflix" stay; bot never overwrites that column.
 The catalog service is **append + merge only** — never overwrites human-authored
 notes.
 ## How to start a session
 1. Read this file.
 2. Read `docs/architecture.md` if working on compose or catalog code.
 3. Check `git status` and `git remote -v` (must show
   `git.s8n.ru/s8n/media-acquisition.git`).
 4. Owner says what they want; ship + verify kill-switch + commit to Forgejo.
 5. End every turn: commit + push to `git.s8n.ru/s8n/media-acquisition.git`.
 ## Glossary
 | Term                  | Means                                                                            |
 |-----------------------|----------------------------------------------------------------------------------|
 | **ship** / **deploy** | git push to Forgejo → on nullstone, `git pull && docker compose up -d`. Kill-switch test on any gluetun change. |
 | **migrate**           | Phase-2 onyx→nullstone runbook in `docs/migration.md`. Read `scripts/migrate-onyx.sh` first; dry-run mode mandatory. |
 | **add tracker**       | `scripts/add-tracker.sh <name> <url>`; then update `docs/trackers.md` with IP-pinning policy + ratio requirements. |
 | **killswitch test**   | `bash scripts/killswitch-test.sh`. NEVER claim "VPN works" without running this. |
 | **owner**             | P (xynki.dev@gmail.com). Final say. Executive-override pattern from `[[feedback_s8n_executive_override]]` applies. |
--- a/README.md
+++ b/README.md
@ -0,0 +1,107 @@
 # media-acquisition
 Self-hosted BitTorrent + arr-stack + canonical-import pipeline that lands torrents
 directly on **nullstone**, through a Proton WireGuard VPN with verified kill-switch,
 hardlinks files into the existing ARRFLIX library, and auto-commits catalog rows
 to `git.s8n.ru/s8n/beta-flix`.
 Replaces the legacy `onyx → rsync → nullstone` round-trip.
 ## Architecture
 ```
                                    +-----------------+
                                    |  Proton VPN     |
                                    |  (WireGuard)    |
                                    +--------+--------+
                                             | wg0
                                             v
 +------------+   indexer queries   +-------------------+   torrent traffic
 |  Prowlarr  |-------------------->|     gluetun       |<------------------+
 +-----+------+   (via netns)       |  kill-switch fw   |                   |
      |                            +-------------------+                   |
      | search                       ^      ^     ^                        |
      v                              |      |     |                        |
 +------------+   grabs    +----------+      |     +----------+             |
 |  Sonarr/   |----------->|         qBittorrent (netns=gluetun)            |
 |  Radarr    |            |  /home/user/media/_downloads/{incomplete,complete}
 +-----+------+            +-------------------------------------------------+
      |                                                                    
      | OnImport webhook (POST /sonarr or /radarr)                          
      v                                                                    
 +--------------------+                                                      
 | betaflix-catalog   |--+ XFS reflink/hardlink into /home/user/media/{movies,tv}
 | (Flask, Python)    |  |
 +--------+-----------+  +--> Jellyfin (tv.s8n.ru) picks up new items
         |
         | git commit + push (obsidian-ai)
         v
 +-----------------------------+
 | git.s8n.ru/s8n/beta-flix    |
 | playbooks/import-media/     |
 |  MEDIA-LIST.md (updated)    |
 |  runs/<slug>.md (new)       |
 +-----------------------------+
 ```
 Single XFS filesystem at `/home/user/media` → hardlinks / reflinks are free.
 ## Quickstart
 ```bash
 # Clone on nullstone
 ssh user@nullstone
 git clone https://git.s8n.ru/s8n/media-acquisition.git /opt/docker/media-acquisition
 cd /opt/docker/media-acquisition/compose
 # Configure
 cp .env.example .env
 ${EDITOR:-vi} .env       # fill in PVPN_WG_PRIVKEY, PVPN_WG_ADDRESSES, FORGEJO_PUSH_TOKEN, etc.
 # Bring up
 docker compose up -d
 # Verify VPN kill-switch (CRITICAL — do not skip)
 bash ../scripts/killswitch-test.sh
 # Sanity: pick a sacrificial legal torrent in qbt UI, confirm it lands in
 # /home/user/media/_downloads/complete/ and arr stack hardlinks it.
 ```
 ## Layout
 ```
 README.md                  This file.
 CLAUDE.md                  Project rules for Claude Code.
 docs/
  architecture.md          The plan in detail. Decision log + reasoning.
  migration.md             onyx-qbt → nullstone-qbt migration runbook.
  trackers.md              Tracker schema + IP-pinning notes (user fills in).
 compose/
  docker-compose.yml       Full stack: gluetun + qbt + sonarr + radarr + prowlarr + catalog.
  .env.example             All env vars documented.
  traefik/arr.yml          Traefik file-provider for *.s8n.ru subdomains (LAN+TS only).
 catalog/
  catalog.py               Flask webhook receiver → beta-flix catalog updater.
  Dockerfile               python:3.12-slim base.
  requirements.txt         Pinned versions.
  templates/               Jinja2 templates for run logs and catalog rows.
  README.md                Catalog service docs.
 scripts/
  migrate-onyx.sh          Phase-2 migration: rsync + .torrent mass-add.
  add-tracker.sh           Helper: add tracker to Prowlarr via API.
  killswitch-test.sh       Verify gluetun blocks traffic when VPN drops.
 ```
 ## Related
 - Plan: `docs/architecture.md`
 - Catalog target: `git.s8n.ru/s8n/beta-flix` (`playbooks/import-media/MEDIA-LIST.md`)
 - Jellyfin (consumer): `tv.s8n.ru` (`jellyfin-stock` container on nullstone)
 - Host docs: `ai-lab/SYSTEM.md`
 ## Status
 Scaffold. Live deploy pending VPN slot allocation + tracker IP-pinning review.
 Next step: fill in `compose/.env` and bring up gluetun + qbt only (no arr yet)
 to validate kill-switch.
--- a/catalog/Dockerfile
+++ b/catalog/Dockerfile
@ -0,0 +1,28 @@
 FROM python:3.12-slim
 ENV PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PIP_DISABLE_PIP_VERSION_CHECK=1
 # git is required for clone/pull/push; openssh-client for ssh remotes (future).
 RUN apt-get update \
 && apt-get install -y --no-install-recommends git openssh-client ca-certificates tini \
 && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY requirements.txt /app/requirements.txt
 RUN pip install -r requirements.txt
 COPY catalog.py /app/catalog.py
 COPY templates /app/templates
 # Forge globally so the bot identity persists even if env vars get dropped.
 RUN git config --global user.name "obsidian-ai" \
 && git config --global user.email "obsidian-ai@s8n.ru" \
 && git config --global pull.rebase true \
 && git config --global init.defaultBranch main
 EXPOSE 5055
 ENTRYPOINT ["/usr/bin/tini", "--"]
 CMD ["python", "/app/catalog.py"]
--- a/catalog/README.md
+++ b/catalog/README.md
@ -0,0 +1,73 @@
 # betaflix-catalog
 Flask service that receives Sonarr/Radarr **OnImport** webhooks and commits
 catalog updates to `git.s8n.ru/s8n/beta-flix`.
 ## What it does
 For each `Import` event:
 1. Pulls latest `main` of `beta-flix` (rebase).
 2. Inserts a row into `playbooks/import-media/MEDIA-LIST.md`, alphabetic by
   title. Dedupes — if the key (`Title (Year)`) already exists, it skips.
 3. Writes a per-import run log to
   `playbooks/import-media/runs/<slug>.md` using the Jinja template at
   `templates/run.md.j2`.
 4. Commits as `obsidian-ai <obsidian-ai@s8n.ru>`.
 5. Pushes to Forgejo using `FORGEJO_PUSH_TOKEN` embedded in the URL.
 Idempotency: payload-hash cache at `/state/seen-imports.json`. Sonarr/Radarr
 retry transient failures; duplicates are no-ops.
 ## Endpoints
 - `POST /sonarr` — Sonarr Connect webhook target. Set Sonarr → Settings →
  Connect → Webhook → URL `http://host.docker.internal:5055/sonarr`, method
  POST, triggers: **On Import** only.
 - `POST /radarr` — same shape for Radarr at `/radarr`.
 - `GET /healthz` — liveness probe.
 ## Build
 ```bash
 cd catalog/
 docker build -t betaflix-catalog:local .
 ```
 Or use compose: the parent `compose/docker-compose.yml` defines the
 `betaflix-catalog` service with `build:` set to this directory.
 ## Env vars
 | Variable             | Required | Default                                    | What                                  |
 |----------------------|----------|--------------------------------------------|---------------------------------------|
 | `FORGEJO_REMOTE`     | yes      | `https://git.s8n.ru/s8n/beta-flix.git`     | Push target.                          |
 | `FORGEJO_PUSH_TOKEN` | yes      | (empty)                                    | Forgejo PAT — scopes: repository RW.  |
 | `GIT_AUTHOR_NAME`    | no       | `obsidian-ai`                              | Commit author.                        |
 | `GIT_AUTHOR_EMAIL`   | no       | `obsidian-ai@s8n.ru`                       | Commit author email.                  |
 | `REPO_PATH`          | no       | `/repo`                                    | Where beta-flix gets cloned.          |
 | `STATE_DIR`          | no       | `/state`                                   | seen-imports.json lives here.         |
 | `LISTEN_PORT`        | no       | `5055`                                     | Flask bind port.                      |
 ## Volumes
 - `/repo` — beta-flix checkout. Bind-mounted persistent volume.
 - `/state` — `seen-imports.json` cache.
 - `/root/.ssh` (optional, read-only) — for SSH deploy key (currently uses
  HTTPS+PAT; SSH path reserved for future).
 ## Development
 Run locally without Docker:
 ```bash
 cd catalog/
 python -m venv .venv && . .venv/bin/activate
 pip install -r requirements.txt
 REPO_PATH=/tmp/beta-flix-test STATE_DIR=/tmp/catalog-state \
  FORGEJO_PUSH_TOKEN=xxx python catalog.py
 # In another shell:
 curl -X POST http://localhost:5055/sonarr \
  -H 'Content-Type: application/json' \
  -d '{"eventType":"Test"}'
 ```
--- a/catalog/catalog.py
+++ b/catalog/catalog.py
@ -0,0 +1,366 @@
 """betaflix-catalog — Sonarr/Radarr OnImport webhook receiver.
 Listens for OnImport events from Sonarr and Radarr, edits
 `playbooks/import-media/MEDIA-LIST.md` in the beta-flix Forgejo repo, writes
 a per-import run log, and commits + pushes as `obsidian-ai`.
 POST endpoints:
    /sonarr   Sonarr Connect webhook target.
    /radarr   Radarr Connect webhook target.
    /healthz  Liveness probe.
 Idempotency: payload-hash cache at /state/seen-imports.json. Duplicates skipped.
 Environment:
    FORGEJO_REMOTE         e.g. https://git.s8n.ru/s8n/beta-flix.git
    FORGEJO_PUSH_TOKEN     PAT — embedded into the push URL.
    GIT_AUTHOR_NAME        obsidian-ai
    GIT_AUTHOR_EMAIL       obsidian-ai@s8n.ru
    LISTEN_PORT            5055
 """
 from __future__ import annotations
 import hashlib
 import json
 import logging
 import os
 import re
 import subprocess
 import sys
 import threading
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 from flask import Flask, jsonify, request
 from jinja2 import Environment, FileSystemLoader, select_autoescape
 # --- Config -----------------------------------------------------------------
 REPO_PATH = Path(os.environ.get("REPO_PATH", "/repo"))
 STATE_DIR = Path(os.environ.get("STATE_DIR", "/state"))
 TEMPLATES_DIR = Path(__file__).parent / "templates"
 FORGEJO_REMOTE = os.environ.get("FORGEJO_REMOTE", "https://git.s8n.ru/s8n/beta-flix.git")
 FORGEJO_TOKEN = os.environ.get("FORGEJO_PUSH_TOKEN", "")
 GIT_AUTHOR_NAME = os.environ.get("GIT_AUTHOR_NAME", "obsidian-ai")
 GIT_AUTHOR_EMAIL = os.environ.get("GIT_AUTHOR_EMAIL", "obsidian-ai@s8n.ru")
 LISTEN_PORT = int(os.environ.get("LISTEN_PORT", "5055"))
 MEDIA_LIST = REPO_PATH / "playbooks" / "import-media" / "MEDIA-LIST.md"
 RUNS_DIR = REPO_PATH / "playbooks" / "import-media" / "runs"
 SEEN_PATH = STATE_DIR / "seen-imports.json"
 # Section headers in MEDIA-LIST.md the bot will edit.
 MOVIES_SECTION = "## Movies"
 TV_SECTION = "## TV"
 logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    stream=sys.stdout,
 )
 log = logging.getLogger("catalog")
 app = Flask(__name__)
 _lock = threading.Lock()
 _jinja = Environment(
    loader=FileSystemLoader(str(TEMPLATES_DIR)),
    autoescape=select_autoescape(["html", "xml"]),
    trim_blocks=True,
    lstrip_blocks=True,
 )
 # --- Idempotency ------------------------------------------------------------
 def _load_seen() -> set[str]:
    if not SEEN_PATH.exists():
        return set()
    try:
        return set(json.loads(SEEN_PATH.read_text()))
    except Exception:
        log.warning("seen-imports.json corrupt; resetting")
        return set()
 def _save_seen(seen: set[str]) -> None:
    STATE_DIR.mkdir(parents=True, exist_ok=True)
    SEEN_PATH.write_text(json.dumps(sorted(seen)))
 def _payload_hash(kind: str, payload: dict[str, Any]) -> str:
    """Stable hash for the import event — series:season:episode or movie:year."""
    if kind == "sonarr":
        sid = payload.get("series", {}).get("id", "?")
        eps = payload.get("episodes", []) or [{}]
        keys = sorted(f"{e.get('seasonNumber', '?')}x{e.get('episodeNumber', '?')}" for e in eps)
        seed = f"sonarr:{sid}:{','.join(keys)}"
    elif kind == "radarr":
        mid = payload.get("movie", {}).get("id", "?")
        seed = f"radarr:{mid}"
    else:
        seed = f"unknown:{json.dumps(payload, sort_keys=True)}"
    return hashlib.sha256(seed.encode()).hexdigest()[:16]
 # --- Git helpers ------------------------------------------------------------
 def _git(*args: str, cwd: Path = REPO_PATH) -> subprocess.CompletedProcess:
    env = os.environ.copy()
    env.setdefault("GIT_AUTHOR_NAME", GIT_AUTHOR_NAME)
    env.setdefault("GIT_AUTHOR_EMAIL", GIT_AUTHOR_EMAIL)
    env.setdefault("GIT_COMMITTER_NAME", GIT_AUTHOR_NAME)
    env.setdefault("GIT_COMMITTER_EMAIL", GIT_AUTHOR_EMAIL)
    return subprocess.run(
        ["git", *args],
        cwd=cwd,
        env=env,
        check=True,
        capture_output=True,
        text=True,
    )
 def _ensure_repo() -> None:
    """Clone the repo if /repo is empty."""
    if (REPO_PATH / ".git").is_dir():
        return
    REPO_PATH.mkdir(parents=True, exist_ok=True)
    clone_url = _push_url()
    subprocess.run(
        ["git", "clone", clone_url, str(REPO_PATH)],
        check=True,
        capture_output=True,
        text=True,
    )
 def _push_url() -> str:
    if FORGEJO_TOKEN and FORGEJO_REMOTE.startswith("https://"):
        return FORGEJO_REMOTE.replace("https://", f"https://{FORGEJO_TOKEN}@", 1)
    return FORGEJO_REMOTE
 def _pull_rebase() -> None:
    _git("fetch", "origin")
    _git("rebase", "origin/main")
 def _commit_and_push(title: str) -> str:
    _git("add", "playbooks/import-media/MEDIA-LIST.md", "playbooks/import-media/runs/")
    status = _git("status", "--porcelain")
    if not status.stdout.strip():
        log.info("no changes to commit (%s)", title)
        return ""
    msg = f"catalog: add {title}"
    _git("commit", "-m", msg, f"--author={GIT_AUTHOR_NAME} <{GIT_AUTHOR_EMAIL}>")
    _git("push", _push_url(), "HEAD:main")
    sha = _git("rev-parse", "HEAD").stdout.strip()
    return sha
 # --- MEDIA-LIST.md editing --------------------------------------------------
 def _normalise_title(title: str) -> str:
    return re.sub(r"\s+", " ", title.strip())
 def _slugify(s: str) -> str:
    s = re.sub(r"[^a-zA-Z0-9]+", "-", s.lower()).strip("-")
    return s[:80] or "untitled"
 def _row(kind: str, title: str, year: int | None, source: str) -> str:
    year_s = f"({year})" if year else ""
    if kind == "tv":
        return f"| {title} {year_s} | TV | {source} | _todo_ | "
    return f"| {title} {year_s} | Movie | {source} | _todo_ | "
 def _insert_alphabetic(section_header: str, row: str, key: str) -> bool:
    """Insert `row` into the section under `section_header`, alphabetic by key.
    Returns True if a new row was added, False if the key already existed
    (caller handles merge/dedup separately).
    """
    if not MEDIA_LIST.exists():
        log.warning("MEDIA-LIST.md missing at %s — skipping insert", MEDIA_LIST)
        return False
    lines = MEDIA_LIST.read_text().splitlines()
    try:
        start = next(i for i, line in enumerate(lines) if line.strip() == section_header)
    except StopIteration:
        log.warning("section %r not found in MEDIA-LIST.md", section_header)
        return False
    # Find table boundaries.
    i = start + 1
    while i < len(lines) and not lines[i].lstrip().startswith("|"):
        i += 1
    if i >= len(lines):
        log.warning("no table found under section %r", section_header)
        return False
    header_idx = i
    # Skip header + separator rows.
    i = header_idx + 2
    section_rows_start = i
    while i < len(lines) and lines[i].lstrip().startswith("|"):
        if key.lower() in lines[i].lower():
            log.info("row already present for key=%r — skipping", key)
            return False
        i += 1
    section_rows_end = i
    # Alphabetic insert by first column.
    insert_at = section_rows_end
    for j in range(section_rows_start, section_rows_end):
        cell = lines[j].split("|")[1].strip() if "|" in lines[j] else ""
        if key.lower() < cell.lower():
            insert_at = j
            break
    lines.insert(insert_at, row)
    MEDIA_LIST.write_text("\n".join(lines) + "\n")
    return True
 def _write_run_log(slug: str, ctx: dict[str, Any]) -> Path:
    RUNS_DIR.mkdir(parents=True, exist_ok=True)
    template = _jinja.get_template("run.md.j2")
    out = RUNS_DIR / f"{slug}.md"
    out.write_text(template.render(**ctx))
    return out
 # --- Webhook handlers -------------------------------------------------------
 def _handle_sonarr(payload: dict[str, Any]) -> tuple[str, bool]:
    series = payload.get("series", {}) or {}
    title = _normalise_title(series.get("title", "Unknown Series"))
    year = series.get("year") or None
    eps = payload.get("episodes", []) or []
    files = payload.get("episodeFiles") or payload.get("episodeFile") or []
    if isinstance(files, dict):
        files = [files]
    source = (files[0].get("sceneName") or files[0].get("relativePath") or "?") if files else "?"
    key = f"{title} ({year})" if year else title
    with _lock:
        _ensure_repo()
        _pull_rebase()
        added = _insert_alphabetic(TV_SECTION, _row("tv", title, year, source), key)
        slug = _slugify(f"{key}-S{eps[0].get('seasonNumber','?')}E{eps[0].get('episodeNumber','?')}" if eps else key)
        _write_run_log(slug, {
            "kind": "tv",
            "title": title,
            "year": year,
            "source": source,
            "episodes": eps,
            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
            "row_added": added,
        })
        sha = _commit_and_push(f"{title} ({year})" if year else title)
    return sha, added
 def _handle_radarr(payload: dict[str, Any]) -> tuple[str, bool]:
    movie = payload.get("movie", {}) or {}
    title = _normalise_title(movie.get("title", "Unknown Movie"))
    year = movie.get("year") or None
    mfile = payload.get("movieFile") or {}
    source = mfile.get("sceneName") or mfile.get("relativePath") or "?"
    key = f"{title} ({year})" if year else title
    with _lock:
        _ensure_repo()
        _pull_rebase()
        added = _insert_alphabetic(MOVIES_SECTION, _row("movie", title, year, source), key)
        slug = _slugify(key)
        _write_run_log(slug, {
            "kind": "movie",
            "title": title,
            "year": year,
            "source": source,
            "ts": datetime.now(timezone.utc).isoformat(timespec="seconds"),
            "row_added": added,
        })
        sha = _commit_and_push(f"{title} ({year})" if year else title)
    return sha, added
 # --- Flask routes -----------------------------------------------------------
@app.get("/healthz")
 def healthz():
    return jsonify(ok=True), 200
@app.post("/sonarr")
 def sonarr():
    payload = request.get_json(silent=True) or {}
    event = payload.get("eventType", "")
    if event in ("Test", "ApplicationUpdate"):
        log.info("sonarr probe event=%s — ack", event)
        return jsonify(ok=True, ignored=event), 200
    if event != "Import" and event != "Download":
        log.info("sonarr event=%s — ignored", event)
        return jsonify(ok=True, ignored=event), 200
    h = _payload_hash("sonarr", payload)
    seen = _load_seen()
    if h in seen:
        log.info("sonarr duplicate event hash=%s — skipping", h)
        return jsonify(ok=True, duplicate=h), 200
    try:
        sha, added = _handle_sonarr(payload)
    except subprocess.CalledProcessError as e:
        log.exception("git failed: %s", e.stderr)
        return jsonify(ok=False, error=e.stderr), 500
    except Exception as e:  # noqa: BLE001
        log.exception("sonarr handler crashed")
        return jsonify(ok=False, error=str(e)), 500
    seen.add(h)
    _save_seen(seen)
    return jsonify(ok=True, sha=sha, row_added=added), 200
@app.post("/radarr")
 def radarr():
    payload = request.get_json(silent=True) or {}
    event = payload.get("eventType", "")
    if event in ("Test", "ApplicationUpdate"):
        log.info("radarr probe event=%s — ack", event)
        return jsonify(ok=True, ignored=event), 200
    if event != "Import" and event != "Download":
        log.info("radarr event=%s — ignored", event)
        return jsonify(ok=True, ignored=event), 200
    h = _payload_hash("radarr", payload)
    seen = _load_seen()
    if h in seen:
        log.info("radarr duplicate event hash=%s — skipping", h)
        return jsonify(ok=True, duplicate=h), 200
    try:
        sha, added = _handle_radarr(payload)
    except subprocess.CalledProcessError as e:
        log.exception("git failed: %s", e.stderr)
        return jsonify(ok=False, error=e.stderr), 500
    except Exception as e:  # noqa: BLE001
        log.exception("radarr handler crashed")
        return jsonify(ok=False, error=str(e)), 500
    seen.add(h)
    _save_seen(seen)
    return jsonify(ok=True, sha=sha, row_added=added), 200
 if __name__ == "__main__":
    log.info("betaflix-catalog listening on 0.0.0.0:%d", LISTEN_PORT)
    app.run(host="0.0.0.0", port=LISTEN_PORT)
--- a/catalog/requirements.txt
+++ b/catalog/requirements.txt
@ -0,0 +1,5 @@
 flask==3.0.3
 requests==2.32.3
 jinja2==3.1.4
 gitpython==3.1.43
 pyyaml==6.0.2
--- a/catalog/templates/catalog_row.md.j2
+++ b/catalog/templates/catalog_row.md.j2
@ -0,0 +1,4 @@
 {# Reference template for MEDIA-LIST.md row generation.
   Pipe-delimited; matches the existing beta-flix table schema.
   Columns: Title | Kind | Source / Version | Why on arrflix | (trailing pipe) #}
 | {{ title }}{% if year %} ({{ year }}){% endif %} | {{ kind }} | {{ source }} | {{ why | default("_todo_") }} |
--- a/catalog/templates/run.md.j2
+++ b/catalog/templates/run.md.j2
@ -0,0 +1,24 @@
 # {{ title }}{% if year %} ({{ year }}){% endif %} — import run
 - **Date:** {{ ts }}
 - **Kind:** {{ kind }}
 - **Source / release name:** `{{ source }}`
 - **Catalog row added:** {{ "yes" if row_added else "no (already present)" }}
 {% if kind == "tv" and episodes %}
 ## Episodes imported
 | Season | Episode | Title |
 |--------|---------|-------|
 {% for e in episodes %}
 | {{ e.seasonNumber }} | {{ e.episodeNumber }} | {{ e.title | default("?") }} |
 {% endfor %}
 {% endif %}
 ## Notes
 _(human-authored)_
 ---
 _Auto-generated by `betaflix-catalog` on Sonarr/Radarr OnImport webhook._
--- a/compose/.env.example
+++ b/compose/.env.example
@ -0,0 +1,38 @@
 # compose/.env.example
 #
 # Copy to .env (gitignored) and fill in real values.
 #
 # Never commit .env. Forgejo PAT + Proton WG key + arr API keys = secrets.
 # --- Timezone (logs + scheduling) ---
 TZ=Europe/London
 # --- Proton VPN (gluetun) ---
 # Generate a dedicated WireGuard key in the Proton dashboard:
 #   Account → WireGuard → New Configuration → name it "nullstone-gluetun-arr"
 # Do NOT reuse the host's wg-pvpn-A/B keys.
 PVPN_WG_PRIVKEY=REPLACE_WITH_PROTON_WG_PRIVATE_KEY
 # The address Proton assigns to the new key (e.g. 10.2.0.3/32).
 PVPN_WG_ADDRESSES=10.2.0.3/32
 # Country (P2P-permitted). Comma-separated to let gluetun pick from a pool.
 PVPN_SERVER_COUNTRIES=Netherlands
 # --- Catalog service: Forgejo push ---
 # https://git.s8n.ru → Settings → Applications → Generate New Token
 # Scopes required: repository (read+write), user (read).
 # Token is embedded in the remote URL inside the catalog container.
 FORGEJO_PUSH_TOKEN=REPLACE_WITH_FORGEJO_PAT
 # Remote URL — leave default unless beta-flix is moved.
 FORGEJO_REMOTE=https://git.s8n.ru/s8n/beta-flix.git
 # --- arr API keys ---
 # Fetch from each app's Settings → General → Security after first launch.
 # Used by catalog service to enrich the webhook payload via API calls.
 SONARR_API_KEY=REPLACE_WITH_SONARR_API_KEY
 RADARR_API_KEY=REPLACE_WITH_RADARR_API_KEY
 PROWLARR_API_KEY=REPLACE_WITH_PROWLARR_API_KEY
 # --- Optional: forwarded-port sync helper ---
 # If you add caillef/qbittorrent-port-sync later for ratio-critical seeding,
 # the qbt webui password goes here (used by that helper, not qbt itself).
 QBT_WEBUI_PASSWORD=REPLACE_WITH_QBT_WEBUI_PASSWORD
--- a/compose/docker-compose.yml
+++ b/compose/docker-compose.yml
@ -0,0 +1,141 @@
 # nullstone media-acquisition stack
 #
 # Compose file for: gluetun (VPN + kill-switch) + qBittorrent + Sonarr +
 # Radarr + Prowlarr + betaflix-catalog (Forgejo committer).
 #
 # Place this directory under /opt/docker/media-acquisition/ on nullstone.
 # Run: docker compose up -d
 # Verify kill-switch: bash ../scripts/killswitch-test.sh
 services:
  gluetun:
    image: qmcgaw/gluetun:v3.40
    container_name: gluetun
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun:/dev/net/tun
    environment:
      - VPN_SERVICE_PROVIDER=protonvpn
      - VPN_TYPE=wireguard
      - WIREGUARD_PRIVATE_KEY=${PVPN_WG_PRIVKEY}
      - WIREGUARD_ADDRESSES=${PVPN_WG_ADDRESSES}
      - SERVER_COUNTRIES=${PVPN_SERVER_COUNTRIES:-Netherlands}
      - VPN_PORT_FORWARDING=on
      - VPN_PORT_FORWARDING_PROVIDER=protonvpn
      - FIREWALL_OUTBOUND_SUBNETS=192.168.0.0/24,172.16.0.0/12,100.64.0.0/10
      - DOT=off
      - TZ=${TZ:-Europe/London}
    ports:
      # All published on 127.0.0.1 — Traefik file-provider picks them up.
      - "127.0.0.1:8080:8080"   # qBittorrent WebUI
      - "127.0.0.1:9696:9696"   # Prowlarr
      - "127.0.0.1:8989:8989"   # Sonarr
      - "127.0.0.1:7878:7878"   # Radarr
    volumes:
      - ./gluetun:/gluetun
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "-qO-", "--tries=1", "--timeout=10", "https://ipinfo.io"]
      interval: 30s
      timeout: 15s
      retries: 3
      start_period: 30s
  qbittorrent:
    image: qbittorrentofficial/qbittorrent-nox:5.0.5
    container_name: qbittorrent
    depends_on:
      gluetun:
        condition: service_healthy
    network_mode: "service:gluetun"
    user: "1000:1000"
    environment:
      - QBT_LEGAL_NOTICE=confirm
      - QBT_WEBUI_PORT=8080
      - UMASK=022
      - TZ=${TZ:-Europe/London}
    volumes:
      - ./qbittorrent/config:/config
      - /home/user/media/_downloads:/downloads
      - /home/user/media:/media
    restart: unless-stopped
  prowlarr:
    image: ghcr.io/hotio/prowlarr:release
    container_name: prowlarr
    depends_on:
      gluetun:
        condition: service_healthy
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=022
      - TZ=${TZ:-Europe/London}
    volumes:
      - ./prowlarr:/config
    restart: unless-stopped
  sonarr:
    image: ghcr.io/hotio/sonarr:release
    container_name: sonarr
    depends_on:
      gluetun:
        condition: service_healthy
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=022
      - TZ=${TZ:-Europe/London}
    volumes:
      - ./sonarr:/config
      - /home/user/media:/media
    restart: unless-stopped
  radarr:
    image: ghcr.io/hotio/radarr:release
    container_name: radarr
    depends_on:
      gluetun:
        condition: service_healthy
    network_mode: "service:gluetun"
    environment:
      - PUID=1000
      - PGID=1000
      - UMASK=022
      - TZ=${TZ:-Europe/London}
    volumes:
      - ./radarr:/config
      - /home/user/media:/media
    restart: unless-stopped
  betaflix-catalog:
    image: betaflix-catalog:local
    container_name: betaflix-catalog
    build:
      context: ../catalog
      dockerfile: Dockerfile
    # NOT bound to gluetun — needs to reach Forgejo + Sonarr/Radarr
    network_mode: bridge
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - FORGEJO_REMOTE=${FORGEJO_REMOTE:-https://git.s8n.ru/s8n/beta-flix.git}
      - FORGEJO_PUSH_TOKEN=${FORGEJO_PUSH_TOKEN}
      - GIT_AUTHOR_NAME=obsidian-ai
      - GIT_AUTHOR_EMAIL=obsidian-ai@s8n.ru
      - GIT_COMMITTER_NAME=obsidian-ai
      - GIT_COMMITTER_EMAIL=obsidian-ai@s8n.ru
      - SONARR_API_KEY=${SONARR_API_KEY}
      - RADARR_API_KEY=${RADARR_API_KEY}
      - TZ=${TZ:-Europe/London}
      - LISTEN_PORT=5055
    ports:
      - "127.0.0.1:5055:5055"
    volumes:
      - ./catalog/repo:/repo
      - ./catalog/ssh:/root/.ssh:ro
      - ./catalog/state:/state
    restart: unless-stopped
--- a/compose/traefik/arr.yml
+++ b/compose/traefik/arr.yml
@ -0,0 +1,77 @@
 # Traefik file-provider snippet for the media-acquisition stack.
 #
 # Symlink (or cp) this file into /opt/docker/traefik/config/arr.yml on
 # nullstone. Traefik picks up file-provider configs without restart.
 #
 # All routes are LAN+Tailscale-only (trusted-only@file middleware) AND
 # require Authentik forward-auth. Add the arr-stack Authentik group as
 # needed.
 #
 # Backends are 127.0.0.1:<port> because gluetun publishes the qbt/prowlarr/
 # sonarr/radarr ports on host loopback (network_mode: service:gluetun).
 http:
  routers:
    qbt:
      rule: "Host(`qbt.s8n.ru`)"
      entryPoints: [websecure]
      service: qbt
      tls:
        certResolver: gandi
      middlewares:
        - trusted-only@file
        - authentik-forwardauth@file
    prowlarr:
      rule: "Host(`prowlarr.s8n.ru`)"
      entryPoints: [websecure]
      service: prowlarr
      tls:
        certResolver: gandi
      middlewares:
        - trusted-only@file
        - authentik-forwardauth@file
    sonarr:
      rule: "Host(`sonarr.s8n.ru`)"
      entryPoints: [websecure]
      service: sonarr
      tls:
        certResolver: gandi
      middlewares:
        - trusted-only@file
        - authentik-forwardauth@file
    radarr:
      rule: "Host(`radarr.s8n.ru`)"
      entryPoints: [websecure]
      service: radarr
      tls:
        certResolver: gandi
      middlewares:
        - trusted-only@file
        - authentik-forwardauth@file
    # Catalog service has no public route — Sonarr/Radarr hit it via
    # host.docker.internal:5055 from inside their gluetun netns.
  services:
    qbt:
      loadBalancer:
        servers:
          - url: "http://127.0.0.1:8080"
    prowlarr:
      loadBalancer:
        servers:
          - url: "http://127.0.0.1:9696"
    sonarr:
      loadBalancer:
        servers:
          - url: "http://127.0.0.1:8989"
    radarr:
      loadBalancer:
        servers:
          - url: "http://127.0.0.1:7878"
--- a/docs/architecture.md
+++ b/docs/architecture.md
@ -0,0 +1,242 @@
 # Architecture — nullstone BitTorrent + Import Pipeline
 Last reviewed: 2026-05-20 against live state of `user@192.168.0.100`.
 **Goal:** kill the `download-on-onyx → rsync → import` round-trip. Land torrents
 directly on nullstone, through VPN, hardlink into the canonical ARRFLIX library,
 auto-update the catalog in `git.s8n.ru/s8n/beta-flix`.
 ---
 ## TL;DR Decisions
 | Question                | Decision                                                                                                                              |
 |-------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
 | Client                  | `qbittorrentofficial/qbittorrent-nox:5.0.5` (single container, official build, slim)                                                  |
 | VPN binding             | **gluetun sidecar + `network_mode: service:gluetun`** (WireGuard, kill-switch built-in). Reuses Proton WG. Replaces `socks-pvpn` for BT only. |
 | Folder layout           | `/home/user/media/_downloads/{incomplete,complete}` (NOT scanned by JF) + hardlinks into existing `movies/tv/...`                     |
 | Arr stack?              | **Yes for Sonarr/Radarr/Prowlarr, NO for Bazarr/cross-seed (yet)**. Mature rename engine beats bespoke; manual selection still works.  |
 | FS atomic-import        | XFS reflinks (`cp --reflink=always`) — same inode cost as hardlinks but allow free path/perm divergence. "Use Hardlinks" toggle works. |
 | Catalog auto-update     | sidecar Python service (`betaflix-catalog`) on Sonarr/Radarr webhooks → patches `MEDIA-LIST.md` → git commit+push to Forgejo.         |
 | GPU                     | untouched — qbt doesn't need it; Jellyfin keeps its existing passthrough (CPU-only post-driver-issue, separate concern).               |
 Override any of this if your gut disagrees — but record an ADR under
 `docs/decisions/` first.
 ---
 ## Current State (verified live)
 - `socks-pvpn` container: `serjs/go-socks5-proxy` on `socks-vpn` (172.31.0.0/24).
  Already provides `socks5://socks-pvpn:1080` with `qbt` user. Egress via host's
  `wg-pvpn-A` / `wg-pvpn-B` (policy-routed by fwmark `0x51820` / `0x51821`).
  Proton WG is **host-side**, not in a container.
 - `jellyfin-stock`: mounts `/home/user/media → /media` bind, in `proxy` network.
 - xfs at `/dev/sda1 → /home/user/media`, 5.5T total / 3.9T free. Reflink-capable.
 - No existing Sonarr / Radarr / Prowlarr / gluetun / qbt containers.
 - Traefik on networks `proxy`, `socket-proxy-net`, `misskey-frontend`.
 Two viable VPN strategies: keep using `socks-pvpn` SOCKS5 with qbt proxy, or
 drop in a dedicated `gluetun` for the BT stack only. See § b.
 ---
 ## a) qBittorrent image
 **Pick:** `qbittorrentofficial/qbittorrent-nox:5.0.5`.
 - Official upstream build, signed, no LSIO PUID/PGID overhead.
 - 5.0.x ships native WebUI v2 and modern logging.
 - Single port: 8080 (WebUI) + chosen listen port (e.g. 51820+random for BT).
 - Run as uid `1000:1000` (matches `user:user` on host) so anything qbt writes
  to `/home/user/media/_downloads` already matches library ownership.
 **Skip** `linuxserver/qbittorrent` — extra init scripts, slower updates, PUID
 drift when paired with userns-remap.
 **Skip** `qbittorrent-nox` bare on host — Docker buys VPN-namespace binding +
 restart isolation. Cheap.
 ---
 ## b) VPN binding — pick `gluetun`
 Three patterns considered:
 | Pattern                                   | Pro                                         | Con                                                                                                                       |
 |-------------------------------------------|---------------------------------------------|---------------------------------------------------------------------------------------------------------------------------|
 | qbt SOCKS5 → `socks-pvpn`                 | Zero new infra                              | qbt SOCKS support has historical leaks (UDP, trackers, DHT). Not a kill-switch — if SOCKS dies, qbt uses default route → clear-net leak |
 | WireGuard inside qbt container            | Tight blast radius                          | Bake wg into image; restart re-attach pain; upgrades painful                                                              |
 | **`gluetun` sidecar, qbt joins its netns**| Mature kill-switch (iptables-enforced), port-forward helper, qbt unchanged | Adds one container; eats a Proton WG slot                                                                                 |
 **Decision: gluetun.** It's a kill-switch by design — if WG drops, gluetun's
 firewall blackholes traffic. Used by every torrent setup in /r/selfhosted for
 that reason. Add a third Proton WG endpoint specifically for it (so it doesn't
 collide with the existing wg-pvpn-A/B host-level policy routes).
 Keep `socks-pvpn` running for other clients.
 ### Kill-switch verification
 ```bash
 docker exec qbittorrent curl -sf --max-time 5 https://api.ipify.org   # should return Proton exit IP
 docker stop gluetun && docker exec qbittorrent curl -sf --max-time 5 https://api.ipify.org   # MUST hang/fail
 docker start gluetun
 ```
 If the second command succeeds, you have a leak — **do not proceed**.
 The wrapper script is at `scripts/killswitch-test.sh`.
 ---
 ## c) Folder layout (xfs, single device)
 ```
 /home/user/media/
 ├── _downloads/            # NOT in any JF library → JF can't see it
 │   ├── incomplete/        # qbt's "temp path" — half-written files
 │   ├── complete/          # qbt's "save path" — completed, still seeding
 │   └── watch/             # drop .torrent files here for auto-add
 ├── movies/                # canonical, JF scans (existing)
 ├── tv/                    # canonical, JF scans (existing)
 ├── education/             # YouTube creator, JF scans (existing)
 ├── music/                 # (existing)
 └── podcasts/              # (existing)
 ```
 JF library paths are configured in dashboard and only point at the four
 canonical roots. `_downloads/` is on the same xfs filesystem → hardlinks /
 reflinks are free (zero extra blocks consumed) when sonarr/radarr import.
 Sonarr/Radarr setting: **Use Hardlinks instead of Copy = yes**.
 Permissions: qbt runs as `1000:1000`, files land 644/dirs 755 (image sets
 `umask 022`). If defaults drift, force with `UMASK=022` in container env
 (qbt 5 honors it).
 ---
 ## d, f) Arr stack vs custom watcher — pick Arr
 For 20-40 items in pipeline the bespoke watcher is *tempting*. Pick
 Sonarr/Radarr anyway:
 **For Sonarr/Radarr (mature rename + import):**
 - Their rename engine handles 100+ edge cases your bash will eventually trip:
  multi-episode files, anime absolute numbering, special seasons,
  daily-broadcast dates, year-disambiguated titles. You will hit these.
 - "Interactive Search" gives manual selection — not forced into RSS auto-grab.
 - Hardlink-on-import is a checkbox, not a function to debug.
 - Webhook on import → ready-made trigger for catalog-update.
 - Library "Scan after import" is built-in. Skip the cargo-cult JF scan task ID
  dance (keep as manual escape hatch).
 **For Prowlarr:**
 - One-place indexer config. Even if you only use 3 trackers, having them
  managed in Prowlarr and pushed to Sonarr+Radarr is less duplication.
 - Categories + capabilities matter when manual-search returns results — you
  want season-pack vs single-episode discrimination on the search UI.
 **Against (kept honest):**
 - Five extra containers (gluetun, qbt, sonarr, radarr, prowlarr). ~600 MB RAM
  combined idle. nullstone has 31 G; rounding error.
 - Sonarr database in SQLite — back up in `./backup.sh`.
 - More UI surface. Two evenings.
 **Hard NO for now:**
 - **Bazarr** — subtitle pipeline is the WhisperX v4 build, not OpenSubtitles.
 - **cross-seed** — only useful when seriously seeding to ratio. Defer.
 - **Lidarr / Readarr** — out of scope (music + books not in this pipeline).
 If after 2 weeks Sonarr's metadata picker is fighting you, **then** swap to
 bespoke — files on disk are the same shape either way.
 ---
 ## e) Catalog-update service (mandatory regardless)
 Even with Sonarr/Radarr, neither tool knows about
 `/home/admin/projects/beta-flix/playbooks/import-media/MEDIA-LIST.md`. So:
 `betaflix-catalog` (Python 3.12, Flask, ~200 LoC, in `catalog/`). Listens for
 Sonarr/Radarr **"On Import"** webhooks. For each event:
 1. Pull metadata from webhook payload (`series.title`, `series.year`,
   `episodeFile.path`, or `movie.title` + `movie.year` + `movieFile.path`).
 2. `git -C /repo pull --rebase origin main`.
 3. Edit `playbooks/import-media/MEDIA-LIST.md`:
   - Movies: insert into Movies table, alphabetic on title.
   - TV: if series row exists, merge seasons into the `Seasons` column;
     else insert new row.
   - "Source / Version" column = parsed from filename release-group tokens
     **before** Sonarr stripped them. The webhook gives `sourceTitle`
     (original release name) — log it raw, you can edit later.
   - "Why on arrflix" column stays blank — that's human-authored.
 4. Write run log to `playbooks/import-media/runs/<slug>.md` using a Jinja
   template (date, source path, target path, item count, ffprobe summary
   from a `docker exec jellyfin-stock ffprobe` call — optional, deferred).
 5. `git commit -m "catalog: add <title> (<year>)" --author "obsidian-ai <obsidian-ai@s8n.ru>"`.
 6. `git push origin main`. Forgejo deploy key in `compose/catalog/ssh/`
   (gitignored — placed by operator at deploy time).
 Webhook config in Sonarr: Settings → Connect → Webhook → POST to
 `http://host.docker.internal:5055/sonarr` on `OnImport` event only.
 Idempotency: hash the payload (`{series_id}:{season}:{episode}`); skip if
 seen in the last hour (Sonarr retries on transient failure). Cache lives at
 `/tmp/seen-imports.json` (ephemeral; that's fine — duplicate commits are
 benign-but-noisy, not destructive).
 Skeleton lives at `catalog/catalog.py` in this repo. ~30 minutes to draft,
 ~2 hours to harden. The piece that bridges "files on nullstone" to "facts
 in Forgejo".
 ---
 ## g) Migration from onyx-qbt → nullstone-qbt
 State: 60+ active torrents on onyx, with download dirs on onyx local disk.
 **Goal:** keep seeding (don't burn ratios) while shifting future downloads to
 nullstone. Two-phase, no big-bang.
 Full runbook: `docs/migration.md` (and the script `scripts/migrate-onyx.sh`).
 ---
 ## What this doesn't solve (be aware)
 - **Tracker IP allowlists.** Some private trackers pin sessions to a single
  IP. Switching from onyx public IP → Proton exit IP will trip them. Check
  each tracker's rules before migrating — you may need an IP-update request
  per private tracker. See `docs/trackers.md`.
 - **Port forwarding via Proton.** gluetun's `VPN_PORT_FORWARDING=on` handles
  this for Proton, but the forwarded port rotates. Set qbt to use the
  gluetun-provided port via the gluetun control server (gluetun writes the
  current port to `/tmp/gluetun/forwarded_port`; qbt's `qBittorrent.conf`
  needs a wrapper script to read it on start). Known helper image:
  `caillef/qbittorrent-port-sync` — drop in as a 6th container if seeding
  ratio matters. Deferred until tracker ratio becomes a real concern.
 - **Backup.** Add `/opt/docker/media-acquisition/compose/{sonarr,radarr,prowlarr,qbittorrent}/config`
  to nullstone's `/opt/docker/backup.sh`. SQLite DBs — stop containers
  briefly or use `sqlite3 .backup` semantics.
 ---
 ## Open decisions to confirm before implementing
 1. Proton plan slot count — gluetun needs its own WG key. Free slot?
 2. Which private trackers do you actually use? IP-pinning check.
 3. Public hostnames for the arr-stack: confirm `qbt/sonarr/radarr/prowlarr.s8n.ru`
   or pick a sub-zone (`arr.s8n.ru/qbt/`).
 4. Authentik group for arr-stack access (LAN-only? or also from gravel via
   Tailscale?).
 5. Forgejo deploy key — generate now or reuse `obsidian-ai`'s existing key?
 Answer those five and the implementation is ~1 evening of compose + ~2 hours
 on the catalog service. Migration is a separate weekend.
--- a/docs/migration.md
+++ b/docs/migration.md
@ -0,0 +1,136 @@
 # Migration — onyx-qbt → nullstone-qbt
 State at time of writing: 60+ active torrents on onyx with download dirs on
 onyx local disk. **Goal:** keep seeding (don't burn ratios) while shifting
 future downloads to nullstone. Two-phase, no big-bang.
 ---
 ## Phase 1 — Stand up nullstone stack (no migration yet)
 1. **Prep directory tree** on nullstone:
    ```bash
    ssh user@nullstone
    sudo mkdir -p /home/user/media/_downloads/{incomplete,complete,watch}
    sudo chown -R user:user /home/user/media/_downloads
    ```
 2. **Generate new Proton WG key + provisioning for gluetun.** Don't reuse
   `wg-pvpn-A` keys (they're host-routed; conflict risk). Log into Proton
   account → WireGuard → new key → name it `nullstone-gluetun-arr` → save
   the privkey + assigned address (e.g. `10.2.0.3/32`).
 3. **Drop the privkey + address into `compose/.env`:**
    ```bash
    cd /opt/docker/media-acquisition/compose
    cp .env.example .env
    ${EDITOR:-vi} .env
    # Set:
    #   PVPN_WG_PRIVKEY=<the new privkey>
    #   PVPN_WG_ADDRESSES=10.2.0.3/32
    #   PVPN_SERVER_COUNTRIES=Netherlands
    ```
 4. **Bring up the stack.** Start gluetun + qbt only first:
    ```bash
    docker compose up -d gluetun qbittorrent
    ```
 5. **Kill-switch test (NON-NEGOTIABLE):**
    ```bash
    bash scripts/killswitch-test.sh
    ```
    If second curl succeeds → leak. Tear down and debug. Do not proceed.
 6. **Sacrificial torrent.** Pick something legal + big you don't care about
   (e.g. a Linux distro ISO). Add it via qbt webui, watch it land in
   `/home/user/media/_downloads/complete/`. Confirm it **does not** appear in JF.
 7. **Bring up the rest of the stack.**
    ```bash
    docker compose up -d
    ```
    Configure Prowlarr → Sonarr → Radarr (in that order — Prowlarr pushes
    indexers downstream). Set "Use Hardlinks instead of Copy = yes" in
    Sonarr/Radarr Media Management.
 8. **Test arr → import path.** Sonarr Interactive Search → manual grab → import
   into `/media/tv/...`. Verify catalog service commits to Forgejo.
 ---
 ## Phase 2 — Migrate onyx torrents
 For each active torrent on onyx that you want to keep seeding:
 ```bash
 # On onyx — export .torrent files + qbt's fastresume state
 mkdir -p /tmp/qbt-migrate
 cp ~/.local/share/qBittorrent/BT_backup/*.torrent /tmp/qbt-migrate/
 cp ~/.local/share/qBittorrent/BT_backup/*.fastresume /tmp/qbt-migrate/
 # rsync the actual data files to nullstone first (LAN gigabit)
 rsync -av --info=progress2 ~/Downloads/qbt/ \
  user@192.168.0.100:/home/user/media/_downloads/complete/
 ```
 Then on nullstone qbt webui:
 1. Add `.torrent` files in bulk via webui ("Add torrent files…"), save path =
   `/downloads/complete/`, **uncheck "Start torrent"**.
 2. Force-recheck each added torrent. qbt matches local files → `100%` → seeding.
 3. Verify trackers respond. Private trackers may need source-IP rotation —
   gluetun exit IP differs from onyx public IP. See `docs/trackers.md`.
 4. On onyx: pause torrents one-by-one as nullstone takes over. Don't stop
   onyx-qbt entirely until every torrent shows seeding on nullstone for 24h
   with no tracker errors.
 **Catalog backfill:** for torrents that correspond to already-imported
 library items, **don't** trigger arr-import — they're already in canonical
 locations. Just seed from `_downloads/complete/`. Catalog stays accurate.
 For torrents that were mid-download on onyx but never made it into the
 library: re-add on nullstone, let them complete via VPN, then sonarr/radarr
 picks them up via the normal path.
 **Estimated migration window:** 1 weekend. ~250 GB rsync over LAN gigabit ≈
 ~30 min wall clock for the data move, then a manual-but-tedious
 add-and-recheck loop in qbt.
 The wrapper script for steps 1-2 is at `scripts/migrate-onyx.sh`. It does
 the rsync + builds a `.torrent` index for a follow-up bulk-add. The
 fastresume-rewrite step is documented inline in the script.
 ---
 ## Phase 3 — Decommission onyx-qbt
 After 7 days clean on nullstone:
 1. Stop qbt service on onyx (`systemctl --user stop qbittorrent-nox` or kill
   the GUI; depends on how it was launched).
 2. Delete `~/Downloads/qbt/` on onyx (only after confirming no in-flight
   torrents reference it).
 3. Update `ai-lab/CLAUDE.md` device registry note if onyx had a
   "downloads role" annotation. (As of 2026-05-20 it does not — onyx has been
   the staging host but is not formally documented as such.)
 4. Optional: keep the `.torrent` files archive on onyx for 30 days as a
   safety net.
 ---
 ## Rollback
 If nullstone stack starts failing during phase 2:
 - `docker compose down` on nullstone.
 - Re-enable onyx qbt (Phase 1's stack is non-destructive — onyx torrents still
  have their data + fastresume).
 - File an issue + revisit phase 1 step 5 (kill-switch test).
--- a/docs/trackers.md
+++ b/docs/trackers.md
@ -0,0 +1,59 @@
 # Trackers — schema, IP-pinning, ratio notes
 Single source of truth for what trackers feed this pipeline, and what their
 quirks are. Per-tracker entries get added by the operator; the schema is
 below.
 ## IP-pinning risk
 Many private trackers **pin sessions to a single source IP**. Switching
 from onyx public IP → Proton exit IP (via gluetun) will trip them: tracker
 returns `unauthorized: source IP mismatch` on announce, the torrent stops
 announcing → seeding stats halt → ratio decays.
 Mitigations, ordered cheapest → most invasive:
 1. **Read the tracker's FAQ first.** Most private trackers have a documented
   policy: "1 IP, change requires staff" / "rolling IP allowed, contact us
   after change" / "IP locked to account, no exceptions".
 2. **Request an IP update** from staff before migrating that torrent.
   Provide the new Proton exit IP (gluetun reports current exit via
   `docker exec gluetun cat /tmp/gluetun/ip`).
 3. **Hot-swap manually:** announce on onyx, immediately re-add on nullstone,
   force-announce. Some trackers' anti-abuse is rate-limited and won't catch
   the swap.
 4. **Multiple exit profiles.** Run two gluetun containers with different
   Proton server selections (one for tracker A, one for tracker B). Heavy.
 If a tracker rejects all of the above, **leave that torrent on onyx**. The
 migration is not all-or-nothing; some seedboxes will live forever on the
 old host. Document the exception in the table below.
 ## Per-tracker schema
 Use this table format in this file. **Sort alphabetically by tracker name.**
 | Tracker            | URL                          | Type    | IP-Pinning            | Ratio Required | Notes                          |
 |--------------------|------------------------------|---------|-----------------------|----------------|--------------------------------|
 | _example.tracker_  | https://_example.tracker_/   | private | locked, request swap  | 1.0 over 30d   | Staff respond on IRC in < 24h. |
 | _public.example_   | http://_public.example_/     | public  | n/a                   | n/a            | No account, no ratio.          |
 (Replace the example rows with real trackers as they are onboarded.)
 ## Onboarding a new tracker
 When adding a new private tracker:
 1. Read the tracker's FAQ / rules. Record IP-pinning + ratio policy in the
   table above.
 2. Run `scripts/add-tracker.sh <name> <url>` to push it into Prowlarr. The
   script prompts for cookies / API key as needed.
 3. Add a row to the per-tracker table above. Commit.
 4. Monitor first 24h: check Prowlarr → Indexer → Stats for failed-query rate.
   > 10% failures → recheck the IP-pinning column.
 ## Public trackers
 Public trackers (e.g. open BitTorrent indexers) have no IP-pinning concerns
 but generally bad quality + slow speeds. List them sparingly; prefer private
 trackers for the long tail of niche media.
--- a/scripts/add-tracker.sh
+++ b/scripts/add-tracker.sh
@ -0,0 +1,74 @@
 #!/usr/bin/env bash
 # scripts/add-tracker.sh — register a tracker with Prowlarr via API.
 #
 # Usage:
 #   PROWLARR_API_KEY=xxx ./add-tracker.sh <indexer-name> <indexer-id>
 #
 # Where <indexer-id> is Prowlarr's internal ID for the indexer type (look it
 # up via `curl /api/v1/indexer/schema` — see "Discovering indexer IDs" below).
 #
 # This script POSTs a minimal indexer config to Prowlarr. For trackers that
 # need cookies / passkeys / 2FA, finish the setup in the Prowlarr webui
 # afterwards.
 #
 # Pre-reqs:
 #   - Prowlarr container up.
 #   - PROWLARR_API_KEY exported (Prowlarr → Settings → General → Security).
 #   - PROWLARR_URL defaults to http://127.0.0.1:9696.
 set -euo pipefail
 NAME="${1:-}"
 INDEXER_ID="${2:-}"
 PROWLARR_URL="${PROWLARR_URL:-http://127.0.0.1:9696}"
 PROWLARR_API_KEY="${PROWLARR_API_KEY:-}"
 if [ -z "$NAME" ] || [ -z "$INDEXER_ID" ] || [ -z "$PROWLARR_API_KEY" ]; then
    cat <<EOF >&2
 Usage: PROWLARR_API_KEY=xxx $0 <indexer-name> <indexer-id>
 Env:
  PROWLARR_URL      default: http://127.0.0.1:9696
  PROWLARR_API_KEY  required — Prowlarr → Settings → General → Security.
 Discovering indexer IDs:
  curl -s "\$PROWLARR_URL/api/v1/indexer/schema" \\
       -H "X-Api-Key: \$PROWLARR_API_KEY" | \\
       jq -r '.[] | "\\(.implementation)\\t\\(.implementationName)"' | sort -u
  Find the row matching your tracker, then look up its integer id via the
  full schema entry. Many private trackers use the "Cardigann" implementation
  with a YAML config — see Prowlarr docs for the full attribute list.
 EOF
    exit 2
 fi
 echo "Querying schema for '$INDEXER_ID'..."
 SCHEMA_JSON="$(curl -fsS \
    -H "X-Api-Key: $PROWLARR_API_KEY" \
    "$PROWLARR_URL/api/v1/indexer/schema" \
  | jq --arg id "$INDEXER_ID" '.[] | select(.id == ($id | tonumber))')"
 if [ -z "$SCHEMA_JSON" ]; then
    echo "No schema entry for indexer id=$INDEXER_ID" >&2
    exit 1
 fi
 # Override name with the user-provided one and keep all other fields as-is.
 PAYLOAD="$(jq --arg name "$NAME" '. + {name: $name, enable: true}' <<<"$SCHEMA_JSON")"
 echo "POSTing indexer config..."
 RESPONSE="$(curl -fsS -X POST \
    -H "X-Api-Key: $PROWLARR_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$PAYLOAD" \
    "$PROWLARR_URL/api/v1/indexer")"
 NEW_ID="$(jq -r '.id' <<<"$RESPONSE")"
 echo "OK — indexer '$NAME' added with id=$NEW_ID"
 echo
 echo "Next steps:"
 echo "  1. Open Prowlarr → Indexers → $NAME → fill in cookies/passkey/API key."
 echo "  2. Test indexer (Settings → Indexers → Test)."
 echo "  3. Add a row to docs/trackers.md with IP-pinning + ratio notes."
 echo "  4. Push to Sonarr/Radarr via Prowlarr's Apps → Sync."
--- a/scripts/killswitch-test.sh
+++ b/scripts/killswitch-test.sh
@ -0,0 +1,96 @@
 #!/usr/bin/env bash
 # scripts/killswitch-test.sh — verify gluetun blocks traffic when VPN drops.
 #
 # Test plan (per docs/architecture.md §b):
 #
 #   1. With gluetun UP, qbt MUST resolve api.ipify.org and return an IP
 #      that is NOT nullstone's WAN IP (i.e. Proton exit).
 #   2. Stop gluetun. qbt's container MUST NOT be able to reach the internet
 #      (curl hangs / fails fast). If it succeeds → kill-switch leak → ABORT.
 #   3. Restart gluetun, re-verify step 1.
 #
 # Run from anywhere with `docker` access on the host. Idempotent.
 set -euo pipefail
 GLUETUN="${GLUETUN_CONTAINER:-gluetun}"
 QBT="${QBT_CONTAINER:-qbittorrent}"
 TIMEOUT="${TIMEOUT:-8}"
 red()   { printf '\033[31m%s\033[0m\n' "$*"; }
 green() { printf '\033[32m%s\033[0m\n' "$*"; }
 yellow(){ printf '\033[33m%s\033[0m\n' "$*"; }
 require_container() {
    if ! docker inspect "$1" >/dev/null 2>&1; then
        red "FAIL: container '$1' not found"; exit 1
    fi
 }
 require_container "$GLUETUN"
 require_container "$QBT"
 # --- Step 0: discover nullstone's WAN IP (so we can detect leaks).
 WAN_IP="$(curl -sf --max-time "$TIMEOUT" https://api.ipify.org || true)"
 if [ -z "$WAN_IP" ]; then
    yellow "WARN: could not fetch host WAN IP — leak detection will be best-effort"
 else
    echo "Host WAN IP: $WAN_IP"
 fi
 # --- Step 1: VPN-up check
 echo
 echo "Step 1: VPN-up — qbt should exit via Proton."
 if ! docker inspect -f '{{.State.Running}}' "$GLUETUN" | grep -q true; then
    yellow "gluetun not running — starting…"
    docker start "$GLUETUN" >/dev/null
    sleep 5
 fi
 VPN_IP="$(docker exec "$QBT" curl -sf --max-time "$TIMEOUT" https://api.ipify.org || true)"
 if [ -z "$VPN_IP" ]; then
    red "FAIL: qbt could not reach api.ipify.org even with gluetun up. Check VPN config."
    exit 1
 fi
 echo "qbt sees IP: $VPN_IP"
 if [ -n "$WAN_IP" ] && [ "$VPN_IP" = "$WAN_IP" ]; then
    red "FAIL: qbt's IP == host WAN IP. Traffic is NOT going through VPN."
    exit 1
 fi
 green "OK: qbt egressing via VPN."
 # --- Step 2: kill-switch check
 echo
 echo "Step 2: kill-switch — stop gluetun, qbt MUST fail to reach internet."
 docker stop "$GLUETUN" >/dev/null
 sleep 2
 set +e
 LEAK_IP="$(docker exec "$QBT" curl -sf --max-time "$TIMEOUT" https://api.ipify.org 2>/dev/null)"
 RC=$?
 set -e
 docker start "$GLUETUN" >/dev/null
 if [ $RC -eq 0 ] && [ -n "$LEAK_IP" ]; then
    red "FAIL: kill-switch broken — qbt reached the internet with VPN down."
    red "       Leaked IP: $LEAK_IP"
    red "       Tear down the stack and investigate before adding any torrents."
    exit 1
 fi
 green "OK: qbt could not reach internet with gluetun stopped."
 # --- Step 3: re-verify VPN comes back
 echo
 echo "Step 3: VPN restart — wait for gluetun to be healthy again."
 for i in $(seq 1 30); do
    if [ "$(docker inspect -f '{{.State.Health.Status}}' "$GLUETUN" 2>/dev/null || echo none)" = "healthy" ]; then
        break
    fi
    sleep 2
 done
 RECOVERY_IP="$(docker exec "$QBT" curl -sf --max-time "$TIMEOUT" https://api.ipify.org || true)"
 if [ -z "$RECOVERY_IP" ]; then
    yellow "WARN: gluetun did not recover within 60s. Check 'docker logs $GLUETUN'."
    exit 1
 fi
 green "OK: VPN recovered. qbt sees IP $RECOVERY_IP."
 echo
 green "Kill-switch test PASSED. Safe to seed."
--- a/scripts/migrate-onyx.sh
+++ b/scripts/migrate-onyx.sh
@ -0,0 +1,109 @@
 #!/usr/bin/env bash
 # scripts/migrate-onyx.sh — Phase 2 migration helper.
 #
 # Usage:
 #   ./migrate-onyx.sh <source-dir-on-onyx> <target-dir-on-nullstone>
 #
 # Example:
 #   ./migrate-onyx.sh "$HOME/Downloads/qbt/" \
 #                     /home/user/media/_downloads/complete/
 #
 # What it does:
 #   1. rsync <source-dir> → user@nullstone:<target-dir> over LAN.
 #   2. Copies onyx's .torrent + .fastresume files to /tmp/qbt-migrate/
 #      on nullstone (you mass-add them via qbt webui afterwards).
 #   3. Prints a checklist of remaining manual steps.
 #
 # Pre-reqs:
 #   - run from onyx (the SOURCE machine).
 #   - ssh user@nullstone reachable on LAN.
 #   - nullstone qbt stack already up (Phase 1 complete) — check with
 #     `bash killswitch-test.sh` first.
 set -euo pipefail
 SRC="${1:-}"
 DST="${2:-}"
 NULLSTONE="${NULLSTONE_SSH:-user@192.168.0.100}"
 DRY_RUN="${DRY_RUN:-1}"
 usage() {
    cat <<EOF
 Usage: $0 <source-dir> <target-dir-on-nullstone>
 Env:
  NULLSTONE_SSH   default: user@192.168.0.100
  DRY_RUN         default: 1 (rsync --dry-run). Set DRY_RUN=0 to actually copy.
 Example (dry-run):
  $0 "\$HOME/Downloads/qbt/" /home/user/media/_downloads/complete/
 Example (real):
  DRY_RUN=0 $0 "\$HOME/Downloads/qbt/" /home/user/media/_downloads/complete/
 EOF
    exit 2
 }
 [ -z "$SRC" ] || [ -z "$DST" ] && usage
 [ -d "$SRC" ] || { echo "Source dir not found: $SRC" >&2; exit 1; }
 QBT_BACKUP="$HOME/.local/share/qBittorrent/BT_backup"
 [ -d "$QBT_BACKUP" ] || { echo "qBittorrent BT_backup dir missing: $QBT_BACKUP" >&2; exit 1; }
 RSYNC_FLAGS=(-av --info=progress2 --partial --human-readable)
 if [ "$DRY_RUN" = "1" ]; then
    RSYNC_FLAGS+=(--dry-run)
    echo "=== DRY-RUN — no data will be copied. Set DRY_RUN=0 to run for real. ==="
 fi
 echo "=== Step 1/3: rsync data files to nullstone ==="
 rsync "${RSYNC_FLAGS[@]}" "$SRC" "$NULLSTONE:$DST"
 echo
 echo "=== Step 2/3: ship .torrent + .fastresume to nullstone /tmp/qbt-migrate/ ==="
 ssh "$NULLSTONE" "mkdir -p /tmp/qbt-migrate"
 if [ "$DRY_RUN" = "1" ]; then
    echo "(dry-run) would scp $QBT_BACKUP/*.torrent $QBT_BACKUP/*.fastresume → $NULLSTONE:/tmp/qbt-migrate/"
 else
    scp -q "$QBT_BACKUP"/*.torrent "$QBT_BACKUP"/*.fastresume "$NULLSTONE:/tmp/qbt-migrate/"
 fi
 echo
 echo "=== Step 3/3: remaining manual steps ==="
 cat <<EOF
 Manual steps on the nullstone qbt webui (https://qbt.s8n.ru):
  1. "Add Torrent" → multi-select all files in /tmp/qbt-migrate/*.torrent
     Save path: $DST
     [ ] UNCHECK "Start torrent" — we want them queued, not auto-resumed.
  2. Select all newly-added torrents → right-click → "Force recheck"
     qbt will hash-match files in $DST → mark each at 100% → start seeding.
  3. Check tracker status per torrent. Private trackers may reject the new
     source IP (Proton exit). See docs/trackers.md for the per-tracker
     mitigation playbook.
  4. On onyx (THIS machine): pause torrents one-by-one as nullstone takes
     over each. Do NOT stop onyx-qbt entirely until every torrent shows
     seeding on nullstone for 24h with zero tracker errors.
 Fastresume path-rewrite (optional, only if save_path drift breaks recheck):
  ssh $NULLSTONE 'python3 - <<PYEOF
 import os, re, sys
 from pathlib import Path
 src_prefix = "/home/admin/Downloads/qbt"     # onyx path
 dst_prefix = "/downloads/complete"            # nullstone path inside qbt container
 for fr in Path("/tmp/qbt-migrate").glob("*.fastresume"):
    data = fr.read_bytes()
    if src_prefix.encode() in data:
        new = data.replace(src_prefix.encode(), dst_prefix.encode())
        fr.write_bytes(new)
        print("rewrote:", fr.name)
 PYEOF'
  (Only run if force-recheck fails — qbt 5 usually handles re-pathing via
  the UI's "Save path" field on add.)
 EOF