feat: add human-friendly architecture dashboard with Mermaid.js

Add dashboard.py that generates a single-page HTML architecture overview
from graph.json, designed for human team members and onboarding.

- Merges fine-grained Leiden communities into 5-10 macro-modules
- Auto-detects architectural layers (frontend/backend/engine/data/tools/tests)
- Renders Mermaid.js flowchart with layered subgraphs and directional arrows
- Module cards with key files, top nodes, and cross-module dependencies
- PageRank-based recommended reading order for new team members
- LLM-optional: auto-infers names, accepts override names and descriptions
- CLI: graphify dashboard [--graph path] [--output path]
- Skill: auto-generates in Step 6c of /graphify pipeline
- No new dependencies (Mermaid.js via CDN)

Author: kluacisco888

graphify/__main__.py

@@ -117,7 +117,7 @@ def _refresh_all_version_stamps() -> None:
     },
     "antigravity": {
         "skill_file": "skill.md",
-        "skill_dst": Path(".agents") / "skills" / "graphify" / "SKILL.md",
+        "skill_dst": Path(".agent") / "skills" / "graphify" / "SKILL.md",
         "claude_md": False,
     },
     "windows": {
@@ -148,12 +148,7 @@ def install(platform: str = "claude") -> None:
         print(f"error: {cfg['skill_file']} not found in package - reinstall graphify", file=sys.stderr)
         sys.exit(1)
 
-    import os as _os
-    if platform in ("claude", "windows") and _os.environ.get("CLAUDE_CONFIG_DIR"):
-        _claude_base = Path(_os.environ["CLAUDE_CONFIG_DIR"])
-        skill_dst = _claude_base / "skills" / "graphify" / "SKILL.md"
-    else:
-        skill_dst = Path.home() / cfg["skill_dst"]
+    skill_dst = Path.home() / cfg["skill_dst"]
     skill_dst.parent.mkdir(parents=True, exist_ok=True)
     shutil.copy(skill_src, skill_dst)
     (skill_dst.parent / ".graphify_version").write_text(__version__, encoding="utf-8")
@@ -196,7 +191,6 @@ def install(platform: str = "claude") -> None:
 Rules:
 - Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
-- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)
 """
 
@@ -212,7 +206,6 @@ def install(platform: str = "claude") -> None:
 Rules:
 - Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
-- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)
 """
 
@@ -226,7 +219,6 @@ def install(platform: str = "claude") -> None:
 Rules:
 - Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
-- For cross-module "how does X relate to Y" questions, prefer `graphify query "<question>"`, `graphify path "<A>" "<B>"`, or `graphify explain "<concept>"` over grep — these traverse the graph's EXTRACTED + INFERRED edges instead of scanning files
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)
 """
 
@@ -417,8 +409,8 @@ def vscode_uninstall(project_dir: Path | None = None) -> None:
         print(f"  {instructions}  ->  deleted (was empty after removal)")
 
 
-_ANTIGRAVITY_RULES_PATH = Path(".agents") / "rules" / "graphify.md"
-_ANTIGRAVITY_WORKFLOW_PATH = Path(".agents") / "workflows" / "graphify.md"
+_ANTIGRAVITY_RULES_PATH = Path(".agent") / "rules" / "graphify.md"
+_ANTIGRAVITY_WORKFLOW_PATH = Path(".agent") / "workflows" / "graphify.md"
 
 _ANTIGRAVITY_RULES = """\
 ## graphify
@@ -429,7 +421,6 @@ def vscode_uninstall(project_dir: Path | None = None) -> None:
 - Before answering architecture or codebase questions, read graphify-out/GRAPH_REPORT.md for god nodes and community structure
 - If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
 - If the graphify MCP server is active, utilize tools like `query_graph`, `get_node`, and `shortest_path` for precise architecture navigation instead of falling back to `grep`
