context-mcp-server 1.1.0 → 1.1.1

package/README.md

@@ -11,7 +11,7 @@
 
 Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.
 
-One shared context store across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another.
+One shared context store across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Antigravity IDE, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another.
 
 ---
 
@@ -77,9 +77,16 @@ ctx install --cursor      # Cursor
 ctx install --vscode      # VS Code Copilot
 ctx install --gemini      # Gemini CLI
 ctx install --codex       # Codex CLI
-ctx install --windsurf    # Windsurf
+ctx install --windsurf      # Windsurf
+ctx install --antigravity   # Antigravity IDE
 ```
 
+For Codex project installs, `ctx install --codex` writes:
+
+- `.codex/config.toml` with `[mcp_servers.context-mcp]` MCP configuration.
+- `AGENTS.md` with Context-MCP usage rules for Codex.
+- `.codex/hooks/` pre/post shell hook scripts for project-local Codex sessions.
+
 For web clients (Claude.ai, ChatGPT), start the HTTP server:
 
 ```bash
@@ -113,8 +120,9 @@ ctx online                     # start HTTP server (idempotent)
 ctx online --restart           # force stop + restart
 ctx settings                   # view and edit config interactively
 
-# Tools
-ctx benchmark                  # token savings report (memory + graph)
+# Install
+ctx install --initial          # install / update Node.js + Python deps
+ctx install --all              # write config + rules for all platforms
 ```
 
 ---
@@ -152,18 +160,32 @@ Any file or git operation outside that directory is rejected. Applies to all HTT
 codegraph_build(path)
 ```
 
-Parses codebase via tree-sitter AST (16 languages, regex fallback). Extracts functions, classes, imports, call edges. Build metadata saved to `~/.context-mcp/projects/<name>/graph.json`.
+Parses codebase via tree-sitter AST (16 languages, regex fallback). Extracts functions, classes, imports, and call edges. Automatically generates visualizations on every build. Metadata saved to `<project>/codegraph-cache/`.
 
 **Step 2 — Query** (instant, forever):
 
 ```
+codegraph_arch(path, limit?)              → module map: every file, its exports, its imports
 codegraph_query(path, question?, node?)   → structural question OR single-node lookup (or both)
-codegraph_path(path, from, to)            → shortest path between two concepts
 codegraph_nodes(path, type)               → list all nodes of a type
 codegraph_report(path)                    → god nodes, clusters, surprising connections
+codegraph_affected(path, node, depth?)    → BFS blast radius — what breaks if you change X?
+```
+
+`codegraph_query` accepts `question` (natural language), `node` (exact/partial name), or both. Use before reading any files.
+
+**Step 3 — Visualize** (auto-generated on every build):
+
+```
+codegraph_html(path, formats?)            → regenerate visualizations on demand
 ```
 
-`codegraph_query` accepts `question` (natural language), `node` (exact/partial name for type + file + deps + callers), or both in one call. Use before reading any files.
+Every `codegraph_build` automatically writes to `<project>/codegraph-cache/`:
+- `graph.html` — interactive vis.js force graph (dark theme, search, community toggle)
+- `tree.html` — D3 collapsible file hierarchy
+- `callflow.html` — Mermaid architecture diagrams per community
+- `graph.graphml` — Gephi / yEd export
+- `obsidian/` — per-node `.md` vault with `[[wikilinks]]`
 
 ### File & Git Tools
 

package/codegraph/affected.py

