@softspark/ai-toolkit 4.11.0 → 4.13.0

package/scripts/generate_antigravity.py

@@ -99,6 +99,21 @@ def _write_skill_pointer(target_dir: Path) -> None:
 # Main
 # ---------------------------------------------------------------------------
 
+def generate_global(target_dir: Path) -> None:
+    """Write the skill pointer to Antigravity's documented HOME-scoped skill
+    dirs. ``~/.gemini/config/skills/`` is shared across all Antigravity products
+    (IDE, editor, CLI); ``~/.gemini/antigravity-cli/skills/`` is CLI-private.
+    Antigravity RULES have no documented global file surface, so only the skill
+    pointer is emitted globally (rules stay project-local).
+    """
+    content = _pointer_skill_md()
+    for rel in (".gemini/config/skills", ".gemini/antigravity-cli/skills"):
+        skill_dir = target_dir / rel / POINTER_SKILL_NAME
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+        print(f"  Generated: {rel}/{POINTER_SKILL_NAME}/SKILL.md")
+
+
 def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
              rules_dir: Path | None = None,

package/scripts/generate_codex_hooks.py

@@ -8,11 +8,14 @@ Codex exposes 10 lifecycle events (PascalCase in config.toml / hooks.json):
 ``PreToolUse``, ``PostToolUse``, ``PermissionRequest``, ``PreCompact``,
 ``PostCompact``, ``SessionStart``, ``UserPromptSubmit``, ``SubagentStart``,
 ``SubagentStop``, ``Stop``. PreToolUse/PostToolUse only support the ``Bash``
-matcher. We wire all 10 events in ``CODEX_HOOKS`` below to the shared toolkit
-hook scripts, mirroring the Claude Code mapping in ``app/hooks.json``.
-
-Handler types in Codex: ``command`` (what we emit), ``prompt``, and ``agent``.
-Reference: codex-rs/config/src/hook_config.rs.
+matcher. We wire 9 of the 10 events in ``CODEX_HOOKS`` below to the shared
+toolkit hook scripts, mirroring the Claude Code mapping in ``app/hooks.json``.
+``PostCompact`` is intentionally unwired (its only hook was the removed
+environment-snapshot probe).
+
+Handler types in Codex: ``command`` (what we emit). ``prompt`` and ``agent``
+are parsed by Codex but not yet executed, so hand-authored handlers of those
+types are inert. Reference: codex-rs/config/src/hook_config.rs.
 
 Usage:
   python3 scripts/generate_codex_hooks.py [target-dir]

package/scripts/generate_copilot.py

@@ -228,17 +228,24 @@ def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
              rules_dir: Path | None = None,
              emit_prompts: bool = True,
-             emit_instructions: bool = True) -> None:
+             emit_instructions: bool = True,
+             config_root: Path | None = None) -> None:
     """Write Copilot path-specific instructions and prompt files.
 
+    By default writes to ``<target_dir>/.github/`` (project-local). Pass
+    ``config_root=~/.copilot`` for the Copilot CLI user-level global layout,
+    where instructions land in ``~/.copilot/instructions/*.instructions.md``.
+
     ``.github/copilot-instructions.md`` is intentionally not written here —
     the legacy ``main()`` entry point still emits it to stdout so existing
     scripts (including ``ai-toolkit install``) keep working unchanged.
     """
     github_dir = target_dir / ".github"
+    instr_root = config_root if config_root is not None else github_dir
+    instr_label = "~/.copilot/instructions" if config_root is not None else ".github/instructions"
 
     if emit_instructions:
-        instr_dir = github_dir / "instructions"
+        instr_dir = instr_root / "instructions"
         instr_dir.mkdir(parents=True, exist_ok=True)
 
         instruction_files: dict[str, callable] = dict(_make_instruction_files())
