chore: remove RST swap mechanism, archive rst-*.rst under docs/_rst_legacy/

The swap mechanism (RST-as-fallback for migrated MD pages) is dormant —
docs/_rst_overrides.txt has been empty since the MyST flip trio
(#1899/#1900/#1901) landed in May 2026. The mechanism's surface area
(scripts/swap_sources.py, its 245-line test, RTD pre/post hooks,
Makefile glue, conf.py dynamic loader) is dead weight, and the
rst-*.rst shadows scattered across the source tree cause Context7's
parser to misclassify the project as RST.

Changes:
- Move 253 rst-*.rst shadow files into docs/_rst_legacy/ preserving
  subdirectory structure. They remain in the repo for reference; Sphinx
  excludes the folder via exclude_patterns; Context7 excludes it via
  excludeFolders.
- Strip swap_sources.py invocation from docs/Makefile (swap/restore
  targets, : swap deps, trap chains).
- Strip jobs: pre_build/post_build block from .readthedocs.yml.
- Strip rst-*.rst exclude entry and the _md_exclude.txt loader from
  docs/conf.py; replace with a single _rst_legacy exclude.
- Delete scripts/swap_sources.py, tests/test_swap_sources.py,
  docs/_rst_overrides.txt.
- Update context7.json: add docs/_rst_legacy to excludeFolders;
  fix stale "Branch current tracks…" rule to "Branch rolling tracks…"
  (default branch was renamed 2026-05-10).
- Update AGENTS.md: drop the "RST override mechanism" section and the
  test-runner snippet for the deleted test; describe _rst_legacy as
  archive only.

Verified: sphinx-build -b html with --keep-going produces identical
warning set (68 unique), identical sitemap entry count (257), identical
llms.txt entry count (22), zero rst-* URLs in any artifact.

🤖 Generated by [robots](https://vyos.io)

1 files changed, 0 insertions, 245 deletions

diff --git a/tests/test_swap_sources.py b/tests/test_swap_sources.py
deleted file mode 100644
index 7e9f68be..00000000
--- a/tests/test_swap_sources.py
+++ /dev/null
@@ -1,245 +0,0 @@
-"""Tests for swap_sources.py — run with:
-  cd tests && PYTHONPATH=../scripts python -m pytest test_swap_sources.py -v
-
-In the inverted model MD is the canonical source for migrated pages and RST
-under the ``rst-<stem>.rst`` prefix is a fallback used only for stems listed
-in ``docs/_rst_overrides.txt``. ``do_swap`` activates the override (renames
-``rst-<stem>.rst`` → ``<stem>.rst`` and excludes ``<stem>.md``); ``do_restore``
-undoes that.
-"""
-import json
-import os
-from pathlib import Path
-
-import pytest
-
-
-# ---------------------------------------------------------------------------
-# Helper
-# ---------------------------------------------------------------------------
-
-def _setup_docs(tmp_path: Path, stems: list[str]) -> Path:
-    """Create a minimal docs/ tree with MD primary + rst-prefixed RST for each stem."""
-    docs = tmp_path / "docs"
-    for stem in stems:
-        p = Path(stem)
-        name = p.name
-        parent = p.parent  # may be "." for flat stems
-        target_dir = docs / parent if str(parent) != "." else docs
-        target_dir.mkdir(parents=True, exist_ok=True)
-        # MD file is the canonical source after the flip.
-        (target_dir / f"{name}.md").write_text(f"# {name}\nDummy MyST for {stem}\n")
-        # rst-prefixed RST file waiting to be activated as an override.
-        (target_dir / f"rst-{name}.rst").write_text(f".. _{name}:\n\nDummy RST for {stem}\n")
-    return docs
-
-
-# ---------------------------------------------------------------------------
-# parse_override_list
-# ---------------------------------------------------------------------------
-
-def test_parse_override_list_basic(tmp_path):
-    from swap_sources import parse_override_list
-
-    overrides_txt = tmp_path / "_rst_overrides.txt"
-    overrides_txt.write_text(
-        "# comment\n"
-        "\n"
-        "configuration/firewall/zone\n"
-        "  quick-start  \n"  # leading/trailing whitespace
-        "# another comment\n"
-        "installation/virtual/vmware\n"
-    )
-    stems = parse_override_list(overrides_txt)
-    assert stems == [
-        "configuration/firewall/zone",
-        "quick-start",
-        "installation/virtual/vmware",
-    ]
-
-
-def test_parse_override_list_empty(tmp_path):
-    from swap_sources import parse_override_list
-
-    missing = tmp_path / "_rst_overrides.txt"
-    assert parse_override_list(missing) == []
-
-
-# ---------------------------------------------------------------------------
-# do_swap (apply RST overrides)
-# ---------------------------------------------------------------------------
-
-def test_swap_renames_files(tmp_path):
-    from swap_sources import do_swap
-
-    stems = ["quick-start"]
-    docs = _setup_docs(tmp_path, stems)
-    (docs / "_rst_overrides.txt").write_text("quick-start\n")
-
-    do_swap(docs)
-
-    assert (docs / "quick-start.rst").exists(), "rst- file should be renamed to plain .rst"
-    assert not (docs / "rst-quick-start.rst").exists(), "rst- prefix file should be gone"
-    assert (docs / "quick-start.md").exists(), "MD file should still exist (just excluded)"
-
-
-def test_swap_creates_state_file(tmp_path):
-    from swap_sources import do_swap
-
-    stems = ["quick-start"]
-    docs = _setup_docs(tmp_path, stems)
-    (docs / "_rst_overrides.txt").write_text("quick-start\n")
-
-    do_swap(docs)
-
-    state_file = docs / "_build" / "_rst_override_state.json"
-    assert state_file.exists(), "state file should be created in _build/"
-
-    state = json.loads(state_file.read_text())
-    assert state["version"] == 2
-    assert len(state["overrides"]) == 1
-
-    entry = state["overrides"][0]
-    assert entry["stem"] == "quick-start"
-    assert "rst_from" in entry
-    assert "rst_to" in entry
-    assert "md_excluded" in entry
-
-
-def test_swap_creates_exclude_file(tmp_path):
-    from swap_sources import do_swap
-
-    stems = ["quick-start"]
-    docs = _setup_docs(tmp_path, stems)
-    (docs / "_rst_overrides.txt").write_text("quick-start\n")
-
-    do_swap(docs)
-
-    exclude_file = docs / "_build" / "_md_exclude.txt"
-    assert exclude_file.exists(), "exclude file should be created in _build/"
-
-    lines = [l.strip() for l in exclude_file.read_text().splitlines() if l.strip()]
-    assert "quick-start.md" in lines
-
-
-# ---------------------------------------------------------------------------
-# do_restore
-# ---------------------------------------------------------------------------
-
-def test_restore_undoes_renames(tmp_path):
-    from swap_sources import do_restore, do_swap
-
-    stems = ["quick-start"]
-    docs = _setup_docs(tmp_path, stems)
-    (docs / "_rst_overrides.txt").write_text("quick-start\n")
-
-    do_swap(docs)
-    assert (docs / "quick-start.rst").exists()
-
-    do_restore(docs)
-
-    assert (docs / "rst-quick-start.rst").exists(), "rst- prefix file should be restored"
-    assert not (docs / "quick-start.rst").exists(), "plain .rst should be gone after restore"
-    assert (docs / "quick-start.md").exists(), "MD file should remain untouched throughout"
-
-    state_file = docs / "_build" / "_rst_override_state.json"
-    exclude_file = docs / "_build" / "_md_exclude.txt"
-    assert not state_file.exists(), "state file should be deleted after restore"
-    assert not exclude_file.exists(), "exclude file should be deleted after restore"
-
-
-def test_restore_noop_without_state(tmp_path):
-    from swap_sources import do_restore
-
-    docs = tmp_path / "docs"
-    docs.mkdir()
-    # Should not raise even with no state file
-    do_restore(docs)  # no error = pass
-
-
-# ---------------------------------------------------------------------------
-# Collision / validation
-# ---------------------------------------------------------------------------
-
-def test_swap_fails_on_collision(tmp_path):
-    from swap_sources import do_swap
-
-    stems = ["quick-start", "cli"]
-    docs = _setup_docs(tmp_path, stems)
-    (docs / "_rst_overrides.txt").write_text("quick-start\ncli\n")
-
-    # Simulate a collision: unprefixed .rst already exists for "cli"
-    (docs / "cli.rst").write_text(".. _cli:\nCollision RST\n")
-
-    with pytest.raises(RuntimeError, match="collision"):
-        do_swap(docs)
-
-    # Rollback: first stem's rename should be undone
-    assert (docs / "rst-quick-start.rst").exists(), "rollback should undo completed renames"
-    assert not (docs / "quick-start.rst").exists(), "renamed file should not exist after rollback"
-
-    # State file should NOT be written on failure
-    state_file = docs / "_build" / "_rst_override_state.json"
-    assert not state_file.exists(), "no state file should be written on failure"
-
-
-# ---------------------------------------------------------------------------
-# Rollback on rename failure (monkeypatched os.rename)
-# ---------------------------------------------------------------------------
-
-def test_swap_rollback_on_rename_failure(tmp_path, monkeypatch):
-    """If os.rename raises on the second call, the first rename must be undone."""
-    from swap_sources import do_swap
-
-    stems = ["quick-start", "cli"]
-    docs = _setup_docs(tmp_path, stems)
-    (docs / "_rst_overrides.txt").write_text("quick-start\ncli\n")
-
-    call_count = {"n": 0}
-    real_rename = os.rename
-
-    def failing_rename(src, dst):
-        call_count["n"] += 1
-        if call_count["n"] == 2:
-            raise OSError("simulated rename failure")
-        real_rename(src, dst)
-
-    monkeypatch.setattr(os, "rename", failing_rename)
-
-    with pytest.raises(RuntimeError):
-        do_swap(docs)
-
-    # First rename (quick-start) should have been rolled back
-    assert (docs / "rst-quick-start.rst").exists(), "rollback should undo the first rename"
-    assert not (docs / "quick-start.rst").exists(), "renamed file should not exist after rollback"
-
-    # No state file should exist
-    assert not (docs / "_build" / "_rst_override_state.json").exists()
-
-
-# ---------------------------------------------------------------------------
-# Nested paths
-# ---------------------------------------------------------------------------
-
-def test_swap_nested_paths(tmp_path):
-    from swap_sources import do_swap, do_restore
-
-    stems = ["configuration/firewall/zone"]
-    docs = _setup_docs(tmp_path, stems)
-    (docs / "_rst_overrides.txt").write_text("configuration/firewall/zone\n")
-
-    do_swap(docs)
-
-    activated = docs / "configuration" / "firewall" / "zone.rst"
-    rst_source = docs / "configuration" / "firewall" / "rst-zone.rst"
-    assert activated.exists(), "nested rst file should be renamed"
-    assert not rst_source.exists()
-
-    exclude_file = docs / "_build" / "_md_exclude.txt"
-    lines = [l.strip() for l in exclude_file.read_text().splitlines() if l.strip()]
-    assert "configuration/firewall/zone.md" in lines
-
-    do_restore(docs)
-
-    assert rst_source.exists(), "nested rst- file should be restored"
-    assert not activated.exists()