@softspark/ai-toolkit 4.10.1 → 4.12.0

package/CHANGELOG.md

@@ -7,6 +7,44 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.12.0 — Global-first editor installs + Codex path fix (2026-07-02)
+
+Minor release. Expands global (HOME-scoped) installs to every editor with a documented, merge-safe file surface, and fixes a Codex global-install bug where instructions landed in a file Codex never reads. Test count: 1203 → 1208.
+
+### Fixed
+- **Codex global instructions path** — `ai-toolkit install --editors codex` and `ai-toolkit plugin install --editor codex` wrote to `~/AGENTS.md`, which Codex never loads as global instructions, so global installs delivered zero instructions. Now write `~/.codex/AGENTS.md` (the documented `$CODEX_HOME/AGENTS.md`), strip the stale `~/AGENTS.md` toolkit section on upgrade, and warn when `~/.codex/AGENTS.override.md` would mask it.
+- **Codex plugin-pack rules** — pack rules were copied to `~/.agents/rules/`, a directory Codex never reads; now marker-injected into `~/.codex/AGENTS.md`, with legacy dead files cleaned on install/remove (`scripts/plugin.py`).
+- **`inject-hook` Codex event parity** — `CODEX_EVENTS` propagated only 5 of the 9 events `scripts/generate_codex_hooks.py` wires; added `PermissionRequest`, `SubagentStart`, `SubagentStop`, `PreCompact`.
+
+### Added
+- **Global native surfaces for 7 editors** — `install_ai_tools` now threads `--profile` and installs each editor's documented HOME surfaces (gated like the local install): **Gemini** (hooks `~/.gemini/settings.json`, `~/.gemini/commands/`, skills pointer), **Augment** (`~/.augment/agents/`, `~/.augment/commands/`, hooks), **Roo/Zoo** (skills via `~/.agents/skills`), **Windsurf** (`~/.config/devin/AGENTS.md` for Devin CLI), **Cursor** (`~/.cursor/hooks.json`), **GitHub Copilot** (`~/.copilot/` instructions), **Google Antigravity** (skill pointer to `~/.gemini/config/skills` and `~/.gemini/antigravity-cli/skills`).
+
+### Changed
+- **`GLOBAL_CAPABLE_EDITORS`** — added `cursor`, `copilot`, and `antigravity` (scoped: cursor = hooks, copilot = instructions, antigravity = skills; RULES stay project-local where no mergeable global file surface exists).
+- **`generate_copilot.py`** and **`generate_antigravity.py`** gained global layouts (`config_root=~/.copilot`; `generate_global()`).
+
+### Ecosystem
+- **Roo → Zoo Code** (class D) — `RooCodeInc/Roo-Code` archived (frozen v3.54.0, dead release feed); retargeted the feed to the successor `Zoo-Code-Org/Zoo-Code` and added skills/commands config paths. (class F) Global skill install via `~/.agents/skills`.
+- **Cursor** (class F) global `~/.cursor/hooks.json`; (class D) `.cursorrules` demoted to legacy (dropped from official rules docs).
+- **GitHub Copilot** (class F) documented `~/.copilot/` user-level surface adopted.
+- **Google Antigravity** (class F) global skill dirs adopted; `~/.gemini/config/mcp_config.json` global MCP path resolved and recorded (adapter is backlog).
+- **Gemini / Augment** (class F) hooks/commands/agents made global.
+- Version refresh: Gemini v0.49.0, Codex 0.142.5, Auggie 0.31.0, Antigravity CLI 1.0.14, Claude Code 2.1.198; Devin `read_config_from` 7-key matrix. Snapshot re-baselined via `scripts/ecosystem_doctor.py --update`.
+
+## v4.11.0 — Claude rules-space fix + editor registry parity (2026-06-30)
+
+Minor release. Reduces Claude Code startup context pressure by moving ai-toolkit rules out of global/project `CLAUDE.md` inline blocks and into Claude Code rule files. Also finishes the editor registry sync by recording all Gemini generators in the canonical ecosystem registry. Test count: 1198 → 1203.
+
+### Changed
+- **Claude Code global rules now use `~/.claude/rules/ai-toolkit-*.md`.** `ai-toolkit install/update` writes toolkit rules from `app/rules/*.md` and registered rules from `~/.softspark/ai-toolkit/rules/*.md` into Claude Code user-level rule files, keeps `~/.claude/CLAUDE.md` as a compact index, and removes legacy inline rule markers during migration. The `ai-toolkit-*` prefix is installer-managed.
+- **Claude Code common rules now use `.claude/rules/ai-toolkit-*.md`.** `install --local` writes `ai-toolkit-coding-style.md`, `ai-toolkit-git-workflow.md`, `ai-toolkit-performance.md`, `ai-toolkit-security.md`, and `ai-toolkit-testing.md` under `.claude/rules/` with `paths: ["**/*"]` frontmatter, while `.claude/CLAUDE.md` stays a compact index. This follows Claude Code's current guidance to keep `CLAUDE.md` concise and move larger instruction sets into scoped rules.
+- **Language rules reference updated.** `kb/reference/language-rules.md` now documents the Claude-specific split: common rules as project-local Claude rules, per-language rules as knowledge skills, and other editors still receiving native rule files from their generators.
+- **Ecosystem registry reflects Gemini native surfaces.** `scripts/ecosystem_tools.json` now includes `generate_gemini_hooks.py`, `generate_gemini_commands.py`, and `generate_gemini_skills.py` alongside `generate_gemini.py`, matching the installer and supported-tools registry.
+- **Ecosystem doctor baseline refreshed.** Snapshot updated after class A/C upstream documentation drift review; no additional generator contract changes were required.
+
+### Fixed
+- **Claude rules-space regression.** Global Claude installs no longer inline toolkit/registered rules into `~/.claude/CLAUDE.md`, and project-local Claude installs no longer inflate `.claude/CLAUDE.md` with the full common-rule corpus. Regression tests now assert compact CLAUDE.md indexes, generated rule files, legacy marker cleanup, and managed `.claude/rules/ai-toolkit-*.md` refresh behavior.
+
 ## v4.10.1 — Copilot AGENTS.md install + Claude KB-first rule (2026-06-23)
 
 Patch release. Fixes two governance regressions found in the editor-update audit: Copilot installs now emit the root `AGENTS.md` surface documented in the registry, and Claude Code receives the KB-first rule in `CLAUDE.md`, which it actually reads. Test count: 1195 → 1198.

