graphitect 0.2.0__py3-none-any.whl

graphify/install.py

@@ -0,0 +1,2366 @@
+"""graphify install/uninstall subsystem.
+
+The per-platform skill/hook installers and uninstallers, extracted verbatim from
+graphify/__main__.py so the CLI dispatcher (`main`) stays readable. Import path is
+unchanged: `graphify.__main__` re-exports every name defined here, so
+`from graphify.__main__ import claude_install` (etc.) keeps working.
+
+Lives at graphify/install.py (same package dir as __main__) on purpose: the
+installers resolve packaged assets via `Path(__file__).parent / "always_on"` and
+`/ "skills"`, which only works from within the graphify/ directory.
+"""
+
+from __future__ import annotations
+import functools
+import json
+import os
+import platform
+import re
+import shutil
+import stat
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("graphifyy")
+except Exception:
+    __version__ = "unknown"
+
+from graphify.paths import GRAPHIFY_OUT as _GRAPHIFY_OUT
+
+
+def _write_version_stamp(skill_dst: Path, version: str) -> None:
+    """Atomically write ``.graphify_version`` beside ``skill_dst``.
+
+    Matches the SKILL.md install path: temp file in the same directory, then
+    ``os.replace``. Unlike ``Path.write_text`` (and unlike
+    ``paths.write_text_atomic``, which resolves through symlinks), ``os.replace``
+    replaces a managed symlink in place — consistent with SKILL.md /
+    ``references/`` and crash-safe against a half-written stamp (#3286).
+    """
+    version_file = skill_dst.parent / ".graphify_version"
+    tmp = version_file.with_name(".graphify_version.tmp")
+    try:
+        tmp.write_text(version, encoding="utf-8")
+        os.replace(tmp, version_file)
+    except Exception:
+        try:
+            tmp.unlink(missing_ok=True)
+        except OSError:
+            pass
+        raise
+
+
+@functools.lru_cache(maxsize=None)
+def _always_on(basename: str) -> str:
+    """Read a packaged always-on instruction block from graphify/always_on/.
+
+    The six always-on blocks (CLAUDE.md / AGENTS.md / GEMINI.md / VS Code
+    Copilot instructions / Antigravity rules / Kiro steering) live as committed
+    markdown next to this module, generated by tools/skillgen from a single
+    human-edited fragment and guarded against drift by ``skillgen --check``. The
+    installer injects them verbatim via ``_replace_or_append_section``, so the
+    bytes here must match the former triple-quoted constant exactly — the
+    always-on-roundtrip validator proves that.
+    """
+    path = Path(__file__).parent / "always_on" / f"{basename}.md"
+    try:
+        return path.read_text(encoding="utf-8")
+    except OSError as exc:
+        # Defer to use-time so a missing/corrupt packaged block can't crash module
+        # import (which would brick every CLI command, not just install). Reached
+        # only by an install/integration path that actually needs this block.
+        raise RuntimeError(
+            f"graphify install is incomplete: missing always-on block '{basename}' "
+            f"at {path}. Reinstall graphifyy (e.g. `uv tool install --reinstall graphifyy`)."
+        ) from exc
+def _platform_skill_destination(platform_name: str, *, project: bool = False, project_dir: Path | None = None) -> Path:
+    """Return the skill destination for a platform and scope."""
+    if platform_name == "gemini":
+        if project:
+            return (project_dir or Path(".")) / ".gemini" / "skills" / "graphify" / "SKILL.md"
+        if platform.system() == "Windows":
+            return Path.home() / ".agents" / "skills" / "graphify" / "SKILL.md"
+        return Path.home() / ".gemini" / "skills" / "graphify" / "SKILL.md"
+
+    if platform_name == "opencode":
+        if project:
+            return (project_dir or Path(".")) / ".opencode" / "skills" / "graphify" / "SKILL.md"
+        return Path.home() / ".config" / "opencode" / "skills" / "graphify" / "SKILL.md"
+
+    if platform_name == "hermes":
+        if project:
+            return (project_dir or Path(".")) / ".hermes" / "skills" / "graphify" / "SKILL.md"
+        # On Windows, Hermes scans %LOCALAPPDATA%\hermes\skills, not ~/.hermes (#1403).
+        if platform.system() == "Windows":
+            local_appdata = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
+            return local_appdata / "hermes" / "skills" / "graphify" / "SKILL.md"
+        return Path.home() / ".hermes" / "skills" / "graphify" / "SKILL.md"
+
+    if platform_name == "devin":
+        if project:
+            return (project_dir or Path(".")) / ".devin" / "skills" / "graphify" / "SKILL.md"
+        return Path.home() / ".config" / "devin" / "skills" / "graphify" / "SKILL.md"
+
+    if platform_name == "amp":
+        if project:
+            return (project_dir or Path(".")) / ".agents" / "skills" / "graphify" / "SKILL.md"
+        return Path.home() / ".config" / "agents" / "skills" / "graphify" / "SKILL.md"
+
+    if platform_name == "agents":
+        # The generic Agent-Skills target: project ./.agents/skills, global the
+        # spec's user-global ~/.agents/skills (read by `npx skills` and compliant
+        # frameworks), NOT amp's ~/.config/agents/skills.
+        if project:
+            return (project_dir or Path(".")) / ".agents" / "skills" / "graphify" / "SKILL.md"
+        return Path.home() / ".agents" / "skills" / "graphify" / "SKILL.md"
+
+    if platform_name in ("antigravity", "antigravity-windows"):
+        if project:
+            return (project_dir or Path(".")) / ".agents" / "skills" / "graphify" / "SKILL.md"
+        # Global Antigravity skill dir (all workspaces): ~/.gemini/config/skills/
+        return Path.home() / ".gemini" / "config" / "skills" / "graphify" / "SKILL.md"
+
+    cfg = _PLATFORM_CONFIG[platform_name]
+    if project:
+        return (project_dir or Path(".")) / cfg["skill_dst"]
+
+    if platform_name in ("claude", "windows") and os.environ.get("CLAUDE_CONFIG_DIR"):
+        return Path(os.environ["CLAUDE_CONFIG_DIR"]) / "skills" / "graphify" / "SKILL.md"
+    return Path.home() / cfg["skill_dst"]
+def _packaged_skill_refs_dir(platform_name: str) -> Path | None:
+    """Return the packaged references source dir for a progressive platform, else None.
+
+    A platform opts into progressive disclosure by setting ``skill_refs`` in its
+    ``_PLATFORM_CONFIG`` entry. The value names a bundle under
+    ``graphify/skills/<bundle>/references/``. Reuse keys (e.g. trae-cn) point at
+    their twin's bundle.
+
+    ``gemini`` has no ``_PLATFORM_CONFIG`` entry: it installs claude's
+    ``skill.md`` body verbatim (see ``_copy_skill_file``). Since that body is the
+    lean progressive core that links to ``references/``, gemini needs claude's
+    references/ sidecar too, or its SKILL.md ships with dead pointers. So gemini
+    resolves to the claude bundle rather than opting out.
+
+    Bundles ship one platform-group at a time. A host whose bundle directory
+    ``graphify/skills/<bundle>/`` is not in this build has not gone progressive
+    yet, so this returns None and the host installs today's monolithic SKILL.md
+    with no references/ sidecar. Only when the bundle directory IS present does
+    this return the references path; if that directory then lacks its
+    ``references/`` subdir, ``_copy_skill_file`` hard-fails (a malformed bundle,
+    the empty-sidecar regression the wheel-content test also guards).
+    """
+    if platform_name == "gemini":
+        bundle = "claude"
+    else:
+        bundle = _PLATFORM_CONFIG[platform_name].get("skill_refs")
+    if not bundle:
+        return None
+    bundle_dir = Path(__file__).parent / "skills" / bundle
+    if not bundle_dir.is_dir():
+        return None
+    return bundle_dir / "references"
+def _install_skill_references(skill_dst: Path, refs_src: Path) -> None:
+    """Atomically install a packaged references/ sidecar next to SKILL.md.
+
+    Stages the packaged dir into ``references.tmp`` (copytree), drops any stale
+    ``references/`` already on disk, then ``os.replace``-renames the staged dir
+    into place. The rename is atomic on the same filesystem, so an interrupted
+    install never leaves a half-written references/ visible to the agent.
+    """
+    refs_dst = skill_dst.parent / "references"
+    refs_staged = skill_dst.parent / "references.tmp"
+    if refs_staged.exists():
+        shutil.rmtree(refs_staged)
+    try:
+        shutil.copytree(refs_src, refs_staged)
+        # copytree preserves the source's mode bits, and a packaged bundle can
+        # be read-only: a Nix store path, a root-owned site-packages, a
+        # container image layer. Renaming a directory needs write permission on
+        # the directory itself, to update its ".." entry, so the os.replace
+        # below would fail with EACCES. Restore owner-write on the staged copy.
+        for path in (refs_staged, *refs_staged.rglob("*")):
+            path.chmod(path.stat().st_mode | stat.S_IWUSR)
+        if refs_dst.exists():
+            shutil.rmtree(refs_dst)
+        os.replace(refs_staged, refs_dst)
+    except Exception:
+        if refs_staged.exists():
+            shutil.rmtree(refs_staged, ignore_errors=True)
+        raise
+def _copy_skill_file(platform_name: str, *, project: bool = False, project_dir: Path | None = None) -> Path:
+    """Copy a packaged skill file and write its version stamp.
+
+    For progressive platforms (those with ``skill_refs`` set), the packaged
+    ``references/`` sidecar is installed alongside SKILL.md and the single
+    ``.graphify_version`` stamp covers both. For monolith platforms (no
+    ``skill_refs``), any orphan ``references/`` left by a prior progressive
+    install is removed so the on-disk layout matches the package.
+    """
+    skill_file = "skill.md" if platform_name == "gemini" else _PLATFORM_CONFIG[platform_name]["skill_file"]
+    skill_src = Path(__file__).parent / skill_file
+    if not skill_src.exists():
+        print(f"error: {skill_file} not found in package - reinstall graphify", file=sys.stderr)
+        sys.exit(1)
+
+    refs_src = _packaged_skill_refs_dir(platform_name)
+    if refs_src is not None and not refs_src.exists():
+        # Progressive platform declared a references bundle that is missing from
+        # the package. Fail loud rather than silently shipping an empty sidecar.
+        print(
+            f"error: references for '{platform_name}' not found in package "
+            f"({refs_src}) - reinstall graphify",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    skill_dst = _platform_skill_destination(platform_name, project=project, project_dir=project_dir)
+    skill_dst.parent.mkdir(parents=True, exist_ok=True)
+
+    # Install the references/ sidecar (or clear an orphan one) BEFORE writing
+    # SKILL.md, so SKILL.md is the last artifact laid down. An install that is
+    # interrupted partway then leaves no SKILL.md rather than a SKILL.md that
+    # points at an absent references/ dir.
+    if refs_src is not None:
+        _install_skill_references(skill_dst, refs_src)
+        print(f"  references       ->  {skill_dst.parent / 'references'}")
+    else:
+        # Monolith (or progressive-with-no-refs): clear any orphan references/.
+        orphan_refs = skill_dst.parent / "references"
+        if orphan_refs.exists():
+            shutil.rmtree(orphan_refs)
+
+    # A SKILL.md that differs from what is about to be written may carry the
+    # user's local edits (a tuned description:, extra guidance); replacing it
+    # wholesale with only "skill installed ->" for output read like a no-op
+    # while the edits were gone (#3144). Keep one .bak beside it and say so.
+    # Every upgrade differs too - the .bak is overwritten each install, so it
+    # always holds exactly the previous copy.
+    try:
+        if skill_dst.exists() and skill_dst.read_bytes() != skill_src.read_bytes():
+            backup = skill_dst.with_suffix(skill_dst.suffix + ".bak")
+            shutil.copy2(skill_dst, backup)
+            print(f"  previous copy    ->  {backup} (differed from the packaged skill)")
+    except OSError:
+        pass  # a failed backup must not block the install
+    # SKILL.md last (crash-safety), via an atomic temp + rename.
+    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
+
+    _write_version_stamp(skill_dst, __version__)
+    print(f"  skill installed  ->  {skill_dst}")
+    return skill_dst
+def _remove_skill_file(platform_name: str, *, project: bool = False, project_dir: Path | None = None) -> bool:
+    """Remove a platform skill file and its version stamp without touching other scopes."""
+    skill_dst = _platform_skill_destination(platform_name, project=project, project_dir=project_dir)
+    removed = False
+    if skill_dst.exists():
+        skill_dst.unlink()
+        print(f"  skill removed    ->  {skill_dst}")
+        removed = True
+    version_file = skill_dst.parent / ".graphify_version"
+    if version_file.exists():
+        version_file.unlink()
+        removed = True
+    refs_dir = skill_dst.parent / "references"
+    if refs_dir.exists():
+        shutil.rmtree(refs_dir)
+        removed = True
+    for d in (skill_dst.parent, skill_dst.parent.parent, skill_dst.parent.parent.parent):
+        try:
+            d.rmdir()
+        except OSError:
+            break
+    return removed
+def _project_scope_root(path: Path, project_dir: Path) -> Path:
+    """Return the top-level project artifact for a project-scoped skill path."""
+    try:
+        rel = path.relative_to(project_dir)
+    except ValueError:
+        return path
+    return project_dir / rel.parts[0] if rel.parts else path
+def _remove_claude_skill_registration(project_dir: Path) -> None:
+    """Remove the project-scoped Claude skill registration file/section."""
+    claude_md = project_dir / ".claude" / "CLAUDE.md"
+    if not claude_md.exists():
+        return
+    content = claude_md.read_text(encoding="utf-8")
+    # Match the exact H1 `# graphify` registration heading, never a substring of a
+    # user's `## graphify`/`### graphify` (#2062). Section runs to the next H1.
+    cleaned = _remove_marker_section(content, "# graphify", boundary_prefix="# ")
+    if cleaned is None:
+        return
+    if cleaned:
+        claude_md.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"  CLAUDE.md        ->  graphify skill registration removed from {claude_md}")
+    else:
+        claude_md.unlink()
+        print(f"  CLAUDE.md        ->  deleted {claude_md}")
+def _print_project_git_add_hint(paths: list[Path]) -> None:
+    unique: list[str] = []
+    for path in paths:
+        text = path.as_posix().rstrip("/")
+        if path.exists() and path.is_dir():
+            text += "/"
+        if text not in unique:
+            unique.append(text)
+    if not unique:
+        return
+    print()
+    print("Project-scoped install. Add to version control:")
+    print(f"  git add {' '.join(unique)}")
+def _claude_pretooluse_hooks(strict: bool = False, project: bool = False) -> "list[dict]":
+    """graphify's Claude/Codebuddy PreToolUse hooks, resolved at install time.
+
+    The command invokes `graphify hook-guard <search|read>` via the absolute exe
+    path (`_resolve_graphify_exe`) — or, for a project-scoped install, via the
+    bare `graphify` command, since that config gets committed (#3129). Either
+    form parses under sh, cmd.exe and PowerShell alike — this is the #522 fix,
+    and mirrors the codex hook. Matchers are
+    "Bash|Grep" and "Read|Glob" and the command always contains "graphify", so the
+    existing install/uninstall filters find and replace both old bash hooks and
+    these. "Grep" is in the search matcher because current Claude Code routes
+    content search through its dedicated Grep tool, not Bash (#1986) — a
+    Bash-only matcher never fired on the agent's primary search path.
+
+    When ``strict`` is set, the read hook carries ``--strict`` so it blocks the
+    first raw read per session (Claude Code only). The ``GRAPHIFY_HOOK_STRICT`` env
+    var can force it on or off at runtime without a reinstall.
+    """
+    exe = _resolve_graphify_exe(project=project)
+    if " " in exe and not exe.startswith('"'):
+        exe = f'"{exe}"'
+    read_cmd = f"{exe} hook-guard read" + (" --strict" if strict else "")
+    return [
+        {"matcher": "Bash|Grep",
+         "hooks": [{"type": "command", "command": f"{exe} hook-guard search"}]},
+        {"matcher": "Read|Glob",
+         "hooks": [{"type": "command", "command": read_cmd}]},
+    ]
+def _skill_registration(skill_path: str = "~/.claude/skills/graphify/SKILL.md") -> str:
+    return (
+        "\n# graphify\n"
+        f"- **graphify** (`{skill_path}`) "
+        "- any input to knowledge graph. Trigger: `/graphify`\n"
+        "When the user types `/graphify`, use the installed graphify skill "
+        "or instructions before doing anything else.\n"
+    )
+def _register_always_on_block(target: Path, prefix: str, registration: str) -> None:
+    """Append an always-on registration to *target*, degrading instead of raising.
+
+    The skill files are copied before this runs, so a *target* that cannot be
+    read or written must not abort an otherwise-complete install (#3474). That
+    happens whenever the dotfile is managed declaratively -- nix/home-manager
+    symlinks ``~/.claude/CLAUDE.md`` into a read-only /nix/store, and chezmoi or
+    stow with read-only sources leave the same shape.
+    """
+    try:
+        if target.exists():
+            content = target.read_text(encoding="utf-8")
+            if "graphify" in content:
+                print(f"{prefix}already registered (no change)")
+            else:
+                target.write_text(content.rstrip() + registration, encoding="utf-8")
+                print(f"{prefix}skill registered in {target}")
+        else:
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(registration.lstrip(), encoding="utf-8")
+            print(f"{prefix}created at {target}")
+    except OSError as exc:
+        print(f"{prefix}skipped: {exc.__class__.__name__}: {exc}", file=sys.stderr)
+        print(
+            f"  hint: the skill files were installed; add the graphify block to "
+            f"{target} manually to finish always-on registration",
+            file=sys.stderr,
+        )
+_PLATFORM_CONFIG: dict[str, dict] = {
+    "claude": {
+        "skill_file": "skill.md",
+        "skill_dst": Path(".claude") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": True,
+        "skill_refs": "claude",
+    },
+    "codex": {
+        "skill_file": "skill-codex.md",
+        "skill_dst": Path(".codex") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "codex",
+    },
+    "opencode": {
+        "skill_file": "skill-opencode.md",
+        "skill_dst": Path(".config") / "opencode" / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "opencode",
+    },
+    "kilo": {
+        "skill_file": "skill-kilo.md",
+        "skill_dst": Path(".config") / "kilo" / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "kilo",
+    },
+    "aider": {
+        # Monolith: aider ships the full SKILL.md inline, no references/ sidecar.
+        "skill_file": "skill-aider.md",
+        "skill_dst": Path(".aider") / "graphify" / "SKILL.md",
+        "claude_md": False,
+    },
+    "copilot": {
+        "skill_file": "skill-copilot.md",
+        "skill_dst": Path(".copilot") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "copilot",
+    },
+    "claw": {
+        "skill_file": "skill-claw.md",
+        "skill_dst": Path(".openclaw") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "claw",
+    },
+    "droid": {
+        "skill_file": "skill-droid.md",
+        "skill_dst": Path(".factory") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "droid",
+    },
+    "trae": {
+        "skill_file": "skill-trae.md",
+        "skill_dst": Path(".trae") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "trae",
+    },
+    "trae-cn": {
+        # Reuses trae's split bundle (same skill body + references).
+        "skill_file": "skill-trae.md",
+        "skill_dst": Path(".trae-cn") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "trae",
+    },
+    "hermes": {
+        # Reuses claw's split bundle.
+        "skill_file": "skill-claw.md",
+        "skill_dst": Path(".hermes") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "claw",
+    },
+    "kiro": {
+        "skill_file": "skill-kiro.md",
+        "skill_dst": Path(".kiro") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "kiro",
+    },
+    "pi": {
+        "skill_file": "skill-pi.md",
+        "skill_dst": Path(".pi") / "agent" / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "pi",
+    },
+    "codebuddy": {
+        # Reuses claude's split bundle (shares skill.md).
+        "skill_file": "skill.md",
+        "skill_dst": Path(".codebuddy") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "claude",
+    },
+    "antigravity": {
+        # Rides claude's split bundle (shares skill.md).
+        "skill_file": "skill.md",
+        "skill_dst": Path(".agents") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "claude",
+    },
+    "antigravity-windows": {
+        # Rides windows' split bundle.
+        "skill_file": "skill-windows.md",
+        "skill_dst": Path(".agents") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "windows",
+    },
+    "windows": {
+        "skill_file": "skill-windows.md",
+        "skill_dst": Path(".claude") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": True,
+        "skill_refs": "windows",
+    },
+    "kimi": {
+        # Reuses claude's split bundle (shares skill.md).
+        "skill_file": "skill.md",
+        "skill_dst": Path(".kimi") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "claude",
+    },
+    "amp": {
+        # Amp searches .agents/skills (project) and ~/.config/agents/skills (user),
+        # not .amp/skills. The user-scope path is set in _platform_skill_destination.
+        "skill_file": "skill-amp.md",
+        "skill_dst": Path(".agents") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "amp",
+    },
+    "agents": {
+        # The generic cross-framework Agent-Skills target. Global: ~/.agents/skills
+        # (the spec's user-global location, read by `npx skills` and compliant
+        # frameworks); project: ./.agents/skills. The CLI accepts `skills` as an
+        # alias (see _canonical_platform). Ships its own rendered bundle.
+        "skill_file": "skill-agents.md",
+        "skill_dst": Path(".agents") / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+        "skill_refs": "agents",
+    },
+    "devin": {
+        # Monolith: devin ships the full SKILL.md inline, no references/ sidecar.
+        "skill_file": "skill-devin.md",
+        # User scope: ~/.config/devin/skills/graphify/SKILL.md
+        # Project scope: .devin/skills/graphify/SKILL.md (overridden in _platform_skill_destination)
+        "skill_dst": Path(".config") / "devin" / "skills" / "graphify" / "SKILL.md",
+        "claude_md": False,
+    },
+}
+# CLI-only platform aliases, resolved to a real _PLATFORM_CONFIG key before
+# dispatch. `skills` is the friendly alias for the generic `agents` platform
+# (the Agent-Skills ecosystem calls them "skills").
+_PLATFORM_ALIASES: dict[str, str] = {"skills": "agents"}
+def _canonical_platform(platform_name: str) -> str:
+    """Resolve a CLI platform alias to its real _PLATFORM_CONFIG key."""
+    return _PLATFORM_ALIASES.get(platform_name, platform_name)
+def _replace_or_append_section(content: str, marker: str, new_section: str) -> str:
+    """Idempotently update or append a graphify-owned section in shared files.
+
+    If no line is exactly ``marker`` (the heading, at column 0), append
+    ``new_section`` to the end (with a blank-line separator if there's existing
+    content).
+
+    If a real ``marker`` heading exists, replace the existing section in place.
+    The section runs from that heading to the line before the next H2 heading
+    (``## `` at line start), or to EOF if no later H2 exists. This lets older
+    installs receive the updated copy without users having to uninstall and
+    reinstall (issue #580).
+
+    The heading is matched only when a line *is* exactly ``marker`` (after
+    stripping surrounding whitespace), never as a substring. Matching ``##
+    graphify`` inside a bullet or an inline reference used to anchor the replace
+    on that mention and delete every line from there to the next heading,
+    silently destroying hand-curated content (#1688). When several exact
+    headings exist, the last one is used, since graphify's section is appended.
+    """
+    lines = content.split("\n")
+    starts = [i for i, line in enumerate(lines) if line.strip() == marker]
+    if not starts:
+        if content.strip():
+            return content.rstrip() + "\n\n" + new_section.lstrip()
+        return new_section.lstrip()
+
+    start = starts[-1]
+    end = len(lines)
+    for j in range(start + 1, len(lines)):
+        if lines[j].startswith("## "):
+            end = j
+            break
+
+    head = "\n".join(lines[:start]).rstrip()
+    tail = "\n".join(lines[end:]).lstrip()
+    section = new_section.strip()
+
+    parts: list[str] = []
+    if head:
+        parts.append(head)
+    parts.append(section)
+    if tail:
+        parts.append(tail)
+    out = "\n\n".join(parts)
+    if not out.endswith("\n"):
+        out += "\n"
+    return out
+
+
+def _remove_marker_section(content: str, marker: str, boundary_prefix: str = "## ") -> "str | None":
+    """Remove every section whose heading line is exactly ``marker``.
+
+    The heading is matched only when a line *is* exactly ``marker`` (after
+    stripping surrounding whitespace), never as a substring. The old uninstall
+    regex ``## graphify`` was unanchored, so it matched inside a user's
+    ``### graphify`` heading and deleted hand-written content (#2062) — the same
+    class of bug the install side hardened against in #1688. Each section runs to
+    the line before the next ``boundary_prefix`` heading (default the next H2) or
+    EOF, mirroring ``_replace_or_append_section``. All exact-heading sections are
+    removed (pre-#1688 installs could leave duplicates).
+
+    Returns None when no exact ``marker`` line exists — the caller must then leave
+    the file untouched. This doubles as the guard: a substring mention (a bullet,
+    an inline reference, a deeper ``###`` heading) never triggers a strip.
+    """
+    lines = content.split("\n")
+    removed = False
+    while True:
+        starts = [i for i, line in enumerate(lines) if line.strip() == marker]
+        if not starts:
+            break
+        start = starts[-1]
+        end = len(lines)
+        for j in range(start + 1, len(lines)):
+            if lines[j].startswith(boundary_prefix):
+                end = j
+                break
+        head = "\n".join(lines[:start]).rstrip()
+        tail = "\n".join(lines[end:]).lstrip()
+        merged = head + "\n\n" + tail if head and tail else (head or tail)
+        lines = merged.split("\n")
+        removed = True
+    if not removed:
+        return None
+    return "\n".join(lines).rstrip()
+
+
+def _print_banner() -> None:
+    """Amber brain banner on graphify install. TTY-only, never raises."""
+    if not sys.stdout.isatty():
+        return
+    try:
+        if sys.platform == "win32":
+            import ctypes
+            ctypes.windll.kernel32.SetConsoleMode(
+                ctypes.windll.kernel32.GetStdHandle(-11), 7
+            )
+        A = "\033[38;5;214m"
+        D = "\033[38;5;130m"
+        R = "\033[0m"
+        print(f"""{A}
+  ╭──◉──╮     ╭──◉──╮
+ ╱  ◉   ◉ ╲ ╱ ◉   ◉  ╲
+│   ◉─◉─◉  ◉  ◉─◉─◉   │
+│    ◉   ◉ │ ◉   ◉    │
+│   ◉─◉─◉  ◉  ◉─◉─◉   │
+ ╲  ◉   ◉ ╱ ╲ ◉   ◉  ╱
+  ╰──◉──╯     ╰──◉──╯
+           ◉
+
+  █▀▀ █▀█ ▄▀█ █▀█ █ █ █ █▀▀ █▄█
+  █▄█ █▀▄ █▀█ █▀▀ █▀█ █ █▀   █{D}  {__version__}{R}
+""")
+    except Exception:
+        pass
+def install(platform: str = "claude", *, project: bool = False, project_dir: Path | None = None) -> None:
+    _print_banner()
+    platform = _canonical_platform(platform)
+    if platform == "gemini":
+        gemini_install(project_dir=project_dir, project=project)
+        return
+    if platform == "cursor":
+        _cursor_install(Path("."))
+        return
+    # On Windows, antigravity needs the PowerShell skill, not the bash one
+    if platform == "antigravity" and sys.platform == "win32":
+        platform = "antigravity-windows"
+    if platform not in _PLATFORM_CONFIG:
+        print(
+            f"error: unknown platform '{platform}'. Choose from: {', '.join(_PLATFORM_CONFIG)}, gemini, cursor",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    cfg = _PLATFORM_CONFIG[platform]
+    project_dir = project_dir or Path(".")
+    skill_dst = _copy_skill_file(platform, project=project, project_dir=project_dir)
+
+    if platform == "kilo":
+        # Kilo Code also supports a native /graphify command file.
+        command_src = Path(__file__).parent / "command-kilo.md"
+        if not command_src.exists():
+            print(
+                f"error: command-kilo.md not found in package - reinstall graphify",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+        command_dst = Path.home() / ".config" / "kilo" / "command" / "graphify.md"
+        command_dst.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copy(command_src, command_dst)
+        print(f"  command installed ->  {command_dst}")
+
+    if cfg["claude_md"]:
+        # Register in the matching Claude Code scope. Honor CLAUDE_CONFIG_DIR
+        # for the global (non-project) case, same as _platform_skill_destination
+        # does for the skill copy path (#527) -- this always-on registration
+        # path was missed by that fix (#2694).
+        if project:
+            claude_md = project_dir / ".claude" / "CLAUDE.md"
+            skill_ref = ".claude/skills/graphify/SKILL.md"
+        elif os.environ.get("CLAUDE_CONFIG_DIR"):
+            config_dir = Path(os.environ["CLAUDE_CONFIG_DIR"])
+            claude_md = config_dir / "CLAUDE.md"
+            skill_ref = str(config_dir / "skills" / "graphify" / "SKILL.md")
+        else:
+            claude_md = Path.home() / ".claude" / "CLAUDE.md"
+            skill_ref = "~/.claude/skills/graphify/SKILL.md"
+        _register_always_on_block(
+            claude_md, "  CLAUDE.md        ->  ", _skill_registration(skill_ref)
+        )
+
+    if platform == "codebuddy":
+        # Register in ~/.codebuddy/CODEBUDDY.md (CodeBuddy only)
+        _register_always_on_block(
+            Path.home() / ".codebuddy" / "CODEBUDDY.md",
+            "  CODEBUDDY.md     ->  ",
+            _skill_registration("~/.codebuddy/skills/graphify/SKILL.md"),
+        )
+
+    if platform == "opencode":
+        _install_opencode_plugin(project_dir if project else Path("."))
+
+    if project:
+        _print_project_git_add_hint([_project_scope_root(skill_dst, project_dir)])
+
+    print()
+    print("Done. Open your AI coding assistant and type:")
+    print()
+    print("  /graphify .")
+    print()
+    print("Prefer a hosted version? Early access to the graphify platform is")
+    print("open free before the public v1 launch: https://app.graphify.com")
+    print()
+def _print_install_usage() -> None:
+    platforms = ", ".join([*_PLATFORM_CONFIG, "gemini", "cursor"])
+    print("Usage: graphify install [--project] [--strict] [--platform P|P]")
+    print(f"Platforms: {platforms}")
+    print("  --strict  block the first raw file read per session until one "
+          "`graphify query` runs (Claude Code project hook only; needs --project)")
+_CLAUDE_MD_MARKER = "## graphify"
+_CODEBUDDY_MD_MARKER = "## graphify"
+_AGENTS_MD_MARKER = "## graphify"
+_GEMINI_MD_MARKER = "## graphify"
+def _gemini_hook(project: bool = False) -> dict:
+    """Gemini CLI BeforeTool hook, resolved to a shell-agnostic `graphify` call.
+
+    A project-scoped install emits the bare command, since .gemini/settings.json
+    is then committed and an installing machine's path is wrong there (#3129).
+    """
+    exe = _resolve_graphify_exe(project=project)
+    if " " in exe and not exe.startswith('"'):
+        exe = f'"{exe}"'
+    return {
+        "matcher": "read_file|list_directory",
+        "hooks": [{"type": "command", "command": f"{exe} hook-guard gemini"}],
+    }
+def gemini_install(project_dir: Path | None = None, *, project: bool = False) -> None:
+    """Copy skill file, write GEMINI.md section, and install BeforeTool hook."""
+    project_dir = project_dir or Path(".")
+    skill_dst = _copy_skill_file("gemini", project=project, project_dir=project_dir)
+
+    target = project_dir / "GEMINI.md"
+
+    if target.exists():
+        content = target.read_text(encoding="utf-8")
+        new_content = _replace_or_append_section(
+            content, _GEMINI_MD_MARKER, _always_on("gemini-md")
+        )
+    else:
+        new_content = _always_on("gemini-md")
+
+    if target.exists() and new_content == target.read_text(encoding="utf-8"):
+        print(f"graphify already configured in {target.resolve()} (no change)")
+    else:
+        target.write_text(new_content, encoding="utf-8")
+        print(f"graphify section written to {target.resolve()}")
+
+    # Always re-install the Gemini hook so an older payload (e.g. pre-issue-#580
+    # wording) is replaced on upgrade.
+    _install_gemini_hook(project_dir, project=project)
+    if project:
+        _print_project_git_add_hint([_project_scope_root(skill_dst, project_dir), project_dir / "GEMINI.md", project_dir / ".gemini"])
+    print()
+    print("Gemini CLI will now check the knowledge graph before answering")
+    print("codebase questions and rebuild it after code changes.")
+def _refuse_to_modify(settings_path: Path) -> "NoReturn":
+    """Abort a hook install rather than clobber a config file we can't parse (#2167)."""
+    print(
+        f"[graphify] refusing to modify {settings_path}: not valid JSON "
+        "(fix or move it and re-run)",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+def _read_settings_for_merge(settings_path: Path) -> dict:
+    """Load an existing settings/hooks JSON file for a read-modify-write merge.
+
+    A missing file yields a fresh ``{}`` (first install). An existing file that
+    cannot be parsed as a JSON object aborts via ``_refuse_to_modify`` instead of
+    silently falling back to ``{}`` — the old fallback rewrote the whole file and
+    destroyed every setting the user had (#2167). Reads with ``utf-8-sig`` so a
+    UTF-8 BOM (the most likely parse-error trigger, same class as #2163) is
+    tolerated rather than fatal.
+    """
+    if not settings_path.exists():
+        return {}
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8-sig"))
+    except (json.JSONDecodeError, UnicodeDecodeError, OSError):
+        settings = None
+    if not isinstance(settings, dict):
+        _refuse_to_modify(settings_path)
+    return settings
+def _write_settings_with_backup(settings_path: Path, settings: dict) -> None:
+    """Serialize ``settings`` to ``settings_path``, backing up the previous file.
+
+    Skips the write entirely when the output is identical to what is on disk
+    (idempotent re-install: no backup churn, no mtime churn). Otherwise copies
+    the existing file to ``<name>.graphify-bak`` (single rolling backup) before
+    overwriting, so one bad merge can never destroy the user's config (#2167).
+    """
+    output = json.dumps(settings, indent=2)
+    if settings_path.exists():
+        if settings_path.read_text(encoding="utf-8") == output:
+            return
+        backup = settings_path.with_name(settings_path.name + ".graphify-bak")
+        shutil.copy2(settings_path, backup)
+    settings_path.write_text(output, encoding="utf-8")
+def _install_gemini_hook(project_dir: Path, project: bool = False) -> None:
+    settings_path = project_dir / ".gemini" / "settings.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+    settings = _read_settings_for_merge(settings_path)
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        _refuse_to_modify(settings_path)
+    before_tool = hooks.setdefault("BeforeTool", [])
+    if not isinstance(before_tool, list):
+        _refuse_to_modify(settings_path)
+    hooks["BeforeTool"] = [
+        h for h in before_tool if "graphify" not in str(h)
+    ]
+    hooks["BeforeTool"].append(_gemini_hook(project=project))
+    _write_settings_with_backup(settings_path, settings)
+    print("  .gemini/settings.json  ->  BeforeTool hook registered")
+def _uninstall_gemini_hook(project_dir: Path) -> None:
+    settings_path = project_dir / ".gemini" / "settings.json"
+    if not settings_path.exists():
+        return
+    try:
+        settings = json.loads(settings_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return
+    before_tool = settings.get("hooks", {}).get("BeforeTool", [])
+    filtered = [h for h in before_tool if "graphify" not in str(h)]
+    if len(filtered) == len(before_tool):
+        return
+    settings["hooks"]["BeforeTool"] = filtered
+    settings_path.write_text(json.dumps(settings, indent=2), encoding="utf-8")
+    print("  .gemini/settings.json  ->  BeforeTool hook removed")
+def gemini_uninstall(project_dir: Path | None = None, *, project: bool = False, remove_user_skill: bool | None = None) -> None:
+    """Remove the graphify section from GEMINI.md, uninstall hook, and remove skill file.
+
+    Scope rules (#2215): a bare call removes the user-global skill; passing
+    ``project_dir`` (or ``project=True``) scopes skill removal to that project
+    and leaves the global tree untouched, unless ``remove_user_skill=True``
+    explicitly opts back into the global delete (as ``uninstall_all`` does).
+    """
+    explicit_dir = project_dir is not None
+    project_dir = project_dir or Path(".")
+    if remove_user_skill is None:
+        remove_user_skill = not project and not explicit_dir
+    if project or (explicit_dir and not remove_user_skill):
+        _remove_skill_file("gemini", project=True, project_dir=project_dir)
+    if remove_user_skill:
+        _remove_skill_file("gemini", project=False)
+
+    target = project_dir / "GEMINI.md"
+    if not target.exists():
+        print("No GEMINI.md found in current directory - nothing to do")
+        return
+    content = target.read_text(encoding="utf-8")
+    cleaned = _remove_marker_section(content, _GEMINI_MD_MARKER)
+    if cleaned is None:
+        print("graphify section not found in GEMINI.md - nothing to do")
+        return
+    if cleaned:
+        target.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"graphify section removed from {target.resolve()}")
+    else:
+        target.unlink()
+        print(f"GEMINI.md was empty after removal - deleted {target.resolve()}")
+    _uninstall_gemini_hook(project_dir)
+_VSCODE_INSTRUCTIONS_MARKER = "## graphify"
+def vscode_install(project_dir: Path | None = None) -> None:
+    """Install graphify skill for VS Code Copilot Chat + write .github/copilot-instructions.md."""
+    skill_src = Path(__file__).parent / "skill-vscode.md"
+    refs_bundle = "vscode"
+    if not skill_src.exists():
+        skill_src = Path(__file__).parent / "skill-copilot.md"
+        refs_bundle = "copilot"
+    skill_dst = Path.home() / ".copilot" / "skills" / "graphify" / "SKILL.md"
+    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
+    # Progressive-capable: install the packaged references/ sidecar when present.
+    refs_src = Path(__file__).parent / "skills" / refs_bundle / "references"
+    if refs_src.exists():
+        _install_skill_references(skill_dst, refs_src)
+        print(f"  references       ->  {skill_dst.parent / 'references'}")
+    else:
+        orphan_refs = skill_dst.parent / "references"
+        if orphan_refs.exists():
+            shutil.rmtree(orphan_refs)
+    _write_version_stamp(skill_dst, __version__)
+    print(f"  skill installed  ->  {skill_dst}")
+
+    instructions = (project_dir or Path(".")) / ".github" / "copilot-instructions.md"
+    instructions.parent.mkdir(parents=True, exist_ok=True)
+    if instructions.exists():
+        content = instructions.read_text(encoding="utf-8")
+        new_content = _replace_or_append_section(
+            content, _VSCODE_INSTRUCTIONS_MARKER, _always_on("vscode-instructions")
+        )
+        if new_content == content:
+            print(f"  {instructions}  ->  already configured (no change)")
+        else:
+            instructions.write_text(new_content, encoding="utf-8")
+            print(f"  {instructions}  ->  graphify section {'updated' if _VSCODE_INSTRUCTIONS_MARKER in content else 'added'}")
+    else:
+        instructions.write_text(_always_on("vscode-instructions"), encoding="utf-8")
+        print(f"  {instructions}  ->  created")
+
+    print()
+    print(
+        "VS Code Copilot Chat configured. Type /graphify in the chat panel to build the graph."
+    )
+    print("Note: for GitHub Copilot CLI (terminal), use: graphify copilot install")
+def vscode_uninstall(project_dir: Path | None = None) -> None:
+    """Remove graphify VS Code Copilot Chat skill and .github/copilot-instructions.md section."""
+    skill_dst = Path.home() / ".copilot" / "skills" / "graphify" / "SKILL.md"
+    if skill_dst.exists():
+        skill_dst.unlink()
+        print(f"  skill removed    ->  {skill_dst}")
+    version_file = skill_dst.parent / ".graphify_version"
+    if version_file.exists():
+        version_file.unlink()
+    refs_dir = skill_dst.parent / "references"
+    if refs_dir.exists():
+        shutil.rmtree(refs_dir)
+    for d in (
+        skill_dst.parent,
+        skill_dst.parent.parent,
+        skill_dst.parent.parent.parent,
+    ):
+        try:
+            d.rmdir()
+        except OSError:
+            break
+
+    instructions = (project_dir or Path(".")) / ".github" / "copilot-instructions.md"
+    if not instructions.exists():
+        return
+    content = instructions.read_text(encoding="utf-8")
+    cleaned = _remove_marker_section(content, _VSCODE_INSTRUCTIONS_MARKER)
+    if cleaned is None:
+        return
+    if cleaned:
+        instructions.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"  graphify section removed from {instructions}")
+    else:
+        instructions.unlink()
+        print(f"  {instructions}  ->  deleted (was empty after removal)")
+_ANTIGRAVITY_RULES_PATH = Path(".agents") / "rules" / "graphify.md"
+_ANTIGRAVITY_WORKFLOW_PATH = Path(".agents") / "workflows" / "graphify.md"
+# Names no SKILL.md location on purpose: this constant is shared by the global and
+# project-scoped installs, which put the skill in different places, so any hardcoded
+# path dangles for the other scope. Antigravity resolves the skill by frontmatter name.
+_ANTIGRAVITY_WORKFLOW = """\
+---
+name: graphify
+description: Turn any folder of files into a navigable knowledge graph
+---
+
+# Workflow: graphify
+
+Follow the graphify skill to run the full pipeline.
+
+If no path argument is given, use `.` (current directory).
+"""
+def _kiro_install(project_dir: Path) -> None:
+    """Write graphify skill + steering file for Kiro IDE/CLI."""
+    project_dir = project_dir or Path(".")
+
+    # Skill file + references/ sidecar + .graphify_version stamp via the shared
+    # progressive-disclosure helper.  Previously this used a bare write_text that
+    # bypassed _copy_skill_file, so the references/ dir and version stamp were
+    # never written even though kiro declares skill_refs: "kiro" (#1142).
+    _copy_skill_file("kiro", project=True, project_dir=project_dir)
+
+    # Steering file → .kiro/steering/graphify.md (always-on)
+    steering_dir = project_dir / ".kiro" / "steering"
+    steering_dir.mkdir(parents=True, exist_ok=True)
+    steering_dst = steering_dir / "graphify.md"
+    if steering_dst.exists() and steering_dst.read_text(encoding="utf-8") == _always_on("kiro-steering"):
+        print(f"  .kiro/steering/graphify.md  ->  already configured (no change)")
+    else:
+        # File is wholly graphify-owned. Overwrite on upgrade so older
+        # report-first wording does not silently linger (issue #580).
+        action = "updated" if steering_dst.exists() else "written"
+        steering_dst.write_text(_always_on("kiro-steering"), encoding="utf-8")
+        print(f"  .kiro/steering/graphify.md  ->  always-on steering {action}")
+
+    print()
+    print("Kiro will now read the knowledge graph before every conversation.")
+    print("Use /graphify to build or update the graph.")
+def _kiro_uninstall(project_dir: Path) -> None:
+    """Remove graphify skill + steering file for Kiro."""
+    project_dir = project_dir or Path(".")
+    removed = []
+
+    # Skill + .graphify_version + references/ sidecar + empty-dir walk.
+    skill_dst = _platform_skill_destination("kiro", project=True, project_dir=project_dir)
+    if _remove_skill_file("kiro", project=True, project_dir=project_dir):
+        removed.append(str(skill_dst.relative_to(project_dir)))
+
+    steering_dst = project_dir / ".kiro" / "steering" / "graphify.md"
+    if steering_dst.exists():
+        steering_dst.unlink()
+        removed.append(str(steering_dst.relative_to(project_dir)))
+
+    print("Removed: " + (", ".join(removed) if removed else "nothing to remove"))
+def _antigravity_finalize(skill_dst: Path, project_dir: Path) -> None:
+    """Write Antigravity's always-on layer next to an installed skill.
+
+    Injects the native tool-discovery YAML frontmatter into *skill_dst*, then
+    writes ``.agents/rules/graphify.md`` and ``.agents/workflows/graphify.md``
+    under *project_dir*. Shared by the global ``antigravity install`` and the
+    project-scoped ``install --project --platform antigravity`` paths, so both lay
+    down the rules/workflows that the uninstall path already expects to remove.
+    """
+    # Inject YAML frontmatter for native Antigravity tool discovery.
+    if skill_dst.exists():
+        content = skill_dst.read_text(encoding="utf-8")
+        if not content.startswith("---\n"):
+            frontmatter = "---\nname: graphify-manager\ndescription: Rebuild the code graph or perform manual CLI queries when MCP server is offline.\n---\n\n"
+            skill_dst.write_text(frontmatter + content, encoding="utf-8")
+
+    # .agents/rules/graphify.md
+    rules_path = project_dir / _ANTIGRAVITY_RULES_PATH
+    rules_path.parent.mkdir(parents=True, exist_ok=True)
+    if rules_path.exists():
+        existing = rules_path.read_text(encoding="utf-8")
+        if _always_on("antigravity-rules").strip() != existing.strip():
+            rules_path.write_text(_always_on("antigravity-rules"), encoding="utf-8")
+            print(f"graphify rule updated at {rules_path.resolve()}")
+        else:
+            print(f"graphify rule already configured at {rules_path.resolve()} (no change)")
+    else:
+        rules_path.write_text(_always_on("antigravity-rules"), encoding="utf-8")
+        print(f"graphify rule written to {rules_path.resolve()}")
+
+    # .agents/workflows/graphify.md
+    wf_path = project_dir / _ANTIGRAVITY_WORKFLOW_PATH
+    wf_path.parent.mkdir(parents=True, exist_ok=True)
+    if wf_path.exists():
+        existing = wf_path.read_text(encoding="utf-8")
+        if _ANTIGRAVITY_WORKFLOW.strip() != existing.strip():
+            wf_path.write_text(_ANTIGRAVITY_WORKFLOW, encoding="utf-8")
+            print(f"graphify workflow updated at {wf_path.resolve()}")
+        else:
+            print(f"graphify workflow already configured at {wf_path.resolve()} (no change)")
+    else:
+        wf_path.write_text(_ANTIGRAVITY_WORKFLOW, encoding="utf-8")
+        print(f"graphify workflow written to {wf_path.resolve()}")
+def _antigravity_install(project_dir: Path) -> None:
+    """Install graphify for Google Antigravity (global skill + .agents/rules + .agents/workflows)."""
+    # Copy the skill to ~/.gemini/config/skills/graphify/SKILL.md (global), then
+    # lay down the always-on rules/workflows under the project dir.
+    install(platform="antigravity")
+    _antigravity_finalize(_platform_skill_destination("antigravity"), project_dir)
+
+    print()
+    print("Antigravity will now check the knowledge graph before answering")
+    print("codebase questions. Run /graphify first to build the graph.")
+    print()
+    print(
+        "To enable full MCP architecture navigation, add this to ~/.gemini/antigravity/mcp_config.json:"
+    )
+    print('  "graphify": {')
+    print('    "command": "uv",')
+    print(
+        '    "args": ["run", "--with", "graphifyy", "--with", "mcp", "-m", "graphify.serve", "${workspace.path}/graphify-out/graph.json"]'
+    )
+    print("  }")
+def _antigravity_uninstall(project_dir: Path, *, project: bool = False) -> None:
+    """Remove graphify Antigravity rules, workflow, and skill files."""
+    # Remove rules file
+    rules_path = project_dir / _ANTIGRAVITY_RULES_PATH
+    if rules_path.exists():
+        rules_path.unlink()
+        print(f"graphify rule removed from {rules_path.resolve()}")
+    else:
+        print("No graphify Antigravity rule found - nothing to do")
+
+    # Remove workflow file
+    wf_path = project_dir / _ANTIGRAVITY_WORKFLOW_PATH
+    if wf_path.exists():
+        wf_path.unlink()
+        print(f"graphify workflow removed from {wf_path.resolve()}")
+
+    # Remove skill file
+    skill_dst = _platform_skill_destination("antigravity", project=project, project_dir=project_dir)
+    if skill_dst.exists():
+        skill_dst.unlink()
+        print(f"graphify skill removed from {skill_dst}")
+    version_file = skill_dst.parent / ".graphify_version"
+    if version_file.exists():
+        version_file.unlink()
+    refs_dir = skill_dst.parent / "references"
+    if refs_dir.exists():
+        shutil.rmtree(refs_dir)
+    for d in (
+        skill_dst.parent,
+        skill_dst.parent.parent,
+        skill_dst.parent.parent.parent,
+    ):
+        try:
+            d.rmdir()
+        except OSError:
+            break
+_CURSOR_RULE_PATH = Path(".cursor") / "rules" / "graphify.mdc"
+_CURSOR_RULE = """\
+---
+description: graphify knowledge graph context
+alwaysApply: true
+---
+
+This project has a graphify knowledge graph at graphify-out/.
+
+**MANDATORY: Before using Read, Grep, Glob, or Bash to explore the codebase, you MUST run graphify first:**
+- `graphify query "<question>"` — scoped subgraph for any codebase or architecture question
+- `graphify path "<A>" "<B>"` — dependency path between two symbols
+- `graphify explain "<concept>"` — all nodes related to a concept
+
+This applies to YOU and to every subagent you spawn. Include this rule explicitly in every subagent prompt that involves code exploration. Do not skip graphify because files are "already known" or because you are executing a plan — the graph surfaces cross-file dependencies and INFERRED edges that grep and Read cannot find.
+
+Only use Read/Grep/Glob directly when:
+1. graphify has already oriented you and you need to modify or debug specific lines
+2. `graphify-out/graph.json` does not exist yet
+
+- If `graphify-out/wiki/index.md` exists, navigate it instead of reading raw files
+- Read `graphify-out/GRAPH_REPORT.md` only for broad architecture review when query/path/explain do not surface enough context
+- After modifying code files, run `graphify update .` to keep the graph current (AST-only, no API cost)
+"""
+def _cursor_install(project_dir: Path) -> None:
+    """Write .cursor/rules/graphify.mdc with alwaysApply: true."""
+    rule_path = (project_dir or Path(".")) / _CURSOR_RULE_PATH
+    rule_path.parent.mkdir(parents=True, exist_ok=True)
+    if rule_path.exists() and rule_path.read_text(encoding="utf-8") == _CURSOR_RULE:
+        print(f"graphify rule at {rule_path} already configured (no change)")
+        return
+    # File is wholly graphify-owned. Overwrite on upgrade so older
+    # report-first wording does not silently linger (issue #580).
+    action = "updated" if rule_path.exists() else "written"
+    rule_path.write_text(_CURSOR_RULE, encoding="utf-8")
+    print(f"graphify rule {action} at {rule_path.resolve()}")
+    print()
+    print("Cursor will now always include the knowledge graph context.")
+    print("Run /graphify . first to build the graph if you haven't already.")
+def _cursor_uninstall(project_dir: Path) -> None:
+    """Remove .cursor/rules/graphify.mdc."""
+    rule_path = (project_dir or Path(".")) / _CURSOR_RULE_PATH
+    if not rule_path.exists():
+        print("No graphify Cursor rule found - nothing to do")
+        return
+    rule_path.unlink()
+    print(f"graphify Cursor rule removed from {rule_path.resolve()}")
+# Devin CLI — .windsurf/rules/graphify.md (always-on context)
+# Devin reads .windsurf/rules/*.md files the same way Windsurf IDE does.
+_DEVIN_RULES_PATH = Path(".windsurf") / "rules" / "graphify.md"
+_DEVIN_RULES = """\
+## graphify
+
+This project has a graphify knowledge graph at graphify-out/.
+
+Rules:
+- For codebase or architecture questions, when `graphify-out/graph.json` exists, first run `graphify query "<question>"` (or `graphify path "<A>" "<B>"` / `graphify explain "<concept>"`). These return a scoped subgraph, usually much smaller than `GRAPH_REPORT.md` or raw grep output.
+- If graphify-out/wiki/index.md exists, navigate it instead of reading raw files
+- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context
+- After modifying code files in this session, run `graphify update .` to keep the graph current (AST-only, no API cost)
+"""
+def _devin_rules_install(project_dir: Path) -> None:
+    """Write .windsurf/rules/graphify.md for always-on Devin context."""
+    rules_path = (project_dir or Path(".")) / _DEVIN_RULES_PATH
+    rules_path.parent.mkdir(parents=True, exist_ok=True)
+    if rules_path.exists() and rules_path.read_text(encoding="utf-8") == _DEVIN_RULES:
+        print(f"  {rules_path}  ->  already configured (no change)")
+        return
+    action = "updated" if rules_path.exists() else "written"
+    rules_path.write_text(_DEVIN_RULES, encoding="utf-8")
+    print(f"  rules {action}  ->  {rules_path}")
+def _devin_rules_uninstall(project_dir: Path) -> None:
+    """Remove .windsurf/rules/graphify.md."""
+    rules_path = (project_dir or Path(".")) / _DEVIN_RULES_PATH
+    if not rules_path.exists():
+        return
+    rules_path.unlink()
+    print(f"  rules removed  ->  {rules_path}")
+_KILO_PLUGIN_JS = """\
+// graphify Kilo plugin
+// Injects a knowledge graph reminder before bash tool calls when the graph exists.
+import { existsSync } from "fs";
+import { join } from "path";
+
+export const GraphifyPlugin = async ({ directory }) => {
+  let reminded = false;
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (reminded) return;
+      if (!existsSync(join(directory, "graphify-out", "graph.json"))) return;
+
+      if (input.tool === "bash") {
+        // Separate with ';' not '&&' — Windows PowerShell 5.1 rejects '&&' as a
+        // statement separator ("not a valid statement separator"), which broke
+        // the first bash command in every OpenCode session on Windows (#1646).
+        // ';' works in PowerShell 5.1, Bash, and POSIX shells alike.
+        output.args.command =
+          'echo "[graphify] Knowledge graph available. Read graphify-out/GRAPH_REPORT.md for god nodes and architecture context before searching files." ; ' +
+          output.args.command;
+        reminded = true;
+      }
+    },
+  };
+};
+"""
+_KILO_PLUGIN_PATH = Path(".kilo") / "plugins" / "graphify.js"
+_KILO_CONFIG_JSON_PATH = Path(".kilo") / "kilo.json"
+_KILO_CONFIG_JSONC_PATH = Path(".kilo") / "kilo.jsonc"
+def _strip_json_comments(raw: str) -> str:
+    """Remove JSONC-style comments while leaving string content intact."""
+    result: list[str] = []
+    in_string = False
+    escaped = False
+    line_comment = False
+    block_comment = False
+    i = 0
+
+    while i < len(raw):
+        ch = raw[i]
+        nxt = raw[i + 1] if i + 1 < len(raw) else ""
+
+        if line_comment:
+            if ch == "\n":
+                line_comment = False
+                result.append(ch)
+            i += 1
+            continue
+
+        if block_comment:
+            if ch == "*" and nxt == "/":
+                block_comment = False
+                i += 2
+            else:
+                i += 1
+            continue
+
+        if in_string:
+            result.append(ch)
+            if escaped:
+                escaped = False
+            elif ch == "\\":
+                escaped = True
+            elif ch == '"':
+                in_string = False
+            i += 1
+            continue
+
+        if ch == "/" and nxt == "/":
+            line_comment = True
+            i += 2
+            continue
+        if ch == "/" and nxt == "*":
+            block_comment = True
+            i += 2
+            continue
+
+        result.append(ch)
+        if ch == '"':
+            in_string = True
+        i += 1
+
+    return re.sub(r",(\s*[}\]])", r"\1", "".join(result))
+def _load_json_like(config_file: Path) -> dict:
+    if not config_file.exists():
+        return {}
+    try:
+        raw = config_file.read_text(encoding="utf-8")
+        if config_file.suffix == ".jsonc":
+            raw = _strip_json_comments(raw)
+        loaded = json.loads(raw)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return loaded if isinstance(loaded, dict) else {}
+def _kilo_config_path(project_dir: Path) -> Path:
+    kilo_dir = (project_dir or Path(".")) / ".kilo"
+    json_path = kilo_dir / _KILO_CONFIG_JSON_PATH.name
+    if json_path.exists():
+        return json_path
+    jsonc_path = kilo_dir / _KILO_CONFIG_JSONC_PATH.name
+    if jsonc_path.exists():
+        return jsonc_path
+    return json_path
+def _kilo_config_write_path(project_dir: Path) -> Path:
+    """Write automated Kilo edits to kilo.json so existing JSONC stays untouched."""
+    kilo_dir = (project_dir or Path(".")) / ".kilo"
+    return kilo_dir / _KILO_CONFIG_JSON_PATH.name
+def _install_kilo_plugin(project_dir: Path) -> None:
+    """Write graphify.js plugin and register it without rewriting user JSONC."""
+    plugin_file = project_dir / _KILO_PLUGIN_PATH
+    plugin_file.parent.mkdir(parents=True, exist_ok=True)
+    plugin_file.write_text(_KILO_PLUGIN_JS, encoding="utf-8")
+    print(f"  {_KILO_PLUGIN_PATH}  ->  tool.execute.before hook written")
+
+    config_file = _kilo_config_path(project_dir)
+    write_config_file = _kilo_config_write_path(project_dir)
+    write_config_file.parent.mkdir(parents=True, exist_ok=True)
+    config = _load_json_like(config_file)
+    plugins = config.get("plugin")
+    if not isinstance(plugins, list):
+        plugins = []
+        config["plugin"] = plugins
+    entry = plugin_file.resolve().as_uri()
+    if entry not in plugins:
+        plugins.append(entry)
+        write_config_file.write_text(json.dumps(config, indent=2), encoding="utf-8")
+        print(f"  {write_config_file.relative_to(project_dir)}  ->  plugin registered")
+    else:
+        print(
+            f"  {config_file.relative_to(project_dir)}  ->  plugin already registered (no change)"
+        )
+def _uninstall_kilo_plugin(project_dir: Path) -> None:
+    """Remove graphify.js plugin and deregister it without rewriting user JSONC."""
+    plugin_file = project_dir / _KILO_PLUGIN_PATH
+    if plugin_file.exists():
+        plugin_file.unlink()
+        print(f"  {_KILO_PLUGIN_PATH}  ->  removed")
+
+    config_file = _kilo_config_path(project_dir)
+    if not config_file.exists():
+        return
+    write_config_file = _kilo_config_write_path(project_dir)
+    config = _load_json_like(config_file)
+    plugins = config.get("plugin", [])
+    if not isinstance(plugins, list):
+        plugins = []
+    entry = plugin_file.resolve().as_uri()
+    if entry in plugins:
+        config["plugin"] = [plugin for plugin in plugins if plugin != entry]
+        if not config["plugin"]:
+            config.pop("plugin")
+        write_config_file.parent.mkdir(parents=True, exist_ok=True)
+        write_config_file.write_text(json.dumps(config, indent=2), encoding="utf-8")
+        print(
+            f"  {write_config_file.relative_to(project_dir)}  ->  plugin deregistered"
+        )
+# OpenCode tool.execute.before plugin — fires before every tool call.
+# Injects a graph reminder into bash command output when graph.json exists.
+_OPENCODE_PLUGIN_JS = """\
+// graphify OpenCode plugin
+// Injects a knowledge graph reminder before bash tool calls when the graph exists.
+//
+// IMPORTANT: keep the reminder string free of backticks and $(...) constructs.
+// The hook prepends `echo "<reminder>" && <cmd>` to the user's bash command;
+// backticks inside the double-quoted echo trigger bash command substitution,
+// which both corrupts tool output and silently executes the very graphify
+// command we are only suggesting. Plain words render fine in opencode's TUI.
+import { existsSync } from "fs";
+import { join } from "path";
+
+export const GraphifyPlugin = async ({ directory }) => {
+  let reminded = false;
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (reminded) return;
+      if (!existsSync(join(directory, "graphify-out", "graph.json"))) return;
+
+      if (input.tool === "bash") {
+        // ';' not '&&' — Windows PowerShell 5.1 rejects '&&' as a statement
+        // separator, breaking the first bash command of the session (#1646).
+        output.args.command =
+          'echo "[graphify] knowledge graph at graphify-out/. For focused questions, run graphify query with your question (scoped subgraph, usually much smaller than GRAPH_REPORT.md) instead of grepping raw files. Read GRAPH_REPORT.md only for broad architecture context." ; ' +
+          output.args.command;
+        reminded = true;
+      }
+    },
+  };
+};
+"""
+_OPENCODE_PLUGIN_PATH = Path(".opencode") / "plugins" / "graphify.js"
+_OPENCODE_CONFIG_PATH = Path(".opencode") / "opencode.json"
+def _install_opencode_plugin(project_dir: Path) -> None:
+    """Write graphify.js plugin and register it in opencode.json."""
+    plugin_file = project_dir / _OPENCODE_PLUGIN_PATH
+    plugin_file.parent.mkdir(parents=True, exist_ok=True)
+    plugin_file.write_text(_OPENCODE_PLUGIN_JS, encoding="utf-8")
+    print(f"  {_OPENCODE_PLUGIN_PATH}  ->  tool.execute.before hook written")
+
+    config_file = project_dir / _OPENCODE_CONFIG_PATH
+    if config_file.exists():
+        try:
+            config = json.loads(config_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            config = {}
+    else:
+        config = {}
+
+    plugins = config.setdefault("plugin", [])
+    entry = _OPENCODE_PLUGIN_PATH.as_posix()
+    if entry not in plugins:
+        plugins.append(entry)
+        config_file.write_text(json.dumps(config, indent=2), encoding="utf-8")
+        print(f"  {_OPENCODE_CONFIG_PATH}  ->  plugin registered")
+    else:
+        print(f"  {_OPENCODE_CONFIG_PATH}  ->  plugin already registered (no change)")
+def _uninstall_opencode_plugin(project_dir: Path) -> None:
+    """Remove graphify.js plugin and deregister from opencode.json."""
+    plugin_file = project_dir / _OPENCODE_PLUGIN_PATH
+    if plugin_file.exists():
+        plugin_file.unlink()
+        print(f"  {_OPENCODE_PLUGIN_PATH}  ->  removed")
+
+    config_file = project_dir / _OPENCODE_CONFIG_PATH
+    if not config_file.exists():
+        return
+    try:
+        config = json.loads(config_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return
+    plugins = config.get("plugin", [])
+    entry = _OPENCODE_PLUGIN_PATH.as_posix()
+    if entry in plugins:
+        plugins.remove(entry)
+        if not plugins:
+            config.pop("plugin")
+        config_file.write_text(json.dumps(config, indent=2), encoding="utf-8")
+        print(f"  {_OPENCODE_CONFIG_PATH}  ->  plugin deregistered")
+def _resolve_graphify_exe(project: bool = False) -> str:
+    """Return the absolute path to the graphify executable, with forward slashes.
+
+    With *project* set, return the bare ``graphify`` command instead. A
+    project-scoped install writes hook config the installer then tells the user
+    to commit, so an absolute path resolved from the installing machine is wrong
+    for every other clone: it names a directory that does not exist there, and
+    the drive letter and ``.EXE`` casing do not even survive between two Windows
+    checkouts. A committed hook refers to ``graphify`` the way it would refer to
+    ``git`` or ``node``, and PATH resolves it per machine (#3129).
+
+    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).
+
+    The path is normalized to forward slashes so it survives every shell that
+    runs the hook command. On Windows, Claude Code runs command-type hooks
+    through Git Bash by default, where an unquoted backslash is an escape
+    character: a raw ``C:\\Users\\me\\graphify.EXE`` collapses to
+    ``C:Usersmegraphify.EXE: command not found`` and the guard silently fails.
+    Forward slashes are accepted by Git Bash, cmd.exe, and PowerShell alike, and
+    ``.replace`` is a no-op on POSIX where paths already use forward slashes.
+    """
+    import shutil
+    if project:
+        return "graphify"
+    found = shutil.which("graphify")
+    if not 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():
+                found = str(candidate)
+                break
+    return (found or "graphify").replace("\\", "/")
+def _install_codex_hook(project_dir: Path, project: bool = False) -> None:
+    """Add graphify PreToolUse hook to .codex/hooks.json.
+
+    A project-scoped install emits the bare command, since .codex/hooks.json is
+    then committed and an installing machine's path is wrong there (#3129).
+    """
+    hooks_path = project_dir / ".codex" / "hooks.json"
+    hooks_path.parent.mkdir(parents=True, exist_ok=True)
+
+    existing = _read_settings_for_merge(hooks_path)
+
+    graphify_exe = _resolve_graphify_exe(project=project)
+    hook_entry = {
+        "hooks": {
+            "PreToolUse": [
+                {
+                    "matcher": "Bash",
+                    "hooks": [{"type": "command", "command": f"{graphify_exe} hook-check"}],
+                }
+            ]
+        }
+    }
+
+    hooks = existing.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        _refuse_to_modify(hooks_path)
+    pre_tool = hooks.setdefault("PreToolUse", [])
+    if not isinstance(pre_tool, list):
+        _refuse_to_modify(hooks_path)
+    hooks["PreToolUse"] = [h for h in pre_tool if "graphify" not in str(h)]
+    hooks["PreToolUse"].extend(hook_entry["hooks"]["PreToolUse"])
+    _write_settings_with_backup(hooks_path, existing)
+    print(
+        f"  .codex/hooks.json  ->  PreToolUse hook registered ({graphify_exe} hook-check"
+        " - intentional no-op; Codex Desktop rejects additionalContext on PreToolUse,"
+        " so graph guidance comes from AGENTS.md)"
+    )
+
+
+def _uninstall_codex_hook(project_dir: Path) -> None:
+    """Remove graphify 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, platform: str, project: bool = False) -> None:
+    """Write the graphify section to the local AGENTS.md for always-on platforms."""
+    target = (project_dir or Path(".")) / "AGENTS.md"
+
+    if target.exists():
+        content = target.read_text(encoding="utf-8")
+        new_content = _replace_or_append_section(
+            content, _AGENTS_MD_MARKER, _always_on("agents-md")
+        )
+    else:
+        new_content = _always_on("agents-md")
+
+    if target.exists() and new_content == target.read_text(encoding="utf-8"):
+        print(f"graphify already configured in {target.resolve()} (no change)")
+    else:
+        target.write_text(new_content, encoding="utf-8")
+        print(f"graphify section written to {target.resolve()}")
+
+    if platform == "codex":
+        _install_codex_hook(project_dir or Path("."), project=project)
+    elif platform == "opencode":
+        _install_opencode_plugin(project_dir or Path("."))
+    elif platform == "kilo":
+        _install_kilo_plugin(project_dir or Path("."))
+
+    print()
+    print(
+        f"{platform.capitalize()} will now check the knowledge graph before answering"
+    )
+    print("codebase questions and rebuild it after code changes.")
+    if platform not in ("codex", "opencode", "kilo"):
+        print()
+        print("Note: unlike Claude Code, there is no PreToolUse hook equivalent for")
+        print(
+            f"{platform.capitalize()} — the AGENTS.md rules are the always-on mechanism."
+        )
+def _amp_legacy_cleanup() -> None:
+    """Best-effort removal of the pre-fix ~/.amp/skills/graphify install dir.
+
+    Older graphify versions wrote the Amp skill to ~/.amp/skills, which Amp does
+    not search. Clean it up on install so a stale, never-loaded copy does not
+    linger. Failures are ignored (the new path is what matters).
+    """
+    legacy = Path.home() / ".amp" / "skills" / "graphify"
+    if legacy.exists():
+        shutil.rmtree(legacy, ignore_errors=True)
+        if not legacy.exists():
+            print(f"  legacy removed   ->  {legacy}")
+def _amp_install(project_dir: Path | None = None) -> None:
+    """User-scope Amp install: skill into ~/.config/agents/skills + AGENTS.md."""
+    _amp_legacy_cleanup()
+    _copy_skill_file("amp")
+    _agents_install(project_dir or Path("."), "amp")
+def _amp_uninstall(project_dir: Path | None = None) -> None:
+    """User-scope Amp uninstall: remove the skill and the AGENTS.md section."""
+    removed = _remove_skill_file("amp")
+    if removed:
+        print("skill removed")
+    _agents_uninstall(project_dir or Path("."), platform="amp")
+def _agents_platform_install(project_dir: Path | None = None) -> None:
+    """`graphify agents install`: skill into ~/.agents/skills + AGENTS.md.
+
+    The amp-twin of the generic Agent-Skills target. Mirrors _amp_install but
+    lands the skill at the spec's user-global ~/.agents/skills (set in
+    _platform_skill_destination). Wiring AGENTS.md keeps it honest with the
+    rendered hooks reference, which points at `graphify agents install`. The bare
+    `graphify install --platform agents` path stays skill-only (via install()),
+    exactly as amp's `--platform amp` does.
+    """
+    _copy_skill_file("agents")
+    _agents_install(project_dir or Path("."), "agents")
+def _agents_platform_uninstall(project_dir: Path | None = None) -> None:
+    """`graphify agents uninstall`: remove the skill and the AGENTS.md section."""
+    removed = _remove_skill_file("agents")
+    if removed:
+        print("skill removed")
+    _agents_uninstall(project_dir or Path("."), platform="agents")
+def _project_install(platform_name: str, project_dir: Path | None = None, strict: bool = False) -> None:
+    """Install platform skill/config files in the current project."""
+    project_dir = project_dir or Path(".")
+    platform_name = _canonical_platform(platform_name)
+    if platform_name in ("claude", "windows"):
+        install(platform=platform_name, project=True, project_dir=project_dir)
+        claude_install(project_dir, strict=strict, project=True)
+        _print_project_git_add_hint([project_dir / ".claude", project_dir / "CLAUDE.md"])
+    elif platform_name == "gemini":
+        gemini_install(project_dir, project=True)
+    elif platform_name == "cursor":
+        _cursor_install(project_dir)
+        _print_project_git_add_hint([project_dir / ".cursor"])
+    elif platform_name == "kiro":
+        _kiro_install(project_dir)
+        _print_project_git_add_hint([project_dir / ".kiro"])
+    elif platform_name in ("aider", "amp", "codex", "opencode", "claw", "droid", "trae", "trae-cn", "hermes"):
+        skill_dst = _copy_skill_file(platform_name, project=True, project_dir=project_dir)
+        _agents_install(project_dir, platform_name, project=True)
+        hint_paths = [_project_scope_root(skill_dst, project_dir), project_dir / "AGENTS.md"]
+        if platform_name == "opencode":
+            hint_paths.append(project_dir / ".opencode")
+        elif platform_name == "codex":
+            hint_paths.append(project_dir / ".codex")
+        _print_project_git_add_hint(hint_paths)
+    elif platform_name == "devin":
+        skill_dst = _copy_skill_file("devin", project=True, project_dir=project_dir)
+        _devin_rules_install(project_dir)
+        _print_project_git_add_hint([_project_scope_root(skill_dst, project_dir), project_dir / ".windsurf"])
+    elif platform_name == "antigravity":
+        # Project-scoped: skill in .agents/skills/ PLUS the .agents/rules +
+        # .agents/workflows always-on layer (previously this path wrote only the
+        # skill, leaving the rules/workflows the uninstall path removes unset).
+        skill_dst = _copy_skill_file("antigravity", project=True, project_dir=project_dir)
+        _antigravity_finalize(skill_dst, project_dir)
+        _print_project_git_add_hint([_project_scope_root(skill_dst, project_dir), project_dir / ".agents"])
+    elif platform_name in ("copilot", "pi", "kimi", "agents"):
+        # Skill-only project install: drop SKILL.md (+ references) at the scope
+        # root. `agents` -> ./.agents/skills/graphify/SKILL.md.
+        skill_dst = _copy_skill_file(platform_name, project=True, project_dir=project_dir)
+        _print_project_git_add_hint([_project_scope_root(skill_dst, project_dir)])
+    else:
+        install(platform=platform_name, project=True, project_dir=project_dir)
+def _project_uninstall(platform_name: str, project_dir: Path | None = None) -> None:
+    """Remove project-scoped platform skill/config files only."""
+    project_dir = project_dir or Path(".")
+    platform_name = _canonical_platform(platform_name)
+    if platform_name in ("claude", "windows"):
+        _remove_skill_file(platform_name, project=True, project_dir=project_dir)
+        _remove_claude_skill_registration(project_dir)
+        claude_uninstall(project_dir, project=True)
+    elif platform_name == "gemini":
+        gemini_uninstall(project_dir, project=True)
+    elif platform_name == "cursor":
+        _cursor_uninstall(project_dir)
+    elif platform_name == "kiro":
+        _kiro_uninstall(project_dir)
+    elif platform_name in ("aider", "amp", "codex", "opencode", "claw", "droid", "trae", "trae-cn", "hermes"):
+        _remove_skill_file(platform_name, project=True, project_dir=project_dir)
+        _agents_uninstall(project_dir, platform=platform_name)
+        if platform_name == "codex":
+            _uninstall_codex_hook(project_dir)
+    elif platform_name == "antigravity":
+        _antigravity_uninstall(project_dir, project=True)
+    elif platform_name == "devin":
+        removed = _remove_skill_file("devin", project=True, project_dir=project_dir)
+        _devin_rules_uninstall(project_dir)
+        if not removed:
+            print("nothing to remove")
+    elif platform_name in ("copilot", "pi", "kimi", "agents"):
+        removed = _remove_skill_file(platform_name, project=True, project_dir=project_dir)
+        if not removed:
+            print("nothing to remove")
+    elif platform_name == "codebuddy":
+        # project=True keeps `uninstall --project` project-scoped; previously
+        # this deleted the user-global codebuddy skill (#2215).
+        codebuddy_uninstall(project_dir, project=True)
+    else:
+        _remove_skill_file(platform_name, project=True, project_dir=project_dir)
+def _project_uninstall_all(project_dir: Path | None = None) -> None:
+    """Remove project-scoped install files without touching user-scope installs."""
+    project_dir = project_dir or Path(".")
+    print("Uninstalling project-scoped graphify files...\n")
+    for platform_name in _PLATFORM_CONFIG:
+        _project_uninstall(platform_name, project_dir)
+    for platform_name in ("gemini", "cursor"):
+        _project_uninstall(platform_name, project_dir)
+    print("\nDone.")
+def _agents_uninstall(project_dir: Path, platform: str = "") -> None:
+    """Remove the graphify 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")
+        if platform == "opencode":
+            _uninstall_opencode_plugin(project_dir or Path("."))
+        elif platform == "kilo":
+            _uninstall_kilo_plugin(project_dir or Path("."))
+        return
+
+    content = target.read_text(encoding="utf-8")
+    cleaned = _remove_marker_section(content, _AGENTS_MD_MARKER)
+    if cleaned is None:
+        print("graphify section not found in AGENTS.md - nothing to do")
+        if platform == "opencode":
+            _uninstall_opencode_plugin(project_dir or Path("."))
+        elif platform == "kilo":
+            _uninstall_kilo_plugin(project_dir or Path("."))
+        return
+
+    if cleaned:
+        target.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"graphify section removed from {target.resolve()}")
+    else:
+        target.unlink()
+        print(f"AGENTS.md was empty after removal - deleted {target.resolve()}")
+
+    if platform == "opencode":
+        _uninstall_opencode_plugin(project_dir or Path("."))
+    elif platform == "kilo":
+        _uninstall_kilo_plugin(project_dir or Path("."))
+def _kilo_uninstall_global() -> list[str]:
+    removed = []
+    command_dst = Path.home() / ".config" / "kilo" / "command" / "graphify.md"
+    if command_dst.exists():
+        command_dst.unlink()
+        removed.append(f"command removed: {command_dst}")
+    try:
+        command_dst.parent.rmdir()
+    except OSError:
+        pass
+
+    skill_dst = Path.home() / _PLATFORM_CONFIG["kilo"]["skill_dst"]
+    if skill_dst.exists():
+        skill_dst.unlink()
+        removed.append(f"skill removed: {skill_dst}")
+    version_file = skill_dst.parent / ".graphify_version"
+    if version_file.exists():
+        version_file.unlink()
+    for d in (
+        skill_dst.parent,
+        skill_dst.parent.parent,
+        skill_dst.parent.parent.parent,
+    ):
+        try:
+            d.rmdir()
+        except OSError:
+            break
+
+    return removed
+def _kilo_install(project_dir: Path) -> None:
+    """Install native Kilo skill + command globally and always-on project wiring locally."""
+    install(platform="kilo")
+    _agents_install(project_dir or Path("."), "kilo")
+def _kilo_uninstall(project_dir: Path) -> None:
+    """Remove Kilo always-on project wiring and global skill/command files."""
+    _agents_uninstall(project_dir or Path("."), platform="kilo")
+    removed = _kilo_uninstall_global()
+    print("; ".join(removed) if removed else "nothing to remove")
+def claude_install(project_dir: Path | None = None, strict: bool = False, project: bool = False) -> None:
+    """Write the graphify section to the local CLAUDE.md."""
+    target = (project_dir or Path(".")) / "CLAUDE.md"
+
+    if target.exists():
+        content = target.read_text(encoding="utf-8")
+        new_content = _replace_or_append_section(
+            content, _CLAUDE_MD_MARKER, _always_on("claude-md")
+        )
+    else:
+        new_content = _always_on("claude-md")
+
+    if target.exists() and new_content == target.read_text(encoding="utf-8"):
+        print(f"graphify already configured in {target.resolve()} (no change)")
+    else:
+        target.write_text(new_content, encoding="utf-8")
+        print(f"graphify section written to {target.resolve()}")
+
+    # Always re-install the Claude Code PreToolUse hook so an old hook
+    # payload (e.g. pre-issue-#580 wording) is replaced on upgrade.
+    _install_claude_hook(project_dir or Path("."), strict=strict, project=project)
+
+    print()
+    print("Claude Code will now check the knowledge graph before answering")
+    print("codebase questions and rebuild it after code changes.")
+    if strict:
+        print("Strict mode: the first raw file read per session is blocked until")
+        print("one `graphify query` runs (toggle with GRAPHIFY_HOOK_STRICT=0).")
+def _install_claude_hook(project_dir: Path, strict: bool = False, project: bool = False) -> None:
+    """Add graphify PreToolUse hook to .claude/settings.json.
+
+    A project-scoped install emits the bare command, since .claude/settings.json
+    is then committed and an installing machine's path is wrong there (#3129).
+    """
+    settings_path = project_dir / ".claude" / "settings.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    settings = _read_settings_for_merge(settings_path)
+
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        _refuse_to_modify(settings_path)
+    pre_tool = hooks.setdefault("PreToolUse", [])
+    if not isinstance(pre_tool, list):
+        _refuse_to_modify(settings_path)
+
+    hooks["PreToolUse"] = [h for h in pre_tool if not (isinstance(h, dict) and h.get("matcher") in ("Glob|Grep", "Bash", "Bash|Grep", "Read|Glob") and "graphify" in str(h))]
+    hooks["PreToolUse"].extend(_claude_pretooluse_hooks(strict=strict, project=project))
+    _write_settings_with_backup(settings_path, settings)
+    _mode = " (strict)" if strict else ""
+    print(f"  .claude/settings.json  ->  PreToolUse hooks registered (Bash|Grep search + Read/Glob){_mode}")
+def _uninstall_claude_hook(project_dir: Path) -> None:
+    """Remove the graphify PreToolUse hook from .claude/settings.json and its
+    local-only sibling .claude/settings.local.json.
+
+    A user may relocate the hook into settings.local.json so it is not committed
+    to a shared repo, so uninstall has to clean whichever file holds it (#1731).
+    """
+    claude_dir = project_dir / ".claude"
+    for name in ("settings.json", "settings.local.json"):
+        _strip_graphify_hook(claude_dir / name)
+def _strip_graphify_hook(settings_path: Path) -> None:
+    """Drop graphify PreToolUse hooks from a single Claude settings file, if present."""
+    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", "Bash|Grep", "Read|Glob") 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_path.name}  ->  PreToolUse hook removed")
+def uninstall_all(project_dir: Path | None = None, purge: bool = False) -> None:
+    """Remove graphify from every platform detected in the current project."""
+    pd = project_dir or Path(".")
+    print("Uninstalling graphify from all detected platforms...\n")
+
+    # Skill-file / config-section uninstallers. remove_user_skill=True keeps the
+    # historical `graphify uninstall` behavior: global skill delete plus md/hook
+    # cleanup at the project dir (#2215).
+    claude_uninstall(pd, remove_user_skill=True)
+    codebuddy_uninstall(pd, remove_user_skill=True)
+    gemini_uninstall(pd, remove_user_skill=True)
+    vscode_uninstall(pd)
+    _cursor_uninstall(pd)
+    _kiro_uninstall(pd)
+    _antigravity_uninstall(pd)
+    # AGENTS.md covers: codex, aider, opencode, claw, droid, trae, trae-cn, hermes, copilot
+    _agents_uninstall(pd)
+    # Amp also drops a user-scope skill at ~/.config/agents/skills, which the
+    # AGENTS.md cleanup above does not touch.
+    _remove_skill_file("amp")
+    # The generic agents platform's user-scope skill lives at ~/.agents/skills,
+    # which neither the AGENTS.md cleanup nor amp's removal reaches.
+    _remove_skill_file("agents")
+    _uninstall_opencode_plugin(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(f"\n  {_GRAPHIFY_OUT}/  ->  not found (nothing to purge)")
+
+    print("\nDone. Run 'pip uninstall graphifyy' to remove the package itself.")
+def claude_uninstall(project_dir: Path | None = None, *, project: bool = False, remove_user_skill: bool | None = None) -> None:
+    """Remove the graphify skill tree (SKILL.md + references/) and the graphify
+    section from CLAUDE.md and its local-only variants, plus the PreToolUse hook.
+
+    Mirrors gemini_uninstall: the bare `graphify uninstall` and `graphify claude
+    uninstall` must remove the installed skill, not just strip CLAUDE.md, or the
+    progressive-disclosure tree (SKILL.md + references/) is orphaned (#1121).
+
+    A user may relocate the section/hook into the local-only files Claude Code
+    supports so they are not committed to a shared repo, so uninstall also cleans
+    CLAUDE.local.md, .claude/CLAUDE.local.md and .claude/settings.local.json (#1731).
+
+    Scope rules (#2215): a bare call removes the user-global skill; passing
+    ``project_dir`` (or ``project=True``) scopes skill removal to that project
+    and leaves the global tree untouched, unless ``remove_user_skill=True``
+    explicitly opts back into the global delete (as ``uninstall_all`` does).
+    """
+    explicit_dir = project_dir is not None
+    project_dir = project_dir or Path(".")
+    if remove_user_skill is None:
+        remove_user_skill = not project and not explicit_dir
+    if project or (explicit_dir and not remove_user_skill):
+        _remove_skill_file("claude", project=True, project_dir=project_dir)
+    if remove_user_skill:
+        _remove_skill_file("claude", project=False)
+
+    md_targets = [
+        project_dir / "CLAUDE.md",
+        project_dir / "CLAUDE.local.md",
+        project_dir / ".claude" / "CLAUDE.local.md",
+    ]
+    existing = [t for t in md_targets if t.exists()]
+    removed_any = False
+    for target in existing:
+        # Not short-circuited: every present file must be cleaned, not just the first.
+        if _strip_graphify_md_section(target):
+            removed_any = True
+
+    if not existing:
+        print("No CLAUDE.md found in current directory - nothing to do")
+    elif not removed_any:
+        print("graphify section not found in CLAUDE.md - nothing to do")
+
+    _uninstall_claude_hook(project_dir)
+def _strip_graphify_md_section(target: Path) -> bool:
+    """Strip the ## graphify section from one CLAUDE.md-style file.
+
+    Returns True if a section was removed. Deletes the file if nothing else
+    remains after removal.
+    """
+    try:
+        content = target.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        # An unreadable/undecodable CLAUDE.md-style file (e.g. non-UTF-8, or a
+        # directory of that name) must not abort uninstall - nothing to strip.
+        return False
+    # Remove graphify's ## graphify section (heading matched exactly, never as a
+    # substring of a user's ### graphify) from the marker to the next H2 or EOF.
+    cleaned = _remove_marker_section(content, _CLAUDE_MD_MARKER)
+    if cleaned is None:
+        return False
+    if cleaned:
+        target.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"graphify section removed from {target.resolve()}")
+    else:
+        target.unlink()
+        print(f"{target.name} was empty after removal - deleted {target.resolve()}")
+    return True
+def codebuddy_install(project_dir: Path | None = None) -> None:
+    """Install the graphify skill and CODEBUDDY.md section for CodeBuddy."""
+    _copy_skill_file("codebuddy", project=bool(project_dir), project_dir=project_dir)
+    target = (project_dir or Path(".")) / "CODEBUDDY.md"
+
+    if target.exists():
+        content = target.read_text(encoding="utf-8")
+        new_content = _replace_or_append_section(
+            content, _CODEBUDDY_MD_MARKER, _always_on("claude-md")
+        )
+    else:
+        new_content = _always_on("claude-md")
+
+    if target.exists() and new_content == target.read_text(encoding="utf-8"):
+        print(f"graphify already configured in {target.resolve()} (no change)")
+    else:
+        target.write_text(new_content, encoding="utf-8")
+        print(f"graphify section written to {target.resolve()}")
+
+    # Also write CodeBuddy PreToolUse hook to .codebuddy/settings.json
+    _install_codebuddy_hook(project_dir or Path("."))
+
+    print()
+    print("CodeBuddy will now check the knowledge graph before answering")
+    print("codebase questions and rebuild it after code changes.")
+def _install_codebuddy_hook(project_dir: Path) -> None:
+    """Add graphify PreToolUse hook to .codebuddy/settings.json."""
+    settings_path = project_dir / ".codebuddy" / "settings.json"
+    settings_path.parent.mkdir(parents=True, exist_ok=True)
+
+    settings = _read_settings_for_merge(settings_path)
+
+    hooks = settings.setdefault("hooks", {})
+    if not isinstance(hooks, dict):
+        _refuse_to_modify(settings_path)
+    pre_tool = hooks.setdefault("PreToolUse", [])
+    if not isinstance(pre_tool, list):
+        _refuse_to_modify(settings_path)
+
+    hooks["PreToolUse"] = [h for h in pre_tool if not (isinstance(h, dict) and h.get("matcher") in ("Glob|Grep", "Bash", "Bash|Grep", "Read|Glob") and "graphify" in str(h))]
+    hooks["PreToolUse"].extend(_claude_pretooluse_hooks())
+    _write_settings_with_backup(settings_path, settings)
+    print(f"  .codebuddy/settings.json  ->  PreToolUse hooks registered")
+def _uninstall_codebuddy_hook(project_dir: Path) -> None:
+    """Remove graphify PreToolUse hook from .codebuddy/settings.json."""
+    settings_path = project_dir / ".codebuddy" / "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", "Bash|Grep", "Read|Glob") 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"  .codebuddy/settings.json  ->  PreToolUse hook removed")
+def codebuddy_uninstall(project_dir: Path | None = None, *, project: bool = False, remove_user_skill: bool | None = None) -> None:
+    """Remove the graphify skill tree (SKILL.md + references/) and the CODEBUDDY.md section.
+
+    Scope rules (#2215): a bare call removes the user-global skill; passing
+    ``project_dir`` (or ``project=True``) scopes skill removal to that project
+    and leaves the global tree untouched, unless ``remove_user_skill=True``
+    explicitly opts back into the global delete (as ``uninstall_all`` does).
+    """
+    explicit_dir = project_dir is not None
+    project_dir = project_dir or Path(".")
+    if remove_user_skill is None:
+        remove_user_skill = not project and not explicit_dir
+    if project or (explicit_dir and not remove_user_skill):
+        _remove_skill_file("codebuddy", project=True, project_dir=project_dir)
+    if remove_user_skill:
+        _remove_skill_file("codebuddy", project=False)
+    target = project_dir / "CODEBUDDY.md"
+
+    if not target.exists():
+        print("No CODEBUDDY.md found in current directory - nothing to do")
+        return
+
+    content = target.read_text(encoding="utf-8")
+    cleaned = _remove_marker_section(content, _CODEBUDDY_MD_MARKER)
+    if cleaned is None:
+        print("graphify section not found in CODEBUDDY.md - nothing to do")
+        return
+
+    if cleaned:
+        target.write_text(cleaned + "\n", encoding="utf-8")
+        print(f"graphify section removed from {target.resolve()}")
+    else:
+        target.unlink()
+        print(f"CODEBUDDY.md was empty after removal - deleted {target.resolve()}")
+
+    _uninstall_codebuddy_hook(project_dir or Path("."))
+
+
+_CLI_INSTALL_COMMANDS = frozenset({
+    "agents",
+    "aider",
+    "amp",
+    "antigravity",
+    "claude",
+    "claw",
+    "codebuddy",
+    "codex",
+    "copilot",
+    "cursor",
+    "devin",
+    "droid",
+    "gemini",
+    "hermes",
+    "install",
+    "kilo",
+    "kiro",
+    "opencode",
+    "pi",
+    "skills",
+    "trae",
+    "trae-cn",
+    "uninstall",
+    "vscode",
+})
+
+
+def dispatch_install_cli(cmd: str) -> bool:
+    """Handle `graphify <install-command>` dispatch (install/uninstall + every
+    per-platform install target). Returns True if cmd was an install command and
+    was handled, False otherwise so the caller can continue its own dispatch.
+    Moved verbatim from __main__.main().
+    """
+    if cmd not in _CLI_INSTALL_COMMANDS:
+        return False
+    if cmd == "install":
+        # Default to windows platform on Windows, claude elsewhere
+        default_platform = "windows" if platform.system() == "Windows" else "claude"
+        selected_platform: str | None = None
+        project_scope = False
+        strict = False
+        args = sys.argv[2:]
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            if arg in ("-h", "--help"):
+                _print_install_usage()
+                return True
+            if arg == "--project":
+                project_scope = True
+                i += 1
+            elif arg == "--strict":
+                strict = True
+                i += 1
+            elif 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
+        if project_scope:
+            _project_install(chosen_platform, Path("."), strict=strict)
+        else:
+            if strict:
+                print(
+                    "note: --strict applies to the project PreToolUse hook; run "
+                    "`graphify install --project --strict` or `graphify claude install --strict`.",
+                    file=sys.stderr,
+                )
+            install(platform=chosen_platform)
+    elif cmd == "uninstall":
+        args = sys.argv[2:]
+        purge = "--purge" in args
+        project_scope = "--project" in args
+        selected_platform = None
+        i = 0
+        while i < len(args):
+            arg = args[i]
+            if arg in ("--purge", "--project"):
+                i += 1
+            elif arg.startswith("--platform="):
+                selected_platform = arg.split("=", 1)[1]
+                i += 1
+            elif arg == "--platform":
+                if i + 1 >= len(args):
+                    print("error: --platform requires a value", file=sys.stderr)
+                    sys.exit(1)
+                selected_platform = args[i + 1]
+                i += 2
+            elif arg.startswith("-"):
+                print(f"error: unknown uninstall option '{arg}'", file=sys.stderr)
+                sys.exit(1)
+            else:
+                selected_platform = arg
+                i += 1
+        if project_scope:
+            if selected_platform:
+                _project_uninstall(selected_platform, Path("."))
+            else:
+                _project_uninstall_all(Path("."))
+        else:
+            uninstall_all(purge=purge)
+    elif cmd == "claude":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            _strict = "--strict" in sys.argv[3:]
+            if "--project" in sys.argv[3:]:
+                _project_install("claude", Path("."), strict=_strict)
+            else:
+                claude_install(strict=_strict)
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall("claude", Path("."))
+            else:
+                claude_uninstall()
+        else:
+            print("Usage: graphify claude [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "codebuddy":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            codebuddy_install()
+        elif subcmd == "uninstall":
+            codebuddy_uninstall()
+        else:
+            print("Usage: graphify codebuddy [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "gemini":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            gemini_install(project=("--project" in sys.argv[3:]))
+        elif subcmd == "uninstall":
+            gemini_uninstall(project=("--project" in sys.argv[3:]))
+        else:
+            print("Usage: graphify gemini [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "cursor":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            _cursor_install(Path("."))
+        elif subcmd == "uninstall":
+            _cursor_uninstall(Path("."))
+        else:
+            print("Usage: graphify cursor [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "vscode":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            vscode_install()
+        elif subcmd == "uninstall":
+            vscode_uninstall()
+        else:
+            print("Usage: graphify vscode [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "copilot":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            if "--project" in sys.argv[3:]:
+                _project_install("copilot", Path("."))
+            else:
+                install(platform="copilot")
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall("copilot", Path("."))
+            else:
+                removed = _remove_skill_file("copilot")
+                print("skill removed" if removed else "nothing to remove")
+        else:
+            print("Usage: graphify copilot [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "kilo":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            _kilo_install(Path("."))
+        elif subcmd == "uninstall":
+            _kilo_uninstall(Path("."))
+        else:
+            print("Usage: graphify kilo [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "kiro":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            _kiro_install(Path("."))
+        elif subcmd == "uninstall":
+            _kiro_uninstall(Path("."))
+        else:
+            print("Usage: graphify kiro [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "devin":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            if "--project" in sys.argv[3:]:
+                _project_install("devin", Path("."))
+            else:
+                install(platform="devin")
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall("devin", Path("."))
+            else:
+                removed = _remove_skill_file("devin")
+                print("skill removed" if removed else "nothing to remove")
+        else:
+            print("Usage: graphify devin [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "pi":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            if "--project" in sys.argv[3:]:
+                _project_install("pi", Path("."))
+            else:
+                install("pi")
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall("pi", Path("."))
+            else:
+                _remove_skill_file("pi")
+        else:
+            print("Usage: graphify pi [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "amp":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            if "--project" in sys.argv[3:]:
+                _project_install("amp", Path("."))
+            else:
+                _amp_install(Path("."))
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall("amp", Path("."))
+            else:
+                _amp_uninstall(Path("."))
+        else:
+            print("Usage: graphify amp [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd in ("agents", "skills"):
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            if "--project" in sys.argv[3:]:
+                _project_install("agents", Path("."))
+            else:
+                _agents_platform_install(Path("."))
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall("agents", Path("."))
+            else:
+                _agents_platform_uninstall(Path("."))
+        else:
+            print(f"Usage: graphify {cmd} [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd in ("aider", "codex", "opencode", "claw", "droid", "trae", "trae-cn", "hermes"):
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            if "--project" in sys.argv[3:]:
+                _project_install(cmd, Path("."))
+            else:
+                _agents_install(Path("."), cmd)
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall(cmd, Path("."))
+            else:
+                _agents_uninstall(Path("."), platform=cmd)
+                if cmd == "codex":
+                    _uninstall_codex_hook(Path("."))
+        else:
+            print(f"Usage: graphify {cmd} [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    elif cmd == "antigravity":
+        subcmd = sys.argv[2] if len(sys.argv) > 2 else ""
+        if subcmd == "install":
+            if "--project" in sys.argv[3:]:
+                _project_install("antigravity", Path("."))
+            else:
+                _antigravity_install(Path("."))
+        elif subcmd == "uninstall":
+            if "--project" in sys.argv[3:]:
+                _project_uninstall("antigravity", Path("."))
+            else:
+                _antigravity_uninstall(Path("."))
+        else:
+            print("Usage: graphify antigravity [install|uninstall]", file=sys.stderr)
+            sys.exit(1)
+    return True