magnet-scout 0.1.0__tar.gz

magnet_scout-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

magnet_scout-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,30 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -e '.[dev,dht]'
+      - run: ruff format --check .
+      - run: ruff check .
+      - run: mypy
+      - run: pytest
+      - run: python scripts/check_release.py
+      - run: bandit -r src -ll
+      - run: pip-audit . --progress-spinner off
+      - run: python -m build

magnet_scout-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,80 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify distributions
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+          cache: pip
+      - name: Install build tools
+        run: python -m pip install 'build>=1.2' 'twine>=6.1,<7'
+      - name: Validate release metadata
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: python scripts/check_release.py
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+      - name: Upload immutable build artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    if: github.event_name == 'workflow_dispatch'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/magnet-scout
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+
+  publish-pypi:
+    name: Publish to PyPI
+    if: github.event_name == 'release'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/magnet-scout
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish to PyPI with attestations
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist/

magnet_scout-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+dist/
+build/
+*.egg-info/

magnet_scout-0.1.0/AGENTS.md

@@ -0,0 +1,17 @@
+# MagnetScout agent instructions
+
+- Preserve the product boundary: return torrent metadata and magnet URIs only. Never add
+  payload or piece downloading, content storage, client launching, or media-library integration.
+- Prefer structured provider APIs and explicitly legal or public collections over generic web
+  search and brittle scraping.
+- Keep providers behind `SearchProvider`; one provider failing must not fail an aggregate search.
+- Treat provider seed counts as untrusted reports. Only verifier observations may populate
+  `verified`, `verified_peers`, or tracker and DHT evidence.
+- Canonicalize and deduplicate by info hash before verification and ranking.
+- Add fixtures and tests for every provider. Tests must not depend on the live network.
+- Keep timeouts and concurrency bounded. Never log full peer IP addresses.
+- DHT backends must use a hard deadline, perform peer discovery only, discard addresses after
+  counting, and never fetch metadata or announce. Prefer process isolation for blocking clients.
+- Record architectural discoveries and scoring changes in `docs/`.
+- Commit messages must be in English and should read like natural, human-written summaries.
+- Run `ruff format --check .`, `ruff check .`, `mypy`, and `pytest` before handing off changes.

magnet_scout-0.1.0/CHANGELOG.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## 0.1.0 - 2026-10-09
+
+- Initial CLI and Python API for searching public BitTorrent metadata providers.
+- Magnet parsing, info-hash normalization, metadata merging, verification, and health ranking.
+- Internet Archive, Academic Torrents, Fedora, and configurable Torznab adapters.

magnet_scout-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing
+
+Thank you for helping improve MagnetScout. Keep changes within the metadata-only boundary: no
+payload downloads, client launching, content storage, or media-library automation.
+
+Create a focused branch, add offline tests for behavior changes, and update the relevant document
+when provider behavior or scoring changes. Before opening a pull request, run:
+
+```console
+ruff format --check .
+ruff check .
+mypy
+pytest
+```
+
+Commit messages should be concise, natural English summaries of the change.

magnet_scout-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MagnetScout contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

magnet_scout-0.1.0/PKG-INFO