package/README.md

@@ -6,18 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-108-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1198%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1208%20passing-success)](tests/)
 
-## What's New in v4.10.1
+## What's New in v4.12.0
 
-v4.10.1 fixes editor-governance gaps found in the release audit.
+v4.12.0 makes global (HOME-scoped) installs first-class for every editor with a documented file surface, and fixes a Codex global-install bug.
 
-- **Copilot local installs now emit root `AGENTS.md`**: `ai-toolkit install --local --editors copilot` writes the generated agent catalog into a `TOOLKIT:copilot-agents` section while preserving existing Codex/opencode sections and user text.
-- **Claude Code KB-first enforcement restored**: `CLAUDE.md` now carries the mandatory `smart_query()` / `hybrid_search_kb()` rule before technical/project answers, instead of relying on generated `AGENTS.md`.
-- **Codex PostToolUse hook output fixed**: `loop-guard.sh` no longer forces Claude-style JSON with `suppressOutput` under quiet Codex hooks.
-- **Release packaging hardened**: local `.claude` session artifacts under `app/` are excluded from `npm pack`, even if they exist in a maintainer checkout.
-- **Docs and ecosystem baseline refreshed**: README, registry, and architecture docs now match the Copilot implementation; ecosystem-doctor snapshot is refreshed for upstream Claude/Gemini docs hash drift.
-- **Test count**: 1195 → 1198.
+- **Codex global path fix**: `install --editors codex` now writes `~/.codex/AGENTS.md` (the file Codex actually reads) instead of the never-loaded `~/AGENTS.md`; upgrades strip the stale section.
+- **Global installs for 7 editors**: Gemini (hooks/commands/skills), Augment (agents/commands/hooks), Roo/Zoo (skills), Windsurf (`~/.config/devin/AGENTS.md`), plus new global support for Cursor (`~/.cursor/hooks.json`), GitHub Copilot (`~/.copilot/`), and Antigravity (skill pointer).
+- **Roo → Zoo Code**: retargeted the dead `RooCodeInc/Roo-Code` release feed to the active successor `Zoo-Code-Org/Zoo-Code`.
+- **Ecosystem refresh**: Gemini v0.49.0, Codex 0.142.5, Auggie 0.31.0, Antigravity CLI 1.0.14, Claude Code 2.1.198; snapshot re-baselined.
+- **Test count**: 1203 → 1208.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -102,7 +101,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 
 | Platform | Config Files | Hooks | Scope |
 |----------|-------------|:-----:|-------|
