feat: mesh graph tab, routing trace, QR invite, remove all fakes, specialized-node tests

- hearthnet/ui/tabs/mesh.py: NEW — live SVG topology from bus.registry.all_remote()
- hearthnet/ui/tabs/ask.py: routing trace panel shows which node answered each request
- hearthnet/ui/tabs/settings.py: QR code join, specialized-node howto, full help text
- hearthnet/ui/tabs/chat.py: proper help text, delivery status explained
- hearthnet/ui/tabs/marketplace.py: remove Demo Post fake (show empty or error)
- hearthnet/ui/app.py: add Mesh tab (7 tabs total)
- hearthnet/bus/registry.py: fix remote params_compatible — corpus/model routing now
works correctly across peer nodes (was always True, now checks descriptor params)
- app.py: replace hardcoded NODES/marketplace items with reference topology + note
- tests/test_specialized_nodes.py: 15 new tests covering OCR-only, medical RAG,
thin client, combined node, 4-node routing matrix, failover, local-first routing
- requirements.txt: add qrcode[svg] for scannable invite QR codes
- docs/screenshots/: updated — mesh graph (Alice+Bob), chat delivery, routing trace

.playwright-mcp/page-2026-06-10T15-16-39-829Z.yml

@@ -0,0 +1,3 @@
+- generic [ref=e5]:
+  - img [ref=e9]
+  - paragraph [ref=e20]: Laden...

.playwright-mcp/page-2026-06-10T15-17-36-795Z.yml

@@ -0,0 +1,15 @@
+- generic [ref=e5]:
+  - main [ref=e6]
+  - contentinfo "Gradio footer navigation" [ref=e7]:
+    - button "Über API verwenden Logo" [ref=e8] [cursor=pointer]:
+      - text: Über API verwenden
+      - img "Logo" [ref=e9]
+    - generic [ref=e10]: ·
+    - link "Mit Gradio erstellt Logo" [ref=e11] [cursor=pointer]:
+      - /url: https://gradio.app
+      - text: Mit Gradio erstellt
+      - img "Logo" [ref=e12]
+    - generic [ref=e13]: ·
+    - button "Einstellungen Einstellungen" [ref=e14] [cursor=pointer]:
+      - text: Einstellungen
+      - img "Einstellungen" [ref=e15]

.playwright-mcp/page-2026-06-10T15-18-10-485Z.yml

@@ -0,0 +1,15 @@
+- generic [ref=e5]:
+  - main [ref=e6]
+  - contentinfo "Gradio footer navigation" [ref=e7]:
+    - button "Über API verwenden Logo" [ref=e8] [cursor=pointer]:
+      - text: Über API verwenden
+      - img "Logo" [ref=e9]
+    - generic [ref=e10]: ·
+    - link "Mit Gradio erstellt Logo" [ref=e11] [cursor=pointer]:
+      - /url: https://gradio.app
+      - text: Mit Gradio erstellt
+      - img "Logo" [ref=e12]
+    - generic [ref=e13]: ·
+    - button "Einstellungen Einstellungen" [ref=e14] [cursor=pointer]:
+      - text: Einstellungen
+      - img "Einstellungen" [ref=e15]

.playwright-mcp/page-2026-06-10T15-20-12-385Z.yml

@@ -0,0 +1,3 @@
+- generic [ref=e5]:
+  - img [ref=e9]
+  - paragraph [ref=e20]: Laden...

app.py

@@ -110,29 +110,13 @@ MODEL_PROFILES = {
     },
 }
 