@@ -0,0 +1,129 @@
+Metadata-Version: 2.4
+Name: magnet-scout
+Version: 0.1.0
+Summary: Discover and assess public BitTorrent metadata without downloading payloads
+Project-URL: Homepage, https://github.com/monhoney/magnet-scout
+Project-URL: Repository, https://github.com/monhoney/magnet-scout
+Project-URL: Issues, https://github.com/monhoney/magnet-scout/issues
+Author: MagnetScout contributors
+License: MIT
+License-File: LICENSE
+Keywords: bittorrent,infohash,magnet,metadata,torrent,tracker
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet
+Requires-Python: >=3.11
+Requires-Dist: bencode-py<5,>=4.1
+Requires-Dist: click<8.3,>=8.2
+Requires-Dist: defusedxml<1,>=0.7.1
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: torf<5,>=4.3.1
+Requires-Dist: typer<0.21,>=0.20
+Provides-Extra: dev
+Requires-Dist: bandit<2,>=1.9; extra == 'dev'
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.15; extra == 'dev'
+Requires-Dist: pip-audit<3,>=2.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.11; extra == 'dev'
+Requires-Dist: twine<7,>=6.1; extra == 'dev'
+Requires-Dist: types-defusedxml>=0.7.0.20240218; extra == 'dev'
+Provides-Extra: dht
+Requires-Dist: pythontorrentdht<2,>=1.0.3; extra == 'dht'
+Description-Content-Type: text/markdown
+
+# MagnetScout
+
+MagnetScout is a lightweight Python CLI and library for discovering BitTorrent metadata from
+pluggable providers, normalizing magnet links, checking current swarm signals, and ranking useful
+results. It never downloads torrent payloads or sends results to a BitTorrent client.
+
+MagnetScout is intended for public, freely licensed, and otherwise lawfully distributed content.
+Metadata is informative rather than a legal determination; users remain responsible for deciding
+whether they may access a result.
+
+## Status
+
+The project is alpha software. Provider availability and swarm observations can change at any
+time, and a healthy score does not guarantee a successful download.
+
+## Install
+
+MagnetScout requires Python 3.11 or newer.
+
+```console
+python -m pip install magnet-scout
+```
+
+Until the first PyPI release, install from a checkout:
+
+```console
+python -m pip install -e .
+```
+
+Optional DHT peer discovery is installed separately:
+
+```console
+python -m pip install 'magnet-scout[dht]'
+```
+
+## CLI
+
+```console
+magnet-scout search ubuntu
+magnet-scout search ubuntu --top 10
+magnet-scout search ubuntu --verify --top 10
+magnet-scout search ubuntu --verify --min-verified-seeders 3
+magnet-scout search ubuntu --json
+magnet-scout search dataset --provider academic-torrents
+```
+
+The default providers are Internet Archive, Academic Torrents, and Fedora. Provider failures are
+reported independently, so one unavailable source does not discard results from the others.
+
+`--verify` performs bounded tracker and web-seed observations without requesting payload pieces.
+`--dht` adds optional, process-isolated peer discovery. A provider's reported seeder count remains
+separate from independently observed values.
+
+## Python API
+
+```python
+from magnet_scout import parse_magnet
+
+magnet = parse_magnet("magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567&dn=Example")
+print(magnet.info_hash)
+print(magnet.canonical_uri)
+```
+
+Provider integration uses the asynchronous `SearchProvider` protocol. See
+[docs/providers.md](docs/providers.md) for a complete example.
+
+## Evidence, not guarantees
+
+- `reported_seeders` is untrusted metadata supplied by a provider.
+- `verified_seeders` is a recent tracker observation when the tracker supports scraping.
+- `dht_peers` counts peer endpoints discovered during a bounded lookup; addresses are discarded.
+- `UNKNOWN` means there was not enough independent evidence. It does not mean dead.
+- No check proves that a complete payload will remain available.
+
+The exact score and ranking rules are documented in
+[docs/health-scoring.md](docs/health-scoring.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Providers](docs/providers.md)
+- [Health scoring](docs/health-scoring.md)
+- [Development](docs/development.md)
+- [Release process](docs/releasing.md)
+
+## License
+
+MagnetScout is released under the MIT License.

magnet_scout-0.1.0/README.md