@@ -269,7 +276,7 @@ def generate(target_dir: Path, *,
 
         for name, content_fn in instruction_files.items():
             (instr_dir / name).write_text(content_fn(), encoding="utf-8")
-            print(f"  Generated: .github/instructions/{name}")
+            print(f"  Generated: {instr_label}/{name}")
 
     if emit_prompts:
         prompt_dir = github_dir / "prompts"

package/scripts/generate_devin_hooks.py

@@ -3,10 +3,9 @@
 
 Devin CLI uses a hook format **compatible with Claude Code hooks**
 (docs.devin.ai/cli/extensibility/hooks/overview). This generator is the
-replacement for the deprecated Cascade ``.windsurf/hooks.json`` surface,
-which stops working when Cascade sunsets on 2026-07-01. Devin Local / Devin
-CLI do NOT read ``.windsurf/hooks.json`` as a fallback, so the hooks must be
-regenerated onto this new file.
+replacement for the removed Cascade ``.windsurf/hooks.json`` surface, which
+stopped working on 2026-07-01. Devin Local and the standalone Devin CLI do not
+read that legacy file as a fallback, so hooks are emitted here.
 
 Output file: ``<target>/.devin/hooks.v1.json``. Per the Devin docs the
 standalone ``hooks.v1.json`` file's entire contents ARE the hooks object —

package/scripts/generate_windsurf_skills.py

@@ -1,10 +1,9 @@
 #!/usr/bin/env python3
-"""Generate a Devin Desktop (formerly Windsurf) skill pointer.
+"""Generate a Devin/Windsurf skill pointer.
 
-Dual-emits under ``.devin/skills/`` (primary since the 2026-06-02 rebrand)
-and ``.windsurf/skills/`` (legacy fallback). Pass an explicit ``skill_root``
-to emit a single location instead (used for the ``~/.codeium/windsurf/``
-global install path).
+Current Devin docs list ``.windsurf/skills/`` as a supported cross-tool skill
+path and do not list ``.devin/skills/``. Pass an explicit ``skill_root`` for a
+single alternate location (used by the legacy HOME-scoped Windsurf install).
 """
 from __future__ import annotations
 
@@ -14,7 +13,7 @@ from pathlib import Path
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from skill_pointer import POINTER_SKILL_NAME, write_pointer_skill
 
-DEFAULT_SKILL_ROOTS: tuple[str, ...] = (".devin/skills", ".windsurf/skills")
+DEFAULT_SKILL_ROOTS: tuple[str, ...] = (".windsurf/skills",)
 
 
 def generate(target_dir: Path, *, emit_skill_pointer: bool = True,

package/scripts/inject_hook_cli.py

@@ -49,8 +49,22 @@ sys.path.insert(0, str(Path(__file__).resolve().parent))
 # Protected source tag -- this CLI must never touch ai-toolkit's own entries.
 PROTECTED_SOURCE = "ai-toolkit"
 
-# Codex CLI supports only these 5 hook events.
-CODEX_EVENTS = {"SessionStart", "PreToolUse", "PostToolUse", "UserPromptSubmit", "Stop"}
+# Codex CLI's HookEventName enum defines 10 events; we propagate the 9 that
+# generate_codex_hooks.py also wires (all except PostCompact, whose only hook
+# was the removed environment-snapshot probe). Keeping this in sync with the
+# generator prevents injected custom hooks from silently losing events Codex
+# supports.
+CODEX_EVENTS = {
+    "SessionStart",
+    "PreToolUse",
+    "PostToolUse",
+    "PermissionRequest",
+    "UserPromptSubmit",
+    "SubagentStart",
+    "SubagentStop",
+    "PreCompact",
+    "Stop",
+}
 
 
 # ---------------------------------------------------------------------------

package/scripts/install.py

@@ -18,7 +18,7 @@ Other tools (global config locations):
   - Roo Code: ~/.roo/rules/
   - Aider:    ~/.aider.conf.yml (created only if absent)
   - Augment:  ~/.augment/rules/ai-toolkit.md
-  - Codex:    ~/AGENTS.md, ~/.agents/, ~/.codex/hooks.json
+  - Codex:    ~/.codex/AGENTS.md, ~/.agents/skills/, ~/.codex/hooks.json
   - opencode: ~/.config/opencode/
 
 Registered rules (~/.softspark/ai-toolkit/rules/*.md) are also synced into
@@ -750,40 +750,42 @@ def main() -> None:
             global_eds = get_global_editors() or None
 
         installed_eds = install_ai_tools(target_dir, rules_dir, dry_run,
-                                         editors=global_eds)
+                                         editors=global_eds, profile=profile)
         install_persona(target_dir, persona, dry_run)
         install_strict_git_hooks(profile, local, dry_run)
 
     # Record install state (skip for dry-run)
     if not dry_run:
-        auto_detected = None
-        if auto_detect:
-            auto_detected = detect_languages(project_dir, toolkit_dir)
-
-        # Determine what modules to record
-        if resolved_modules is not None:
-            record_modules = resolved_modules
-        else:
-            # Legacy mode: infer modules from profile/only
-            record_modules = _infer_modules_from_legacy(profile, only)
-
         # Extract extends metadata if available
         extends_info = None
         merged = cfg.get("_merged_config")
         if merged and merged.get("_extends_meta"):
             extends_info = merged["_extends_meta"]
 
-        record_install(
-            version=_get_toolkit_version(),
-            modules=record_modules,
-            profile=profile or "standard",
-            auto_detected=auto_detected,
-            extends_info=extends_info,
-        )
+        # state.json describes the global install and drives future `update`
+        # invocations. Project-local installs belong in projects.json and must
+        # never replace the global profile/modules with the last project's
+        # auto-detected language set.
+        if not local:
+            auto_detected = None
+            if auto_detect:
+                auto_detected = detect_languages(project_dir, toolkit_dir)
+
+            if resolved_modules is not None:
+                record_modules = resolved_modules
+            else:
+                record_modules = _infer_modules_from_legacy(profile, only)
+
+            record_install(
+                version=_get_toolkit_version(),
+                modules=record_modules,
+                profile=profile or "standard",
+                auto_detected=auto_detected,
+                extends_info=extends_info,
+            )
 
-        # Record global editors (only for global install, not --local)
-        if not local and installed_eds:
-            record_global_editors(installed_eds)
+            if installed_eds:
+                record_global_editors(installed_eds)
 
         # Register project in global registry (for `ai-toolkit update` propagation)
         # Skipped when called from update_projects.py (--skip-register) to avoid

package/scripts/install_steps/ai_tools.py

@@ -20,12 +20,16 @@ from injection import (
 
 def install_ai_tools(target_dir: Path, rules_dir: Path,
                      dry_run: bool,
-                     editors: list[str] | None = None) -> list[str]:
+                     editors: list[str] | None = None,
+                     profile: str = "standard") -> list[str]:
     """Install global editor configs.
 
     Args:
         editors: Explicit list of editors to install globally. If None,
                  uses DEFAULT_GLOBAL_EDITORS (empty = Claude only).
+        profile: Install profile. Gates each editor's optional native surfaces
+                 the same way the local install does — hooks at
+                 standard/strict/full, sub-agents/commands/skills at full.
 
     Returns:
         List of editors that were actually installed (for state tracking).
@@ -43,6 +47,10 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
     if not eds:
         return []
 
+    _profile = profile if profile in {"minimal", "standard", "strict", "full"} else "standard"
+    add_hooks = _profile in {"standard", "strict", "full"}
+    add_native_surfaces = _profile == "full"
+
     print()
     print("## Other AI Tools (global)")
     print()
@@ -57,6 +65,7 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
         if dry_run:
             print("  Would inject: ~/.codeium/windsurf/memories/global_rules.md")
             print("  Would generate: ~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md")
+            print("  Would inject: ~/.config/devin/AGENTS.md (Devin CLI global rules)")
         else:
             _install_windsurf_global(target_dir, rules_dir)
         installed.append("windsurf")
@@ -65,22 +74,46 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
         gemini_file = target_dir / ".gemini" / "GEMINI.md"
         if dry_run:
             print("  Would inject: ~/.gemini/GEMINI.md")
+            if add_hooks:
+                print("  Would generate: ~/.gemini/settings.json (hooks)")
+            if add_native_surfaces:
+                print("  Would generate: ~/.gemini/commands/, ~/.gemini/skills/")
         else:
             inject_with_rules("generate-gemini.sh", gemini_file, rules_dir)
+            # Hooks (~/.gemini/settings.json), commands (~/.gemini/commands/),
+            # and the skills pointer (~/.gemini/skills/) are documented user-tier
+            # surfaces — install them globally, gated like the local install.
+            if add_hooks:
+                _try_generator("generate_gemini_hooks", target_dir)
+            if add_native_surfaces:
+                _try_generator("generate_gemini_commands", target_dir)
+                _try_generator("generate_gemini_skills", target_dir)
         installed.append("gemini")
 
     if "augment" in eds:
         augment_file = target_dir / ".augment" / "rules" / "ai-toolkit.md"
         if dry_run:
             print("  Would inject: ~/.augment/rules/ai-toolkit.md")
+            if add_native_surfaces:
+                print("  Would generate: ~/.augment/agents/, ~/.augment/commands/, ~/.augment/settings.json (hooks)")
         else:
             inject_with_rules("generate-augment.sh", augment_file, rules_dir)
+            # Sub-agents, commands, and hooks all have documented user-tier
+            # surfaces under ~/.augment — a global-only Augment user otherwise
+            # gets no hooks/agents/commands. Gate them like the local install.
+            if add_native_surfaces:
+                _try_generator("generate_augment_agents", target_dir)
+                _try_generator("generate_augment_commands", target_dir)
+                _try_generator("generate_augment_hooks", target_dir)
         installed.append("augment")
 
     if "cline" in eds:
         if dry_run:
             print("  Would generate: ~/Documents/Cline/Rules/ai-toolkit-*.md")
-            print("  Would generate: ~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md")
+            if _claude_skills_discoverable(target_dir):
+                print("  Would reuse: ~/.claude/skills/ (Cline-compatible discovery)")
+            else:
+                print("  Would generate: ~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md")
         else:
             _install_cline_global(target_dir, rules_dir)
         installed.append("cline")
@@ -88,8 +121,15 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
     if "roo" in eds:
         if dry_run:
             print("  Would generate: ~/.roo/rules/ai-toolkit-*.md")
+            if "codex" not in eds:
+                print("  Would generate: ~/.agents/skills/* (Roo native skill discovery)")
         else:
             _install_roo_global(target_dir, rules_dir)
+            # Roo/Zoo Code natively discover skills from ~/.agents/skills. Reuse
+            # the shared installer, but skip when codex is also selected — its
+            # branch populates the same directory — to avoid a duplicate pass.
+            if "codex" not in eds:
+                _install_codex_skills(target_dir)
         installed.append("roo")
 
     if "aider" in eds:
@@ -101,7 +141,7 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
 
     if "codex" in eds:
         if dry_run:
-            print("  Would inject: ~/AGENTS.md, ~/.agents/, ~/.codex/hooks.json")
+            print("  Would inject: ~/.codex/AGENTS.md, ~/.agents/skills/, ~/.codex/hooks.json")
         else:
             _install_codex_global(target_dir, rules_dir)
         installed.append("codex")
@@ -114,28 +154,85 @@ def install_ai_tools(target_dir: Path, rules_dir: Path,
             _install_opencode_global(target_dir, rules_dir)
         installed.append("opencode")
 
+    if "cursor" in eds:
+        # Cursor RULES have no mergeable global file surface (Settings UI only),
+        # but ~/.cursor/hooks.json is a documented user-level hooks scope — so a
+        # global Cursor install activates the safety/quality hooks everywhere.
+        if dry_run:
+            if add_hooks:
+                print("  Would generate: ~/.cursor/hooks.json (global hooks)")
+        elif add_hooks:
+            _try_generator("generate_cursor_hooks", target_dir)
+        installed.append("cursor")
+
+    if "copilot" in eds:
+        # Copilot CLI reads user-level instructions from ~/.copilot/. RULES have
+        # a documented global surface here even though .github/ stays repo-only.
+        copilot_root = target_dir / ".copilot"
+        if dry_run:
+            print("  Would inject: ~/.copilot/copilot-instructions.md")
+            print("  Would generate: ~/.copilot/instructions/ai-toolkit-*.instructions.md")
+        else:
+            inject_with_rules(
+                "generate_copilot.py",
+                copilot_root / "copilot-instructions.md",
+                rules_dir,
+            )
+            _try_generator("generate_copilot", target_dir,
+                           rules_dir=rules_dir, config_root=copilot_root,
+                           emit_prompts=False)
+        installed.append("copilot")
+
+    if "antigravity" in eds:
+        # Antigravity RULES stay project-local, but the skill pointer has a
+        # documented global surface: ~/.gemini/config/skills (all Antigravity
+        # products) and ~/.gemini/antigravity-cli/skills (CLI-private).
+        if dry_run:
+            print("  Would generate: ~/.gemini/config/skills/, ~/.gemini/antigravity-cli/skills/ (skill pointer)")
+        else:
+            from generate_antigravity import generate_global as gen_antigravity_global
+            gen_antigravity_global(target_dir)
+        installed.append("antigravity")
+
     print()
     print(f"  Available: {', '.join(GLOBAL_CAPABLE_EDITORS)}")
-    print("  Note: Cursor, Copilot, and Antigravity rule installs are project-local; use 'ai-toolkit install --local' for those.")
+    print("  Note: Cursor and Antigravity RULES stay project-local (no mergeable "
+          "global file surface); their global installs cover hooks/skills only. "
+          "Use 'ai-toolkit install --local' for full per-project setup.")
 
     return installed
 
 
 def _install_codex_global(target_dir: Path, rules_dir: Path) -> None:
-    """Install Codex at the global level (~/ layer).
+    """Install Codex at the global level (~/.codex layer).
 
     Creates:
-      - ~/AGENTS.md (marker injection; universal coding rules inlined here —
-        Codex reads instructions only from AGENTS.md, not .agents/rules/)
-      - ~/.agents/skills/* (skill symlinks)
+      - ~/.codex/AGENTS.md (marker injection; universal coding rules inlined
+        here). Codex reads GLOBAL instructions from ``$CODEX_HOME/AGENTS.md``
+        (default ~/.codex/AGENTS.md), NOT ~/AGENTS.md — a home-root AGENTS.md
+        is only loaded in the degenerate case where a session's cwd is $HOME.
+      - ~/.agents/skills/* (skill symlinks; a documented Codex skill dir)
       - ~/.codex/hooks.json (lifecycle hooks)
     """
     inject_with_rules(
         "generate_codex.py",
-        target_dir / "AGENTS.md",
+        target_dir / ".codex" / "AGENTS.md",
         rules_dir,
     )
 
+    # Migration: earlier versions wrote global instructions to ~/AGENTS.md,
+    # which Codex never loads as global instructions. Strip that stale toolkit
+    # section so upgraders are not left with dead, unread content.
+    if _strip_toolkit_sections(target_dir / "AGENTS.md"):
+        print("  Migrated: removed stale ai-toolkit section from ~/AGENTS.md")
+
+    override = target_dir / ".codex" / "AGENTS.override.md"
+    if override.is_file() and override.read_text(encoding="utf-8").strip():
+        print(
+            "  Warning: ~/.codex/AGENTS.override.md exists and takes precedence "
+            "over ~/.codex/AGENTS.md — toolkit rules will be masked."
+        )
+
     from generate_codex_hooks import generate as gen_codex_hooks
     gen_codex_hooks(target_dir)
     print("  Created: ~/.codex/hooks.json")
@@ -166,6 +263,13 @@ def _install_windsurf_global(target_dir: Path, rules_dir: Path) -> None:
     windsurf_file = target_dir / ".codeium" / "windsurf" / "memories" / "global_rules.md"
     inject_with_rules("generate-windsurf.sh", windsurf_file, rules_dir)
 
+    # Devin CLI reads global rules from ~/.config/devin/AGENTS.md, NOT the
+    # Desktop ~/.codeium/windsurf/memories/global_rules.md (that path is absent
+    # from read_config_from.windsurf). Cover editor-only Devin CLI installs
+    # where no global Claude install (~/.claude/CLAUDE.md compat read) exists.
+    devin_agents = target_dir / ".config" / "devin" / "AGENTS.md"
+    inject_with_rules("generate-windsurf.sh", devin_agents, rules_dir)
+
     from generate_windsurf_skills import generate as gen_windsurf_skills
     # Windsurf is excluded from the .claude/skills conditional: its native scan
     # of .claude/skills is gated behind a Devin "Claude Code config reading"
@@ -176,6 +280,80 @@ def _install_windsurf_global(target_dir: Path, rules_dir: Path) -> None:
     )
 
 
+def _cleanup_retired_windsurf_surfaces(cwd: Path) -> None:
+    """Remove only ai-toolkit content from retired/undocumented Devin paths."""
+    import json
+
+    legacy_hooks = cwd / ".windsurf" / "hooks.json"
+    if legacy_hooks.is_file():
+        try:
+            document = json.loads(legacy_hooks.read_text(encoding="utf-8"))
+        except (OSError, json.JSONDecodeError):
+            print("  Warning: kept invalid .windsurf/hooks.json for manual review")
+        else:
+            hooks = document.get("hooks") if isinstance(document, dict) else None
+            changed = False
+            if isinstance(hooks, dict):
+                kept_hooks: dict = {}
+                for event, entries in hooks.items():
+                    if not isinstance(entries, list):
+                        kept_hooks[event] = entries
+                        continue
+                    survivors = [
+                        entry
+                        for entry in entries
+                        if not (
+                            isinstance(entry, dict)
+                            and (
+                                entry.get("_source") == "ai-toolkit"
+                                or any(
+                                    isinstance(handler, dict)
+                                    and handler.get("_source") == "ai-toolkit"
+                                    for handler in entry.get("hooks", [])
+                                )
+                            )
+                        )
+                    ]
+                    if len(survivors) != len(entries):
+                        changed = True
+                    if survivors:
+                        kept_hooks[event] = survivors
+                if changed:
+                    if kept_hooks:
+                        document["hooks"] = kept_hooks
+                    else:
+                        document.pop("hooks", None)
+                    if document:
+                        legacy_hooks.write_text(
+                            json.dumps(
+                                document,
+                                indent=4,
+                                ensure_ascii=False,
+                                sort_keys=True,
+                            ) + "\n",
+                            encoding="utf-8",
+                        )
+                    else:
+                        legacy_hooks.unlink()
+                    print("  Migrated: removed retired ai-toolkit Cascade hooks")
+
+    retired_pointer = (
+        cwd / ".devin" / "skills" / "ai-toolkit-skill-catalogue"
+    )
+    skill_file = retired_pointer / "SKILL.md"
+    if skill_file.is_file() and "name: ai-toolkit-skill-catalogue" in (
+        skill_file.read_text(encoding="utf-8")
+    ):
+        if retired_pointer.is_symlink():
+            retired_pointer.unlink()
+        else:
+            shutil.rmtree(retired_pointer)
+        for parent in (retired_pointer.parent, retired_pointer.parent.parent):
+            if parent.is_dir() and not any(parent.iterdir()):
+                parent.rmdir()
+        print("  Migrated: removed undocumented .devin/skills toolkit pointer")
+
+
 def _install_cline_global(target_dir: Path, rules_dir: Path) -> None:
     """Install Cline global rules in the documented ~/.cline directory."""
     from generate_cline_rules import generate as gen_cline_rules
@@ -352,6 +530,35 @@ def inject_with_rules(
     print(f"  Updated: {target_file}")
 
 
+def _strip_toolkit_sections(target_file: Path) -> bool:
+    """Remove ai-toolkit ``<!-- TOOLKIT:* -->`` marker sections from an existing
+    file, preserving any non-toolkit content. Returns True if the file changed.
+
+    Used to clean a stale ~/AGENTS.md after Codex global instructions moved to
+    ~/.codex/AGENTS.md. If stripping leaves the file empty (it only ever held
+    toolkit content), the file is removed.
+    """
+    if not target_file.is_file():
+        return False
+    import re
+
+    original = target_file.read_text(encoding="utf-8")
+    stripped = re.sub(
+        r"<!-- TOOLKIT:[^ ]+ START -->.*?<!-- TOOLKIT:[^ ]+ END -->\n?",
+        "",
+        original,
+        flags=re.DOTALL,
+    )
+    if stripped == original:
+        return False
+    stripped = stripped.lstrip("\n")
+    if stripped.strip():
+        target_file.write_text(stripped, encoding="utf-8")
+    else:
+        target_file.unlink()
+    return True
+
+
 def _inject_text_section(target_file: Path, section: str, text: str) -> None:
     """Inject generated text into one marker section without touching others."""
     target_file.parent.mkdir(parents=True, exist_ok=True)
@@ -811,6 +1018,18 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         if ed in eds:
             print(msg)
 
+    if "windsurf" in eds:
+        if (Path.cwd() / ".windsurf" / "hooks.json").is_file():
+            print("  Would migrate: remove retired ai-toolkit Cascade hooks")
+        if (
+            Path.cwd()
+            / ".devin"
+            / "skills"
+            / "ai-toolkit-skill-catalogue"
+            / "SKILL.md"
+        ).is_file():
+            print("  Would migrate: remove undocumented .devin/skills toolkit pointer")
+
     # Profile-driven extras (matrix in kb/reference/global-install-model.md)
     if "copilot" in eds and add_copilot_dir:
         print("  Would generate: .github/instructions/ + .github/prompts/ (profile >= standard)")
@@ -820,7 +1039,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         if "cursor" in eds:
             print("  Would generate: .cursor/hooks.json + .cursor/agents/ + .cursor/skills/ (profile=full)")
         if "windsurf" in eds:
-            print("  Would generate: .devin/hooks.v1.json + .windsurf/hooks.json (Cascade, deprecated) + .devin/skills/ + .windsurf/skills/ (profile=full)")
+            print("  Would generate: .devin/hooks.v1.json + .windsurf/skills/ (profile=full)")
         if "cline" in eds:
             print("  Would generate: .cline/skills/ (profile=full)")
         if "augment" in eds:
@@ -1044,6 +1263,7 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
             _try_generator("generate_cursor_skills", cwd, emit_skill_pointer=emit_pointer)
 
     if "windsurf" in eds:
+        _cleanup_retired_windsurf_surfaces(cwd)
         inject_with_rules(
             "generate-windsurf.sh",
             cwd / ".windsurfrules",
@@ -1053,11 +1273,11 @@ def _create_local_ai_tool_configs(cwd: Path, rules_dir: Path,
         gen_windsurf_rules(cwd, language_modules=language_modules,
                            rules_dir=rules_dir)
         if add_native_surfaces:
-            # .windsurf/hooks.json is Cascade-scoped and dies 2026-07-01;
-            # .devin/hooks.v1.json is the Devin CLI replacement (Claude format).
-            _try_generator("generate_windsurf_hooks", cwd)
+            # Cascade's .windsurf/hooks.json surface ended on 2026-07-01.
+            # Devin CLI uses the Claude-compatible .devin/hooks.v1.json format.
             _try_generator("generate_devin_hooks", cwd)
-            # Windsurf pointer stays unconditional (its .claude scan is gated).
+            # Current Devin docs list .windsurf/skills as a supported path;
+            # .devin/skills is not documented.
             _try_generator("generate_windsurf_skills", cwd)
 
     if "cline" in eds:

package/scripts/install_steps/install_state.py

@@ -131,13 +131,20 @@ DEFAULT_GLOBAL_EDITORS: list[str] = []
 
 # All editors that support global install (opt-in via --editors).
 #
-# Cursor intentionally stays out of this list: its documented global rules
-# surface is the Settings UI, not a stable file path we can merge safely.
+# Scope varies by editor's documented global file surfaces:
+#   - cursor: HOOKS only (~/.cursor/hooks.json). Cursor RULES stay project-local
+#     — their only global surface is the Settings UI, not a mergeable file.
+#   - copilot: user-level instructions (~/.copilot/, read by Copilot CLI).
+#   - antigravity: global skill pointer (~/.gemini/config/skills,
+#     ~/.gemini/antigravity-cli/skills). Rules stay project-local.
 GLOBAL_CAPABLE_EDITORS = [
     "aider",
+    "antigravity",
     "augment",
     "cline",
     "codex",
+    "copilot",
+    "cursor",
     "gemini",
     "opencode",
     "roo",
@@ -190,6 +197,8 @@ def record_install(
     state["profile"] = profile
     if auto_detected is not None:
         state["auto_detected_languages"] = sorted(auto_detected)
+    else:
+        state.pop("auto_detected_languages", None)
 
     if extends_info is not None:
         state["extends"] = {