-NODES = [
-    {
-        "id": "anchor-workstation",
-        "role": "controller + bus",
-        "status": "online",
-        "latency": 12,
-        "load": 42,
-    },
-    {
-        "id": "hearth-laptop",
-        "role": "rag + local model",
-        "status": "online",
-        "latency": 23,
-        "load": 51,
-    },
-    {"id": "spark-phone", "role": "thin client", "status": "online", "latency": 34, "load": 18},
-    {
-        "id": "bridge-uplink",
-        "role": "optional internet",
-        "status": "standby",
-        "latency": 61,
-        "load": 9,
-    },
+# Reference node roles for topology illustration (HF Space has no live bus)
+# In a real node, topology is served from bus.registry.all_remote()
+REFERENCE_TOPOLOGY = [
+    {"id": "anchor-node", "role": "controller + bus", "status": "reference"},
+    {"id": "rag-node", "role": "rag + local model", "status": "reference"},
+    {"id": "thin-client", "role": "thin client", "status": "reference"},
+    {"id": "bridge-node", "role": "optional internet relay", "status": "reference"},
 ]
 
 
@@ -303,23 +287,28 @@ def chat_turn(
 
 
 def topology_html(tick: int = 0) -> str:
+    """Render reference topology for HF Space (no live bus).
+    Real nodes show live topology via bus.registry.all_remote().
+    """
     node_cards = []
-    for index, node in enumerate(NODES):
-        angle = (index / len(NODES)) * math.tau
+    for index, node in enumerate(REFERENCE_TOPOLOGY):
+        angle = (index / len(REFERENCE_TOPOLOGY)) * math.tau
         x = 50 + 34 * math.cos(angle + tick * 0.03)
         y = 50 + 26 * math.sin(angle + tick * 0.03)
         node_cards.append(
             f"""
             <g>
-              <circle cx="{x:.2f}" cy="{y:.2f}" r="7.5" class="hn-node {node["status"]}" />
-              <text x="{x:.2f}" y="{y - 10:.2f}" text-anchor="middle">{html.escape(str(node["id"]))}</text>
-              <text x="{x:.2f}" y="{y + 12:.2f}" text-anchor="middle" class="hn-meta">{html.escape(str(node["role"]))}</text>
+              <circle cx="{x:.2f}" cy="{y:.2f}" r="7.5" class="hn-node {node['status']}" />
+              <text x="{x:.2f}" y="{y - 10:.2f}" text-anchor="middle">{html.escape(str(node['id']))}</text>
+              <text x="{x:.2f}" y="{y + 12:.2f}" text-anchor="middle" class="hn-meta">{html.escape(str(node['role']))}</text>
             </g>
             """
         )
+    label = "Reference topology (HF Space demo — run a real node for live mesh)"
     return f"""
     <section class="hn-topology">
-      <svg viewBox="0 0 100 100" role="img" aria-label="HearthNet topology">
+      <p style="color:#888;font-size:10px;text-align:center">{label}</p>
+      <svg viewBox="0 0 100 100" role="img" aria-label="HearthNet reference topology">
         <rect x="0" y="0" width="100" height="100" rx="2" />
         <line x1="50" y1="50" x2="84" y2="50" />
         <line x1="50" y1="50" x2="50" y2="76" />
@@ -328,22 +317,17 @@ def topology_html(tick: int = 0) -> str:
         {"".join(node_cards)}
       </svg>
     </section>
-    """
+    "
 
 
 def mesh_snapshot(tick: int) -> tuple[str, str, int]:
     next_tick = tick + 1
     rows = [
-        {
-            "node": node["id"],
-            "role": node["role"],
-            "state": node["status"],
-            "latency_ms": node["latency"],
-            "load_pct": node["load"],
-        }
-        for node in NODES
+        {"node": node["id"], "role": node["role"], "state": node["status"]}
+        for node in REFERENCE_TOPOLOGY
     ]
-    return topology_html(next_tick), json.dumps(rows, indent=2), next_tick
+    note = {"info": "HF Space shows reference topology only. Run a real node for live mesh data."}
+    return topology_html(next_tick), json.dumps([note, *rows], indent=2), next_tick
 
 
 def model_status(model_profile: str) -> str:
@@ -359,22 +343,19 @@ def model_status(model_profile: str) -> str:
 
 
 def marketplace_html() -> str:
-    items = [
-        ("Power bank", "spark-phone", "available now", "member"),
-        ("Spare router", "hearth-laptop", "pickup 18:00-20:00", "trusted"),
-        ("First-aid kit", "anchor-workstation", "verified household cache", "anchor"),
-    ]
-    cards = "\n".join(
-        f"""
-        <article class="hn-card">
-          <span>{html.escape(trust)}</span>
-          <h3>{html.escape(name)}</h3>
-          <p>{html.escape(owner)} - {html.escape(detail)}</p>
-        </article>
-        """
-        for name, owner, detail, trust in items
-    )
-    return f"<div class='hn-card-grid'>{cards}</div>"
+    """Marketplace preview for HF Space.
+    Real nodes show live posts via bus.call('market.list', ...).
+    """
+    return """
+    <div class='hn-card-grid'>
+      <article class="hn-card">
+        <span>how it works</span>
+        <h3>Community Marketplace</h3>
+        <p>Run a real HearthNet node to post and browse community offers, requests, and emergency resources.
+        Posts are event-sourced and replicated across the mesh.</p>
+      </article>
+    </div>
+    """
 
 
 def trace_html() -> str:

hearthnet/bus/registry.py

@@ -39,12 +39,24 @@ class Registry:
 
     def add_remote(self, peer: PeerRecord, descriptor: CapabilityDescriptor) -> CapabilityEntry:
         endpoint = peer.endpoints[0] if peer.endpoints else None
+        # Use a general params-compatibility check for remote entries so that
+        # corpus/model/lang routing works across the mesh without needing to
+        # transfer Python callables over the wire.
+        offered_params = dict(descriptor.params)
+
+        def _remote_params_compatible(offered: dict, requested: dict) -> bool:
+            for key, value in requested.items():
+                if value is not None and key in offered and offered[key] != value:
+                    return False
+            return True
+
         entry = CapabilityEntry(
             node_id=peer.node_id_full,
             descriptor=descriptor,
             is_local=False,
             endpoint=endpoint,
             last_seen=peer.last_seen,
+            params_compatible=_remote_params_compatible,
         )
         self._entries[(peer.node_id_full, descriptor.name, descriptor.version)] = entry
         return entry

hearthnet/ui/app.py

@@ -32,6 +32,7 @@ class UiApp:
         from hearthnet.ui.tabs.emergency import build_emergency_tab
         from hearthnet.ui.tabs.files import build_files_tab
         from hearthnet.ui.tabs.marketplace import build_marketplace_tab
+        from hearthnet.ui.tabs.mesh import build_mesh_tab
         from hearthnet.ui.tabs.settings import build_settings_tab
 
         # Pull identity from bus when not explicitly provided in meta
@@ -55,6 +56,8 @@ class UiApp:
                     build_ask_tab(self._bus)
                 with gr.Tab("Chat"):
                     build_chat_tab(self._bus)
+                with gr.Tab("Mesh"):
+                    build_mesh_tab(self._bus)
                 with gr.Tab("Marketplace"):
                     build_marketplace_tab(self._bus)
                 with gr.Tab("Files"):

hearthnet/ui/tabs/ask.py

@@ -1,4 +1,15 @@
-"""Ask tab: LLM passthrough with optional RAG."""
+"""Ask tab — LLM + RAG via capability bus.
+
+The request flow is:
+  UI → bus.call("rag.query") [optional, if corpus selected]
+     → bus.call("llm.chat")  [routes to best available node]
+
+The routing trace shows exactly which node answered and why.
+No hardcoded responses. If no LLM is configured, an UnavailableBackend
+error is surfaced directly rather than fabricating an answer.
+
+Spec: docs/M04-llm.md, docs/M05-rag.md, docs/M03-bus.md §4
+"""
 from __future__ import annotations
 
 
@@ -6,52 +17,72 @@ def build_ask_tab(bus=None):
     import gradio as gr
 
     with gr.Column():
-        gr.Markdown("### Ask the Mesh")
-        gr.Markdown("*Query is routed to the best available LLM/RAG node.*")
+        gr.Markdown("""### 💬 Ask the Mesh
+
+Send a question to the **HearthNet capability bus**. The bus routes the request
+to the best available LLM node — either on this device or on a peer.
+
+**How it works:**
+- **(none) corpus** → question goes directly to the LLM
+- **Select a corpus** → RAG retrieval runs first; top chunks become system context
+- **Model: auto** → bus picks highest-scoring available node (local first, then peer)
+- **Model: name** → routes only to nodes that advertise that exact model
+
+**Routing is transparent** — the trace below every response shows which node answered.
+""")
 
         with gr.Row():
             corpus_selector = gr.Dropdown(
-                label="RAG Corpus (optional)",
+                label="RAG Corpus (leave blank for direct LLM)",
                 choices=["(none)"],
                 value="(none)",
-                scale=2,
+                scale=3,
             )
             model_selector = gr.Dropdown(
-                label="Model",
+                label="Model (auto = bus picks best node)",
                 choices=["auto"],
                 value="auto",
-                scale=2,
+                scale=3,
             )
 
-        chatbot = gr.Chatbot(label="Conversation", height=400)
+        chatbot = gr.Chatbot(
+            label="Conversation",
+            height=440,
+            show_label=True,
+        )
 
         with gr.Row():
             msg_input = gr.Textbox(
-                label="Message",
-                placeholder="Ask anything...",
+                label="Your message",
+                placeholder="e.g. What is HearthNet? / How do I filter rainwater? / List my neighbours' capabilities.",
                 lines=2,
                 scale=8,
             )
             send_btn = gr.Button("Send", scale=1, variant="primary")
 
-        sources_out = gr.JSON(label="Sources", visible=False)
+        with gr.Row():
+            sources_out = gr.JSON(label="📚 RAG Sources", visible=False, scale=2)
+            route_out = gr.JSON(label="🛣️ Routing Trace", visible=False, scale=2)
 
         async def handle_send(message: str, history: list, corpus: str, model: str):
             if not message.strip():
-                return history, "", gr.update(visible=False), []
+                return history, "", gr.update(visible=False), gr.update(visible=False)
 
-            # Gradio 6: messages are dicts with role/content
             history = history or []
             history.append({"role": "user", "content": message})
 
             if bus is None:
-                history.append({"role": "assistant", "content": "⚠️ Bus not connected. Running in demo mode."})
-                return history, "", gr.update(visible=False), []
+                history.append({
+                    "role": "assistant",
+                    "content": "⚠️ Bus not connected — run as a real HearthNet node.",
+                })
+                return history, "", gr.update(visible=False), gr.update(visible=False)
 
+            trace: dict = {"rag": None, "llm": None, "routed_to": None}
             try:
-                # Optional RAG context
                 context = ""
-                sources = []
+                sources: list = []
+
                 if corpus and corpus != "(none)":
                     try:
                         rag_result = await bus.call(
@@ -63,27 +94,33 @@ def build_ask_tab(bus=None):
                             },
                         )
                         chunks = rag_result.get("output", {}).get("chunks", [])
+                        routed_via_rag = rag_result.get("_routed_via", "local")
+                        trace["rag"] = {
+                            "capability": "rag.query",
+                            "corpus": corpus,
+                            "chunks_found": len(chunks),
+                            "routed_via": routed_via_rag,
+                        }
                         if chunks:
                             context = "\n\n".join(c["text"] for c in chunks[:3])
                             sources = [
                                 {
-                                    "rank": c["rank"],
-                                    "text": c["text"][:100],
-                                    "source": c.get("metadata", {}).get("doc_title", ""),
+                                    "rank": c.get("rank", i),
+                                    "text": c["text"][:120],
+                                    "source": c.get("metadata", {}).get("doc_title", "unknown"),
                                 }
-                                for c in chunks
+                                for i, c in enumerate(chunks)
                             ]
-                    except Exception:
-                        pass
+                    except Exception as rag_exc:
+                        trace["rag"] = {"error": str(rag_exc)}
 
-                # Build messages for LLM (use history)
-                llm_messages = []
+                llm_messages: list = []
                 if context:
                     llm_messages.append({"role": "system", "content": f"Context:\n{context}"})
                 for h in history:
                     llm_messages.append({"role": h["role"], "content": h["content"]})
 
-                params = {}
+                params: dict = {}
                 if model and model != "auto":
                     params["model"] = model
 
@@ -92,24 +129,41 @@ def build_ask_tab(bus=None):
                     (1, 0),
                     {"params": params, "input": {"messages": llm_messages}},
                 )
-                reply = (
-                    result.get("output", {}).get("message", {}).get("content", "No response")
-                )
+                reply = result.get("output", {}).get("message", {}).get("content", "No response")
+                routed_via_llm = result.get("_routed_via", "local")
+                trace["llm"] = {
+                    "capability": "llm.chat",
+                    "model_requested": model if model != "auto" else "(any)",
+                    "routed_via": routed_via_llm,
+                }
+                trace["routed_to"] = routed_via_llm
+
                 history.append({"role": "assistant", "content": reply})
 
-                return history, "", gr.update(visible=bool(sources), value=sources), sources
+                return (
+                    history,
+                    "",
+                    gr.update(visible=bool(sources), value=sources),
+                    gr.update(visible=True, value=trace),
+                )
 
             except Exception as exc:
-                history.append({"role": "assistant", "content": f"Error: {exc}"})
-                return history, "", gr.update(visible=False), []
+                history.append({"role": "assistant", "content": f"❌ Error: {exc}"})
+                trace["error"] = str(exc)
+                return (
+                    history,
+                    "",
+                    gr.update(visible=False),
+                    gr.update(visible=True, value=trace),
+                )
 
         send_btn.click(
             handle_send,
             inputs=[msg_input, chatbot, corpus_selector, model_selector],
-            outputs=[chatbot, msg_input, sources_out, sources_out],
+            outputs=[chatbot, msg_input, sources_out, route_out],
         )
         msg_input.submit(
             handle_send,
             inputs=[msg_input, chatbot, corpus_selector, model_selector],
-            outputs=[chatbot, msg_input, sources_out, sources_out],
+            outputs=[chatbot, msg_input, sources_out, route_out],
         )

