docs: move PRIVATE_SERVER.md and NATS_REPORT.md to nats-docker submodule

tests/test_deploy_freshness.py

@@ -266,6 +266,20 @@ def test_d10_customization_survives_repeated_refresh(src_and_target):
             "user gets no signal that their edit is diverging" % n)
 
 
+def _resolve_private_server_doc() -> str:
+    for candidate in [
+        os.path.join(REPO_ROOT, "nats-docker", "PRIVATE_SERVER.md"),
+        os.path.join(REPO_ROOT, "nats-docker", "docs", "PRIVATE_SERVER.md"),
+        os.path.join(REPO_ROOT, "PRIVATE_SERVER.md"),
+    ]:
+        if os.path.exists(candidate):
+            return candidate
+    return os.path.join(REPO_ROOT, "nats-docker", "PRIVATE_SERVER.md")
+
+
+PRIVATE_SERVER_DOC_PATH = _resolve_private_server_doc()
+
+
 # --------------------------------------------------------------------------
 # D-11 — (G-D1) PRIVATE_SERVER.md must only document MQTT_* environment
 #        variables that broker_config_from_env() actually parses.
@@ -274,8 +288,8 @@ def test_d11_private_server_env_names_valid():
     sys.path.insert(0, os.path.join(REPO_ROOT, ".agents", "skills", "multi-agent-mux-delegate-job", "scripts"))
     import mqtt_common
 
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
-    assert os.path.exists(doc_path), "PRIVATE_SERVER.md missing"
+    doc_path = PRIVATE_SERVER_DOC_PATH
+    assert os.path.exists(doc_path), f"PRIVATE_SERVER.md missing at {doc_path}"
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -301,7 +315,7 @@ def test_d11_private_server_env_names_valid():
 #        active configuration code blocks.
 # --------------------------------------------------------------------------
 def test_d12_private_server_no_mam_mqtt_in_code_fences():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -317,7 +331,7 @@ def test_d12_private_server_no_mam_mqtt_in_code_fences():
 #        use valid config blocks (mqtt {) and not HTTP port flag (-m 1883).
 # --------------------------------------------------------------------------
 def test_d13_private_server_nats_config_valid():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -333,7 +347,7 @@ def test_d13_private_server_nats_config_valid():
 #        CLI flags matching the actual scripts' argparse parsers.
 # --------------------------------------------------------------------------
 def test_d14_private_server_cli_args_valid():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -353,7 +367,7 @@ def test_d14_private_server_cli_args_valid():
 #        and heredocs writing it must be unquoted (<<EOF).
 # --------------------------------------------------------------------------
 def test_d15_private_server_store_dir_valid():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -374,7 +388,7 @@ def test_d15_private_server_store_dir_valid():
 # D-16 — (G-D6) nats image references in code fences must use pinned alpine
 # --------------------------------------------------------------------------
 def test_d16_private_server_nats_image_alpine_pinned():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -390,7 +404,7 @@ def test_d16_private_server_nats_image_alpine_pinned():
 # D-17 — (G-D7) Port 8222 in docker examples must be bound to 127.0.0.1
 # --------------------------------------------------------------------------
 def test_d17_private_server_monitoring_port_localhost_bound():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -407,7 +421,7 @@ def test_d17_private_server_monitoring_port_localhost_bound():
 # D-18 — (G-D8) TLS examples must not use IP literals for MQTT_BROKER
 # --------------------------------------------------------------------------
 def test_d18_private_server_tls_examples_use_domain_names():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -423,7 +437,7 @@ def test_d18_private_server_tls_examples_use_domain_names():
 # D-19 — (G-D9) Subject literals in config examples match DEFAULT_TOPIC_ROOT
 # --------------------------------------------------------------------------
 def test_d19_private_server_subject_literals_match_default_topic_root():
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         content = f.read()
 
@@ -526,7 +540,7 @@ def test_d23_compose_image_matches_doc_and_is_alpine():
     assert compose_tag != "latest", "Compose image tag must not be 'latest'"
     assert "alpine" in compose_tag, f"Compose image tag '{compose_tag}' must use alpine variant"
 
-    doc_path = os.path.join(REPO_ROOT, "PRIVATE_SERVER.md")
+    doc_path = PRIVATE_SERVER_DOC_PATH
     with open(doc_path, "r", encoding="utf-8") as f:
         doc_content = f.read()
     doc_tags = re.findall(r'\bnats:([a-zA-Z0-9_.-]+)', doc_content)