@@ -0,0 +1,88 @@
+# MagnetScout
+
+MagnetScout is a lightweight Python CLI and library for discovering BitTorrent metadata from
+pluggable providers, normalizing magnet links, checking current swarm signals, and ranking useful
+results. It never downloads torrent payloads or sends results to a BitTorrent client.
+
+MagnetScout is intended for public, freely licensed, and otherwise lawfully distributed content.
+Metadata is informative rather than a legal determination; users remain responsible for deciding
+whether they may access a result.
+
+## Status
+
+The project is alpha software. Provider availability and swarm observations can change at any
+time, and a healthy score does not guarantee a successful download.
+
+## Install
+
+MagnetScout requires Python 3.11 or newer.
+
+```console
+python -m pip install magnet-scout
+```
+
+Until the first PyPI release, install from a checkout:
+
+```console
+python -m pip install -e .
+```
+
+Optional DHT peer discovery is installed separately:
+
+```console
+python -m pip install 'magnet-scout[dht]'
+```
+
+## CLI
+
+```console
+magnet-scout search ubuntu
+magnet-scout search ubuntu --top 10
+magnet-scout search ubuntu --verify --top 10
+magnet-scout search ubuntu --verify --min-verified-seeders 3
+magnet-scout search ubuntu --json
+magnet-scout search dataset --provider academic-torrents
+```
+
+The default providers are Internet Archive, Academic Torrents, and Fedora. Provider failures are
+reported independently, so one unavailable source does not discard results from the others.
+
+`--verify` performs bounded tracker and web-seed observations without requesting payload pieces.
+`--dht` adds optional, process-isolated peer discovery. A provider's reported seeder count remains
+separate from independently observed values.
+
+## Python API
+
+```python
+from magnet_scout import parse_magnet
+
+magnet = parse_magnet("magnet:?xt=urn:btih:0123456789abcdef0123456789abcdef01234567&dn=Example")
+print(magnet.info_hash)
+print(magnet.canonical_uri)
+```
+
+Provider integration uses the asynchronous `SearchProvider` protocol. See
+[docs/providers.md](docs/providers.md) for a complete example.
+
+## Evidence, not guarantees
+
+- `reported_seeders` is untrusted metadata supplied by a provider.
+- `verified_seeders` is a recent tracker observation when the tracker supports scraping.
+- `dht_peers` counts peer endpoints discovered during a bounded lookup; addresses are discarded.
+- `UNKNOWN` means there was not enough independent evidence. It does not mean dead.
+- No check proves that a complete payload will remain available.
+
+The exact score and ranking rules are documented in
+[docs/health-scoring.md](docs/health-scoring.md).
+
+## Documentation
+
+- [Architecture](docs/architecture.md)
+- [Providers](docs/providers.md)
+- [Health scoring](docs/health-scoring.md)
+- [Development](docs/development.md)
+- [Release process](docs/releasing.md)
+
+## License
+
+MagnetScout is released under the MIT License.

magnet_scout-0.1.0/SECURITY.md

@@ -0,0 +1,14 @@
+# Security policy
+
+Please report suspected vulnerabilities privately through GitHub's security advisory feature.
+Do not include API keys, full peer addresses, or private index URLs in a public issue.
+
+MagnetScout processes untrusted network metadata. Reports involving unsafe metainfo parsing,
+credential exposure, unbounded network activity, SSRF, or unexpected payload retrieval are
+especially useful. The project does not consider provider downtime or stale swarm counts a
+security vulnerability.
+
+Every external response is subject to a decompressed byte limit before parsing. XML entity
+expansion and redirects are disabled, tracker and web-seed verification rejects non-public address
+ranges, and DHT discovery runs in a disposable process. These controls are security boundaries;
+changes to them require regression tests and updated architecture documentation.

magnet_scout-0.1.0/docs/architecture.md