-| Claude Code | `~/.claude/` | ✅ | global |
+| Claude Code | `~/.claude/agents`, `~/.claude/skills`, `~/.claude/rules/*.md`, `~/.claude/settings.json` | ✅ | global |
 | Cursor | `.cursor/rules/*.mdc` + `.cursor/mcp.json` + `.cursor/skills/*` | ✅ | project (`~/.cursor/mcp.json` for MCP only) |
 | Windsurf (Devin Desktop) | `~/.codeium/.../global_rules.md` + `~/.codeium/windsurf/skills/*` + `.devin/rules/*.md` + `.windsurf/rules/*.md` (legacy) | ✅ | global + project |
 | Gemini CLI | `~/.gemini/GEMINI.md` | ✅ | global |
@@ -130,7 +129,7 @@ See [CLI Reference](kb/reference/cli-reference.md) for all commands and options.
 | `hooks/` | 29 entries / 14 events | Quality gates, path safety, prompt governance, loop guard, session lifecycle |
 | `plugins/` | 11 packs | Opt-in domain bundles (security, research, frontend, enterprise, 6 language packs) |
 | `constitution.md` | 7 articles | Machine-enforced safety rules |
-| `rules/` | auto-injected | Language-specific and custom rules injected into your configs |
+| `rules/` | auto-synced | Global/project rule files for Claude and other editors |
 | `kb/` | reference docs | Architecture, procedures, and best practices |
 
 ---
@@ -142,7 +141,7 @@ ai-toolkit/
 ├── app/
 │   ├── agents/          # 44 agent definitions
 │   ├── skills/          # 108 skills (task / hybrid / knowledge)
-│   ├── rules/           # Auto-injected into your CLAUDE.md
+│   ├── rules/           # Source rules synced into Claude/editor rule files
 │   ├── hooks/           # Hook scripts (29 entries, 14 lifecycle events)
 │   ├── plugins/         # 11 experimental plugin packs (opt-in)
 │   ├── output-styles/   # System prompt output style overrides
@@ -150,7 +149,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1198 tests)
+├── tests/               # Bats test suite (1208 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.10.1",
+  "version": "4.12.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-06-23T07:06:46Z",
+  "last_run": "2026-07-01T22:55:24Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "a0c51061febc16c4",
+      "docs_hash": "04b55a2b2d496b45",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "c20e5688ed230a66",
+      "docs_hash": "338d55540b385861",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -122,15 +122,18 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.186 (Claude Code)"
+      "version": "2.1.198 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "858fa542e2aacde5",
+      "docs_hash": "80209baf691558e2",
       "headings": [
         "API Reference",
         "Best Practices",
+        "Bring Your Own Key",
         "CLI",
+        "Cline (usage-billing)",
         "Cline Overview",
+        "ClinePass",
         "Configurations",
         "Documentation Index",
         "Features",
@@ -149,6 +152,7 @@
         "\u200bAgent Core (SDK)",
         "\u200bApplications",
         "\u200bEnterprise Solutions",
+        "\u200bModel access",
         "\u200bOther IDE Supports",
         "\u200bWhat is Cline?"
       ],