-- If the MCP server is not active, the CLI equivalents are `graphify query "<question>"`, `graphify path "<A>" "<B>"`, and `graphify explain "<concept>"` — prefer these over grep for cross-module questions
 - After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)
 """
 
@@ -439,7 +430,7 @@ def vscode_uninstall(project_dir: Path | None = None) -> None:
 **Description:** Turn any folder of files into a navigable knowledge graph
 
 ## Steps
-Follow the graphify skill installed at ~/.agents/skills/graphify/SKILL.md to run the full pipeline.
+Follow the graphify skill installed at ~/.agent/skills/graphify/SKILL.md to run the full pipeline.
 
 If no path argument is given, use `.` (current directory).
 """
@@ -509,8 +500,8 @@ def _kiro_uninstall(project_dir: Path) -> None:
 
 
 def _antigravity_install(project_dir: Path) -> None:
-    """Install graphify for Google Antigravity: skill + .agents/rules + .agents/workflows."""
-    # 1. Copy skill file to ~/.agents/skills/graphify/SKILL.md
+    """Install graphify for Google Antigravity: skill + .agent/rules + .agent/workflows."""
+    # 1. Copy skill file to ~/.agent/skills/graphify/SKILL.md
     install(platform="antigravity")
 
     # 1.5. Inject YAML frontmatter for native Antigravity tool discovery
@@ -521,7 +512,7 @@ def _antigravity_install(project_dir: Path) -> None:
             frontmatter = "---\nname: graphify-manager\ndescription: Rebuild the code graph or perform manual CLI queries when MCP server is offline.\n---\n\n"
             skill_dst.write_text(frontmatter + content, encoding="utf-8")
 
-    # 2. Write .agents/rules/graphify.md
+    # 2. Write .agent/rules/graphify.md
     rules_path = project_dir / _ANTIGRAVITY_RULES_PATH
     rules_path.parent.mkdir(parents=True, exist_ok=True)
     if rules_path.exists():
@@ -530,7 +521,7 @@ def _antigravity_install(project_dir: Path) -> None:
         rules_path.write_text(_ANTIGRAVITY_RULES, encoding="utf-8")
         print(f"graphify rule written to {rules_path.resolve()}")
 
-    # 3. Write .agents/workflows/graphify.md
+    # 3. Write .agent/workflows/graphify.md
     wf_path = project_dir / _ANTIGRAVITY_WORKFLOW_PATH
     wf_path.parent.mkdir(parents=True, exist_ok=True)
     if wf_path.exists():
