fix(docs): bind user guidance to visible routes

tests/test_docs_context.py

@@ -8,7 +8,7 @@ from unittest.mock import patch
 from fastapi import HTTPException
 
 from govoplan_access.backend.manifest import get_manifest as get_access_manifest
-from govoplan_core.core.modules import DocumentationCondition, DocumentationLink, DocumentationTopic, ModuleManifest
+from govoplan_core.core.modules import DocumentationCondition, DocumentationLink, DocumentationTopic, ModuleManifest, NavItem
 from govoplan_core.core.registry import PlatformRegistry
 from govoplan_tenancy.backend.manifest import get_manifest as get_tenancy_manifest
 from govoplan_docs.backend.api.v1.routes import (
@@ -92,6 +92,7 @@ class DocsContextTests(unittest.TestCase):
             id="example",
             name="Example",
             version="9.9.9",
+            nav_items=(NavItem(path="/example", label="Example", required_any=("docs:documentation:read",)),),
             documentation=(
                 DocumentationTopic(
                     id="example.workflow.safe",
@@ -103,7 +104,10 @@ class DocsContextTests(unittest.TestCase):
                         DocumentationLink(label="Open task", href="/example", kind="runtime"),
                         DocumentationLink(label="Unsafe runtime", href="javascript:alert(1)", kind="runtime"),
                         DocumentationLink(label="Backslash runtime", href="/\\evil.invalid", kind="runtime"),
+                        DocumentationLink(label="Invisible runtime", href="/hidden", kind="runtime"),
+                        DocumentationLink(label="Shell settings", href="/settings?section=example", kind="runtime"),
                         DocumentationLink(label="Public help", href="https://example.invalid/help", kind="public"),
+                        DocumentationLink(label="Malformed public", href="https://[", kind="public"),
                         DocumentationLink(label="Repository", href="example/docs/SECRET.md", kind="repository"),
                         DocumentationLink(label="API", href="/api/v1/example", kind="api"),
                     ),
@@ -137,7 +141,10 @@ class DocsContextTests(unittest.TestCase):
         )
         topic = layers["configured"][0]
 
-        self.assertEqual([link["href"] for link in topic["links"]], ["/example", "https://example.invalid/help"])
+        self.assertEqual(
+            [link["href"] for link in topic["links"]],
+            ["/example", "/settings?section=example", "https://example.invalid/help"],
+        )
         self.assertEqual(topic["conditions"], [])
         self.assertEqual(topic["configuration_keys"], [])
         self.assertEqual(topic["blockers"], {"modules": [], "capabilities": [], "scopes": []})
@@ -221,6 +228,11 @@ class DocsContextTests(unittest.TestCase):
         self.assertEqual(payload["layers"]["configured"]["permissions"], [])
         self.assertEqual(payload["layers"]["available"]["routes"], [])
         self.assertEqual(payload["layers"]["evidence"]["sources"], [])
+        self.assertEqual(
+            [(item["module_id"], item["path"]) for item in payload["layers"]["configured"]["routes"]],
+            [("docs", "/docs")],
+        )
+        self.assertEqual(payload["summary"]["visible_route_count"], 1)
 
     def test_topic_anchor_is_stable(self) -> None:
         self.assertEqual(