@@ -0,0 +1,233 @@
+"""
+affected.py — "what breaks if I change X?" BFS over the knowledge graph.
+
+Ported from graphify's affected.py with field name adaptations:
+  graphify uses 'label' / 'source_file' / 'source_location'
+  context-mcp uses 'name' / 'file' / 'line'
+"""
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass
+from typing import Iterable
+
+import networkx as nx
+
+
+DEFAULT_AFFECTED_RELATIONS = (
+    "calls",
+    "references",
+    "imports",
+    "imports_from",
+    "re_exports",
+    "inherits",
+    "extends",
+    "implements",
+    "uses",
+    "mixes_in",
+    "embeds",
+)
+
+
+@dataclass(frozen=True)
+class AffectedHit:
+    node_id: str
+    depth: int
+    via_relation: str
+
+
+# ── Graph loading ─────────────────────────────────────────────────────────────
+
+def graph_from_dict(graph_dict: dict) -> nx.DiGraph:
+    """Reconstruct nx.DiGraph from our graph.json dict format (edges use 'from'/'to')."""
+    G = nx.DiGraph()
+    for node in graph_dict.get("nodes", []):
+        nid = node.get("id", "")
+        if nid:
+            G.add_node(nid, **{k: v for k, v in node.items() if k != "id"})
+    for edge in graph_dict.get("edges", []):
+        src = edge.get("from", "")
+        tgt = edge.get("to", "")
+        if src and tgt:
+            G.add_edge(src, tgt, **{k: v for k, v in edge.items() if k not in ("from", "to")})
+    return G
+
+
+# ── Node helpers ──────────────────────────────────────────────────────────────
+
+def _node_label(graph: nx.Graph, node_id: str) -> str:
+    data = graph.nodes[node_id]
+    return str(data.get("name") or node_id)
+
+
+def _format_location(data: dict) -> str:
+    source_file = data.get("file") or "-"
+    line = data.get("line")
+    if line:
+        return f"{source_file}:{line}"
+    return str(source_file)
+
+
+def _bare_name(label: str) -> str:
+    label = label.lower()
+    return label[:-2] if label.endswith("()") else label
+
+
+# ── Seed resolution ───────────────────────────────────────────────────────────
+
+def resolve_seed(graph: nx.Graph, query: str) -> str | None:
+    """Find the node ID that best matches the query string.
+
+    Resolution order: exact ID → exact name → bare name (strips "()")
+    → exact file path → contains match.
+    """
+    if query in graph:
+        return query
+    query_lower = query.lower()
+    exact_name_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if str(data.get("name", "")).lower() == query_lower
+    ]
+    if len(exact_name_matches) == 1:
+        return exact_name_matches[0]
+
+    query_bare = _bare_name(query_lower)
+    bare_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if _bare_name(str(data.get("name", ""))) == query_bare
+    ]
+    if len(bare_matches) == 1:
+        return bare_matches[0]
+
+    exact_file_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if str(data.get("file", "")).lower() == query_lower
+    ]
+    if len(exact_file_matches) == 1:
+        return exact_file_matches[0]
+
+    contains_matches = [
+        str(node_id)
+        for node_id, data in graph.nodes(data=True)
+        if query_lower in str(data.get("name", "")).lower()
+    ]
+    if len(contains_matches) == 1:
+        return contains_matches[0]
+    return None
+
+
+# ── BFS traversal ─────────────────────────────────────────────────────────────
+
+def affected_nodes(
+    graph: nx.Graph,
+    seed: str,
+    *,
+    relations: Iterable[str] = DEFAULT_AFFECTED_RELATIONS,
+    depth: int = 2,
+) -> list[AffectedHit]:
+    """BFS from seed following incoming edges whose relation is in `relations`.
+
+    Returns nodes that would be affected by a change to the seed node.
+    """
+    relation_set = set(relations)
+    seen = {seed}
+    queue: deque[tuple[str, int]] = deque([(seed, 0)])
+    hits: list[AffectedHit] = []
+
+    while queue:
+        current, current_depth = queue.popleft()
+        if current_depth >= depth:
+            continue
+        if hasattr(graph, "in_edges"):
+            incoming = graph.in_edges(current, data=True)
+        else:
+            incoming = (
+                (source, target, data)
+                for source, target, data in graph.edges(data=True)
+                if target == current
+            )
+        for source, _target, data in incoming:
+            relation = str(data.get("relation", ""))
+            if relation not in relation_set:
+                continue
+            source = str(source)
+            if source in seen:
+                continue
+            seen.add(source)
+            hits.append(AffectedHit(source, current_depth + 1, relation))
+            queue.append((source, current_depth + 1))
+
+    return hits
+
+
+# ── Formatted output ──────────────────────────────────────────────────────────
+
+def format_affected(
+    graph: nx.Graph,
+    query: str,
+    *,
+    relations: Iterable[str] = DEFAULT_AFFECTED_RELATIONS,
+    depth: int = 2,
+) -> str:
+    """Return a human-readable summary of nodes affected by changing `query`."""
+    relation_list = tuple(relations)
+    seed = resolve_seed(graph, query)
+    if seed is None:
+        return f"No unique node match for '{query}'"
+
+    hits = affected_nodes(graph, seed, relations=relation_list, depth=depth)
+    lines = [
+        f"Affected nodes for: {_node_label(graph, seed)}",
+        f"Relations tracked: {', '.join(relation_list)}",
+        f"Depth: {depth}",
+        "",
+    ]
+    if not hits:
+        lines.append("No affected nodes found.")
+        return "\n".join(lines)
+
+    for hit in hits:
+        data = graph.nodes[hit.node_id]
+        lines.append(
+            f"  depth={hit.depth}  [{hit.via_relation}]  "
+            f"{_node_label(graph, hit.node_id)}  @ {_format_location(data)}"
+        )
+    return "\n".join(lines)
+
+
+# ── Convenience entry point ───────────────────────────────────────────────────
+
+def run_affected(graph_dict: dict, query: str, depth: int = 2) -> dict:
+    """Run affected analysis from a graph.json dict. Returns structured result."""
+    G = graph_from_dict(graph_dict)
+    seed = resolve_seed(G, query)
+    if seed is None:
+        return {"query": query, "seed": None, "hits": [], "text": f"No unique node match for '{query}'"}
+
+    hits = affected_nodes(G, seed, depth=depth)
+    seed_data = G.nodes[seed]
+
+    hit_list = []
+    for hit in hits:
+        data = G.nodes.get(hit.node_id, {})
+        hit_list.append({
+            "node_id":      hit.node_id,
+            "name":         data.get("name", hit.node_id),
+            "file":         data.get("file", ""),
+            "line":         data.get("line"),
+            "depth":        hit.depth,
+            "via_relation": hit.via_relation,
+        })
+
+    return {
+        "query":   query,
+        "seed":    seed,
+        "seed_name": seed_data.get("name", seed),
+        "seed_file": seed_data.get("file", ""),
+        "depth":   depth,
+        "hits":    hit_list,
+        "text":    format_affected(G, query, depth=depth),
+    }

