Merge pull request #676 from ThalesGroup/codex/explain-hf-runtime-url

Guard Hugging Face runtime URL docs

Author: jpmorard

docs/.docs_source_mirror_stamp.json

@@ -2,8 +2,8 @@
   "file_count": 276,
   "format_version": 1,
   "managed_target": "docs/source",
-  "source_digest_sha256": "261c525c294e43cfbf6846b7f8f2165ee8fb3da7a82869087dc4e0d49266c2d5",
+  "source_digest_sha256": "b621157f587d6c0ba45930f96810875a913fe0b9e621a8b260382a4302e68a61",
   "source_hint": "../thales_agilab/docs/source",
   "sync_tool": "tools/sync_docs_source.py",
-  "target_digest_sha256": "261c525c294e43cfbf6846b7f8f2165ee8fb3da7a82869087dc4e0d49266c2d5"
+  "target_digest_sha256": "b621157f587d6c0ba45930f96810875a913fe0b9e621a8b260382a4302e68a61"
 }

docs/source/apps-pages.rst

@@ -85,6 +85,12 @@ hosted demo or future UI adapters.
    url = "https://jpmorard-agilab.hf.space/?active_app=pytorch_playground_project"
    capabilities = ["hosted-demo", "live-training"]
 
+Use the ``*.hf.space`` runtime URL for app-surface backends because it opens
+the running Space directly and preserves the ``active_app`` route. Use the
+Hugging Face project page, for example
+``https://huggingface.co/spaces/jpmorard/agilab``, for public badges,
+release-proof links, and documentation entry points.
+
 The generic launcher is::
 
    agilab app surface pytorch_playground_project --ui streamlit

test/test_audit_response_docs.py

@@ -125,6 +125,15 @@ def test_faq_separates_public_and_maintainer_docs_paths() -> None:
     assert "../thales_agilab/docs/source" not in faq
 
 
+def test_apps_pages_explains_huggingface_runtime_url_role() -> None:
+    docs = (DOCS_SOURCE / "apps-pages.rst").read_text(encoding="utf-8")
+
+    assert "Use the ``*.hf.space`` runtime URL for app-surface backends" in docs
+    assert "preserves the ``active_app`` route" in docs
+    assert "https://huggingface.co/spaces/jpmorard/agilab" in docs
+    assert "release-proof links, and documentation entry points" in docs
+
+
 def test_security_policy_addresses_public_audit_adoption_boundaries() -> None:
     security = Path("SECURITY.md").read_text(encoding="utf-8")