9 files changed, 641 insertions, 0 deletions
diff --git a/scripts/docs_gates/__init__.py b/scripts/docs_gates/__init__.py
new file mode 100644
index 00000000..e69de29b
--- /dev/null
+++ b/scripts/docs_gates/__init__.py
diff --git a/scripts/docs_gates/conftest.py b/scripts/docs_gates/conftest.py
new file mode 100644
index 00000000..38d6127e
--- /dev/null
+++ b/scripts/docs_gates/conftest.py
@@ -0,0 +1,55 @@
+"""Shared pytest fixtures for docs_gates tests.
+
+Provides a real local HTTP server (stdlib http.server, no TLS) used to exercise the
+_NoRedirect opener pattern (parity.py / smoke.py) end-to-end over an actual network
+round trip, rather than only unit-testing the handler class in isolation.
+"""
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+from http.server import BaseHTTPRequestHandler, HTTPServer
+
+import pytest
+
+REDIRECT_PATH = "/redirect-me"
+REDIRECT_LOCATION = "https://example.invalid/target"
+
+
+class _RedirectHandler(BaseHTTPRequestHandler):
+    """301+Location for REDIRECT_PATH; 200 for anything else."""
+
+    def do_GET(self) -> None:  # noqa: N802 — stdlib handler method name
+        self._respond()
+
+    def do_HEAD(self) -> None:  # noqa: N802
+        self._respond()
+
+    def _respond(self) -> None:
+        if self.path == REDIRECT_PATH:
+            self.send_response(301)
+            self.send_header("Location", REDIRECT_LOCATION)
+            self.end_headers()
+        else:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/plain")
+            self.end_headers()
+            if self.command == "GET":
+                self.wfile.write(b"ok")
+
+    def log_message(self, format: str, *args: object) -> None:  # noqa: A002 — quiet test output
+        pass
+
+
+@pytest.fixture
+def redirect_http_server() -> Iterator[str]:
+    """Starts the server on 127.0.0.1 (ephemeral port); yields 'host:port'."""
+    server = HTTPServer(("127.0.0.1", 0), _RedirectHandler)
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+    try:
+        yield f"127.0.0.1:{server.server_address[1]}"
+    finally:
+        server.shutdown()
+        server.server_close()
+        thread.join(timeout=5)
diff --git a/scripts/docs_gates/critical-pages.txt b/scripts/docs_gates/critical-pages.txt
new file mode 100644
index 00000000..1bd1a171
--- /dev/null
+++ b/scripts/docs_gates/critical-pages.txt
@@ -0,0 +1,9 @@
+# Paths relative to en/<slug>/ that must exist in every deployable build.
+# Verified 2026-07-10 against a real `sphinx-build -b html docs docs/_build/html-verify`
+# of the `rolling` tree (Python 3.12 venv; coverage.md excluded — pre-existing,
+# unrelated CfgcmdList/HTML5Translator crash, not touched by this task).
+index.html
+installation/index.html
+configuration/index.html
+cli.html
+search.html
diff --git a/scripts/docs_gates/gates.py b/scripts/docs_gates/gates.py
new file mode 100644
index 00000000..73f4b23e
--- /dev/null
+++ b/scripts/docs_gates/gates.py
@@ -0,0 +1,93 @@
+"""Deploy-blocking sanity gates (spec §7.1).
+
+Gates: file-count vs plan cap (<= 80% of 100k), per-file < 25 MiB, index.html +
+critical-page presence, page-count delta vs previous deploy, canonical URLs must
+start with the https://docs.vyos.io/en/<slug>/ prefix, declared PDF present,
+Pagefind non-empty.
+Exit 0 = deployable; exit 1 = blocked (one line per failed gate on stderr).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from pathlib import Path
+
+FILE_CAP = 100_000
+CAP_FRACTION = 0.8
+MAX_FILE = 25 * 1024 * 1024
+COUNT_DELTA_MIN_RATIO = 0.5  # new build must have >= 50% of previous page count
+CANONICAL_RE = re.compile(r'<link\s+rel="canonical"\s+href="([^"]+)"')
+
+
+def _fail(msgs: list[str], msg: str) -> None:
+    msgs.append(msg)
+    print(f"GATE-FAIL: {msg}", file=sys.stderr)
+
+
+def run(artifact: Path, slug: str, versions: Path, previous_meta: Path | None,
+        critical: list[str]) -> int:
+    fails: list[str] = []
+    root = artifact / "en" / slug
+    manifest = json.loads(versions.read_text())
+    entry = next((v for v in manifest["versions"] if v["slug"] == slug), None)
+    if entry is None:
+        _fail(fails, f"slug {slug} not in versions.json")
+        return 1
+
+    files = [p for p in artifact.rglob("*") if p.is_file()]
+    if len(files) > FILE_CAP * CAP_FRACTION:
+        _fail(fails, f"file count {len(files)} > 80% of {FILE_CAP} cap")
+    for p in files:
+        if p.stat().st_size > MAX_FILE:
+            _fail(fails, f"{p.relative_to(artifact)} exceeds 25 MiB")
+
+    for rel in ["index.html", *critical]:
+        if not (root / rel).is_file():
+            _fail(fails, f"critical page missing: en/{slug}/{rel}")
+
+    pagefind = root / "pagefind"
+    if not pagefind.is_dir() or not any(pagefind.iterdir()):
+        _fail(fails, "Pagefind index missing or empty")
+
+    if entry.get("pdf"):
+        expected = artifact / entry["pdf"].lstrip("/")
+        if not expected.is_file():
+            _fail(fails, f"declared PDF missing: {entry['pdf']}")
+
+    pages = [p for p in root.rglob("*.html")]
+    if previous_meta is not None and previous_meta.is_file():
+        prev = json.loads(previous_meta.read_text())
+        if prev.get("page_count") and len(pages) < prev["page_count"] * COUNT_DELTA_MIN_RATIO:
+            _fail(fails, f"page count collapsed: {len(pages)} vs previous {prev['page_count']}")
+
+    want = f"https://docs.vyos.io/en/{slug}/"
+    for p in pages:
+        m = CANONICAL_RE.search(p.read_text(errors="ignore"))
+        if m is None:
+            _fail(fails, f"missing canonical link in en/{slug}/{p.relative_to(root)}")
+            break  # one example is enough to block
+        if not m.group(1).startswith(want):
+            _fail(fails, f"bad canonical in en/{slug}/{p.relative_to(root)}: {m.group(1)}")
+            break  # one example is enough to block
+
+    return 1 if fails else 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--artifact", type=Path, required=True)
+    ap.add_argument("--slug", required=True)
+    ap.add_argument("--versions", type=Path, required=True)
+    ap.add_argument("--previous-meta", type=Path, default=None)
+    ap.add_argument("--critical-list", type=Path,
+                    default=Path("scripts/docs_gates/critical-pages.txt"))
+    a = ap.parse_args()
+    critical = [line.strip() for line in a.critical_list.read_text().splitlines()
+                if line.strip() and not line.startswith("#")]
+    return run(a.artifact, a.slug, a.versions, a.previous_meta, critical)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/docs_gates/parity.py b/scripts/docs_gates/parity.py
new file mode 100644
index 00000000..08225f5a
--- /dev/null
+++ b/scripts/docs_gates/parity.py
@@ -0,0 +1,121 @@
+"""URL-parity corpus + alias assertions (spec §11).
+
+Modes:
+  --sitemap-host X   pull per-version sitemaps from X (RTD pre-cutover)
+  --probe-host Y     probe every URL on Y (canary via Access, or production)
+Fails (exit 1) on any status mismatch (non-200 for corpus rows; wrong
+Location for alias rows).
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+import urllib.request
+from pathlib import Path
+
+SITEMAP_LOC = re.compile(r"<loc>([^<]+)</loc>")
+
+# Sitemap sweep covers only the versions THIS repo builds on CF (rolling/1.5/1.4).
+# 1.3/1.2 have NO RTD sitemaps (spec §15a.5) — their parity is the legacy snapshot
+# repo's crawl-inventory job. Their alias/PDF redirect rows below stay in scope.
+DEFAULT_SLUGS = "rolling,1.5,1.4"
+
+ALIASES = [("latest", "rolling"), ("stable", "1.5"), ("lts", "1.5"),
+           ("circinus", "1.5"), ("sagitta", "1.4"), ("equuleus", "1.3"), ("crux", "1.2")]
+
+
+def urls_from_sitemap(xml: str) -> list[str]:
+    out = []
+    for loc in SITEMAP_LOC.findall(xml):
+        path = re.sub(r"^https?://[^/]+", "", loc)
+        if path.startswith("/en/"):
+            out.append(path)
+    return out
+
+
+def alias_corpus() -> list[tuple[str, int, str]]:
+    rows = [(f"/en/{a}/", 301, f"/en/{s}/") for a, s in ALIASES]
+    # 1.2 excluded: never had an RTD PDF artifact (Phase-0 finding, spec §15a) — pdf: null
+    rows += [(f"/_/downloads/en/{s}/pdf/", 301, f"/en/{s}/vyos-documentation.pdf")
+             for s in ["rolling", "1.5", "1.4", "1.3"]]
+    rows.append(("/_/downloads/en/latest/pdf/", 301, "/en/rolling/vyos-documentation.pdf"))
+    return rows
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """The parity checker must SEE 301s, not follow them (alias assertions)."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D401
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+# Overridable in tests (monkeypatched to "http") so fetch() can be exercised end-to-end
+# against a real local http.server instead of requiring TLS for a unit test.
+_SCHEME = "https"
+
+
+def fetch(host: str, path: str, access: tuple[str, str] | None, method: str = "HEAD"):
+    req = urllib.request.Request(f"{_SCHEME}://{host}{path}", method=method)
+    if access:
+        req.add_header("CF-Access-Client-Id", access[0])
+        req.add_header("CF-Access-Client-Secret", access[1])
+    try:
+        with _OPENER.open(req, timeout=30) as r:
+            return r.status, r.headers.get("Location")
+    except urllib.error.HTTPError as e:  # 3xx land here with the no-redirect handler
+        return e.code, e.headers.get("Location")
+    except Exception:  # noqa: BLE001 — DNS blip/timeout fails THIS probe, not the run
+        return 0, None
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--sitemap-host", required=True)
+    ap.add_argument("--probe-host", required=True)
+    ap.add_argument("--slugs", default=DEFAULT_SLUGS)
+    ap.add_argument("--access-id")
+    ap.add_argument("--access-secret")
+    ap.add_argument("--report", type=Path, default=Path("parity-report.json"))
+    a = ap.parse_args()
+    access = (a.access_id, a.access_secret) if a.access_id else None
+    failures: list[dict] = []
+    checked = 0
+
+    for slug in a.slugs.split(","):
+        status, _ = fetch(a.sitemap_host, f"/en/{slug}/sitemap.xml", None, "GET")
+        if status != 200:
+            failures.append({"path": f"/en/{slug}/sitemap.xml", "reason": f"sitemap {status}"})
+            continue
+        try:
+            with urllib.request.urlopen(f"https://{a.sitemap_host}/en/{slug}/sitemap.xml",
+                                        timeout=30) as r:
+                urls = urls_from_sitemap(r.read().decode())
+        except Exception as e:  # noqa: BLE001 — record per-slug, keep sweeping; report ALWAYS written
+            failures.append({"path": f"/en/{slug}/sitemap.xml",
+                             "reason": f"sitemap fetch error: {e}"})
+            continue
+        for path in urls:
+            checked += 1
+            st, _ = fetch(a.probe_host, path, access)
+            if st != 200:
+                failures.append({"path": path, "reason": f"status {st}"})
+
+    for path, want_status, want_loc in alias_corpus():
+        checked += 1
+        st, loc = fetch(a.probe_host, path, access)
+        if st != want_status or (loc or "") != want_loc:
+            failures.append({"path": path, "reason": f"got {st} → {loc}, want {want_status} → {want_loc}"})
+
+    a.report.write_text(json.dumps({"checked": checked, "failures": failures}, indent=2))
+    for f in failures:
+        print(f"PARITY-FAIL {f['path']}: {f['reason']}", file=sys.stderr)
+    print(f"checked={checked} failures={len(failures)}")
+    return 1 if failures else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/docs_gates/smoke.py b/scripts/docs_gates/smoke.py
new file mode 100644
index 00000000..d25e9a1f
--- /dev/null
+++ b/scripts/docs_gates/smoke.py
@@ -0,0 +1,117 @@
+"""Scoped pre-traffic smoke + post-promote probe (spec §7.1 steps 2/5).
+
+Probes ONE version's pages plus apex special paths through a host, presenting a
+CF Access service token. Header contract (§3.3): content probes assert
+X-Docs-Build == --expect-sha; apex probes assert X-Apex-Build presence only.
+
+Phase-2 obligation (authorized addition, not in the original spec text): the
+version's index.html probe also asserts the response body carries the
+`#vyos-search` mount div (docs/_templates/searchbox.html), guarding the
+Pagefind gate's silent-degrade failure mode — a build that forgot to set
+DOCS_VERSION_SLUG would otherwise ship stock RTD search without CI noticing.
+"""
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import json
+import sys
+import urllib.request
+
+APEX_PATHS = ["/versions.json", "/healthz", "/robots.txt", "/sitemap.xml"]
+SEARCH_MOUNT_MARKER = 'id="vyos-search"'
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Probes assert an EXACT status per-path (200 or 404) — following a 3xx would
+    silently swap the probed status for whatever the redirect target returns,
+    masking an accidental redirect where a direct 200/404 was expected. Mirrors
+    parity.py's _NoRedirect/_OPENER pattern."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # noqa: D401
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+@dataclasses.dataclass
+class Probe:
+    path: str
+    expect_status: int
+    assert_docs_build: bool
+    assert_apex_build: bool
+    assert_search_mount: bool = False
+
+
+def probe_plan(slug: str, pdf: str | None, critical: list[str]) -> list[Probe]:
+    plan = [Probe(f"/en/{slug}/{rel}", 200, True, False) for rel in ["index.html", *critical]]
+    plan.append(Probe(f"/en/{slug}/pagefind/pagefind.js", 200, True, False))
+    if pdf:
+        plan.append(Probe(pdf, 200, True, False))
+    plan.append(Probe(f"/en/{slug}/definitely-missing-page-xyz.html", 404, False, False))
+    plan += [Probe(p, 200, False, True) for p in APEX_PATHS]
+    plan[0].assert_search_mount = True  # plan[0] is always /en/<slug>/index.html
+    return plan
+
+
+def docs_build_ok(header_value: str | None, expect_sha: str) -> bool:
+    """SKIP sentinel (nightly sweep): header presence only; otherwise exact match."""
+    if expect_sha == "SKIP":
+        return header_value is not None
+    return header_value == expect_sha
+
+
+def search_mount_present(html: str) -> bool:
+    return SEARCH_MOUNT_MARKER in html
+
+
+def run(host: str, slug: str, expect_sha: str, access_id: str, access_secret: str,
+        pdf: str | None, critical: list[str]) -> int:
+    failures = 0
+    for probe in probe_plan(slug, pdf, critical):
+        req = urllib.request.Request(f"https://{host}{probe.path}", method="GET")
+        req.add_header("CF-Access-Client-Id", access_id)
+        req.add_header("CF-Access-Client-Secret", access_secret)
+        try:
+            with _OPENER.open(req, timeout=30) as resp:
+                status, headers, body = resp.status, resp.headers, resp.read()
+        except urllib.error.HTTPError as e:  # non-2xx still carries headers
+            status, headers, body = e.code, e.headers, e.read()
+        except Exception as e:  # noqa: BLE001 — any transport error fails the probe
+            print(f"SMOKE-FAIL {probe.path}: {e}", file=sys.stderr)
+            failures += 1
+            continue
+        ok = status == probe.expect_status
+        if probe.assert_docs_build and not docs_build_ok(headers.get("X-Docs-Build"), expect_sha):
+            ok = False
+        if probe.assert_apex_build and not headers.get("X-Apex-Build"):
+            ok = False
+        if probe.assert_search_mount and not search_mount_present(
+                body.decode("utf-8", errors="replace")):
+            ok = False
+        if not ok:
+            print(f"SMOKE-FAIL {probe.path}: status={status} "
+                  f"docs-build={headers.get('X-Docs-Build')}", file=sys.stderr)
+            failures += 1
+    print(json.dumps({"failures": failures}))
+    return 1 if failures else 0
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--host", required=True)
+    ap.add_argument("--slug", required=True)
+    ap.add_argument("--expect-sha", required=True)
+    ap.add_argument("--access-id", required=True)
+    ap.add_argument("--access-secret", required=True)
+    ap.add_argument("--pdf", default=None)
+    ap.add_argument("--critical-list", default="scripts/docs_gates/critical-pages.txt")
+    a = ap.parse_args()
+    critical = [line.strip() for line in open(a.critical_list).read().splitlines()
+                if line.strip() and not line.startswith("#")]
+    return run(a.host, a.slug, a.expect_sha, a.access_id, a.access_secret, a.pdf, critical)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
diff --git a/scripts/docs_gates/test_gates.py b/scripts/docs_gates/test_gates.py
new file mode 100644
index 00000000..a30837ea
--- /dev/null
+++ b/scripts/docs_gates/test_gates.py
@@ -0,0 +1,104 @@
+import json
+from pathlib import Path
+import pytest
+from scripts.docs_gates import gates
+
+
+@pytest.fixture()
+def artifact(tmp_path: Path) -> Path:
+    root = tmp_path / "en" / "rolling"
+    root.mkdir(parents=True)
+    for i in range(50):
+        (root / f"p{i}.html").write_text(
+            f'<html><head><link rel="canonical" href="https://docs.vyos.io/en/rolling/p{i}.html"/></head><body>x</body></html>'
+        )
+    (root / "index.html").write_text(
+        '<html><head><link rel="canonical" href="https://docs.vyos.io/en/rolling/index.html"/></head></html>'
+    )
+    (root / "vyos-documentation.pdf").write_bytes(b"%PDF-1.4 fake")
+    (root / "pagefind").mkdir()
+    (root / "pagefind" / "pagefind.js").write_text("// index")
+    (root / "installation").mkdir()
+    (root / "installation" / "index.html").write_text(
+        '<html><head><link rel="canonical" href="https://docs.vyos.io/en/rolling/installation/index.html"/></head></html>'
+    )
+    return tmp_path
+
+
+def versions_arg(tmp_path: Path) -> Path:
+    """Hermetic stand-in for workers/versions.json — writes a fixture-local
+    manifest with the minimal schema the gates consume (mirrors the real
+    file's shape for the rolling entry) so tests never depend on, or break
+    from, edits to the repo file."""
+    p = tmp_path / "versions.json"
+    p.write_text(json.dumps({
+        "schema_version": 2,
+        "default_lang": "en",
+        "default_version": "rolling",
+        "languages": [{"code": "en", "label": "English"}],
+        "versions": [
+            {"slug": "rolling", "label": "Rolling (development)", "status": "dev",
+             "binding": "DOCS_ROLLING", "aliases": ["latest"],
+             "pdf": "/en/rolling/vyos-documentation.pdf"},
+        ],
+    }))
+    return p
+
+
+@pytest.fixture()
+def versions(tmp_path: Path) -> Path:
+    return versions_arg(tmp_path)
+
+
+def test_pass_on_good_artifact(artifact: Path, versions: Path):
+    rc = gates.run(artifact=artifact, slug="rolling", versions=versions,
+                   previous_meta=None, critical=["index.html", "installation/index.html"])
+    assert rc == 0
+
+
+def test_fail_on_missing_critical_page(artifact: Path, versions: Path):
+    (artifact / "en/rolling/installation/index.html").unlink()
+    rc = gates.run(artifact=artifact, slug="rolling", versions=versions,
+                   previous_meta=None, critical=["index.html", "installation/index.html"])
+    assert rc == 1
+
+
+def test_fail_on_count_collapse(artifact: Path, versions: Path, tmp_path: Path):
+    meta = tmp_path / "meta.json"
+    meta.write_text(json.dumps({"sha": "old", "page_count": 5000}))  # previous build 100x bigger
+    rc = gates.run(artifact=artifact, slug="rolling", versions=versions,
+                   previous_meta=meta, critical=["index.html"])
+    assert rc == 1
+
+
+def test_fail_on_alias_canonical(artifact: Path, versions: Path):
+    (artifact / "en/rolling/bad.html").write_text(
+        '<html><head><link rel="canonical" href="https://docs.vyos.io/en/latest/bad.html"/></head></html>'
+    )
+    rc = gates.run(artifact=artifact, slug="rolling", versions=versions,
+                   previous_meta=None, critical=["index.html"])
+    assert rc == 1
+
+
+def test_fail_on_missing_canonical(artifact: Path, versions: Path):
+    (artifact / "en/rolling/nocanon.html").write_text(
+        '<html><head></head><body>no canonical link at all</body></html>'
+    )
+    rc = gates.run(artifact=artifact, slug="rolling", versions=versions,
+                   previous_meta=None, critical=["index.html"])
+    assert rc == 1
+
+
+def test_fail_on_oversize_file(artifact: Path, versions: Path):
+    big = artifact / "en/rolling/huge.bin"
+    big.write_bytes(b"\0" * (26 * 1024 * 1024))  # > 25 MiB
+    rc = gates.run(artifact=artifact, slug="rolling", versions=versions,
+                   previous_meta=None, critical=["index.html"])
+    assert rc == 1
+
+
+def test_fail_when_declared_pdf_missing(artifact: Path, versions: Path):
+    (artifact / "en/rolling/vyos-documentation.pdf").unlink()
+    rc = gates.run(artifact=artifact, slug="rolling", versions=versions,
+                   previous_meta=None, critical=["index.html"])
+    assert rc == 1
diff --git a/scripts/docs_gates/test_parity.py b/scripts/docs_gates/test_parity.py
new file mode 100644
index 00000000..76057d70
--- /dev/null
+++ b/scripts/docs_gates/test_parity.py
@@ -0,0 +1,72 @@
+import json
+import sys
+import urllib.error
+
+from scripts.docs_gates import parity
+from scripts.docs_gates.conftest import REDIRECT_LOCATION, REDIRECT_PATH
+
+
+def test_sitemap_url_extraction():
+    xml = ('<?xml version="1.0"?><urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">'
+           "<url><loc>https://docs.vyos.io/en/1.5/a.html</loc></url>"
+           "<url><loc>https://docs.vyos.io/en/1.5/b/</loc></url></urlset>")
+    assert parity.urls_from_sitemap(xml) == ["/en/1.5/a.html", "/en/1.5/b/"]
+
+
+def test_alias_corpus_includes_pdf_and_alias_rows():
+    rows = parity.alias_corpus()
+    assert ("/en/latest/", 301, "/en/rolling/") in rows
+    assert ("/_/downloads/en/1.5/pdf/", 301, "/en/1.5/vyos-documentation.pdf") in rows
+
+
+def test_fetch_never_follows_redirects_unit():
+    # unit-level sanity check on the handler class in isolation (kept alongside the
+    # end-to-end test below, which is what actually proves the opener is wired up)
+    handler = parity._NoRedirect()
+    assert handler.redirect_request(None, None, 301, "Moved", {}, "https://x/") is None
+
+
+def test_fetch_never_follows_redirects(redirect_http_server, monkeypatch):
+    # End-to-end: real local HTTP server returns a 301, exercised through the PUBLIC
+    # fetch() entrypoint (not just the handler class) — proves _OPENER is actually
+    # wired into fetch() and surfaces (301, Location) instead of following it.
+    monkeypatch.setattr(parity, "_SCHEME", "http")
+    status, location = parity.fetch(redirect_http_server, REDIRECT_PATH, None, "GET")
+    assert status == 301
+    assert location == REDIRECT_LOCATION
+
+
+def test_default_slugs_scoped_to_cf_built_versions():
+    # 1.3/1.2 have NO RTD sitemaps (spec §15a.5); legacy parity belongs to the
+    # snapshot repo's crawl-inventory job, not this sweep
+    assert parity.DEFAULT_SLUGS == "rolling,1.5,1.4"
+
+
+def test_fetch_records_transport_error_as_status_zero(monkeypatch):
+    # a DNS blip / timeout must fail the single probe, not abort the whole run
+    class _Boom:
+        def open(self, req, timeout=None):
+            raise urllib.error.URLError("dns blip")
+
+    monkeypatch.setattr(parity, "_OPENER", _Boom())
+    assert parity.fetch("host.invalid", "/en/rolling/", None) == (0, None)
+
+
+def test_main_always_writes_report_on_transport_errors(tmp_path, monkeypatch):
+    # sitemap status probe says 200, but the body fetch raises mid-sweep:
+    # the run must record per-slug failures, keep going, and STILL write the report
+    report = tmp_path / "parity-report.json"
+    monkeypatch.setattr(parity, "fetch", lambda *a, **k: (200, None))
+
+    def _boom(*a, **k):
+        raise urllib.error.URLError("timed out")
+
+    monkeypatch.setattr(parity.urllib.request, "urlopen", _boom)
+    monkeypatch.setattr(sys, "argv", ["parity", "--sitemap-host", "sitemap.invalid",
+                                      "--probe-host", "probe.invalid",
+                                      "--report", str(report)])
+    rc = parity.main()
+    assert rc == 1
+    data = json.loads(report.read_text())
+    assert data["failures"]  # report written despite transport errors
+    assert any("sitemap" in f["reason"] for f in data["failures"])
diff --git a/scripts/docs_gates/test_smoke.py b/scripts/docs_gates/test_smoke.py
new file mode 100644
index 00000000..595e6a28
--- /dev/null
+++ b/scripts/docs_gates/test_smoke.py
@@ -0,0 +1,70 @@
+import urllib.error
+import urllib.request
+
+from scripts.docs_gates import smoke
+from scripts.docs_gates.conftest import REDIRECT_LOCATION, REDIRECT_PATH
+
+
+def test_probe_plan_scoped_to_slug():
+    plan = smoke.probe_plan("1.5", pdf="/en/1.5/vyos-documentation.pdf",
+                            critical=["index.html", "cli/index.html"])
+    urls = [p.path for p in plan]
+    assert "/en/1.5/index.html" in urls
+    assert "/en/1.5/cli/index.html" in urls
+    assert "/en/1.5/vyos-documentation.pdf" in urls
+    assert "/en/1.5/definitely-missing-page-xyz.html" in urls  # 404-status probe
+    assert "/versions.json" in urls and "/healthz" in urls      # apex specials
+    assert not any(u.startswith("/en/rolling/") for u in urls)  # scoped (§7.1.2)
+
+
+def test_assertions_follow_header_contract():
+    plan = smoke.probe_plan("1.5", pdf=None, critical=["index.html"])
+    content = next(p for p in plan if p.path == "/en/1.5/index.html")
+    assert content.expect_status == 200 and content.assert_docs_build is True
+    apex = next(p for p in plan if p.path == "/versions.json")
+    assert apex.assert_docs_build is False and apex.assert_apex_build is True
+    missing = next(p for p in plan if "definitely-missing" in p.path)
+    assert missing.expect_status == 404
+
+
+def test_skip_sentinel_relaxes_sha_to_presence_only():
+    # expect_sha == "SKIP" (nightly sweep, Task 3.5): header must be PRESENT but any value passes
+    assert smoke.docs_build_ok("anything", expect_sha="SKIP") is True
+    assert smoke.docs_build_ok(None, expect_sha="SKIP") is False
+    assert smoke.docs_build_ok("abc", expect_sha="abc") is True
+    assert smoke.docs_build_ok("abc", expect_sha="def") is False
+
+
+# --- Phase-2 obligation (authorized addition, not in the original brief): the
+# index.html probe must assert the CF-built HTML carries the `#vyos-search`
+# mount div, so CI catches a build that silently forgot to set
+# DOCS_VERSION_SLUG (which would ship stock RTD search instead of Pagefind). ---
+
+def test_probe_plan_asserts_search_mount_on_index_only():
+    plan = smoke.probe_plan("1.5", pdf=None, critical=["index.html", "cli/index.html"])
+    index = next(p for p in plan if p.path == "/en/1.5/index.html")
+    assert index.assert_search_mount is True
+    other_content = [p for p in plan if p.path != "/en/1.5/index.html" and p.assert_docs_build]
+    assert other_content and all(p.assert_search_mount is False for p in other_content)
+
+
+# --- CodeRabbit finding: smoke's probe requests must mirror parity.py's _NoRedirect
+# opener — an exact-status probe (200/404) that silently followed a 3xx would report
+# whatever the redirect target returns instead of the redirect itself. ---
+
+def test_opener_observes_redirect_directly_not_followed(redirect_http_server):
+    # End-to-end: a real local HTTP server returns a 301, opened through smoke.py's
+    # module-level _OPENER (the exact object `run()` uses) — proves it's actually
+    # wired to refuse the redirect, matching run()'s HTTPError-catch handling of 3xx.
+    req = urllib.request.Request(f"http://{redirect_http_server}{REDIRECT_PATH}", method="GET")
+    try:
+        smoke._OPENER.open(req, timeout=5)
+        raise AssertionError("expected HTTPError for a 301 with the no-redirect opener")
+    except urllib.error.HTTPError as e:
+        assert e.code == 301
+        assert e.headers.get("Location") == REDIRECT_LOCATION
+
+
+def test_search_mount_present():
+    assert smoke.search_mount_present('<div id="vyos-search" role="search"></div>') is True
+    assert smoke.search_mount_present('<html><body>no search here</body></html>') is False