adl-toolkit 0.0.0-stage → 0.1.1

package/scripts/install_toolkit.py

@@ -0,0 +1,3584 @@
+#!/usr/bin/env python3
+"""Install one graph tool and optional agent skills into a project."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import hashlib
+import json
+import os
+import queue
+import re
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+import tempfile
+import time
+from urllib.request import Request, urlopen
+from collections import deque
+from dataclasses import dataclass, replace
+from http.client import HTTPException
+from pathlib import Path, PureWindowsPath
+from typing import Callable, Sequence
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+CODEGRAPH_PACKAGE = "@colbymchenry/codegraph@1.6.1"
+GITNEXUS_PACKAGE = "gitnexus@1.6.12"
+GRAPHIFY_PACKAGE = "graphifyy[mcp,sql,pdf,openai]==0.9.80"
+SKILLS_PACKAGE = "skills@1.7.0"
+UV_VERSION = "0.12.24"
+ADDON_SOURCES = {
+    "caveman": "JuliusBrussee/caveman",
+    "ponytail": "DietrichGebert/ponytail",
+}
+SKILLS_AGENT = {
+    "codex": "codex", "claude": "claude-code", "cursor": "cursor",
+    "antigravity": "antigravity",
+}
+CLIENTS = ("codex", "claude", "cursor", "antigravity")
+GRAPHS = ("adl-drift", "codegraph", "gitnexus", "graphify", "other")
+EXTRAS = ("http", "embeddings")
+MANIFEST_VERSION = 1
+MANIFEST_PATH = Path(".adl-toolkit/install.json")
+MANAGED_FILES = (
+    Path(".mcp.json"), Path(".codex/config.toml"), Path(".cursor/mcp.json"),
+    Path("AGENTS.md"), Path("skills-lock.json"),
+)
+MANAGED_ROOTS = (
+    Path(".agents/skills"), Path(".claude/skills"), Path(".cursor/skills"),
+    Path(".cursor/rules"), Path(".agents/rules"),
+)
+ANTIGRAVITY_CONFIGS = {
+    "unified": Path(".gemini/config/mcp_config.json"),
+    "legacy": Path(".gemini/antigravity/mcp_config.json"),
+}
+ANTIGRAVITY_MIGRATED_MARKER = Path(".gemini/config/.migrated")
+RUNTIME_PATHS = {
+    "adl-drift": Path(".adl-toolkit/venv"),
+    "other": Path(".adl-toolkit/venv"),
+    "codegraph": Path(".adl-toolkit/codegraph"),
+    "gitnexus": Path(".adl-toolkit/gitnexus"),
+    "graphify": Path(".adl-toolkit/venv"),
+}
+INDEX_PATHS = {
+    "adl-drift": (Path(".adl-drift"), Path(".drift")),
+    "codegraph": (Path(".codegraph"),),
+    "gitnexus": (Path(".gitnexus"),),
+    "graphify": (Path("graphify-out"),),
+    "other": (),
+}
+INTEGRATION_INSTRUCTION_PATHS = {
+    "codex": Path("AGENTS.md"),
+    "claude": Path("CLAUDE.md"),
+    "cursor": Path(".cursor/rules/adl-toolkit-integrations.mdc"),
+    "antigravity": Path("AGENTS.md"),
+}
+INTEGRATION_SKILL_ROOTS = {
+    "codex": Path(".agents/skills"),
+    "claude": Path(".claude/skills"),
+    "cursor": Path(".cursor/skills"),
+    "antigravity": Path(".agents/skills"),
+}
+INTEGRATION_BEGIN = "<!-- BEGIN ADL TOOLKIT INTEGRATIONS -->"
+INTEGRATION_END = "<!-- END ADL TOOLKIT INTEGRATIONS -->"
+CLIENT_CONFIG_PATHS = {
+    "codex": Path(".codex/config.toml"),
+    "claude": Path(".mcp.json"),
+    "cursor": Path(".cursor/mcp.json"),
+}
+
+
+class InstallError(RuntimeError):
+    """An installation step failed."""
+
+
+@dataclass(frozen=True)
+class Options:
+    graph: str
+    project: Path
+    client: str = "codex"
+    addons: tuple[str, ...] = ()
+    extras: tuple[str, ...] = ()
+    package: str | None = None
+    index: bool = True
+    dry_run: bool = False
+    clients: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class UninstallOptions:
+    project: Path
+    graph: str | None = None
+    client: str | None = None
+    addons: tuple[str, ...] = ()
+    yes: bool = False
+    dry_run: bool = False
+    purge_index: bool = False
+    remove_clients: tuple[str, ...] = ()
+    remove_addons: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class Step:
+    label: str
+    command: tuple[str, ...]
+    cwd: Path
+    timeout: float = 900
+    owner: str = "graph"
+    quiet: bool = False
+    client: str | None = None
+
+
+@dataclass(frozen=True)
+class HealthCheck:
+    category: str
+    name: str
+    state: str
+    detail: str
+    action: str | None = None
+
+
+@dataclass(frozen=True)
+class HealthReport:
+    project: Path
+    graph: str | None
+    clients: tuple[str, ...]
+    addons: tuple[str, ...]
+    checks: tuple[HealthCheck, ...]
+
+    @property
+    def healthy(self) -> bool:
+        return all(check.state != "error" for check in self.checks)
+
+
+def _venv_executable(project: Path, name: str) -> Path:
+    directory = "Scripts" if os.name == "nt" else "bin"
+    suffix = ".exe" if os.name == "nt" else ""
+    return project / ".adl-toolkit" / "venv" / directory / f"{name}{suffix}"
+
+
+def _codegraph_executable(project: Path) -> Path:
+    suffix = ".cmd" if os.name == "nt" else ""
+    return (
+        project
+        / ".adl-toolkit"
+        / "codegraph"
+        / "node_modules"
+        / ".bin"
+        / f"codegraph{suffix}"
+    )
+
+
+def _codegraph_global_step(project: Path, label: str) -> Step:
+    return Step(
+        label,
+        (
+            "npm", "install", "--global", "--bin-links=true", "--no-audit", "--no-fund",
+            CODEGRAPH_PACKAGE,
+        ),
+        project,
+        1800,
+    )
+
+
+def _gitnexus_executable(project: Path) -> Path:
+    suffix = ".cmd" if os.name == "nt" else ""
+    return project / RUNTIME_PATHS["gitnexus"] / "node_modules" / ".bin" / f"gitnexus{suffix}"
+
+
+def _graphify_global_step(project: Path) -> Step:
+    return Step(
+        "Set up uv and Graphify terminal command",
+        (sys.executable, str(REPO_ROOT / "scripts/install_toolkit.py"),
+         "setup-graphify-global", "--project", str(project)),
+        project, 1800,
+    )
+
+
+def _managed_mcp_entry(graph: str, project: Path) -> dict[str, object]:
+    if graph == "gitnexus":
+        return {"command": str(_gitnexus_executable(project)), "args": ["mcp"]}
+    if graph == "graphify":
+        return {
+            "command": str(_venv_executable(project, "python")),
+            "args": ["-m", "graphify.serve", str(project / "graphify-out" / "graph.json")],
+        }
+    raise InstallError(f"Unsupported managed MCP tool: {graph}")
+
+
+def _graphify_command(command: Sequence[str]) -> str:
+    if os.name == "nt":
+        return "& " + " ".join("'" + arg.replace("'", "''") + "'" for arg in command)
+    return shlex.join(command)
+
+
+def _graphify_skill(project: Path, client: str) -> tuple[Path, str]:
+    relative = INTEGRATION_SKILL_ROOTS[client] / "graphify" / "SKILL.md"
+    executable = str(_venv_executable(project, "graphify"))
+    graph = str(project / "graphify-out" / "graph.json")
+    commands = (
+        ("Build or refresh the code graph", (executable, "extract", str(project), "--code-only", "--out", str(project))),
+        ("Generate the report and visualization", (executable, "cluster-only", str(project), "--no-label")),
+        ("Query", (executable, "query", "<question>", "--graph", graph)),
+        ("Explain", (executable, "explain", "<entity>", "--graph", graph)),
+        ("Trace a path", (executable, "path", "<A>", "<B>", "--graph", graph)),
+    )
+    content = (
+        "---\nname: graphify\ndescription: Use Graphify to index code, explore architecture, "
+        "query relationships, explain entities, and trace paths in this repository.\n---\n\n"
+        "# Graphify\n\n"
+        f"Run commands from the repository root: `{project}`. Use the managed executable below; "
+        "a global Graphify installation is unnecessary. Replace angle-bracket placeholders "
+        "with names or questions from this project's graph.\n\n"
+        + "\n\n".join(f"{label}:\n\n```{'powershell' if os.name == 'nt' else 'sh'}\n{_graphify_command(command)}\n```" for label, command in commands)
+        + "\n\nIf the graph is missing, build it first. After code changes, refresh it before "
+        "querying again. Code-only extraction and `--no-label` require no LLM credentials. "
+        "Only enable semantic document/media extraction when explicitly requested.\n\n"
+        "Open `graphify-out/graph.html` for visualization and `graphify-out/GRAPH_REPORT.md` "
+        "for architecture context. Prefer scoped queries for focused questions. The configured "
+        "Graphify MCP server exposes the same project graph. Cite source paths and distinguish "
+        "EXTRACTED relationships from INFERRED ones. Verify uncertain results against source "
+        "and tests; an empty graph result does not prove a symbol is unused.\n"
+    )
+    return relative, content
+
+
+def _graphify_client_files(project: Path, client: str) -> dict[Path, str]:
+    skill, content = _graphify_skill(project, client)
+    files = {skill: content}
+    if client in {"cursor", "antigravity"}:
+        relative = (Path(".cursor/rules/graphify.mdc") if client == "cursor"
+                    else Path(".agents/rules/graphify.md"))
+        activation = "alwaysApply: true" if client == "cursor" else "trigger: always_on"
+        files[relative] = (
+            "---\ndescription: Use the project Graphify graph for code exploration and change planning.\n"
+            f"{activation}\n---\n\n# Graphify\n\n"
+            f"For architecture, symbols, dependencies, and change planning, load `{skill.as_posix()}` "
+            "and query Graphify before exploring raw files. Use the configured `graphify` MCP "
+            "server's `query_graph` tool for scoped questions, then inspect nodes, neighbors, "
+            "or paths as needed. Use the skill's managed CLI commands if MCP is unavailable. "
+            "Build a missing graph and refresh it after code changes with the code-only commands. "
+            "Read source for details or verification and as a fallback when Graphify cannot "
+            "answer. Cite file paths and distinguish EXTRACTED from INFERRED relationships. "
+            "A user request to disable Graphify overrides this default for the conversation.\n"
+        )
+    return files
+
+
+def _configure_managed_mcp(graph: str, project: Path, client: str) -> None:
+    """Merge only the selected server; existing ownership snapshots handle removal."""
+    if graph not in {"gitnexus", "graphify"} or client not in CLIENTS:
+        raise InstallError("Invalid managed MCP configuration request")
+    project = project.resolve()
+    files = _graphify_client_files(project, client) if graph == "graphify" else {}
+    for relative, content in files.items():
+        _assert_no_symlink(project, relative)
+        skill_path = project / relative
+        if skill_path.exists() and skill_path.read_text(encoding="utf-8") != content:
+            kind = "skill" if relative.name == "SKILL.md" else "rule"
+            raise InstallError(f"Existing Graphify {kind} differs: {skill_path}; preserve or move it before installing")
+
+    def write_client_files() -> None:
+        for relative, content in files.items():
+            path = project / relative
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+
+    entry = _managed_mcp_entry(graph, project)
+    if client == "antigravity":
+        config, path = _antigravity_preferred_config()
+        _, _, document = _read_antigravity_config(config)
+    else:
+        relative = CLIENT_CONFIG_PATHS[client]
+        _assert_no_symlink(project, relative)
+        path = project / relative
+        if client == "codex":
+            content = path.read_text(encoding="utf-8") if path.exists() else ""
+            block = f"[mcp_servers.{graph}]\n" + "".join(
+                f"{key} = {json.dumps(value, ensure_ascii=False)}\n" for key, value in entry.items()
+            )
+            # Python 3.10 has no stdlib TOML parser. Refuse existing files there
+            # rather than rewriting a configuration we cannot validate.
+            try:
+                import tomllib
+            except ImportError as error:
+                if content.strip():
+                    raise InstallError("Merging existing Codex TOML for this tool requires Python 3.11+; set ADL_TOOLKIT_PYTHON.") from error
+                tomllib = None
+            document = tomllib.loads(content) if tomllib else {}
+            existing = document.get("mcp_servers", {}).get(graph)
+            if existing is not None and existing != entry:
+                raise InstallError(f"Existing {graph} MCP entry differs; remove it before installing")
+            if existing is not None:
+                write_client_files()
+                return
+            content = content.rstrip() + "\n\n" + block
+            if tomllib:
+                tomllib.loads(content)
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(content, encoding="utf-8")
+            write_client_files()
+            return
+        document = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {}
+    if not isinstance(document, dict) or not isinstance(document.get("mcpServers", {}), dict):
+        raise InstallError(f"Invalid MCP configuration: {path}")
+    servers = document.setdefault("mcpServers", {})
+    existing = servers.get(graph)
+    if existing is not None and existing != entry:
+        raise InstallError(f"Existing {graph} MCP entry differs; remove it before installing")
+    servers[graph] = entry
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    write_client_files()
+
+
+def _managed_mcp_step(graph: str, project: Path, client: str) -> Step:
+    return Step(
+        f"Configure {graph} client ({client})",
+        (sys.executable, str(REPO_ROOT / "scripts/install_toolkit.py"),
+         "configure-managed-mcp", "--graph", graph, "--project", str(project), "--client", client),
+        project, owner=f"client:{client}", client=client,
+    )
+
+
+def validate_options(options: Options) -> Options:
+    project = options.project.expanduser().resolve()
+    if not project.is_dir():
+        raise ValueError(f"Project directory does not exist: {project}")
+    if options.graph not in GRAPHS:
+        raise ValueError(f"Invalid graph tool: {options.graph}")
+    clients = tuple(dict.fromkeys(options.clients or (options.client,)))
+    unknown_clients = set(clients) - set(CLIENTS)
+    if not clients or unknown_clients:
+        raise ValueError(f"Invalid client: {', '.join(sorted(unknown_clients)) or 'none'}")
+    unknown_addons = set(options.addons) - ADDON_SOURCES.keys()
+    if unknown_addons:
+        raise ValueError(f"Invalid add-on: {', '.join(sorted(unknown_addons))}")
+    unknown_extras = set(options.extras) - set(EXTRAS)
+    if unknown_extras:
+        raise ValueError(f"Invalid ADL extra: {', '.join(sorted(unknown_extras))}")
+    if options.extras and options.graph != "adl-drift":
+        raise ValueError("--extra is only supported with ADL-Drift")
+    package = options.package.strip() if options.package else None
+    if options.graph == "other":
+        if not package:
+            raise ValueError("--package is required when selecting Other")
+        if package.startswith("-") or any(c.isspace() or c in "/\\:" for c in package):
+            raise ValueError("--package must be a pip package name/spec, such as code2graph==1.2.0")
+    elif package:
+        raise ValueError("--package is only supported when selecting Other")
+    return Options(
+        graph=options.graph,
+        project=project,
+        client=clients[0],
+        addons=tuple(dict.fromkeys(options.addons)),
+        extras=tuple(dict.fromkeys(options.extras)),
+        package=package,
+        index=options.index if options.graph != "other" else False,
+        dry_run=options.dry_run,
+        clients=clients,
+    )
+
+
+def build_plan(options: Options) -> tuple[Step, ...]:
+    options = validate_options(options)
+    project = options.project
+    toolkit = project / ".adl-toolkit"
+    steps: list[Step] = []
+    postflight: Step | None = None
+
+    if options.graph in {"adl-drift", "graphify", "other"}:
+        python = _venv_executable(project, "python")
+        steps.append(Step(
+            "Create Python environment",
+            (sys.executable, "-m", "venv", str(toolkit / "venv")),
+            project,
+        ))
+        install_spec = options.package
+        if options.graph == "graphify":
+            install_spec = GRAPHIFY_PACKAGE
+        if options.graph == "adl-drift":
+            suffix = f"[{','.join(options.extras)}]" if options.extras else ""
+            install_spec = f"{REPO_ROOT}{suffix}"
+        pip_args = (str(python), "-m", "pip", "install")
+        steps.append(Step(
+            "Install graph tool and dependencies",
+            pip_args + (install_spec or "",),
+            project,
+            1800,
+        ))
+
+        if options.graph == "adl-drift":
+            adl = _venv_executable(project, "adl-drift")
+            for client in options.clients:
+                steps.append(Step(
+                    "Configure MCP client" if len(options.clients) == 1 else f"Configure MCP client ({client})",
+                    (str(adl), "-p", str(project), "mcp", "setup", f"--{client}"),
+                    project, owner=("graph" if len(options.clients) == 1 else f"client:{client}"), client=client,
+                ))
+            postflight = Step(
+                "Check MCP connection",
+                (str(adl), "-p", str(project), "mcp", "doctor"),
+                project,
+                90,
+            )
+            if options.index:
+                steps.append(Step(
+                    "Initialize ADL-Drift index",
+                    (str(adl), "-p", str(project), "graph"),
+                    project,
+                    1800,
+                ))
+    elif options.graph == "gitnexus":
+        steps.append(Step(
+            "Install Git Nexus locally",
+            ("npm", "install", "--prefix", str(toolkit / "gitnexus"),
+             "--no-audit", "--no-fund", GITNEXUS_PACKAGE), project, 1800,
+        ))
+    else:
+        prefix = toolkit / "codegraph"
+        codegraph = _codegraph_executable(project)
+        steps.append(Step(
+            "Install CodeGraph locally",
+            (
+                "npm", "install", "--prefix", str(prefix),
+                "--no-audit", "--no-fund", CODEGRAPH_PACKAGE,
+            ),
+            project,
+            1800,
+        ))
+        for client in options.clients:
+            steps.append(Step(
+                "Configure CodeGraph client" if len(options.clients) == 1 else f"Configure CodeGraph client ({client})",
+                (
+                    str(codegraph), "install", "--target", client,
+                    "--location", "global" if client == "antigravity" else "local",
+                    "--yes", "--no-permissions",
+                ),
+                project, owner=("graph" if len(options.clients) == 1 else f"client:{client}"), client=client,
+            ))
+        if options.index:
+            steps.append(Step(
+                "Initialize CodeGraph index",
+                (str(codegraph), "init", "--yes", str(project)),
+                project,
+                1800,
+            ))
+        steps.append(_codegraph_global_step(
+            project, "Install CodeGraph terminal command globally",
+        ))
+
+    if options.graph in {"gitnexus", "graphify"}:
+        steps.extend(_managed_mcp_step(options.graph, project, client) for client in options.clients)
+        if options.index:
+            command = (
+                (str(_gitnexus_executable(project)), "analyze", str(project), "--index-only", "--skip-git")
+                if options.graph == "gitnexus" else
+                (str(_venv_executable(project, "graphify")), "extract", str(project),
+                 "--code-only", "--out", str(project))
+            )
+            steps.append(Step(f"Initialize {options.graph} index", command, project, 1800))
+            if options.graph == "graphify":
+                steps.append(Step(
+                    "Generate Graphify report and visualization",
+                    (str(_venv_executable(project, "graphify")), "cluster-only", str(project), "--no-label"),
+                    project, 1800,
+                ))
+
+    for addon in options.addons:
+        installed_roots: set[Path] = set()
+        for client in options.clients:
+            skill_root = INTEGRATION_SKILL_ROOTS[client]
+            if skill_root in installed_roots:
+                continue
+            installed_roots.add(skill_root)
+            steps.append(Step(
+                (f"Install {addon.title()} skills (skills only)" if len(options.clients) == 1
+                 else f"Install {addon.title()} skills for {client}"),
+                (
+                    "npx", "--yes", SKILLS_PACKAGE, "add", ADDON_SOURCES[addon],
+                    "--skill", "*", "-a", SKILLS_AGENT[client],
+                    "--copy", "--yes",
+                ),
+                project,
+                1200,
+                f"addon:{addon}",
+                True,
+                client,
+            ))
+    if options.graph == "adl-drift":
+        steps.append(Step(
+            "Install ADL-Drift terminal command globally",
+            ("npm", "install", "--global", "--bin-links=true", "--no-audit", "--no-fund", str(REPO_ROOT)),
+            project, 1800,
+        ))
+    if options.graph == "graphify":
+        steps.append(_graphify_global_step(project))
+    if postflight:
+        steps.append(postflight)
+    return tuple(steps)
+
+
+def _display_command(command: Sequence[str]) -> str:
+    return subprocess.list2cmdline(command) if os.name == "nt" else shlex.join(command)
+
+
+def format_plan(options: Options) -> str:
+    options = validate_options(options)
+    lines = [
+        "\nInstallation plan:",
+        f"  Project: {options.project}",
+        f"  Graph tool: {options.graph}",
+        f"  Clients: {', '.join(options.clients)}",
+        f"  Add-on: {', '.join(options.addons) or 'none'}",
+        f"  Initialize index: {'yes' if options.index else 'no'}",
+    ]
+    if options.extras:
+        lines.append(f"  ADL extras: {', '.join(options.extras)}")
+    if options.package:
+        lines.append(f"  Pip package: {options.package}")
+        lines.append("  Note: Other only installs a pip package; MCP configuration is not automatic.")
+    if options.graph == "codegraph":
+        lines.append(f"  Approved CodeGraph pin: {CODEGRAPH_PACKAGE}")
+        lines.append(
+            "  Note: the shared global CodeGraph command will be aligned to this pin "
+            "and remains after project uninstall."
+        )
+    if options.graph == "adl-drift":
+        lines.append("  Note: the shared ADL-Drift terminal launcher is installed globally and remains after project uninstall.")
+    if options.graph == "graphify":
+        lines.append("  Note: missing uv is installed for the current user; Graphify is upgraded globally and shell PATH is configured. These shared tools remain after project uninstall.")
+    for number, step in enumerate(build_plan(options), 1):
+        lines.extend((f"\n  {number}. {step.label}", f"     $ {_display_command(step.command)}"))
+    return "\n".join(lines)
+
+
+def _normalized_path(path: str | Path) -> str:
+    return os.path.normcase(str(Path(path).expanduser().resolve()))
+
+
+def preflight(
+    options: Options,
+    which: Callable[[str], str | None] = shutil.which,
+    *,
+    run: Callable[..., subprocess.CompletedProcess[str]] | None = None,
+    inherited_path: str | None = None,
+) -> None:
+    required: set[str] = set()
+    if options.graph == "gitnexus":
+        required.update(("node", "npm", "git"))
+    if options.graph in {"adl-drift", "codegraph"}:
+        required.update(("node", "npm"))
+    if options.addons:
+        required.update(("node", "npm", "npx", "git"))
+    missing = sorted(tool for tool in required if which(tool) is None)
+    if missing:
+        raise InstallError(
+            "Missing system tools: " + ", ".join(missing)
+            + ". Install them and try again; the project has not been changed."
+        )
+    if options.graph in {"adl-drift", "codegraph"}:
+        try:
+            result = (run or subprocess.run)(
+                (which("npm") or "npm", "prefix", "--global"),
+                capture_output=True, text=True, timeout=10, check=True,
+            )
+            prefix = result.stdout.strip()
+            if not prefix:
+                raise ValueError("npm returned an empty global prefix")
+        except (OSError, ValueError, subprocess.SubprocessError) as error:
+            raise InstallError(
+                f"Could not determine npm's global executable directory: {error}. "
+                "Fix npm and try again; the project has not been changed."
+            ) from error
+        global_bin = Path(prefix) if os.name == "nt" else Path(prefix) / "bin"
+        path_value = os.environ.get("PATH", "") if inherited_path is None else inherited_path
+        path_entries = [
+            _normalized_path(entry) for entry in path_value.split(os.pathsep) if entry
+        ]
+        normalized_bin = _normalized_path(global_bin)
+        if normalized_bin not in path_entries:
+            raise InstallError(
+                f"npm's global executable directory is not on PATH: {global_bin}. "
+                "Add this directory to PATH before rerunning the installer; PATH is not "
+                "changed automatically and the project has not been changed."
+            )
+        existing_command = which(options.graph)
+        own_adl_launcher = (
+            options.graph == "adl-drift"
+            and existing_command is not None
+            and _normalized_path(existing_command) == _normalized_path(REPO_ROOT / "bin" / "adl-drift.mjs")
+        )
+        if existing_command and not own_adl_launcher:
+            command_directory = _normalized_path(Path(existing_command).parent)
+            if (
+                command_directory in path_entries
+                and path_entries.index(command_directory) < path_entries.index(normalized_bin)
+            ):
+                raise InstallError(
+                    f"Another {options.graph} command takes precedence on PATH: {existing_command}. "
+                    f"Move {global_bin} before that directory on PATH and rerun the installer; "
+                    "the project has not been changed."
+                )
+    if options.addons:
+        try:
+            version = subprocess.run(
+                (which("node") or "node", "--version"), capture_output=True,
+                text=True, timeout=10, check=True,
+            ).stdout.strip().lstrip("v")
+            numbers = tuple(int(part) for part in version.split(".")[:3])
+        except (OSError, ValueError, subprocess.SubprocessError) as error:
+            raise InstallError(f"Could not determine Node.js version: {error}") from error
+        if numbers < (22, 20, 0):
+            raise InstallError("Integration skills require Node.js 22.20.0 or newer.")
+
+
+def _digest(content: bytes) -> str:
+    return hashlib.sha256(content).hexdigest()
+
+
+def _encoded(content: bytes | None) -> str | None:
+    return None if content is None else base64.b64encode(content).decode("ascii")
+
+
+def _decoded(content: str | None) -> bytes | None:
+    return None if content is None else base64.b64decode(content, validate=True)
+
+
+def _safe_relative(value: str) -> Path:
+    if not isinstance(value, str):
+        raise InstallError("Unsafe path in installation manifest")
+    path = Path(value)
+    if path.is_absolute() or PureWindowsPath(value).drive or not path.parts or ".." in path.parts or ".." in PureWindowsPath(value).parts:
+        raise InstallError(f"Unsafe path in installation manifest: {value!r}")
+    return path
+
+
+def _assert_no_symlink(project: Path, relative: Path) -> None:
+    current = project
+    for part in relative.parts:
+        current /= part
+        if current.is_symlink():
+            raise InstallError(f"Refusing to follow symlink: {current}")
+
+
+def _toolkit_dir(project: Path) -> Path:
+    _assert_no_symlink(project, Path(".adl-toolkit"))
+    return project / ".adl-toolkit"
+
+
+def _managed_path(relative: Path) -> bool:
+    return relative in MANAGED_FILES or any(
+        relative == root or root in relative.parents for root in MANAGED_ROOTS
+    )
+
+
+def _snapshot(project: Path) -> dict[str, bytes]:
+    files: dict[str, bytes] = {}
+    for relative in MANAGED_FILES:
+        path = project / relative
+        _assert_no_symlink(project, relative)
+        if path.is_file():
+            files[relative.as_posix()] = path.read_bytes()
+    for root in MANAGED_ROOTS:
+        path = project / root
+        _assert_no_symlink(project, root)
+        if not path.is_dir():
+            continue
+        for child in path.rglob("*"):
+            relative = child.relative_to(project)
+            _assert_no_symlink(project, relative)
+            if child.is_file():
+                files[relative.as_posix()] = child.read_bytes()
+    return files
+
+
+def _antigravity_paths() -> dict[str, Path]:
+    home = Path.home()
+    return {name: home / relative for name, relative in ANTIGRAVITY_CONFIGS.items()}
+
+
+def _antigravity_preferred_config() -> tuple[str, Path]:
+    paths = _antigravity_paths()
+    marker = Path.home() / ANTIGRAVITY_MIGRATED_MARKER
+    if marker.exists() or paths["unified"].exists():
+        return "unified", paths["unified"]
+    return "legacy", paths["legacy"]
+
+
+def _global_server_names(graph: str, client: str) -> tuple[str, ...]:
+    if client != "antigravity":
+        return ()
+    if graph == "adl-drift":
+        return ("adl-drift", "drift")
+    if graph == "codegraph":
+        return ("codegraph",)
+    if graph in {"gitnexus", "graphify"}:
+        return (graph,)
+    return ()
+
+
+def _expected_antigravity_entry(graph: str, project: Path) -> tuple[str, dict[str, object]]:
+    if graph in {"gitnexus", "graphify"}:
+        return graph, _managed_mcp_entry(graph, project)
+    if graph == "adl-drift":
+        return "adl-drift", {
+            "command": str(_venv_executable(project, "python")),
+            "args": [
+                "-m", "adl_drift.server.mcp_stdio", "--project", str(project.resolve()),
+            ],
+        }
+    if graph == "codegraph":
+        return "codegraph", {
+            "command": str(_codegraph_executable(project)),
+            "args": ["serve", "--mcp", "--path", str(project.resolve())],
+        }
+    raise InstallError(f"{graph} does not configure Antigravity MCP.")
+
+
+def _ensure_antigravity_slot(options: Options) -> set[str]:
+    if "antigravity" not in options.clients or options.graph == "other":
+        return set()
+    preferred, _ = _antigravity_preferred_config()
+    primary, expected = _expected_antigravity_entry(options.graph, options.project)
+    found: list[tuple[str, str, object]] = []
+    for config in ANTIGRAVITY_CONFIGS:
+        _, _, document = _read_antigravity_config(config)
+        servers = document.get("mcpServers", {})
+        assert isinstance(servers, dict)
+        for server in _global_server_names(options.graph, "antigravity"):
+            if server in servers:
+                found.append((config, server, servers[server]))
+    if not found:
+        return set()
+    if found == [(preferred, primary, expected)]:
+        return set()
+    if options.graph == "adl-drift" and len(found) == 1:
+        config, server, entry = found[0]
+        if (config == preferred and server == primary and isinstance(entry, dict)
+                and set(entry) == {"command", "args"}
+                and isinstance(entry.get("command"), str)
+                and entry.get("args") == expected["args"]):
+            return {_global_entry_key(config, server)}
+    raise InstallError(
+        "Antigravity is already configured for this graph tool in another project. "
+        "Uninstall that integration before configuring this project."
+    )
+
+
+def _global_entry_key(config: str, server: str) -> str:
+    return f"{config}/{server}"
+
+
+def _read_antigravity_config(config: str) -> tuple[Path, bool, dict[str, object]]:
+    if config not in ANTIGRAVITY_CONFIGS:
+        raise InstallError("Installation manifest has an invalid global config.")
+    relative = ANTIGRAVITY_CONFIGS[config]
+    home = Path.home()
+    _assert_no_symlink(home, relative)
+    path = home / relative
+    if not path.exists():
+        return path, False, {}
+    if not path.is_file():
+        raise InstallError(f"Antigravity MCP config is not a file: {path}")
+    try:
+        document = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise InstallError(f"Cannot read Antigravity MCP config: {error}") from error
+    if not isinstance(document, dict):
+        raise InstallError(f"Antigravity MCP config must contain a JSON object: {path}")
+    servers = document.get("mcpServers", {})
+    if not isinstance(servers, dict):
+        raise InstallError(f"Antigravity mcpServers must contain a JSON object: {path}")
+    return path, True, document
+
+
+def _global_entry_snapshot(graph: str, client: str) -> dict[str, dict[str, object]]:
+    names = _global_server_names(graph, client)
+    if not names:
+        return {}
+    snapshot: dict[str, dict[str, object]] = {}
+    for config in ANTIGRAVITY_CONFIGS:
+        _, file_present, document = _read_antigravity_config(config)
+        servers = document.get("mcpServers", {})
+        assert isinstance(servers, dict)
+        for server in names:
+            snapshot[_global_entry_key(config, server)] = {
+                "file_present": file_present,
+                "present": server in servers,
+                "value": servers.get(server),
+            }
+    return snapshot
+
+
+def _record_global_changes(
+    manifest: dict[str, object], before: dict[str, dict[str, object]],
+    after: dict[str, dict[str, object]], *, force: bool = False,
+    adopted: set[str] | None = None,
+) -> None:
+    entries = manifest.setdefault("global_entries", {})
+    assert isinstance(entries, dict)
+    adopted = adopted or set()
+    for key in sorted(set(before) | set(after)):
+        if key in adopted and before.get(key) == after.get(key):
+            continue
+        if before.get(key) == after.get(key):
+            state = after.get(key, {})
+            if not force or not state.get("present"):
+                continue
+        old = before.get(key, {"file_present": False, "present": False, "value": None})
+        new = after.get(key, {"file_present": False, "present": False, "value": None})
+        if key in adopted:
+            old = {**old, "present": False, "value": None}
+        record = entries.setdefault(key, {
+            "baseline_file_present": old["file_present"],
+            "baseline_present": old["present"],
+            "baseline": old["value"],
+        })
+        assert isinstance(record, dict)
+        record["installed_present"] = new["present"]
+        record["installed"] = new["value"]
+
+
+def _configure_antigravity_codegraph(project: Path) -> None:
+    config, path = _antigravity_preferred_config()
+    _, _, document = _read_antigravity_config(config)
+    servers = document.setdefault("mcpServers", {})
+    assert isinstance(servers, dict)
+    server, entry = _expected_antigravity_entry("codegraph", project)
+    servers[server] = entry
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+
+
+def _lock_skills(content: bytes | None) -> dict[str, object]:
+    if content is None:
+        return {}
+    try:
+        document = json.loads(content)
+    except (UnicodeDecodeError, json.JSONDecodeError):
+        return {}
+    skills = document.get("skills", {}) if isinstance(document, dict) else {}
+    return skills if isinstance(skills, dict) else {}
+
+
+def _integration_block(
+    client: str, addons: Sequence[str], *, codegraph: bool = False,
+) -> str:
+    selected = set(addons)
+    skill_root = INTEGRATION_SKILL_ROOTS[client]
+    lines = [
+        INTEGRATION_BEGIN,
+        "## ADL Toolkit integrations",
+    ]
+    if selected:
+        lines.extend((
+            "",
+            "The selected integrations are active by default.",
+        ))
+    if "caveman" in selected:
+        lines.extend((
+            "",
+            f"- For responses, load and follow only `{skill_root / 'caveman/SKILL.md'}` "
+            "from the Caveman package. Keep every technical fact needed for correctness, "
+            "debugging, validation, and review.",
+        ))
+    if "ponytail" in selected:
+        lines.extend((
+            "",
+            f"- For source-code work, load and follow only `{skill_root / 'ponytail/SKILL.md'}` "
+            "in full mode. Preserve correctness, security, validation, tests, data integrity, "
+            "accessibility, and explicit user requirements.",
+        ))
+    if codegraph:
+        lines.extend((
+            "",
+            "### CodeGraph",
+            "",
+            "For repository structure, dependency, impact, and refactoring questions, call "
+            "`codegraph_explore` first. Confirm its index is available and current, then use "
+            "the returned source, dependency paths, and blast radius before opening files. "
+            "Read files for details the response does not contain, or as the fallback when "
+            "CodeGraph is unavailable or unindexed. Base every relationship claim on graph "
+            "or source evidence.",
+        ))
+    if codegraph:
+        names = [
+            *(addon.title() for addon in addons),
+            "CodeGraph",
+        ]
+        lines.extend((
+            "",
+            f"Any clear user request to disable {', '.join(names)} or all integrations "
+            "overrides these defaults without requiring an exact phrase. Keep that choice "
+            "for the current conversation until the user clearly re-enables it.",
+        ))
+    elif selected:
+        lines.extend((
+            "",
+            "Any clear user request to disable Caveman, Ponytail, or all integrations overrides "
+            "these defaults without requiring an exact phrase. Keep that choice for the current "
+            "conversation until the user clearly re-enables it.",
+        ))
+    lines.append(INTEGRATION_END)
+    return "\n".join(lines)
+
+
+def _integration_content(
+    client: str, addons: Sequence[str], *, file_preexisting: bool,
+    codegraph: bool = False,
+) -> str:
+    block = _integration_block(client, addons, codegraph=codegraph)
+    if client == "cursor":
+        return "\n".join((
+            "---",
+            "description: Activate the integration tools selected with ADL Toolkit",
+            "alwaysApply: true",
+            "---",
+            block,
+            "",
+        ))
+    return ("\n" if file_preexisting else "") + block + "\n"
+
+
+def _activate_integration_instructions(
+    project: Path, manifest: dict[str, object], clients: Sequence[str],
+    addons: Sequence[str], *, codegraph: bool = False,
+) -> None:
+    if not addons and not codegraph:
+        return
+    records = manifest.setdefault("integration_instructions", {})
+    assert isinstance(records, dict)
+    by_path: dict[Path, list[str]] = {}
+    for client in clients:
+        if addons or (codegraph and client == "antigravity"):
+            by_path.setdefault(INTEGRATION_INSTRUCTION_PATHS[client], []).append(client)
+    for relative, path_clients in by_path.items():
+        _assert_no_symlink(project, relative)
+        path = project / relative
+        key = relative.as_posix()
+        record = records.get(key)
+        representative = path_clients[0]
+        path_codegraph = codegraph and "antigravity" in path_clients
+        if record is not None:
+            assert isinstance(record, dict)
+            old_content = str(record["content"])
+            try:
+                current = path.read_text(encoding="utf-8")
+            except (OSError, UnicodeError) as error:
+                raise InstallError(f"Cannot update integration instructions: {path}") from error
+            if current.count(old_content) != 1:
+                raise InstallError(f"Integration instructions were modified; preserved {key}.")
+            file_preexisting = bool(record["file_preexisting"])
+            merged_clients = tuple(dict.fromkeys([*record.get("clients", ()), *path_clients]))
+            path_codegraph = path_codegraph or bool(record.get("codegraph", False))
+            content = _integration_content(
+                representative, addons, file_preexisting=file_preexisting,
+                codegraph=path_codegraph,
+            )
+            path.write_text(current.replace(old_content, content, 1), encoding="utf-8")
+        else:
+            if path.exists() and not path.is_file():
+                raise InstallError(f"Integration instruction path is not a file: {path}")
+            if representative == "cursor" and path.exists():
+                raise InstallError(f"Integration rule already exists; preserved {key}.")
+            try:
+                current = path.read_text(encoding="utf-8") if path.exists() else ""
+            except (OSError, UnicodeError) as error:
+                raise InstallError(f"Cannot read integration instructions: {path}") from error
+            if INTEGRATION_BEGIN in current or INTEGRATION_END in current:
+                raise InstallError(f"Integration instruction markers already exist in {key}.")
+            file_preexisting = path.exists()
+            merged_clients = tuple(path_clients)
+            content = _integration_content(
+                representative, addons, file_preexisting=file_preexisting,
+                codegraph=path_codegraph,
+            )
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(current + content, encoding="utf-8")
+        records[key] = {
+            "path": key, "clients": list(merged_clients), "addons": list(addons),
+            "codegraph": path_codegraph, "file_preexisting": file_preexisting,
+            "content": content,
+        }
+
+
+def _integration_instruction_state(
+    project: Path, manifest: dict[str, object] | None,
+) -> list[dict[str, object]]:
+    if not manifest or "integration_instructions" not in manifest:
+        return []
+    records = manifest["integration_instructions"]
+    assert isinstance(records, dict)
+    states: list[dict[str, object]] = []
+    for record in records.values():
+        assert isinstance(record, dict)
+        relative = Path(str(record["path"]))
+        _assert_no_symlink(project, relative)
+        path = project / relative
+        try:
+            current = path.read_text(encoding="utf-8") if path.is_file() else None
+        except (OSError, UnicodeError):
+            current = None
+        content = str(record["content"])
+        removable = current is not None and current.count(content) == 1
+        cleaned: str | None = None
+        if removable:
+            cleaned = current.replace(content, "", 1)
+            if not bool(record["file_preexisting"]) and current == content:
+                cleaned = None
+        states.append({
+            "project": project, "path": path, "relative": relative,
+            "current": current, "cleaned": cleaned, "content": content,
+            "removable": removable,
+        })
+    return states
+
+
+def _apply_integration_instruction_removal(state: dict[str, object]) -> None:
+    project = state["project"]
+    path = state["path"]
+    assert isinstance(project, Path)
+    assert isinstance(path, Path)
+    cleaned = state["cleaned"]
+    if cleaned is None:
+        if path.is_file():
+            path.unlink()
+            _prune_empty_parents(project, path)
+    else:
+        assert isinstance(cleaned, str)
+        path.write_text(cleaned, encoding="utf-8")
+
+
+def _restore_integration_instruction_after_failure(state: dict[str, object]) -> None:
+    path = state["path"]
+    assert isinstance(path, Path)
+    content = str(state["content"])
+    try:
+        current = path.read_text(encoding="utf-8") if path.is_file() else ""
+    except (OSError, UnicodeError):
+        return
+    if INTEGRATION_BEGIN in current or INTEGRATION_END in current:
+        return
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(current + content, encoding="utf-8")
+
+
+def _record_changes(
+    manifest: dict[str, object], before: dict[str, bytes], after: dict[str, bytes], owner: str,
+    force_paths: set[str] | None = None,
+) -> None:
+    artifacts = manifest.setdefault("artifacts", {})
+    assert isinstance(artifacts, dict)
+    for relative in sorted(set(before) | set(after)):
+        old_content = _without_integration_instructions(
+            manifest, relative, before.get(relative),
+        )
+        new_content = _without_integration_instructions(
+            manifest, relative, after.get(relative),
+        )
+        if relative == "skills-lock.json" or (
+            old_content == new_content
+            and relative not in (force_paths or set())
+        ):
+            continue
+        entry = artifacts.get(relative)
+        if not isinstance(entry, dict):
+            entry = {"baseline": _encoded(old_content), "owner": owner}
+            artifacts[relative] = entry
+        entry["installed_sha256"] = (
+            _digest(new_content) if new_content is not None else None
+        )
+
+    if not owner.startswith("addon:"):
+        return
+    addon = owner.split(":", 1)[1]
+    lock = manifest.setdefault("lock", {"preexisting": "skills-lock.json" in before, "entries": {}})
+    assert isinstance(lock, dict)
+    entries = lock.setdefault("entries", {})
+    assert isinstance(entries, dict)
+    old_skills = _lock_skills(before.get("skills-lock.json"))
+    new_skills = _lock_skills(after.get("skills-lock.json"))
+    for name in sorted(set(old_skills) | set(new_skills)):
+        if old_skills.get(name) == new_skills.get(name):
+            continue
+        installed = new_skills.get(name)
+        if not isinstance(installed, dict) or installed.get("source") != ADDON_SOURCES[addon]:
+            continue
+        if name not in entries:
+            entries[name] = {"addon": addon, "baseline": old_skills.get(name)}
+        entries[name]["installed"] = installed
+
+
+def _without_integration_instructions(
+    manifest: dict[str, object], relative: str, content: bytes | None,
+) -> bytes | None:
+    records = manifest.get("integration_instructions")
+    if content is None or not isinstance(records, dict):
+        return content
+    if records.get("path") == relative:
+        expected = str(records["content"]).encode("utf-8")
+        return content.replace(expected, b"", 1) if content.count(expected) == 1 else content
+    record = records.get(relative)
+    if not isinstance(record, dict):
+        return content
+    expected = str(record["content"]).encode("utf-8")
+    return content.replace(expected, b"", 1) if content.count(expected) == 1 else content
+
+
+def _validate_manifest(project: Path, manifest: object) -> dict[str, object]:
+    if not isinstance(manifest, dict) or manifest.get("version") != MANIFEST_VERSION:
+        raise InstallError("Unsupported or malformed installation manifest.")
+    if manifest.get("graph") not in GRAPHS or manifest.get("client") not in CLIENTS:
+        raise InstallError("Installation manifest has an invalid graph tool or client.")
+    clients = manifest.get("clients", [manifest["client"]])
+    if (not isinstance(clients, list) or not clients
+            or len(clients) != len(set(clients)) or any(item not in CLIENTS for item in clients)
+            or manifest["client"] != clients[0]):
+        raise InstallError("Installation manifest has invalid clients.")
+    manifest["clients"] = clients
+    configured_clients = manifest.get("configured_clients", clients)
+    if (not isinstance(configured_clients, list)
+            or len(configured_clients) != len(set(configured_clients))
+            or any(item not in clients for item in configured_clients)):
+        raise InstallError("Installation manifest has invalid configured clients.")
+    manifest["configured_clients"] = configured_clients
+    addons = manifest.get("addons")
+    if not isinstance(addons, list) or any(item not in ADDON_SOURCES for item in addons):
+        raise InstallError("Installation manifest has invalid add-ons.")
+    extras = manifest.get("extras", [])
+    if (not isinstance(extras, list) or len(extras) != len(set(extras))
+            or any(item not in EXTRAS for item in extras)
+            or (extras and manifest["graph"] != "adl-drift")):
+        raise InstallError("Installation manifest has invalid ADL extras.")
+    manifest["extras"] = extras
+    package = manifest.get("package")
+    if package is not None and (
+        manifest["graph"] != "other" or not isinstance(package, str)
+        or not package.strip() or package.startswith("-")
+        or any(char.isspace() or char in "/\\:" for char in package)
+    ):
+        raise InstallError("Installation manifest has an invalid pip package spec.")
+    if manifest["graph"] != "other" and package is not None:
+        raise InstallError("Installation manifest has an unexpected pip package spec.")
+    manifest["package"] = package
+    index = manifest.get("index", False)
+    if type(index) is not bool or (index and manifest["graph"] == "other"):
+        raise InstallError("Installation manifest has an invalid index preference.")
+    manifest["index"] = index
+    completed_steps = manifest.get("completed_steps", [])
+    if (not isinstance(completed_steps, list)
+            or any(not isinstance(item, str) or not item for item in completed_steps)):
+        raise InstallError("Installation manifest has invalid completed steps.")
+    manifest["completed_steps"] = completed_steps
+    artifacts = manifest.get("artifacts", {})
+    if not isinstance(artifacts, dict):
+        raise InstallError("Installation manifest has invalid artifacts.")
+    for value, entry in artifacts.items():
+        relative = _safe_relative(value)
+        if not _managed_path(relative) or not isinstance(entry, dict):
+            raise InstallError(f"Installation manifest contains unmanaged path: {value}")
+        _assert_no_symlink(project, relative)
+        if not {"baseline", "owner", "installed_sha256"} <= entry.keys():
+            raise InstallError(f"Incomplete artifact record for {value}")
+        if entry.get("owner") not in {
+            "graph", *(f"addon:{addon}" for addon in addons),
+            *(f"client:{client}" for client in clients),
+        }:
+            raise InstallError(f"Invalid artifact owner for {value}")
+        try:
+            _decoded(entry.get("baseline"))
+        except (TypeError, ValueError) as error:
+            raise InstallError(f"Invalid baseline data for {value}") from error
+        digest = entry.get("installed_sha256")
+        if digest is not None and (
+            not isinstance(digest, str) or len(digest) != 64
+            or any(char not in "0123456789abcdef" for char in digest)
+        ):
+            raise InstallError(f"Invalid digest for {value}")
+    runtimes = manifest.get("runtimes", {})
+    indexes = manifest.get("indexes", {})
+    if not isinstance(runtimes, dict) or set(runtimes) - {
+        path.as_posix() for path in RUNTIME_PATHS.values()
+    }:
+        raise InstallError("Installation manifest has invalid runtime paths.")
+    if not isinstance(indexes, dict) or set(indexes) - {
+        path.as_posix() for paths in INDEX_PATHS.values() for path in paths
+    }:
+        raise InstallError("Installation manifest has invalid index paths.")
+    for value in (*runtimes, *indexes):
+        relative = _safe_relative(value)
+        _assert_no_symlink(project, relative)
+        record = runtimes[value] if value in runtimes else indexes[value]
+        if not isinstance(record, dict) or type(record.get("preexisting")) is not bool:
+            raise InstallError(f"Invalid ownership record for {value}")
+    lock = manifest.get("lock", {})
+    if not isinstance(lock, dict) or not isinstance(lock.get("entries", {}), dict):
+        raise InstallError("Installation manifest has invalid skill lock data.")
+    for name, record in lock.get("entries", {}).items():
+        if (not isinstance(name, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]*", name)
+                or not isinstance(record, dict) or record.get("addon") not in addons
+                or not isinstance(record.get("installed"), dict)):
+            raise InstallError("Installation manifest has an invalid skill lock entry.")
+    global_entries = manifest.get("global_entries", {})
+    if not isinstance(global_entries, dict):
+        raise InstallError("Installation manifest has invalid global entries.")
+    allowed_global_entries = {
+        _global_entry_key(config, server)
+        for config in ANTIGRAVITY_CONFIGS
+        for server in _global_server_names(
+            str(manifest["graph"]), "antigravity" if "antigravity" in clients else ""
+        )
+    }
+    if set(global_entries) - allowed_global_entries:
+        raise InstallError("Installation manifest has an invalid global entry.")
+    primary_global_name = None
+    expected_global_entry = None
+    if "antigravity" in clients and manifest["graph"] != "other":
+        primary_global_name, expected_global_entry = _expected_antigravity_entry(
+            str(manifest["graph"]), project,
+        )
+    for key, record in global_entries.items():
+        if (not isinstance(record, dict)
+                or not {"baseline_file_present", "baseline_present", "baseline",
+                        "installed_present", "installed"} <= record.keys()
+                or type(record["baseline_file_present"]) is not bool
+                or type(record["baseline_present"]) is not bool
+                or type(record["installed_present"]) is not bool
+                or (record["installed_present"] and not isinstance(record["installed"], dict))):
+            raise InstallError(f"Installation manifest has an invalid global entry: {key}")
+        config, server = key.split("/", 1)
+        expected_installed = expected_global_entry if server == primary_global_name else None
+        if ((record["installed_present"] and record["installed"] != expected_installed)
+                or (not record["installed_present"] and record["installed"] is not None)
+                or (record["baseline_present"] and (
+                    server != primary_global_name
+                    or record["baseline"] != expected_global_entry
+                    or not record["installed_present"]
+                ))
+                or (not record["baseline_present"] and record["baseline"] is not None)):
+            raise InstallError(f"Unsafe global entry in installation manifest: {key}")
+        _read_antigravity_config(config)
+    instructions = manifest.get("integration_instructions")
+    if instructions is not None:
+        if not isinstance(instructions, dict):
+            raise InstallError("Installation manifest has invalid integration instructions.")
+        # Migrate the original single-record schema in memory.
+        if "path" in instructions:
+            old = dict(instructions)
+            old["clients"] = [str(manifest["client"])]
+            instructions = {str(old["path"]): old}
+            manifest["integration_instructions"] = instructions
+        for key, record in instructions.items():
+            base_keys = {"path", "clients", "addons", "file_preexisting", "content"}
+            record_keys = set(record) if isinstance(record, dict) else set()
+            record_clients = record.get("clients") if isinstance(record, dict) else None
+            instruction_addons = record.get("addons") if isinstance(record, dict) else None
+            codegraph_guidance = record.get("codegraph", False) if isinstance(record, dict) else False
+            if (not isinstance(record, dict)
+                    or record_keys not in (base_keys, {*base_keys, "codegraph"})
+                    or record.get("path") != key
+                    or type(record.get("file_preexisting")) is not bool
+                    or not isinstance(record_clients, list) or not record_clients
+                    or len(record_clients) != len(set(record_clients))
+                    or any(client not in clients for client in record_clients)
+                    or any(INTEGRATION_INSTRUCTION_PATHS[client].as_posix() != key
+                           for client in record_clients)
+                    or not isinstance(instruction_addons, list)
+                    or len(instruction_addons) != len(set(instruction_addons))
+                    or any(addon not in addons for addon in instruction_addons)
+                    or type(codegraph_guidance) is not bool
+                    or (codegraph_guidance and (
+                        manifest["graph"] != "codegraph" or "antigravity" not in record_clients
+                    ))
+                    or (not instruction_addons and not codegraph_guidance)):
+                raise InstallError("Installation manifest has invalid integration instructions.")
+            representative = str(record_clients[0])
+            if representative == "cursor" and record["file_preexisting"]:
+                raise InstallError("Installation manifest has invalid Cursor integration ownership.")
+            expected_content = _integration_content(
+                representative, instruction_addons,
+                file_preexisting=bool(record["file_preexisting"]),
+                codegraph=codegraph_guidance,
+            )
+            if record.get("content") != expected_content:
+                raise InstallError("Installation manifest has unsafe integration content.")
+            _assert_no_symlink(project, Path(key))
+    _assert_no_symlink(project, Path("skills-lock.json"))
+    _assert_no_symlink(project, MANIFEST_PATH)
+    return manifest
+
+
+def _load_manifest(project: Path) -> dict[str, object] | None:
+    toolkit = _toolkit_dir(project)
+    path = toolkit / "install.json"
+    _assert_no_symlink(project, MANIFEST_PATH)
+    if not path.exists():
+        return None
+    if not path.is_file():
+        raise InstallError(f"Installation manifest is not a file: {path}")
+    try:
+        manifest = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as error:
+        raise InstallError(f"Cannot read installation manifest: {error}") from error
+    return _validate_manifest(project, manifest)
+
+
+def _save_manifest(project: Path, manifest: dict[str, object]) -> None:
+    toolkit = _toolkit_dir(project)
+    toolkit.mkdir(exist_ok=True)
+    path = toolkit / "install.json"
+    temporary = toolkit / "install.json.tmp"
+    temporary.write_text(json.dumps(manifest, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    os.replace(temporary, path)
+
+
+def _install_manifest(options: Options) -> dict[str, object]:
+    options = validate_options(options)
+    existing = _load_manifest(options.project)
+    if existing:
+        if existing["graph"] != options.graph:
+            raise InstallError(
+                f"{existing['graph']} is already managed for this project; uninstall it first."
+            )
+        existing_clients = list(existing.get("clients", [existing["client"]]))
+        existing["clients"] = list(dict.fromkeys([*existing_clients, *options.clients]))
+        existing["client"] = str(existing["clients"][0])
+        existing["addons"] = list(dict.fromkeys([
+            *existing.get("addons", []), *options.addons,
+        ]))
+        existing["extras"] = list(options.extras)
+        existing["package"] = options.package
+        existing["index"] = options.index
+        return existing
+    return {
+        "version": MANIFEST_VERSION,
+        "graph": options.graph,
+        "client": options.client,
+        "clients": list(options.clients),
+        "configured_clients": [],
+        "addons": list(options.addons),
+        "extras": list(options.extras),
+        "package": options.package,
+        "index": options.index,
+        "completed_steps": [],
+        "artifacts": {},
+        "runtimes": {
+            RUNTIME_PATHS[options.graph].as_posix(): {
+                "preexisting": (options.project / RUNTIME_PATHS[options.graph]).exists(),
+            },
+        },
+        "indexes": {
+            path.as_posix(): {"preexisting": (options.project / path).exists()}
+            for path in INDEX_PATHS[options.graph]
+        },
+        "lock": {
+            "preexisting": (options.project / "skills-lock.json").exists(),
+            "entries": {},
+        },
+        "global_entries": {},
+    }
+
+
+def _stop_process_tree(process: subprocess.Popen[str], grace: float = 5) -> None:
+    if os.name == "nt":
+        try:
+            subprocess.run(
+                (
+                    shutil.which("taskkill") or "taskkill",
+                    "/PID", str(process.pid), "/T", "/F",
+                ),
+                capture_output=True,
+                text=True,
+                timeout=grace,
+                check=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            if process.poll() is None:
+                process.kill()
+    else:
+        group_alive = True
+        try:
+            os.killpg(process.pid, signal.SIGTERM)
+        except ProcessLookupError:
+            group_alive = False
+        deadline = time.monotonic() + grace
+        while group_alive and time.monotonic() < deadline:
+            process.poll()
+            time.sleep(0.05)
+            try:
+                os.killpg(process.pid, 0)
+            except ProcessLookupError:
+                group_alive = False
+        if group_alive:
+            try:
+                os.killpg(process.pid, signal.SIGKILL)
+            except ProcessLookupError:
+                pass
+    try:
+        process.wait(timeout=grace)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+
+
+def run_command(step: Step, emit: Callable[[str], None] = print) -> None:
+    emit(f"\n→ {step.label}")
+    emit(f"  $ {_display_command(step.command)}")
+    executable = shutil.which(step.command[0]) or step.command[0]
+    command = (executable, *step.command[1:])
+    try:
+        process = subprocess.Popen(
+            command,
+            cwd=step.cwd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            env={**os.environ, "PYTHONUTF8": "1", "PYTHONIOENCODING": "utf-8"},
+            bufsize=1,
+            start_new_session=os.name != "nt",
+            creationflags=(
+                subprocess.CREATE_NEW_PROCESS_GROUP if os.name == "nt" else 0
+            ),
+        )
+    except OSError as error:
+        raise InstallError(
+            f"Cannot run step: {step.label}\n"
+            f"Command: {_display_command(step.command)}\n{error}"
+        ) from error
+    output: queue.Queue[str | None] = queue.Queue()
+    tail: deque[str] = deque(maxlen=20)
+
+    def read_output() -> None:
+        assert process.stdout is not None
+        try:
+            for line in process.stdout:
+                output.put(line)
+        finally:
+            process.stdout.close()
+            output.put(None)
+
+    reader = threading.Thread(target=read_output, daemon=True)
+    reader.start()
+    deadline = time.monotonic() + step.timeout
+    stop_tree = False
+    try:
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise InstallError(
+                    f"Timed out ({step.timeout:g}s): {step.label}\n"
+                    f"Command: {_display_command(step.command)}"
+                )
+            try:
+                line = output.get(timeout=min(0.2, remaining))
+            except queue.Empty:
+                continue
+            if line is None:
+                break
+            line = line.rstrip()
+            tail.append(line)
+            if not step.quiet:
+                emit(f"  {line}")
+        try:
+            exit_code = process.wait(timeout=max(0.1, deadline - time.monotonic()))
+        except subprocess.TimeoutExpired as error:
+            raise InstallError(
+                f"Timed out ({step.timeout:g}s): {step.label}\n"
+                f"Command: {_display_command(step.command)}"
+            ) from error
+    except BaseException:
+        stop_tree = True
+        raise
+    finally:
+        if stop_tree:
+            _stop_process_tree(process)
+        else:
+            process.wait()
+        reader.join(timeout=5)
+    if exit_code:
+        detail = "\n".join(tail)
+        raise InstallError(
+            f"Step failed (exit {exit_code}): {step.label}\n"
+            f"Command: {_display_command(step.command)}" + (f"\n{detail}" if detail else "")
+        )
+
+
+def _setup_graphify_global(
+    project: Path, *, emit: Callable[[str], None] = print,
+    runner: Callable[[Step, Callable[[str], None]], None] = run_command,
+) -> None:
+    def find_uv() -> str | None:
+        existing = shutil.which("uv")
+        if existing:
+            return existing
+        directories = [Path.home() / ".local" / "bin"]
+        for variable in ("UV_INSTALL_DIR", "XDG_BIN_HOME"):
+            if os.environ.get(variable):
+                directories.insert(0, Path(os.environ[variable]).expanduser())
+        name = "uv.exe" if os.name == "nt" else "uv"
+        return next((str(directory / name) for directory in directories
+                     if (directory / name).is_file()), None)
+
+    uv = find_uv()
+    if uv is None:
+        extension = "ps1" if os.name == "nt" else "sh"
+        url = f"https://astral.sh/uv/{UV_VERSION}/install.{extension}"
+        emit(f"Installing uv {UV_VERSION} with the official user-scoped installer: {url}")
+        with tempfile.TemporaryDirectory(prefix="adl-toolkit-uv-") as directory:
+            installer = Path(directory) / f"install.{extension}"
+            for attempt in range(3):
+                try:
+                    request = Request(url, headers={"User-Agent": "adl-toolkit"})
+                    with urlopen(request, timeout=30) as response:
+                        content = response.read()
+                    break
+                except (OSError, HTTPException) as error:
+                    if attempt == 2:
+                        raise InstallError(f"Could not download the uv installer: {error}") from error
+                    emit(f"Retrying uv installer download: {error}")
+            installer.write_bytes(content)
+            command = (
+                (shutil.which("powershell") or "powershell", "-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(installer))
+                if os.name == "nt" else
+                (shutil.which("sh") or "sh", str(installer))
+            )
+            runner(Step("Install uv for the current user", command, project, 300), emit)
+        uv = find_uv()
+        if uv is None:
+            raise InstallError("The uv installer finished but its executable was not found; check UV_INSTALL_DIR and rerun installation.")
+    runner(Step("Install or upgrade Graphify terminal command",
+                (uv, "tool", "install", "--upgrade", GRAPHIFY_PACKAGE), project, 1800), emit)
+    runner(Step("Configure Graphify terminal PATH",
+                (uv, "tool", "update-shell"), project, 60), emit)
+    emit("uv and Graphify are ready. Reopen your terminal to load any PATH changes.")
+
+
+def _install_retry_command(options: Options) -> str:
+    command = [
+        "adl-toolkit", "install", "--graph", options.graph,
+        "--project", str(options.project),
+    ]
+    for client in options.clients:
+        command.extend(("--client", client))
+    for addon in options.addons:
+        command.extend(("--addon", addon))
+    for extra in options.extras:
+        command.extend(("--extra", extra))
+    if options.package:
+        command.extend(("--package", options.package))
+    if not options.index:
+        command.append("--no-index")
+    return _display_command(command)
+
+
+def _index_summary(graph: str, project: Path, enabled: bool) -> str:
+    if graph == "other":
+        return "not managed for custom packages"
+    present = [path.as_posix() for path in INDEX_PATHS[graph] if (project / path).exists()]
+    if present:
+        return "present: " + ", ".join(present)
+    return "requested; no index path found" if enabled else "skipped by saved preference"
+
+
+def _format_completion_summary(
+    manifest: dict[str, object], project: Path, *, action: str,
+) -> str:
+    graph = str(manifest["graph"])
+    clients = [str(item) for item in manifest.get("clients", [manifest["client"]])]
+    addons = [str(item) for item in manifest.get("addons", ())]
+    lines = [
+        f"\n✓ {action} complete.",
+        f"  Graph tool: {graph}",
+        f"  Clients: {', '.join(clients)}",
+        f"  Add-ons: {', '.join(addons) or 'none'}",
+        f"  Index: {_index_summary(graph, project, bool(manifest.get('index', False)))}",
+        f"  Restart clients: {', '.join(clients)}",
+    ]
+    if graph == "codegraph" and (
+        not bool(manifest.get("index", False)) or not (project / ".codegraph").exists()
+    ):
+        global_codegraph = shutil.which("codegraph")
+        arguments = (
+            ("codegraph", "init", "--yes", ".")
+            if global_codegraph
+            else (
+                str(_codegraph_executable(project.resolve())),
+                "init", "--yes", ".",
+            )
+        )
+        command = (
+            "& " + " ".join("'" + argument.replace("'", "''") + "'" for argument in arguments)
+            if os.name == "nt" else _display_command(arguments)
+        )
+        if global_codegraph:
+            lines.append("  CodeGraph's terminal command is available on PATH.")
+        else:
+            lines.append(
+                "  The global CodeGraph command was not found; using the managed local runtime."
+            )
+        if os.name == "nt":
+            lines.append("  Run the following command in PowerShell.")
+        lines.append(f"  Run from the project directory: {project.resolve()}")
+        lines.append(f"  Build the index manually: {command}")
+    if graph == "adl-drift":
+        lines.append(f"  Run from the project directory: {project.resolve()}")
+        lines.append("  Build the graph manually: adl-drift graph")
+    if graph == "other":
+        lines.append("  Manual setup: configure the custom package in each MCP client if needed.")
+        lines.append("  Sample prompt: Use the installed graph tool to map this project's main modules.")
+    else:
+        tool = {"adl-drift": "ADL-Drift", "codegraph": "CodeGraph", "gitnexus": "Git Nexus", "graphify": "Graphify"}[graph]
+        lines.append(f"  Sample prompt: Use {tool} to map the call path for this feature.")
+    if graph in {"gitnexus", "graphify"}:
+        command = (
+            (str(_gitnexus_executable(project)), "analyze", str(project), "--index-only", "--skip-git")
+            if graph == "gitnexus" else
+            (str(_venv_executable(project, "graphify")), "extract", str(project), "--code-only", "--out", str(project))
+        )
+        display = _graphify_command(command) if graph == "graphify" else _display_command(command)
+        lines.append(f"  Build the index manually: {display}")
+    if graph == "graphify":
+        executable = str(_venv_executable(project, "graphify"))
+        lines.append("  Graphify's global uv tool is upgraded to the toolkit pin; reopen your terminal if PATH changed.")
+        lines.append("  Run from the project directory: graphify extract . --code-only")
+        lines.append(f"  Generate HTML/report: {_graphify_command((executable, 'cluster-only', str(project), '--no-label'))}")
+        lines.append(f"  Query: {_graphify_command((executable, 'query', 'show the main modules', '--graph', str(project / 'graphify-out/graph.json')))}")
+        lines.append("  Refresh after code changes: rerun the code-only build and HTML/report commands.")
+        lines.append(f"  Outputs: {project / 'graphify-out'} (graph.json, graph.html, GRAPH_REPORT.md)")
+        lines.append("  Assistant skill: $graphify (Codex), /graphify (Claude Code); Cursor/Antigravity use Graphify by default through project rules.")
+    return "\n".join(lines)
+
+
+def run_install(
+    options: Options,
+    *,
+    emit: Callable[[str], None] = print,
+    runner: Callable[[Step, Callable[[str], None]], None] = run_command,
+) -> None:
+    options = validate_options(options)
+    existing = _load_manifest(options.project)
+    if existing:
+        if existing["graph"] != options.graph:
+            raise InstallError(
+                f"{existing['graph']} is already managed for this project; uninstall it first."
+            )
+        clients = tuple(dict.fromkeys([
+            *existing.get("clients", [existing["client"]]), *options.clients,
+        ]))
+        options = replace(
+            options, client=clients[0], clients=clients,
+            addons=tuple(dict.fromkeys([*existing.get("addons", []), *options.addons])),
+            extras=tuple(dict.fromkeys([*existing.get("extras", []), *options.extras])),
+            package=options.package or (
+                str(existing["package"]) if existing.get("package") else None
+            ),
+            index=options.index and bool(existing.get("index", False)),
+        )
+    emit(format_plan(options))
+    if options.dry_run:
+        emit("\nDry-run: no files written, dependencies downloaded, or processes run.")
+        return
+    preflight(options)
+    adopted_global = _ensure_antigravity_slot(options)
+    global_client = "antigravity" if "antigravity" in options.clients else ""
+    manifest = _install_manifest(options)
+    existing_instructions = _integration_instruction_state(options.project, manifest)
+    if any(not state["removable"] for state in existing_instructions):
+        raise InstallError(
+            "Integration instructions were modified; restore or remove the managed block "
+            "before reinstalling."
+        )
+    plan = build_plan(options)
+    codegraph_guidance = (
+        options.graph == "codegraph" and "antigravity" in options.clients
+    )
+    activate_instructions = bool(options.addons or codegraph_guidance)
+    total_steps = len(plan) + int(activate_instructions)
+    manifest["completed_steps"] = []
+    manifest.pop("retry_command", None)
+    _save_manifest(options.project, manifest)
+    for number, step in enumerate(plan, 1):
+        emit(f"\n[{number}/{total_steps}] {step.label}")
+        before = _snapshot(options.project)
+        before_global = _global_entry_snapshot(
+            options.graph, global_client,
+        )
+        config_step = step.client is not None and step.label.startswith("Configure ")
+        force_paths = (
+            {"AGENTS.md", ".agents/rules/drift.md"}
+            if options.graph == "adl-drift" and step.client == "antigravity" and config_step
+            else set()
+        )
+        try:
+            runner(step, emit)
+            if options.graph == "codegraph" and step.client == "antigravity" and config_step:
+                _configure_antigravity_codegraph(options.project)
+        except BaseException:
+            _record_changes(
+                manifest, before, _snapshot(options.project), step.owner, force_paths,
+            )
+            _record_global_changes(
+                manifest, before_global,
+                _global_entry_snapshot(options.graph, global_client),
+                force=config_step and step.client == "antigravity", adopted=adopted_global,
+            )
+            manifest["failed_step"] = step.label
+            manifest["retry_command"] = _install_retry_command(options)
+            _save_manifest(options.project, manifest)
+            emit(
+                f"\n✗ Stopped after {number - 1}/{total_steps} completed steps.\n"
+                f"  Retry: {manifest['retry_command']}"
+            )
+            raise
+        _record_changes(
+            manifest, before, _snapshot(options.project), step.owner, force_paths,
+        )
+        _record_global_changes(
+            manifest, before_global,
+            _global_entry_snapshot(options.graph, global_client),
+            force=config_step and step.client == "antigravity", adopted=adopted_global,
+        )
+        manifest.pop("failed_step", None)
+        if config_step and step.client:
+            configured = manifest.setdefault("configured_clients", [])
+            assert isinstance(configured, list)
+            if step.client not in configured:
+                configured.append(step.client)
+        completed = manifest.setdefault("completed_steps", [])
+        assert isinstance(completed, list)
+        completed.append(step.label)
+        _save_manifest(options.project, manifest)
+        emit(f"  ✓ Completed {number}/{total_steps} steps.")
+    if activate_instructions:
+        number = len(plan) + 1
+        label = "Activate integration instructions"
+        emit(f"\n[{number}/{total_steps}] {label}")
+        active_addons = tuple(manifest.get("addons", options.addons))
+        try:
+            _activate_integration_instructions(
+                options.project, manifest, options.clients, active_addons,
+                codegraph=codegraph_guidance,
+            )
+        except BaseException:
+            manifest["failed_step"] = label
+            manifest["retry_command"] = _install_retry_command(options)
+            _save_manifest(options.project, manifest)
+            emit(
+                f"\n✗ Stopped after {number - 1}/{total_steps} completed steps.\n"
+                f"  Retry: {manifest['retry_command']}"
+            )
+            raise
+        manifest.pop("failed_step", None)
+        manifest.pop("retry_command", None)
+        completed = manifest.setdefault("completed_steps", [])
+        assert isinstance(completed, list)
+        completed.append(label)
+        _save_manifest(options.project, manifest)
+        emit(f"  ✓ Completed {number}/{total_steps} steps.")
+    manifest.pop("failed_step", None)
+    manifest.pop("retry_command", None)
+    _save_manifest(options.project, manifest)
+    emit(_format_completion_summary(manifest, options.project, action="Installation"))
+
+
+def _runtime_update_steps(project: Path, manifest: dict[str, object]) -> tuple[Step, ...]:
+    graph = str(manifest["graph"])
+    if graph == "gitnexus":
+        return (Step(
+            f"Upgrade Git Nexus runtime ({GITNEXUS_PACKAGE})",
+            ("npm", "install", "--prefix", str(project / RUNTIME_PATHS[graph]),
+             "--no-audit", "--no-fund", GITNEXUS_PACKAGE), project, 1800,
+        ),)
+    if graph == "codegraph":
+        return (
+            Step(
+                f"Upgrade CodeGraph runtime ({CODEGRAPH_PACKAGE})",
+                (
+                    "npm", "install", "--prefix", str(project / RUNTIME_PATHS[graph]),
+                    "--no-audit", "--no-fund", CODEGRAPH_PACKAGE,
+                ),
+                project, 1800,
+            ),
+            _codegraph_global_step(
+                project, f"Upgrade global CodeGraph command ({CODEGRAPH_PACKAGE})",
+            ),
+        )
+    package = manifest.get("package")
+    if graph == "other" and not package:
+        raise InstallError(
+            "This older custom-package installation did not save its pip package spec. "
+            "Re-run `adl-toolkit install --graph other --package <name-or-pin> "
+            f"--project {shlex.quote(str(project))}` once to save it, then retry update."
+        )
+    extras = tuple(str(item) for item in manifest.get("extras", ()))
+    suffix = f"[{','.join(extras)}]" if extras else ""
+    install_spec = str(package) if graph == "other" else f"{REPO_ROOT}{suffix}"
+    if graph == "graphify":
+        install_spec = GRAPHIFY_PACKAGE
+    runtime_step = Step(
+        "Upgrade graph runtime",
+        (
+            str(_venv_executable(project, "python")), "-m", "pip", "install",
+            "--upgrade", install_spec,
+        ),
+        project, 1800,
+    )
+    return (runtime_step, _graphify_global_step(project)) if graph == "graphify" else (runtime_step,)
+
+
+def run_update(
+    project: Path, *, dry_run: bool = False,
+    emit: Callable[[str], None] = print,
+    runner: Callable[[Step, Callable[[str], None]], None] = run_command,
+) -> None:
+    project = project.expanduser().resolve()
+    if not project.is_dir():
+        raise ValueError(f"Project directory does not exist: {project}")
+    manifest = _load_manifest(project)
+    if manifest is None:
+        raise InstallError("No installation manifest found. Run `adl-toolkit install` first.")
+    steps = _runtime_update_steps(project, manifest)
+    runtime_ready, runtime_path = _runtime_ready(str(manifest["graph"]), project)
+    if not runtime_ready:
+        raise InstallError(
+            f"Cannot update because the managed runtime is missing: {runtime_path}. "
+            "Run the saved install command again to restore it."
+        )
+    emit("\nUpdate plan:")
+    emit(f"  Project: {project}")
+    emit(f"  Graph tool: {manifest['graph']}")
+    if manifest["graph"] == "codegraph":
+        emit(f"  Approved CodeGraph pin: {CODEGRAPH_PACKAGE}")
+        emit("  The shared global CodeGraph command will be aligned to this pin")
+    emit("  Runtime only: clients, add-ons, instructions, and index are preserved")
+    for number, step in enumerate(steps, 1):
+        emit(f"\n  {number}. {step.label}\n     $ {_display_command(step.command)}")
+    if dry_run:
+        emit("\nDry-run: no files, configurations, or runtimes were changed.")
+        return
+    if manifest["graph"] == "codegraph":
+        preflight(Options("codegraph", project, index=False))
+    previous_failed_step = manifest.get("failed_step")
+    previous_retry_command = manifest.get("retry_command")
+    previous_completed_steps = list(manifest.get("completed_steps", ()))
+    manifest["update_completed_steps"] = []
+    manifest.pop("update_failed_step", None)
+    manifest.pop("update_retry_command", None)
+    _save_manifest(project, manifest)
+    for number, step in enumerate(steps, 1):
+        emit(f"\n[{number}/{len(steps)}] {step.label}")
+        try:
+            runner(step, emit)
+        except BaseException:
+            manifest["update_failed_step"] = step.label
+            manifest["update_retry_command"] = _display_command(
+                ("adl-toolkit", "update", "--project", str(project))
+            )
+            _save_manifest(project, manifest)
+            emit(
+                f"\n✗ Stopped after {number - 1}/{len(steps)} completed steps.\n"
+                f"  Retry: {manifest['update_retry_command']}"
+            )
+            raise
+        completed = manifest.setdefault("update_completed_steps", [])
+        assert isinstance(completed, list)
+        completed.append(step.label)
+        _save_manifest(project, manifest)
+        emit(f"  ✓ Completed {number}/{len(steps)} steps.")
+    manifest.pop("update_failed_step", None)
+    manifest.pop("update_retry_command", None)
+    manifest["completed_steps"] = previous_completed_steps
+    if previous_failed_step is None:
+        manifest.pop("failed_step", None)
+    else:
+        manifest["failed_step"] = previous_failed_step
+    if previous_retry_command is None:
+        manifest.pop("retry_command", None)
+    else:
+        manifest["retry_command"] = previous_retry_command
+    _save_manifest(project, manifest)
+    emit(_format_completion_summary(manifest, project, action="Update"))
+
+
+def _runtime_ready(graph: str, project: Path) -> tuple[bool, Path]:
+    if graph in {"gitnexus", "graphify"}:
+        path = _gitnexus_executable(project) if graph == "gitnexus" else _venv_executable(project, "graphify")
+        return path.is_file(), path
+    if graph == "adl-drift":
+        path = _venv_executable(project, "adl-drift")
+        return path.is_file(), path
+    if graph == "codegraph":
+        path = _codegraph_executable(project)
+        return path.is_file(), path
+    path = _venv_executable(project, "python")
+    return path.is_file(), path
+
+
+def _client_configured(graph: str, client: str, project: Path) -> tuple[bool, str]:
+    if graph == "other":
+        return True, "No automatic MCP configuration for custom packages"
+    if graph == "graphify":
+        for relative in _graphify_client_files(project, client):
+            _assert_no_symlink(project, relative)
+            if not (project / relative).is_file():
+                return False, f"Missing Graphify skill or rule: {relative}"
+    server_names = _global_server_names(graph, "antigravity")
+    if client == "antigravity":
+        expected_name, expected_entry = _expected_antigravity_entry(graph, project)
+        found: list[str] = []
+        for config in ANTIGRAVITY_CONFIGS:
+            path, _, document = _read_antigravity_config(config)
+            servers = document.get("mcpServers", {})
+            assert isinstance(servers, dict)
+            for name in server_names:
+                if name in servers:
+                    if name == expected_name and servers[name] == expected_entry:
+                        return True, str(path)
+                    found.append(f"{path} ({name})")
+        if found:
+            return False, "Different project entry in " + ", ".join(found)
+        return False, "Antigravity MCP entry is missing"
+
+    relative = CLIENT_CONFIG_PATHS[client]
+    path = project / relative
+    _assert_no_symlink(project, relative)
+    if not path.is_file():
+        return False, f"Missing {relative.as_posix()}"
+    names = ("adl-drift", "drift") if graph == "adl-drift" else (graph,)
+    try:
+        if client == "codex":
+            text = path.read_text(encoding="utf-8")
+            entries = []
+            for name in names:
+                match = re.search(
+                    rf"(?ms)^\[mcp_servers\.{re.escape(name)}\]\s*\n(.*?)"
+                    rf"(?=^\[|\Z)", text,
+                )
+                if match:
+                    values = dict(re.findall(r"(?m)^(command|args)\s*=\s*(.+)$", match.group(1)))
+                    entries.append({key: json.loads(value) for key, value in values.items()})
+        else:
+            document = json.loads(path.read_text(encoding="utf-8"))
+            servers = document.get("mcpServers", {}) if isinstance(document, dict) else {}
+            entries = [servers[name] for name in names if name in servers] if isinstance(servers, dict) else []
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return False, f"Cannot read a valid MCP configuration from {relative.as_posix()}"
+    if not entries:
+        return False, f"Graph server entry is missing from {relative.as_posix()}"
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        if graph in {"gitnexus", "graphify"}:
+            expected = _managed_mcp_entry(graph, project)
+            ready = all(entry.get(key) == value for key, value in expected.items())
+        elif graph == "adl-drift":
+            expected = _expected_antigravity_entry(graph, project)[1]
+            if client in {"claude", "cursor"}:
+                expected["args"] = ["-m", "adl_drift.server.mcp_stdio", "--project", "."]
+            ready = all(entry.get(key) == value for key, value in expected.items())
+        else:
+            command, args = entry.get("command"), entry.get("args")
+            ready = (
+                isinstance(command, str)
+                and re.split(r"[/\\]", command)[-1] in {"codegraph", "codegraph.cmd", "codegraph.exe"}
+                and args in (["serve", "--mcp"], ["serve", "--mcp", "--path", str(project)])
+            )
+        if ready:
+            return True, f"Server entry matches this project in {relative.as_posix()} (live handshake not run)"
+    return False, f"Graph server command or arguments do not match this project in {relative.as_posix()}"
+
+
+def _artifact_digest(project: Path, manifest: dict[str, object], relative: str) -> str | None:
+    path = project / _safe_relative(relative)
+    if not path.is_file():
+        return None
+    content = _without_integration_instructions(manifest, relative, path.read_bytes())
+    return _digest(content) if content is not None else None
+
+
+def inspect_health(project: Path) -> HealthReport:
+    project = project.expanduser().resolve()
+    if not project.is_dir():
+        raise ValueError(f"Project directory does not exist: {project}")
+    manifest = _load_manifest(project)
+    if manifest is None:
+        return HealthReport(project, None, (), (), (
+            HealthCheck(
+                "installation", "manifest", "error",
+                "No ADL Toolkit installation manifest was found.",
+                "Run `adl-toolkit install` for this project.",
+            ),
+        ))
+
+    graph = str(manifest["graph"])
+    clients = tuple(str(item) for item in manifest.get("clients", [manifest["client"]]))
+    configured = set(str(item) for item in manifest.get("configured_clients", clients))
+    addons = tuple(str(item) for item in manifest.get("addons", ()))
+    checks: list[HealthCheck] = []
+
+    runtime_ready, runtime_path = _runtime_ready(graph, project)
+    checks.append(HealthCheck(
+        "runtime", graph, "ok" if runtime_ready else "error",
+        str(runtime_path) if runtime_ready else f"Missing runtime executable: {runtime_path}",
+        None if runtime_ready else "Run `adl-toolkit install` again to restore the runtime.",
+    ))
+
+    for client in clients:
+        ready, detail = _client_configured(graph, client, project)
+        if graph != "other" and client not in configured:
+            ready = False
+            detail = "Client setup did not complete"
+        checks.append(HealthCheck(
+            "client", client, "ok" if ready else "error", detail,
+            None if ready else "Run `adl-toolkit repair`.",
+        ))
+        relative = CLIENT_CONFIG_PATHS.get(client)
+        if relative is not None:
+            artifacts = manifest.get("artifacts", {})
+            assert isinstance(artifacts, dict)
+            record = artifacts.get(relative.as_posix())
+            if isinstance(record, dict):
+                current = _artifact_digest(project, manifest, relative.as_posix())
+                if current is not None and current != record.get("installed_sha256"):
+                    checks.append(HealthCheck(
+                        "client", client, "warning",
+                        f"{relative.as_posix()} changed after installation; user changes are preserved",
+                    ))
+
+    instruction_paths = set()
+    instructions = manifest.get("integration_instructions", {})
+    if isinstance(instructions, dict):
+        instruction_paths = set(instructions)
+        expected_instruction_clients: dict[str, set[str]] = {}
+        for client in clients:
+            if addons or (graph == "codegraph" and client == "antigravity"):
+                key = INTEGRATION_INSTRUCTION_PATHS[client].as_posix()
+                expected_instruction_clients.setdefault(key, set()).add(client)
+        for relative, expected_clients in sorted(expected_instruction_clients.items()):
+            record = instructions.get(relative)
+            if not isinstance(record, dict):
+                checks.append(HealthCheck(
+                    "instructions", relative, "error", "Managed instruction block is missing",
+                    "Run `adl-toolkit repair`.",
+                ))
+                continue
+            record_clients = set(str(item) for item in record.get("clients", ()))
+            record_addons = set(str(item) for item in record.get("addons", ()))
+            expected_codegraph = graph == "codegraph" and "antigravity" in expected_clients
+            if (not expected_clients <= record_clients or record_addons != set(addons)
+                    or bool(record.get("codegraph", False)) != expected_codegraph):
+                checks.append(HealthCheck(
+                    "instructions", relative, "error",
+                    "Managed instructions do not match the saved selections",
+                    "Run `adl-toolkit repair`.",
+                ))
+        states = {
+            state["relative"].as_posix(): state
+            for state in _integration_instruction_state(project, manifest)
+            if isinstance(state.get("relative"), Path)
+        }
+        for relative in sorted(instructions):
+            state = states[relative]
+            if state["removable"]:
+                checks.append(HealthCheck("instructions", relative, "ok", "Managed block is active"))
+            else:
+                path = project / _safe_relative(relative)
+                missing = not path.exists()
+                checks.append(HealthCheck(
+                    "instructions", relative, "error",
+                    "Managed instruction file is missing" if missing
+                    else "Managed instruction block was changed or removed",
+                    "Run `adl-toolkit repair`; modified managed blocks are preserved for manual review.",
+                ))
+
+    artifacts = manifest.get("artifacts", {})
+    assert isinstance(artifacts, dict)
+    config_paths = {path.as_posix() for path in CLIENT_CONFIG_PATHS.values()}
+    for relative, record in sorted(artifacts.items()):
+        assert isinstance(record, dict)
+        if relative in instruction_paths or relative in config_paths:
+            continue
+        owner = str(record.get("owner", ""))
+        if owner.startswith("addon:"):
+            continue
+        current = _artifact_digest(project, manifest, relative)
+        expected = record.get("installed_sha256")
+        if current == expected:
+            checks.append(HealthCheck("managed file", relative, "ok", "Present and unchanged"))
+        elif current is None:
+            checks.append(HealthCheck(
+                "managed file", relative, "error", "Managed file is missing",
+                "Run `adl-toolkit repair`.",
+            ))
+        else:
+            checks.append(HealthCheck(
+                "managed file", relative, "warning",
+                "File changed after installation; repair will preserve it",
+            ))
+
+    checked_skills: set[tuple[Path, str]] = set()
+    for addon in addons:
+        for client in clients:
+            root = INTEGRATION_SKILL_ROOTS[client]
+            key = (root, addon)
+            if key in checked_skills:
+                continue
+            checked_skills.add(key)
+            relative = root / addon / "SKILL.md"
+            path = project / relative
+            if path.is_file():
+                checks.append(HealthCheck("integration", f"{addon} ({root})", "ok", str(relative)))
+            else:
+                source = ADDON_SOURCES[addon]
+                agent = SKILLS_AGENT[client]
+                command = _display_command((
+                    "npx", "--yes", SKILLS_PACKAGE, "add", source,
+                    "--skill", "*", "-a", agent, "--copy", "--yes",
+                ))
+                checks.append(HealthCheck(
+                    "integration", f"{addon} ({root})", "error",
+                    f"Missing {relative.as_posix()}",
+                    f"Reinstall the selected skills: `{command}`",
+                ))
+
+    index_paths = INDEX_PATHS[graph]
+    if not index_paths:
+        checks.append(HealthCheck("index", graph, "info", "Not managed for custom packages"))
+    else:
+        present = [path for path in index_paths if (project / path).exists()]
+        detail = (
+            "Present (freshness is not checked): " + ", ".join(path.as_posix() for path in present)
+            if present else "Not found (it may have been skipped during installation)"
+        )
+        checks.append(HealthCheck("index", graph, "info", detail))
+
+    if manifest.get("failed_step"):
+        checks.append(HealthCheck(
+            "installation", "last attempt", "error",
+            f"Incomplete step: {manifest['failed_step']}",
+            "Run `adl-toolkit repair`; reinstall if it reports a missing runtime or skill.",
+        ))
+    if manifest.get("update_failed_step"):
+        retry = str(manifest.get(
+            "update_retry_command",
+            _display_command(("adl-toolkit", "update", "--project", str(project))),
+        ))
+        checks.append(HealthCheck(
+            "installation", "last update", "error",
+            f"Incomplete update step: {manifest['update_failed_step']}",
+            f"Retry the runtime update: `{retry}`",
+        ))
+    if manifest.get("uninstall_error"):
+        checks.append(HealthCheck(
+            "installation", "uninstall", "error",
+            f"Previous uninstall failed: {manifest['uninstall_error']}",
+            "Retry `adl-toolkit uninstall`.",
+        ))
+    return HealthReport(project, graph, clients, addons, tuple(checks))
+
+
+def format_health(report: HealthReport, *, title: str = "Toolkit status") -> str:
+    lines = [
+        f"\n{title}:",
+        f"  Project: {report.project}",
+        f"  Graph tool: {report.graph or 'not installed'}",
+        f"  Clients: {', '.join(report.clients) or 'none'}",
+        f"  Integrations: {', '.join(report.addons) or 'none'}",
+    ]
+    symbols = {"ok": "✓", "error": "✗", "warning": "!", "info": "•"}
+    for check in report.checks:
+        lines.append(
+            f"  {symbols[check.state]} {check.category} / {check.name}: {check.detail}"
+        )
+        if check.action:
+            lines.append(f"      → {check.action}")
+    lines.append(
+        "\n✓ Installation file checks passed."
+        if report.healthy else "\n✗ Installation needs attention."
+    )
+    lines.append("Live MCP connection and index freshness are not checked.")
+    return "\n".join(lines)
+
+
+def run_status(
+    project: Path, *, emit: Callable[[str], None] = print, doctor: bool = False,
+) -> bool:
+    report = inspect_health(project)
+    emit(format_health(report, title="Toolkit doctor" if doctor else "Toolkit status"))
+    if doctor and report.healthy and report.graph == "adl-drift":
+        step = Step(
+            "Check live MCP handshake",
+            (str(_venv_executable(report.project, "adl-drift")),
+             "-p", str(report.project), "mcp", "doctor"),
+            report.project, 90,
+        )
+        try:
+            run_command(step, emit)
+        except InstallError as error:
+            emit(f"\n✗ Live MCP connection failed:\n{error}")
+            return False
+    return report.healthy
+
+
+def _client_setup_step(graph: str, project: Path, client: str) -> Step | None:
+    if graph in {"gitnexus", "graphify"}:
+        return _managed_mcp_step(graph, project, client)
+    if graph == "adl-drift":
+        return Step(
+            f"Repair MCP client ({client})",
+            (str(_venv_executable(project, "adl-drift")), "-p", str(project),
+             "mcp", "setup", f"--{client}"),
+            project, owner=f"client:{client}", client=client,
+        )
+    if graph == "codegraph":
+        return Step(
+            f"Repair CodeGraph client ({client})",
+            (str(_codegraph_executable(project)), "install", "--target", client,
+             "--location", "global" if client == "antigravity" else "local",
+             "--yes", "--no-permissions"),
+            project, owner=f"client:{client}", client=client,
+        )
+    return None
+
+
+def _client_owned_artifacts(
+    manifest: dict[str, object], client: str,
+) -> dict[str, dict[str, object]]:
+    artifacts = manifest.get("artifacts", {})
+    assert isinstance(artifacts, dict)
+    owners = {f"client:{client}"}
+    if client == manifest.get("client"):
+        owners.add("graph")
+    return {
+        relative: record for relative, record in artifacts.items()
+        if isinstance(record, dict) and record.get("owner") in owners
+    }
+
+
+def _repair_instruction_blocks(
+    project: Path, manifest: dict[str, object], *, dry_run: bool,
+    emit: Callable[[str], None],
+) -> bool:
+    addons = tuple(str(item) for item in manifest.get("addons", ()))
+    clients = tuple(str(item) for item in manifest.get("clients", [manifest["client"]]))
+    graph = str(manifest["graph"])
+    expected: dict[Path, list[str]] = {}
+    for client in clients:
+        if addons or (graph == "codegraph" and client == "antigravity"):
+            expected.setdefault(INTEGRATION_INSTRUCTION_PATHS[client], []).append(client)
+    if not expected:
+        return True
+
+    records = manifest.setdefault("integration_instructions", {})
+    assert isinstance(records, dict)
+    complete = True
+    for relative, path_clients in expected.items():
+        _assert_no_symlink(project, relative)
+        key = relative.as_posix()
+        path = project / relative
+        record = records.get(key)
+        if record is not None:
+            assert isinstance(record, dict)
+            stored = str(record["content"])
+            try:
+                current = path.read_text(encoding="utf-8") if path.is_file() else ""
+            except (OSError, UnicodeError):
+                emit(f"  ! Preserved unreadable integration instructions: {key}")
+                complete = False
+                continue
+            if current.count(stored) == 1:
+                merged_clients = tuple(dict.fromkeys([
+                    *(str(item) for item in record.get("clients", ())), *path_clients,
+                ]))
+                desired_codegraph = bool(record.get("codegraph", False)) or (
+                    graph == "codegraph" and "antigravity" in merged_clients
+                )
+                desired = _integration_content(
+                    merged_clients[0], addons,
+                    file_preexisting=bool(record["file_preexisting"]),
+                    codegraph=desired_codegraph,
+                )
+                if desired != stored:
+                    emit(f"  {'$' if dry_run else '✓'} Refresh integration instructions: {key}")
+                    if not dry_run:
+                        path.write_text(current.replace(stored, desired, 1), encoding="utf-8")
+                if not dry_run:
+                    record.update({
+                        "clients": list(merged_clients), "addons": list(addons),
+                        "codegraph": desired_codegraph, "content": desired,
+                    })
+                continue
+            if INTEGRATION_BEGIN in current or INTEGRATION_END in current:
+                emit(f"  ! Preserved modified integration instructions: {key}")
+                complete = False
+                continue
+            emit(f"  {'$' if dry_run else '✓'} Restore integration instructions: {key}")
+            if not dry_run:
+                path.parent.mkdir(parents=True, exist_ok=True)
+                path.write_text(current + stored, encoding="utf-8")
+            continue
+
+        if path.exists() and not path.is_file():
+            emit(f"  ! Preserved non-file integration path: {key}")
+            complete = False
+            continue
+        try:
+            current = path.read_text(encoding="utf-8") if path.is_file() else ""
+        except (OSError, UnicodeError):
+            emit(f"  ! Preserved unreadable integration instructions: {key}")
+            complete = False
+            continue
+        if INTEGRATION_BEGIN in current or INTEGRATION_END in current:
+            emit(f"  ! Preserved unowned integration markers: {key}")
+            complete = False
+            continue
+        if path_clients[0] == "cursor" and path.exists():
+            emit(f"  ! Preserved existing Cursor integration rule: {key}")
+            complete = False
+            continue
+        file_preexisting = path.exists()
+        codegraph = graph == "codegraph" and "antigravity" in path_clients
+        content = _integration_content(
+            path_clients[0], addons, file_preexisting=file_preexisting,
+            codegraph=codegraph,
+        )
+        emit(f"  {'$' if dry_run else '✓'} Create integration instructions: {key}")
+        if not dry_run:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(current + content, encoding="utf-8")
+            records[key] = {
+                "path": key, "clients": list(path_clients), "addons": list(addons),
+                "codegraph": codegraph, "file_preexisting": file_preexisting,
+                "content": content,
+            }
+    return complete
+
+
+def run_repair(
+    project: Path, *, dry_run: bool = False,
+    emit: Callable[[str], None] = print,
+    runner: Callable[[Step, Callable[[str], None]], None] = run_command,
+) -> bool:
+    project = project.expanduser().resolve()
+    if not project.is_dir():
+        raise ValueError(f"Project directory does not exist: {project}")
+    manifest = _load_manifest(project)
+    if manifest is None:
+        raise InstallError("No installation manifest found. Run `adl-toolkit install` first.")
+    graph = str(manifest["graph"])
+    clients = tuple(str(item) for item in manifest.get("clients", [manifest["client"]]))
+    configured = manifest.setdefault("configured_clients", [])
+    assert isinstance(configured, list)
+    runtime_ready, runtime_path = _runtime_ready(graph, project)
+    emit("\nRepair plan:" if dry_run else "\nRepairing ADL Toolkit:")
+    emit(f"  Project: {project}")
+    if not runtime_ready:
+        emit(f"  ! Runtime is missing: {runtime_path}")
+        emit("    Run `adl-toolkit install` again; repair does not download runtimes.")
+
+    instructions = manifest.get("integration_instructions", {})
+    instruction_paths = set(instructions) if isinstance(instructions, dict) else set()
+    for client in clients:
+        ready, detail = _client_configured(graph, client, project)
+        owned = _client_owned_artifacts(manifest, client)
+        missing_owned = [
+            relative for relative in owned
+            if relative not in instruction_paths
+            and _artifact_digest(project, manifest, relative) is None
+        ]
+        needs_repair = client not in configured or not ready or bool(missing_owned)
+        if not needs_repair:
+            continue
+        modified = [
+            relative for relative, record in owned.items()
+            if relative not in instruction_paths
+            and _artifact_digest(project, manifest, relative) is not None
+            and _artifact_digest(project, manifest, relative) != record.get("installed_sha256")
+        ]
+        if modified:
+            emit(
+                f"  ! Preserved modified {client} files; skipped client repair: "
+                + ", ".join(modified)
+            )
+            continue
+        if client == "antigravity" and not ready and detail.startswith("Different project entry"):
+            emit(f"  ! Preserved Antigravity configuration: {detail}")
+            continue
+        step = _client_setup_step(graph, project, client)
+        if step is None:
+            emit(f"  ! {client}: custom packages require manual client configuration")
+            continue
+        if not runtime_ready:
+            continue
+        if dry_run:
+            emit(f"  $ {_display_command(step.command)}")
+            continue
+
+        adopted: set[str] = set()
+        if client == "antigravity":
+            adopted = _ensure_antigravity_slot(Options(
+                graph, project, client=client, clients=(client,), index=False,
+            ))
+        before = _snapshot(project)
+        before_global = _global_entry_snapshot(
+            graph, "antigravity" if client == "antigravity" else "",
+        )
+        owner = "graph" if client == manifest.get("client") else f"client:{client}"
+        force_paths = (
+            {"AGENTS.md", ".agents/rules/drift.md"}
+            if graph == "adl-drift" and client == "antigravity" else set()
+        )
+        try:
+            runner(step, emit)
+            if graph == "codegraph" and client == "antigravity":
+                _configure_antigravity_codegraph(project)
+        except BaseException:
+            _record_changes(manifest, before, _snapshot(project), owner, force_paths)
+            _record_global_changes(
+                manifest, before_global,
+                _global_entry_snapshot(graph, "antigravity" if client == "antigravity" else ""),
+                force=client == "antigravity", adopted=adopted,
+            )
+            manifest["failed_step"] = step.label
+            _save_manifest(project, manifest)
+            raise
+        _record_changes(manifest, before, _snapshot(project), owner, force_paths)
+        _record_global_changes(
+            manifest, before_global,
+            _global_entry_snapshot(graph, "antigravity" if client == "antigravity" else ""),
+            force=client == "antigravity", adopted=adopted,
+        )
+        if client not in configured:
+            configured.append(client)
+        emit(f"  ✓ Repaired client configuration: {client}")
+        _save_manifest(project, manifest)
+
+    instructions_complete = _repair_instruction_blocks(
+        project, manifest, dry_run=dry_run, emit=emit,
+    )
+    if not dry_run:
+        failed_step = str(manifest.get("failed_step", ""))
+        if (failed_step.startswith(("Configure ", "Repair "))
+                and all(_client_configured(graph, client, project)[0] for client in clients)):
+            manifest.pop("failed_step", None)
+        elif failed_step == "Activate integration instructions" and instructions_complete:
+            manifest.pop("failed_step", None)
+        _save_manifest(project, manifest)
+
+    report = inspect_health(project)
+    missing_skills = [
+        check for check in report.checks
+        if check.category == "integration" and check.state == "error"
+    ]
+    for check in missing_skills:
+        if check.action:
+            emit(f"  ! {check.name}: {check.action}")
+    if dry_run:
+        emit("\nDry-run: no files or configurations were changed.")
+        return report.healthy
+    emit(format_health(report, title="Repair result"))
+    return report.healthy
+
+
+def _current_digest(project: Path, relative: Path) -> str | None:
+    _assert_no_symlink(project, relative)
+    path = project / relative
+    return _digest(path.read_bytes()) if path.is_file() else None
+
+
+def _remove_tree(project: Path, relative: Path) -> None:
+    _assert_no_symlink(project, relative)
+    path = project / relative
+    if path.is_dir():
+        shutil.rmtree(path)
+    elif path.exists():
+        raise InstallError(f"Expected a directory but found a file: {path}")
+
+
+def _prune_empty_parents(project: Path, path: Path) -> None:
+    roots = {project / root for root in MANAGED_ROOTS}
+    parent = path.parent
+    while parent != project and any(parent == root or root in parent.parents for root in roots):
+        try:
+            parent.rmdir()
+        except OSError:
+            break
+        parent = parent.parent
+
+
+def _graph_uninstall_step(graph: str, project: Path, client: str) -> Step | None:
+    if graph == "adl-drift":
+        return Step(
+            "Remove ADL-Drift client configuration",
+            (str(_venv_executable(project, "adl-drift")), "-p", str(project),
+             "mcp", "uninstall", f"--{client}"),
+            project, client=client,
+        )
+    if graph == "codegraph":
+        return Step(
+            "Remove CodeGraph client configuration",
+            (str(_codegraph_executable(project)), "uninstall", "--target", client,
+             "--location", "global" if client == "antigravity" else "local",
+             "--yes", "--keep-cli"),
+            project, client=client,
+        )
+    return None
+
+
+def _validate_uninstall_options(options: UninstallOptions) -> UninstallOptions:
+    project = options.project.expanduser().resolve()
+    if not project.is_dir():
+        raise ValueError(f"Project directory does not exist: {project}")
+    if options.graph is not None and options.graph not in GRAPHS:
+        raise ValueError(f"Invalid graph tool: {options.graph}")
+    if options.client is not None and options.client not in CLIENTS:
+        raise ValueError(f"Invalid client: {options.client}")
+    unknown = set(options.addons) - ADDON_SOURCES.keys()
+    if unknown:
+        raise ValueError(f"Invalid add-on: {', '.join(sorted(unknown))}")
+    unknown_clients = set(options.remove_clients) - set(CLIENTS)
+    if unknown_clients:
+        raise ValueError(f"Invalid client: {', '.join(sorted(unknown_clients))}")
+    unknown_addons = set(options.remove_addons) - ADDON_SOURCES.keys()
+    if unknown_addons:
+        raise ValueError(f"Invalid add-on: {', '.join(sorted(unknown_addons))}")
+    if options.purge_index and (options.remove_clients or options.remove_addons):
+        raise ValueError("--purge-index cannot be used with selective removal")
+    return UninstallOptions(
+        project, options.graph, options.client, tuple(dict.fromkeys(options.addons)),
+        options.yes, options.dry_run, options.purge_index,
+        tuple(dict.fromkeys(options.remove_clients)),
+        tuple(dict.fromkeys(options.remove_addons)),
+    )
+
+
+def _preflight_uninstall(steps: Sequence[Step]) -> None:
+    missing: list[str] = []
+    for step in steps:
+        executable = step.command[0]
+        if os.path.sep in executable or (os.altsep and os.altsep in executable):
+            if not Path(executable).is_file():
+                missing.append(executable)
+        elif shutil.which(executable) is None:
+            missing.append(executable)
+    if missing:
+        raise InstallError(
+            "Missing uninstall tools: " + ", ".join(sorted(set(missing)))
+            + ". No files were changed."
+        )
+
+
+def _restore_lock(
+    project: Path, manifest: dict[str, object], selected: set[str],
+    before_skills: dict[str, object], emit: Callable[[str], None],
+) -> set[str]:
+    lock = manifest.get("lock", {})
+    assert isinstance(lock, dict)
+    entries = lock.get("entries", {})
+    assert isinstance(entries, dict)
+    path = project / "skills-lock.json"
+    try:
+        document = json.loads(path.read_text(encoding="utf-8")) if path.exists() else {
+            "version": 1, "skills": {},
+        }
+    except (OSError, json.JSONDecodeError):
+        emit("  ! Preserved modified skills-lock.json")
+        return set(entries)
+    if not isinstance(document, dict) or not isinstance(document.get("skills", {}), dict):
+        emit("  ! Preserved modified skills-lock.json")
+        return set(entries)
+    skills = document.setdefault("skills", {})
+    retained: set[str] = set()
+    for name, record in entries.items():
+        if not isinstance(record, dict) or record.get("addon") not in selected:
+            retained.add(name)
+            continue
+        if before_skills.get(name) != record.get("installed"):
+            emit(f"  ! Preserved modified skill lock entry: {name}")
+            retained.add(name)
+            continue
+        baseline = record.get("baseline")
+        if baseline is None:
+            skills.pop(name, None)
+        else:
+            skills[name] = baseline
+    if not skills and not lock.get("preexisting"):
+        if path.exists():
+            path.unlink()
+    else:
+        path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    return retained
+
+
+def _restore_artifacts(
+    project: Path, manifest: dict[str, object], removable_owners: set[str],
+    before_digests: dict[str, str | None], emit: Callable[[str], None],
+    skip_restore: set[str] | None = None,
+) -> set[str]:
+    artifacts = manifest.get("artifacts", {})
+    assert isinstance(artifacts, dict)
+    retained: set[str] = set()
+    for value, entry in list(artifacts.items()):
+        assert isinstance(entry, dict)
+        if value in (skip_restore or set()):
+            retained.add(value)
+            continue
+        if entry.get("owner") not in removable_owners:
+            if before_digests[value] != entry.get("installed_sha256"):
+                emit(f"  ! Preserved modified file: {value}")
+            retained.add(value)
+            continue
+        if before_digests[value] != entry.get("installed_sha256"):
+            emit(f"  ! Preserved modified file: {value}")
+            retained.add(value)
+            continue
+        relative = _safe_relative(value)
+        path = project / relative
+        baseline = _decoded(entry.get("baseline"))
+        if baseline is None:
+            if path.is_file():
+                path.unlink()
+                _prune_empty_parents(project, path)
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(baseline)
+    return retained
+
+
+def _global_entry_matches(
+    current: dict[str, object], record: dict[str, object], prefix: str,
+) -> bool:
+    return (
+        current.get("present") == record.get(f"{prefix}_present")
+        and current.get("value") == record.get(prefix)
+    )
+
+
+def _codex_uses_adl_runtime(project: Path, *, workflow_only: bool = False) -> bool:
+    path = project / ".codex/config.toml"
+    if not path.is_file():
+        return False
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    expected = _expected_antigravity_entry("adl-drift", project)
+    expected_entry = expected[1]
+    for name in ("adl-drift", "drift"):
+        match = re.search(
+            rf"(?ms)^\[mcp_servers\.{re.escape(name)}\]\n(.*?)"
+            rf"(?=^\[(?!mcp_servers\.{re.escape(name)}(?:\.|\]))|\Z)",
+            text,
+        )
+        if not match:
+            continue
+        values = dict(re.findall(r"(?m)^(command|args)\s*=\s*(.+)$", match.group(1)))
+        try:
+            entry = {"command": json.loads(values["command"]), "args": json.loads(values["args"])}
+        except (KeyError, json.JSONDecodeError):
+            continue
+        if entry == expected_entry or (workflow_only and entry.get("args") == expected_entry["args"]):
+            return True
+    return False
+
+
+def _restore_global_entries(
+    manifest: dict[str, object], current: dict[str, dict[str, object]],
+    emit: Callable[[str], None],
+) -> set[str]:
+    entries = manifest.get("global_entries", {})
+    assert isinstance(entries, dict)
+    retained: set[str] = set()
+    by_config: dict[str, list[tuple[str, str, dict[str, object]]]] = {}
+    for key, record in entries.items():
+        assert isinstance(record, dict)
+        config, server = key.split("/", 1)
+        by_config.setdefault(config, []).append((key, server, record))
+
+    for config, records in by_config.items():
+        path, _, document = _read_antigravity_config(config)
+        servers = document.setdefault("mcpServers", {})
+        assert isinstance(servers, dict)
+        for key, server, record in records:
+            state = current[key]
+            if record["baseline_present"]:
+                # The wrapper found an identical, already-working entry and
+                # never owned it. Leave it in place rather than reconstructing
+                # a global command from project-local manifest data.
+                if not _global_entry_matches(state, record, "installed"):
+                    emit(f"  ! Preserved modified Antigravity MCP entry: {server}")
+                    retained.add(key)
+                continue
+            if state.get("present") and not _global_entry_matches(state, record, "installed"):
+                emit(f"  ! Preserved modified Antigravity MCP entry: {server}")
+                retained.add(key)
+                continue
+            if state.get("present"):
+                servers.pop(server, None)
+        if not servers:
+            document.pop("mcpServers", None)
+        if not document and all(not record["baseline_file_present"] for _, _, record in records):
+            if path.exists():
+                path.unlink()
+        else:
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_text(json.dumps(document, indent=2) + "\n", encoding="utf-8")
+    return retained
+
+
+def _artifact_can_be_removed(
+    project: Path, manifest: dict[str, object], relative: str,
+    record: dict[str, object],
+) -> bool:
+    current = _artifact_digest(project, manifest, relative)
+    return current == record.get("installed_sha256") or (
+        current is None and record.get("baseline") is None
+    )
+
+
+def _restore_selected_artifact(
+    project: Path, manifest: dict[str, object], relative: str,
+    record: dict[str, object], emit: Callable[[str], None],
+) -> bool:
+    if not _artifact_can_be_removed(project, manifest, relative, record):
+        emit(f"  ! Preserved modified file: {relative}")
+        return False
+    path = project / _safe_relative(relative)
+    baseline = _decoded(record.get("baseline"))
+    if baseline is None:
+        if path.is_file():
+            path.unlink()
+            _prune_empty_parents(project, path)
+    else:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_bytes(baseline)
+    return True
+
+
+def _desired_instruction_clients(
+    graph: str, clients: Sequence[str], addons: Sequence[str], relative: str,
+) -> list[str]:
+    return [
+        client for client in clients
+        if INTEGRATION_INSTRUCTION_PATHS[client].as_posix() == relative
+        and (addons or (graph == "codegraph" and client == "antigravity"))
+    ]
+
+
+def _selective_instruction_changes(
+    project: Path, manifest: dict[str, object], clients: Sequence[str],
+    addons: Sequence[str], *, apply: bool,
+) -> bool:
+    records = manifest.get("integration_instructions", {})
+    if not isinstance(records, dict):
+        return True
+    graph = str(manifest["graph"])
+    states = {
+        state["relative"].as_posix(): state
+        for state in _integration_instruction_state(project, manifest)
+        if isinstance(state.get("relative"), Path)
+    }
+    for relative, record in records.items():
+        assert isinstance(record, dict)
+        desired_clients = _desired_instruction_clients(
+            graph, clients, addons, relative,
+        )
+        state = states[relative]
+        if state["removable"]:
+            continue
+        if state["current"] is None and not record["file_preexisting"] and not desired_clients:
+            continue
+        return False
+    if not apply:
+        return True
+    for relative, record in list(records.items()):
+        assert isinstance(record, dict)
+        desired_clients = _desired_instruction_clients(
+            graph, clients, addons, relative,
+        )
+        state = states[relative]
+        if not desired_clients:
+            if state["removable"]:
+                _apply_integration_instruction_removal(state)
+            records.pop(relative, None)
+            continue
+        old_content = str(record["content"])
+        current = str(state["current"])
+        codegraph = graph == "codegraph" and "antigravity" in desired_clients
+        content = _integration_content(
+            desired_clients[0], addons,
+            file_preexisting=bool(record["file_preexisting"]),
+            codegraph=codegraph,
+        )
+        path = project / _safe_relative(relative)
+        path.write_text(current.replace(old_content, content, 1), encoding="utf-8")
+        record.update({
+            "clients": list(desired_clients), "addons": list(addons),
+            "codegraph": codegraph, "content": content,
+        })
+    if not records:
+        manifest.pop("integration_instructions", None)
+    return True
+
+
+def _selective_uninstall_plan(
+    options: UninstallOptions, manifest: dict[str, object],
+) -> tuple[list[str], list[str], list[str], list[str]]:
+    clients = [str(item) for item in manifest.get("clients", [manifest["client"]])]
+    addons = [str(item) for item in manifest.get("addons", ())]
+    remove_clients = list(options.remove_clients)
+    remove_addons = list(options.remove_addons)
+    if not remove_clients and not remove_addons:
+        raise InstallError("Select at least one --remove-client or --remove-addon.")
+    missing_clients = sorted(set(remove_clients) - set(clients))
+    missing_addons = sorted(set(remove_addons) - set(addons))
+    if missing_clients:
+        raise InstallError("Clients are not installed: " + ", ".join(missing_clients))
+    if missing_addons:
+        raise InstallError("Add-ons are not installed: " + ", ".join(missing_addons))
+    remaining_clients = [client for client in clients if client not in remove_clients]
+    if not remaining_clients:
+        raise InstallError(
+            "Selective removal must keep at least one client. "
+            "Run `adl-toolkit uninstall --yes` for a full uninstall."
+        )
+    remaining_addons = [addon for addon in addons if addon not in remove_addons]
+    return remove_clients, remove_addons, remaining_clients, remaining_addons
+
+
+def _run_selective_uninstall(
+    options: UninstallOptions, manifest: dict[str, object], *,
+    emit: Callable[[str], None],
+    runner: Callable[[Step, Callable[[str], None]], None],
+) -> bool:
+    remove_clients, remove_addons, remaining_clients, remaining_addons = (
+        _selective_uninstall_plan(options, manifest)
+    )
+    graph = str(manifest["graph"])
+    configured = [str(item) for item in manifest.get("configured_clients", ())]
+    artifacts = manifest.get("artifacts", {})
+    assert isinstance(artifacts, dict)
+    selected_owners = {f"client:{client}" for client in remove_clients}
+    if str(manifest["client"]) in remove_clients:
+        selected_owners.add("graph")
+    orphan_roots = {
+        INTEGRATION_SKILL_ROOTS[client] for client in remove_clients
+        if INTEGRATION_SKILL_ROOTS[client]
+        not in {INTEGRATION_SKILL_ROOTS[item] for item in remaining_clients}
+    }
+    selected_artifacts = {
+        relative: record for relative, record in artifacts.items()
+        if isinstance(record, dict) and (
+            record.get("owner") in selected_owners
+            or record.get("owner") in {f"addon:{addon}" for addon in remove_addons}
+            or (
+                str(record.get("owner", "")).startswith("addon:")
+                and any(root == _safe_relative(relative)
+                        or root in _safe_relative(relative).parents for root in orphan_roots)
+            )
+        )
+    }
+    retained_graphify_skills: dict[str, str] = {}
+    if graph == "graphify":
+        for client in remaining_clients:
+            relative, _ = _graphify_skill(options.project, client)
+            key = relative.as_posix()
+            if key in selected_artifacts:
+                selected_artifacts.pop(key)
+                retained_graphify_skills[key] = client
+    steps = [
+        step for client in remove_clients if client in configured and client != "antigravity"
+        for step in [_graph_uninstall_step(graph, options.project, client)] if step is not None
+    ]
+    emit("\nSelective uninstall plan:")
+    emit(f"  Project: {options.project}")
+    emit(f"  Remove clients: {', '.join(remove_clients) or 'none'}")
+    emit(f"  Remove add-ons: {', '.join(remove_addons) or 'none'}")
+    emit("  Runtime and index: preserved")
+    for step in steps:
+        emit(f"  $ {_display_command(step.command)}")
+    if options.dry_run:
+        emit("\nDry-run: no files, configurations, runtimes, or indexes were changed.")
+        return True
+    shared_agents = bool(
+        {"codex", "antigravity"} & set(remaining_clients)
+    )
+    blocked_artifacts = [
+        relative for relative, record in selected_artifacts.items()
+        if not (relative == "AGENTS.md" and shared_agents)
+        and not _artifact_can_be_removed(options.project, manifest, relative, record)
+    ]
+    if blocked_artifacts:
+        emit("  ! Preserved modified files: " + ", ".join(sorted(blocked_artifacts)))
+        manifest["uninstall_error"] = "Selective removal blocked by modified files"
+        _save_manifest(options.project, manifest)
+        return False
+    if not _selective_instruction_changes(
+        options.project, manifest, remaining_clients, remaining_addons, apply=False,
+    ):
+        emit("  ! Preserved modified integration instructions; manifest retained for retry.")
+        manifest["uninstall_error"] = "Selective removal blocked by modified integration instructions"
+        _save_manifest(options.project, manifest)
+        return False
+
+    before_skills = _lock_skills(
+        (options.project / "skills-lock.json").read_bytes()
+        if (options.project / "skills-lock.json").is_file() else None
+    )
+    lock = manifest.get("lock", {})
+    assert isinstance(lock, dict)
+    lock_entries = lock.get("entries", {})
+    assert isinstance(lock_entries, dict)
+    changed_lock = [
+        name for name, record in lock_entries.items()
+        if isinstance(record, dict) and record.get("addon") in remove_addons
+        and before_skills.get(name) != record.get("installed")
+        and not (name not in before_skills and record.get("baseline") is None)
+    ]
+    if changed_lock:
+        emit("  ! Preserved modified skill lock entries: " + ", ".join(sorted(changed_lock)))
+        manifest["uninstall_error"] = "Selective removal blocked by modified skill lock entries"
+        _save_manifest(options.project, manifest)
+        return False
+
+    _preflight_uninstall(steps)
+    completed_clients: list[str] = []
+    try:
+        for step in steps:
+            runner(step, emit)
+            if step.client:
+                if graph != "other" and _client_configured(
+                    graph, step.client, options.project,
+                )[0]:
+                    raise InstallError(
+                        f"Native uninstall did not remove the {step.client} client entry"
+                    )
+                completed_owners = {f"client:{step.client}"}
+                if step.client == manifest["client"]:
+                    completed_owners.add("graph")
+                for relative, record in artifacts.items():
+                    if (isinstance(record, dict)
+                            and record.get("owner") in completed_owners
+                            and not (relative == "AGENTS.md" and shared_agents)):
+                        record["installed_sha256"] = _artifact_digest(
+                            options.project, manifest, relative,
+                        )
+                completed_clients.append(step.client)
+        if "antigravity" in remove_clients:
+            retained_global = _restore_global_entries(
+                manifest, _global_entry_snapshot(graph, "antigravity"), emit,
+            )
+            if retained_global:
+                raise InstallError("Antigravity configuration changed after installation")
+            manifest["global_entries"] = {}
+    except BaseException as error:
+        manifest["configured_clients"] = [
+            client for client in configured if client not in completed_clients
+        ]
+        manifest["uninstall_error"] = str(error)
+        _save_manifest(options.project, manifest)
+        raise
+
+    for relative, client in retained_graphify_skills.items():
+        artifacts[relative]["owner"] = f"client:{client}"
+    for relative, record in selected_artifacts.items():
+        assert isinstance(record, dict)
+        if relative == "AGENTS.md" and shared_agents:
+            remaining_owner = next(
+                client for client in remaining_clients
+                if client in {"codex", "antigravity"}
+            )
+            record["owner"] = f"client:{remaining_owner}"
+            continue
+        if not _restore_selected_artifact(
+            options.project, manifest, relative, record, emit,
+        ):
+            manifest["uninstall_error"] = f"Could not remove {relative}"
+            _save_manifest(options.project, manifest)
+            return False
+        artifacts.pop(relative, None)
+
+    if remove_addons:
+        retained_lock = _restore_lock(
+            options.project, manifest, set(remove_addons), before_skills, emit,
+        )
+        removed_names = {
+            name for name, record in lock_entries.items()
+            if isinstance(record, dict) and record.get("addon") in remove_addons
+        }
+        if retained_lock & removed_names:
+            manifest["uninstall_error"] = "Some skill lock entries could not be removed"
+            _save_manifest(options.project, manifest)
+            return False
+        lock["entries"] = {
+            name: record for name, record in lock_entries.items()
+            if name not in removed_names
+        }
+
+    if not _selective_instruction_changes(
+        options.project, manifest, remaining_clients, remaining_addons, apply=True,
+    ):
+        manifest["uninstall_error"] = "Could not refresh integration instructions"
+        _save_manifest(options.project, manifest)
+        return False
+    manifest["clients"] = remaining_clients
+    manifest["client"] = remaining_clients[0]
+    manifest["configured_clients"] = [
+        client for client in configured if client in remaining_clients
+    ]
+    manifest["addons"] = remaining_addons
+    manifest.pop("uninstall_error", None)
+    _save_manifest(options.project, manifest)
+    emit("\n✓ Selective uninstall complete. Runtime and index were preserved.")
+    return True
+
+
+def format_uninstall_plan(options: UninstallOptions) -> str:
+    options = _validate_uninstall_options(options)
+    manifest = _load_manifest(options.project)
+    graph = manifest["graph"] if manifest else options.graph
+    clients = (
+        list(options.remove_clients)
+        if manifest and options.remove_clients
+        else manifest.get("clients", [manifest["client"]]) if manifest else [options.client]
+    )
+    addons = (
+        list(options.remove_addons)
+        if manifest and options.remove_addons else manifest["addons"] if manifest else list(options.addons)
+    )
+    return "\n".join((
+        "\nUninstall plan:",
+        f"  Project: {options.project}",
+        f"  Graph tool: {graph or 'none'}",
+        f"  Clients: {', '.join(str(client) for client in clients if client) or 'none'}",
+        f"  Add-ons: {', '.join(addons) or 'none'}",
+        f"  Purge index: {'yes' if options.purge_index else 'no (preserved)'}",
+    ))
+
+
+def run_uninstall(
+    options: UninstallOptions,
+    *,
+    emit: Callable[[str], None] = print,
+    runner: Callable[[Step, Callable[[str], None]], None] = run_command,
+) -> bool:
+    options = _validate_uninstall_options(options)
+    manifest = _load_manifest(options.project)
+    if manifest and (options.graph or options.client or options.addons):
+        raise InstallError("Graph, client, and add-on selectors are only for legacy installs without a manifest.")
+    if not manifest and (options.remove_clients or options.remove_addons):
+        raise InstallError(
+            "--remove-client and --remove-addon require an installation manifest. "
+            "Use legacy --client/--addon selectors only for legacy cleanup."
+        )
+    if not manifest and not (options.graph or options.addons):
+        raise InstallError("No installation manifest found; select --graph and/or --addon for legacy removal.")
+    if not manifest and options.addons:
+        raise InstallError("Cannot safely remove legacy skills without ownership records. Use the Skills CLI to remove those skills explicitly.")
+    if not options.yes and not options.dry_run:
+        raise InstallError("Uninstall requires --yes.")
+    if manifest and (options.remove_clients or options.remove_addons):
+        return _run_selective_uninstall(
+            options, manifest, emit=emit, runner=runner,
+        )
+
+    graph = str(manifest["graph"]) if manifest else options.graph
+    clients = (
+        [str(client) for client in manifest.get("clients", [manifest["client"]])]
+        if manifest else [options.client or "codex"]
+    )
+    configured_clients = (
+        [str(client) for client in manifest.get("configured_clients", clients)]
+        if manifest else clients
+    )
+    addons = set(manifest["addons"] if manifest else options.addons)
+    emit(format_uninstall_plan(options))
+
+    artifacts = manifest.get("artifacts", {}) if manifest else {}
+    assert isinstance(artifacts, dict)
+    instruction_states = _integration_instruction_state(options.project, manifest)
+    instruction_by_path = {
+        state["relative"].as_posix(): state for state in instruction_states
+        if isinstance(state["relative"], Path)
+    }
+    before_digests = {
+        value: (
+            _digest(str(instruction_by_path[value]["cleaned"]).encode("utf-8"))
+            if value in instruction_by_path and instruction_by_path[value]["removable"]
+            and instruction_by_path[value]["cleaned"] is not None
+            else None
+            if value in instruction_by_path and instruction_by_path[value]["removable"]
+            else _current_digest(options.project, _safe_relative(value))
+        )
+        for value in artifacts
+    }
+    modified_owners = {
+        str(entry.get("owner")) for value, entry in artifacts.items()
+        if isinstance(entry, dict) and before_digests[value] != entry.get("installed_sha256")
+    }
+    global_entries = manifest.get("global_entries", {}) if manifest else {}
+    assert isinstance(global_entries, dict)
+    current_global = _global_entry_snapshot(
+        graph or "", "antigravity" if "antigravity" in clients else "",
+    )
+    modified_global = {
+        key for key, record in global_entries.items()
+        if isinstance(record, dict)
+        and not _global_entry_matches(current_global[key], record, "installed")
+    }
+    global_blocked = bool(modified_global)
+    client_owners = {f"client:{client}" for client in clients}
+    graph_blocked = bool(modified_owners & ({"graph"} | client_owners)) or global_blocked
+    instruction_retained = any(not state["removable"] for state in instruction_states)
+    removable_addons = {
+        addon for addon in addons
+        if f"addon:{addon}" not in modified_owners and not instruction_retained
+    }
+    steps: list[Step] = []
+    graph_managed = (
+        not manifest or bool(global_entries)
+        or any(entry.get("owner") in ({"graph"} | client_owners) for entry in artifacts.values())
+    )
+    managed_antigravity = bool(manifest and "antigravity" in clients)
+    if graph and graph_managed and not global_blocked:
+        steps.extend(
+            step for client in configured_clients
+            if client != "antigravity"
+            for step in [_graph_uninstall_step(graph, options.project, client)]
+            if step is not None
+        )
+    if options.dry_run:
+        for step in steps:
+            emit(f"  $ {_display_command(step.command)}")
+        emit("\nDry-run: no files or runtimes were removed.")
+        return True
+    _preflight_uninstall(steps)
+    before_skills = _lock_skills(
+        (options.project / "skills-lock.json").read_bytes()
+        if (options.project / "skills-lock.json").is_file() else None
+    )
+    if instruction_retained:
+        for instruction_state in instruction_states:
+            if not instruction_state["removable"]:
+                emit(
+                    "  ! Preserved modified integration instructions: "
+                    f"{instruction_state['relative']}"
+                )
+    else:
+        for instruction_state in instruction_states:
+            _apply_integration_instruction_removal(instruction_state)
+
+    def cleanup(action: Callable[[], object]) -> object:
+        try:
+            return action()
+        except BaseException:
+            for instruction_state in instruction_states:
+                if instruction_state["removable"]:
+                    _restore_integration_instruction_after_failure(instruction_state)
+            raise
+
+    completed_clients: set[str] = set()
+    try:
+        for step in steps:
+            runner(step, emit)
+            if step.client:
+                completed_clients.add(step.client)
+    except BaseException as error:
+        try:
+            if manifest:
+                for value, entry in artifacts.items():
+                    if (entry.get("owner") in (
+                            {"graph"} | {f"client:{client}" for client in completed_clients}
+                        )
+                            and before_digests[value] == entry.get("installed_sha256")):
+                        entry["installed_sha256"] = _current_digest(
+                            options.project, _safe_relative(value),
+                        )
+                failed_global = _global_entry_snapshot(
+                    graph or "", "antigravity" if "antigravity" in clients else "",
+                )
+                for key, entry in global_entries.items():
+                    assert isinstance(entry, dict)
+                    entry["installed_present"] = failed_global[key]["present"]
+                    entry["installed"] = failed_global[key]["value"]
+                manifest["uninstall_error"] = str(error)
+                configured = manifest.get("configured_clients", [])
+                if isinstance(configured, list):
+                    manifest["configured_clients"] = [
+                        client for client in configured if client not in completed_clients
+                    ]
+                _save_manifest(options.project, manifest)
+        finally:
+            for instruction_state in instruction_states:
+                if instruction_state["removable"]:
+                    _restore_integration_instruction_after_failure(instruction_state)
+        raise
+
+    retained_artifacts: set[str] = set()
+    retained_lock: set[str] = set()
+    retained_global: set[str] = set(global_entries)
+    if manifest:
+        removable_owners = ({"graph", *client_owners} if not graph_blocked else set()) | {
+            f"addon:{addon}" for addon in removable_addons
+        }
+        native_preserved = set()
+        codex_uses_runtime = (
+            graph == "adl-drift" and "antigravity" in clients
+            and _codex_uses_adl_runtime(options.project, workflow_only=True)
+        )
+        if codex_uses_runtime and "AGENTS.md" in artifacts:
+            native_preserved.add("AGENTS.md")
+        retained_artifacts = cleanup(lambda: _restore_artifacts(
+            options.project, manifest, removable_owners, before_digests, emit,
+            native_preserved,
+        ))
+        assert isinstance(retained_artifacts, set)
+        retained_artifacts -= native_preserved
+        if steps:
+            # Native removal edits only its own client entry. Do not restore a
+            # whole-file baseline over settings added since installation.
+            retained_artifacts = {
+                name for name in retained_artifacts
+                if artifacts[name].get("owner") != "graph"
+            }
+            graph_blocked = False
+            retained_global = cleanup(lambda: _restore_global_entries(
+                manifest, _global_entry_snapshot(
+                    graph or "", "antigravity" if "antigravity" in clients else ""
+                ), emit,
+            ))
+            assert isinstance(retained_global, set)
+            graph_blocked = bool(retained_global)
+        elif managed_antigravity and global_entries and not global_blocked:
+            retained_global = cleanup(lambda: _restore_global_entries(
+                manifest, _global_entry_snapshot(graph or "", "antigravity"), emit,
+            ))
+            assert isinstance(retained_global, set)
+            graph_blocked = bool(retained_global)
+        retained_lock = cleanup(lambda: _restore_lock(
+            options.project, manifest, removable_addons, before_skills, emit,
+        ))
+        assert isinstance(retained_lock, set)
+        artifacts = manifest["artifacts"]
+        assert isinstance(artifacts, dict)
+        manifest["artifacts"] = {
+            name: entry for name, entry in artifacts.items() if name in retained_artifacts
+        }
+        lock = manifest["lock"]
+        assert isinstance(lock, dict)
+        entries = lock.get("entries", {})
+        assert isinstance(entries, dict)
+        lock["entries"] = {name: entry for name, entry in entries.items() if name in retained_lock}
+        manifest["global_entries"] = {
+            name: entry for name, entry in global_entries.items() if name in retained_global
+        }
+        if not instruction_retained:
+            manifest.pop("integration_instructions", None)
+
+    graph_ok = not graph_blocked
+    if graph_blocked:
+        emit("  ! Preserved modified graph configuration; runtime retained for retry.")
+    if graph == "graphify" and graph_ok:
+        skill = Path.home() / ".agents" / "skills" / "graphify"
+        if skill.is_symlink():
+            cleanup(skill.unlink)
+        elif skill.is_dir():
+            cleanup(lambda: shutil.rmtree(skill))
+    runtime = RUNTIME_PATHS.get(graph or "")
+    if runtime and graph_ok:
+        preexisting = False
+        if manifest:
+            runtime_record = manifest.get("runtimes", {}).get(runtime.as_posix(), {})
+            preexisting = runtime_record.get("preexisting", True) if isinstance(runtime_record, dict) else True
+        global_runtime_in_use = any(
+            isinstance(record, dict) and record.get("baseline_present")
+            for record in global_entries.values()
+        )
+        codex_runtime_in_use = (
+            graph == "adl-drift" and "antigravity" in clients
+            and _codex_uses_adl_runtime(options.project)
+        )
+        if not preexisting and not global_runtime_in_use and not codex_runtime_in_use:
+            cleanup(lambda: _remove_tree(options.project, runtime))
+    if options.purge_index and graph:
+        for index in INDEX_PATHS[graph]:
+            preexisting = False
+            if manifest:
+                record = manifest.get("indexes", {}).get(index.as_posix(), {})
+                preexisting = record.get("preexisting", True) if isinstance(record, dict) else True
+            if not preexisting:
+                cleanup(lambda: _remove_tree(options.project, index))
+
+    retained = graph_blocked or instruction_retained or bool(
+        retained_artifacts or retained_lock or retained_global
+    )
+    if manifest and retained:
+        manifest.pop("uninstall_error", None)
+        cleanup(lambda: _save_manifest(options.project, manifest))
+        emit("\nUninstall incomplete; the manifest was retained for a safe retry.")
+        return False
+    elif manifest:
+        path = options.project / MANIFEST_PATH
+        cleanup(path.unlink)
+        try:
+            path.parent.rmdir()
+        except OSError:
+            pass
+        emit("\n✓ Uninstall complete." + ("" if options.purge_index else " Preserved graph index data."))
+        return True
+    else:
+        emit("\n✓ Legacy uninstall complete." + ("" if options.purge_index else " Preserved graph index data."))
+        return True
+
+
+def _choose(title: str, choices: Sequence[tuple[str, str]], default: int = 1) -> str:
+    while True:
+        print(f"\n{title}")
+        for number, (_, label) in enumerate(choices, 1):
+            print(f"  {number}. {label}")
+        answer = input(f"Select [{default}]: ").strip()
+        if not answer:
+            return choices[default - 1][0]
+        if answer.isdigit() and 1 <= int(answer) <= len(choices):
+            return choices[int(answer) - 1][0]
+        print("Invalid selection.")
+
+
+def _checkboxes(title: str, choices: Sequence[tuple[str, str]]) -> tuple[str, ...]:
+    selected: set[str] = set()
+    while True:
+        print(f"\n{title} (enter a number to toggle, Enter to continue)")
+        for number, (value, label) in enumerate(choices, 1):
+            print(f"  {number}. [{'x' if value in selected else ' '}] {label}")
+        answer = input("Select: ").strip()
+        if not answer:
+            return tuple(value for value, _ in choices if value in selected)
+        if answer.isdigit() and 1 <= int(answer) <= len(choices):
+            value = choices[int(answer) - 1][0]
+            selected.symmetric_difference_update((value,))
+        else:
+            print("Invalid selection.")
+
+
+def _yes_no(question: str, default: bool = True) -> bool:
+    suffix = "[Y/n]" if default else "[y/N]"
+    while True:
+        answer = input(f"{question} {suffix}: ").strip().lower()
+        if not answer:
+            return default
+        if answer in {"y", "yes"}:
+            return True
+        if answer in {"n", "no"}:
+            return False
+        print("Please enter y or n.")
+
+
+def wizard(*, dry_run: bool = False) -> Options | None:
+    print("\nInstall ADL Toolkit")
+    graph = _choose(
+        "Choose 1 graph tool:",
+        (
+            ("adl-drift", "ADL-Drift"), ("codegraph", "CodeGraph"),
+            ("graphify", "Graphify"), ("gitnexus", "GitNexus"),
+        ),
+    )
+    addons = _checkboxes(
+        "Choose integration skills",
+        (("caveman", "Caveman"), ("ponytail", "Ponytail")),
+    )
+    clients = _checkboxes(
+        "Choose one or more MCP/agent clients",
+        tuple((item, item.title()) for item in CLIENTS),
+    ) or ("codex",)
+    project_text = input(f"Project [{Path.cwd()}]: ").strip()
+    project = Path(project_text or Path.cwd())
+    extras: tuple[str, ...] = ()
+    package = None
+    if graph == "other":
+        package = input("Pip package name/spec (e.g. code2graph==1.2.0): ").strip()
+    index = graph != "other" and _yes_no("Initialize the index after installation?", True)
+    options = validate_options(
+        Options(graph, project, clients[0], addons, extras, package, index, dry_run, clients)
+    )
+    if dry_run:
+        return options
+    print(format_plan(options))
+    return options if _yes_no("Proceed with installation?", False) else None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        description="Install, inspect, repair, or uninstall one graph tool and selected agent skills."
+    )
+    parser.add_argument(
+        "action", nargs="?",
+        choices=("install", "update", "uninstall", "status", "doctor", "repair"),
+        default="install",
+        help="Action to run (default: install)",
+    )
+    parser.add_argument(
+        "--graph", choices=GRAPHS, help="Graph tool (omit to open the wizard)"
+    )
+    parser.add_argument(
+        "--addon", action="append", choices=tuple(ADDON_SOURCES),
+        help="Add-on skill; repeat as needed (requires --graph)",
+    )
+    parser.add_argument(
+        "--client", action="append", choices=(*CLIENTS, "all"),
+        help="Agent client; repeat or use 'all' (requires --graph)"
+    )
+    parser.add_argument(
+        "--remove-client", action="append", choices=CLIENTS,
+        help="Installed client to remove; repeat as needed (selective uninstall only)",
+    )
+    parser.add_argument(
+        "--remove-addon", action="append", choices=tuple(ADDON_SOURCES),
+        help="Installed add-on to remove; repeat as needed (selective uninstall only)",
+    )
+    parser.add_argument(
+        "--project", type=Path, help="Target project (requires --graph)"
+    )
+    parser.add_argument(
+        "--extra", action="append", choices=EXTRAS,
+        help="ADL optional dependency; repeat as needed (requires --graph)",
+    )
+    parser.add_argument(
+        "--package", help="Pip package spec for --graph other (requires --graph)"
+    )
+    parser.add_argument(
+        "--no-index", dest="index", action="store_false", default=None,
+        help="Skip index initialization (requires --graph)",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Print the full plan without changing the system",
+    )
+    parser.add_argument(
+        "--yes", action="store_true", help="Confirm uninstall without prompting",
+    )
+    parser.add_argument(
+        "--purge-index", action="store_true",
+        help="Also remove index data created by this installer",
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    arguments = list(sys.argv[1:] if argv is None else argv)
+    if arguments and arguments[0] == "setup-graphify-global":
+        internal = argparse.ArgumentParser()
+        internal.add_argument("--project", type=Path, required=True)
+        args = internal.parse_args(arguments[1:])
+        try:
+            _setup_graphify_global(args.project.resolve())
+        except (OSError, InstallError) as error:
+            print(f"Error: {error}", file=sys.stderr)
+            return 1
+        return 0
+    if arguments and arguments[0] == "configure-managed-mcp":
+        internal = argparse.ArgumentParser()
+        internal.add_argument("--graph", choices=("gitnexus", "graphify"), required=True)
+        internal.add_argument("--client", choices=CLIENTS, required=True)
+        internal.add_argument("--project", type=Path, required=True)
+        args = internal.parse_args(arguments[1:])
+        _configure_managed_mcp(args.graph, args.project, args.client)
+        return 0
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.action in {"status", "doctor", "repair", "update"}:
+        unsupported = (
+            args.graph, args.addon, args.client, args.extra, args.package,
+            args.index, args.yes, args.purge_index,
+            args.remove_client, args.remove_addon,
+        )
+        if any(value not in (None, False) for value in unsupported):
+            parser.error(
+                "status, doctor, repair, and update only support --project; "
+                "repair and update also support --dry-run"
+            )
+        if args.dry_run and args.action not in {"repair", "update"}:
+            parser.error("--dry-run is only supported with repair or update")
+        try:
+            project = args.project or Path.cwd()
+            if args.action == "update":
+                run_update(project, dry_run=args.dry_run)
+                return 0
+            if args.action == "repair":
+                return 0 if run_repair(project, dry_run=args.dry_run) else 1
+            return 0 if run_status(project, doctor=args.action == "doctor") else 1
+        except (EOFError, KeyboardInterrupt):
+            print("\nCancelled.", file=sys.stderr)
+            return 130
+        except (ValueError, InstallError) as error:
+            print(f"\nError: {error}", file=sys.stderr)
+            return 1
+    if args.action == "uninstall":
+        if args.extra or args.package or args.index is not None:
+            parser.error("--extra, --package, and --no-index are install options")
+        try:
+            options = UninstallOptions(
+                args.project or Path.cwd(), args.graph,
+                (args.client[0] if args.client and args.client[0] != "all" else None),
+                tuple(args.addon or ()), args.yes, args.dry_run, args.purge_index,
+                tuple(args.remove_client or ()), tuple(args.remove_addon or ()),
+            )
+            if not options.yes and not options.dry_run:
+                print(format_uninstall_plan(options))
+                if not _yes_no("Proceed with uninstall?", False):
+                    print("Cancelled; no changes were made.")
+                    return 0
+                options = replace(options, yes=True)
+            return 0 if run_uninstall(options) else 1
+        except (EOFError, KeyboardInterrupt):
+            print("\nCancelled.", file=sys.stderr)
+            return 130
+        except (ValueError, InstallError) as error:
+            print(f"\nError: {error}", file=sys.stderr)
+            return 1
+    if args.yes or args.purge_index or args.remove_client or args.remove_addon:
+        parser.error(
+            "--yes, --purge-index, --remove-client, and --remove-addon are uninstall options"
+        )
+    selections = (
+        args.addon, args.client, args.project, args.extra, args.package, args.index,
+    )
+    if not args.graph and any(value is not None for value in selections):
+        parser.error(
+            "--graph is required when using --addon, --client, --project, "
+            "--extra, --package, or --no-index"
+        )
+    try:
+        if args.graph:
+            selected_clients = tuple(
+                CLIENTS if "all" in (args.client or ()) else (args.client or ("codex",))
+            )
+            options = Options(
+                args.graph, args.project or Path.cwd(), selected_clients[0],
+                tuple(args.addon or ()), tuple(args.extra or ()), args.package,
+                True if args.index is None else args.index, args.dry_run, selected_clients,
+            )
+        else:
+            options = wizard(dry_run=args.dry_run)
+            if options is None:
+                print("Cancelled; no changes were made.")
+                return 0
+        run_install(options)
+        return 0
+    except (ValueError, InstallError) as error:
+        print(f"\nError: {error}", file=sys.stderr)
+        return 1
+    except (EOFError, KeyboardInterrupt):
+        print("\nCancelled.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())