Render architecture diagram via HTML at docs marker for HF compatibility

app.py

@@ -28,6 +28,7 @@ from psq_rag.ui.group_ranked_display import rank_groups_from_tfidf, _load_enable
 APP_DIR = Path(__file__).parent
 DOCS_DIR = APP_DIR / "docs"
 ARCH_DIAGRAM_FILE = DOCS_DIR / "assets" / "architecture_overview.png"
+ARCH_DIAGRAM_MARKER = "{{ARCHITECTURE_DIAGRAM}}"
 
 
 _CORPORATE_HARDBLOCK_PATTERNS = [
@@ -137,15 +138,6 @@ def _load_about_docs_markdown() -> str:
             parts = text.split("---", 2)
             if len(parts) >= 3:
                 text = parts[2].strip()
-        if "{{ARCHITECTURE_DIAGRAM}}" in text:
-            arch_uri = _load_arch_diagram_data_uri()
-            if arch_uri:
-                text = text.replace(
-                    "{{ARCHITECTURE_DIAGRAM}}",
-                    f'<img src="{arch_uri}" alt="Architecture diagram" />',
-                )
-            else:
-                text = text.replace("{{ARCHITECTURE_DIAGRAM}}", "`(architecture diagram unavailable)`")
         if text:
             return text
     return (
@@ -183,6 +175,25 @@ def _load_arch_diagram_data_uri() -> str:
     return f"data:image/png;base64,{b64}"
 
 
+def _split_about_docs_for_diagram(md: str) -> Tuple[str, str]:
+    text = (md or "").strip()
+    if ARCH_DIAGRAM_MARKER not in text:
+        return text, ""
+    before, after = text.split(ARCH_DIAGRAM_MARKER, 1)
+    return before.strip(), after.strip()
+
+
+def _build_arch_diagram_html() -> str:
+    uri = _load_arch_diagram_data_uri()
+    if not uri:
+        return "<p><code>(architecture diagram unavailable)</code></p>"
+    return f"""
+<div class="arch-diagram-wrap">
+  <img src="{uri}" alt="Architecture diagram" />
+</div>
+"""
+
+
 def _selection_source_rank(origin: str) -> int:
     o = _normalize_selection_origin(origin)
     if o == "structural":
@@ -1435,6 +1446,10 @@ css = """
   background: #ffffff;
 }
 
+.arch-diagram-wrap {
+  margin: 6px 0 10px 0;
+}
+
 .top-instruction {
   text-align: center;
   margin: 2px 0 6px 0;
@@ -2184,11 +2199,30 @@ with gr.Blocks(css=css, js=client_js) as app:
             placeholder="Progress logs will appear here."
         )
     with gr.Accordion("How Prompt Squirrel Works", open=False):
-        gr.Markdown(
-            _load_about_docs_markdown(),
-            elem_id="about-docs",
-            elem_classes=["about-docs"],
-        )
+        _about_md = _load_about_docs_markdown()
+        if ARCH_DIAGRAM_MARKER in _about_md:
+            _about_before, _about_after = _split_about_docs_for_diagram(_about_md)
+            if _about_before:
+                gr.Markdown(
+                    _about_before,
+                    elem_id="about-docs",
+                    elem_classes=["about-docs"],
+                )
+            gr.HTML(
+                _build_arch_diagram_html(),
+                elem_classes=["about-docs"],
+            )
+            if _about_after:
+                gr.Markdown(
+                    _about_after,
+                    elem_classes=["about-docs"],
+                )
+        else:
+            gr.Markdown(
+                _about_md,
+                elem_id="about-docs",
+                elem_classes=["about-docs"],
+            )
     tooltip_map_payload = gr.Textbox(
         value="{}",
         visible=True,