@@ -0,0 +1,53 @@
+# Architecture
+
+## Scope
+
+MagnetScout returns normalized torrent metadata and magnet URIs. It does not download pieces,
+store payload content, launch torrent clients, or manage media libraries.
+
+## Search pipeline
+
+```text
+query
+  -> concurrent providers
+  -> normalized TorrentResult values
+  -> magnet validation and canonical info hashes
+  -> merge by info hash
+  -> optional bounded verification
+  -> health and confidence scoring
+  -> ranking and filters
+  -> CLI or Python result objects
+```
+
+`SearchService` owns orchestration. Each provider implements `SearchProvider`, and exceptions are
+converted to `ProviderFailure` entries. The successful providers continue to contribute results.
+
+## Models and normalization
+
+`TorrentResult` keeps claims and observations distinct. Provider counts use `reported_*` fields;
+tracker and DHT observations use `verified_*` and `dht_peers`. Missing data stays `None` rather
+than becoming a misleading zero.
+
+`parse_magnet` accepts hexadecimal and base32 BEP 9 `btih` values and produces a lowercase,
+40-character hexadecimal info hash. `merge_results` uses that hash as its key, retains all source
+providers and URLs, and merges the richest available metadata.
+
+## Verification boundaries
+
+The tracker verifier sends HTTP(S) or UDP scrape requests where supported. It does not announce as
+a peer. Web-seed checks make bounded HTTP `HEAD` requests for responsiveness and do not count as
+swarm health. Optional DHT verification runs in a separate process under a hard deadline, requests
+peer discovery only, counts returned endpoints, and discards their addresses.
+
+All network work uses explicit timeouts, concurrency limits, and decompressed response-size caps.
+Redirects are disabled so credentials and bounded-request rules cannot be bypassed through a
+redirect chain. Environment proxy variables are ignored by the CLI. Verification observations are
+cached briefly to avoid repeatedly contacting infrastructure.
+
+## Trust boundaries
+
+Provider titles, descriptions, counts, links, and torrent files are untrusted input. Control
+characters are removed in human output, XML entities are disabled, magnet complexity is bounded,
+torrent metainfo is parsed without materializing payloads, and provider errors cannot terminate
+aggregate search. API keys for optional Torznab providers are read from environment variables,
+never stored directly in the configuration file, and sent only to HTTPS endpoints.

magnet_scout-0.1.0/docs/development.md

@@ -0,0 +1,39 @@
+# Development
+
+```console
+python -m pip install -e '.[dev,dht]'
+ruff check .
+mypy
+pytest
+bandit -r src -ll
+pip-audit . --progress-spinner off
+python -m build
+```
+
+Tests use injected HTTPX transports and fixtures and must pass offline. To make
+a live smoke test, run `magnet-scout search ubuntu --provider internet-archive
+--top 3`; live API failures should produce a provider warning and a nonzero exit
+only when no provider produced results.
+
+Structured diagnostics use Python logging and go to stderr so JSON stdout stays
+machine-readable. Do not include peer addresses in logs or fixtures.
+
+Tracker verification tests use HTTPX's in-process mock transport and binary UDP
+response fixtures. They must never contact public trackers during the test
+suite. Live verification reveals the caller's IP address to each queried
+tracker even though scrape does not register the caller as a swarm peer.
+
+The SQLite verification cache defaults to
+`$XDG_CACHE_HOME/magnet-scout/verification.sqlite3` (or `~/.cache/...`). Tests
+must use `tmp_path`; never write tests into a developer's real cache.
+
+CI runs formatting, lint, strict typing, tests, and wheel/sdist builds on Python
+3.11–3.13. DHT tests use a stubbed count path plus a real parent-deadline test;
+they do not query the public DHT.
+
+Torznab tests use XML fixtures and HTTPX mock transports. Never put real API
+keys in fixtures, command examples, exception messages, or snapshots.
+
+See `docs/releasing.md` for the release checklist. Do not create a version tag
+before a release commit exists, and do not publish externally without explicit
+authorization.

magnet_scout-0.1.0/docs/health-scoring.md

