code-search-cli 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

code_retrieval/cli.py

@@ -9,7 +9,13 @@ from importlib.metadata import PackageNotFoundError, version
 
 from .engine import RetrievalEngine
 from .index_store import PersistentIndex
-from .installer import install_codex_skill, uninstall_codex_skill
+from .installer import (
+    AGENT_SELECTORS,
+    AgentName,
+    agent_display_name,
+    install_skills,
+    uninstall_skills,
+)
 from .models import Evidence
 from .repository import RETRIEVAL_SCOPES, RepositoryReader
 
@@ -51,11 +57,25 @@ def build_parser() -> argparse.ArgumentParser:
     clean = subparsers.add_parser("clean", help="remove the persistent index for a repository")
     _repository_args(clean)
 
-    install = subparsers.add_parser("install", help="install the bundled Codex skill")
+    install = subparsers.add_parser("install", help="install the bundled skill for a coding agent")
+    install.add_argument(
+        "--target",
+        choices=AGENT_SELECTORS,
+        default="codex",
+        help="agent destination; 'detected' uses best-effort local signals (default: codex)",
+    )
     install.add_argument("--force", action="store_true", help="replace a locally modified installed skill")
-
-    uninstall = subparsers.add_parser("uninstall", help="remove the bundled Codex skill")
+    install.add_argument("--dry-run", action="store_true", help="preview changes without writing files")
+
+    uninstall = subparsers.add_parser("uninstall", help="remove the bundled skill for a coding agent")
+    uninstall.add_argument(
+        "--target",
+        choices=AGENT_SELECTORS,
+        default="codex",
+        help="agent destination; 'detected' uses best-effort local signals (default: codex)",
+    )
     uninstall.add_argument("--force", action="store_true", help="remove a locally modified installed skill")
+    uninstall.add_argument("--dry-run", action="store_true", help="preview changes without removing files")
     return parser
 
 
@@ -63,11 +83,14 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     try:
         if args.command in {"install", "uninstall"}:
-            operation = install_codex_skill if args.command == "install" else uninstall_codex_skill
-            path, action = operation(force=args.force)
-            print(f"Codex skill {action}: {path}")
-            if args.command == "install":
-                print("Restart Codex to load the skill.")
+            operation = install_skills if args.command == "install" else uninstall_skills
+            results = operation(target=args.target, force=args.force, dry_run=args.dry_run)
+            for result in results:
+                action = f"would be {result.action}" if args.dry_run else result.action
+                print(f"{agent_display_name(result.agent)} skill {action}: {result.path}")
+            if args.command == "install" and not args.dry_run:
+                for result in results:
+                    print(_skill_reload_hint(result.agent))
             return 0
 
         if args.command in {"index", "status", "clean"}:
@@ -128,6 +151,16 @@ def _non_empty(value: str) -> str:
     return value
 
 
+def _skill_reload_hint(agent: AgentName) -> str:
+    if agent == "codex":
+        return "Restart Codex if the skill does not appear automatically."
+    if agent == "gemini":
+        return "Run /skills reload in Gemini CLI if the skill does not appear automatically."
+    if agent == "kiro":
+        return "Kiro loads Agent Skills automatically; reopen the session if it is not listed."
+    return f"Restart {agent_display_name(agent)} if the skill does not appear automatically."
+
+
 def _evidence_json(evidence: list[Evidence]) -> str:
     from dataclasses import asdict
 

code_retrieval/installer.py

@@ -1,65 +1,468 @@
 from __future__ import annotations
 
+import hashlib
+import json
 import os
+import shutil
+import tempfile
+from dataclasses import dataclass
 from importlib.resources import files
 from pathlib import Path
-from typing import Literal
+from typing import Literal, cast
 
 
+AgentName = Literal[
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "opencode",
+    "github-copilot",
+    "kiro",
+]
+AgentSelector = AgentName | Literal["detected"]
 InstallAction = Literal["created", "updated", "unchanged"]