@@ -168,7 +172,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "eeb0e17a839b09bd",
+      "docs_hash": "ad6bbf5e29c7155f",
       "headings": [
         "API",
         "API Reference",
@@ -208,6 +212,7 @@
         "Resources",
         "Run and scale",
         "Search the Codex docs",
+        "Spaces",
         "Specialized models",
         "Suggested",
         "Tools",
@@ -238,7 +243,7 @@
       "version": "codex-cli 0.142.0"
     },
     "cursor": {
-      "docs_hash": "86b6d48e8ab40d90",
+      "docs_hash": "080c1289cb353e6c",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -254,7 +259,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "c3ba6d09d810f9c3",
+      "docs_hash": "a0ff94dabdb6cd8a",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -269,6 +274,7 @@
         "Provide feedback",
         "Saved searches",
         "Search code, repositories, users, issues, pull requests...",
+        "Uh oh!",
         "Use saved searches to filter your results more quickly",
         "docs",
         "parent directory"
@@ -296,7 +302,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "df7c22e121dbb3d1",
+      "docs_hash": "1f9817b3477c576b",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -330,7 +336,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "e6c90b9d937dd9f0",
+      "docs_hash": "4d2e384b2c2add18",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -347,7 +353,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "302de3ac69940747",
+      "docs_hash": "28dcd5b88aeb84e0",
       "headings": [
         "Add features",
         "Ask questions",
@@ -407,7 +413,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "cdd657d4d684c68a",
+      "docs_hash": "b457c990c531efc4",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -66,7 +66,7 @@ const COMMANDS = {
   reset: 'Wipe and recreate project-local configs from scratch (requires --local)',
   uninstall: 'Remove ai-toolkit from ~/.claude/',
   'add-rule': 'Register a rule file or URL in ~/.softspark/ai-toolkit/rules/ (URL rules auto-refresh on update)',
-  'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
+  'remove-rule': 'Unregister a rule and remove its generated Claude rule file',
   'inject-hook': 'Inject external hooks (file or URL) into ~/.claude/settings.json (URL hooks auto-refresh on update)',
   'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json (also unregisters URL source)',
   'inject-mcp': 'Inject external MCP template (file or URL) into ~/.mcp.json + all editor MCP configs (URL templates auto-refresh on update)',

package/kb/procedures/maintenance-sop.md

@@ -87,7 +87,8 @@ What `install` and `update` do (merge-friendly — user content never overwritte
 | `settings.json` hooks | JSON merge via `merge-hooks.py` | User hooks + settings preserved, toolkit entries tagged `_source: ai-toolkit` |
 | `constitution.md` | Marker injection via `inject_section_cli.py` | User content outside `<!-- TOOLKIT:* -->` markers untouched |
 | `ARCHITECTURE.md` | Marker injection via `inject_section_cli.py` | Same as above |
-| `CLAUDE.md` | Marker injection of `app/rules/*.md` via `inject_rule_cli.py` | User content outside markers untouched |
+| `CLAUDE.md` | Compact index for managed global rules | User content outside toolkit markers untouched |
+| `rules/ai-toolkit-*.md` | File-based Claude Code user-level rules from `app/rules/*.md` and registered rules | `ai-toolkit-*` prefix reserved for installer-managed files |
 
 Re-running updates only toolkit content. Old whole-directory symlinks are auto-upgraded to per-file on next run.
 
@@ -135,7 +136,7 @@ ai-toolkit add-rule ./my-project-rules.md
 # → copies to ~/.softspark/ai-toolkit/rules/my-project-rules.md
 
 ai-toolkit update
-# → injects the rule into ~/.claude/CLAUDE.md and all global editor configs
+# → syncs the rule into ~/.claude/rules/ai-toolkit-registered-*.md and all global editor configs
 
 ai-toolkit update --local
 # → also propagates as ai-toolkit-custom-<name> to directory-based editors (Cursor, Windsurf, Cline, Roo, Augment, Antigravity)
@@ -430,5 +431,6 @@ What `uninstall` does:
 - Removes per-directory skill symlinks (user skills preserved)
 - Strips toolkit hook entries from `settings.json` (user hooks + settings preserved)
 - Strips toolkit markers from `constitution.md` and `ARCHITECTURE.md` (user content preserved; empty files removed)
-- `~/.claude/CLAUDE.md` preserved (contains your custom rules + toolkit rule markers)
+- `~/.claude/CLAUDE.md` preserved (contains your custom content + compact toolkit index)
+- `~/.claude/rules/` preserved unless explicitly removed
 - Empty `agents/` and `skills/` directories cleaned up

package/kb/reference/architecture-overview.md

@@ -32,7 +32,7 @@ ai-toolkit/
   app/                       # All toolkit components
     agents/                  # Agent definitions (.md + YAML frontmatter)
     skills/                  # skills: task, hybrid, knowledge
-    rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
+    rules/                   # Source rules synced into Claude/editor rule files
     hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
     constitution.md          # Immutable safety rules, 7 articles (marker-injected)
@@ -85,8 +85,9 @@ Machine (global)                              Project (local)
   skills/*/      → per-dir symlinks              hooks/     ← hook scripts (copied)
   settings.json  ← hooks merged here
   constitution.md ← marker injection            my-project/
-  ARCHITECTURE.md ← marker injection              CLAUDE.md            ← project rules
-  CLAUDE.md       ← marker injection (rules)      .claude/
+  ARCHITECTURE.md ← marker injection              CLAUDE.md            ← project index
+  CLAUDE.md       ← compact rule index            .claude/
+  rules/*.md      ← Claude user-level rules
                                                     settings.local.json  ← MCP, perms
                                                     constitution.md     ← marker injection
 ```
@@ -123,7 +124,7 @@ If a project already has `.mcp.json`, local install mirrors its `mcpServers` ent
 | `update --local` | `./` | Re-apply + refresh project-local configs |
 | `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
 | `add-rule <file>` | `~/.softspark/ai-toolkit/rules/` | Register rule — auto-applied on every `update` |
-| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/CLAUDE.md` | Unregister rule and remove its block |
+| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/rules/` | Unregister rule and remove generated Claude rule file |
 | `mcp add <name...>` | `./.mcp.json` | Merge canonical MCP template(s) into project config |
 | `mcp install --editor <name...>` | native editor config | Render MCP template(s) into editor-native config files |
 | `validate` | toolkit | Integrity check |

package/kb/reference/codex-cli-compatibility.md

@@ -29,8 +29,7 @@ model.
 
 `ai-toolkit install --local --editors codex` generates:
 
-- `AGENTS.md`
-- `.agents/rules/*.md`
+- `AGENTS.md` (project root; universal coding rules inlined — Codex reads instructions only from AGENTS.md, not `.agents/rules/`)
 - `.agents/skills/*`
 - `.codex/hooks.json`
 
@@ -38,8 +37,7 @@ model.
 
 `ai-toolkit plugin install --editor codex <pack>` bootstraps or reuses:
 
-- `~/AGENTS.md`
-- `~/.agents/rules/*.md`
+- `~/.codex/AGENTS.md` (the documented global instruction file; pack rules are marker-injected here, not written as unread `~/.agents/rules/` files)
 - `~/.agents/skills/*`
 - `~/.codex/hooks.json`
 
@@ -93,20 +91,27 @@ The adapter also covers skills that previously depended only on Claude's
 
 ## Hook Compatibility
 
-Codex does not expose the full Claude hook event surface. The Codex hook
-generator emits only the events supported by Codex runtime integration:
+Codex does not expose the full Claude hook event surface. Codex's
+`HookEventName` enum defines 10 events; the Codex hook generator wires 9 of
+them:
 
 - `SessionStart`
 - `PreToolUse`
 - `PostToolUse`
+- `PermissionRequest`
 - `UserPromptSubmit`
+- `SubagentStart`
+- `SubagentStop`
+- `PreCompact`
 - `Stop`
 
-This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
-`SubagentStart`, `SubagentStop`, `PreCompact`, `SessionEnd`, and
-`Notification` are not available in `.codex/hooks.json`.
+`PostCompact` is the one enum event left unwired (its only hook was the removed
+environment-snapshot probe). Claude-only events such as `TaskCompleted`,
+`TeammateIdle`, `SessionEnd`, and `Notification` have no Codex equivalent and
+are not available in `.codex/hooks.json`. Handler types: only `command` runs;
+`prompt` and `agent` are parsed by Codex but not yet executed.
 
-`inject-hook` automatically propagates Codex-compatible events to
+`inject-hook` automatically propagates these 9 Codex-compatible events to
 `~/.codex/hooks.json` (global layer). Non-Codex events are silently skipped.
 `remove-hook` cleans both Claude and Codex targets.
 

package/kb/reference/extension-api.md

@@ -21,19 +21,19 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 
 | Command | Target File | Mechanism | Idempotent |
 |---------|-------------|-----------|------------|
-| `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
-| `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
+| `inject-rule <file.md>` | `~/.claude/CLAUDE.md` | Legacy HTML comment markers (`<!-- TOOLKIT:name -->`) | Yes |
+| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/rules/` | Unregister and remove generated Claude rule file | Yes |
 | `inject-hook <file.json\|url> [name]` | `~/.claude/settings.json` | JSON `_source` tag per entry, URL cached + registered | Yes |
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source`, unregister URL source | Yes |
 | `inject-mcp <file.json\|url> [name] [--force]` | `~/.mcp.json` + every editor with `global_path` | JSON `_source` tag per server, URL cached + registered, full editor propagation | Yes |
 | `remove-mcp <name>` | `~/.mcp.json` + every editor with `global_path` | Strip all servers with matching `_source`, clean editor configs, unregister URL | Yes |
-| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
+| `add-rule <file.md\|url>` | `~/.softspark/ai-toolkit/rules/` | File copy + sync to `~/.claude/rules/ai-toolkit-registered-*.md` on next `update` | Yes |
 | `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from built-in template | Yes |
 | `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
 ## inject-rule
 
-Injects a Markdown rules file into `~/.claude/CLAUDE.md` between named HTML comment markers.
+Legacy direct injection: injects a Markdown rules file into `~/.claude/CLAUDE.md` between named HTML comment markers. Prefer `add-rule` for persistent global rules; `ai-toolkit update` syncs those into Claude Code user-level rule files under `~/.claude/rules/`.
 
 ```bash
 npx @softspark/ai-toolkit inject-rule ./my-tool-rules.md
@@ -52,7 +52,7 @@ The block name is derived from the file stem (`my-tool-rules.md` → `my-tool-ru
 
 ## remove-rule
 
-Strips a previously injected rule block from `~/.claude/CLAUDE.md`.
+Unregisters a persistent rule, removes `~/.claude/rules/ai-toolkit-registered-<name>.md`, and strips any legacy injected rule block from `~/.claude/CLAUDE.md`.
 
 ```bash
 npx @softspark/ai-toolkit remove-rule my-tool-rules

package/kb/reference/global-install-model.md

@@ -3,9 +3,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "3.0.1"
+version: "3.1.0"
 created: "2026-03-26"
-last_updated: "2026-04-28"
+last_updated: "2026-06-30"
 description: "Reference description of the global install target, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -15,7 +15,7 @@ description: "Reference description of the global install target, project-local
 
 `ai-toolkit` installs globally into `~/.claude/` by default.
 
-That means one machine-level install provides agents, skills, hooks, and rules to every project without committing toolkit boilerplate into each repository.
+That means one machine-level install provides agents, skills, hooks, constitution, and rule files to every project without committing toolkit boilerplate into each repository.
 
 Other editor targets are opt-in and only use documented file surfaces. Cursor
 rules stay project-local because Cursor's global user rules are managed through
@@ -57,19 +57,38 @@ The `--profile` flag controls how much of each editor's native surface is activa
 
 ## Global Editor Targets
 
+Claude Code's default global install writes these managed surfaces:
+
+- `~/.claude/agents/*.md` — per-file symlinks to toolkit agents.
+- `~/.claude/skills/*/` — per-directory symlinks to toolkit skills.
+- `~/.claude/settings.json` — merged hook configuration and global settings.
+- `~/.claude/constitution.md` — marker-injected safety constitution.
+- `~/.claude/ARCHITECTURE.md` — marker-injected architecture reference.
+- `~/.claude/rules/ai-toolkit-*.md` — toolkit rules from `app/rules/*.md`.
+- `~/.claude/rules/ai-toolkit-registered-*.md` — rules registered with `ai-toolkit add-rule`.
+- `~/.claude/CLAUDE.md` — compact index pointing at the managed rule files.
+
+The `ai-toolkit-*` prefix in `~/.claude/rules/` is reserved for installer-managed files. User-authored Claude rules should use another filename prefix, or be registered through `ai-toolkit add-rule` so they are emitted as `ai-toolkit-registered-*.md`.
+
 `ai-toolkit install --editors <name>` can write global files only for editors
 with documented, file-based config surfaces:
 
-- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md`
-- `gemini`: `~/.gemini/GEMINI.md`
-- `augment`: `~/.augment/rules/ai-toolkit.md`
+- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md` plus `~/.config/devin/AGENTS.md` (Devin CLI global rules — the Desktop `global_rules.md` path is not imported by `read_config_from.windsurf`)
+- `gemini`: `~/.gemini/GEMINI.md`; hooks at `~/.gemini/settings.json` (profile ≥ standard); `~/.gemini/commands/` and `~/.gemini/skills/` pointer (profile full)
+- `augment`: `~/.augment/rules/ai-toolkit.md`; `~/.augment/agents/`, `~/.augment/commands/`, and hooks in `~/.augment/settings.json` (profile full)
 - `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
-- `roo`: `~/.roo/rules/ai-toolkit-*.md`
+- `roo`: `~/.roo/rules/ai-toolkit-*.md` plus `~/.agents/skills/*` (Roo/Zoo native skill discovery; skipped when `codex` is also selected, which fills the same dir)
 - `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
-- `codex`: `~/AGENTS.md` (coding rules inlined), `~/.agents/skills/*`, `~/.codex/hooks.json`
+- `codex`: `~/.codex/AGENTS.md` (coding rules inlined; the documented global instruction file — NOT `~/AGENTS.md`, which Codex never loads as global instructions), `~/.agents/skills/*`, `~/.codex/hooks.json`
 - `opencode`: `~/.config/opencode/*`
 
-Cursor, GitHub Copilot, and Google Antigravity rule installs stay project-local.
+Cursor, GitHub Copilot, and Google Antigravity now have partial global support,
+scoped to whatever documented HOME file surface each exposes:
+
+- `cursor`: `~/.cursor/hooks.json` (safety/quality hooks; profile ≥ standard). Cursor RULES stay project-local — their only global surface is the Settings UI.
+- `copilot`: `~/.copilot/copilot-instructions.md` plus `~/.copilot/instructions/ai-toolkit-*.instructions.md` (read by Copilot CLI; VS Code and GitHub.com still use repo `.github/` files, which the local install emits).
+- `antigravity`: skill pointer at `~/.gemini/config/skills/` and `~/.gemini/antigravity-cli/skills/`. Antigravity RULES stay project-local.
+
 Their global MCP support, where available, is handled by `ai-toolkit mcp
 install`, not by the rule installer.
 
@@ -103,6 +122,8 @@ These files still stay local to a repository as part of the core install model:
 - `.git/hooks/pre-commit` (fallback)
 - project-specific documentation or safety overlays
 
+Project-local Claude Code language rules live in `.claude/rules/ai-toolkit-*.md` with `paths` frontmatter. They are separate from the global user-level `~/.claude/rules/ai-toolkit-*.md` files above.
+
 Hooks do **not** live in project-local settings. They are merged only into global `~/.claude/settings.json`.
 
 Codex is the exception in terms of file location, not hook ownership: its local
@@ -126,8 +147,7 @@ Codex wrappers so the project still receives the full skill catalog.
 
 `ai-toolkit plugin install --editor codex <pack>` additionally targets:
 
-- `~/AGENTS.md`
-- `~/.agents/rules/*.md`
+- `~/.codex/AGENTS.md` (base instructions; pack rules are marker-injected here, not written as unread `~/.agents/rules/` files)
 - `~/.agents/skills/*`
 - `~/.codex/hooks.json`
 

package/kb/reference/integrations.md

@@ -3,15 +3,15 @@ title: "AI Toolkit - External Integrations"
 category: reference
 service: ai-toolkit
 tags: [integrations, rules, add-rule]
-version: "1.0.5"
+version: "1.1.0"
 created: "2026-03-26"
-last_updated: "2026-03-26"
-description: "How external repos inject rules into ~/.claude/CLAUDE.md via ai-toolkit"
+last_updated: "2026-06-30"
+description: "How external repos register rules that ai-toolkit syncs into Claude Code user-level rules and other editor configs."
 ---
 
 # External Integrations
 
-Repos that register rules with ai-toolkit so they are automatically injected into `~/.claude/CLAUDE.md` on every `update`.
+Repos that register rules with ai-toolkit so they are automatically synced into Claude Code user-level rules and other editor configs on every `update`.
 
 ---
 
@@ -25,9 +25,11 @@ ai-toolkit add-rule ./jira-rules.md
 ai-toolkit update   # inject now
 ```
 
-After registration, `ai-toolkit update` will always re-inject the rule. Registry location: `~/.softspark/ai-toolkit/rules/`.
+After registration, `ai-toolkit update` will always re-sync the rule. Registry location: `~/.softspark/ai-toolkit/rules/`.
 
-To unregister a rule (removes from `~/.softspark/ai-toolkit/rules/` and strips the block from `CLAUDE.md`):
+For Claude Code, registered rules are written to `~/.claude/rules/ai-toolkit-registered-<name>.md`. The `ai-toolkit-*` prefix in `~/.claude/rules/` is installer-managed; use another prefix for hand-written Claude rules.
+
+To unregister a rule (removes from `~/.softspark/ai-toolkit/rules/`, deletes the generated Claude rule file, and strips any legacy block from `CLAUDE.md`):
 
 ```bash
 ai-toolkit remove-rule jira-rules
@@ -37,17 +39,13 @@ ai-toolkit remove-rule jira-rules
 
 ## How It Works
 
-Both mechanisms use marker-based idempotent injection. Rule name = filename without `.md`.
+Claude Code uses file-based user-level rules:
 
 ```
-<!-- TOOLKIT:jira-rules START -->
-
-...rule content...
-
-<!-- TOOLKIT:jira-rules END -->
+~/.claude/rules/ai-toolkit-registered-jira-rules.md
 ```
 
-Content outside markers is never touched. Re-running updates only the marked block.
+Other editors receive the same registered rule through their native generated rule surfaces. Legacy `CLAUDE.md` marker sections are removed during migration, but content outside toolkit-managed markers is never touched.
 
 ---
 
@@ -56,8 +54,9 @@ Content outside markers is never touched. Re-running updates only the marked blo
 1. Create `<name>-rules.md` in your repo with Claude-relevant conventions
 2. Register it: `ai-toolkit add-rule ./<name>-rules.md`
 3. Verify it appears in: `~/.softspark/ai-toolkit/rules/<name>-rules.md`
-4. On next `install` it will be listed in: `Rules injected: ... <name>-rules`
-5. Add an entry below documenting the integration
+4. On next `install` it will be listed in: `Rules synced: ... <name>-rules`
+5. Verify Claude receives it at: `~/.claude/rules/ai-toolkit-registered-<name>-rules.md`
+6. Add an entry below documenting the integration
 
 ---
 
@@ -66,7 +65,7 @@ Content outside markers is never touched. Re-running updates only the marked blo
 ### rag-mcp
 
 **Rule file:** `rag-mcp.md`
-**Marker:** `TOOLKIT:rag-mcp`
+**Claude rule file:** `~/.claude/rules/ai-toolkit-registered-rag-mcp.md`
 
 Teaches Claude Code the RAG-MCP search protocol: always call `smart_query()` before answering, `kb_id` vs `file_path` distinction, available MCP tools.
 
@@ -78,7 +77,7 @@ ai-toolkit add-rule ./rag-mcp-rules.md
 ### jira-mcp
 
 **Rule file:** `jira-rules.md`
-**Marker:** `TOOLKIT:jira-rules`
+**Claude rule file:** `~/.claude/rules/ai-toolkit-registered-jira-rules.md`
 
 Teaches Claude Code the Jira MCP tool set: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `log_task_time`, and key rules (sync first, hours only, check transitions).