@softspark/ai-toolkit 4.10.1 → 4.12.0

package/scripts/ecosystem_tools.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-06-23",
+  "last_updated": "2026-06-30",
   "tools": [
     {
       "id": "claude-code",
@@ -226,7 +226,10 @@
         ".gemini/extensions/gemini-extension.json"
       ],
       "our_generators": [
-        "scripts/generate_gemini.py"
+        "scripts/generate_gemini.py",
+        "scripts/generate_gemini_hooks.py",
+        "scripts/generate_gemini_commands.py",
+        "scripts/generate_gemini_skills.py"
       ],
       "capability_markers": [
         "GEMINI.md",
@@ -310,18 +313,23 @@
       "kind": "editor",
       "urls": {
         "docs": "https://roocodeinc.github.io/Roo-Code",
-        "release_notes": "https://github.com/RooCodeInc/Roo-Code/releases",
+        "release_notes": "https://github.com/Zoo-Code-Org/Zoo-Code/releases",
         "changelog": null
       },
-      "status": "archived",
-      "status_note": "Upstream RooCodeInc/Roo-Code repo archived/read-only as of 2026-05-15, frozen at v3.54.0; docs.roocode.com 301-redirects to roocodeinc.github.io/Roo-Code. A community fork reportedly continues maintenance. JSON .roomodes is NOT deprecated; both generators remain valid.",
+      "status": "succeeded-by-fork",
+      "status_note": "Upstream RooCodeInc/Roo-Code archived/read-only 2026-05-15, frozen at v3.54.0; its releases feed is dead. Successor project by former Roo contributors: Zoo-Code-Org/Zoo-Code (marketplace ZooCodeOrganization.zoo-code, docs.zoocode.dev), active through v3.64.0 (2026-06-26) continuing Roo's version line. Config compat is total: same .roomodes (JSON 'still fully supported and won't be deprecated'), .roo/rules/, .roo/rules-{slug}/, .roo/skills/, .roo/commands/, ~/.roo/* paths — both generators remain valid. Watch Zoo GitHub releases as the authoritative feed (docs.zoocode.dev/update-notes is stale at v3.50.0). Skills (~/.roo/skills, ~/.agents/skills) shipped in v3.46.0/v3.47.2; ai-toolkit now installs them globally via ~/.agents/skills. Roo team pivoted to roomote.dev and recommended Cline.",
       "config_paths": [
         ".roomodes",
         ".roo/rules/*.md",
         ".roo/rules-{slug}/*.md",
+        ".roo/skills/*/SKILL.md",
+        "~/.roo/skills/*/SKILL.md",
+        ".agents/skills/*/SKILL.md",
+        "~/.agents/skills/*",
+        ".roo/commands/*.md",
+        "~/.roo/commands/*.md",
         ".roo/mcp.json",
         "~/.roo/rules/",
-        "~/.roo/custom_modes.yaml",
         "mcp_settings.json"
       ],
       "our_generators": [
@@ -486,8 +494,11 @@
       },
       "config_paths": [
         "AGENTS.md",
+        "~/.codex/AGENTS.md",
+        "~/.codex/AGENTS.override.md",
         ".agents/skills/*/SKILL.md",
         ".codex/hooks.json",
+        "~/.codex/hooks.json",
         ".codex/config.toml",
         "~/.codex/config.toml"
       ],

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_language_rules_skills.py

@@ -10,8 +10,10 @@ This is the proper progressive-disclosure replacement for the v1.3.8 pointer
 block in ``.claude/CLAUDE.md``: instead of nudging Claude to Read absolute
 nvm-pinned paths on demand, the rules ride on the Agent Skills mechanism.
 
-Common rules (``app/rules/common/``) stay inlined in ``CLAUDE.md`` because
-they are language-agnostic and should be visible regardless of context.
+Common rules (``app/rules/common/``) are installed as Claude Code
+path-scoped ``.claude/rules/ai-toolkit-*.md`` files by ``install --local``.
+This keeps ``CLAUDE.md`` below Claude's current size guidance while still
+loading common guidance when project files are opened.
 
 Idempotent: rerunning overwrites generated SKILL.md but leaves any other
 files in the skill directory alone.

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

@@ -9,7 +9,7 @@ Claude Code (~/.claude/):
   - Per-file symlinks: agents/*.md, skills/*/  (merges with user files)
   - Merged JSON: hooks.json (toolkit entries tagged with _source)
   - Marker injection: constitution.md, ARCHITECTURE.md (preserves user content)
-  - Rules injected into ~/.claude/CLAUDE.md
+  - User-level rules: rules/ai-toolkit-*.md plus compact CLAUDE.md index
 
 Other tools (global config locations):
   - Windsurf: ~/.codeium/windsurf/memories/global_rules.md + ~/.codeium/windsurf/skills/
@@ -18,10 +18,10 @@ 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 injected into
+Registered rules (~/.softspark/ai-toolkit/rules/*.md) are also synced into
 all of the above. Add rules with: ai-toolkit add-rule <rule.md>
 
 Usage:
@@ -412,7 +412,7 @@ def print_summary(local: bool = False) -> None:
     else:
         print()
         print("Next steps:")
-        print("  1. Edit ~/.claude/CLAUDE.md -- add your global rules above the toolkit sections")
+        print("  1. Add hand-written global rules under ~/.claude/rules/ (avoid ai-toolkit-* prefix)")
         print("  2. Per project: ai-toolkit install --local --editors all")
         print("  3. To update: npm install -g @softspark/ai-toolkit@latest && ai-toolkit update")
         print("  4. To register rules from other tools: ai-toolkit add-rule <rule.md>")
@@ -750,7 +750,7 @@ 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)
 

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,16 +74,37 @@ 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:
@@ -88,8 +118,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 +138,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 +151,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 +260,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"
@@ -352,6 +453,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)
@@ -661,17 +791,16 @@ def _apply_extends_config(cwd: Path, merged: dict) -> None:
 
 
 def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> None:
-    """Inject ``app/rules/common/*.md`` content into project's ``.claude/CLAUDE.md``.
+    """Install Claude language-rule entrypoints for a project.
 
     Per-language rules (``app/rules/<lang>/``) are NOT injected here -- they
     ship as ``<lang>-rules`` knowledge skills under ``app/skills/`` and load
-    contextually via the Agent Skills progressive-disclosure mechanism. This
-    keeps ``CLAUDE.md`` small while ensuring language-specific guidance still
-    reaches Claude when relevant.
+    contextually via the Agent Skills progressive-disclosure mechanism.
 
-    Common rules are language-agnostic (security, git workflow, testing,
-    coding-style, performance) and stay inlined so they remain in scope for
-    every prompt.
+    Common rules are written as Claude Code path-scoped rules under
+    ``.claude/rules/``. Current Claude Code guidance targets under 200 lines
+    per ``CLAUDE.md`` file; path-scoped rules keep startup context smaller
+    while still loading the rule bodies when project files are opened.
     """
     if not language_modules:
         return
@@ -681,6 +810,8 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
     if not common_dir.is_dir():
         return
 
+    rule_files = _sync_claude_common_rules(cwd, common_dir)
+
     # Detect requested per-language modules so we can name the linked skills
     # in the marker block. The modules themselves are not inlined.
     langs: list[str] = []
@@ -690,38 +821,30 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
             if name != "common":
                 langs.append(name)
 
-    # Inline full content of every common rule file, stripping YAML
-    # frontmatter so the resulting block reads as plain Markdown.
-    inlined: list[str] = []
-    for f in sorted(common_dir.glob("*.md")):
-        body = f.read_text(encoding="utf-8")
-        if body.startswith("---"):
-            end = body.find("\n---", 3)
-            if end != -1:
-                body = body[end + 4:].lstrip("\n")
-        inlined.append(body.rstrip())
-
     lines: list[str] = ["# Language Rules", ""]
     lines.append(
-        "Common (language-agnostic) rules apply to every change in this "
-        "project. Language-specific rules live in `<lang>-rules` knowledge "
-        "skills (e.g. `python-rules`, `typescript-rules`) and load "
-        "automatically when their triggers match -- you do not need to "
-        "Read them manually."
+        "Common ai-toolkit rules live in `.claude/rules/ai-toolkit-*.md` "
+        "with Claude Code `paths` frontmatter so they load when project files "
+        "are opened instead of expanding this CLAUDE.md at session startup."
+    )
+    if rule_files:
+        lines.append("")
+        lines.append("Common rule files: " + ", ".join(f"`{p}`" for p in rule_files) + ".")
+    lines.append("")
+    lines.append(
+        "Language-specific rules live in `<lang>-rules` knowledge skills "
+        "(e.g. `python-rules`, `typescript-rules`) and load automatically "
+        "when their triggers match -- you do not need to Read them manually."
     )
     if langs:
         skill_names = ", ".join(f"`{l}-rules`" for l in langs)
         lines.append("")
         lines.append(f"Detected languages: {skill_names}.")
-    lines.append("")
-    lines.append("---")
-    lines.append("")
-    lines.extend(inlined)
 
     # Write to temp file, then inject as a single named section so reruns are
     # idempotent (existing block is replaced, not duplicated).
     import tempfile
-    combined = "\n\n".join(lines).rstrip() + "\n"
+    combined = "\n".join(lines).rstrip() + "\n"
     with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False,
                                      encoding="utf-8") as tmp:
         tmp.write(combined)
@@ -738,6 +861,51 @@ def _inject_language_rules(cwd: Path, language_modules: list[str] | None) -> Non
         tmp_path.unlink(missing_ok=True)
 
 
+def _strip_rule_frontmatter(text: str) -> str:
+    if text.startswith("---"):
+        end = text.find("\n---", 3)
+        if end != -1:
+            return text[end + 4:].lstrip("\n")
+    return text
+
+
+def _sync_claude_common_rules(cwd: Path, common_dir: Path) -> list[str]:
+    """Write common ai-toolkit rules as Claude Code path-scoped rules.
+
+    Only ``ai-toolkit-*.md`` files are managed. User-authored files in
+    ``.claude/rules/`` are preserved.
+    """
+    rules_dir = cwd / ".claude" / "rules"
+    rules_dir.mkdir(parents=True, exist_ok=True)
+
+    source_files = sorted(common_dir.glob("*.md"))
+    expected = {f"ai-toolkit-{src.stem}.md" for src in source_files}
+    for stale in sorted(rules_dir.glob("ai-toolkit-*.md")):
+        if stale.name not in expected:
+            stale.unlink()
+
+    written: list[str] = []
+    for src in source_files:
+        body = _strip_rule_frontmatter(src.read_text(encoding="utf-8")).rstrip()
+        rel = Path(".claude") / "rules" / f"ai-toolkit-{src.stem}.md"
+        target = cwd / rel
+        target.write_text(
+            "\n".join([
+                "---",
+                "paths:",
+                '  - "**/*"',
+                "---",
+                "",
+                body,
+                "",
+            ]),
+            encoding="utf-8",
+        )
+        written.append(rel.as_posix())
+
+    return written
+
+
 def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
                             profile: str = "standard",
                             codex_skills: bool = False) -> None:
@@ -750,6 +918,7 @@ def _install_local_dry_run(reset: bool, editors: list[str] | None = None,
         print("  Would create: CLAUDE.md (if missing)")
         print("  Would create: .claude/settings.local.json (if missing)")
         print("  Would inject: .claude/constitution.md")
+        print("  Would generate: .claude/rules/ai-toolkit-*.md")
 
     add_copilot_dir = profile in {"standard", "strict", "full"}
     add_gemini_hooks = profile in {"standard", "strict", "full"}

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",