ckgraphify 0.1.0__py3-none-any.whl

graphify/__main__.py

@@ -0,0 +1,2885 @@
+"""graphify CLI - `graphify install` sets up the cgraph assistant skill."""
+from __future__ import annotations
+import json
+import os
+import re
+import shutil
+import sys
+from pathlib import Path
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("ckgraphify")
+except Exception:
+    __version__ = "unknown"
+
+# Output directory — override with GRAPHIFY_OUT env var for worktrees or shared-output setups.
+# Accepts a relative name ("graphify-out-feature") or an absolute path ("/shared/graphify-out").
+_GRAPHIFY_OUT = os.environ.get("GRAPHIFY_OUT", "graphify-out")
+
+
+def _default_graph_path() -> str:
+    return str(Path(_GRAPHIFY_OUT) / "graph.json")
+
+
+def _check_skill_version(skill_dst: Path) -> None:
+    """Warn if the installed skill is from an older ckgraphify package version."""
+    version_file = skill_dst.parent / ".cgraph_version"
+    if not version_file.exists():
+        return
+    if not skill_dst.exists():
+        print("  warning: skill dir exists but SKILL.md is missing. Run 'graphify install' to repair.")
+        return
+    installed = version_file.read_text(encoding="utf-8").strip()
+    if installed != __version__:
+        print(f"  warning: skill is from ckgraphify {installed}, package is {__version__}. Run 'graphify install' to update.", file=sys.stderr)
+
+
+def _refresh_all_version_stamps() -> None:
+    """After a successful install, update .cgraph_version in all other known skill dirs.
+
+    Prevents stale-version warnings from platforms that were installed previously
+    but not explicitly re-installed during this upgrade.
+    """
+    for cfg in _PLATFORM_CONFIG.values():
+        skill_dst = Path.home() / cfg["skill_dst"]
+        vf = skill_dst.parent / ".cgraph_version"
+        if skill_dst.exists():
+            vf.write_text(__version__, encoding="utf-8")
+
+_SETTINGS_HOOK = {
+    # Claude Code v2.1.117+ removed dedicated Grep/Glob tools; searches now go through Bash.
+    # We match on Bash and inspect the command string to avoid firing on every shell call.
+    "matcher": "Bash",
+    "hooks": [
+        {
+            "type": "command",
+            "command": (
+                "CMD=$(python3 -c \""
+                "import json,sys; d=json.load(sys.stdin); "
+                "print(d.get('tool_input',d).get('command',''))\" 2>/dev/null || true); "
+                "case \"$CMD\" in "
+                r"*grep*|*rg\ *|*ripgrep*|*find\ *|*fd\ *|*ack\ *|*ag\ *) "
+                "  [ -f graphify-out/graph.json ] && "
+                r"""  echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"cgraph: Knowledge graph exists. Read graphify-out/GRAPH_REPORT.md for god nodes and community structure before searching raw files."}}' """
+                "  || true ;; "
+                "esac"
+            ),
+        }
+    ],
+}
+
+_SKILL_REGISTRATION = (
+    "\n# cgraph\n"
+    "- **cgraph** (`~/.claude/skills/cgraph/SKILL.md`) "
+    "- graph-main, multi-repo call-chain, and business-map skill. Trigger: `/cgraph`\n"
+    "When the user types `/cgraph`, invoke the Skill tool "
+    "with `skill: \"cgraph\"` before doing anything else.\n"
+)
+
+
+_PLATFORM_CONFIG: dict[str, dict] = {
+    "claude": {
+        "skill_file": "skill/skill.md",
+        "skill_dst": Path(".claude") / "skills" / "cgraph" / "SKILL.md",
+        "claude_md": True,
+    },
+    "codex": {
+        "skill_file": "skill/skill-codex.md",
+        "skill_dst": Path(".agents") / "skills" / "cgraph" / "SKILL.md",
+        "claude_md": False,
+    },
+}
+
+
+def install(platform: str = "claude") -> None:
+    if platform not in _PLATFORM_CONFIG:
+        print(
+            f"error: unknown platform '{platform}'. Choose from: {', '.join(_PLATFORM_CONFIG)}",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    cfg = _PLATFORM_CONFIG[platform]
+    skill_src = Path(__file__).parent.parent / cfg["skill_file"]
+    if not skill_src.exists():
+        print(f"error: {cfg['skill_file']} not found in package - reinstall cgraph", file=sys.stderr)
+        sys.exit(1)
+
+    import os as _os
+    if platform == "claude" and _os.environ.get("CLAUDE_CONFIG_DIR"):
+        _claude_base = Path(_os.environ["CLAUDE_CONFIG_DIR"])
+        skill_dst = _claude_base / "skills" / "cgraph" / "SKILL.md"
+    else:
+        skill_dst = Path.home() / cfg["skill_dst"]
+    skill_dst.parent.mkdir(parents=True, exist_ok=True)
+    tmp_dst = skill_dst.with_suffix(skill_dst.suffix + ".tmp")
+    try:
+        shutil.copy(skill_src, tmp_dst)
+        os.replace(tmp_dst, skill_dst)
+    except Exception:
+        try:
+            tmp_dst.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+    (skill_dst.parent / ".cgraph_version").write_text(__version__, encoding="utf-8")
+    print(f"  skill installed  ->  {skill_dst}")
+
+    if cfg["claude_md"]:
+        # Register in ~/.claude/CLAUDE.md (Claude Code only)
+        claude_md = Path.home() / ".claude" / "CLAUDE.md"
+        if claude_md.exists():
+            content = claude_md.read_text(encoding="utf-8")
+            if "cgraph" in content:
+                print(f"  CLAUDE.md        ->  already registered (no change)")
+            else:
+                claude_md.write_text(content.rstrip() + _SKILL_REGISTRATION, encoding="utf-8")
+                print(f"  CLAUDE.md        ->  skill registered in {claude_md}")
+        else:
+            claude_md.parent.mkdir(parents=True, exist_ok=True)
+            claude_md.write_text(_SKILL_REGISTRATION.lstrip(), encoding="utf-8")
+            print(f"  CLAUDE.md        ->  created at {claude_md}")
+
+    # Refresh version stamps in all other previously-installed skill dirs so
+    # stale-version warnings don't fire for platforms not explicitly re-installed.
+    _refresh_all_version_stamps()
+
+    print()
+    print("Done. Open your AI coding assistant and type:")
+    print()
+    print("  /cgraph")
+    print()
+
+
+def _print_install_usage() -> None:
+    platforms = ", ".join([*_PLATFORM_CONFIG])
+    print("Usage: graphify install [--platform P|P]")
+    print(f"Platforms: {platforms}")
+
+
+_CLAUDE_MD_SECTION = """\
+## cgraph
+
+This project has a cgraph knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+Rules:
+- ALWAYS read graphify-out/GRAPH_REPORT.md before reading any source files, running grep/glob searches, or answering codebase questions. The graph is your primary map of the codebase.
+- 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, run `graphify update .` to keep the graph current (AST-only, no API cost).
+"""
+
+_CLAUDE_MD_MARKER = "## cgraph"
+
+# AGENTS.md section for Codex.
+_AGENTS_MD_SECTION = """\
+## cgraph
+
+This project has a cgraph knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.
+
+When the user types `/cgraph` or `$cgraph`, invoke the `skill` tool with `skill: "cgraph"` before doing anything else.
+
+Rules:
+- ALWAYS read graphify-out/GRAPH_REPORT.md before reading any source files, running grep/glob searches, or answering codebase questions. The graph is your primary map of the codebase.
+- 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, run `graphify update .` to keep the graph current (AST-only, no API cost).
+"""
+
+_AGENTS_MD_MARKER = "## cgraph"
+
+
+_CODEX_HOOK = {
+    "hooks": {
+        "PreToolUse": [
+            {
+                "matcher": "Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        # Use the graphify CLI itself so the hook is shell-agnostic:
+                        # no [ -f ] bash syntax, no python3 vs python Conda issue,
+                        # no JSON escaping inside PowerShell strings. Works on
+                        # Windows (PowerShell/cmd.exe), macOS, and Linux.
+                        "command": "graphify hook-check",
+                    }
+                ],
+            }
+        ]
+    }
+}
+
+
+def _resolve_graphify_exe() -> str:
+    """Return the absolute path to the graphify executable.
+
+    Falls back to bare 'graphify' if resolution fails. Using an absolute path
+    ensures the hook works in environments where the venv Scripts/ directory is
+    not on PATH (e.g. VS Code Codex extension on Windows).
+    """
+    import shutil
+    found = shutil.which("graphify")
+    if found:
+        return found
+    # Derive from sys.executable: same Scripts/ (Windows) or bin/ (Unix) dir
+    scripts_dir = Path(sys.executable).parent
+    for name in ("graphify.exe", "graphify"):
+        candidate = scripts_dir / name
+        if candidate.exists():
+            return str(candidate)
+    return "graphify"
+
+
+def _install_codex_hook(project_dir: Path) -> None:
+    """Add cgraph PreToolUse hook to .codex/hooks.json."""
+    hooks_path = project_dir / ".codex" / "hooks.json"
+    hooks_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if hooks_path.exists():
+        try:
+            existing = json.loads(hooks_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            existing = {}
+    else:
+        existing = {}
+
+    graphify_exe = _resolve_graphify_exe()
+    hook_entry = {
+        "hooks": {
+            "PreToolUse": [
+                {
+                    "matcher": "Bash",
+                    "hooks": [{"type": "command", "command": f"{graphify_exe} hook-check"}],
+                }
+            ]
+        }
+    }
+
+    pre_tool = existing.setdefault("hooks", {}).setdefault("PreToolUse", [])
+    existing["hooks"]["PreToolUse"] = [h for h in pre_tool if "graphify" not in str(h)]
+    existing["hooks"]["PreToolUse"].extend(hook_entry["hooks"]["PreToolUse"])
+    hooks_path.write_text(json.dumps(existing, indent=2), encoding="utf-8")
+    print(f"  .codex/hooks.json  ->  PreToolUse hook registered ({graphify_exe} hook-check)")
+
+
+def _uninstall_codex_hook(project_dir: Path) -> None:
+    """Remove cgraph PreToolUse hook from .codex/hooks.json."""
+    hooks_path = project_dir / ".codex" / "hooks.json"
+    if not hooks_path.exists():
+        return
+    try:
+        existing = json.loads(hooks_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return
+    pre_tool = existing.get("hooks", {}).get("PreToolUse", [])
+    filtered = [h for h in pre_tool if "graphify" not in str(h)]
+    existing["hooks"]["PreToolUse"] = filtered
+    hooks_path.write_text(json.dumps(existing, indent=2), encoding="utf-8")
+    print(f"  .codex/hooks.json  ->  PreToolUse hook removed")
+
+
+def _agents_install(project_dir: Path) -> None:
+    """Write the cgraph section to the local AGENTS.md (Codex)."""
+    target = (project_dir or Path(".")) / "AGENTS.md"
+
+    if target.exists():
+        content = target.read_text(encoding="utf-8")
+        if _AGENTS_MD_MARKER in content:
+            print(f"cgraph already configured in AGENTS.md")
+        else:
+            target.write_text(content.rstrip() + "\n\n" + _AGENTS_MD_SECTION, encoding="utf-8")
+            print(f"cgraph section written to {target.resolve()}")
+    else:
+        target.write_text(_AGENTS_MD_SECTION, encoding="utf-8")
+        print(f"cgraph section written to {target.resolve()}")
+
+    _install_codex_hook(project_dir or Path("."))
+
+    print()
+    print("Codex will now check the knowledge graph before answering")
+    print("codebase questions and rebuild it after code changes.")
+
+
+def _agents_uninstall(project_dir: Path) -> None:
+    """Remove the cgraph section from the local AGENTS.md."""
+    target = (project_dir or Path(".")) / "AGENTS.md"
+
+    if not target.exists():
+        print("No AGENTS.md found in current directory - nothing to do")
+        return
+
+    content = target.read_text(encoding="utf-8")
+    if _AGENTS_MD_MARKER not in content:
+        print("cgraph section not found in AGENTS.md - nothing to do")
+        return
+
+    cleaned = re.sub(
+        r"\n*## cgraph\n.*?(?=\n## |\Z)",
+        "",
+        content,
+        flags=re.DOTALL,
+    ).rstrip()
+    if cleaned:
+        target.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"cgraph section removed from {target.resolve()}")
+    else:
+        target.unlink()
+        print(f"AGENTS.md was empty after removal - deleted {target.resolve()}")
+
+
+
+def claude_install(project_dir: Path | None = None) -> None:
+    """Write the cgraph section to the local CLAUDE.md."""
+    target = (project_dir or Path(".")) / "CLAUDE.md"
+
+    if target.exists():
+        content = target.read_text(encoding="utf-8")
+        if _CLAUDE_MD_MARKER in content:
+            print("cgraph already configured in CLAUDE.md")
+            return
+        new_content = content.rstrip() + "\n\n" + _CLAUDE_MD_SECTION
+    else:
+        new_content = _CLAUDE_MD_SECTION
+
+    target.write_text(new_content, encoding="utf-8")
+    print(f"cgraph section written to {target.resolve()}")
+
+    # Also write Claude Code PreToolUse hook to .claude/settings.json
+    _install_claude_hook(project_dir or Path("."))
+
+    print()
+    print("Claude Code will now check the knowledge graph before answering")
+    print("codebase questions and rebuild it after code changes.")
+
+
+def _install_claude_hook(project_dir: Path) -> None:
+    """Add cgraph PreToolUse hook to .claude/settings.json."""
+    settings_path = project_dir / ".claude" / "settings.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    if settings_path.exists():
+        try:
+            settings = json.loads(settings_path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            settings = {}
+    else:
+        settings = {}
+
+    hooks = settings.setdefault("hooks", {})
+    pre_tool = hooks.setdefault("PreToolUse", [])
+
+    hooks["PreToolUse"] = [h for h in pre_tool if not (h.get("matcher") in ("Glob|Grep", "Bash") and "graphify" in str(h))]
+    hooks["PreToolUse"].append(_SETTINGS_HOOK)
+    settings_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    print(f"  .claude/settings.json  ->  PreToolUse hook registered")
+
+
+def _uninstall_claude_hook(project_dir: Path) -> None:
+    """Remove cgraph PreToolUse hook from .claude/settings.json."""
+    settings_path = project_dir / ".claude" / "settings.json"
+    if not settings_path.exists():
+        return
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return
+    pre_tool = settings.get("hooks", {}).get("PreToolUse", [])
+    filtered = [h for h in pre_tool if not (h.get("matcher") in ("Glob|Grep", "Bash") and "graphify" in str(h))]
+    if len(filtered) == len(pre_tool):
+        return
+    settings["hooks"]["PreToolUse"] = filtered
+    settings_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    print(f"  .claude/settings.json  ->  PreToolUse hook removed")
+
+
+def uninstall_all(project_dir: Path | None = None, purge: bool = False) -> None:
+    """Remove cgraph from supported assistant configs in the current project."""
+    pd = project_dir or Path(".")
+    print("Uninstalling cgraph from Claude Code and Codex configs...\n")
+
+    # Skill-file / config-section uninstallers
+    claude_uninstall(pd)
+    # AGENTS.md covers codex
+    _agents_uninstall(pd)
+    _uninstall_codex_hook(pd)
+
+    # Git hook
+    try:
+        from graphify.hooks import uninstall as hook_uninstall
+        result = hook_uninstall(pd)
+        if result:
+            print(result)
+    except Exception:
+        pass
+
+    if purge:
+        import shutil as _shutil
+        out = pd / "graphify-out"
+        if out.exists():
+            _shutil.rmtree(out)
+            print(f"\n  graphify-out/  ->  deleted (--purge)")
+        else:
+            print("\n  graphify-out/  ->  not found (nothing to purge)")
+
+    print("\nDone. Run 'pip uninstall ckgraphify' to remove the package itself.")
+
+
+def claude_uninstall(project_dir: Path | None = None) -> None:
+    """Remove the cgraph section from the local CLAUDE.md."""
+    target = (project_dir or Path(".")) / "CLAUDE.md"
+
+    if not target.exists():
+        print("No CLAUDE.md found in current directory - nothing to do")
+        return
+
+    content = target.read_text(encoding="utf-8")
+    if _CLAUDE_MD_MARKER not in content:
+        print("cgraph section not found in CLAUDE.md - nothing to do")
+        return
+
+    # Remove the ## cgraph section: from the marker to the next ## heading or EOF
+    cleaned = re.sub(
+        r"\n*## cgraph\n.*?(?=\n## |\Z)",
+        "",
+        content,
+        flags=re.DOTALL,
+    ).rstrip()
+    if cleaned:
+        target.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"cgraph section removed from {target.resolve()}")
+    else:
+        target.unlink()
+        print(f"CLAUDE.md was empty after removal - deleted {target.resolve()}")
+
+    _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 branch and branch.startswith("-"):
+        print(f"error: invalid branch name: {branch!r}", file=sys.stderr)
+        sys.exit(1)
+
+    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).
+    # Skip during hook-check — it runs on every editor tool use and must be silent.
+    # Deduplicate paths so platforms sharing the same install dir don't warn twice.
+    _silent_cmds = {"install", "uninstall", "hook-check"}
+    if not any(arg in _silent_cmds for arg in sys.argv):
+        for skill_dst in {Path.home() / cfg["skill_dst"] for cfg in _PLATFORM_CONFIG.values()}:
+            _check_skill_version(skill_dst)
+
+    if len(sys.argv) >= 2 and sys.argv[1] in ("-v", "--version", "version"):
+        print(f"graphify {__version__}")
+        return
+
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help", "-?"):
+        print("Usage: graphify <command>")
+        print()
+        print("Commands:")
+        print("  install [--platform P]  copy skill to supported assistant config dir (claude|codex)")
+        print("  uninstall               remove cgraph from Claude Code and Codex configs")
+        print("    --purge                 also delete graphify-out/ directory")
+        print("  path \"A\" \"B\"            shortest path between two nodes in graph.json")
+        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 /cgraph")
+        print("  merge-driver <base> <current> <other>  git merge driver: union-merge two graph.json files (set up via hook install)")
+        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("  merge-main-graphs <graph-main.json...>  merge multiple graph-main boundary graphs")
+        print("    --out <path>            output path (default: graphify-out/graph-main-merged.json)")
+        print("    --report <path>         report path (default: graphify-out/graph-main-merged-report.md)")
+        print("  main-trace --graph <path> --from <node> [--api <api>] [--max-depth N] [--sources] [--prefer-repo R] [--exclude-repo R]")
+        print("                            trace a graph-main chain from an exact entry/API")
+        print("  business-init --concept <name> [--out graphify-out/business-map.json]")
+        print("                            create a business-map seed (currently: 健康卡)")
+        print("  business-show [--map <path>] [--concept <name>] [--scenario <name>]")
+        print("                            inspect concepts, scenarios, anchors, and trace hints")
+        print("  business-query \"question\" [--map <path>] [--graph <path>] [--trace] [--sources] [--format json|text]")
+        print("                            match a business question to concept/scenario/flow and optionally trace it")
+        print("  business-lint [--map <path>]")
+        print("                            check business-map modeling policy and report conflicts")
+        print("  business-validate [--map <path>] [--graph <path>]")
+        print("                            validate business-map anchors against a graph-main graph")
+        print("  business-trace [--map <path>] [--graph <path>] --concept <name> [--scenario <name>] [--flow <name>] [--max-depth N] [--sources]")
+        print("                            run main-trace from business-map trace hints")
+        print("  bridge-mtop             add cross-repo frontend->mtop->backend bridge edges onto a graph")
+        print("    --repos-root <path>     repos root directory (required)")
+        print("    --graph-in <path>       input graph path (default: graphify-out/graph.json)")
+        print("    --graph-out <path>      output graph path (default: graphify-out/graph-bridge-mtop.json)")
+        print("    --report <path>         write bridge report JSON (default: graphify-out/bridge-mtop-report.json)")
+        print("    --max-file-size N       skip files larger than N bytes (default: 1000000)")
+        print("    --repos A,B,C           optional repo-tag allowlist (defaults to graph repo tags)")
+        print("    --thin-out <path>       optional thin graph output path (mtop-focused subgraph)")
+        print("    --thin-hops N           neighborhood hops for thin graph (default: 1)")
+        print("  main-graph [path]       build graph-main.json (auto-detect frontend/backend)")
+        print("    backend Java repos auto-switch to backend-normal/backend-sdk detection")
+        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")
+        print("    --dir <path>            target directory (default: ./raw)")
+        print("  watch <path>            watch a folder and rebuild the graph on code changes")
+        print("  update <path>           re-extract code files and update the graph (no LLM needed)")
+        print("    --force                 overwrite graph.json even if the rebuild has fewer nodes")
+        print("                            (also: GRAPHIFY_FORCE=1 env var; use after refactors that delete code)")
+        print("    --no-cluster            skip clustering, write raw extraction only")
+        print("  cluster-only <path>     rerun clustering on an existing graph.json and regenerate report")
+        print("    --no-viz                skip graph.html generation (useful for >5000 node graphs / CI)")
+        print("    --graph <path>          path to graph.json (default <path>/graphify-out/graph.json)")
+        print("  query \"<question>\"       BFS traversal of graph.json for a question")
+        print("    --dfs                   use depth-first instead of breadth-first")
+        print("    --context C             explicit edge-context filter (repeatable)")
+        print("    --budget N              cap output at N tokens (default 2000)")
+        print("    --graph <path>          path to graph.json (default graphify-out/graph.json)")
+        print("  save-result             save a Q&A result to graphify-out/memory/ for graph feedback loop")
+        print("    --question Q            the question asked")
+        print("    --answer A              the answer to save")
+        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("  tree                    emit a D3 v7 collapsible-tree HTML for graph.json")
+        print("    --graph PATH            path to graph.json (default graphify-out/graph.json)")
+        print("    --output HTML           output path (default graphify-out/GRAPH_TREE.html)")
+        print("    --root PATH             filesystem root for the hierarchy")
+        print("    --max-children N        cap children per node (default 200)")
+        print("    --top-k-edges N         per-symbol outbound edges in inspector (default 12)")
+        print("    --label NAME            project label in header")
+        print("  extract <path>          headless full extraction (AST + semantic LLM) for CI/scripts")
+        print("    --backend B             gemini|kimi|claude|openai|ollama (default: whichever API key is set)")
+        print("    --model M               override backend default model")
+        print("    --max-workers N         AST extraction subprocess count (default: cpu_count)")
+        print("    --token-budget N        per-chunk token cap for semantic extraction (default: 60000)")
+        print("    --max-concurrency N     parallel semantic chunks in flight (default: 4; set 1 for local LLMs)")
+        print("    --api-timeout S         per-request timeout in seconds for the LLM client (default: 600)")
+        print("    --out DIR               output dir (default: <path>); writes <DIR>/graphify-out/")
+        print("    --google-workspace      export .gdoc/.gsheet/.gslides shortcuts via gws before extraction")
+        print("    --no-cluster            skip clustering, write raw extraction only")
+        print("    --global                also merge the resulting graph into the global graph")
+        print("    --as <tag>              repo tag for --global (default: target directory name)")
+        print("  global add <graph.json>  add/update a project graph in the global graph (~/.graphify/global-graph.json)")
+        print("    --as <tag>               repo tag (default: parent directory name)")
+        print("  global remove <tag>      remove a repo's nodes from the global graph")
+        print("  global list              list repos in the global graph")
+        print("  global path              print path to the global graph file")
+        print("  benchmark [graph.json]  measure token reduction vs naive full-corpus approach")
+        print("  export callflow-html    emit Mermaid-based architecture/call-flow HTML")
+        print("  hook install            install post-commit/post-checkout git hooks")
+        print("  hook uninstall          remove git hooks")
+        print("  hook status             check if git hooks are installed")
+        print("  claude install          write cgraph section to CLAUDE.md + PreToolUse hook (Claude Code)")
+        print("  claude uninstall        remove cgraph section from CLAUDE.md + PreToolUse hook")
+        print("  codex install           write cgraph section to AGENTS.md (Codex)")
+        print("  codex uninstall         remove cgraph section from AGENTS.md")
+        print()
+        return
+
+    cmd = sys.argv[1]
+
+    # Universal help guard: -h/--help/-? anywhere after the command shows help
+    # and stops to prevent flags from silently triggering mutating subcommands.
+    # Exempt: free-text commands (user string may contain these tokens), and
+    # "install"/"uninstall" which have their own per-subcommand help handlers.
+    _FREE_TEXT_CMDS = {"query", "explain", "path", "save-result", "install", "uninstall"}
+    if cmd not in _FREE_TEXT_CMDS and any(a in {"-h", "--help", "-?"} for a in sys.argv[2:]):
+        print(f"Run 'graphify --help' for full usage.")
+        return
+
+    if cmd == "install":
+        default_platform = "claude"
+        selected_platform: str | None = None
+        args = sys.argv[2:]
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            if arg in ("-h", "--help"):
+                _print_install_usage()
+                return
+            if arg.startswith("--platform="):
+                candidate = arg.split("=", 1)[1]
+                if selected_platform and selected_platform != candidate:
+                    print("error: specify install platform only once", file=sys.stderr)
+                    sys.exit(1)
+                selected_platform = candidate
+                i += 1
+            elif arg == "--platform":
+                if i + 1 >= len(args):
+                    print("error: --platform requires a value", file=sys.stderr)
+                    sys.exit(1)
+                candidate = args[i + 1]
+                if selected_platform and selected_platform != candidate:
+                    print("error: specify install platform only once", file=sys.stderr)
+                    sys.exit(1)
+                selected_platform = candidate
+                i += 2
+            elif arg.startswith("-"):
+                print(f"error: unknown install option '{arg}'", file=sys.stderr)
+                sys.exit(1)
+            else:
+                if selected_platform and selected_platform != arg:
+                    print("error: specify install platform only once", file=sys.stderr)
+                    sys.exit(1)
+                selected_platform = arg
+                i += 1
+        chosen_platform = selected_platform or default_platform
+        install(platform=chosen_platform)
+    elif cmd == "uninstall":
+        purge = "--purge" in sys.argv[2:]
+        uninstall_all(purge=purge)
+    elif cmd == "claude":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            claude_install()
+        elif subcmd == "uninstall":
+            claude_uninstall()
+        else:
+            print("Usage: graphify claude [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "codex":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            _agents_install(Path("."))
+        elif subcmd == "uninstall":
+            _agents_uninstall(Path("."))
+            _uninstall_codex_hook(Path("."))
+        else:
+            print("Usage: graphify codex [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "hook":
+        from graphify.hooks import install as hook_install, uninstall as hook_uninstall, status as hook_status
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            print(hook_install(Path(".")))
+        elif subcmd == "uninstall":
+            print(hook_uninstall(Path(".")))
+        elif subcmd == "status":
+            print(hook_status(Path(".")))
+        else:
+            print("Usage: graphify hook [install|uninstall|status]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "query":
+        if len(sys.argv) < 3:
+            print("Usage: graphify query \"<question>\" [--dfs] [--context C] [--budget N] [--graph path]", file=sys.stderr)
+            sys.exit(1)
+        from graphify.serve import _query_graph_text
+        from graphify.security import sanitize_label
+        from networkx.readwrite import json_graph
+        question = sys.argv[2]
+        use_dfs = "--dfs" in sys.argv
+        budget = 2000
+        graph_path = _default_graph_path()
+        context_filters: list[str] = []
+        args = sys.argv[3:]
+        i = 0
+        while i < len(args):
+            if args[i] == "--budget" and i + 1 < len(args):
+                try:
+                    budget = int(args[i + 1])
+                except ValueError:
+                    print(f"error: --budget must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 2
+            elif args[i].startswith("--budget="):
+                try:
+                    budget = int(args[i].split("=", 1)[1])
+                except ValueError:
+                    print(f"error: --budget must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 1
+            elif args[i] == "--context" and i + 1 < len(args):
+                context_filters.append(args[i + 1])
+                i += 2
+            elif args[i].startswith("--context="):
+                context_filters.append(args[i].split("=", 1)[1])
+                i += 1
+            elif args[i] == "--graph" and i + 1 < len(args):
+                graph_path = args[i + 1]; i += 2
+            else:
+                i += 1
+        gp = Path(graph_path).resolve()
+        if not gp.exists():
+            print(f"error: graph file not found: {gp}", file=sys.stderr)
+            sys.exit(1)
+        if not gp.suffix == ".json":
+            print(f"error: graph file must be a .json file", file=sys.stderr)
+            sys.exit(1)
+        try:
+            import json as _json
+            import networkx as _nx
+            _raw = _json.loads(gp.read_text(encoding="utf-8"))
+            if "links" not in _raw and "edges" in _raw:
+                _raw = dict(_raw, links=_raw["edges"])
+            try:
+                G = json_graph.node_link_graph(_raw, edges="links")
+            except TypeError:
+                G = json_graph.node_link_graph(_raw)
+        except Exception as exc:
+            print(f"error: could not load graph: {exc}", file=sys.stderr)
+            sys.exit(1)
+        print(
+            _query_graph_text(
+                G,
+                question,
+                mode="dfs" if use_dfs else "bfs",
+                depth=2,
+                token_budget=budget,
+                context_filters=context_filters,
+            )
+        )
+    elif cmd == "save-result":
+        # graphify save-result --question Q --answer A --type T [--nodes N1 N2 ...]
+        import argparse as _ap
+        p = _ap.ArgumentParser(prog="graphify save-result")
+        p.add_argument("--question", required=True)
+        p.add_argument("--answer", required=True)
+        p.add_argument("--type", dest="query_type", default="query")
+        p.add_argument("--nodes", nargs="*", default=[])
+        p.add_argument("--memory-dir", default="graphify-out/memory")
+        opts = p.parse_args(sys.argv[2:])
+        from graphify.ingest import save_query_result as _sqr
+        out = _sqr(
+            question=opts.question,
+            answer=opts.answer,
+            memory_dir=Path(opts.memory_dir),
+            query_type=opts.query_type,
+            source_nodes=opts.nodes or None,
+        )
+        print(f"Saved to {out}")
+    elif cmd == "path":
+        if len(sys.argv) < 4:
+            print("Usage: graphify path \"<source>\" \"<target>\" [--graph path]", file=sys.stderr)
+            sys.exit(1)
+        from graphify.serve import _score_nodes
+        from networkx.readwrite import json_graph
+        import networkx as _nx
+        source_label = sys.argv[2]
+        target_label = sys.argv[3]
+        graph_path = _default_graph_path()
+        args = sys.argv[4:]
+        for i, a in enumerate(args):
+            if a == "--graph" and i + 1 < len(args):
+                graph_path = args[i + 1]
+        gp = Path(graph_path).resolve()
+        if not gp.exists():
+            print(f"error: graph file not found: {gp}", file=sys.stderr)
+            sys.exit(1)
+        _raw = json.loads(gp.read_text(encoding="utf-8"))
+        if "links" not in _raw and "edges" in _raw:
+            _raw = dict(_raw, links=_raw["edges"])
+        # Force directed so the renderer can recover stored caller→callee direction.
+        _raw = {**_raw, "directed": True}
+        try:
+            G = json_graph.node_link_graph(_raw, edges="links")
+        except TypeError:
+            G = json_graph.node_link_graph(_raw)
+        src_scored = _score_nodes(G, [t.lower() for t in source_label.split()])
+        tgt_scored = _score_nodes(G, [t.lower() for t in target_label.split()])
+        if not src_scored:
+            print(f"No node matching '{source_label}' found.", file=sys.stderr)
+            sys.exit(1)
+        if not tgt_scored:
+            print(f"No node matching '{target_label}' found.", file=sys.stderr)
+            sys.exit(1)
+        src_nid, tgt_nid = src_scored[0][1], tgt_scored[0][1]
+        # Ambiguity guard: when both queries resolve to the same node, the
+        # shortest path is trivially zero hops, which is almost never what the
+        # caller wanted (see bug #828).
+        if src_nid == tgt_nid:
+            print(
+                f"'{source_label}' and '{target_label}' both resolved to the same "
+                f"node '{src_nid}'. Use a more specific label or the exact node ID.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        for _name, _scored in (("source", src_scored), ("target", tgt_scored)):
+            if len(_scored) >= 2:
+                _top, _runner = _scored[0][0], _scored[1][0]
+                if _top > 0 and (_top - _runner) / _top < 0.10:
+                    print(
+                        f"warning: {_name} match was ambiguous "
+                        f"(top score {_top:g}, runner-up {_runner:g})",
+                        file=sys.stderr,
+                    )
+        try:
+            path_nodes = _nx.shortest_path(G.to_undirected(as_view=True), src_nid, tgt_nid)
+        except (_nx.NetworkXNoPath, _nx.NodeNotFound):
+            print(f"No path found between '{source_label}' and '{target_label}'.")
+            sys.exit(0)
+        hops = len(path_nodes) - 1
+        segments = []
+        from graphify.build import edge_data
+        for i in range(len(path_nodes) - 1):
+            u, v = path_nodes[i], path_nodes[i + 1]
+            # Check which direction the stored edge points.
+            if G.has_edge(u, v):
+                edata = edge_data(G, u, v)
+                forward = True
+            else:
+                edata = edge_data(G, v, u)
+                forward = False
+            rel = edata.get("relation", "")
+            conf = edata.get("confidence", "")
+            conf_str = f" [{conf}]" if conf else ""
+            if i == 0:
+                segments.append(G.nodes[u].get("label", u))
+            if forward:
+                segments.append(f"--{rel}{conf_str}--> {G.nodes[v].get('label', v)}")
+            else:
+                segments.append(f"<--{rel}{conf_str}-- {G.nodes[v].get('label', v)}")
+        print(f"Shortest path ({hops} hops):\n  " + " ".join(segments))
+
+    elif cmd == "explain":
+        if len(sys.argv) < 3:
+            print("Usage: graphify explain \"<node>\" [--graph path]", file=sys.stderr)
+            sys.exit(1)
+        from graphify.serve import _find_node
+        from networkx.readwrite import json_graph
+        label = sys.argv[2]
+        graph_path = _default_graph_path()
+        args = sys.argv[3:]
+        for i, a in enumerate(args):
+            if a == "--graph" and i + 1 < len(args):
+                graph_path = args[i + 1]
+        gp = Path(graph_path).resolve()
+        if not gp.exists():
+            print(f"error: graph file not found: {gp}", file=sys.stderr)
+            sys.exit(1)
+        _raw = json.loads(gp.read_text(encoding="utf-8"))
+        if "links" not in _raw and "edges" in _raw:
+            _raw = dict(_raw, links=_raw["edges"])
+        # Force directed so the renderer can recover stored caller→callee direction.
+        _raw = {**_raw, "directed": True}
+        try:
+            G = json_graph.node_link_graph(_raw, edges="links")
+        except TypeError:
+            G = json_graph.node_link_graph(_raw)
+        matches = _find_node(G, label)
+        if not matches:
+            print(f"No node matching '{label}' found.")
+            sys.exit(0)
+        nid = matches[0]
+        d = G.nodes[nid]
+        print(f"Node: {d.get('label', nid)}")
+        print(f"  ID:        {nid}")
+        print(f"  Source:    {d.get('source_file', '')} {d.get('source_location', '')}".rstrip())
+        print(f"  Type:      {d.get('file_type', '')}")
+        print(f"  Community: {d.get('community', '')}")
+        print(f"  Degree:    {G.degree(nid)}")
+        from graphify.build import edge_data
+        connections: list[tuple[str, str, dict]] = []  # (direction, neighbor_id, edge_data)
+        for nb in G.successors(nid):
+            connections.append(("out", nb, edge_data(G, nid, nb)))
+        for nb in G.predecessors(nid):
+            connections.append(("in", nb, edge_data(G, nb, nid)))
+        if connections:
+            print(f"\nConnections ({len(connections)}):")
+            connections.sort(key=lambda c: G.degree(c[1]), reverse=True)
+            for direction, nb, edata in connections[:20]:
+                rel = edata.get("relation", "")
+                conf = edata.get("confidence", "")
+                arrow = "-->" if direction == "out" else "<--"
+                print(f"  {arrow} {G.nodes[nb].get('label', nb)} [{rel}] [{conf}]")
+            if len(connections) > 20:
+                print(f"  ... and {len(connections) - 20} more")
+
+    elif cmd == "add":
+        if len(sys.argv) < 3:
+            print("Usage: graphify add <url> [--author Name] [--contributor Name] [--dir ./raw]", file=sys.stderr)
+            sys.exit(1)
+        from graphify.ingest import ingest as _ingest
+        url = sys.argv[2]
+        author: str | None = None
+        contributor: str | None = None
+        target_dir = Path("raw")
+        args = sys.argv[3:]
+        i = 0
+        while i < len(args):
+            if args[i] == "--author" and i + 1 < len(args):
+                author = args[i + 1]; i += 2
+            elif args[i] == "--contributor" and i + 1 < len(args):
+                contributor = args[i + 1]; i += 2
+            elif args[i] == "--dir" and i + 1 < len(args):
+                target_dir = Path(args[i + 1]); i += 2
+            else:
+                i += 1
+        try:
+            saved = _ingest(url, target_dir, author=author, contributor=contributor)
+            print(f"Saved to {saved}")
+            print("Run /cgraph --update in your AI assistant to update the graph.")
+        except Exception as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "watch":
+        watch_path = Path(sys.argv[2]) if len(sys.argv) > 2 else Path(".")
+        if not watch_path.exists():
+            print(f"error: path not found: {watch_path}", file=sys.stderr)
+            sys.exit(1)
+        from graphify.watch import watch as _watch
+        try:
+            _watch(watch_path)
+        except ImportError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "cluster-only":
+        # Mirror the tree/export arg-parsing pattern: walk argv so flags and
+        # the optional positional path can appear in any order (#724).
+        no_viz = "--no-viz" in sys.argv
+        _min_cs_arg = next((a for a in sys.argv if a.startswith("--min-community-size=")), None)
+        min_community_size = int(_min_cs_arg.split("=")[1]) if _min_cs_arg else 3
+        args = sys.argv[2:]
+        watch_path: Path | None = None
+        graph_override: Path | None = None
+        i_arg = 0
+        while i_arg < len(args):
+            a = args[i_arg]
+            if a == "--graph" and i_arg + 1 < len(args):
+                graph_override = Path(args[i_arg + 1]); i_arg += 2
+            elif a == "--no-viz" or a.startswith("--min-community-size="):
+                i_arg += 1
+            elif a.startswith("--"):
+                i_arg += 1
+            elif watch_path is None:
+                watch_path = Path(a); i_arg += 1
+            else:
+                i_arg += 1
+        if watch_path is None:
+            watch_path = Path(".")
+        graph_json = graph_override if graph_override is not None else watch_path / "graphify-out" / "graph.json"
+        if not graph_json.exists():
+            print(f"error: no graph found at {graph_json} — run /cgraph first", file=sys.stderr)
+            sys.exit(1)
+        from networkx.readwrite import json_graph as _jg
+        from graphify.build import build_from_json
+        from graphify.cluster import cluster, score_all
+        from graphify.analyze import god_nodes, surprising_connections, suggest_questions
+        from graphify.report import generate
+        from graphify.export import to_json, to_html
+        print("Loading existing graph...")
+        _raw = json.loads(graph_json.read_text(encoding="utf-8"))
+        _directed = bool(_raw.get("directed", False))
+        G = build_from_json(_raw, directed=_directed)
+        print(f"Graph: {G.number_of_nodes()} nodes, {G.number_of_edges()} edges")
+        print("Re-clustering...")
+        communities = cluster(G)
+        cohesion = score_all(G, communities)
+        gods = god_nodes(G)
+        surprises = surprising_connections(G, communities)
+        out = watch_path / "graphify-out"
+        labels_path = out / ".graphify_labels.json"
+        if labels_path.exists():
+            try:
+                labels = {int(k): v for k, v in json.loads(labels_path.read_text(encoding="utf-8")).items()}
+            except Exception:
+                labels = {cid: f"Community {cid}" for cid in communities}
+        else:
+            labels = {cid: f"Community {cid}" for cid in communities}
+        questions = suggest_questions(G, communities, labels)
+        tokens = {"input": 0, "output": 0}
+        from graphify.export import _git_head as _gh
+        _commit = _gh()
+        report = generate(G, communities, cohesion, labels, gods, surprises,
+                          {"warning": "cluster-only mode — file stats not available"},
+                          tokens, str(watch_path), suggested_questions=questions,
+                          min_community_size=min_community_size, built_at_commit=_commit)
+        (out / "GRAPH_REPORT.md").write_text(report, encoding="utf-8")
+        to_json(G, communities, str(out / "graph.json"))
+        labels_path.write_text(json.dumps({str(k): v for k, v in labels.items()}, ensure_ascii=False), encoding="utf-8")
+
+        # Mirror watch.py pattern: gate to_html so core outputs (graph.json +
+        # GRAPH_REPORT.md) always land. Honor --no-viz explicitly; otherwise
+        # fall back to ValueError handling so an oversized graph doesn't crash
+        # the CLI mid-write and leave a stale graph.html on disk.
+        html_target = out / "graph.html"
+        if no_viz:
+            if html_target.exists():
+                html_target.unlink()
+            print(f"Done — {len(communities)} communities. GRAPH_REPORT.md and graph.json updated (--no-viz; graph.html removed).")
+        else:
+            try:
+                to_html(G, communities, str(html_target), community_labels=labels or None)
+                print(f"Done — {len(communities)} communities. GRAPH_REPORT.md, graph.json and graph.html updated.")
+            except ValueError as viz_err:
+                if html_target.exists():
+                    html_target.unlink()
+                print(f"Skipped graph.html: {viz_err}")
+                print(f"Done — {len(communities)} communities. GRAPH_REPORT.md and graph.json updated.")
+
+    elif cmd == "update":
+        force = os.environ.get("GRAPHIFY_FORCE", "").lower() in ("1", "true", "yes")
+        no_cluster = False
+        args = sys.argv[2:]
+        watch_arg: str | None = None
+        for a in args:
+            if a == "--force":
+                force = True
+                continue
+            if a == "--no-cluster":
+                no_cluster = True
+                continue
+            if a.startswith("-"):
+                print(f"error: unknown update option: {a}", file=sys.stderr)
+                sys.exit(2)
+            if watch_arg is not None:
+                print("error: update accepts at most one path argument", file=sys.stderr)
+                sys.exit(2)
+            watch_arg = a
+
+        if watch_arg is not None:
+            watch_path = Path(watch_arg)
+        else:
+            # Try to recover the scan root saved by the last full build
+            saved = Path(_GRAPHIFY_OUT) / ".graphify_root"
+            if saved.exists():
+                watch_path = Path(saved.read_text(encoding="utf-8").strip())
+            else:
+                watch_path = Path(".")
+        if not watch_path.exists():
+            print(f"error: path not found: {watch_path}", file=sys.stderr)
+            sys.exit(1)
+        from graphify.watch import _rebuild_code
+        print(f"Re-extracting code files in {watch_path} (no LLM needed)...")
+        # Interactive CLI: block on the per-repo lock rather than skip, so the
+        # user sees their explicit `graphify update` complete instead of
+        # exiting silently when a hook-driven rebuild happens to be running.
+        ok = _rebuild_code(watch_path, force=force, no_cluster=no_cluster, block_on_lock=True)
+        if ok:
+            print("Code graph updated. For doc/paper/image changes run /cgraph --update in your AI assistant.")
+            if not (
+                os.environ.get("GEMINI_API_KEY")
+                or os.environ.get("GOOGLE_API_KEY")
+                or os.environ.get("MOONSHOT_API_KEY")
+                or os.environ.get("GRAPHIFY_NO_TIPS")
+            ):
+                print("Tip: set GEMINI_API_KEY or GOOGLE_API_KEY to use Gemini for semantic extraction.")
+        else:
+            print("Nothing to update or rebuild failed — check output above.", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "hook-check":
+        # Codex Desktop rejects hookSpecificOutput.additionalContext on PreToolUse.
+        # Keep this as a cross-platform no-op so installed hooks never break Bash
+        # tool calls. Graph guidance reaches the agent via AGENTS.md / skill instead.
+        sys.exit(0)
+    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 == "tree":
+        # Emit a D3 v7 collapsible-tree HTML view of graph.json:
+        # expand-all / collapse-all / reset-view buttons, multi-line
+        # wrapText labels with separately-coloured name + count,
+        # depth-based palette, click-to-toggle subtree, hover inspector
+        # showing top-K outbound edges per symbol.
+        from typing import Optional as _Opt
+        from graphify.tree_html import write_tree_html, DEFAULT_MAX_CHILDREN
+        graph_path = Path(_GRAPHIFY_OUT) / "graph.json"
+        output_path: "_Opt[Path]" = None
+        root: "_Opt[str]" = None
+        max_children = DEFAULT_MAX_CHILDREN
+        top_k_edges = 0
+        project_label: "_Opt[str]" = None
+        args = sys.argv[2:]
+        i_arg = 0
+        while i_arg < len(args):
+            a = args[i_arg]
+            if a == "--graph" and i_arg + 1 < len(args):
+                graph_path = Path(args[i_arg + 1]); i_arg += 2
+            elif a == "--output" and i_arg + 1 < len(args):
+                output_path = Path(args[i_arg + 1]); i_arg += 2
+            elif a == "--root" and i_arg + 1 < len(args):
+                root = args[i_arg + 1]; i_arg += 2
+            elif a == "--max-children" and i_arg + 1 < len(args):
+                max_children = int(args[i_arg + 1]); i_arg += 2
+            elif a == "--top-k-edges" and i_arg + 1 < len(args):
+                top_k_edges = int(args[i_arg + 1]); i_arg += 2
+            elif a == "--label" and i_arg + 1 < len(args):
+                project_label = args[i_arg + 1]; i_arg += 2
+            elif a in ("-h", "--help"):
+                print("Usage: graphify tree [--graph PATH] [--output HTML]")
+                print("  --graph PATH         path to graph.json (default graphify-out/graph.json)")
+                print("  --output HTML        output path (default graphify-out/GRAPH_TREE.html)")
+                print("  --root PATH          filesystem root (default: longest common dir of all source_files)")
+                print("  --max-children N     cap visible children per node (default 200)")
+                print("  --top-k-edges N      pre-compute top-K outbound edges per symbol (default 12)")
+                print("  --label NAME         project label shown in the page header")
+                return
+            else:
+                i_arg += 1
+        if not graph_path.is_file():
+            print(f"error: graph.json not found at {graph_path}", file=sys.stderr)
+            sys.exit(1)
+        if output_path is None:
+            output_path = graph_path.parent / "GRAPH_TREE.html"
+        out = write_tree_html(
+            graph_path=graph_path, output_path=output_path,
+            root=root, max_children=max_children,
+            top_k_edges=top_k_edges, project_label=project_label,
+        )
+        size_kb = out.stat().st_size / 1024
+        print(f"wrote {out} ({size_kb:.1f} KB)")
+        print(f"open with: xdg-open {out}  (or file://{out.resolve()})")
+        sys.exit(0)
+
+    elif cmd == "merge-driver":
+        # git merge driver for graph.json — takes (base, current, other) and writes
+        # the union of current+other nodes/edges back to current. Exits 1 on
+        # corrupt input so git surfaces the conflict instead of silently
+        # accepting a poisoned merge (see F-005).
+        # Usage: graphify merge-driver %O %A %B  (set in .git/config merge driver)
+        if len(sys.argv) < 5:
+            print("Usage: graphify merge-driver <base> <current> <other>", file=sys.stderr)
+            sys.exit(1)
+        _base_path, _current_path, _other_path = sys.argv[2], sys.argv[3], sys.argv[4]
+        # Hard caps so a malicious or corrupted graph.json cannot exhaust memory
+        # at parse time. 50 MB / 100k nodes are well above any realistic graph
+        # (typical graphs are <5 MB / <50k nodes); anything larger should fail
+        # the merge so a human can investigate.
+        _MERGE_MAX_BYTES = 50 * 1024 * 1024
+        _MERGE_MAX_NODES = 100_000
+        import networkx as _nx
+        from networkx.readwrite import json_graph as _jg
+        def _load_graph(p: str):
+            path_obj = Path(p)
+            try:
+                size = path_obj.stat().st_size
+            except OSError as exc:
+                raise RuntimeError(f"cannot stat {p}: {exc}") from exc
+            if size > _MERGE_MAX_BYTES:
+                raise RuntimeError(
+                    f"graph.json {p} is {size} bytes, exceeds {_MERGE_MAX_BYTES}-byte cap"
+                )
+            data = json.loads(path_obj.read_text(encoding="utf-8"))
+            try:
+                return _jg.node_link_graph(data, edges="links"), data
+            except TypeError:
+                return _jg.node_link_graph(data), data
+        try:
+            G_cur, _ = _load_graph(_current_path)
+            G_oth, _ = _load_graph(_other_path)
+        except Exception as exc:
+            print(f"[graphify merge-driver] error loading graphs: {exc}", file=sys.stderr)
+            sys.exit(1)  # surface the conflict so git doesn't accept a corrupt merge
+        merged = _nx.compose(G_cur, G_oth)
+        if merged.number_of_nodes() > _MERGE_MAX_NODES:
+            print(
+                f"[graphify merge-driver] merged graph has {merged.number_of_nodes()} nodes, "
+                f"exceeds {_MERGE_MAX_NODES}-node cap; aborting merge.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        try:
+            out_data = _jg.node_link_data(merged, edges="links")
+        except TypeError:
+            out_data = _jg.node_link_data(merged)
+        Path(_current_path).write_text(json.dumps(out_data, indent=2), encoding="utf-8")
+        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
+        from graphify.build import prefix_graph_for_global as _prefix
+        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"))
+            # Normalize edges/links key before loading — graphify writes "links"
+            # via node_link_data but older runs may have used "edges" (#738).
+            if "links" not in data and "edges" in data:
+                data = dict(data, links=data["edges"])
+            try:
+                G = _jg.node_link_graph(data, edges="links")
+            except TypeError:
+                G = _jg.node_link_graph(data)
+            graphs.append(G)
+        merged = _nx.Graph()
+        for G, gp in zip(graphs, graph_paths):
+            repo_tag = gp.parent.parent.name  # graphify-out/../ → repo dir name
+            prefixed = _prefix(G, repo_tag)
+            merged = _nx.compose(merged, prefixed)
+        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 == "merge-main-graphs":
+        args = sys.argv[2:]
+        graph_paths: list[Path] = []
+        out_path = Path(_GRAPHIFY_OUT) / "graph-main-merged.json"
+        report_path: Path | None = None
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--out" and i + 1 < len(args):
+                out_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--out="):
+                out_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--report" and i + 1 < len(args):
+                report_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--report="):
+                report_path = Path(a.split("=", 1)[1]); i += 1
+            elif a.startswith("-"):
+                print(f"error: unknown merge-main-graphs option: {a}", file=sys.stderr)
+                sys.exit(1)
+            else:
+                graph_paths.append(Path(a)); i += 1
+        if len(graph_paths) < 2:
+            print(
+                "Usage: graphify merge-main-graphs <graph-main1.json> <graph-main2.json> [...] "
+                "[--out graph-main-merged.json] [--report report.md]",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if report_path is None:
+            report_path = out_path.with_name(out_path.stem + "-report.md")
+        try:
+            from graphify.graph_main_merge import (
+                merge_graph_main_files as _merge_graph_main_files,
+                write_graph_main_merge_report as _write_graph_main_merge_report,
+            )
+            from graphify.graph_main_html import build_graph_main_html as _build_graph_main_html
+
+            stats = _merge_graph_main_files(graph_paths, out_path)
+            _write_graph_main_merge_report(stats.report, report_path)
+            html_path = out_path.with_suffix(".html")
+            _build_graph_main_html(out_path, html_path, title=f"Graph Main Merged - {out_path.stem}")
+        except Exception as exc:
+            print(f"error: merge-main-graphs failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+        print(
+            "Merged graph-main: "
+            f"repos={stats.repo_count}, nodes={stats.nodes}, edges={stats.edges}, "
+            f"cross_edges={stats.cross_edges}, mtop={stats.mtop_links}, rest={stats.rest_links}, "
+            f"hsf_method={stats.hsf_method_links}, hsf_api={stats.hsf_api_links}, metaq={stats.metaq_links}, "
+            f"unresolved_dependencies={stats.unresolved_dependencies}"
+        )
+        print(f"Graph: {out_path}")
+        print(f"HTML: {html_path}")
+        print(f"Report: {report_path}")
+
+    elif cmd == "main-trace":
+        args = sys.argv[2:]
+        graph_path: Path | None = None
+        from_query = ""
+        api_query = ""
+        max_depth = 8
+        include_sources = False
+        prefer_repos: list[str] = []
+        exclude_repos: list[str] = []
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--graph" and i + 1 < len(args):
+                graph_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--graph="):
+                graph_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--from" and i + 1 < len(args):
+                from_query = args[i + 1]; i += 2
+            elif a.startswith("--from="):
+                from_query = a.split("=", 1)[1]; i += 1
+            elif a == "--api" and i + 1 < len(args):
+                api_query = args[i + 1]; i += 2
+            elif a.startswith("--api="):
+                api_query = a.split("=", 1)[1]; i += 1
+            elif a == "--max-depth" and i + 1 < len(args):
+                try:
+                    max_depth = int(args[i + 1])
+                except ValueError:
+                    print("error: --max-depth must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 2
+            elif a.startswith("--max-depth="):
+                try:
+                    max_depth = int(a.split("=", 1)[1])
+                except ValueError:
+                    print("error: --max-depth must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 1
+            elif a == "--sources":
+                include_sources = True; i += 1
+            elif a == "--prefer-repo" and i + 1 < len(args):
+                prefer_repos.append(args[i + 1]); i += 2
+            elif a.startswith("--prefer-repo="):
+                prefer_repos.append(a.split("=", 1)[1]); i += 1
+            elif a == "--exclude-repo" and i + 1 < len(args):
+                exclude_repos.append(args[i + 1]); i += 2
+            elif a.startswith("--exclude-repo="):
+                exclude_repos.append(a.split("=", 1)[1]); i += 1
+            else:
+                print(f"error: unknown main-trace option: {a}", file=sys.stderr)
+                sys.exit(1)
+        if graph_path is None or not from_query:
+            print(
+                "Usage: graphify main-trace --graph graph-main-merged.json --from <node> [--api <api>] [--max-depth N] [--sources] [--prefer-repo R] [--exclude-repo R]",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if not graph_path.exists():
+            print(f"error: graph file not found: {graph_path}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            from graphify.graph_main_trace import trace_graph_main as _trace_graph_main
+
+            print(
+                _trace_graph_main(
+                    graph_path,
+                    from_query=from_query,
+                    api_query=api_query,
+                    max_depth=max_depth,
+                    include_sources=include_sources,
+                    prefer_repos=prefer_repos,
+                    exclude_repos=exclude_repos,
+                )
+            )
+        except Exception as exc:
+            print(f"error: main-trace failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "business-init":
+        args = sys.argv[2:]
+        concept = ""
+        from graphify.business_map import default_business_map_path
+
+        out_path = default_business_map_path()
+        force = False
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--concept" and i + 1 < len(args):
+                concept = args[i + 1]; i += 2
+            elif a.startswith("--concept="):
+                concept = a.split("=", 1)[1]; i += 1
+            elif a == "--out" and i + 1 < len(args):
+                out_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--out="):
+                out_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--force":
+                force = True; i += 1
+            else:
+                print(f"error: unknown business-init option: {a}", file=sys.stderr)
+                sys.exit(1)
+        if not concept:
+            print("Usage: graphify business-init --concept <name> [--out graphify-out/business-map.json] [--force]", file=sys.stderr)
+            sys.exit(1)
+        try:
+            from graphify.business_map import init_business_map
+
+            data = init_business_map(concept, out_path, force=force)
+            print(f"Business map written: {out_path}")
+            print(f"Concepts: {len(data.get('concepts', []))}")
+        except Exception as exc:
+            print(f"error: business-init failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "business-show":
+        args = sys.argv[2:]
+        from graphify.business_map import default_business_map_path
+
+        map_path = default_business_map_path()
+        concept = ""
+        scenario = ""
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--map" and i + 1 < len(args):
+                map_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--map="):
+                map_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--concept" and i + 1 < len(args):
+                concept = args[i + 1]; i += 2
+            elif a.startswith("--concept="):
+                concept = a.split("=", 1)[1]; i += 1
+            elif a == "--scenario" and i + 1 < len(args):
+                scenario = args[i + 1]; i += 2
+            elif a.startswith("--scenario="):
+                scenario = a.split("=", 1)[1]; i += 1
+            else:
+                print(f"error: unknown business-show option: {a}", file=sys.stderr)
+                sys.exit(1)
+        if not map_path.exists():
+            print(f"error: business map not found: {map_path}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            from graphify.business_map import format_business_show, load_business_map
+
+            print(format_business_show(load_business_map(map_path), concept_query=concept, scenario_query=scenario))
+        except Exception as exc:
+            print(f"error: business-show failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "business-query":
+        args = sys.argv[2:]
+        from graphify.business_map import default_business_graph_path, default_business_map_path
+
+        map_path = default_business_map_path()
+        graph_path: Path | None = None
+        question = ""
+        max_depth: int | None = None
+        include_sources = False
+        run_trace = False
+        output_format = "text"
+        top_k = 5
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--map" and i + 1 < len(args):
+                map_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--map="):
+                map_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--graph" and i + 1 < len(args):
+                graph_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--graph="):
+                graph_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--max-depth" and i + 1 < len(args):
+                try:
+                    max_depth = int(args[i + 1])
+                except ValueError:
+                    print("error: --max-depth must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 2
+            elif a.startswith("--max-depth="):
+                try:
+                    max_depth = int(a.split("=", 1)[1])
+                except ValueError:
+                    print("error: --max-depth must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 1
+            elif a == "--top-k" and i + 1 < len(args):
+                try:
+                    top_k = int(args[i + 1])
+                except ValueError:
+                    print("error: --top-k must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 2
+            elif a.startswith("--top-k="):
+                try:
+                    top_k = int(a.split("=", 1)[1])
+                except ValueError:
+                    print("error: --top-k must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 1
+            elif a == "--format" and i + 1 < len(args):
+                output_format = args[i + 1]; i += 2
+            elif a.startswith("--format="):
+                output_format = a.split("=", 1)[1]; i += 1
+            elif a == "--sources":
+                include_sources = True; i += 1
+            elif a == "--trace":
+                run_trace = True; i += 1
+            elif a.startswith("-"):
+                print(f"error: unknown business-query option: {a}", file=sys.stderr)
+                sys.exit(1)
+            else:
+                question = a if not question else f"{question} {a}"
+                i += 1
+        if not question:
+            print(
+                "Usage: graphify business-query \"question\" [--map <business-map.json>] [--graph <graph-main.json>] [--trace] [--sources] [--format json|text]",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if output_format not in {"json", "text"}:
+            print("error: --format must be json or text", file=sys.stderr)
+            sys.exit(1)
+        if not map_path.exists():
+            print(f"error: business map not found: {map_path}", file=sys.stderr)
+            sys.exit(1)
+        if graph_path is None:
+            graph_path = default_business_graph_path(map_path)
+        if graph_path is not None and not graph_path.exists():
+            print(f"error: graph file not found: {graph_path}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            from graphify.business_map import query_business
+
+            result = query_business(
+                map_path=map_path,
+                graph_path=graph_path,
+                query=question,
+                top_k=top_k,
+                max_depth=max_depth,
+                include_sources=include_sources,
+                run_trace=run_trace,
+            )
+            if output_format == "json":
+                print(json.dumps(result, ensure_ascii=False, indent=2))
+            else:
+                match = result.get("match", {})
+                best = match.get("best")
+                print(f"Business query: {result.get('query')}")
+                print(f"Map: {result.get('map')}")
+                print(f"Graph: {result.get('graph') or '-'}")
+                print(f"Match: {match.get('status')} scope={match.get('scope') or '-'}")
+                if best:
+                    print(
+                        "Best: "
+                        f"{best.get('concept')}"
+                        + (f" / {best.get('scenario')}" if best.get("scenario") else "")
+                        + (f" / {best.get('flow')}" if best.get("flow") else "")
+                        + f" score={best.get('score')}"
+                    )
+                    if best.get("summary"):
+                        print(f"Summary: {best.get('summary')}")
+                if match.get("top_matches"):
+                    print("Top matches:")
+                    for cand in match.get("top_matches", []):
+                        print(
+                            "- "
+                            f"{cand.get('type')} {cand.get('concept')}"
+                            + (f" / {cand.get('scenario')}" if cand.get("scenario") else "")
+                            + (f" / {cand.get('flow')}" if cand.get("flow") else "")
+                            + f" score={cand.get('score')}"
+                        )
+                if result.get("graph_matches"):
+                    print("Graph matches:")
+                    for cand in result.get("graph_matches", [])[:10]:
+                        print(f"- {cand.get('kind')} {cand.get('label')} repo={cand.get('repo') or '-'} score={cand.get('score')}")
+                print(f"Next action: {result.get('next_action')}")
+                if result.get("trace"):
+                    print("")
+                    print(result.get("trace"))
+        except Exception as exc:
+            print(f"error: business-query failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "business-lint":
+        args = sys.argv[2:]
+        from graphify.business_map import default_business_map_path
+
+        map_path = default_business_map_path()
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--map" and i + 1 < len(args):
+                map_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--map="):
+                map_path = Path(a.split("=", 1)[1]); i += 1
+            else:
+                print(f"error: unknown business-lint option: {a}", file=sys.stderr)
+                sys.exit(1)
+        if not map_path.exists():
+            print(f"error: business map not found: {map_path}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            from graphify.business_map import format_lint_result, lint_business_map
+
+            result = lint_business_map(map_path)
+            print(format_lint_result(result))
+            if not result.ok:
+                sys.exit(2)
+        except Exception as exc:
+            print(f"error: business-lint failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "business-validate":
+        args = sys.argv[2:]
+        from graphify.business_map import default_business_graph_path, default_business_map_path
+
+        map_path = default_business_map_path()
+        graph_path: Path | None = None
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--map" and i + 1 < len(args):
+                map_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--map="):
+                map_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--graph" and i + 1 < len(args):
+                graph_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--graph="):
+                graph_path = Path(a.split("=", 1)[1]); i += 1
+            else:
+                print(f"error: unknown business-validate option: {a}", file=sys.stderr)
+                sys.exit(1)
+        if not map_path.exists():
+            print(f"error: business map not found: {map_path}", file=sys.stderr)
+            sys.exit(1)
+        if graph_path is None:
+            graph_path = default_business_graph_path(map_path)
+        if graph_path is None:
+            print("Usage: graphify business-validate [--map <business-map.json>] [--graph <graph-main.json>]", file=sys.stderr)
+            sys.exit(1)
+        if not graph_path.exists():
+            print(f"error: graph file not found: {graph_path}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            from graphify.business_map import format_validation_result, validate_business_map
+
+            result = validate_business_map(map_path, graph_path)
+            print(format_validation_result(result))
+            if not result.ok:
+                sys.exit(2)
+        except Exception as exc:
+            print(f"error: business-validate failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "business-trace":
+        args = sys.argv[2:]
+        from graphify.business_map import default_business_graph_path, default_business_map_path
+
+        map_path = default_business_map_path()
+        graph_path: Path | None = None
+        concept = ""
+        scenario = ""
+        flow = ""
+        max_depth: int | None = None
+        include_sources = False
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--map" and i + 1 < len(args):
+                map_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--map="):
+                map_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--graph" and i + 1 < len(args):
+                graph_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--graph="):
+                graph_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--concept" and i + 1 < len(args):
+                concept = args[i + 1]; i += 2
+            elif a.startswith("--concept="):
+                concept = a.split("=", 1)[1]; i += 1
+            elif a == "--scenario" and i + 1 < len(args):
+                scenario = args[i + 1]; i += 2
+            elif a.startswith("--scenario="):
+                scenario = a.split("=", 1)[1]; i += 1
+            elif a == "--flow" and i + 1 < len(args):
+                flow = args[i + 1]; i += 2
+            elif a.startswith("--flow="):
+                flow = a.split("=", 1)[1]; i += 1
+            elif a == "--max-depth" and i + 1 < len(args):
+                try:
+                    max_depth = int(args[i + 1])
+                except ValueError:
+                    print("error: --max-depth must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 2
+            elif a.startswith("--max-depth="):
+                try:
+                    max_depth = int(a.split("=", 1)[1])
+                except ValueError:
+                    print("error: --max-depth must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 1
+            elif a == "--sources":
+                include_sources = True; i += 1
+            else:
+                print(f"error: unknown business-trace option: {a}", file=sys.stderr)
+                sys.exit(1)
+        if not concept:
+            print(
+                "Usage: graphify business-trace [--map <business-map.json>] [--graph <graph-main.json>] --concept <name> [--scenario <name>] [--flow <name>] [--max-depth N] [--sources]",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if not map_path.exists():
+            print(f"error: business map not found: {map_path}", file=sys.stderr)
+            sys.exit(1)
+        if graph_path is None:
+            graph_path = default_business_graph_path(map_path)
+        if graph_path is None:
+            print(
+                "Usage: graphify business-trace [--map <business-map.json>] [--graph <graph-main.json>] --concept <name> [--scenario <name>] [--flow <name>] [--max-depth N] [--sources]",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if not graph_path.exists():
+            print(f"error: graph file not found: {graph_path}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            from graphify.business_map import trace_business
+
+            print(
+                trace_business(
+                    map_path=map_path,
+                    graph_path=graph_path,
+                    concept_query=concept,
+                    scenario_query=scenario,
+                    flow_query=flow,
+                    max_depth=max_depth,
+                    include_sources=include_sources,
+                )
+            )
+        except Exception as exc:
+            print(f"error: business-trace failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+
+    elif cmd == "bridge-mtop":
+        args = sys.argv[2:]
+        repos_root: Path | None = None
+        graph_in = Path(_GRAPHIFY_OUT) / "graph.json"
+        graph_out = Path(_GRAPHIFY_OUT) / "graph-bridge-mtop.json"
+        report_path = Path(_GRAPHIFY_OUT) / "bridge-mtop-report.json"
+        max_file_size = 1_000_000
+        repo_tags: list[str] | None = None
+        thin_out: Path | None = None
+        thin_hops = 1
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--repos-root" and i + 1 < len(args):
+                repos_root = Path(args[i + 1]); i += 2
+            elif a.startswith("--repos-root="):
+                repos_root = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--graph-in" and i + 1 < len(args):
+                graph_in = Path(args[i + 1]); i += 2
+            elif a.startswith("--graph-in="):
+                graph_in = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--graph-out" and i + 1 < len(args):
+                graph_out = Path(args[i + 1]); i += 2
+            elif a.startswith("--graph-out="):
+                graph_out = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--report" and i + 1 < len(args):
+                report_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--report="):
+                report_path = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--max-file-size" and i + 1 < len(args):
+                try:
+                    max_file_size = int(args[i + 1])
+                except ValueError:
+                    print("error: --max-file-size must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 2
+            elif a.startswith("--max-file-size="):
+                try:
+                    max_file_size = int(a.split("=", 1)[1])
+                except ValueError:
+                    print("error: --max-file-size must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 1
+            elif a == "--repos" and i + 1 < len(args):
+                repo_tags = [t.strip() for t in args[i + 1].split(",") if t.strip()]
+                i += 2
+            elif a.startswith("--repos="):
+                repo_tags = [t.strip() for t in a.split("=", 1)[1].split(",") if t.strip()]
+                i += 1
+            elif a == "--thin-out" and i + 1 < len(args):
+                thin_out = Path(args[i + 1]); i += 2
+            elif a.startswith("--thin-out="):
+                thin_out = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--thin-hops" and i + 1 < len(args):
+                try:
+                    thin_hops = int(args[i + 1])
+                except ValueError:
+                    print("error: --thin-hops must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 2
+            elif a.startswith("--thin-hops="):
+                try:
+                    thin_hops = int(a.split("=", 1)[1])
+                except ValueError:
+                    print("error: --thin-hops must be an integer", file=sys.stderr)
+                    sys.exit(1)
+                i += 1
+            else:
+                i += 1
+        if repos_root is None:
+            print(
+                "Usage: graphify bridge-mtop --repos-root <path> [--graph-in in.json] "
+                "[--graph-out out.json] [--report report.json] [--max-file-size N] [--repos A,B,C]",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if max_file_size <= 0:
+            print("error: --max-file-size must be > 0", file=sys.stderr)
+            sys.exit(1)
+        if thin_hops < 0:
+            print("error: --thin-hops must be >= 0", file=sys.stderr)
+            sys.exit(1)
+        from graphify.bridge_mtop import bridge_mtop as _bridge_mtop
+        try:
+            stats = _bridge_mtop(
+                graph_in=graph_in,
+                graph_out=graph_out,
+                repos_root=repos_root,
+                report_path=report_path,
+                max_file_size=max_file_size,
+                repo_tags=repo_tags,
+                thin_out_path=thin_out,
+                thin_hops=thin_hops,
+            )
+        except Exception as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            sys.exit(1)
+        print(
+            f"Bridge complete: repos={stats.repos_scanned}, files={stats.files_scanned}, "
+            f"api_nodes+={stats.api_nodes_added}, calls_mtop+={stats.edge_calls_added}, "
+            f"implemented_by+={stats.edge_impl_added}"
+        )
+        print(f"Graph: {graph_out}")
+        print(f"Report: {report_path}")
+        if thin_out is not None:
+            print(f"Thin graph: {thin_out}")
+
+    elif cmd == "main-graph":
+        args = sys.argv[2:]
+        root = Path(".")
+        out_path = Path(_GRAPHIFY_OUT) / "graph-main.json"
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--out" and i + 1 < len(args):
+                out_path = Path(args[i + 1]); i += 2
+            elif a.startswith("--out="):
+                out_path = Path(a.split("=", 1)[1]); i += 1
+            elif a.startswith("-"):
+                print(f"error: unknown main-graph option: {a}", file=sys.stderr)
+                sys.exit(1)
+            else:
+                if root != Path("."):
+                    print("error: main-graph accepts at most one path argument", file=sys.stderr)
+                    sys.exit(1)
+                root = Path(a)
+                i += 1
+        if not root.exists() or not root.is_dir():
+            print(f"error: path not found or not a directory: {root}", file=sys.stderr)
+            sys.exit(1)
+
+        root = root.resolve()
+        java_files = list(root.rglob("*.java"))
+        try:
+            if java_files:
+                from graphify.graph_main_backend import build_graph_main_backend as _build_graph_main_backend
+                from graphify.graph_main_html import build_graph_main_html as _build_graph_main_html
+                stats = _build_graph_main_backend(repo_root=root, out_path=out_path)
+                html_out = out_path.with_suffix(".html")
+                report_out = out_path.with_name("graph-main-report.md")
+                _build_graph_main_html(out_path, html_out, title=f"Graph Main - {root.name}")
+                rep = stats.report or {}
+                m = rep.get("mtop_map_impl", {}) if isinstance(rep, dict) else {}
+                unresolved = m.get("unresolved_apis", []) if isinstance(m, dict) else []
+                lines = []
+                lines.append("# Graph Main Report")
+                lines.append("")
+                lines.append(f"- repo_root: `{rep.get('repo_root', '')}`")
+                lines.append(f"- generated_at: `{rep.get('generated_at', '')}`")
+                lines.append(f"- mode: `{rep.get('mode', '')}`")
+                lines.append(f"- files_scanned: `{rep.get('files_scanned', 0)}`")
+                lines.append(f"- node_count: `{rep.get('node_count', 0)}`")
+                lines.append(f"- edge_count: `{rep.get('edge_count', 0)}`")
+                lines.append("")
+                lines.append("## Node Kind Counts")
+                nk = rep.get("node_kind_counts", {}) if isinstance(rep, dict) else {}
+                if isinstance(nk, dict) and nk:
+                    for k in sorted(nk.keys()):
+                        lines.append(f"- {k}: {nk[k]}")
+                else:
+                    lines.append("- (empty)")
+                lines.append("")
+                lines.append("## Relation Counts")
+                rk = rep.get("relation_counts", {}) if isinstance(rep, dict) else {}
+                if isinstance(rk, dict) and rk:
+                    for k in sorted(rk.keys()):
+                        lines.append(f"- {k}: {rk[k]}")
+                else:
+                    lines.append("- (empty)")
+                lines.append("")
+                lines.append("## MTOP Map Coverage")
+                lines.append(f"- map_source_file: `{m.get('map_source_file', '')}`")
+                lines.append(f"- map_total: `{m.get('map_total', 0)}`")
+                lines.append(f"- map_resolved: `{m.get('map_resolved', 0)}`")
+                lines.append(f"- map_unresolved: `{m.get('map_unresolved', 0)}`")
+                lines.append("")
+                lines.append("## Unresolved MTOP APIs (No In-Repo Implementation)")
+                if unresolved:
+                    lines.append("| api | hsf_interface | hsf_method | source_location | reason |")
+                    lines.append("| --- | --- | --- | --- | --- |")
+                    for x in unresolved:
+                        api = str(x.get("api", "")).replace("|", "\\|")
+                        iface = str(x.get("hsf_interface", "")).replace("|", "\\|")
+                        hm = str(x.get("hsf_method", "")).replace("|", "\\|")
+                        loc = str(x.get("source_location", "")).replace("|", "\\|")
+                        reason = str(x.get("reason", "")).replace("|", "\\|")
+                        lines.append(f"| {api} | {iface} | {hm} | {loc} | {reason} |")
+                else:
+                    lines.append("- (none)")
+                report_out.write_text("\n".join(lines) + "\n", encoding="utf-8")
+                sdk = stats.sdk_detection
+                mode = stats.mode
+                print(
+                    "Main graph complete (backend): "
+                    f"files={stats.files_scanned}, nodes={stats.nodes}, edges={stats.edges}, "
+                    f"mode={mode}, is_sdk_repo={sdk.get('is_sdk_repo')}, "
+                    f"packaging={sdk.get('packaging')}, has_modules={sdk.get('has_modules')}, "
+                    f"entry_signal_score={sdk.get('entry_signal_score')}"
+                )
+                print(
+                    "Node counts: "
+                    f"hsf_method={stats.hsf_method_nodes}, hsf_api={stats.hsf_api_nodes}, "
+                    f"mtop_api={stats.mtop_api_nodes}, rest_api={stats.rest_api_nodes}, "
+                    f"dependency={stats.dependency_nodes}, metaq_producer={stats.metaq_producer_nodes}, "
+                    f"metaq_consumer={stats.metaq_consumer_nodes}"
+                )
+                print(f"HTML: {html_out}")
+                print(f"Report: {report_out}")
+            else:
+                from graphify.graph_main_frontend import build_graph_main_frontend as _build_graph_main_frontend
+                from graphify.graph_main_html import build_graph_main_html as _build_graph_main_html
+                stats = _build_graph_main_frontend(repo_root=root, out_path=out_path)
+                html_out = out_path.with_suffix(".html")
+                report_out = out_path.with_name("graph-main-report.md")
+                _build_graph_main_html(out_path, html_out, title=f"Graph Main - {root.name}")
+                rep = stats.report or {}
+                fd = rep.get("frontend_detection", {}) if isinstance(rep, dict) else {}
+                unresolved = rep.get("unresolved_component_entries", []) if isinstance(rep, dict) else []
+                lines = []
+                lines.append("# Graph Main Report")
+                lines.append("")
+                lines.append(f"- repo_root: `{rep.get('repo_root', '')}`")
+                lines.append(f"- generated_at: `{rep.get('generated_at', '')}`")
+                lines.append(f"- mode: `{rep.get('mode', '')}`")
+                lines.append(f"- files_scanned: `{rep.get('files_scanned', 0)}`")
+                lines.append(f"- node_count: `{rep.get('node_count', 0)}`")
+                lines.append(f"- edge_count: `{rep.get('edge_count', 0)}`")
+                lines.append("")
+                lines.append("## Frontend Detection")
+                lines.append(f"- mode: `{fd.get('mode', '')}`")
+                pmd = fd.get("page_mode_detection", {}) if isinstance(fd, dict) else {}
+                lines.append(f"- page_mode: `{pmd.get('mode', fd.get('mode', ''))}`")
+                lines.append(f"- page_count: `{pmd.get('page_count', 0)}`")
+                lines.append(f"- slc_page_count: `{pmd.get('slc_page_count', 0)}`")
+                lines.append(f"- normal_page_count: `{pmd.get('normal_page_count', 0)}`")
+                slc_pages = pmd.get("slc_pages", []) if isinstance(pmd, dict) else []
+                if slc_pages:
+                    lines.append(f"- slc_pages: `{', '.join(str(x) for x in slc_pages)}`")
+                lines.append(f"- legacy_repo_mode: `{fd.get('legacy_repo_mode', '')}`")
+                lines.append(f"- legacy_slc_signal_score: `{fd.get('slc_signal_score', 0)}`")
+                lines.append(f"- has_manifest: `{fd.get('has_manifest', False)}`")
+                lines.append(f"- manifest_count: `{fd.get('manifest_count', 0)}`")
+                lines.append(f"- has_data_service: `{fd.get('has_data_service', False)}`")
+                lines.append(f"- template_hits: `{fd.get('template_hits', 0)}`")
+                lines.append(f"- component_registry_hits: `{fd.get('component_registry_hits', 0)}`")
+                lines.append("")
+                lines.append("## Node Kind Counts")
+                nk = rep.get("node_kind_counts", {}) if isinstance(rep, dict) else {}
+                if isinstance(nk, dict) and nk:
+                    for k in sorted(nk.keys()):
+                        lines.append(f"- {k}: {nk[k]}")
+                else:
+                    lines.append("- (empty)")
+                lines.append("")
+                lines.append("## Relation Counts")
+                rk = rep.get("relation_counts", {}) if isinstance(rep, dict) else {}
+                if isinstance(rk, dict) and rk:
+                    for k in sorted(rk.keys()):
+                        lines.append(f"- {k}: {rk[k]}")
+                else:
+                    lines.append("- (empty)")
+                lines.append("")
+                lines.append("## Unresolved Component Entries")
+                if unresolved:
+                    lines.append("| page | component_id | reason |")
+                    lines.append("| --- | --- | --- |")
+                    for x in unresolved:
+                        page = str(x.get("page", "")).replace("|", "\\|")
+                        cid = str(x.get("component_id", "")).replace("|", "\\|")
+                        reason = str(x.get("reason", "")).replace("|", "\\|")
+                        lines.append(f"| {page} | {cid} | {reason} |")
+                else:
+                    lines.append("- (none)")
+                report_out.write_text("\n".join(lines) + "\n", encoding="utf-8")
+                print(
+                    "Main graph complete (frontend): "
+                    f"files={stats.files_scanned}, nodes={stats.nodes}, edges={stats.edges}, mode={stats.mode}"
+                )
+                print(
+                    "Node counts: "
+                    f"page={stats.page_nodes}, component={stats.component_nodes}, "
+                    f"mtop_api={stats.mtop_api_nodes}, rest_api={stats.rest_api_nodes}"
+                )
+                print(f"HTML: {html_out}")
+                print(f"Report: {report_out}")
+        except Exception as exc:
+            print(f"error: main-graph failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+        print(f"Graph: {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 == "export":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd not in ("html", "callflow-html", "obsidian", "wiki", "svg", "graphml", "neo4j"):
+            print("Usage: graphify export <format>", file=sys.stderr)
+            print("  html      [--graph PATH] [--labels PATH] [--node-limit N] [--no-viz]", file=sys.stderr)
+            print("  callflow-html [GRAPH|DIR] [--graph PATH] [--labels PATH] [--report PATH] [--sections PATH] [--output HTML]", file=sys.stderr)
+            print("            [--lang auto|zh-CN|en] [--max-sections N] [--diagram-scale N]", file=sys.stderr)
+            print("  obsidian  [--graph PATH] [--labels PATH] [--dir PATH]", file=sys.stderr)
+            print("  wiki      [--graph PATH] [--labels PATH]", file=sys.stderr)
+            print("  svg       [--graph PATH] [--labels PATH]", file=sys.stderr)
+            print("  graphml   [--graph PATH]", file=sys.stderr)
+            print("  neo4j     [--graph PATH] [--push URI] [--user U] [--password P]", file=sys.stderr)
+            print("            (or set NEO4J_PASSWORD instead of --password to keep it off argv)", file=sys.stderr)
+            sys.exit(1)
+
+        # Parse shared args
+        args = sys.argv[3:]
+        graph_path = Path(_GRAPHIFY_OUT) / "graph.json"
+        graph_path_explicit = False
+        labels_path = Path(_GRAPHIFY_OUT) / ".graphify_labels.json"
+        labels_path_explicit = False
+        report_path = Path(_GRAPHIFY_OUT) / "GRAPH_REPORT.md"
+        report_path_explicit = False
+        sections_path: Path | None = None
+        callflow_output: Path | None = None
+        callflow_lang = "auto"
+        callflow_max_sections = 15
+        callflow_diagram_scale = 1.0
+        callflow_max_diagram_nodes = 18
+        callflow_max_diagram_edges = 24
+        analysis_path = Path(_GRAPHIFY_OUT) / ".graphify_analysis.json"
+        node_limit = 5000
+        no_viz = False
+        obsidian_dir = Path(_GRAPHIFY_OUT) / "obsidian"
+        neo4j_uri: str | None = None
+        neo4j_user = "neo4j"
+        # F-031: prefer the NEO4J_PASSWORD env var so the password never
+        # appears on argv (visible in `ps` output / shell history). The
+        # explicit --password flag still overrides it for compatibility.
+        neo4j_password: str | None = os.environ.get("NEO4J_PASSWORD") or None
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--graph" and i + 1 < len(args):
+                graph_path = Path(args[i + 1])
+                graph_path_explicit = True
+                i += 2
+            elif a == "--labels" and i + 1 < len(args):
+                labels_path = Path(args[i + 1])
+                labels_path_explicit = True
+                i += 2
+            elif a == "--report" and i + 1 < len(args):
+                report_path = Path(args[i + 1])
+                report_path_explicit = True
+                i += 2
+            elif a == "--sections" and i + 1 < len(args):
+                sections_path = Path(args[i + 1]); i += 2
+            elif a == "--output" and i + 1 < len(args):
+                callflow_output = Path(args[i + 1]).expanduser()
+                if not callflow_output.is_absolute():
+                    callflow_output = Path.cwd() / callflow_output
+                i += 2
+            elif a == "--lang" and i + 1 < len(args):
+                callflow_lang = args[i + 1]; i += 2
+            elif a == "--max-sections" and i + 1 < len(args):
+                callflow_max_sections = int(args[i + 1]); i += 2
+            elif a == "--diagram-scale" and i + 1 < len(args):
+                callflow_diagram_scale = float(args[i + 1]); i += 2
+            elif a == "--max-diagram-nodes" and i + 1 < len(args):
+                callflow_max_diagram_nodes = int(args[i + 1]); i += 2
+            elif a == "--max-diagram-edges" and i + 1 < len(args):
+                callflow_max_diagram_edges = int(args[i + 1]); i += 2
+            elif a in ("-h", "--help") and subcmd == "callflow-html":
+                print("Usage: graphify export callflow-html [GRAPH|DIR] [--graph PATH] [--labels PATH]")
+                print("  --report PATH          path to GRAPH_REPORT.md")
+                print("  --sections PATH        JSON section definitions")
+                print("  --output HTML          output path (default graphify-out/<project>-callflow.html)")
+                print("  --lang LANG            auto, zh-CN, en, etc. (default auto)")
+                print("  --max-sections N       maximum auto-derived sections (default 15)")
+                print("  --diagram-scale N      Mermaid diagram scale (default 1.0)")
+                print("  --max-diagram-nodes N  representative nodes per section (default 18)")
+                print("  --max-diagram-edges N  representative edges per section (default 24)")
+                sys.exit(0)
+            elif a == "--node-limit" and i + 1 < len(args):
+                node_limit = int(args[i + 1]); i += 2
+            elif a == "--no-viz":
+                no_viz = True; i += 1
+            elif a == "--dir" and i + 1 < len(args):
+                obsidian_dir = Path(args[i + 1]); i += 2
+            elif a == "--push" and i + 1 < len(args):
+                neo4j_uri = args[i + 1]; i += 2
+            elif a == "--user" and i + 1 < len(args):
+                neo4j_user = args[i + 1]; i += 2
+            elif a == "--password" and i + 1 < len(args):
+                neo4j_password = args[i + 1]; i += 2
+            elif subcmd == "callflow-html" and not a.startswith("-") and not graph_path_explicit:
+                candidate = Path(a)
+                if candidate.name == "graph.json" or candidate.suffix.lower() == ".json":
+                    graph_path = candidate
+                elif (candidate / "graph.json").exists():
+                    graph_path = candidate / "graph.json"
+                else:
+                    graph_path = candidate / _GRAPHIFY_OUT / "graph.json"
+                graph_path_explicit = True
+                i += 1
+            else:
+                i += 1
+
+        graph_path = graph_path.expanduser()
+        if graph_path_explicit:
+            graph_out_dir = graph_path.parent
+            if not labels_path_explicit:
+                labels_path = graph_out_dir / ".graphify_labels.json"
+            if not report_path_explicit:
+                report_path = graph_out_dir / "GRAPH_REPORT.md"
+        labels_path = labels_path.expanduser()
+        report_path = report_path.expanduser()
+
+        if not graph_path.exists():
+            print(f"error: graph not found: {graph_path}. Run /cgraph <path> first.", file=sys.stderr)
+            sys.exit(1)
+
+        if subcmd == "callflow-html":
+            from graphify.callflow_html import write_callflow_html as _write_callflow_html
+            out = _write_callflow_html(
+                graph=graph_path,
+                report=report_path,
+                labels=labels_path,
+                sections=sections_path,
+                output=callflow_output,
+                lang=callflow_lang,
+                max_sections=callflow_max_sections,
+                diagram_scale=callflow_diagram_scale,
+                max_diagram_nodes=callflow_max_diagram_nodes,
+                max_diagram_edges=callflow_max_diagram_edges,
+                verbose=True,
+            )
+            print(f"callflow HTML written - open in any browser: {out}")
+            sys.exit(0)
+
+        from networkx.readwrite import json_graph as _jg
+        from graphify.build import build_from_json as _bfj
+
+        _raw = json.loads(graph_path.read_text(encoding="utf-8"))
+        try:
+            G = _jg.node_link_graph(_raw, edges="links")
+        except TypeError:
+            G = _jg.node_link_graph(_raw)
+
+        # Load optional analysis/labels
+        communities: dict[int, list[str]] = {}
+        if analysis_path.exists():
+            _an = json.loads(analysis_path.read_text(encoding="utf-8"))
+            communities = {int(k): v for k, v in _an.get("communities", {}).items()}
+            cohesion: dict[int, float] = {int(k): v for k, v in _an.get("cohesion", {}).items()}
+            gods_data = _an.get("gods", [])
+        else:
+            cohesion = {}
+            gods_data = []
+
+        labels: dict[int, str] = {}
+        if labels_path.exists():
+            labels = {int(k): v for k, v in json.loads(labels_path.read_text(encoding="utf-8")).items()}
+
+        out_dir = graph_path.parent
+
+        if subcmd == "html":
+            from graphify.export import to_html as _to_html
+            if no_viz:
+                html_target = out_dir / "graph.html"
+                if html_target.exists():
+                    html_target.unlink()
+                print("--no-viz: skipped graph.html")
+            else:
+                _to_html(G, communities, str(out_dir / "graph.html"),
+                         community_labels=labels or None, node_limit=node_limit)
+                if G.number_of_nodes() <= node_limit:
+                    print(f"graph.html written - open in any browser, no server needed")
+
+        elif subcmd == "obsidian":
+            from graphify.export import to_obsidian as _to_obsidian, to_canvas as _to_canvas
+            n = _to_obsidian(G, communities, str(obsidian_dir),
+                             community_labels=labels or None, cohesion=cohesion or None)
+            print(f"Obsidian vault: {n} notes in {obsidian_dir}/")
+            _to_canvas(G, communities, str(obsidian_dir / "graph.canvas"),
+                       community_labels=labels or None)
+            print(f"Canvas: {obsidian_dir}/graph.canvas")
+            print(f"Open {obsidian_dir}/ as a vault in Obsidian.")
+
+        elif subcmd == "wiki":
+            from graphify.wiki import to_wiki as _to_wiki
+            from graphify.analyze import god_nodes as _god_nodes
+            if not communities:
+                print(
+                    "error: .graphify_analysis.json is missing or empty — refusing to export wiki to prevent data loss.\n"
+                    "Run `graphify extract .` (or `graphify cluster-only .`) to regenerate community data first.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+            if not gods_data:
+                gods_data = _god_nodes(G)
+            n = _to_wiki(G, communities, str(out_dir / "wiki"),
+                         community_labels=labels or None, cohesion=cohesion or None,
+                         god_nodes_data=gods_data)
+            print(f"Wiki: {n} articles written to {out_dir}/wiki/")
+            print(f"  {out_dir}/wiki/index.md  ->  agent entry point")
+
+        elif subcmd == "svg":
+            from graphify.export import to_svg as _to_svg
+            _to_svg(G, communities, str(out_dir / "graph.svg"),
+                    community_labels=labels or None)
+            print(f"graph.svg written - embeds in Obsidian, Notion, GitHub READMEs")
+
+        elif subcmd == "graphml":
+            from graphify.export import to_graphml as _to_graphml
+            _to_graphml(G, communities, str(out_dir / "graph.graphml"))
+            print(f"graph.graphml written - open in Gephi, yEd, or any GraphML tool")
+
+        elif subcmd == "neo4j":
+            if neo4j_uri:
+                from graphify.export import push_to_neo4j as _push
+                if neo4j_password is None:
+                    print("error: --password required for --push", file=sys.stderr)
+                    sys.exit(1)
+                result = _push(G, uri=neo4j_uri, user=neo4j_user,
+                               password=neo4j_password, communities=communities)
+                print(f"Pushed to Neo4j: {result['nodes']} nodes, {result['edges']} edges")
+            else:
+                from graphify.export import to_cypher as _to_cypher
+                _to_cypher(G, str(out_dir / "cypher.txt"))
+                print(f"cypher.txt written - import with: cypher-shell < {out_dir}/cypher.txt")
+
+    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"
+        # Try to load corpus_words from detect output
+        corpus_words = None
+        detect_path = Path(".graphify_detect.json")
+        if detect_path.exists():
+            try:
+                detect_data = json.loads(detect_path.read_text(encoding="utf-8"))
+                corpus_words = detect_data.get("total_words")
+            except Exception:
+                pass
+        result = run_benchmark(graph_path, corpus_words=corpus_words)
+        print_benchmark(result)
+
+    elif cmd == "global":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        from graphify.global_graph import (
+            global_add as _global_add,
+            global_remove as _global_remove,
+            global_list as _global_list,
+            global_path as _global_path,
+        )
+        if subcmd == "add":
+            # graphify global add <graph.json> [--as <tag>]
+            args = sys.argv[3:]
+            source = None
+            tag = None
+            i = 0
+            while i < len(args):
+                if args[i] == "--as" and i + 1 < len(args):
+                    tag = args[i + 1]; i += 2
+                elif not source:
+                    source = Path(args[i]); i += 1
+                else:
+                    i += 1
+            if not source:
+                print("Usage: graphify global add <graph.json> [--as <repo-tag>]", file=sys.stderr)
+                sys.exit(1)
+            tag = tag or source.parent.parent.name
+            try:
+                result = _global_add(source, tag)
+                if result["skipped"]:
+                    print(f"'{tag}' unchanged since last add — global graph not modified.")
+                else:
+                    print(f"Added '{tag}' to global graph: +{result['nodes_added']} nodes, "
+                          f"-{result['nodes_removed']} pruned. Global: {_global_path()}")
+            except Exception as exc:
+                print(f"error: {exc}", file=sys.stderr); sys.exit(1)
+        elif subcmd == "remove":
+            tag = sys.argv[3] if len(sys.argv) > 3 else ""
+            if not tag:
+                print("Usage: graphify global remove <repo-tag>", file=sys.stderr); sys.exit(1)
+            try:
+                removed = _global_remove(tag)
+                print(f"Removed '{tag}' from global graph ({removed} nodes pruned).")
+            except KeyError as exc:
+                print(f"error: {exc}", file=sys.stderr); sys.exit(1)
+        elif subcmd == "list":
+            repos = _global_list()
+            if not repos:
+                print("Global graph is empty. Use 'graphify global add' to add a project.")
+            else:
+                print(f"Global graph: {_global_path()}")
+                for tag, info in repos.items():
+                    print(f"  {tag}: {info.get('node_count', '?')} nodes, added {info.get('added_at', '?')[:10]}")
+        elif subcmd == "path":
+            print(_global_path())
+        else:
+            print("Usage: graphify global [add|remove|list|path]", file=sys.stderr); sys.exit(1)
+
+    elif cmd == "extract":
+        # Headless full-pipeline extraction for CI / scripts (#698).
+        # Runs detect -> AST extraction on code -> semantic LLM extraction on
+        # docs/papers/images -> merge -> build -> cluster -> write outputs.
+        # Unlike the skill.md path (which runs through Claude Code subagents),
+        # this calls extract_corpus_parallel directly using whichever backend
+        # has an API key set.
+        if len(sys.argv) < 3:
+            print(
+                "Usage: graphify extract <path> [--backend gemini|kimi|claude|openai|ollama] "
+                "[--model M] [--out DIR] [--google-workspace] [--no-cluster] "
+                "[--max-workers N] [--token-budget N] [--max-concurrency N] "
+                "[--api-timeout S]",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        target = Path(sys.argv[2]).resolve()
+        if not target.exists():
+            print(f"error: path not found: {target}", file=sys.stderr)
+            sys.exit(1)
+
+        backend: str | None = None
+        model: str | None = None
+        out_dir: Path | None = None
+        no_cluster = False
+        dedup_llm = False
+        google_workspace = False
+        global_merge = False
+        global_repo_tag: str | None = None
+        # Performance/tuning knobs (issue #792). None means "use library default".
+        cli_max_workers: int | None = None
+        cli_token_budget: int | None = None
+        cli_max_concurrency: int | None = None
+        cli_api_timeout: float | None = None
+
+        def _parse_int(name: str, raw: str) -> int:
+            try:
+                v = int(raw)
+            except ValueError:
+                print(f"error: {name} must be a positive integer (got {raw!r})", file=sys.stderr)
+                sys.exit(2)
+            if v <= 0:
+                print(f"error: {name} must be > 0 (got {v})", file=sys.stderr)
+                sys.exit(2)
+            return v
+
+        def _parse_float(name: str, raw: str) -> float:
+            try:
+                v = float(raw)
+            except ValueError:
+                print(f"error: {name} must be a positive number (got {raw!r})", file=sys.stderr)
+                sys.exit(2)
+            if v <= 0:
+                print(f"error: {name} must be > 0 (got {v})", file=sys.stderr)
+                sys.exit(2)
+            return v
+
+        args = sys.argv[3:]
+        i = 0
+        while i < len(args):
+            a = args[i]
+            if a == "--backend" and i + 1 < len(args):
+                backend = args[i + 1]; i += 2
+            elif a.startswith("--backend="):
+                backend = a.split("=", 1)[1]; i += 1
+            elif a == "--model" and i + 1 < len(args):
+                model = args[i + 1]; i += 2
+            elif a.startswith("--model="):
+                model = a.split("=", 1)[1]; i += 1
+            elif a == "--out" and i + 1 < len(args):
+                out_dir = Path(args[i + 1]); i += 2
+            elif a.startswith("--out="):
+                out_dir = Path(a.split("=", 1)[1]); i += 1
+            elif a == "--no-cluster":
+                no_cluster = True; i += 1
+            elif a == "--dedup-llm":
+                dedup_llm = True; i += 1
+            elif a == "--google-workspace":
+                google_workspace = True; i += 1
+            elif a == "--global":
+                global_merge = True; i += 1
+            elif a == "--as" and i + 1 < len(args):
+                global_repo_tag = args[i + 1]; i += 2
+            elif a == "--max-workers" and i + 1 < len(args):
+                cli_max_workers = _parse_int("--max-workers", args[i + 1]); i += 2
+            elif a.startswith("--max-workers="):
+                cli_max_workers = _parse_int("--max-workers", a.split("=", 1)[1]); i += 1
+            elif a == "--token-budget" and i + 1 < len(args):
+                cli_token_budget = _parse_int("--token-budget", args[i + 1]); i += 2
+            elif a.startswith("--token-budget="):
+                cli_token_budget = _parse_int("--token-budget", a.split("=", 1)[1]); i += 1
+            elif a == "--max-concurrency" and i + 1 < len(args):
+                cli_max_concurrency = _parse_int("--max-concurrency", args[i + 1]); i += 2
+            elif a.startswith("--max-concurrency="):
+                cli_max_concurrency = _parse_int("--max-concurrency", a.split("=", 1)[1]); i += 1
+            elif a == "--api-timeout" and i + 1 < len(args):
+                cli_api_timeout = _parse_float("--api-timeout", args[i + 1]); i += 2
+            elif a.startswith("--api-timeout="):
+                cli_api_timeout = _parse_float("--api-timeout", a.split("=", 1)[1]); i += 1
+            else:
+                i += 1
+
+        # CLI flag wins over env var. Setting GRAPHIFY_API_TIMEOUT here so
+        # _call_openai_compat picks it up without needing a new kwarg path.
+        if cli_api_timeout is not None:
+            os.environ["GRAPHIFY_API_TIMEOUT"] = str(cli_api_timeout)
+        if cli_max_workers is not None:
+            os.environ["GRAPHIFY_MAX_WORKERS"] = str(cli_max_workers)
+
+        # Backend resolution. If user did not pass --backend, sniff env.
+        # If backend was explicitly requested, validate its key is present
+        # and surface a clear error early — don't let extract_corpus_parallel
+        # raise mid-run after we've spent time on AST extraction.
+        from graphify.llm import (
+            BACKENDS as _BACKENDS,
+            detect_backend as _detect_backend,
+            estimate_cost as _estimate_cost,
+            extract_corpus_parallel as _extract_corpus_parallel,
+            _format_backend_env_keys,
+            _get_backend_api_key,
+        )
+        if backend is None:
+            backend = _detect_backend()
+            if backend is None:
+                print(
+                    "error: no LLM API key found. Set GEMINI_API_KEY or GOOGLE_API_KEY "
+                    "(gemini), MOONSHOT_API_KEY (kimi), ANTHROPIC_API_KEY (claude), "
+                    "or OPENAI_API_KEY (openai), or pass --backend.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+        if backend not in _BACKENDS:
+            print(
+                f"error: unknown backend '{backend}'. "
+                f"Available: {', '.join(sorted(_BACKENDS))}",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        if not _get_backend_api_key(backend):
+            # Ollama on a loopback URL ignores auth entirely; don't block
+            # the run just because OLLAMA_API_KEY is unset (issue #792).
+            # extract_files_direct already prints a warning and substitutes
+            # a placeholder key in that case.
+            allow_no_key = False
+            if backend == "ollama":
+                from urllib.parse import urlparse
+                ollama_url = os.environ.get(
+                    "OLLAMA_BASE_URL",
+                    _BACKENDS["ollama"].get("base_url", ""),
+                )
+                try:
+                    host = (urlparse(ollama_url).hostname or "").lower()
+                except Exception:
+                    host = ""
+                allow_no_key = (
+                    host in ("localhost", "127.0.0.1", "::1")
+                    or host.startswith("127.")
+                )
+            elif backend == "bedrock":
+                allow_no_key = bool(
+                    os.environ.get("AWS_PROFILE")
+                    or os.environ.get("AWS_REGION")
+                    or os.environ.get("AWS_DEFAULT_REGION")
+                    or os.environ.get("AWS_ACCESS_KEY_ID")
+                )
+            elif backend == "claude-cli":
+                import shutil as _shutil
+                allow_no_key = _shutil.which("claude") is not None
+                if not allow_no_key:
+                    print(
+                        "error: backend 'claude-cli' requires the `claude` CLI on $PATH "
+                        "(install Claude Code and run `claude` once to authenticate).",
+                        file=sys.stderr,
+                    )
+                    sys.exit(1)
+            if not allow_no_key:
+                print(
+                    f"error: backend '{backend}' requires {_format_backend_env_keys(backend)} to be set.",
+                    file=sys.stderr,
+                )
+                sys.exit(1)
+
+        # Resolve output dir. The user-facing contract is "<out>/graphify-out/"
+        # so a fresh checkout writes graphify-out/ at the project root, matching
+        # the skill.md pipeline.
+        out_root = (out_dir.resolve() if out_dir else target)
+        graphify_out = out_root / "graphify-out"
+        graphify_out.mkdir(parents=True, exist_ok=True)
+
+        from graphify.detect import (
+            detect as _detect,
+            detect_incremental as _detect_incremental,
+            save_manifest as _save_manifest,
+        )
+        manifest_path = graphify_out / "manifest.json"
+        existing_graph_path = graphify_out / "graph.json"
+        incremental_mode = manifest_path.exists() and existing_graph_path.exists()
+
+        if incremental_mode:
+            print(f"[graphify extract] incremental scan of {target}")
+            detection = _detect_incremental(
+                target,
+                manifest_path=str(manifest_path),
+                google_workspace=google_workspace or None,
+            )
+        else:
+            print(f"[graphify extract] scanning {target}")
+            detection = _detect(target, google_workspace=google_workspace or None)
+
+        files_by_type = detection.get("files", {})
+        if incremental_mode:
+            new_by_type = detection.get("new_files", {})
+            code_files = [Path(p) for p in new_by_type.get("code", [])]
+            doc_files = [Path(p) for p in new_by_type.get("document", [])]
+            paper_files = [Path(p) for p in new_by_type.get("paper", [])]
+            image_files = [Path(p) for p in new_by_type.get("image", [])]
+            deleted_files = list(detection.get("deleted_files", []))
+            unchanged_total = sum(len(v) for v in detection.get("unchanged_files", {}).values())
+        else:
+            code_files = [Path(p) for p in files_by_type.get("code", [])]
+            doc_files = [Path(p) for p in files_by_type.get("document", [])]
+            paper_files = [Path(p) for p in files_by_type.get("paper", [])]
+            image_files = [Path(p) for p in files_by_type.get("image", [])]
+            deleted_files = []
+            unchanged_total = 0
+
+        semantic_files = doc_files + paper_files + image_files
+        if incremental_mode:
+            print(
+                f"[graphify extract] {len(code_files)} code, {len(doc_files)} docs, "
+                f"{len(paper_files)} papers, {len(image_files)} images changed; "
+                f"{unchanged_total} unchanged; {len(deleted_files)} deleted"
+            )
+        else:
+            print(
+                f"[graphify extract] found {len(code_files)} code, "
+                f"{len(doc_files)} docs, {len(paper_files)} papers, "
+                f"{len(image_files)} images"
+            )
+
+        # AST extraction on code files. Empty code list (docs-only corpus) is
+        # the issue #698 case — skip cleanly instead of crashing inside extract().
+        ast_result: dict = {"nodes": [], "edges": [], "input_tokens": 0, "output_tokens": 0}
+        if code_files:
+            from graphify.extract import extract as _ast_extract
+            ast_kwargs: dict = {"cache_root": target}
+            if cli_max_workers is not None:
+                ast_kwargs["max_workers"] = cli_max_workers
+            print(f"[graphify extract] AST extraction on {len(code_files)} code files...")
+            try:
+                ast_result = _ast_extract(code_files, **ast_kwargs)
+            except Exception as exc:
+                print(f"[graphify extract] AST extraction failed: {exc}", file=sys.stderr)
+                ast_result = {"nodes": [], "edges": [], "input_tokens": 0, "output_tokens": 0}
+
+        # Semantic extraction on docs/papers/images. Check cache first.
+        from graphify.cache import (
+            check_semantic_cache as _check_semantic_cache,
+            save_semantic_cache as _save_semantic_cache,
+        )
+        sem_result: dict = {
+            "nodes": [], "edges": [], "hyperedges": [],
+            "input_tokens": 0, "output_tokens": 0,
+        }
+        sem_cache_hits = 0
+        sem_cache_misses = 0
+        if semantic_files:
+            sem_paths_str = [str(p) for p in semantic_files]
+            cached_nodes, cached_edges, cached_hyperedges, uncached_paths = (
+                _check_semantic_cache(sem_paths_str, root=target)
+            )
+            sem_cache_hits = len(semantic_files) - len(uncached_paths)
+            sem_cache_misses = len(uncached_paths)
+            sem_result["nodes"].extend(cached_nodes)
+            sem_result["edges"].extend(cached_edges)
+            sem_result["hyperedges"].extend(cached_hyperedges)
+            if sem_cache_hits:
+                print(f"[graphify extract] semantic cache: {sem_cache_hits} hit / {sem_cache_misses} miss")
+
+            if uncached_paths:
+                print(f"[graphify extract] semantic extraction on {len(uncached_paths)} files via {backend}...")
+                corpus_kwargs: dict = {
+                    "backend": backend,
+                    "model": model,
+                    "root": target,
+                }
+                if cli_token_budget is not None:
+                    corpus_kwargs["token_budget"] = cli_token_budget
+                if cli_max_concurrency is not None:
+                    corpus_kwargs["max_concurrency"] = cli_max_concurrency
+
+                # Minimal progress callback so the CLI is no longer silent
+                # during long local-inference runs (issue #792 addendum).
+                _total_chunks = {"n": 0}
+                def _progress(idx: int, total: int, _result: dict) -> None:
+                    _total_chunks["n"] = total
+                    print(
+                        f"[graphify extract] chunk {idx + 1}/{total} done",
+                        flush=True,
+                    )
+                corpus_kwargs["on_chunk_done"] = _progress
+
+                try:
+                    fresh = _extract_corpus_parallel(
+                        [Path(p) for p in uncached_paths],
+                        **corpus_kwargs,
+                    )
+                except ImportError as exc:
+                    print(f"error: {exc}", file=sys.stderr)
+                    sys.exit(1)
+                except Exception as exc:
+                    print(
+                        f"[graphify extract] semantic extraction failed: {exc}",
+                        file=sys.stderr,
+                    )
+                    fresh = {"nodes": [], "edges": [], "hyperedges": [], "input_tokens": 0, "output_tokens": 0}
+                try:
+                    _save_semantic_cache(
+                        fresh.get("nodes", []),
+                        fresh.get("edges", []),
+                        fresh.get("hyperedges", []),
+                        root=target,
+                    )
+                except Exception as exc:
+                    print(f"[graphify extract] warning: could not write semantic cache: {exc}", file=sys.stderr)
+                sem_result["nodes"].extend(fresh.get("nodes", []))
+                sem_result["edges"].extend(fresh.get("edges", []))
+                sem_result["hyperedges"].extend(fresh.get("hyperedges", []))
+                sem_result["input_tokens"] += fresh.get("input_tokens", 0)
+                sem_result["output_tokens"] += fresh.get("output_tokens", 0)
+
+        # Merge AST + semantic. Order matters for deduplication: passing AST
+        # first means semantic node attributes win on collision (richer labels
+        # for symbols also referenced in docs). Hyperedges only come from the
+        # semantic side.
+        merged: dict = {
+            "nodes": list(ast_result.get("nodes", [])) + list(sem_result.get("nodes", [])),
+            "edges": list(ast_result.get("edges", [])) + list(sem_result.get("edges", [])),
+            "hyperedges": list(sem_result.get("hyperedges", [])),
+            "input_tokens": ast_result.get("input_tokens", 0) + sem_result.get("input_tokens", 0),
+            "output_tokens": ast_result.get("output_tokens", 0) + sem_result.get("output_tokens", 0),
+        }
+
+        graph_json_path = graphify_out / "graph.json"
+        analysis_path = graphify_out / ".graphify_analysis.json"
+
+        if no_cluster:
+            # --no-cluster: dump the raw merged extraction as graph.json.
+            # No NetworkX, no community detection, no analysis sidecar.
+            graph_json_path.write_text(
+                json.dumps(merged, indent=2), encoding="utf-8"
+            )
+            cost = _estimate_cost(
+                backend, merged["input_tokens"], merged["output_tokens"]
+            )
+            print(
+                f"[graphify extract] wrote {graph_json_path} — "
+                f"{len(merged['nodes'])} nodes, {len(merged['edges'])} edges "
+                f"(no clustering)"
+            )
+            if merged["input_tokens"] or merged["output_tokens"]:
+                print(
+                    f"[graphify extract] tokens: "
+                    f"{merged['input_tokens']:,} in / "
+                    f"{merged['output_tokens']:,} out, "
+                    f"est. cost: ${cost:.4f}"
+                )
+            try:
+                _save_manifest(files_by_type, manifest_path=str(manifest_path))
+            except Exception as exc:
+                print(f"[graphify extract] warning: could not write manifest: {exc}", file=sys.stderr)
+            if global_merge:
+                from graphify.global_graph import global_add as _global_add
+                _tag = global_repo_tag or target.name
+                try:
+                    result = _global_add(graphify_out / "graph.json", _tag)
+                    if result["skipped"]:
+                        print(f"[graphify global] '{_tag}' unchanged since last add — skipped.")
+                    else:
+                        print(f"[graphify global] '{_tag}' merged into global graph "
+                              f"(+{result['nodes_added']} nodes, -{result['nodes_removed']} pruned).")
+                except Exception as exc:
+                    print(f"[graphify global] warning: failed to merge into global graph: {exc}", file=sys.stderr)
+            sys.exit(0)
+
+        # Build graph + cluster + score + write.
+        from graphify.build import (
+            build as _build,
+            build_from_json as _build_from_json,
+            build_merge as _build_merge,
+        )
+        from graphify.cluster import cluster as _cluster, score_all as _score_all
+        from graphify.export import to_json as _to_json
+        from graphify.analyze import god_nodes as _god_nodes, surprising_connections as _surprising
+        dedup_backend = backend if dedup_llm else None
+        if incremental_mode:
+            G = _build_merge(
+                [merged],
+                graph_path=existing_graph_path,
+                prune_sources=deleted_files or None,
+                dedup=True,
+                dedup_llm_backend=dedup_backend,
+            )
+        else:
+            G = _build([merged], dedup=True, dedup_llm_backend=dedup_backend)
+        if G.number_of_nodes() == 0:
+            print(
+                "[graphify extract] graph is empty — extraction produced no nodes. "
+                "Possible causes: all files skipped, binary-only corpus, or LLM "
+                "returned no edges.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+        communities = _cluster(G)
+        cohesion = _score_all(G, communities)
+        try:
+            gods = _god_nodes(G)
+        except Exception:
+            gods = []
+        try:
+            surprises = _surprising(G, communities)
+        except Exception:
+            surprises = []
+
+        _to_json(G, communities, str(graph_json_path), force=True)
+        if global_merge:
+            from graphify.global_graph import global_add as _global_add
+            _tag = global_repo_tag or target.name
+            try:
+                result = _global_add(graphify_out / "graph.json", _tag)
+                if result["skipped"]:
+                    print(f"[graphify global] '{_tag}' unchanged since last add — skipped.")
+                else:
+                    print(f"[graphify global] '{_tag}' merged into global graph "
+                          f"(+{result['nodes_added']} nodes, -{result['nodes_removed']} pruned).")
+            except Exception as exc:
+                print(f"[graphify global] warning: failed to merge into global graph: {exc}", file=sys.stderr)
+        analysis = {
+            "communities": {str(k): v for k, v in communities.items()},
+            "cohesion": {str(k): v for k, v in cohesion.items()},
+            "gods": gods,
+            "surprises": surprises,
+            "tokens": {
+                "input": merged["input_tokens"],
+                "output": merged["output_tokens"],
+            },
+        }
+        analysis_path.write_text(json.dumps(analysis, indent=2), encoding="utf-8")
+        try:
+            _save_manifest(files_by_type, manifest_path=str(manifest_path))
+        except Exception as exc:
+            print(f"[graphify extract] warning: could not write manifest: {exc}", file=sys.stderr)
+
+        cost = _estimate_cost(backend, merged["input_tokens"], merged["output_tokens"])
+        print(
+            f"[graphify extract] wrote {graph_json_path}: "
+            f"{G.number_of_nodes()} nodes, {G.number_of_edges()} edges, "
+            f"{len(communities)} communities"
+        )
+        print(f"[graphify extract] wrote {analysis_path}")
+        if incremental_mode:
+            print(
+                f"[graphify extract] incremental summary: "
+                f"{sem_cache_hits + unchanged_total} files cached/unchanged, "
+                f"{len(code_files) + sem_cache_misses} re-extracted, "
+                f"{len(deleted_files)} deleted"
+            )
+        elif sem_cache_hits:
+            print(f"[graphify extract] semantic cache: {sem_cache_hits} cached, {sem_cache_misses} re-extracted")
+        if merged["input_tokens"] or merged["output_tokens"]:
+            print(
+                f"[graphify extract] tokens: "
+                f"{merged['input_tokens']:,} in / "
+                f"{merged['output_tokens']:,} out, "
+                f"est. cost (~{backend}): ${cost:.4f}"
+            )
+
+    else:
+        print(f"error: unknown command '{cmd}'", file=sys.stderr)
+        print("Run 'graphify --help' for usage.", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()