ragx-cli 0.3.0__tar.gz → 0.3.3__tar.gz

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/.github/workflows/publish.yml

@@ -8,8 +8,8 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
       - run: uv sync --group dev
       - run: uv run pytest -q
       - run: uv run ruff check src tests
@@ -21,8 +21,8 @@ jobs:
     permissions:
       id-token: write
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v8.3.2
       - name: Check tag matches package version
         run: |
           VERSION=$(uv version --short)

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `ragx-cli` are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versions follow
 [Semantic Versioning](https://semver.org/).
 
+## [0.3.3] — 2026-07-15
+
+### Added
+
+- **Early hint when the reranker model download stalls**: the huggingface_hub retry
+  loop inside the cross-encoder load can spin for minutes before failing. The first
+  retry warning now also prints a one-shot stderr pointer to the README's "Reranker on
+  restricted networks" section (manual copy, mirror, or `rerank.enabled false`).
+
+## [0.3.2] — 2026-07-15
+
+_0.3.1 was tagged but never published — its release workflow referenced a nonexistent
+action tag; 0.3.2 is the same change plus the CI fix._
+
+### Changed
+
+- **Legacy config self-heals**: finding a pre-0.3.0 `.ragx/config.toml` no longer fails
+  loud — on a TTY, `ragx-cli` asks before moving it to `ragx.toml` (declining prints the
+  `mv` and exits); non-interactive runs migrate automatically with a stderr notice. Both
+  files existing at once is still a hard error.
+
 ## [0.3.0] — 2026-07-14
 
 ### Changed (BREAKING)
@@ -83,6 +104,8 @@ Initial release: Phases 0–3 of [the plan](ragx-cli-plan.md), built and validat
   on stderr, exit codes `0` results / `1` empty / `2` error.
 - MIT license; PyPI packaging as `ragx-cli` with trusted-publishing release workflow.
 
+[0.3.3]: https://github.com/alber70g/ragx-cli/compare/v0.3.2...v0.3.3
+[0.3.2]: https://github.com/alber70g/ragx-cli/compare/v0.3.0...v0.3.2
 [0.3.0]: https://github.com/alber70g/ragx-cli/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/alber70g/ragx-cli/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/alber70g/ragx-cli/compare/v0.1.0...v0.1.1

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/CLAUDE.md

@@ -39,7 +39,8 @@ src/ragx/
   core/            # all logic lives here, CLI-independent
     config.py      #   ragx.toml at corpus root (committable; 0.3.0 moved it out of .ragx/) +
                    #   ~/.ragxrc (provider sections; rc wins, warns), DEFAULTS, find_root;
-                   #   legacy .ragx/config.toml fails loud with a migration hint
+                   #   legacy .ragx/config.toml self-heals: auto-moved on load (CLI passes a
+                   #   TTY confirm via output.migrate_confirm; both-files-exist fails loud)
     models.py      #   Chunk, ChunkDraft, FileRecord, Edge, ScoredChunk, QueryOutput
     store.py       #   SQLite: files/chunks/edges/meta; replace_edges normalizes src<dst
     vectors.py     #   hnswlib wrapper; soft-delete via JSON sidecar; get_vectors for graph
@@ -60,7 +61,7 @@ src/ragx/
                    # st_reranker.py; registry.py factories (env-var + api_key_env resolution)
   cli/             # thin shells only: app.py (init/status/config + registration),
                    # pipeline.py (index/query), inspect_cmd.py, eval_cmd.py, output.py
-tests/             # 173 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
+tests/             # 177 tests; mocked HTTP (respx), FakeEmbedder integration tests, no live network
 ```
 
 ## Flows
@@ -141,11 +142,11 @@ mostly on Dutch/multilingual queries. Details: `research/bge-m3-dense-q8-vs-nomi
 - Temporal weighting: full decided spec in `docs/feature-temporal-weighting.md` — opt-in
   `--since/--until/--temporal recent|oldest`, date cascade filename/frontmatter → git → mtime,
   schema v2 migration. Build only after it can be measured against the eval baseline.
-- README packaging claims (`uvx ragx-cli`; PyPI name ragx-cli, plain `ragx` is name-blocked) are aspirational — not yet published to PyPI.
+- Published to PyPI as `ragx-cli` (plain `ragx` is name-blocked); releases go out via the `v*`-tag trusted-publishing workflow.
 
 ## Dev loop
 
-`uv sync --group dev --extra rerank` · `uv run pytest -q` (173 pass, ~5 s) ·
+`uv sync --group dev --extra rerank` · `uv run pytest -q` (177 pass, ~5 s) ·
 `uv run ruff check src tests` · file soft cap ~150 lines · expected failures raise `RagxError`
 (CLI maps to exit 2). Live smoke: LM Studio must be running with the configured embedding model.
 Changes that impact usage (CLI flags, config keys/precedence, output schemas, install steps)

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ragx-cli
-Version: 0.3.0
+Version: 0.3.3
 Summary: Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it
 Project-URL: Repository, https://github.com/alber70g/ragx-cli
 Project-URL: Issues, https://github.com/alber70g/ragx-cli/issues
@@ -466,8 +466,10 @@ committed with your corpus; `.ragx/` (index data) is safe to gitignore — a fre
 runs `ragx-cli index`. The config file itself is never indexed as corpus content.
 
 > **Upgrading from ≤0.2.x:** the config moved from `.ragx/config.toml` to `ragx.toml` at the
-> corpus root. Commands fail with a migration hint until you
-> `mv .ragx/config.toml ragx.toml`. The index itself is untouched.
+> corpus root, and ragx-cli migrates it for you on first use: on a TTY it asks before moving
+> the file (declining leaves everything untouched and prints the `mv` to run yourself);
+> piped/agent runs migrate automatically with a notice on stderr. If both files exist,
+> commands fail loud — keep one and delete the other. The index itself is untouched.
 
 `ragx-cli init` is **interactive when run on a TTY**: it probes the default LM Studio
 (`localhost:1234`) and Ollama (`localhost:11434`) ports, lists the models each server
@@ -509,7 +511,7 @@ unchecked ones are next up. Release history: [CHANGELOG.md](CHANGELOG.md).
 - [ ] **query --global** for corpus-level questions (answer from community summaries, not individual chunks)
 - [ ] **MCP server**: a second thin shell over `ragx.core` (the core/CLI split it needs is already enforced)
 - [ ] **[Temporal weighting](docs/feature-temporal-weighting.md)**: opt-in `--since`/`--until`/`--temporal recent|oldest`, date cascade filename/frontmatter → git → mtime
-- [ ] **Release**: publish to PyPI as `ragx-cli` (plain `ragx` is name-blocked, too similar to an existing project) so `uvx ragx-cli` works out of the box
+- [x] **Release**: publish to PyPI as `ragx-cli` (plain `ragx` is name-blocked, too similar to an existing project) so `uvx ragx-cli` works out of the box
 
-Development: `uv sync --group dev && uv run pytest`. 173 tests; module contracts live in
+Development: `uv sync --group dev && uv run pytest`. 177 tests; module contracts live in
 `CONTRACTS.md` / `CONTRACTS-PHASE23.md`.

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/README.md

@@ -438,8 +438,10 @@ committed with your corpus; `.ragx/` (index data) is safe to gitignore — a fre
 runs `ragx-cli index`. The config file itself is never indexed as corpus content.
 
 > **Upgrading from ≤0.2.x:** the config moved from `.ragx/config.toml` to `ragx.toml` at the
-> corpus root. Commands fail with a migration hint until you
-> `mv .ragx/config.toml ragx.toml`. The index itself is untouched.
+> corpus root, and ragx-cli migrates it for you on first use: on a TTY it asks before moving
+> the file (declining leaves everything untouched and prints the `mv` to run yourself);
+> piped/agent runs migrate automatically with a notice on stderr. If both files exist,
+> commands fail loud — keep one and delete the other. The index itself is untouched.
 
 `ragx-cli init` is **interactive when run on a TTY**: it probes the default LM Studio
 (`localhost:1234`) and Ollama (`localhost:11434`) ports, lists the models each server
@@ -481,7 +483,7 @@ unchecked ones are next up. Release history: [CHANGELOG.md](CHANGELOG.md).
 - [ ] **query --global** for corpus-level questions (answer from community summaries, not individual chunks)
 - [ ] **MCP server**: a second thin shell over `ragx.core` (the core/CLI split it needs is already enforced)
 - [ ] **[Temporal weighting](docs/feature-temporal-weighting.md)**: opt-in `--since`/`--until`/`--temporal recent|oldest`, date cascade filename/frontmatter → git → mtime
-- [ ] **Release**: publish to PyPI as `ragx-cli` (plain `ragx` is name-blocked, too similar to an existing project) so `uvx ragx-cli` works out of the box
+- [x] **Release**: publish to PyPI as `ragx-cli` (plain `ragx` is name-blocked, too similar to an existing project) so `uvx ragx-cli` works out of the box
 
-Development: `uv sync --group dev && uv run pytest`. 173 tests; module contracts live in
+Development: `uv sync --group dev && uv run pytest`. 177 tests; module contracts live in
 `CONTRACTS.md` / `CONTRACTS-PHASE23.md`.

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "ragx-cli"
-version = "0.3.0"
+version = "0.3.3"
 description = "Similarity-graph RAG CLI: index a corpus into a chunk-level embedding graph and query it"
 readme = "README.md"
 license = "MIT"

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/src/ragx/cli/app.py

@@ -9,7 +9,7 @@ from pathlib import Path
 import typer
 
 from ragx.cli.init_prompt import collect_answers
-from ragx.cli.output import emit_json, fail
+from ragx.cli.output import emit_json, fail, migrate_confirm
 from ragx.core.config import (
     DEFAULTS,
     Config,
@@ -43,7 +43,7 @@ def _require_root() -> Path:
 
 def _load_config(root: Path) -> Config:
     try:
-        return Config.load(root)
+        return Config.load(root, confirm=migrate_confirm())
     except RagxError as exc:
         fail(str(exc))
 

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/src/ragx/cli/eval_cmd.py

@@ -7,7 +7,7 @@ from pathlib import Path
 
 import typer
 
-from ragx.cli.output import emit_json, fail
+from ragx.cli.output import emit_json, fail, migrate_confirm
 from ragx.core.config import Config, require_root
 from ragx.core.errors import RagxError
 from ragx.core.eval import evaluate, load_queries
@@ -45,7 +45,7 @@ def eval_cmd(
 
     try:
         root = require_root()
-        cfg = Config.load(root)
+        cfg = Config.load(root, confirm=migrate_confirm())
         embedder = make_embedder(cfg)
         generator = make_generator(cfg) if any(_BUILTIN_CONFIGS[n].expand for n in names) else None
         reranker = make_reranker(cfg) if any(_BUILTIN_CONFIGS[n].rerank for n in names) else None

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/src/ragx/cli/output.py

@@ -5,8 +5,11 @@ from __future__ import annotations
 
 import json
 import sys
+from collections.abc import Callable
 from typing import NoReturn
 
+import typer
+
 
 def emit_json(doc: dict) -> None:
     """Write exactly one JSON document to stdout, nothing else on stdout."""
@@ -17,3 +20,11 @@ def fail(msg: str, code: int = 2) -> NoReturn:
     """Print an error message to stderr and exit with `code`."""
     print(msg, file=sys.stderr)
     raise SystemExit(code)
+
+
+def migrate_confirm() -> Callable[[str], bool] | None:
+    """Confirm callback for Config.load's legacy-config migration: prompt on a TTY,
+    None (migrate silently) for piped/agent runs."""
+    if not sys.stdin.isatty():
+        return None
+    return lambda prompt: typer.confirm(prompt, default=True)

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/src/ragx/cli/pipeline.py

@@ -7,7 +7,7 @@ from pathlib import Path
 
 import typer
 
-from ragx.cli.output import emit_json, fail
+from ragx.cli.output import emit_json, fail, migrate_confirm
 from ragx.core.config import Config, require_root
 from ragx.core.errors import RagxError
 from ragx.core.indexer import run_index
@@ -28,7 +28,7 @@ def index(
     """Chunk, embed, and index the corpus (full rebuild unless --changed)."""
     try:
         root = require_root(path)
-        cfg = Config.load(root)
+        cfg = Config.load(root, confirm=migrate_confirm())
         stats = run_index(root, cfg, make_embedder(cfg), changed_only=changed)
     except RagxError as exc:
         fail(str(exc))
@@ -59,7 +59,7 @@ def query(
         text = sys.stdin.read().strip()
     try:
         root = require_root()
-        cfg = Config.load(root)
+        cfg = Config.load(root, confirm=migrate_confirm())
         opts = QueryOptions(
             top=top if top is not None else cfg.get("query.top"),
             files_only=files_only,

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/src/ragx/core/config.py

@@ -6,6 +6,7 @@ from __future__ import annotations
 
 import logging
 import tomllib
+from collections.abc import Callable
 from pathlib import Path
 from typing import Any
 
@@ -88,6 +89,30 @@ def vectors_path(root: Path) -> Path:
     return root / RAGX_DIR / "vectors.hnsw"
 
 
+def _migrate_legacy(root: Path, confirm: Callable[[str], bool] | None) -> None:
+    """Self-heal a pre-0.3.0 corpus: move .ragx/config.toml to ragx.toml at the root.
+
+    `confirm` (interactive callers) is asked before touching anything; declining keeps
+    the old fail-loud error. Without it (agents, library use) the move just happens,
+    with a stderr notice. Both files existing stays a hard error — picking one could
+    silently discard edits."""
+    legacy = root / RAGX_DIR / "config.toml"
+    if not legacy.exists():
+        return
+    target = root / CONFIG_FILE
+    if target.exists():
+        raise RagxError(
+            f"both {target} and legacy {legacy} exist — config moved to ragx.toml "
+            f"in 0.3.0; keep one and delete the other"
+        )
+    if confirm is not None and not confirm(
+        f"config moved in 0.3.0: move legacy {legacy} to {target}?"
+    ):
+        raise RagxError(f"config not migrated — run `mv {legacy} {target}` to proceed")
+    legacy.rename(target)
+    log.warning("config moved in 0.3.0: migrated %s -> %s", legacy, target)
+
+
 def _deep_merge(base: dict, override: dict) -> dict:
     out = {k: dict(v) for k, v in base.items()}
     for section, values in override.items():
@@ -160,13 +185,13 @@ class Config:
         self.file_data = file_data if file_data is not None else data
 
     @classmethod
-    def load(cls, root: Path, rc: Path | None = None) -> Config:
-        legacy = root / RAGX_DIR / "config.toml"
-        if legacy.exists():
-            raise RagxError(
-                f"config moved in 0.3.0: found legacy {legacy} — "
-                f"run `mv {legacy} {root / CONFIG_FILE}`"
-            )
+    def load(
+        cls,
+        root: Path,
+        rc: Path | None = None,
+        confirm: Callable[[str], bool] | None = None,
+    ) -> Config:
+        _migrate_legacy(root, confirm)
         path = config_path(root)
         file_data: dict = {}
         if path.exists():

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/src/ragx/providers/st_reranker.py

@@ -2,10 +2,36 @@
 
 from __future__ import annotations
 
+import logging
+import sys
 from typing import Sequence
 
 from ragx.core.errors import RagxError
 
+_MANUAL_INSTALL_HINT = (
+    "downloading the reranker model from huggingface.co is failing — to install the "
+    "model manually, use a mirror, or disable reranking, see "
+    "https://github.com/alber70g/ragx-cli#reranker-on-restricted-networks-no-huggingfaceco"
+)
+
+
+class _DownloadHintHandler(logging.Handler):
+    """Emits the manual-install hint once, on the first huggingface_hub retry warning."""
+
+    def __init__(self) -> None:
+        super().__init__(level=logging.WARNING)
+        self._fired = False
+
+    def emit(self, record: logging.LogRecord) -> None:
+        if self._fired:
+            return
+        message = record.getMessage().lower()
+        if "retry" in message or "thrown while requesting" in message:
+            self._fired = True
+            # logging drops re-entrant calls made while a record is being
+            # handled, so the hint must go to stderr directly.
+            print(f"WARNING: {_MANUAL_INSTALL_HINT}", file=sys.stderr)
+
 
 class STReranker:
     """Reranker implementing providers.base.Reranker via a sentence-transformers CrossEncoder."""
@@ -20,6 +46,9 @@ class STReranker:
                 "sentence-transformers not installed — install with: uv tool install ragx-cli --with ragx-cli[rerank]"
             ) from exc
         self.model = model
+        hint = _DownloadHintHandler()
+        hub_logger = logging.getLogger("huggingface_hub")
+        hub_logger.addHandler(hint)
         try:
             self._encoder = CrossEncoder(model)
         except Exception as exc:
@@ -30,6 +59,8 @@ class STReranker:
                 "reranking (rerank.enabled false); see README 'Reranker on restricted "
                 "networks (no huggingface.co)'"
             ) from exc
+        finally:
+            hub_logger.removeHandler(hint)
 
     def score(self, query: str, texts: Sequence[str]) -> list[float]:
         pairs = [[query, text] for text in texts]

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/tests/test_cli.py

@@ -8,6 +8,7 @@ import respx
 from typer.testing import CliRunner
 
 from ragx.cli.app import app
+from ragx.cli.output import migrate_confirm
 from ragx.core.config import CONFIG_FILE, Config
 
 runner = CliRunner()
@@ -124,14 +125,33 @@ def test_config_get_bogus_key(tmp_path, monkeypatch):
     assert result.exit_code == 2
 
 
-def test_legacy_config_location_exits_2_with_hint(tmp_path, monkeypatch):
+def test_legacy_config_auto_migrates_when_not_a_tty(tmp_path, monkeypatch):
+    # piped stdin (agents): the pre-0.3.0 config self-heals without a prompt
     (tmp_path / ".ragx").mkdir()
     (tmp_path / ".ragx" / "config.toml").write_text("[graph]\nk = 12\n")
     monkeypatch.chdir(tmp_path)
 
     result = runner.invoke(app, ["config", "get", "graph.k"])
-    assert result.exit_code == 2
-    assert "config moved" in result.output
+    assert result.exit_code == 0
+    assert result.output.strip() == "12"
+    assert (tmp_path / CONFIG_FILE).exists()
+    assert not (tmp_path / ".ragx" / "config.toml").exists()
+
+
+def test_migrate_confirm_prompts_only_on_tty(monkeypatch):
+    class Tty:
+        def isatty(self):
+            return True
+
+    monkeypatch.setattr("sys.stdin", Tty())
+    assert migrate_confirm() is not None
+
+    class Pipe:
+        def isatty(self):
+            return False
+
+    monkeypatch.setattr("sys.stdin", Pipe())
+    assert migrate_confirm() is None
 
 
 def test_config_without_init(tmp_path, monkeypatch):

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/tests/test_config_rc.py

@@ -55,12 +55,47 @@ def test_rc_applies_without_corpus_file(tmp_path, rc, caplog):
     assert not caplog.records
 
 
-def test_legacy_config_location_fails_loud(tmp_path, rc):
-    # pre-0.3.0 corpora kept config at .ragx/config.toml; loading must demand the move
+def _write_legacy(tmp_path):
     (tmp_path / ".ragx").mkdir()
     (tmp_path / ".ragx" / "config.toml").write_text("[graph]\nk = 12\n")
-    with pytest.raises(RagxError, match="config moved"):
+
+
+def test_legacy_config_auto_migrates_without_confirm(tmp_path, rc, caplog):
+    # pre-0.3.0 corpora self-heal: non-interactive loads just move the file, with a notice
+    _write_legacy(tmp_path)
+    with caplog.at_level(logging.WARNING, logger="ragx.config"):
+        cfg = Config.load(tmp_path)
+    assert cfg.get("graph.k") == 12
+    assert config_path(tmp_path).exists()
+    assert not (tmp_path / ".ragx" / "config.toml").exists()
+    assert any("migrated" in r.getMessage() for r in caplog.records)
+
+
+def test_legacy_config_confirm_accepted_migrates(tmp_path, rc):
+    _write_legacy(tmp_path)
+    prompts: list[str] = []
+    cfg = Config.load(tmp_path, confirm=lambda msg: prompts.append(msg) or True)
+    assert cfg.get("graph.k") == 12
+    assert config_path(tmp_path).exists()
+    assert len(prompts) == 1 and "config moved in 0.3.0" in prompts[0]
+
+
+def test_legacy_config_confirm_declined_fails_loud(tmp_path, rc):
+    # declining the prompt keeps the old fail-loud behavior and touches nothing
+    _write_legacy(tmp_path)
+    with pytest.raises(RagxError, match="not migrated"):
+        Config.load(tmp_path, confirm=lambda msg: False)
+    assert (tmp_path / ".ragx" / "config.toml").exists()
+    assert not config_path(tmp_path).exists()
+
+
+def test_legacy_and_new_config_both_present_fails_loud(tmp_path, rc):
+    # migrating over an existing ragx.toml could discard edits — never pick silently
+    _write_legacy(tmp_path)
+    config_path(tmp_path).write_text("[graph]\nk = 5\n")
+    with pytest.raises(RagxError, match="keep one"):
         Config.load(tmp_path)
+    assert (tmp_path / ".ragx" / "config.toml").exists()
 
 
 def test_root_found_via_config_file_alone(tmp_path):

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/tests/test_eval.py

@@ -197,7 +197,7 @@ def test_eval_cmd_json_output(tmp_path, monkeypatch):
     }
     monkeypatch.setattr(eval_cmd_mod, "load_queries", lambda path: [{"query": "q", "relevant_files": []}])
     monkeypatch.setattr(eval_cmd_mod, "require_root", lambda: tmp_path)
-    monkeypatch.setattr(eval_cmd_mod.Config, "load", classmethod(lambda cls, root: object()))
+    monkeypatch.setattr(eval_cmd_mod.Config, "load", classmethod(lambda cls, root, confirm=None: object()))
     monkeypatch.setattr(eval_cmd_mod, "make_embedder", lambda cfg: object())
     monkeypatch.setattr(
         eval_cmd_mod,
@@ -223,7 +223,7 @@ def test_eval_cmd_human_table(tmp_path, monkeypatch):
     }
     monkeypatch.setattr(eval_cmd_mod, "load_queries", lambda path: [{"query": "q", "relevant_files": []}])
     monkeypatch.setattr(eval_cmd_mod, "require_root", lambda: tmp_path)
-    monkeypatch.setattr(eval_cmd_mod.Config, "load", classmethod(lambda cls, root: object()))
+    monkeypatch.setattr(eval_cmd_mod.Config, "load", classmethod(lambda cls, root, confirm=None: object()))
     monkeypatch.setattr(eval_cmd_mod, "make_embedder", lambda cfg: object())
     monkeypatch.setattr(
         eval_cmd_mod,

{ragx_cli-0.3.0 → ragx_cli-0.3.3}/tests/test_providers.py

@@ -200,6 +200,42 @@ def test_make_reranker_model_load_failure_returns_none_and_warns(monkeypatch, ca
     assert "HF_ENDPOINT" in err
 
 
+def test_st_reranker_first_retry_warning_emits_manual_install_hint(monkeypatch, capsys):
+    """The first HF download-retry warning triggers a one-shot README pointer."""
+    import logging
+    import sys
+    import types
+
+    class _RetryingCrossEncoder:
+        def __init__(self, model):
+            hub_log = logging.getLogger("huggingface_hub.utils._http")
+            for _ in range(2):
+                hub_log.warning(
+                    "'_ssl.c:1015: The handshake operation timed out' thrown while "
+                    "requesting HEAD https://huggingface.co/x/resolve/main/modules.json"
+                )
+                hub_log.warning("Retrying in 1s [Retry 1/5].")
+            raise OSError("timed out")
+
+    fake = types.ModuleType("sentence_transformers")
+    fake.CrossEncoder = _RetryingCrossEncoder
+    monkeypatch.setitem(sys.modules, "sentence_transformers", fake)
+
+    from ragx.core.errors import RagxError
+    from ragx.providers.st_reranker import STReranker, _DownloadHintHandler
+
+    with pytest.raises(RagxError):
+        STReranker("BAAI/bge-reranker-v2-m3")
+
+    err = capsys.readouterr().err
+    assert err.count("install the model manually") == 1
+    assert "#reranker-on-restricted-networks" in err
+    assert not any(
+        isinstance(h, _DownloadHintHandler)
+        for h in logging.getLogger("huggingface_hub").handlers
+    )
+
+
 def test_api_key_env_resolved_and_sent(monkeypatch):
     monkeypatch.setenv("RAGX_TEST_KEY", "sk-test-123")
     cfg = _config({"embeddings": {"api_key_env": "RAGX_TEST_KEY"}})