-SKILL_FILES = (Path("SKILL.md"), Path("agents/openai.yaml"))
+UninstallAction = Literal["removed", "not-found"]
+SkillAction = InstallAction | UninstallAction
+
+AGENT_TARGETS: tuple[AgentName, ...] = (
+    "codex",
+    "claude-code",
+    "cursor",
+    "gemini",
+    "opencode",
+    "github-copilot",
+    "kiro",
+)
+AGENT_SELECTORS: tuple[AgentSelector, ...] = (*AGENT_TARGETS, "detected")
+
+PORTABLE_SKILL_FILES = (Path("SKILL.md"),)
+CODEX_SKILL_FILES = (*PORTABLE_SKILL_FILES, Path("agents/openai.yaml"))
+INSTALL_MANIFEST = Path(".code-search-install.json")
+MANIFEST_SCHEMA = 1
+
+# Official files shipped by the first public release predate install manifests. Recognizing
+# their exact digests lets an untouched v0.1.0 Codex skill upgrade safely without --force.
+LEGACY_FILE_DIGESTS: dict[Path, frozenset[str]] = {
+    Path("SKILL.md"): frozenset(
+        {"559892c5964086beb68446931479bdf60585eca198b2ab871ac81e247ab9b1fb"}
+    ),
+    Path("agents/openai.yaml"): frozenset(
+        {"433e80c4c8bd5a0d19c6a3bec70b2fd849fe48343a2c1438b708bca69ff4bc1b"}
+    ),
+}
+
+
+@dataclass(frozen=True, slots=True)
+class SkillResult:
+    agent: AgentName
+    path: Path
+    action: SkillAction
+
+
+def agent_display_name(agent: AgentName) -> str:
+    return {
+        "codex": "Codex",
+        "claude-code": "Claude Code",
+        "cursor": "Cursor",
+        "gemini": "Gemini CLI",
+        "opencode": "OpenCode",
+        "github-copilot": "GitHub Copilot",
+        "kiro": "Kiro",
+    }[agent]
+
+
+def agent_skills_root(agent: AgentName) -> Path:
+    home = _home()
+    if agent == "codex":
+        codex_home = os.environ.get("CODEX_HOME")
+        if codex_home:
+            return _configured_path(codex_home, "CODEX_HOME") / "skills"
+        legacy_root = home / ".codex" / "skills"
+        if (legacy_root / "code-search").exists():
+            return legacy_root
+        return home / ".agents" / "skills"
+    if agent == "claude-code":
+        claude_home = os.environ.get("CLAUDE_CONFIG_DIR")
+        return (
+            _configured_path(claude_home, "CLAUDE_CONFIG_DIR")
+            if claude_home
+            else home / ".claude"
+        ) / "skills"
+    if agent == "cursor":
+        return home / ".cursor" / "skills"
+    if agent == "gemini":
+        gemini_home = os.environ.get("GEMINI_CLI_HOME")
+        return (
+            _configured_path(gemini_home, "GEMINI_CLI_HOME") if gemini_home else home
+        ) / ".gemini" / "skills"
+
+    if agent == "opencode":
+        opencode_home = os.environ.get("OPENCODE_CONFIG_DIR")
+        if opencode_home:
+            return _configured_path(opencode_home, "OPENCODE_CONFIG_DIR") / "skills"
+        return _xdg_config_home(home) / "opencode" / "skills"
+    if agent == "github-copilot":
+        copilot_home = os.environ.get("COPILOT_HOME")
+        return (
+            _configured_path(copilot_home, "COPILOT_HOME")
+            if copilot_home
+            else home / ".copilot"
+        ) / "skills"
+    if agent == "kiro":
+        return home / ".kiro" / "skills"
+    raise ValueError(f"unsupported agent target: {agent}")
 
 
 def codex_skills_root() -> Path:
-    codex_home = os.environ.get("CODEX_HOME")
-    return (Path(codex_home).expanduser() if codex_home else Path.home() / ".codex") / "skills"
+    """Return the compatible Codex destination used by ``code-search install``."""
+    return agent_skills_root("codex")
 
 
-def install_codex_skill(*, force: bool = False) -> tuple[Path, InstallAction]:
-    target = codex_skills_root() / "code-search"
-    source = files("code_retrieval").joinpath("resources/code-search")
-    existed = target.exists()
-    changed = False
-
-    for relative in SKILL_FILES:
-        destination = target / relative
-        content = source.joinpath(relative.as_posix()).read_text(encoding="utf-8")
-        if destination.exists():
-            existing = destination.read_text(encoding="utf-8")
-            if existing == content:
+def detect_agents() -> tuple[AgentName, ...]:
+    return tuple(agent for agent in AGENT_TARGETS if _agent_is_detected(agent))
+
+
+def install_skills(
+    target: AgentSelector = "codex", *, force: bool = False, dry_run: bool = False
+) -> tuple[SkillResult, ...]:
+    agents = _resolve_agents(target)
+    prepared = [_prepare_install(agent, force=force) for agent in agents]
+
+    if not dry_run:
+        for agent, destination, _action in prepared:
+            source = _skill_source()
+            for relative in _managed_files(agent):
+                output = destination / relative
+                content = source.joinpath(relative.as_posix()).read_bytes()
+                if output.exists() and _content_digest(output.read_bytes()) == _content_digest(
+                    content
+                ):
+                    continue
+                _atomic_write(output, content)
+            manifest = destination / INSTALL_MANIFEST
+            content = _manifest_content(agent).encode("utf-8")
+            if not manifest.exists() or manifest.read_bytes() != content:
+                _atomic_write(manifest, content)
+
+    return tuple(
+        SkillResult(agent=agent, path=destination, action=action)
+        for agent, destination, action in prepared
+    )
+
+
+def uninstall_skills(
+    target: AgentSelector = "codex", *, force: bool = False, dry_run: bool = False
+) -> tuple[SkillResult, ...]:
+    agents = _resolve_agents(target)
+    prepared = [_prepare_uninstall(agent, force=force) for agent in agents]
+
+    if not dry_run:
+        for agent, destination, action in prepared:
+            if action == "not-found":
                 continue
-            if not force:
-                raise FileExistsError(
-                    f"refusing to overwrite modified skill file: {destination}; rerun with --force"
-                )
-        destination.parent.mkdir(parents=True, exist_ok=True)
-        destination.write_text(content, encoding="utf-8")
+            managed_files = _managed_paths(agent)
+            for relative in managed_files:
+                output = destination / relative
+                if output.exists():
+                    output.unlink()
+            _remove_empty_managed_directories(destination, managed_files)
+
+    return tuple(
+        SkillResult(agent=agent, path=destination, action=action)
+        for agent, destination, action in prepared
+    )
+
+
+def install_codex_skill(*, force: bool = False) -> tuple[Path, InstallAction]:
+    result = install_skills(force=force)[0]
+    return result.path, cast(InstallAction, result.action)
+
+
+def uninstall_codex_skill(*, force: bool = False) -> tuple[Path, UninstallAction]:
+    result = uninstall_skills(force=force)[0]
+    return result.path, cast(UninstallAction, result.action)
+
+
+def _resolve_agents(target: AgentSelector) -> tuple[AgentName, ...]:
+    if target == "detected":
+        agents = detect_agents()
+        if not agents:
+            choices = ", ".join(AGENT_TARGETS)
+            raise ValueError(
+                "no supported agent targets matched local signals; "
+                f"choose one explicitly with --target ({choices})"
+            )
+        return agents
+    if target not in AGENT_TARGETS:
+        raise ValueError(f"unsupported agent target: {target}")
+    return (cast(AgentName, target),)
+
+
+def _prepare_install(
+    agent: AgentName, *, force: bool
+) -> tuple[AgentName, Path, InstallAction]:
+    destination = agent_skills_root(agent) / "code-search"
+    _validate_target(agent, destination, _managed_paths(agent))
+    existed = destination.exists()
+    installed_digests = _installed_digests(destination, force=force)
+    expected_manifest = _manifest_content(agent).encode("utf-8")
+    manifest = destination / INSTALL_MANIFEST
+    changed = not manifest.exists() or manifest.read_bytes() != expected_manifest
+    source = _skill_source()
+
+    for relative in _managed_files(agent):
+        output = destination / relative
+        content = source.joinpath(relative.as_posix()).read_bytes()
+        if not output.exists():
+            changed = True
+            continue
+        digest = _content_digest(output.read_bytes())
+        if digest == _content_digest(content):
+            continue
+        trusted = installed_digests.get(relative) == digest or digest in LEGACY_FILE_DIGESTS.get(
+            relative, ()
+        )
+        if not force and not trusted:
+            raise FileExistsError(
+                f"refusing to overwrite modified skill file: {output}; rerun with --force"
+            )
         changed = True
 
     action: InstallAction = "unchanged" if not changed else ("updated" if existed else "created")