@@ -648,7 +639,7 @@ def _cursor_uninstall(project_dir: Path) -> None:
 """
 
 _OPENCODE_PLUGIN_PATH = Path(".opencode") / "plugins" / "graphify.js"
-_OPENCODE_CONFIG_PATH = Path(".opencode") / "opencode.json"
+_OPENCODE_CONFIG_PATH = Path("opencode.json")
 
 
 def _install_opencode_plugin(project_dir: Path) -> None:
@@ -911,59 +902,6 @@ def claude_uninstall(project_dir: Path | None = None) -> None:
     _uninstall_claude_hook(project_dir or Path("."))
 
 
-def _clone_repo(url: str, branch: str | None = None, out_dir: Path | None = None) -> Path:
-    """Clone a GitHub repo to a local cache dir and return the path.
-
-    Clones into ~/.graphify/repos/<owner>/<repo> by default so repeated
-    runs on the same URL reuse the existing clone (git pull instead of clone).
-    """
-    import subprocess as _sp
-    import re as _re
-
-    # Normalise URL — strip trailing .git if present
-    url = url.rstrip("/")
-    if not url.endswith(".git"):
-        git_url = url + ".git"
-    else:
-        git_url = url
-        url = url[:-4]
-
-    # Extract owner/repo from URL
-    m = _re.search(r"github\.com[:/]([^/]+)/([^/]+?)(?:\.git)?$", url)
-    if not m:
-        print(f"error: not a recognised GitHub URL: {url}", file=sys.stderr)
-        sys.exit(1)
-    owner, repo = m.group(1), m.group(2)
-
-    if out_dir:
-        dest = out_dir
-    else:
-        dest = Path.home() / ".graphify" / "repos" / owner / repo
-
-    if dest.exists():
-        print(f"Repo already cloned at {dest} — pulling latest...", flush=True)
-        cmd = ["git", "-C", str(dest), "pull"]
-        if branch:
-            cmd += ["origin", branch]
-        result = _sp.run(cmd, capture_output=True, text=True)
-        if result.returncode != 0:
-            print(f"warning: git pull failed:\n{result.stderr}", file=sys.stderr)
-    else:
-        dest.parent.mkdir(parents=True, exist_ok=True)
-        print(f"Cloning {url} → {dest} ...", flush=True)
-        cmd = ["git", "clone", "--depth", "1"]
-        if branch:
-            cmd += ["--branch", branch]
-        cmd += [git_url, str(dest)]
-        result = _sp.run(cmd, capture_output=True, text=True)
-        if result.returncode != 0:
-            print(f"error: git clone failed:\n{result.stderr}", file=sys.stderr)
-            sys.exit(1)
-
-    print(f"Ready at: {dest}", flush=True)
-    return dest
-
-
 def main() -> None:
     # Check all known skill install locations for a stale version stamp.
     # Skip during install/uninstall (hook writes trigger a fresh check anyway).
@@ -981,11 +919,6 @@ def main() -> None:
         print("    --graph <path>          path to graph.json (default graphify-out/graph.json)")
         print("  explain \"X\"             plain-language explanation of a node and its neighbors")
         print("    --graph <path>          path to graph.json (default graphify-out/graph.json)")
-        print("  clone <github-url>      clone a GitHub repo locally and print its path for /graphify")
-        print("  merge-graphs <g1> <g2>  merge two or more graph.json files into one cross-repo graph")
-        print("    --out <path>            output path (default: graphify-out/merged-graph.json)")
-        print("    --branch <branch>       checkout a specific branch (default: repo default)")
-        print("    --out <dir>             clone to a custom directory (default: ~/.graphify/repos/<owner>/<repo>)")
         print("  add <url>               fetch a URL and save it to ./raw, then update the graph")
         print("    --author \"Name\"         tag the author of the content")
         print("    --contributor \"Name\"    tag who added it to the corpus")
@@ -1003,8 +936,10 @@ def main() -> None:
         print("    --type T                query type: query|path_query|explain (default: query)")
         print("    --nodes N1 N2 ...       source node labels cited in the answer")
         print("    --memory-dir DIR        memory directory (default: graphify-out/memory)")
-        print("  check-update <path>     check needs_update flag and notify if semantic re-extraction is pending (cron-safe)")
         print("  benchmark [graph.json]  measure token reduction vs naive full-corpus approach")
+        print("  dashboard             generate human-friendly architecture dashboard")
+        print("    --graph <path>        path to graph.json (default graphify-out/graph.json)")
+        print("    --output <path>       output path (default graphify-out/dashboard.html)")
         print("  hook install            install post-commit/post-checkout git hooks (all platforms)")
         print("  hook uninstall          remove git hooks")
         print("  hook status             check if git hooks are installed")
@@ -1032,8 +967,8 @@ def main() -> None:
         print("  trae uninstall         remove graphify section from AGENTS.md")
         print("  trae-cn install         write graphify section to AGENTS.md (Trae CN)")
         print("  trae-cn uninstall      remove graphify section from AGENTS.md")
-        print("  antigravity install     write .agents/rules + .agents/workflows + skill (Google Antigravity)")
-        print("  antigravity uninstall   remove .agents/rules, .agents/workflows, and skill")
+        print("  antigravity install     write .agent/rules + .agent/workflows + skill (Google Antigravity)")
+        print("  antigravity uninstall   remove .agent/rules, .agent/workflows, and skill")
         print("  hermes install          write skill to ~/.hermes/skills/graphify/ (Hermes)")
         print("  hermes uninstall        remove skill from ~/.hermes/skills/graphify/")
         print("  kiro install            write skill to .kiro/skills/graphify/ + steering file (Kiro IDE/CLI)")
@@ -1415,73 +1350,6 @@ def main() -> None:
             print("Nothing to update or rebuild failed — check output above.", file=sys.stderr)
             sys.exit(1)
 
-    elif cmd == "check-update":
-        if len(sys.argv) < 3:
-            print("Usage: graphify check-update <path>", file=sys.stderr)
-            sys.exit(1)
-        from graphify.watch import check_update
-        check_update(Path(sys.argv[2]).resolve())
-        sys.exit(0)
-    elif cmd == "merge-graphs":
-        # graphify merge-graphs graph1.json graph2.json ... --out merged.json
-        args = sys.argv[2:]
-        graph_paths: list[Path] = []
-        out_path = Path("graphify-out/merged-graph.json")
-        i = 0
-        while i < len(args):
-            if args[i] == "--out" and i + 1 < len(args):
-                out_path = Path(args[i + 1]); i += 2
-            else:
-                graph_paths.append(Path(args[i])); i += 1
-        if len(graph_paths) < 2:
-            print("Usage: graphify merge-graphs <graph1.json> <graph2.json> [...] [--out merged.json]", file=sys.stderr)
-            sys.exit(1)
-        import networkx as _nx
-        from networkx.readwrite import json_graph as _jg
-        graphs = []
-        for gp in graph_paths:
-            if not gp.exists():
-                print(f"error: not found: {gp}", file=sys.stderr)
-                sys.exit(1)
-            data = json.loads(gp.read_text(encoding="utf-8"))
-            try:
-                G = _jg.node_link_graph(data, edges="links")
-            except TypeError:
-                G = _jg.node_link_graph(data)
-            # Tag every node with which repo it came from
-            repo_tag = gp.parent.parent.name  # graphify-out/../ → repo dir name
-            for node in G.nodes:
-                G.nodes[node].setdefault("repo", repo_tag)
-            graphs.append(G)
-        merged = _nx.compose_all(graphs)
-        try:
-            out_data = _jg.node_link_data(merged, edges="links")
-        except TypeError:
-            out_data = _jg.node_link_data(merged)
-        out_path.parent.mkdir(parents=True, exist_ok=True)
-        out_path.write_text(json.dumps(out_data, indent=2), encoding="utf-8")
-        print(f"Merged {len(graphs)} graphs → {merged.number_of_nodes()} nodes, {merged.number_of_edges()} edges")
-        print(f"Written to: {out_path}")
-
-    elif cmd == "clone":
-        if len(sys.argv) < 3:
-            print("Usage: graphify clone <github-url> [--branch <branch>] [--out <dir>]", file=sys.stderr)
-            sys.exit(1)
-        url = sys.argv[2]
-        branch: str | None = None
-        out_dir: Path | None = None
-        args = sys.argv[3:]
-        i = 0
-        while i < len(args):
-            if args[i] == "--branch" and i + 1 < len(args):
-                branch = args[i + 1]; i += 2
-            elif args[i] == "--out" and i + 1 < len(args):
-                out_dir = Path(args[i + 1]); i += 2
-            else:
-                i += 1
-        local_path = _clone_repo(url, branch=branch, out_dir=out_dir)
-        print(local_path)
-
     elif cmd == "benchmark":
         from graphify.benchmark import run_benchmark, print_benchmark
         graph_path = sys.argv[2] if len(sys.argv) > 2 else "graphify-out/graph.json"
@@ -1496,6 +1364,27 @@ def main() -> None:
                 pass
         result = run_benchmark(graph_path, corpus_words=corpus_words)
         print_benchmark(result)
+    elif cmd == "dashboard":
+        graph_path = "graphify-out/graph.json"
+        output_path = "graphify-out/dashboard.html"
+        args = sys.argv[2:]
+        i = 0
+        while i < len(args):
+            if args[i] == "--graph" and i + 1 < len(args):
+                graph_path = args[i + 1]; i += 2
+            elif args[i] == "--output" and i + 1 < len(args):
+                output_path = args[i + 1]; i += 2
+            else:
+                i += 1
+        gp = Path(graph_path)
+        if not gp.exists():
+            print(f"error: graph not found at {gp} — run /graphify first", file=sys.stderr)
+            sys.exit(1)
+        from graphify.dashboard import generate_dashboard
+        result = generate_dashboard(str(gp), output_path)
+        n = len(result["modules"])
+        print(f"Dashboard: {n} modules → {output_path}")
+        print("Open in browser — no server needed.")
     else:
         print(f"error: unknown command '{cmd}'", file=sys.stderr)
         print("Run 'graphify --help' for usage.", file=sys.stderr)