package/codegraph/cache.py

@@ -10,6 +10,7 @@ Format: { "rel/path": { "hash": "...", "nodes": [...], "extracted_at": "..." } }
 
 import hashlib
 import json
+import os
 from datetime import datetime, timezone
 from pathlib import Path
 
@@ -113,6 +114,18 @@ def file_hash(path: str) -> str:
     return h.hexdigest()
 
 
+def stat_hit(path: str, cache_entry: dict) -> bool:
+    """Return True if (size, mtime_ns) matches the cached stat — skips SHA-256."""
+    cached_stat = cache_entry.get("stat")
+    if not cached_stat:
+        return False
+    try:
+        s = os.stat(path)
+        return cached_stat == [s.st_size, s.st_mtime_ns]
+    except OSError:
+        return False
+
+
 def get_cached_nodes(cache: dict, rel_path: str, current_hash: str) -> list | None:
     """Return cached nodes if hash matches, else None."""
     entry = cache.get(rel_path)
@@ -121,12 +134,48 @@ def get_cached_nodes(cache: dict, rel_path: str, current_hash: str) -> list | No
     return None
 
 
-def set_cached_nodes(cache: dict, rel_path: str, file_hash_val: str, nodes: list) -> None:
-    cache[rel_path] = {
+def get_cached_nodes_fast(cache: dict, rel_path: str, abs_path: str) -> list | None:
+    """Return cached nodes using stat fastpath, falling back to SHA-256 check.
+
+    Avoids reading and hashing large files on incremental rebuilds where
+    the file hasn't changed — (size, mtime_ns) is checked first.
+    Returns None if the file is new or has changed.
+    """
+    entry = cache.get(rel_path)
+    if not entry:
+        return None
+    # Fast path: stat match skips SHA-256
+    if stat_hit(abs_path, entry):
+        return entry.get("nodes", [])
+    # Slow path: full hash check
+    try:
+        h = file_hash(abs_path)
+    except OSError:
+        return None
+    if entry.get("hash") == h:
+        # Update stat so next call is fast
+        try:
+            s = os.stat(abs_path)
+            entry["stat"] = [s.st_size, s.st_mtime_ns]
+        except OSError:
+            pass
+        return entry.get("nodes", [])
+    return None
+
+
+def set_cached_nodes(cache: dict, rel_path: str, file_hash_val: str, nodes: list, abs_path: str | None = None) -> None:
+    entry: dict = {
         "hash":         file_hash_val,
         "nodes":        nodes,
         "extracted_at": datetime.now(timezone.utc).isoformat(),
     }
+    if abs_path:
+        try:
+            s = os.stat(abs_path)
+            entry["stat"] = [s.st_size, s.st_mtime_ns]
+        except OSError:
+            pass
+    cache[rel_path] = entry
 
 
 def remove_deleted(cache: dict, existing_rel_paths: set) -> list:

package/codegraph/callflow_html.py

@@ -0,0 +1,273 @@
+"""
+callflow_html.py — Mermaid architecture flowcharts from graph.json communities.
+
+Generates a dark-themed, self-contained HTML with:
+  - Overview architecture diagram (community-level)
+  - Per-community flowcharts showing key call/import edges
+  - Navigation bar
+  - Call detail tables
+"""
+from __future__ import annotations
+
+import json
+import re
+from collections import defaultdict
+from html import escape
+from pathlib import Path
+
+
+# ── CSS (dark theme) ──────────────────────────────────────────────────────────
+
+_CSS = """:root {
+  --bg:#0f172a;--surface:#1e293b;--border:#334155;
+  --text:#e2e8f0;--muted:#94a3b8;--accent:#38bdf8;
+  --warn:#fbbf24;--ok:#34d399;
+}
+*{box-sizing:border-box;margin:0;padding:0;}
+body{font-family:'Segoe UI',system-ui,sans-serif;background:var(--bg);color:var(--text);line-height:1.7;}
+.container{max-width:1200px;margin:0 auto;padding:40px 24px;}
+h1{font-size:2.4rem;margin-bottom:8px;background:linear-gradient(135deg,var(--accent),#a78bfa);-webkit-background-clip:text;-webkit-text-fill-color:transparent;}
+h2{font-size:1.7rem;margin:48px 0 16px;padding-bottom:8px;border-bottom:2px solid var(--accent);}
+h3{font-size:1.25rem;margin:32px 0 12px;color:var(--accent);}
+p{margin:8px 0;color:var(--muted);}
+.subtitle{color:var(--muted);font-size:1.1rem;margin-bottom:32px;}
+.mermaid{background:var(--surface);border:1px solid var(--border);border-radius:12px;padding:24px;margin:20px 0;overflow-x:auto;}
+.call-table{width:100%;border-collapse:collapse;margin:16px 0;font-size:.92rem;}
+.call-table th{background:#1a2744;color:var(--accent);text-align:left;padding:10px 14px;border:1px solid var(--border);}
+.call-table td{padding:8px 14px;border:1px solid var(--border);vertical-align:top;}
+.call-table tr:nth-child(even){background:rgba(255,255,255,.02);}
+.card{background:var(--surface);border:1px solid var(--border);border-radius:10px;padding:20px;margin:16px 0;}
+.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(340px,1fr));gap:16px;margin:16px 0;}
+code{font-family:'Fira Code',monospace;background:rgba(255,255,255,.06);padding:1px 6px;border-radius:3px;font-size:.88em;}
+ul{margin:8px 0 8px 24px;color:var(--muted);}
+li{margin:4px 0;}
+a{color:var(--accent);}
+hr{border:none;border-top:1px solid var(--border);margin:40px 0;}
+.nav{position:sticky;top:0;background:var(--bg);z-index:10;padding:12px 0;border-bottom:1px solid var(--border);display:flex;gap:20px;flex-wrap:wrap;font-size:.9rem;}
+.nav a{text-decoration:none;}
+.nav a:hover{text-decoration:underline;}
+"""
+
+
+# ── Mermaid helpers ───────────────────────────────────────────────────────────
+
+def _mermaid_id(s: str) -> str:
+    """Sanitize string for use as a Mermaid node ID."""
+    return re.sub(r"[^a-zA-Z0-9_]", "_", s)[:40] or "node"
+
+
+def _mermaid_label(s: str) -> str:
+    return s.replace('"', "'")[:60]
+
+
+# ── Overview diagram: community meta-graph ────────────────────────────────────
+
+def _overview_diagram(communities: list[dict], edges: list[dict], node_map: dict[str, dict]) -> str:
+    """Mermaid flowchart showing cross-community edges."""
+    node_community: dict[str, int] = {}
+    for c in communities:
+        for mid in c.get("members", []):
+            node_community[mid] = c["id"]
+
+    cross_counts: dict[tuple[int, int], int] = defaultdict(int)
+    for e in edges:
+        src_comm = node_community.get(e.get("from", ""))
+        tgt_comm = node_community.get(e.get("to", ""))
+        if src_comm is not None and tgt_comm is not None and src_comm != tgt_comm:
+            key = (src_comm, tgt_comm)
+            cross_counts[key] += 1
+
+    lines = ["flowchart LR"]
+    for c in communities:
+        cid = c["id"]
+        label = _mermaid_label(c.get("label", f"Community {cid}"))
+        n = len(c.get("members", []))
+        mid = _mermaid_id(f"c{cid}")
+        lines.append(f'  {mid}["{label}\\n({n} nodes)"]')
+
+    top_cross = sorted(cross_counts.items(), key=lambda x: -x[1])[:30]
+    for (src_c, tgt_c), cnt in top_cross:
+        src_mid = _mermaid_id(f"c{src_c}")
+        tgt_mid = _mermaid_id(f"c{tgt_c}")
+        lines.append(f"  {src_mid} -->|{cnt}| {tgt_mid}")
+
+    return "\n".join(lines)
+
+
+# ── Per-community diagram ─────────────────────────────────────────────────────
+
+def _community_diagram(community: dict, edges: list[dict], node_map: dict[str, dict], max_nodes: int = 15) -> str:
+    """Mermaid flowchart for a single community's internal call edges."""
+    members = set(community.get("members", []))
+    member_nodes = [node_map[m] for m in members if m in node_map]
+
+    # Pick top nodes by internal degree
+    internal_degree: dict[str, int] = defaultdict(int)
+    intra_edges = []
+    for e in edges:
+        src, tgt = e.get("from", ""), e.get("to", "")
+        if src in members and tgt in members:
+            intra_edges.append(e)
+            internal_degree[src] += 1
+            internal_degree[tgt] += 1
+
+    top_nodes = sorted(members, key=lambda n: -internal_degree.get(n, 0))[:max_nodes]
+    top_set = set(top_nodes)
+
+    lines = ["flowchart LR"]
+    for nid in top_nodes:
+        n = node_map.get(nid, {})
+        name = _mermaid_label(n.get("name", nid))
+        ntype = n.get("type", "")
+        shape_open, shape_close = "[", "]"
+        if ntype == "class":
+            shape_open, shape_close = "([", "])"
+        elif ntype in ("function", "method"):
+            shape_open, shape_close = "(", ")"
+        mid = _mermaid_id(nid)
+        lines.append(f'  {mid}{shape_open}"{name}"{shape_close}')
+
+    shown_edges: set[tuple[str, str]] = set()
+    for e in intra_edges:
+        src, tgt = e.get("from", ""), e.get("to", "")
+        if src not in top_set or tgt not in top_set:
+            continue
+        key = (_mermaid_id(src), _mermaid_id(tgt))
+        if key in shown_edges:
+            continue
+        shown_edges.add(key)
+        rel = e.get("relation", "")
+        arrow = f" -->|{rel}| " if rel else " --> "
+        lines.append(f"  {_mermaid_id(src)}{arrow}{_mermaid_id(tgt)}")
+        if len(shown_edges) >= 30:
+            break
+
+    if not shown_edges:
+        # Fallback: show node list if no intra edges
+        lines = ["flowchart LR"]
+        for nid in top_nodes[:8]:
+            n = node_map.get(nid, {})
+            name = _mermaid_label(n.get("name", nid))
+            lines.append(f'  {_mermaid_id(nid)}["{name}"]')
+
+    return "\n".join(lines)
+
+
+# ── Call detail table ─────────────────────────────────────────────────────────
+
+def _call_table(community: dict, edges: list[dict], node_map: dict[str, dict]) -> str:
+    members = set(community.get("members", []))
+    cross_in = []
+    for e in edges:
+        src, tgt = e.get("from", ""), e.get("to", "")
+        if tgt in members and src not in members:
+            src_n = node_map.get(src, {})
+            tgt_n = node_map.get(tgt, {})
+            cross_in.append((src_n.get("name", src), tgt_n.get("name", tgt), e.get("relation", "→"), e.get("confidence", "")))
+
+    if not cross_in:
+        return ""
+
+    rows = "\n".join(
+        f"<tr><td><code>{escape(caller)}</code></td><td><code>{escape(callee)}</code></td><td>{escape(rel)}</td><td>{escape(conf)}</td></tr>"
+        for caller, callee, rel, conf in cross_in[:20]
+    )
+    return f"""<table class="call-table">
+<thead><tr><th>Caller</th><th>Callee</th><th>Relation</th><th>Confidence</th></tr></thead>
+<tbody>{rows}</tbody>
+</table>"""
+
+
+# ── Main entry point ──────────────────────────────────────────────────────────
+
+def to_html(graph_dict: dict, output_path: str) -> str:
+    """Generate Mermaid call-flow HTML. Returns path written."""
+    nodes = graph_dict.get("nodes", [])
+    edges = graph_dict.get("edges", [])
+    communities = graph_dict.get("communities", [])
+    god_nodes = graph_dict.get("god_nodes", [])
+    generated = graph_dict.get("generated_at", "")
+
+    node_map = {n["id"]: n for n in nodes}
+
+    # Navigation
+    nav_links = '<nav class="nav"><a href="#overview">Overview</a>' + "".join(
+        '<a href="#comm-{}">{}</a>'.format(c["id"], escape(c.get("label", f"C{c['id']}")))
+        for c in communities[:20]
+    ) + "</nav>"
+
+    # Overview section
+    overview_mermaid = _overview_diagram(communities, edges, node_map)
+    god_names = [node_map.get(nid, {}).get("name", nid) for nid in god_nodes[:5]]
+    god_html = (
+        "<div class='card'><h3>God Nodes</h3><ul>" +
+        "".join(f"<li><code>{escape(n)}</code></li>" for n in god_names) +
+        "</ul></div>"
+    ) if god_names else ""
+
+    overview_section = f"""<section id="overview">
+<h2>Architecture Overview</h2>
+<p>{len(nodes)} nodes · {len(edges)} edges · {len(communities)} communities · generated {escape(generated)}</p>
+{god_html}
+<div class="mermaid">
+{escape(overview_mermaid)}
+</div>
+</section>"""
+
+    # Per-community sections
+    comm_sections = []
+    for c in communities:
+        cid = c["id"]
+        label = c.get("label", f"Community {cid}")
+        members = c.get("members", [])
+        diagram = _community_diagram(c, edges, node_map)
+        table = _call_table(c, edges, node_map)
+
+        # Top files in this community
+        file_counts: dict[str, int] = defaultdict(int)
+        for mid in members:
+            f = node_map.get(mid, {}).get("file", "")
+            if f:
+                file_counts[f] += 1
+        top_files = sorted(file_counts.items(), key=lambda x: -x[1])[:5]
+        files_html = "".join(f"<li><code>{escape(fp)}</code> ({cnt} nodes)</li>" for fp, cnt in top_files)
+
+        comm_sections.append(f"""<section id="comm-{cid}">
+<h2>{escape(label)}</h2>
+<p>{len(members)} nodes</p>
+<div class="grid">
+  <div class="card"><h3>Key Files</h3><ul>{files_html}</ul></div>
+</div>
+<div class="mermaid">
+{escape(diagram)}
+</div>
+{"<h3>Incoming Cross-Community Calls</h3>" + table if table else ""}
+<hr>
+</section>""")
+
+    body = "\n".join(comm_sections)
+
+    html = f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>CodeGraph Call Flow</title>
+<style>{_CSS}</style>
+<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>
+<script>mermaid.initialize({{startOnLoad:true,theme:'dark',flowchart:{{curve:'basis'}}}});</script>
+</head>
+<body>
+{nav_links}
+<div class="container">
+<h1>Call Flow Architecture</h1>
+<p class="subtitle">Auto-generated from knowledge graph</p>
+{overview_section}
+{body}
+</div>
+</body>
+</html>"""
+
+    out = Path(output_path)
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_text(html, encoding="utf-8")
+    return str(out)