-    return target, action
+    return agent, destination, action
 
 
-def uninstall_codex_skill(*, force: bool = False) -> tuple[Path, Literal["removed", "not-found"]]:
-    target = codex_skills_root() / "code-search"
-    if not target.exists():
-        return target, "not-found"
+def _prepare_uninstall(
+    agent: AgentName, *, force: bool
+) -> tuple[AgentName, Path, UninstallAction]:
+    destination = agent_skills_root(agent) / "code-search"
+    _validate_target(agent, destination, _managed_paths(agent))
+    installed_digests = _installed_digests(destination, force=force)
+    source = _skill_source()
+    found = (destination / INSTALL_MANIFEST).exists()
 
-    source = files("code_retrieval").joinpath("resources/code-search")
-    for relative in SKILL_FILES:
-        destination = target / relative
-        if not destination.exists():
+    for relative in _managed_files(agent):
+        output = destination / relative
+        if not output.exists():
             continue
-        expected = source.joinpath(relative.as_posix()).read_text(encoding="utf-8")
-        if destination.read_text(encoding="utf-8") != expected and not force:
+        found = True
+        expected = source.joinpath(relative.as_posix()).read_bytes()
+        digest = _content_digest(output.read_bytes())
+        trusted = installed_digests.get(relative) == digest or digest in LEGACY_FILE_DIGESTS.get(
+            relative, ()
+        )
+        if digest != _content_digest(expected) and not force and not trusted:
             raise FileExistsError(
-                f"refusing to remove modified skill file: {destination}; rerun with --force"
+                f"refusing to remove modified skill file: {output}; rerun with --force"
             )
