@softspark/ai-toolkit 3.0.2 → 3.1.0

package/kb/history/completed/ecosystem-deep-sweep-20260423.md

@@ -259,7 +259,7 @@ Orchestrator's final output:
 
 ### Open items flagged for future passes
 
-1. **Native `.codex/skills/*/SKILL.md` emission** (class B) — would write ~99 skill directories. Needs opt-in flag + minor bump.
+1. **Native `.agents/skills/*/SKILL.md` emission** (class B) — writes the Codex skill catalog to the upstream discovery path.
 2. **`.opencode/skills/` duplication** — deferred indefinitely; `.claude/skills/` fallback already works.
 3. **New generators needed**: `generate_gemini_hooks.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`.
 4. **Cross-editor hooks unification**: Cursor and Windsurf both shipped `.cursor/hooks.json` and `.windsurf/hooks.json` — worth a dedicated shared-schema pass rather than per-editor copies.

package/kb/procedures/release-preparation-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem]
-version: "1.10.0"
+version: "1.10.1"
 created: "2026-04-10"
-last_updated: "2026-04-24"
+last_updated: "2026-04-28"
 description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, the ecosystem-sync gate added in v1.9.0, and the registry-vs-generators drift gate added in v1.10.0."
 ---
 
@@ -279,7 +279,7 @@ python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS
 python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint
 
 # Registry / generator drift (added in 1.10.0). Meta-generators excluded.
-META="generate_agents_md.py|generate_llms_txt.py"
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
 diff \
   <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
   <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
@@ -304,7 +304,7 @@ echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp
 
 **One-liner:**
 ```bash
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py' | sort -u) && npm test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py|generate_language_rules_skills\.py' | sort -u) && npm test
 ```
 
 **If tests fail:** Fix the issue, do NOT skip. Common failures:

package/kb/procedures/release-verification-sop.md

@@ -3,9 +3,9 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.4.0"
+version: "1.4.1"
 created: "2026-04-08"
-last_updated: "2026-04-24"
+last_updated: "2026-04-28"
 description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds."
 ---
 
@@ -54,7 +54,7 @@ python3 scripts/audit_skills.py --permissions | head -30    # 12. Broad-access s
 npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 13. Provenance attested on npm?
 
 # Deep-coverage verification (Phase 9, v3.0.0+)
-META="generate_agents_md.py|generate_llms_txt.py"
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
 diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 14. Registry <-> generators drift?
 ```
 
@@ -124,7 +124,7 @@ ai-toolkit status
 - [ ] Agents >= 44
 - [ ] Skills >= 99
 - [ ] Hooks merged into settings.json
-- [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
+- [ ] "Other AI Tools" section lists documented global targets only: aider, augment, cline, codex, gemini, opencode, roo, windsurf (Cursor, Copilot, Antigravity via --local for rules)
 
 **Verify `status`:**
 - [ ] Version matches expected
@@ -338,7 +338,7 @@ These verify the native-surface generators shipped in v3.0.0 actually emit the r
 D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
 ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
   --profile full --codex-skills --dry-run 2>&1 \
-  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.windsurf/hooks\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/skills"
+  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.windsurf/hooks\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.agents/skills"
 ```
 
 **Verify** — at least the following lines appear:
@@ -346,22 +346,21 @@ ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
 - [ ] `.windsurf/hooks.json`
 - [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
 - [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
-- [ ] `.codex/skills/` (opt-in via `--codex-skills`)
+- [ ] `.agents/skills/` (Codex native discovery path; refreshed by `--codex-skills`)
 
 ### 9.2 `--codex-skills` is orthogonal to `--profile`
 
 ```bash
 D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
 ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
-  | grep -q "Would generate: .codex/skills" && echo "OK: --codex-skills works without --profile full"
+  | grep -q "Would refresh: .agents/skills" && echo "OK: --codex-skills refreshes .agents/skills without --profile full"
 ai-toolkit install --local --editors codex --profile full --dry-run 2>&1 \
-  | grep -q "Would generate: .codex/skills" && echo "FAIL: --profile full should NOT auto-emit .codex/skills" \
-  || echo "OK: --profile full alone does not auto-emit .codex/skills (correct — opt-in only)"
+  | grep -q "Would generate: .agents/skills" && echo "OK: Codex skills use .agents/skills at profile full"
 ```
 
 **Verify:**
-- [ ] `--codex-skills` emits `.codex/skills/` at any profile
-- [ ] `--profile full` alone does NOT emit `.codex/skills/` (must be opt-in)
+- [ ] `--codex-skills` refreshes `.agents/skills/` at any profile
+- [ ] `--profile full` never emits `.codex/skills/`; Codex skills use `.agents/skills/`
 
 ### 9.3 Breaking-change surfaces land on `--profile standard`
 
@@ -411,7 +410,7 @@ done
 `kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.
 
 ```bash
-META="generate_agents_md.py|generate_llms_txt.py"
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.py"
 REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
 FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
 diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"

package/kb/reference/architecture-overview.md

@@ -187,7 +187,7 @@ Three tiers determine how to approach a task:
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 36 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 49 |
 
 ## Multi-Agent Execution
 

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.0"
+version: "3.0.1"
 created: "2026-03-26"
-last_updated: "2026-04-23"
+last_updated: "2026-04-28"
 description: "Reference description of the global install target, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -17,9 +17,12 @@ description: "Reference description of the global install target, project-local
 
 That means one machine-level install provides agents, skills, hooks, and rules to every project without committing toolkit boilerplate into each repository.
 
-Codex remains project-local for the core toolkit install, but experimental
-plugin packs can now layer a global Codex target in `HOME` when explicitly
-installed with `ai-toolkit plugin install --editor codex`.
+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
+the settings UI, not a stable merge-safe file. Codex remains project-local for
+the core toolkit install, but experimental plugin packs can layer a global
+Codex target in `HOME` when explicitly installed with
+`ai-toolkit plugin install --editor codex`.
 
 ## Command Responsibilities
 
@@ -50,7 +53,25 @@ The `--profile` flag controls how much of each editor's native surface is activa
 | `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks. | Solo dev or tight team with zero tolerance for drift. |
 | `full` | Every native surface across every editor: hooks, sub-agents, custom commands, skill pointers for Cursor / Windsurf / Gemini / Augment / Antigravity. | You want maximum coverage and understand that each editor will carry generated files under its own layout. |
 
-`--codex-skills` is an independent opt-in flag (not part of profile) that materializes the full `.claude/skills/` catalog under `.agents/skills/` for Codex. Other editors stay on compat-read or the per-editor pointer skill.
+`--codex-skills` is an independent opt-in flag (not part of profile) that materializes the full skill catalog under `.agents/skills/` for Codex. Other editors stay on compat-read or the per-editor pointer skill.
+
+## Global Editor Targets
+
+`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`
+- `gemini`: `~/.gemini/GEMINI.md`
+- `augment`: `~/.augment/rules/ai-toolkit.md`
+- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md`
+- `roo`: `~/.roo/rules/ai-toolkit-*.md`
+- `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
+- `codex`: `~/AGENTS.md`, `~/.agents/rules/*`, `~/.agents/skills/*`, `~/.codex/hooks.json`
+- `opencode`: `~/.config/opencode/*`
+
+Cursor, GitHub Copilot, and Google Antigravity rule installs stay project-local.
+Their global MCP support, where available, is handled by `ai-toolkit mcp
+install`, not by the rule installer.
 
 ## Why global install is the default
 
@@ -66,6 +87,7 @@ These files still stay local to a repository as part of the core install model:
 - `.claude/settings.local.json`
 - `.mcp.json`
 - `.cursor/mcp.json`
+- `.roo/mcp.json`
 - `.github/mcp.json`
 - `.claude/constitution.md`
 - project `AGENTS.md`
@@ -119,6 +141,7 @@ If `.mcp.json` exists in the current project, `ai-toolkit install --local` mirro
 - `.claude/settings.local.json`
 - `.cursor/mcp.json` when `--editors cursor` is selected
 - `.github/mcp.json` when `--editors copilot` is selected
+- `.roo/mcp.json` when `--editors roo` is selected
 
 Global-only editor MCP configs are not written during `install --local`. Use `ai-toolkit mcp install --editor <name...>` for those targets.
 

package/kb/reference/language-rules.md

@@ -3,19 +3,22 @@ title: "Language Rules System"
 category: reference
 service: ai-toolkit
 tags: [rules, languages, coding-style, testing, patterns, security]
-version: "1.0.0"
+version: "2.0.0"
 created: "2026-04-07"
-last_updated: "2026-04-07"
-description: "Reference for the language-specific rules system: 14 languages, 5 categories per language, auto-detection."
+last_updated: "2026-04-28"
+description: "Reference for the language-specific rules system: 13 per-language rule sets shipped as knowledge skills, plus a common set inlined into CLAUDE.md."
 ---
 
 # Language Rules System
 
 ## Overview
 
-ai-toolkit ships language-specific rule files covering 14 languages/platforms plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
+ai-toolkit ships rule content for 13 languages/platforms plus a language-agnostic common set. Source files live under `app/rules/` and are split into two delivery channels by `ai-toolkit install --local`:
 
-Rules are distinct from skills: rules are injected as static text into `CLAUDE.md` and are always visible to Claude, whereas skills are loaded contextually by agents.
+- **Common rules** (`app/rules/common/*.md`): full content is inlined into the project's `.claude/CLAUDE.md` under a single `<!-- TOOLKIT:language-rules START -->` marker. They cover coding-style, git-workflow, performance, security, and testing — concerns that apply regardless of language, so they stay always visible.
+- **Per-language rules** (`app/rules/<lang>/*.md`): emitted at build time as `<lang>-rules` knowledge skills under `app/skills/`. Each skill is `user-invocable: false`, so Claude loads it via the Agent Skills progressive-disclosure mechanism only when its description triggers match (file extensions, framework names, or matching keywords in the prompt).
+
+The skills are generated from the rule files via `python3 scripts/generate_language_rules_skills.py`, which is idempotent and rerun-safe. Other editors (Cursor, Windsurf, Cline, Roo, Augment, Codex, Copilot, Antigravity, Gemini, opencode) still receive the full per-language rule content via their own generators in `scripts/dir_rules_shared.py::build_language_rules()` — Claude is the only target where the per-language content is now skill-delivered rather than inlined.
 
 ## File Structure
 
@@ -52,7 +55,7 @@ app/rules/
 └── medplum/
 ```
 
-**Total: 14 directories × 5 files each + 3 standalone = 73 rule files** (see README.md for canonical count)
+**Total: 13 per-language directories × 5 files + 1 common directory × 5 files + 3 standalone files** (see README.md for canonical count). Per-language directories ship as `<lang>-rules` knowledge skills; the common directory is inlined into CLAUDE.md.
 
 ## Supported Languages
 
@@ -137,15 +140,45 @@ ai-toolkit install --local --modules core,agents
 
 The `--lang` flag accepts comma-separated language names and converts them to `rules-<lang>` modules. Common aliases are supported: `go` → `golang`, `c++` → `cpp`, `c#`/`cs` → `csharp`. Using `--lang` implies `--local` and disables auto-detection.
 
-Language rules are injected into the project `CLAUDE.md` between named markers:
+Common rules are injected into the project `CLAUDE.md` between a single named marker (the per-language markers from v1.x are no longer used):
 
 ```
-<!-- TOOLKIT:rules-typescript START -->
-... TypeScript rules content ...
-<!-- TOOLKIT:rules-typescript END -->
+<!-- TOOLKIT:language-rules START -->
+# Language Rules
+
+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.
+
+Detected languages: `python-rules`, `typescript-rules`.
+
+---
+
+... full content of app/rules/common/*.md inlined here ...
+<!-- TOOLKIT:language-rules END -->
 ```
 
-Re-running `install --local` is idempotent — existing blocks are replaced, not duplicated.
+Re-running `install --local` is idempotent — the existing block is replaced, not duplicated. Per-language rules are not injected into `CLAUDE.md` for Claude — they are loaded contextually via their respective `<lang>-rules` knowledge skills.
+
+### Generating language-rules skills
+
+The `<lang>-rules` skills under `app/skills/` are produced by:
+
+```bash
+python3 scripts/generate_language_rules_skills.py            # write all
+python3 scripts/generate_language_rules_skills.py --check    # dry-run, exit 1 on diff
+python3 scripts/generate_language_rules_skills.py --langs python,rust  # subset
+```
+
+The generator reads `app/rules/<lang>/*.md`, strips YAML frontmatter, concatenates the categories, and writes `app/skills/<lang>-rules/SKILL.md` with frontmatter:
+
+- `name: <lang>-rules`
+- `description: ...` — language label, rule categories, and concrete trigger keywords (file extensions, framework names) so the skill activates reliably when Claude is working on that language.
+- `user-invocable: false` — knowledge skill, no slash command.
+- `allowed-tools: Read` — the skill body is reference content, not an action.
+
+Rerunning the generator is idempotent. Editing rule files under `app/rules/<lang>/` and rerunning the generator is the canonical way to update a language skill.
 
 ## Manifest Module Names
 
@@ -170,13 +203,16 @@ Language rules are tracked as modules in `manifest.json`:
 
 ## Rules vs Skills
 
-| | Rules | Skills |
-|---|-------|--------|
-| Location | `app/rules/` | `app/skills/` |
-| Delivery | Injected into `CLAUDE.md` text | Loaded from `~/.claude/skills/` |
-| Visibility | Always visible in context | Loaded contextually by agents |
-| Scope | Per-language static guidance | Domain-specific agent behavior |
-| Install | `--local` only | Global install |
+| | Common rules | Per-language rules | Other skills |
+|---|---|---|---|
+| Source | `app/rules/common/` | `app/rules/<lang>/` | `app/skills/<name>/SKILL.md` |
+| Delivery to Claude | Inlined into project `CLAUDE.md` (`--local`) | Generated as `<lang>-rules` knowledge skills, loaded contextually | Loaded contextually by description match |
+| Visibility | Always in context | Loaded when triggers match (file extensions, framework names) | Loaded when triggers match |
+| Scope | Language-agnostic standards (security, git, testing, perf, style) | Per-language coding-style, frameworks, patterns, security, testing | Domain skills (testing, debugging, RAG, etc.) |
+| Install | `ai-toolkit install --local` | Global install (skills directory is symlinked) | Global install |
+| Other editors | Inlined into editor-specific rule files | Inlined into editor-specific rule files (still full content, not skills) | N/A |
+
+Per-language content delivered as a knowledge skill is the same Markdown that other editors receive inlined. The split exists only for Claude, where the Agent Skills progressive-disclosure mechanism keeps the system prompt small.
 
 ## Related Documentation
 

package/kb/reference/mcp-editor-compatibility.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - MCP Editor Compatibility"
 category: reference
 service: ai-toolkit
 tags: [mcp, editors, compatibility, codex, cursor]
-version: "1.0.0"
+version: "1.1.0"
 created: "2026-04-12"
-last_updated: "2026-04-12"
+last_updated: "2026-04-28"
 description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
 ---
 
@@ -23,6 +23,7 @@ ai-toolkit keeps `.mcp.json` as the project-level canonical template format and
 | Cursor | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors `mcpServers` directly |
 | GitHub Copilot | project + global | `.github/mcp.json`, `~/.copilot/mcp-config.json` | Adds Copilot-required `type` and `tools` fields |
 | Gemini CLI | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Merges `mcpServers` into settings JSON |
+| Roo Code | project | `.roo/mcp.json` | Mirrors `mcpServers` into the documented project-level MCP file |
 | Windsurf | global | `~/.codeium/windsurf/mcp_config.json` | Global-only JSON config |
 | Cline | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only JSON config |
 | Augment | global | `~/.augment/settings.json` | Global-only JSON settings file |
@@ -34,7 +35,6 @@ These editors are still supported by ai-toolkit for rules and instructions, but
 
 | Editor | Reason |
 |--------|--------|
-| Roo Code | MCP support exists, but no verified official file path was adopted in ai-toolkit |
 | Aider | No verified native MCP config surface was adopted in ai-toolkit |
 | Google Antigravity | MCP can be configured via UI/import flows, but no stable file target was adopted in ai-toolkit |
 
@@ -53,6 +53,7 @@ When `.mcp.json` exists in a project, `ai-toolkit install --local` mirrors its s
 - `.claude/settings.local.json`
 - `.cursor/mcp.json` when `--editors cursor` is selected
 - `.github/mcp.json` when `--editors copilot` is selected
+- `.roo/mcp.json` when `--editors roo` is selected
 
 Global-only clients are configured explicitly via `ai-toolkit mcp install --editor ...`.
 

package/kb/reference/mcp-templates.md

@@ -33,7 +33,7 @@ ai-toolkit mcp remove <name>      # Remove from .mcp.json or native editor confi
 The `add` command merges the `mcpServers` block from the template into `.mcp.json`. If `.mcp.json` does not exist it is created. If the server name already exists in `.mcp.json`, the entry is overwritten with the template version.
 
 The `install` command renders the same canonical template into an editor-native config format:
-- JSON clients with `mcpServers` blocks: Claude Code, Cursor, Gemini CLI, Windsurf, Cline, Augment
+- JSON clients with `mcpServers` blocks: Claude Code, Cursor, Gemini CLI, Roo Code, Windsurf, Cline, Augment
 - JSON clients with additional transport metadata: GitHub Copilot
 - TOML clients: Codex CLI (`[mcp_servers.<name>]`)
 
@@ -47,12 +47,13 @@ When `install` runs with `--scope project`, ai-toolkit also updates the project'
 | `cursor` | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors canonical `mcpServers` |
 | `copilot` | project + global | `.github/mcp.json`, `~/.copilot/mcp-config.json` | Adds `type` and `tools: ["*"]` automatically |
 | `gemini` | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Uses Gemini CLI `mcpServers` format |
+| `roo` | project | `.roo/mcp.json` | Mirrors canonical `mcpServers` into Roo's project MCP file |
 | `windsurf` | global | `~/.codeium/windsurf/mcp_config.json` | Global-only official config |
 | `cline` | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only official config |
 | `augment` | global | `~/.augment/settings.json` | Global-only settings file |
 | `codex` | global | `~/.codex/config.toml` | Rendered as TOML `mcp_servers` tables |
 
-Project-local `ai-toolkit install --local` also mirrors `.mcp.json` into Claude project settings plus selected project editors that have official repository/workspace MCP files (`cursor`, `copilot`).
+Project-local `ai-toolkit install --local` also mirrors `.mcp.json` into Claude project settings plus selected project editors that have official repository/workspace MCP files (`cursor`, `copilot`, `roo`).
 
 ## Template List
 

package/kb/reference/supported-tools-registry.md

@@ -3,9 +3,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.2.0"
+version: "1.2.1"
 created: "2026-04-23"
-last_updated: "2026-04-24"
+last_updated: "2026-04-28"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -47,8 +47,8 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://cursor.com/docs |
 | Changelog | https://cursor.com/changelog |
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
-| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json`, `~/.cursor/hooks.json` |
-| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.codex/skills/`, `.codex/agents/` (Cursor cross-reads these so ai-toolkit's Claude install works automatically) |
+| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json` |
+| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.agents/skills/` (Cursor cross-reads these so ai-toolkit's Claude/Codex installs work automatically) |
 | Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full), `scripts/generate_cursor_agents.py` (profile=full) |
 | Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
 
@@ -102,6 +102,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py` |
 | Tracked capabilities | `clinerules`, Plan Mode, Act Mode, MCP, custom modes, workflows, hooks, skills, subagents, conditional rules |
 | Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Skills (`.cline/skills/`) and hooks (`.clinerules/hooks/`) remain experimental upstream and are not yet generated. |
+| Global install | `ai-toolkit install --editors cline` writes only documented global rules under `~/Documents/Cline/Rules/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |
 
 ### Roo Code
 
@@ -110,10 +111,10 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `roo-code` |
 | Docs | https://docs.roocode.com |
 | Release notes | https://github.com/RooCodeInc/Roo-Code/releases |
-| Config paths | `.roomodes`, `.roo/rules/*.md`, `.roo/rules-{slug}/*.md`, `.roo/mcp.json`, `~/.roo/rules/`, `~/.roo/settings/custom_modes.yaml`, `~/.roo/settings/mcp_settings.json` |
+| Config paths | `.roomodes`, `.roo/rules/*.md`, `.roo/rules-{slug}/*.md`, `.roo/mcp.json`, `~/.roo/rules/`, `~/.roo/custom_modes.yaml`, `mcp_settings.json` (global via Roo settings UI) |
 | Our generators | `scripts/generate_roo_modes.py`, `scripts/generate_roo_rules.py` |
 | Tracked capabilities | `roomodes`, custom modes, Code Actions, MCP, Orchestrator mode, `whenToUse`, `description`, `roleDefinition`, `groups` |
-| Notes | `.roomodes` now includes `description` and `whenToUse` for every mode (since 2026-04). YAML `.roomodes` is upstream-preferred but not yet emitted — JSON is still accepted by Roo. |
+| Notes | `.roomodes` now includes `description` and `whenToUse` for every mode (since 2026-04). YAML `.roomodes` is upstream-preferred but not yet emitted — JSON is still accepted by Roo. Global install writes only `~/.roo/rules/` because the exact global MCP settings path is UI-managed. |
 
 ### Aider
 
@@ -125,6 +126,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Config paths | `.aider.conf.yml`, `CONVENTIONS.md`, `~/.aider.conf.yml` |
 | Our generators | `scripts/generate_aider_conf.py`, `scripts/generate_conventions.py` |
 | Tracked capabilities | `.aider.conf.yml`, `CONVENTIONS.md`, `architect`, `auto-accept-architect`, `read`, `lint-cmd`, `test-cmd`, `commit-prompt`, `attribute-co-authored-by`, `chat-language`, `commit-language`, `watch-files`, `auto-commits` |
+| Global install | `ai-toolkit install --editors aider` creates `~/.aider.conf.yml` only when absent and always refreshes `~/.aider-ai-toolkit-CONVENTIONS.md`; existing YAML is preserved. |
 | Version probe | `aider --version` |
 | Latest upstream | v0.86.1 (Aug 2025) |
 
@@ -159,11 +161,11 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `codex-cli` |
 | Docs | https://github.com/openai/codex (redirects from developers.openai.com/codex) |
 | Release notes | https://github.com/openai/codex/releases |
-| Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.codex/hooks.json`, `.codex/skills/*/SKILL.md`, `~/.codex/config.toml` |
+| Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `~/.codex/config.toml` |
 | Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | Tracked hook events | `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`, `PermissionRequest` (6 events supported upstream in `config.toml`) |
 | Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
-| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.codex/skills/*/SKILL.md` (native discovery, not auto-emitted by ai-toolkit yet) |
+| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |
 
 ### opencode