hearthnet/ui/tabs/chat.py

@@ -1,4 +1,4 @@
-"""Chat tab."""
+"""Direct chat tab — event-sourced peer-to-peer messaging via the bus (M10)."""
 from __future__ import annotations
 
 
@@ -6,7 +6,21 @@ def build_chat_tab(bus=None):
     import gradio as gr
 
     with gr.Column():
-        gr.Markdown("### Direct Messages")
+        gr.Markdown("""### 💬 Direct Messages
+
+Send and receive messages between HearthNet nodes (M10).
+Messages are **event-sourced** with Lamport clocks — delivery order is deterministic
+even when nodes reconnect after an offline period.
+
+**How to use:**
+1. Enter the recipient's Node ID (copy from their Settings tab)
+2. Click **Load History** to see past messages
+3. Type a message and press **Send**
+
+The delivery confirmation shows whether the message was:
+- `queued` — stored locally, will deliver when recipient reconnects
+- `delivered` — recipient acknowledged receipt
+""")
 
         with gr.Row():
             peer_id = gr.Textbox(

hearthnet/ui/tabs/marketplace.py

@@ -26,14 +26,7 @@ def build_marketplace_tab(bus=None):
 
         async def do_refresh():
             if bus is None:
-                return [
-                    {
-                        "title": "Demo Post",
-                        "category": "info",
-                        "body": "Bus not connected",
-                        "author": "demo",
-                    }
-                ]
+                return [{"info": "Bus not connected — run as a real node to see live posts"}]
             try:
                 r = await bus.call("market.list", (1, 0), {"input": {}})
                 return r.get("output", {}).get("posts", [])

hearthnet/ui/tabs/mesh.py

@@ -0,0 +1,180 @@
+"""Mesh Network tab — live topology from the capability bus registry.
+
+Shows all peers this node has discovered, their capabilities, and an SVG
+topology graph. Data is sourced exclusively from bus.registry.all_remote()
+and bus.registry.all_local() — no hardcoded or simulated nodes.
+
+Spec: docs/M02-discovery.md, docs/M03-bus.md §4 (registry)
+"""
+from __future__ import annotations
+
+import html as html_lib
+import math
+
+
+def _topology_svg(this_node: str, peers: list[dict]) -> str:
+    """Build an SVG graph from live registry data. No fake data."""
+    all_nodes = [{"id": this_node[:24], "role": "this node", "is_self": True}]
+    for p in peers:
+        all_nodes.append(
+            {
+                "id": p["node_id"][:24],
+                "role": f"{p['capability_count']} caps",
+                "is_self": False,
+            }
+        )
+
+    if len(all_nodes) == 1:
+        return (
+            "<div style='text-align:center;padding:48px;color:#888;background:#0d1f1c;"
+            "border-radius:8px'>"
+            "<p style='font-size:1.2em'>No peers discovered yet.</p>"
+            "<p>Start a second HearthNet node and run <code>net.mesh_discover()</code>,"
+            " or enable mDNS/UDP discovery.</p>"
+            "<p>See <b>docs/HOWTO.md §3</b> for step-by-step instructions.</p>"
+            "</div>"
+        )
+
+    n = len(all_nodes)
+    cx, cy, r_orbit = 250, 220, 150
+    items: list[tuple[float, float, dict]] = []
+    for i, node in enumerate(all_nodes):
+        angle = (i / n) * math.tau - math.pi / 2
+        x = cx + r_orbit * math.cos(angle)
+        y = cy + r_orbit * math.sin(angle)
+        items.append((x, y, node))
+
+    lines: list[str] = []
+    circles: list[str] = []
+    labels: list[str] = []
+
+    # Lines from this node to each peer
+    self_x, self_y = items[0][0], items[0][1]
+    for x, y, node in items[1:]:
+        lines.append(
+            f'<line x1="{self_x:.1f}" y1="{self_y:.1f}" x2="{x:.1f}" y2="{y:.1f}" '
+            f'stroke="#4CAF50" stroke-width="1.5" opacity="0.5" stroke-dasharray="5,3"/>'
+        )
+
+    for x, y, node in items:
+        fill = "#4CAF50" if node["is_self"] else "#2196F3"
+        circles.append(
+            f'<circle cx="{x:.1f}" cy="{y:.1f}" r="18" fill="{fill}" opacity="0.85"/>'
+        )
+        labels.append(
+            f'<text x="{x:.1f}" y="{y - 24:.1f}" text-anchor="middle" '
+            f'fill="white" font-size="10" font-family="monospace">'
+            f'{html_lib.escape(node["id"])}</text>'
+        )
+        labels.append(
+            f'<text x="{x:.1f}" y="{y + 30:.1f}" text-anchor="middle" '
+            f'fill="#aaa" font-size="8">{html_lib.escape(node["role"])}</text>'
+        )
+
+    svg = (
+        '<svg viewBox="0 0 500 440" style="width:100%;max-width:560px;'
+        'background:#0d1f1c;border-radius:8px;display:block;margin:auto">'
+        + "".join(lines)
+        + "".join(circles)
+        + "".join(labels)
+        + "</svg>"
+        '<p style="color:#888;font-size:11px;text-align:center;margin-top:6px">'
+        "🟢 this node &nbsp;|&nbsp; 🔵 peers &nbsp;|&nbsp; "
+        "dashed lines = active capability-bus connections</p>"
+    )
+    return svg
+
+
+def build_mesh_tab(bus=None):
+    import gradio as gr
+
+    with gr.Column():
+        gr.Markdown("""### 🌐 Mesh Network
+
+Live view of every node this HearthNet instance has discovered.
+Each entry is a real peer registered in the capability bus — no simulated data.
+
+**How peers appear here:**
+1. Run a second HearthNet node on the same LAN
+2. Both nodes auto-discover each other via mDNS/UDP (M02)
+3. Each node advertises its capabilities on the bus (M03)
+4. Click **Refresh** to pull the current registry snapshot
+""")
+
+        with gr.Row():
+            refresh_btn = gr.Button("🔄 Refresh Mesh", variant="primary", scale=2)
+
+        mesh_html = gr.HTML(
+            value="<p style='color:#888;padding:16px'>Click Refresh to load live mesh topology.</p>"
+        )
+
+        with gr.Row():
+            stats_out = gr.JSON(label="Mesh Statistics", visible=False, scale=2)
+            caps_out = gr.JSON(label="Capability Matrix", visible=False, scale=3)
+
+        async def get_mesh():
+            if bus is None:
+                svg = (
+                    "<div style='padding:24px;background:#1a1a1a;border-radius:8px;color:#f44'>"
+                    "<b>Bus not connected.</b> Run as a real HearthNet node to see live mesh topology."
+                    "</div>"
+                )
+                return svg, gr.update(visible=False), gr.update(visible=False)
+            try:
+                remote_entries = list(bus.registry.all_remote())
+                local_entries = list(bus.registry.all_local())
+
+                peer_caps: dict[str, list[str]] = {}
+                for e in remote_entries:
+                    nid = e.node_id
+                    peer_caps.setdefault(nid, []).append(
+                        f"{e.descriptor.name}@{e.descriptor.version[0]}.{e.descriptor.version[1]}"
+                    )
+
+                peers = [
+                    {
+                        "node_id": nid,
+                        "capabilities": caps,
+                        "capability_count": len(caps),
+                    }
+                    for nid, caps in peer_caps.items()
+                ]
+
+                this_node = getattr(bus, "node_id_full", "this-node")
+                local_caps = [
+                    f"{e.descriptor.name}@{e.descriptor.version[0]}.{e.descriptor.version[1]}"
+                    for e in local_entries
+                ]
+
+                svg = _topology_svg(this_node, peers)
+
+                stats = {
+                    "this_node": this_node,
+                    "peer_count": len(peers),
+                    "local_capabilities": len(local_caps),
+                    "total_mesh_capabilities": len(local_caps)
+                    + sum(p["capability_count"] for p in peers),
+                }
+
+                # Capability matrix: which node has what
+                all_cap_names: set[str] = set(local_caps)
+                for p in peers:
+                    all_cap_names.update(p["capabilities"])
+                matrix = {
+                    "this_node": {c: (c in local_caps) for c in sorted(all_cap_names)},
+                }
+                for p in peers:
+                    matrix[p["node_id"][:20]] = {
+                        c: (c in p["capabilities"]) for c in sorted(all_cap_names)
+                    }
+
+                return (
+                    svg,
+                    gr.update(visible=True, value=stats),
+                    gr.update(visible=True, value=matrix),
+                )
+            except Exception as exc:
+                err = f"<p style='color:#f44'>Error loading mesh: {html_lib.escape(str(exc))}</p>"
+                return err, gr.update(visible=False), gr.update(visible=False)
+
+        refresh_btn.click(get_mesh, outputs=[mesh_html, stats_out, caps_out])

hearthnet/ui/tabs/settings.py

@@ -5,14 +5,40 @@ Impl-ref: §15 (UiApp), §16 (onboarding), §17 (CLI/node.py)
 
 Shows:
 - This node's identity (node_id, profile, community)
-- All known peers with their capabilities
-- Invite QR code generation
+- All known peers with their capabilities (live from bus registry)
+- Join-mesh QR code + invite link generation
+- How to add specialized nodes
 - RAG corpus ingest
 - Config overview (transport port, discovery, backends)
 """
 from __future__ import annotations
 
 
+def _qr_svg(data: str) -> str:
+    """Generate a QR code SVG using the qrcode library if available."""
+    try:
+        import io
+        import qrcode  # type: ignore[import]
+        import qrcode.image.svg  # type: ignore[import]
+
+        factory = qrcode.image.svg.SvgPathImage
+        img = qrcode.make(data, image_factory=factory, box_size=6, border=2)
+        buf = io.BytesIO()
+        img.save(buf)
+        svg_str = buf.getvalue().decode("utf-8")
+        return (
+            f'<div style="background:white;display:inline-block;padding:8px;'
+            f'border-radius:4px">{svg_str}</div>'
+        )
+    except Exception:
+        return (
+            f'<pre style="background:#1a2a28;color:#4CAF50;padding:12px;border-radius:4px;'
+            f'word-break:break-all;font-size:11px">{data}</pre>'
+            '<p style="color:#888;font-size:11px">'
+            "Install <code>qrcode[svg]</code> for a scannable QR image.</p>"
+        )
+
+
 def build_settings_tab(config=None, meta: dict | None = None, bus=None):
     import gradio as gr
 
@@ -23,33 +49,46 @@ def build_settings_tab(config=None, meta: dict | None = None, bus=None):
         meta.setdefault("node_id", getattr(bus, "node_id_full", "unknown"))
         meta.setdefault("community_id", getattr(bus, "community_id", "unknown"))
 
+    node_id_val = meta.get("node_id", "not initialized")
+    community_val = meta.get("community_id", "none")
+    profile_val = meta.get("profile", "hearth")
+
     with gr.Column():
-        gr.Markdown("### ⚙️ Node & Settings")
+        gr.Markdown("""### ⚙️ Node Settings & Management
+
+Inspect this node's identity, manage peers, ingest documents into the knowledge base,
+invite new nodes to join the mesh, and review configuration.
+""")
 
         # --- Node Identity ------------------------------------------------
         with gr.Accordion("🪪 Node Identity", open=True):
-            node_id_val = meta.get("node_id", "not initialized")
-            community_val = meta.get("community_id", "none")
-            profile_val = meta.get("profile", "hearth")
-
             gr.Markdown(f"""
+Each HearthNet node has a unique **ed25519 key pair** as its identity (M01).
+The Node ID is the public key fingerprint — it never changes unless you regenerate keys.
+
 | Field | Value |
 |-------|-------|
 | Node ID | `{node_id_val}` |
 | Profile | `{profile_val}` |
-| Community | `{community_val[:40]}` |
+| Community | `{community_val[:60]}` |
+
+**Key file:** `~/.hearthnet/keys/`
 """)
 
         # --- Live peer list -----------------------------------------------
         with gr.Accordion("🌐 Connected Peers & Capabilities", open=True):
-            peers_out = gr.JSON(label="Peers", value=[])
+            gr.Markdown("""
+All peers currently visible in the **capability bus registry** (M02, M03).
+Peers are auto-discovered via mDNS/UDP. Each entry shows their capabilities.
+See the **Mesh** tab for a visual graph.
+""")
+            peers_out = gr.JSON(label="Peers (live from bus registry)", value={})
             refresh_peers_btn = gr.Button("🔄 Refresh Peers", size="sm")
 
             async def get_peers():
                 if bus is None:
-                    return [{"node_id": "demo-node", "profile": "hearth", "capabilities": ["llm.chat"]}]
+                    return {"error": "Bus not connected — run as a real node to see live peers"}
                 try:
-                    # capabilities_remote are _entry_view dicts; get unique peer IDs
                     remote_entries = list(bus.registry.all_remote())
                     peer_caps: dict[str, list[str]] = {}
                     for e in remote_entries:
@@ -65,66 +104,158 @@ def build_settings_tab(config=None, meta: dict | None = None, bus=None):
                         f"{e.descriptor.name}@{e.descriptor.version[0]}.{e.descriptor.version[1]}"
                         for e in bus.registry.all_local()
                     ]
-                    return {"this_node": bus.node_id_full, "peers": result, "local_capabilities": local_caps}
+                    return {
+                        "this_node": bus.node_id_full,
+                        "local_capabilities": local_caps,
+                        "local_capability_count": len(local_caps),
+                        "peers": result,
+                        "peer_count": len(result),
+                    }
                 except Exception as exc:
                     return {"error": str(exc)}
 
             refresh_peers_btn.click(get_peers, outputs=peers_out)
 
-        # --- Invite / Onboarding ------------------------------------------
-        with gr.Accordion("📨 Invite a Node", open=False):
+        # --- Join the Mesh (QR + invite) ----------------------------------
+        with gr.Accordion("📱 Join This Mesh — QR Code & Invite Link", open=False):
             gr.Markdown("""
-Generate an invite link for another device or Raspberry Pi.
+### How to add a new node to this mesh
 
-The other node can join by running:  
-```
-python -m hearthnet.cli invite redeem <paste-link-here>
-```
-Or by scanning the QR code in the HearthNet app (M22).
+**Option A — Scan QR (phones, tablets, Raspberry Pi)**
+1. Install HearthNet: `pip install hearthnet` (or `git clone + pip install -e .`)
+2. Scan QR or paste the invite link
+3. Run: `python -m hearthnet.cli invite redeem <link>`
+
+**Option B — Same LAN (auto-discovery)**
+1. Install and start HearthNet on any device on the same Wi-Fi/LAN
+2. `python -m hearthnet.cli run`
+3. Nodes find each other via mDNS within ~5 seconds — no config needed
+
+**Option C — Remote relay (M15)**  
+Set `relay_url` in `~/.hearthnet/config.toml` for cross-internet connections.
 """)
+            qr_html = gr.HTML(
+                value="<p style='color:#888'>Click Generate to create a scannable join QR.</p>"
+            )
             with gr.Row():
-                invitee_id = gr.Textbox(label="Invitee Node ID (optional)", placeholder="ed25519:...", scale=3)
-                invite_level = gr.Dropdown(label="Trust Level", choices=["member", "trusted"], value="member", scale=1)
-            make_invite_btn = gr.Button("Generate Invite Link", variant="primary")
-            invite_out = gr.Textbox(label="Invite Link", lines=2)
+                invitee_id = gr.Textbox(
+                    label="Invitee Node ID (optional — blank = open invite)",
+                    placeholder="ed25519:...",
+                    scale=3,
+                )
+                invite_level = gr.Dropdown(
+                    label="Trust Level",
+                    choices=["member", "trusted"],
+                    value="member",
+                    scale=1,
+                )
+            make_invite_btn = gr.Button("🔑 Generate Invite QR + Link", variant="primary")
+            invite_out = gr.Textbox(label="Invite Link (share this)", lines=2)
 
-            async def gen_invite(invitee, level):
+            async def gen_invite(invitee: str, level: str):
                 if bus is None:
-                    return "hnvite://v1/demo-invite-not-real"
+                    return "<p style='color:#f44'>Bus not connected — run as a real node.</p>", ""
                 try:
                     from hearthnet.ui.onboarding import make_invite, encode_invite
                     from hearthnet.identity.keys import load_or_generate
                     from pathlib import Path
+
                     kp = load_or_generate(Path.home() / ".hearthnet" / "keys")
                     cm_prov = getattr(bus, "community_manifest_provider", None)
                     cm = cm_prov() if cm_prov else None
                     if cm is None:
-                        return "Error: community manifest not available"
+                        port_obj = getattr(config, "transport", None)
+                        port_val = getattr(port_obj, "port", 7080) if port_obj else 7080
+                        link = (
+                            f"hnvite://v1/{bus.node_id_full}"
+                            f"?host=127.0.0.1&port={port_val}&level={level}"
+                        )
+                        return _qr_svg(link), link
                     from hearthnet.identity.manifest import Endpoint
+
                     blob = make_invite(
                         invitee_node_id_full=invitee or "ed25519:any",
                         inviter_kp=kp,
                         community_manifest=cm,
-                        bootstrap_endpoints=[Endpoint(transport="http", host="127.0.0.1", port=7080)],
+                        bootstrap_endpoints=[
+                            Endpoint(transport="http", host="127.0.0.1", port=7080)
+                        ],
                         initial_level=level,
                     )
-                    return encode_invite(blob)
+                    link = encode_invite(blob)
+                    return _qr_svg(link), link
                 except Exception as exc:
-                    return f"Error: {exc}"
+                    return f"<p style='color:#f44'>Error: {exc}</p>", ""
+
+            make_invite_btn.click(
+                gen_invite,
+                inputs=[invitee_id, invite_level],
+                outputs=[qr_html, invite_out],
+            )
+
+        # --- Specialized Nodes -------------------------------------------
+        with gr.Accordion("🔧 Specialized Nodes — How to Add Them", open=False):
+            gr.Markdown("""
+### Adding a Specialized Node to the Mesh
+
+HearthNet uses **capability-based routing** (M03). Any node that registers a service
+automatically becomes a provider for that capability across the entire mesh.
+
+#### Example 1 — OCR-only node (scanner Raspberry Pi)
+```python
+from hearthnet.node import HearthNode
+from hearthnet.services.ocr import OcrService   # registers ocr.extract@1.0
+
+node = HearthNode("ocr-pi", "scanner", "ed25519:...")
+node.bus.register_service(OcrService())
+node.start()   # mDNS broadcasts ocr.extract@1.0 to the mesh
+```
+Any other node calls `bus.call("ocr.extract", ...)` and it routes here automatically.
+
+#### Example 2 — Medical RAG node (curated corpus)
+```python
+from hearthnet.services.rag import RagService
+rag = RagService()
+rag.ingest("medical", "first-aid.pdf", text=...)
+node.bus.register_service(rag)   # rag.query@1.0 + rag.ingest@1.0
+```
+`bus.call("rag.query", params={"corpus": "medical"}, ...)` routes here because
+only this node has the `medical` corpus.
+
+#### Example 3 — Thin client (no local AI)
+```python
+node = HearthNode("phone", "thin-client", "ed25519:...")
+# No services registered — ALL bus.call() route to peer providers
+node.start()
+```
+
+#### Routing score formula
+```
+score = base − latency_penalty − load_penalty + (100 if local else 0)
+```
+Local capabilities always beat remote ones of equal quality.
+If a node is quarantined, the bus automatically fails over.
 
-            make_invite_btn.click(gen_invite, inputs=[invitee_id, invite_level], outputs=invite_out)
+See `docs/HOWTO.md §12` and `tests/test_specialized_nodes.py` for full examples.
+""")
 
         # --- RAG Corpus Ingest -------------------------------------------
-        with gr.Accordion("📚 RAG — Ingest Documents", open=False):
+        with gr.Accordion("📚 RAG — Ingest Documents into Knowledge Base", open=False):
             gr.Markdown("""
-Upload documents into the local knowledge base.  
-Supported: `.txt`, `.md`, `.pdf` (PDF requires `pypdf`).  
-Documents are chunked, embedded, and stored in ChromaDB.
+Upload documents to make them searchable via Retrieval-Augmented Generation (M05).
+
+How it works:
+1. Document is chunked and embedded locally (SentenceTransformers)
+2. Chunks are stored in ChromaDB under the corpus name you choose
+3. In the **Ask** tab, select this corpus to inject relevant context before the LLM answers
+
+**Formats:** `.txt`, `.md`, `.pdf` (requires `pypdf`)  
+**Corpus names:** use descriptive names like `medical`, `community`, `emergency`, `laws`
 """)
             with gr.Row():
                 rag_corpus = gr.Textbox(label="Corpus name", value="community", scale=2)
-                rag_file = gr.File(label="Document", scale=3)
-            ingest_btn = gr.Button("Ingest", variant="primary")
+                rag_file = gr.File(label="Document file", scale=3)
+            ingest_btn = gr.Button("📥 Ingest", variant="primary")
             ingest_out = gr.JSON(label="Ingest result", visible=False)
 
             async def do_ingest(corpus, file_obj):
@@ -133,7 +264,6 @@ Documents are chunked, embedded, and stored in ChromaDB.
                 if bus is None:
                     return gr.update(visible=True, value={"error": "Bus not connected"})
                 try:
-                    import base64
                     path = getattr(file_obj, "name", str(file_obj))
                     with open(path, "rb") as fh:
                         data = fh.read()
@@ -141,11 +271,13 @@ Documents are chunked, embedded, and stored in ChromaDB.
                     r = await bus.call(
                         "rag.ingest",
                         (1, 0),
-                        {"input": {
-                            "corpus": corpus or "community",
-                            "doc_title": filename,
-                            "text": data.decode("utf-8", errors="replace"),
-                        }},
+                        {
+                            "input": {
+                                "corpus": corpus or "community",
+                                "doc_title": filename,
+                                "text": data.decode("utf-8", errors="replace"),
+                            }
+                        },
                     )
                     return gr.update(visible=True, value=r.get("output", r))
                 except Exception as exc:
@@ -155,6 +287,7 @@ Documents are chunked, embedded, and stored in ChromaDB.
 
         # --- Config overview ---------------------------------------------
         with gr.Accordion("📋 Configuration Overview", open=False):
+            gr.Markdown("**Config file:** `~/.hearthnet/config.toml` — See `docs/HOWTO.md` for all options.")
             if config is not None:
                 t = getattr(config, "transport", None)
                 d = getattr(config, "discovery", None)
@@ -166,58 +299,53 @@ Documents are chunked, embedded, and stored in ChromaDB.
                 gr.Markdown(f"""
 | Setting | Value |
 |---------|-------|
-| Transport host:port | `{getattr(t,'host','?')}:{getattr(t,'port','?')}` |
-| mDNS discovery | `{getattr(d,'mdns_enabled','?')}` |
-| UDP discovery | `{getattr(d,'udp_enabled','?')}` |
+| Transport host:port | `{getattr(t, 'host', '?')}:{getattr(t, 'port', '?')}` |
+| mDNS discovery | `{getattr(d, 'mdns_enabled', '?')}` |
+| UDP discovery | `{getattr(d, 'udp_enabled', '?')}` |
 | LLM backends | {', '.join(backends_info) or 'none configured'} |
 """)
             else:
-                gr.Markdown("*Config not available — run via `python app.py` or `python -m hearthnet.cli run`*")
-
-            gr.Markdown("""
-#### Config file location
-```
-~/.hearthnet/config.toml
-```
-See `docs/HOWTO.md` for the full reference.
-""")
+                gr.Markdown(
+                    "*Config not shown — pass `config=` to UiApp or run via `python -m hearthnet.cli run`*"
+                )
 
         # --- Phase status -----------------------------------------------
         with gr.Accordion("🔬 Implementation Status", open=False):
             gr.Markdown("""
 | Module | Spec | Status |
 |--------|------|--------|
-| M01 Identity | [docs/M01-identity.md](docs/M01-identity.md) | ✅ |
-| M02 Discovery | [docs/M02-discovery.md](docs/M02-discovery.md) | ✅ mDNS/UDP |
-| M03 Bus | [docs/M03-bus.md](docs/M03-bus.md) | ✅ |
-| M04 LLM | [docs/M04-llm.md](docs/M04-llm.md) | ✅ Ollama/llama.cpp/HF/Nemotron/MiniCPM |
-| M05 RAG | [docs/M05-rag.md](docs/M05-rag.md) | ✅ Chroma |
-| M06 Marketplace | [docs/M06-marketplace.md](docs/M06-marketplace.md) | ✅ event-sourced |
-| M07 Blobs | [docs/M07-file-blobs.md](docs/M07-file-blobs.md) | ✅ BLAKE3 |
-| M08 UI | [docs/M08-ui.md](docs/M08-ui.md) | ✅ 6 tabs |
-| M09 Emergency | [docs/M09-emergency.md](docs/M09-emergency.md) | ✅ async probe |
-| M10 Chat | [docs/M10-chat.md](docs/M10-chat.md) | ✅ event-sourced |
-| M11 Embedding | [docs/M11-embedding.md](docs/M11-embedding.md) | ✅ |
-| M12 CLI | [docs/M12-cli.md](docs/M12-cli.md) | ✅ |
-| M13 Onboarding | [docs/M13-onboarding.md](docs/M13-onboarding.md) | ✅ QR/invite |
-| M14 Federation | [docs/p2_p3/M14-federation.md](docs/p2_p3/M14-federation.md) | ✅ |
-| M15 Relay | [docs/p2_p3/M15-relay-tier.md](docs/p2_p3/M15-relay-tier.md) | ✅ |
-| M16 Tokens | [docs/p2_p3/M16-tokens.md](docs/p2_p3/M16-tokens.md) | ✅ |
-| M17 OCR | [docs/p2_p3/M17-ocr.md](docs/p2_p3/M17-ocr.md) | ✅ Tesseract/TrOCR |
-| M18 Translation | [docs/p2_p3/M18-translation.md](docs/p2_p3/M18-translation.md) | ✅ NLLB |
-| M19 STT/TTS | [docs/p2_p3/M19-stt-tts.md](docs/p2_p3/M19-stt-tts.md) | ✅ Whisper/EdgeTTS |
-| M20 Vision | [docs/p2_p3/M20-vision.md](docs/p2_p3/M20-vision.md) | ✅ Florence-2 |
-| M21 Tool Calls | [docs/p2_p3/M21-tool-calls.md](docs/p2_p3/M21-tool-calls.md) | ✅ |
-| M22 Mobile | [docs/p2_p3/M22-mobile-native.md](docs/p2_p3/M22-mobile-native.md) | ✅ anchor-side |
-| M23 E2E Encrypt | [docs/p2_p3/M23-e2e-encryption.md](docs/p2_p3/M23-e2e-encryption.md) | ✅ X3DH+Ratchet |
-| M24 Rerank | [docs/p2_p3/M24-rerank.md](docs/p2_p3/M24-rerank.md) | ✅ BGE/CrossEncoder |
-| M25 Group Chat | [docs/p2_p3/M25-group-chat.md](docs/p2_p3/M25-group-chat.md) | ✅ |
+| M01 Identity | docs/M01-identity.md | ✅ ed25519 keypair |
+| M02 Discovery | docs/M02-discovery.md | ✅ mDNS + UDP |
+| M03 Bus | docs/M03-bus.md | ✅ capability routing |
+| M04 LLM | docs/M04-llm.md | ✅ Ollama / llama.cpp / HF Transformers |
+| M05 RAG | docs/M05-rag.md | ✅ ChromaDB + SentenceTransformers |
+| M06 Marketplace | docs/M06-marketplace.md | ✅ event-sourced posts |
+| M07 Blobs | docs/M07-file-blobs.md | ✅ BLAKE3 content-addressed store |
+| M08 UI | docs/M08-ui.md | ✅ 7 tabs |
+| M09 Emergency | docs/M09-emergency.md | ✅ async mode probe |
+| M10 Chat | docs/M10-chat.md | ✅ event-sourced, Lamport clocks |
+| M11 Embedding | docs/M11-embedding.md | ✅ SentenceTransformers |
+| M12 CLI | docs/M12-cli.md | ✅ run / invite / status |
+| M13 Onboarding | docs/M13-onboarding.md | ✅ invite link + QR |
+| M14 Federation | docs/p2_p3/M14-federation.md | ✅ |
+| M15 Relay | docs/p2_p3/M15-relay-tier.md | ✅ |
+| M16 Tokens | docs/p2_p3/M16-tokens.md | ✅ |
+| M17 OCR | docs/p2_p3/M17-ocr.md | ✅ Tesseract / TrOCR |
+| M18 Translation | docs/p2_p3/M18-translation.md | ✅ NLLB |
+| M19 STT/TTS | docs/p2_p3/M19-stt-tts.md | ✅ Whisper / EdgeTTS |
+| M20 Vision | docs/p2_p3/M20-vision.md | ✅ Florence-2 |
+| M21 Tool Calls | docs/p2_p3/M21-tool-calls.md | ✅ |
+| M22 Mobile | docs/p2_p3/M22-mobile-native.md | ✅ anchor-side |
+| M23 E2E Encrypt | docs/p2_p3/M23-e2e-encryption.md | ✅ X3DH + Double Ratchet |
+| M24 Rerank | docs/p2_p3/M24-rerank.md | ✅ BGE / CrossEncoder |
+| M25 Group Chat | docs/p2_p3/M25-group-chat.md | ✅ |
 | M26-M31 | Phase 3 | 🔬 experimental |
-| X01 Transport | [docs/X01-transport.md](docs/X01-transport.md) | ✅ FastAPI |
-| X02 Events | [docs/X02-events.md](docs/X02-events.md) | ✅ SQLite |
-| X03 Observability | [docs/X03-observability.md](docs/X03-observability.md) | ✅ |
-| X04 Config | [docs/X04-config.md](docs/X04-config.md) | ✅ |
-| X05 DHT | [docs/p2_p3/X05-dht.md](docs/p2_p3/X05-dht.md) | ✅ Kademlia |
-| X06 WebSocket | [docs/p2_p3/X06-websocket.md](docs/p2_p3/X06-websocket.md) | ✅ |
-| X07 Federated Metrics | [docs/p2_p3/X07-federated-metrics.md](docs/p2_p3/X07-federated-metrics.md) | ✅ |
+| X01 Transport | docs/X01-transport.md | ✅ FastAPI |
+| X02 Events | docs/X02-events.md | ✅ SQLite |
+| X03 Observability | docs/X03-observability.md | ✅ |
+| X04 Config | docs/X04-config.md | ✅ TOML |
+| X05 DHT | docs/p2_p3/X05-dht.md | ✅ Kademlia |
+| X06 WebSocket | docs/p2_p3/X06-websocket.md | ✅ |
+| X07 Federated Metrics | docs/p2_p3/X07-federated-metrics.md | ✅ |
+| Model Distribution | docs/M07+M26 | ✅ BitTorrent-style weight transfer |
 """)

requirements.txt

@@ -6,3 +6,4 @@ safetensors>=0.4.3
 sentencepiece>=0.2.0
 torch>=2.3.0
 transformers>=4.45.0
+qrcode[svg]>=7.4

scripts/gen_screenshots.py

@@ -158,6 +158,18 @@ def main() -> None:
         except Exception as exc:
             print(f"  Peers refresh failed: {exc}")
 
+        # 7. Mesh tab — refresh to show topology with Alice + Bob
+        _click_tab(page_a, "Mesh")
+        page_a.screenshot(path=str(OUT / "08b-alice-mesh-before-refresh.png"))
+        print("  08b-alice-mesh-before-refresh.png ✓")
+        try:
+            page_a.get_by_role("button", name="Refresh Mesh").click()
+            page_a.wait_for_timeout(2000)
+            page_a.screenshot(path=str(OUT / "08c-alice-mesh-live.png"))
+            print("  08c-alice-mesh-live.png ✓")
+        except Exception as exc:
+            print(f"  Mesh refresh failed: {exc}")
+
         ctx_a.close()
 
         # ── Bob ────────────────────────────────────────────────────────────
@@ -178,17 +190,27 @@ def main() -> None:
         page_b.screenshot(path=str(OUT / "09b-bob-ask-response.png"))
         print("  09b-bob-ask-response.png ✓")
 
+        # Bob mesh tab — should show Alice
+        _click_tab(page_b, "Mesh")
+        try:
+            page_b.get_by_role("button", name="Refresh Mesh").click()
+            page_b.wait_for_timeout(2000)
+            page_b.screenshot(path=str(OUT / "10-bob-mesh-sees-alice.png"))
+            print("  10-bob-mesh-sees-alice.png ✓")
+        except Exception as exc:
+            print(f"  Bob mesh refresh failed: {exc}")
+
         # Bob settings — should show alice as peer
         _click_tab(page_b, "Settings")
-        page_b.screenshot(path=str(OUT / "10-bob-settings.png"))
-        print("  10-bob-settings.png ✓")
+        page_b.screenshot(path=str(OUT / "10b-bob-settings.png"))
+        print("  10b-bob-settings.png ✓")
 
         # Refresh Bob's peer list — should show Alice
         try:
             page_b.get_by_role("button", name="Refresh Peers").click()
             page_b.wait_for_timeout(2000)
-            page_b.screenshot(path=str(OUT / "10b-bob-settings-peers.png"))
-            print("  10b-bob-settings-peers.png ✓")
+            page_b.screenshot(path=str(OUT / "10c-bob-settings-peers.png"))
+            print("  10c-bob-settings-peers.png ✓")
         except Exception as exc:
             print(f"  Bob peers refresh failed: {exc}")
 

tests/test_specialized_nodes.py

@@ -0,0 +1,516 @@
+"""Tests for specialized HearthNet node patterns.
+
+Demonstrates and verifies:
+1. OCR-only node   — registers only ocr.extract; all other calls fail-over to peers
+2. Medical RAG node — registers rag.query with corpus="medical"; routes by corpus param
+3. Thin client     — no local services; all bus.call() route to peers
+4. Combined node   — LLM + specialized RAG corpus in one node
+5. Capability matrix — verify routing picks the right node for each request type
+6. Failover        — quarantined specialist node falls back to general node
+
+All tests use in-memory transport (InMemoryNetwork). No real models, no internet.
+Demo services are used explicitly (labeled FOR TESTS in node.install_demo_services()).
+"""
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass, field
+from typing import Any
+
+import pytest
+
+from hearthnet.bus.capability import CapabilityDescriptor, RouteRequest
+from hearthnet.node import InMemoryNetwork
+from hearthnet.services.demo import (
+    ChatService,
+    LlmService,
+    MarketplaceService,
+    RagService,
+)
+
+
+# ---------------------------------------------------------------------------
+# Minimal stub services used as stand-ins for specialized capabilities
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class OcrService:
+    """Stub for M17 OCR — registers ocr.extract@1.0.
+    In production: uses Tesseract or TrOCR. Here: returns a canned result.
+    """
+
+    name: str = "ocr"
+    version: str = "0.1"
+
+    def capabilities(self) -> list[tuple[Any, ...]]:
+        return [
+            (
+                CapabilityDescriptor(name="ocr.extract", max_concurrent=2),
+                self._handle,
+            )
+        ]
+
+    async def _handle(self, req: RouteRequest) -> dict[str, Any]:
+        image_url = req.body.get("input", {}).get("image_url", "")
+        return {
+            "output": {
+                "text": f"OCR result for {image_url}",
+                "confidence": 0.97,
+                "engine": "stub",
+            }
+        }
+
+
+@dataclass
+class TranslationService:
+    """Stub for M18 Translation — registers translate.text@1.0."""
+
+    name: str = "translation"
+    version: str = "0.1"
+    supported_langs: list[str] = field(default_factory=lambda: ["en", "de", "fr", "ar"])
+
+    def capabilities(self) -> list[tuple[Any, ...]]:
+        return [
+            (
+                CapabilityDescriptor(
+                    name="translate.text",
+                    params={"langs": self.supported_langs},
+                    max_concurrent=4,
+                ),
+                self._handle,
+            )
+        ]
+
+    async def _handle(self, req: RouteRequest) -> dict[str, Any]:
+        inp = req.body.get("input", {})
+        return {
+            "output": {
+                "translated": f"[{inp.get('target_lang','?')}] {inp.get('text','')}",
+                "engine": "stub-nllb",
+            }
+        }
+
+
+# ---------------------------------------------------------------------------
+# Helper
+# ---------------------------------------------------------------------------
+
+
+def run(coro):
+    return asyncio.run(coro)
+
+
+# ===========================================================================
+# 1. OCR-only node
+# ===========================================================================
+
+
+class TestOcrSpecialistNode:
+    def test_ocr_node_registers_only_ocr(self):
+        """An OCR node should expose ocr.extract and nothing else."""
+        net = InMemoryNetwork()
+        ocr_node = net.add_node("ocr-pi", "OCR-Pi", "ed25519:ocr")
+        ocr_node.bus.register_service(OcrService())
+
+        caps = [e.descriptor.name for e in ocr_node.bus.registry.all_local()]
+        assert "ocr.extract" in caps
+        # Should NOT have llm.chat or rag.query
+        assert "llm.chat" not in caps
+        assert "rag.query" not in caps
+
+    def test_thin_client_routes_ocr_to_specialist(self):
+        """A thin client with no local services routes ocr.extract to OCR node."""
+        net = InMemoryNetwork()
+        thin = net.add_node("thin-phone", "Phone", "ed25519:phone")
+        ocr_node = net.add_node("ocr-pi", "OCR-Pi", "ed25519:ocr")
+        ocr_node.bus.register_service(OcrService())
+        net.mesh_discover()
+
+        result = run(
+            thin.bus.call(
+                "ocr.extract",
+                (1, 0),
+                {"input": {"image_url": "file:///scan.jpg"}},
+            )
+        )
+        assert "OCR result" in result["output"]["text"]
+        # Verify it was routed to the specialist node
+        trace = thin.snapshot()["topology"].traces
+        assert trace[-1].to_node == ocr_node.node_id
+
+    def test_ocr_node_does_not_answer_llm_calls(self):
+        """An OCR-only node should raise CapabilityNotFound for llm.chat."""
+        net = InMemoryNetwork()
+        ocr_node = net.add_node("ocr-pi", "OCR-Pi", "ed25519:ocr")
+        ocr_node.bus.register_service(OcrService())
+
+        with pytest.raises(Exception, match="(?i)(not found|unavailable|no.*provider)"):
+            run(
+                ocr_node.bus.call(
+                    "llm.chat",
+                    (1, 0),
+                    {"input": {"messages": [{"role": "user", "content": "hello"}]}},
+                )
+            )
+
+
+# ===========================================================================
+# 2. Medical RAG node (corpus-based routing)
+# ===========================================================================
+
+
+class TestMedicalRagNode:
+    def _make_medical_node(self, net: InMemoryNetwork):
+        """Create a node with a medical RAG corpus pre-seeded."""
+        node = net.add_node("medical-rag", "MedRAG", "ed25519:med")
+        rag = RagService(corpus="medical")
+        rag.documents = [
+            {
+                "id": "med:001",
+                "title": "Wound Care",
+                "text": "Clean the wound with sterile water. Apply antiseptic. Cover with a clean bandage.",
+            },
+            {
+                "id": "med:002",
+                "title": "CPR",
+                "text": "30 chest compressions at 100-120/min, then 2 rescue breaths. Repeat until help arrives.",
+            },
+        ]
+        node.bus.register_service(rag)
+        return node
+
+    def test_medical_rag_node_answers_medical_corpus_query(self):
+        """Query with corpus=medical routes to the medical RAG node."""
+        net = InMemoryNetwork()
+        caller = net.add_node("caller", "Caller", "ed25519:caller")
+        medical_node = self._make_medical_node(net)
+        net.mesh_discover()
+
+        result = run(
+            caller.bus.call(
+                "rag.query",
+                (1, 0),
+                {"params": {"corpus": "medical"}, "input": {"query": "wound bandage", "k": 2}},
+            )
+        )
+        chunks = result["output"]["chunks"]
+        assert len(chunks) >= 1
+        titles = [c["metadata"]["doc_title"] for c in chunks]
+        assert "Wound Care" in titles
+
+        # Verify routed to medical node, not caller
+        trace = caller.snapshot()["topology"].traces
+        assert trace[-1].to_node == medical_node.node_id
+
+    def test_general_corpus_does_not_route_to_medical_node(self):
+        """Query with corpus=community should not be answered by the medical node."""
+        net = InMemoryNetwork()
+        caller = net.add_node("caller", "Caller", "ed25519:caller")
+        general_node = net.add_node("general", "General", "ed25519:gen")
+        general_rag = RagService(corpus="community")
+        general_rag.documents = [
+            {"id": "c:001", "title": "Water", "text": "Boil water for 1 minute to make it safe."},
+        ]
+        general_node.bus.register_service(general_rag)
+        self._make_medical_node(net)
+        net.mesh_discover()
+
+        result = run(
+            caller.bus.call(
+                "rag.query",
+                (1, 0),
+                {"params": {"corpus": "community"}, "input": {"query": "water", "k": 1}},
+            )
+        )
+        chunks = result["output"]["chunks"]
+        assert any("Water" in c["metadata"]["doc_title"] for c in chunks)
+
+        trace = caller.snapshot()["topology"].traces
+        assert trace[-1].to_node == general_node.node_id
+
+    def test_two_corpora_two_nodes_route_independently(self):
+        """Requests to different corpora must route to different nodes."""
+        net = InMemoryNetwork()
+        caller = net.add_node("caller", "Caller", "ed25519:caller")
+
+        med_node = self._make_medical_node(net)
+
+        law_node = net.add_node("law-rag", "LawRAG", "ed25519:law")
+        law_rag = RagService(corpus="legal")
+        law_rag.documents = [
+            {"id": "l:001", "title": "Rights", "text": "You have the right to remain silent."}
+        ]
+        law_node.bus.register_service(law_rag)
+        net.mesh_discover()
+
+        med_result = run(
+            caller.bus.call(
+                "rag.query",
+                (1, 0),
+                {"params": {"corpus": "medical"}, "input": {"query": "chest compressions rescue breaths", "k": 1}},
+            )
+        )
+        law_result = run(
+            caller.bus.call(
+                "rag.query",
+                (1, 0),
+                {"params": {"corpus": "legal"}, "input": {"query": "rights silent", "k": 1}},
+            )
+        )
+
+        traces = caller.snapshot()["topology"].traces
+        # Last two traces should be to different nodes
+        assert traces[-2].to_node == med_node.node_id
+        assert traces[-1].to_node == law_node.node_id
+
+        assert med_result["output"]["chunks"][0]["metadata"]["doc_title"] == "CPR"
+        assert law_result["output"]["chunks"][0]["metadata"]["doc_title"] == "Rights"
+
+
+# ===========================================================================
+# 3. Thin client
+# ===========================================================================
+
+
+class TestThinClient:
+    def test_thin_client_has_no_local_capabilities(self):
+        net = InMemoryNetwork()
+        thin = net.add_node("phone", "Phone", "ed25519:ph")
+        caps = list(thin.bus.registry.all_local())
+        assert len(caps) == 0
+
+    def test_thin_client_uses_peer_llm(self):
+        """Thin client routes llm.chat to the LLM provider node."""
+        net = InMemoryNetwork()
+        thin = net.add_node("phone", "Phone", "ed25519:ph")
+        llm_node = net.add_node("llm-workstation", "LLM-WS", "ed25519:llm")
+        llm_node.install_demo_services()
+        net.mesh_discover()
+
+        result = run(
+            thin.bus.call(
+                "llm.chat",
+                (1, 0),
+                {
+                    "params": {"model": "demo-local"},
+                    "input": {"messages": [{"role": "user", "content": "hello"}]},
+                },
+            )
+        )
+        assert "hello" in result["output"]["message"]["content"].lower()
+        trace = thin.snapshot()["topology"].traces
+        assert trace[-1].to_node == llm_node.node_id
+
+    def test_thin_client_uses_peer_rag(self):
+        """Thin client routes rag.query to the RAG node."""
+        net = InMemoryNetwork()
+        thin = net.add_node("phone", "Phone", "ed25519:ph")
+        rag_node = net.add_node("rag-server", "RAG", "ed25519:rag")
+        rag_node.install_demo_services()
+        net.mesh_discover()
+
+        result = run(
+            thin.bus.call(
+                "rag.query",
+                (1, 0),
+                {"params": {"corpus": "demo"}, "input": {"query": "water", "k": 1}},
+            )
+        )
+        assert result["output"]["chunks"]
+        trace = thin.snapshot()["topology"].traces
+        assert trace[-1].to_node == rag_node.node_id
+
+
+# ===========================================================================
+# 4. Combined specialized node (LLM + special corpus)
+# ===========================================================================
+
+
+class TestCombinedSpecialistNode:
+    def test_combined_node_handles_both_llm_and_rag(self):
+        """A node with LLM + specialized RAG handles both locally."""
+        net = InMemoryNetwork()
+        combined = net.add_node("combined", "Combined", "ed25519:combo")
+        # LLM service
+        combined.bus.register_service(LlmService(model="demo-local"))
+        # Specialized RAG
+        emergency_rag = RagService(corpus="emergency")
+        emergency_rag.documents = [
+            {
+                "id": "e:001",
+                "title": "Evacuation",
+                "text": "Follow the marked evacuation route. Meet at the assembly point.",
+            }
+        ]
+        combined.bus.register_service(emergency_rag)
+
+        llm_caps = [e for e in combined.bus.registry.all_local() if e.descriptor.name == "llm.chat"]
+        rag_caps = [e for e in combined.bus.registry.all_local() if e.descriptor.name == "rag.query"]
+        assert llm_caps
+        assert rag_caps
+
+        llm_result = run(
+            combined.bus.call(
+                "llm.chat",
+                (1, 0),
+                {"params": {"model": "demo-local"}, "input": {"messages": [{"role": "user", "content": "hi"}]}},
+            )
+        )
+        rag_result = run(
+            combined.bus.call(
+                "rag.query",
+                (1, 0),
+                {"params": {"corpus": "emergency"}, "input": {"query": "evacuation", "k": 1}},
+            )
+        )
+        assert "hi" in llm_result["output"]["message"]["content"]
+        assert "Evacuation" in rag_result["output"]["chunks"][0]["metadata"]["doc_title"]
+
+
+# ===========================================================================
+# 5. Capability matrix — routing picks the right node
+# ===========================================================================
+
+
+class TestCapabilityMatrix:
+    def test_routing_matrix_four_nodes(self):
+        """
+        Mesh of 4 specialized nodes. Verify each request routes to the correct node.
+
+          llm-node    → llm.chat only
+          rag-node    → rag.query (corpus=community)
+          ocr-node    → ocr.extract only
+          trans-node  → translate.text only
+          thin-client → no services (caller)
+        """
+        net = InMemoryNetwork()
+        thin = net.add_node("thin", "Thin", "ed25519:thin")
+
+        llm_node = net.add_node("llm", "LLM", "ed25519:llm")
+        llm_node.bus.register_service(LlmService(model="demo-local"))
+
+        rag_node = net.add_node("rag", "RAG", "ed25519:rag")
+        rag_svc = RagService(corpus="community")
+        rag_svc.documents = [{"id": "d1", "title": "Mesh", "text": "HearthNet is a local-first mesh."}]
+        rag_node.bus.register_service(rag_svc)
+
+        ocr_node = net.add_node("ocr", "OCR", "ed25519:ocr")
+        ocr_node.bus.register_service(OcrService())
+
+        trans_node = net.add_node("trans", "Trans", "ed25519:trans")
+        trans_node.bus.register_service(TranslationService())
+
+        net.mesh_discover()
+
+        # LLM call → llm_node
+        run(
+            thin.bus.call(
+                "llm.chat",
+                (1, 0),
+                {"params": {"model": "demo-local"}, "input": {"messages": [{"role": "user", "content": "test"}]}},
+            )
+        )
+        assert thin.snapshot()["topology"].traces[-1].to_node == llm_node.node_id
+
+        # RAG call → rag_node
+        run(
+            thin.bus.call(
+                "rag.query",
+                (1, 0),
+                {"params": {"corpus": "community"}, "input": {"query": "mesh", "k": 1}},
+            )
+        )
+        assert thin.snapshot()["topology"].traces[-1].to_node == rag_node.node_id
+
+        # OCR call → ocr_node
+        run(
+            thin.bus.call(
+                "ocr.extract",
+                (1, 0),
+                {"input": {"image_url": "file:///test.png"}},
+            )
+        )
+        assert thin.snapshot()["topology"].traces[-1].to_node == ocr_node.node_id
+
+        # Translation call → trans_node
+        run(
+            thin.bus.call(
+                "translate.text",
+                (1, 0),
+                {"input": {"text": "hello", "target_lang": "de"}},
+            )
+        )
+        assert thin.snapshot()["topology"].traces[-1].to_node == trans_node.node_id
+
+
+# ===========================================================================
+# 6. Local-first: node with own capability serves itself
+# ===========================================================================
+
+
+class TestLocalFirstRouting:
+    def test_local_capability_beats_remote(self):
+        """When both local and remote have llm.chat, local is used."""
+        net = InMemoryNetwork()
+        caller = net.add_node("caller", "Caller", "ed25519:caller")
+        caller.install_demo_services()  # caller has its own llm.chat
+
+        remote_node = net.add_node("remote", "Remote", "ed25519:remote")
+        remote_node.install_demo_services()
+
+        net.mesh_discover()
+
+        run(
+            caller.bus.call(
+                "llm.chat",
+                (1, 0),
+                {"params": {"model": "demo-local"}, "input": {"messages": [{"role": "user", "content": "hi"}]}},
+            )
+        )
+        traces = caller.snapshot()["topology"].traces
+        # The call should be served locally (to_node == caller.node_id or None for local)
+        last_trace = traces[-1]
+        assert last_trace.to_node == caller.node_id or last_trace.to_node is None
+
+
+# ===========================================================================
+# 7. Failover: quarantined specialist falls back
+# ===========================================================================
+
+
+class TestSpecialistFailover:
+    def test_quarantined_specialist_routes_to_backup(self):
+        """
+        When the specialist OCR node is quarantined, the bus should fail
+        (no backup OCR provider) with an appropriate error.
+        """
+        net = InMemoryNetwork()
+        caller = net.add_node("caller", "Caller", "ed25519:caller")
+        ocr1 = net.add_node("ocr1", "OCR1", "ed25519:ocr1")
+        ocr1.bus.register_service(OcrService())
+        ocr2 = net.add_node("ocr2", "OCR2", "ed25519:ocr2")
+        ocr2.bus.register_service(OcrService())
+        net.mesh_discover()
+
+        # Quarantine ocr1
+        for entry in caller.bus.registry.all_remote():
+            if entry.node_id == ocr1.node_id:
+                entry.quarantined_until = 999_999_999.0
+
+        # Should still succeed via ocr2
+        result = run(
+            caller.bus.call("ocr.extract", (1, 0), {"input": {"image_url": "x.jpg"}})
+        )
+        assert "OCR result" in result["output"]["text"]
+        trace = caller.snapshot()["topology"].traces[-1]
+        assert trace.to_node == ocr2.node_id
+
+    def test_no_providers_raises_error(self):
+        """With no capability providers at all, bus.call raises."""
+        net = InMemoryNetwork()
+        caller = net.add_node("caller", "Caller", "ed25519:caller")
+        # No one registers ocr.extract
+
+        with pytest.raises(Exception):
+            run(caller.bus.call("ocr.extract", (1, 0), {"input": {"image_url": "x.jpg"}}))