-        destination.unlink()
-
-    agents = target / "agents"
-    if agents.exists() and not any(agents.iterdir()):
-        agents.rmdir()
-    if target.exists() and not any(target.iterdir()):
-        target.rmdir()
-    return target, "removed"
+
+    return agent, destination, "removed" if found else "not-found"
+
+
+def _validate_target(
+    agent: AgentName, destination: Path, managed_files: tuple[Path, ...]
+) -> None:
+    skills_root = destination.parent
+    config_root = skills_root.parent
+    guarded_roots = (config_root, *_additional_configuration_roots(agent))
+    guarded_paths = tuple(
+        dict.fromkeys(
+            path
+            for root in guarded_roots
+            for path in _configuration_path_components(root)
+        )
+    )
+    for path in guarded_paths:
+        if path.is_symlink():
+            raise OSError(f"refusing to manage a symlinked agent configuration path: {path}")
+        if path.exists() and not path.is_dir():
+            raise NotADirectoryError(f"agent configuration path is not a directory: {path}")
+    if skills_root.is_symlink():
+        raise OSError(f"refusing to manage a symlinked skills root: {skills_root}")
+    if skills_root.exists() and not skills_root.is_dir():
+        raise NotADirectoryError(f"skills root is not a directory: {skills_root}")
+    if destination.is_symlink():
+        raise OSError(f"refusing to manage a symlinked skill directory: {destination}")
+    if destination.exists() and not destination.is_dir():
+        raise NotADirectoryError(f"skill destination is not a directory: {destination}")
+
+    for relative in managed_files:
+        current = destination
+        for index, part in enumerate(relative.parts):
+            current /= part
+            if current.is_symlink():
+                raise OSError(f"refusing to manage a symlinked skill path: {current}")
+            if index < len(relative.parts) - 1 and current.exists() and not current.is_dir():
+                raise NotADirectoryError(f"skill path parent is not a directory: {current}")
+        if current.exists() and not current.is_file():
+            raise OSError(f"skill file destination is not a regular file: {current}")
+
+
+def _remove_empty_managed_directories(destination: Path, managed_files: tuple[Path, ...]) -> None:
+    directories = {
+        destination / parent
+        for relative in managed_files
+        for parent in relative.parents
+        if parent != Path(".")
+    }
+    for directory in sorted(directories, key=lambda path: len(path.parts), reverse=True):
+        if directory.exists() and not any(directory.iterdir()):
+            directory.rmdir()
+    if destination.exists() and not any(destination.iterdir()):
+        destination.rmdir()
+
+
+def _agent_is_detected(agent: AgentName) -> bool:
+    destination = agent_skills_root(agent) / "code-search"
+    if destination.exists():
+        return True
+
+    home = _home()
+    if agent == "codex":
+        return bool(os.environ.get("CODEX_HOME")) or (home / ".codex").exists() or bool(
+            shutil.which("codex")
+        )
+    if agent == "claude-code":
+        return bool(os.environ.get("CLAUDE_CONFIG_DIR")) or (home / ".claude").exists() or bool(
+            shutil.which("claude")
+        )
+    if agent == "cursor":
+        return (home / ".cursor").exists()
+    if agent == "gemini":
+        return bool(os.environ.get("GEMINI_CLI_HOME")) or (home / ".gemini").exists() or bool(
+            shutil.which("gemini")
+        )
+    if agent == "opencode":
+        configured = bool(os.environ.get("OPENCODE_CONFIG_DIR"))
+        config_home = _xdg_config_home(home)
+        return configured or (config_home / "opencode").exists() or bool(shutil.which("opencode"))
+    if agent == "github-copilot":
+        return bool(os.environ.get("COPILOT_HOME")) or (home / ".copilot").exists() or bool(
+            shutil.which("copilot")
+        )
+    return (home / ".kiro").exists() or bool(shutil.which("kiro-cli"))
+
+
+def _managed_files(agent: AgentName) -> tuple[Path, ...]:
+    return CODEX_SKILL_FILES if agent == "codex" else PORTABLE_SKILL_FILES
+
+
+def _managed_paths(agent: AgentName) -> tuple[Path, ...]:
+    return (*_managed_files(agent), INSTALL_MANIFEST)
+
+
+def _manifest_content(agent: AgentName) -> str:
+    source = _skill_source()
+    digests = {
+        relative.as_posix(): _content_digest(
+            source.joinpath(relative.as_posix()).read_bytes()
+        )
+        for relative in _managed_files(agent)
+    }
+    return json.dumps(
+        {"schema": MANIFEST_SCHEMA, "files": digests},
+        indent=2,
+        sort_keys=True,
+    ) + "\n"
+
+
+def _installed_digests(destination: Path, *, force: bool) -> dict[Path, str]:
+    manifest = destination / INSTALL_MANIFEST
+    if not manifest.exists():
+        return {}
+    try:
+        data = json.loads(manifest.read_text(encoding="utf-8"))
+        if data.get("schema") != MANIFEST_SCHEMA or not isinstance(data.get("files"), dict):
+            raise ValueError("unsupported manifest schema")
+        digests: dict[Path, str] = {}
+        for name, digest in data["files"].items():
+            relative = Path(name)
+            if (
+                not isinstance(name, str)
+                or not isinstance(digest, str)
+                or relative.is_absolute()
+                or ".." in relative.parts
+                or len(digest) != 64
+                or any(character not in "0123456789abcdef" for character in digest)
+            ):
+                raise ValueError("invalid managed file entry")
+            digests[relative] = digest
+        return digests
+    except (AttributeError, json.JSONDecodeError, TypeError, ValueError) as error:
+        if force:
+            return {}
+        raise ValueError(
+            f"refusing to use invalid install manifest: {manifest}; rerun with --force"
+        ) from error
+
+
+def _content_digest(content: bytes) -> str:
+    try:
+        normalized = content.decode("utf-8").replace("\r\n", "\n").replace("\r", "\n")
+        canonical = normalized.encode("utf-8")
+    except UnicodeDecodeError:
+        canonical = b"\x00binary\x00" + content
+    return hashlib.sha256(canonical).hexdigest()
+
+
+def _configuration_path_components(config_root: Path) -> tuple[Path, ...]:
+    home = _home()
+    components = [config_root]
+    if config_root != home and config_root.is_relative_to(home):
+        current = config_root.parent
+        while current != home:
+            components.append(current)
+            current = current.parent
+    return tuple(components)
+
+
+def _additional_configuration_roots(agent: AgentName) -> tuple[Path, ...]:
+    if agent == "gemini" and (value := os.environ.get("GEMINI_CLI_HOME")):
+        return (_configured_path(value, "GEMINI_CLI_HOME"),)
+    if agent == "opencode" and not os.environ.get("OPENCODE_CONFIG_DIR"):
+        value = os.environ.get("XDG_CONFIG_HOME")
+        if value:
+            path = Path(value).expanduser()
+            if path.is_absolute():
+                return (path,)
+    return ()
+
+
+def _atomic_write(destination: Path, content: bytes) -> None:
+    destination.parent.mkdir(parents=True, exist_ok=True)
+    descriptor, temporary = tempfile.mkstemp(
+        dir=destination.parent,
+        prefix=f".{destination.name}.",
+    )
+    try:
+        with os.fdopen(descriptor, "wb") as output:
+            output.write(content)
+        os.replace(temporary, destination)
+    finally:
+        if os.path.exists(temporary):
+            os.unlink(temporary)
+
+
+def _skill_source():
+    return files("code_retrieval").joinpath("resources/code-search")
+
+
+def _configured_path(value: str, variable: str) -> Path:
+    path = Path(value).expanduser()
+    if not path.is_absolute():
+        raise ValueError(f"{variable} must be an absolute path: {value}")
+    return path
+
+
+def _xdg_config_home(home: Path) -> Path:
+    value = os.environ.get("XDG_CONFIG_HOME")
+    if value:
+        candidate = Path(value).expanduser()
+        if candidate.is_absolute():
+            return candidate
+    return home / ".config"
+
+
+def _home() -> Path:
+    return Path.home()