@@ -0,0 +1,53 @@
+# Health and confidence scoring
+
+Scores are evidence summaries, never availability guarantees.
+
+## Current formula
+
+Health starts at 0 and is capped at 100:
+
+- independently observed peers: `min(60, 15 * log2(peers + 1))`
+- responsive tracker with observed peers: 15
+- metadata observed from the swarm: 10
+- each additional reporting provider: 5, capped at 10
+- reported seeders: `min(5, log2(seeders + 1))`; deliberately low weight
+- freshness: 5 when checked within 15 minutes, fading linearly to 0 at 24 hours
+
+Classification: `EXCELLENT >= 80`, `GOOD >= 60`, `FAIR >= 40`, `POOR > 0`,
+`DEAD = 0` only when at least one tracker returned a valid zero-peer scrape.
+Timeouts, tracker errors, unsupported trackers, and absent trackers remain
+`UNKNOWN` rather than being treated as evidence of death.
+
+Confidence is separate. It starts at 10 for valid normalized metadata, adds 15
+per provider (cap 45), 25 for a completed independent check, 10 for a responsive
+tracker, 10 for a responsive web-seed endpoint, 5 for swarm metadata, and up to
+10 for freshness. It is capped at 100. Web-seed responsiveness never adds
+health points and never changes the swarm health classification.
+
+Provider-reported counts never set `verified`. Tracker scrape values populate
+`verified_seeders`, `verified_leechers`, and `verified_peers`. Counts from
+different trackers are not summed because their peer sets may overlap; the
+maximum observation is retained. A positive peer count sets `verified`, but
+does not guarantee that a complete, reachable copy can be downloaded.
+
+`verification_status` makes the evidence explicit:
+
+- `NOT_CHECKED`: no verification was requested or no supported tracker exists
+- `VERIFIED_SEEDED`: at least one tracker reported a complete peer
+- `VERIFIED_PEERS_ONLY`: peers were reported but no complete peer was observed
+- `TRACKER_RESPONSIVE`: a valid scrape reported zero peers
+- `UNREACHABLE`: supported trackers were tried but none returned a valid scrape
+
+With `--dht`, `dht_peers` is an independently discovered peer count. A positive
+count can produce `VERIFIED_PEERS_ONLY`, but cannot prove that a complete seeder
+exists; only a tracker complete count can produce `VERIFIED_SEEDED`. A zero DHT
+count alone remains `UNKNOWN` because DHT observation is incomplete by nature.
+
+## Ranking
+
+Sort keys, in order, are: verified status, health score, verified peers,
+provider count, responsive web seed, confidence, freshness, reported seeders,
+then title. Missing numbers sort below known numbers. With `--verify`, `--min-seeders` uses
+`verified_seeders`; otherwise it uses the provider-reported field. Unknown
+values are excluded. Prefer the unambiguous `--min-reported-seeders` and
+`--min-verified-seeders` options; `--min-seeders` exists for compatibility.

magnet_scout-0.1.0/docs/providers.md

@@ -0,0 +1,63 @@
+# Providers
+
+Providers translate a source-specific response into `TorrentResult` objects. They never rank
+results, mark provider claims as verified, or download torrent payloads.
+
+## Included providers
+
+| Name | Source | Notes |
+| --- | --- | --- |
+| `internet-archive` | Internet Archive advanced search and metadata APIs | Public collections; optional subject and explicit-license filters |
+| `academic-torrents` | Academic Torrents public index | Research datasets and publications; index is cached locally |
+| `fedora` | Fedora torrent metadata | Official Fedora release torrents |
+| configurable name | Torznab-compatible API | Optional; trust and legality depend on the configured service |
+
+The first three are enabled by default. Torznab endpoints are opt-in because they vary in quality,
+policy, authentication, and content.
+
+## Interface
+
+```python
+from typing import Protocol
+
+from magnet_scout.models import TorrentResult
+
+
+class SearchProvider(Protocol):
+    name: str
+
+    async def search(self, query: str, limit: int) -> list[TorrentResult]: ...
+```
+
+A provider should:
+
+1. Use a structured, documented endpoint where possible.
+2. Apply the supplied result limit and the shared HTTP client's timeout.
+3. Produce a valid magnet URI and place the source name in `providers`.
+4. Put source pages in `provider_urls`, not arbitrary download destinations.
+5. Treat seed and leech counts as reported data only.
+6. Leave unavailable values as `None`.
+7. Include offline fixtures and tests for success, malformed data, and server failure.
+
+Register a default provider in `providers/registry.py`. A provider exception is deliberately
+isolated by `SearchService`; do not catch broad exceptions merely to return an empty list.
+
+## Torznab configuration
+
+Create `${XDG_CONFIG_HOME:-~/.config}/magnet-scout/config.toml`:
+
+```toml
+[[torznab]]
+name = "my-index"
+url = "https://example.invalid/api"
+api_key_env = "MY_INDEX_API_KEY"
+```
+
+Then export the key and select the configured provider:
+
+```console
+export MY_INDEX_API_KEY='...'
+magnet-scout search example --provider my-index
+```
+
+MagnetScout does not endorse or determine the legality of a configured Torznab source.