{code_search_cli-0.2.0.dist-info → code_search_cli-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-search-cli
-Version: 0.2.0
+Version: 0.3.0
 Summary: Task-aware code search with compact, auditable evidence for coding agents
 Author: Code Search contributors
 License-Expression: Apache-2.0
@@ -9,7 +9,7 @@ Project-URL: Documentation, https://code-search.quguai.cc/
 Project-URL: Repository, https://github.com/quguai/code-search
 Project-URL: Issues, https://github.com/quguai/code-search/issues
 Project-URL: Changelog, https://github.com/quguai/code-search/releases
-Keywords: code-search,code-retrieval,coding-agents,cli,codex
+Keywords: code-search,code-retrieval,coding-agents,agent-skills,cli,codex
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -39,7 +39,7 @@ Dynamic: license-file
   <a href="https://pypi.org/project/code-search-cli/"><img alt="PyPI" src="https://img.shields.io/pypi/v/code-search-cli?style=flat-square" /></a>
   <a href="https://github.com/quguai/code-search/blob/main/LICENSE"><img alt="Apache-2.0 license" src="https://img.shields.io/github/license/quguai/code-search?style=flat-square" /></a>
   <img alt="Python 3.11+" src="https://img.shields.io/badge/Python-3.11%2B-3776AB?style=flat-square&amp;logo=python&amp;logoColor=white" />
-  <img alt="Codex skill included" src="https://img.shields.io/badge/Codex-skill_included-5B47D6?style=flat-square" />
+  <img alt="Agent Skill installers for seven agents" src="https://img.shields.io/badge/Agent_Skills-7_targets-5B47D6?style=flat-square" />
   <img alt="Experimental status" src="https://img.shields.io/badge/status-experimental-D97706?style=flat-square" />
 </p>
 
@@ -91,15 +91,19 @@ index inside it. It incrementally maintains a per-user SQLite index under the op
 directory, honors Git ignore rules for working trees, and uses `code-search clean` to remove the
 cached source snapshot and derived metadata.
 
-### Optional Codex integration
+### Optional agent integration
 
 ```bash
-code-search install
+code-search install                  # Codex remains the default
+code-search install --target cursor  # Or select one target explicitly
 ```
 
-This installs the bundled `code-search` skill into Codex. Restart Codex so it can discover the
-skill. The installer is idempotent and refuses to overwrite a locally modified skill unless
-`--force` is supplied.
+The bundled `code-search` Agent Skill can be installed for Codex, Claude Code, Cursor, Gemini CLI,
+OpenCode, GitHub Copilot, or Kiro. Installation is user-level and idempotent. It tracks hashes of
+the files it installed, so an untouched older release can upgrade safely while a locally modified
+skill is still protected unless `--force` is supplied. Add `--dry-run` to preview the operation.
+The CLI remains the primary interface; installing the skill adds neither an MCP server nor a runtime
+model.
 
 ### Why there is no model underneath
 
@@ -125,7 +129,10 @@ versioned comparison methods; they are not Code Search runtime dependencies.
   default path.
 - Compact exact-symbol windows across all indexed source formats when the whole task is an
   identifier or qualified name.
-- A bundled Codex skill that teaches the agent when to retrieve, expand, or fall back to exact `rg`.
+- A bundled Agent Skill, with user-level filesystem installers for Codex, Claude Code, Cursor,
+  Gemini CLI, OpenCode, GitHub Copilot, and Kiro, that teaches the agent when to retrieve, expand,
+  or fall back to exact `rg`. Their paths, dry-run behavior, idempotence, safe upgrades, and
+  file-protection behavior have automated coverage.
 
 ## Task evidence beyond ranked matches
 
@@ -185,13 +192,52 @@ code-search expand \
   --relation enclosing
 ```
 
-Manage the Codex skill:
+Manage the optional Agent Skill:
 
 ```bash
-code-search install
-code-search uninstall
+code-search install                                  # Codex
+code-search install --target claude-code
+code-search install --target cursor
+code-search install --target gemini
+code-search install --target opencode
+code-search install --target github-copilot
+code-search install --target kiro
+code-search install --target detected                # Best-effort convenience selector
+code-search install --target detected --dry-run      # Preview without writing
+code-search uninstall --target cursor
+code-search uninstall --target detected
 ```
 
+The installer writes only managed Skill files and its hash manifest inside the selected agent's
+user configuration:
+
+| `--target` | User-level destination |
+|---|---|
+| `codex` | `$CODEX_HOME/skills/code-search/` when set; otherwise `~/.agents/skills/code-search/` |
+| `claude-code` | `$CLAUDE_CONFIG_DIR/skills/code-search/` when set; otherwise `~/.claude/skills/code-search/` |
+| `cursor` | `~/.cursor/skills/code-search/` |
+| `gemini` | `$GEMINI_CLI_HOME/.gemini/skills/code-search/` when set; otherwise `~/.gemini/skills/code-search/` |
+| `opencode` | `$OPENCODE_CONFIG_DIR/skills/code-search/` when set; otherwise `${XDG_CONFIG_HOME:-~/.config}/opencode/skills/code-search/` |
+| `github-copilot` | `$COPILOT_HOME/skills/code-search/` when set; otherwise `~/.copilot/skills/code-search/` |
+| `kiro` | `~/.kiro/skills/code-search/` |
+
+Agent-specific environment overrides must be absolute paths; a relative `XDG_CONFIG_HOME` is ignored
+as required by the XDG base-directory specification. An existing legacy Codex installation under
+`~/.codex/skills/code-search/` is updated and removed in place instead of being silently migrated.
+
+`detected` is a best-effort convenience selector based on known commands, configuration directories,
+environment overrides, and an already-installed target. It does not launch a client or verify that
+the client can load the skill. Cursor detection deliberately relies on `~/.cursor` rather than the
+ambiguous `agent` executable name. Because some clients also scan another client's compatibility
+directories, prefer an explicit target and use one if the same skill appears more than once.
+
+Every selected destination is preflighted before writing or removing files. A small hidden manifest
+records hashes of the managed files; it is installer metadata, not another instruction loaded by the
+agent. This lets an untouched older installation upgrade without treating it as a user edit.
+Uninstall removes only managed files whose content is still recognized and leaves extra user files
+in place. Use `--force` only when you intentionally want to replace or remove a modified managed
+file. `--dry-run` performs the same checks and reports the planned action without changing files.
+
 Prewarm, inspect, or remove the per-repository index:
 
 ```bash
@@ -211,7 +257,7 @@ The repository publishes two recorded development comparisons. Both measure
 scores must not be merged into one leaderboard. The shared Java runner reproduces all six methods;
 the multilingual public runner currently reproduces BM25, Probe, and ripgrep, while the other three
 rows retain their recorded implementation identities and per-task output. The Code Search rows
-describe the source revisions recorded by each benchmark, not a new measurement of version 0.2.0.
+describe the source revisions recorded by each benchmark, not a new measurement of the current release.
 
 ### Shared Java comparison
 
@@ -329,7 +375,8 @@ validation remain future work.
   executable patch tests and repeated model runs.
 - **P1, retrieval quality:** close the long-query ranking gaps surfaced by the multilingual
   diagnostic, and add stronger AST/symbol parsers.
-- **P1, onboarding breadth:** add safe CLI/skill installers for more coding agents. Consider MCP only
+- **P1, onboarding validation:** expand beyond the seven current user-level Agent Skill destinations
+  only when another integration has a real discovery path and automated coverage. Consider MCP only
   if a resident index or structured tool discovery provides a measured benefit over CLI invocation.
 - **P2, distribution:** ship signed standalone binaries.
 
@@ -338,7 +385,7 @@ validation remain future work.
 This is a testable experimental MVP, not a production release. The public development benchmark
 measures retrieval, while the deterministic fixtures and tests cover output behavior and package
 quality. None of them proves held-out retrieval superiority or executable patch success. The
-implementation and bundled Codex skill are independently designed around the task-evidence workflow.
+implementation and bundled Agent Skill are independently designed around the task-evidence workflow.
 
 ## License
 

{code_search_cli-0.2.0.dist-info → code_search_cli-0.3.0.dist-info}/RECORD

@@ -1,19 +1,19 @@
 code_retrieval/__init__.py,sha256=zNqqZe91zhRnR4onrqkRk9iW7xxG60wiZeQmTgZ8awQ,220
 code_retrieval/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
-code_retrieval/cli.py,sha256=ACdzH_bfq-ZAYIm5hAw-FgjxmjrgDLScJaxRea4PF8g,6909
+code_retrieval/cli.py,sha256=-ziVT56Uyxv_0pL8rvEgxvLxiBXVqSkFCufuYVt3ovE,8358
 code_retrieval/engine.py,sha256=40K728-ktbCNkLrGYTW1SsYIVIcSSzwS-ZMtk3osM08,42442
 code_retrieval/index_store.py,sha256=WMZlghrQA9wPiIpp7QkQ_wlLCaFbNhSqCdFUQiUvgLY,11580
-code_retrieval/installer.py,sha256=l4wdDk3jSe2EQT4vGZhZvY8oCIEJofprUyoy6XIOi9s,2415
+code_retrieval/installer.py,sha256=FGaKpMfV-N8sG5FNn2vN8_96GuOwC2indA278BldEKM,16820
 code_retrieval/models.py,sha256=MXziQGHlgPLgzbwSWNvpmstW5oLga27D0fPZwwbKNKY,2736
 code_retrieval/query.py,sha256=RrAYC-DuH78PEosjrt_rsEwqQwI4AGhTEZkV6dGaGys,3837
 code_retrieval/repository.py,sha256=RbCN6XzampK9880mQbSoNkbVplY0qln1jNw5JpoD_v8,7806
 code_retrieval/structure.py,sha256=pJ6ZFXXWqhGiw5rio8RY28NQ3GJiIVzSzdNKlyAsybE,7471
 code_retrieval/resources/code-search/SKILL.md,sha256=mOv8zHkPUJDDjdznLHwo7t4KoBIlwtBta3wVADPWblo,2300
 code_retrieval/resources/code-search/agents/openai.yaml,sha256=Qz6AxMi9Wg0ZxqO-xwsv2En-SDQ6LBQ4twi8pp_0vBs,212
-code_search_cli-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
-code_search_cli-0.2.0.dist-info/licenses/NOTICE,sha256=fORXMPhszVyKxagqcQGdbMdYt3irmab8QyyPnPOpk4c,117
-code_search_cli-0.2.0.dist-info/METADATA,sha256=JUIaWZlBNO_E-gmV3IrnDGWT2YCu905QlFaM85-2e1U,18655
-code_search_cli-0.2.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
-code_search_cli-0.2.0.dist-info/entry_points.txt,sha256=Y4u1GuLbinsDr-jdhyQZF9XFEdnsco_byL8NTrDYp7w,56
-code_search_cli-0.2.0.dist-info/top_level.txt,sha256=G2fxsJkpCt-QxmOlHVKR-XtsH9IZnM1lAhfurXOqsDw,15
-code_search_cli-0.2.0.dist-info/RECORD,,
+code_search_cli-0.3.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+code_search_cli-0.3.0.dist-info/licenses/NOTICE,sha256=fORXMPhszVyKxagqcQGdbMdYt3irmab8QyyPnPOpk4c,117
+code_search_cli-0.3.0.dist-info/METADATA,sha256=Jkq3svJC2bP2lYQJ0FBbX18ZKmEo6q8oQJe4c6902d8,22155
+code_search_cli-0.3.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+code_search_cli-0.3.0.dist-info/entry_points.txt,sha256=Y4u1GuLbinsDr-jdhyQZF9XFEdnsco_byL8NTrDYp7w,56
+code_search_cli-0.3.0.dist-info/top_level.txt,sha256=G2fxsJkpCt-QxmOlHVKR-XtsH9IZnM1lAhfurXOqsDw,15
+code_search_cli-0.3.0.dist-info/RECORD,,