@softspark/ai-toolkit 2.0.2 → 2.1.1

package/kb/reference/cli-reference.md

@@ -0,0 +1,135 @@
+---
+title: "CLI Reference"
+category: reference
+service: ai-toolkit
+tags: [cli, commands, reference, install, update, plugin, mcp]
+created: "2026-04-13"
+last_updated: "2026-04-13"
+description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
+---
+
+# CLI Reference
+
+```
+Usage: ai-toolkit <command> [options]
+```
+
+## Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `install` | First-time global install into `~/.claude/` + Cursor, Windsurf, Gemini |
+| `install --local` | Claude Code configs only; add `--editors all` or `--editors cursor,aider` for other tools |
+| `update` | Re-apply toolkit after `npm install -g @softspark/ai-toolkit@latest` |
+| `update --local` | Re-apply + auto-detect editors from existing project files |
+| `reset --local` | Wipe all project-local configs and recreate from scratch (clean slate) |
+| `status` | Show installed modules and version |
+| `uninstall` | Remove toolkit from `~/.claude/` |
+| `validate` | Verify toolkit integrity (`--strict` for CI-grade, warnings = errors) |
+| `doctor` | Diagnose install health, hooks, quick-win assets, and artifact drift |
+| `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |
+| `eject [dir]` | Export standalone config (no symlinks, no toolkit dependency) |
+
+## Rule & Hook Injection
+
+| Command | Description |
+|---------|-------------|
+| `add-rule <rule.md> [name]` | Register rule in `~/.softspark/ai-toolkit/rules/` — auto-applied on every `update` |
+| `remove-rule <name> [dir]` | Unregister rule and remove its block from `CLAUDE.md` |
+| `inject-hook <file.json>` | Inject external hooks into settings.json (idempotent, `_source` tagged) |
+| `remove-hook <name>` | Remove injected hooks by source name |
+
+## MCP Management
+
+| Command | Description |
+|---------|-------------|
+| `mcp list` | List available MCP server templates (25 templates) |
+| `mcp editors` | List editors with native MCP config adapters and scopes |
+| `mcp add <name> [names...]` | Add MCP server template(s) to `.mcp.json` |
+| `mcp install --editor <name[,..]> [names...]` | Install templates into native editor MCP config |
+| `mcp show <name>` | Show MCP template config details |
+| `mcp remove <name>` | Remove MCP server from `.mcp.json` or editor MCP config |
+
+## Plugin Management
+
+| Command | Description |
+|---------|-------------|
+| `plugin list` | Show available plugin packs with install status |
+| `plugin install <name> [--editor claude\|codex\|all]` | Install a plugin pack for selected runtime(s) |
+| `plugin install --all [--editor claude\|codex\|all]` | Install all 11 plugin packs |
+| `plugin update <name> [--editor claude\|codex\|all]` | Update a plugin pack (remove + reinstall, preserves data) |
+| `plugin update --all [--editor claude\|codex\|all]` | Update all installed plugin packs |
+| `plugin clean <name> [--days N]` | Prune old plugin data (default: 90 days) |
+| `plugin remove <name> [--editor claude\|codex\|all]` | Remove a plugin pack |
+| `plugin status [--editor claude\|codex\|all]` | Show installed plugins with runtime-specific details |
+
+## Config Inheritance
+
+| Command | Description |
+|---------|-------------|
+| `config validate [path]` | Validate `.softspark-toolkit.json` schema + extends + enforcement |
+| `config diff [path]` | Show project vs base config differences |
+| `config init [flags]` | Create `.softspark-toolkit.json` (`--extends`, `--profile`, `--no-extends`) |
+| `config create-base <name>` | Scaffold base config npm package |
+| `config check [path]` | CI enforcement gate (exit 0=pass, 1=fail, 2=no config; `--json`) |
+
+## Project Registry
+
+| Command | Description |
+|---------|-------------|
+| `projects` | List registered projects |
+| `projects --prune` | Remove stale (deleted) entries |
+| `projects remove /path` | Unregister specific project |
+
+## Generator Commands
+
+| Command | Description |
+|---------|-------------|
+| `generate-all` | Generate all platform configs at once |
+| `agents-md` | Regenerate `AGENTS.md` from agent definitions |
+| `codex-md` | Generate `AGENTS.md` with marker injection for Codex CLI |
+| `codex-rules` | Generate `.agents/rules/*.md` for Codex CLI |
+| `codex-hooks` | Generate `.codex/hooks.json` for Codex CLI |
+| `cursor-rules` | Generate `.cursorrules` (legacy single file) |
+| `cursor-mdc` | Generate `.cursor/rules/*.mdc` (recommended) |
+| `windsurf-rules` | Generate `.windsurfrules` (legacy) |
+| `windsurf-dir-rules` | Generate `.windsurf/rules/*.md` (recommended) |
+| `copilot-instructions` | Generate `.github/copilot-instructions.md` |
+| `gemini-md` | Generate `GEMINI.md` for Gemini CLI |
+| `cline-rules` | Generate `.clinerules` (legacy) |
+| `cline-dir-rules` | Generate `.clinerules/*.md` (recommended) |
+| `roo-modes` | Generate `.roomodes` |
+| `roo-dir-rules` | Generate `.roo/rules/*.md` |
+| `aider-conf` | Generate `.aider.conf.yml` |
+| `conventions-md` | Generate `CONVENTIONS.md` for Aider |
+| `augment-rules` | Generate `.augment/rules/ai-toolkit.md` (legacy) |
+| `augment-dir-rules` | Generate `.augment/rules/ai-toolkit-*.md` (recommended) |
+| `antigravity-rules` | Generate `.agent/rules/` and `.agent/workflows/` |
+| `llms-txt` | Generate `llms.txt` and `llms-full.txt` |
+
+## Other Commands
+
+| Command | Description |
+|---------|-------------|
+| `stats` | Show skill usage statistics (`--reset` to clear, `--json` for raw output) |
+| `benchmark --my-config` | Compare your config vs defaults vs ecosystem |
+| `benchmark-ecosystem` | Generate ecosystem benchmark snapshot |
+| `create skill <name>` | Scaffold new skill from template (`--template=linter\|reviewer\|generator\|workflow\|knowledge`) |
+| `sync` | Config portability via GitHub Gist (`--export`, `--push`, `--pull`, `--import`) |
+| `compile-slm` | Compile toolkit into minimal SLM system prompt (`--budget`, `--model-size`, `--dry-run`) |
+| `evaluate` | Run skill evaluation suite |
+
+## Install / Update Options
+
+```bash
+ai-toolkit install --only agents,hooks          # apply only listed components
+ai-toolkit install --skip hooks                 # skip listed components
+ai-toolkit install --profile minimal            # minimal | standard | strict
+ai-toolkit install --persona backend-lead       # backend-lead | frontend-lead | devops-eng | junior-dev
+ai-toolkit install --local --editors all        # Claude Code + all editors
+ai-toolkit install --local --editors cursor,aider  # + specific editors
+ai-toolkit install --local --lang typescript    # explicit language rules
+ai-toolkit install --modules core,agents,rules-typescript  # selective modules
+ai-toolkit install --list                       # dry-run: show what would change
+ai-toolkit update --local                       # auto-detects editors from existing files
+```

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

@@ -0,0 +1,136 @@
+---
+title: "AI Toolkit - Codex CLI Compatibility"
+category: reference
+service: ai-toolkit
+tags: [codex, compatibility, install, skills, hooks]
+version: "1.0.0"
+created: "2026-04-12"
+last_updated: "2026-04-13"
+description: "Reference for how ai-toolkit maps Claude-oriented skills, hooks, and plugin packs to Codex CLI."
+---
+
+# AI Toolkit - Codex CLI Compatibility
+
+## Summary
+
+Codex CLI now receives the full `ai-toolkit` skill catalog during local install.
+
+Native Codex-compatible skills are linked directly into `.agents/skills/`. Skills
+that depend on Claude-only orchestration primitives are generated as Codex
+wrappers that preserve the original workflow intent while translating execution
+to Codex subagents and plan tracking.
+
+Experimental plugin packs can also target a global Codex surface with
+`ai-toolkit plugin install --editor codex`, which layers plugin-specific skills,
+rules, and hooks into `HOME` without changing the project-local core install
+model.
+
+## Local Install Outputs
+
+`ai-toolkit install --local --editors codex` generates:
+
+- `AGENTS.md`
+- `.agents/rules/*.md`
+- `.agents/skills/*`
+- `.codex/hooks.json`
+
+## Global Plugin Outputs
+
+`ai-toolkit plugin install --editor codex <pack>` bootstraps or reuses:
+
+- `~/AGENTS.md`
+- `~/.agents/rules/*.md`
+- `~/.agents/skills/*`
+- `~/.codex/hooks.json`
+
+Plugin packs only add their own runtime-specific layer on top of the generated
+Codex base. Shared hook scripts and plugin scripts still live in
+`~/.softspark/ai-toolkit/`.
+
+## Skill Translation Model
+
+Two delivery modes are used for Codex:
+
+| Mode | How it is installed | Use case |
+|------|----------------------|----------|
+| Native | Symlink to `app/skills/<name>/` | Skills whose `allowed-tools` are already supported in Codex |
+| Adapted | Generated wrapper directory in `.agents/skills/<name>/` | Skills that rely on Claude-only `Agent`, `Team*`, or `Task*` primitives |
+
+Adapted skills keep the same support assets (`reference/`, `scripts/`, `assets/`)
+via symlinks, but rewrite `SKILL.md` to Codex-native guidance.
+
+## Claude-to-Codex Tool Mapping
+
+The adapter rewrites Claude-specific delegation guidance to the closest Codex
+runtime primitives:
+
+| Claude-oriented primitive | Codex replacement |
+|---------------------------|------------------|
+| `Agent(...)` | `spawn_agent(..., fork_context=True, ...)` |
+| `SendMessage` | `send_input` |
+| `TaskCreate` / `TaskList` / `TaskUpdate` | `update_plan` or explicit checklist tracking |
+| `TaskGet` / `TaskOutput` | `wait_agent` |
+| `TaskStop` / `TeamDelete` | `close_agent` |
+| Agent teams | Multiple spawned subagents with explicit file ownership |
+
+## Adapted Skill Classes
+
+The main adapted group is multi-agent orchestration:
+
+- `/orchestrate`
+- `/workflow`
+- `/swarm`
+- `/teams`
+- `/subagent-development`
+
+The adapter also covers skills that previously depended only on Claude's
+`Agent` primitive, such as:
+
+- `/tdd`
+- `/write-a-prd`
+- `/qa-session`
+- `/triage-issue`
+- `/architecture-audit`
+
+## 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:
+
+- `SessionStart`
+- `PreToolUse`
+- `PostToolUse`
+- `UserPromptSubmit`
+- `Stop`
+
+This means Claude-only events such as `TaskCompleted`, `TeammateIdle`,
+`SubagentStart`, `SubagentStop`, `PreCompact`, `SessionEnd`, and
+`Notification` are not available in `.codex/hooks.json`.
+
+## Behavioral Limits
+
+Codex wrappers preserve workflow intent, but not every Claude runtime behavior
+has a perfect one-to-one equivalent.
+
+Known limits:
+
+- No native Codex equivalent of tmux-backed Agent Teams lifecycle events
+- No separate task object model equivalent to Claude `Task*` APIs
+- Hook event coverage is narrower than Claude Code
+
+These are runtime platform limits, not installation defects.
+
+## Verification
+
+The Codex compatibility path is verified by:
+
+1. Generator contract tests for `generate_codex.py`
+2. Local install tests for `.agents/skills/` and `.codex/hooks.json`
+3. Plugin install tests for global Codex rules, hooks, and cleanup paths
+4. CLI tests for `codex-md` and `codex-hooks`
+
+## Related
+
+- `kb/reference/skills-catalog.md`
+- `kb/reference/architecture-overview.md`
+- `kb/reference/global-install-model.md`

package/kb/reference/comparison.md

@@ -0,0 +1,29 @@
+---
+title: "Ecosystem Comparison"
+category: reference
+service: ai-toolkit
+tags: [comparison, ecosystem, features, alternatives]
+created: "2026-04-13"
+last_updated: "2026-04-13"
+description: "Feature comparison of ai-toolkit vs other Claude Code toolkits and agent frameworks."
+---
+
+# Ecosystem Comparison
+
+| Feature | ai-toolkit | everything-claude-code | wshobson/agents | ruflo |
+|---------|---------------|----------------------|-----------------|-------|
+| Skills | 92 | 100+ | 146 | 20+ |
+| Agents | 44 | 30+ | 112 | 20+ |
+| Machine-enforced constitution | **Yes** | No (docs only) | No | No |
+| Skill-scoped lifecycle hooks | **Yes** | No | No | No |
+| Effort-based model budgeting | **Yes** | No | No | No |
+| Test suite | Yes (bats) | Yes (997 tests) | No | Yes |
+| npm/npx install | Yes | Yes | Yes | Yes |
+| Cross-tool support | **Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex** | 5+ tools | Smithery | Limited |
+| Selective install | Yes | Yes | Yes (72 plugins) | No |
+| Session persistence | Yes | Yes | No | No |
+| Architecture notes | **Yes** | No | No | No |
+| KB/RAG integration | **Yes** | No | No | Yes |
+| License | MIT | MIT | MIT | MIT |
+
+For live benchmark data, see the [ecosystem benchmark snapshot](claude-ecosystem-benchmark-snapshot.md).

package/kb/reference/extension-api.md

@@ -2,11 +2,11 @@
 title: "Extension API Reference"
 category: reference
 service: ai-toolkit
-tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration]
-version: "1.3.8"
+tags: [extension-api, inject-rule, inject-hook, mcp-templates, integration, editors]
+version: "1.3.9"
 created: "2026-04-07"
-last_updated: "2026-04-07"
-description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and mcp template management."
+last_updated: "2026-04-12"
+description: "Reference for ai-toolkit's extension API: inject-rule, inject-hook, remove-rule, remove-hook, and editor-aware MCP template management."
 ---
 
 # Extension API Reference
@@ -27,6 +27,7 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source` | Yes |
 | `add-rule <file.md>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
 | `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
+| `mcp install --editor <name...>` | Native editor MCP config | Render canonical template into editor format | Yes |
 
 ## inject-rule
 
@@ -103,7 +104,7 @@ npx @softspark/ai-toolkit remove-hook my-tool-hooks
 
 The argument is the source name (file stem used during `inject-hook`). If no entries with that source are present, the command exits 0 silently.
 
-## mcp add
+## mcp add / install
 
 Merges one or more MCP server templates from `app/mcp-templates/` into the project's `.mcp.json`.
 
@@ -111,13 +112,24 @@ Merges one or more MCP server templates from `app/mcp-templates/` into the proje
 ai-toolkit mcp add github                # add a single template
 ai-toolkit mcp add github postgres slack  # add multiple at once
 ai-toolkit mcp list                       # list all available templates
+ai-toolkit mcp editors                    # list supported native adapters
 ai-toolkit mcp show github                # print a template's JSON
+ai-toolkit mcp install --editor cursor --scope project github --target .
+ai-toolkit mcp install --editor codex context7
 ai-toolkit mcp remove github             # remove an entry from .mcp.json
+ai-toolkit mcp remove github --editor cursor --scope project --target .
 ```
 
 **Implementation:** `scripts/mcp_manager.py`.
 
-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, the entry is overwritten. See [mcp-templates.md](mcp-templates.md) for the full list of available templates.
+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, the entry is overwritten.
+
+The `install` command renders the same canonical template into a native editor config format. Supported adapters currently cover:
+- JSON clients with `mcpServers`: Claude Code, Cursor, Gemini CLI, Windsurf, Cline, Augment
+- JSON clients with additional required metadata: GitHub Copilot
+- TOML clients: Codex CLI
+
+When `install` runs with `--scope project`, ai-toolkit also updates `.mcp.json` so the project-level config remains the source of truth for later sync and local install flows.
 
 ## Architecture
 
@@ -132,6 +144,7 @@ The `add` command merges the `mcpServers` block from the template into `.mcp.jso
 │    remove-hook  <name>        → settings.json        │
 │    add-rule     <file.md>     → rules/ registry      │
 │    mcp add      <template>    → .mcp.json            │
+│    mcp install  <template>    → editor-native MCP    │
 │                                                      │
 │  Idempotent: markers (rules) / _source tags (hooks)  │
 │  ai-toolkit NEVER calls external services            │
@@ -157,6 +170,9 @@ npx @softspark/ai-toolkit inject-hook ./hooks/my-tool-hooks.json
 
 # Add an MCP server template
 npx @softspark/ai-toolkit mcp add github
+
+# Render the same template into Cursor project config
+npx @softspark/ai-toolkit mcp install --editor cursor --scope project github --target .
 ```
 
 To uninstall:
@@ -172,4 +188,5 @@ All operations are idempotent — safe to run on every install or update.
 
 - [PATH: kb/reference/hooks-catalog.md] — built-in hooks reference
 - [PATH: kb/reference/mcp-templates.md] — available MCP server templates
+- [PATH: kb/reference/mcp-editor-compatibility.md] — native editor MCP support matrix
 - [PATH: kb/reference/architecture-overview.md] — overall install model

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

@@ -2,11 +2,11 @@
 title: "Global Install Model"
 category: reference
 service: ai-toolkit
-tags: [install, global, claude, local-setup]
-version: "1.4.2"
+tags: [install, global, claude, codex, plugins, local-setup]
+version: "1.4.4"
 created: "2026-03-26"
-last_updated: "2026-04-09"
-description: "Reference description of the global install target, local project setup, and command responsibilities in ai-toolkit."
+last_updated: "2026-04-13"
+description: "Reference description of the global install target, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
 # Global Install Model
@@ -17,6 +17,10 @@ description: "Reference description of the global install target, local project
 
 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`.
+
 ## Command Responsibilities
 
 | Command | Target | Purpose |
@@ -29,6 +33,11 @@ That means one machine-level install provides agents, skills, hooks, and rules t
 | `ai-toolkit update --local` | current project | refresh project configs; auto-detects editors from existing files |
 | `ai-toolkit add-rule` | `~/.softspark/ai-toolkit/rules/` | register a global rule |
 | `ai-toolkit remove-rule` | `~/.softspark/ai-toolkit/rules/` | unregister a global rule |
+| `ai-toolkit mcp add <name...>` | current project | merge MCP templates into `.mcp.json` |
+| `ai-toolkit mcp install --editor <name...>` | editor-native config | render MCP templates into editor-specific config files |
+| `ai-toolkit plugin install --editor claude|codex|all <name>` | runtime-native config | install plugin pack for selected runtime(s) |
+| `ai-toolkit plugin update --editor claude|codex|all <name>` | runtime-native config | re-apply plugin pack after toolkit updates |
+| `ai-toolkit plugin remove --editor claude|codex|all <name>` | runtime-native config | remove plugin pack from selected runtime(s) |
 
 ## Why global install is the default
 
@@ -39,10 +48,17 @@ That means one machine-level install provides agents, skills, hooks, and rules t
 
 ## What remains project-local
 
-These files still stay local to a repository:
+These files still stay local to a repository as part of the core install model:
 - `CLAUDE.md`
 - `.claude/settings.local.json`
+- `.mcp.json`
+- `.cursor/mcp.json`
+- `.github/mcp.json`
 - `.claude/constitution.md`
+- project `AGENTS.md`
+- project `.agents/rules/*.md`
+- project `.agents/skills/*`
+- project `.codex/hooks.json`
 - `.github/copilot-instructions.md`
 - `.clinerules`
 - `.roomodes`
@@ -54,7 +70,48 @@ These files still stay local to a repository:
 
 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
+`.codex/hooks.json` points to hook scripts already installed globally in
+`~/.softspark/ai-toolkit/hooks/`.
+
+## Codex Local Install Behavior
+
+`ai-toolkit install --local --editors codex` creates:
+
+- `AGENTS.md`
+- `.agents/rules/*.md`
+- `.agents/skills/*`
+- `.codex/hooks.json`
+
+Native Codex-compatible skills are linked directly. Claude-oriented skills that
+depend on `Agent`, `Team*`, or `Task*` primitives are translated into generated
+Codex wrappers so the project still receives the full skill catalog.
+
+## Codex Global Plugin Layer
+
+`ai-toolkit plugin install --editor codex <pack>` additionally targets:
+
+- `~/AGENTS.md`
+- `~/.agents/rules/*.md`
+- `~/.agents/skills/*`
+- `~/.codex/hooks.json`
+
+This is not the default core install path. It is an explicit, opt-in plugin
+layer used only for plugin packs. Runtime state is tracked in
+`~/.softspark/ai-toolkit/plugins.json` per target (`claude`, `codex`).
+
+## MCP Local Sync Behavior
+
+If `.mcp.json` exists in the current project, `ai-toolkit install --local` mirrors its `mcpServers` block into:
+- `.claude/settings.local.json`
+- `.cursor/mcp.json` when `--editors cursor` is selected
+- `.github/mcp.json` when `--editors copilot` is selected
+
+Global-only editor MCP configs are not written during `install --local`. Use `ai-toolkit mcp install --editor <name...>` for those targets.
+
 ## Related Documents
 
 - `kb/reference/distribution-model.md`
 - `kb/reference/merge-friendly-install-model.md`
+- `kb/reference/codex-cli-compatibility.md`
+- `kb/reference/mcp-editor-compatibility.md`

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

@@ -0,0 +1,62 @@
+---
+title: "AI Toolkit - MCP Editor Compatibility"
+category: reference
+service: ai-toolkit
+tags: [mcp, editors, compatibility, codex, cursor]
+version: "1.0.0"
+created: "2026-04-12"
+last_updated: "2026-04-12"
+description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
+---
+
+# MCP Editor Compatibility
+
+## Overview
+
+ai-toolkit keeps `.mcp.json` as the project-level canonical template format and can render that config into native editor MCP files where the editor exposes a stable, documented configuration surface.
+
+## Supported Native Adapters
+
+| Editor | Scope | Native Config Path | Adapter Behavior |
+|--------|-------|--------------------|------------------|
+| Claude Code | project + global | `.claude/settings.local.json`, `~/.claude/settings.json` | Merges `mcpServers` while preserving other settings keys |
+| 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 |
+| 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 |
+| Codex CLI | global | `~/.codex/config.toml` | Renders JSON templates as TOML `mcp_servers` tables |
+
+## Unsupported for Automatic Install
+
+These editors are still supported by ai-toolkit for rules and instructions, but ai-toolkit does not currently auto-write MCP config because a stable official file target was not adopted:
+
+| 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 |
+
+## CLI
+
+```bash
+ai-toolkit mcp editors
+ai-toolkit mcp install --editor cursor --scope project github --target .
+ai-toolkit mcp install --editor codex context7
+ai-toolkit mcp remove github --editor cursor --scope project --target .
+```
+
+## Install Flow Integration
+
+When `.mcp.json` exists in a project, `ai-toolkit install --local` mirrors its servers into:
+- `.claude/settings.local.json`
+- `.cursor/mcp.json` when `--editors cursor` is selected
+- `.github/mcp.json` when `--editors copilot` is selected
+
+Global-only clients are configured explicitly via `ai-toolkit mcp install --editor ...`.
+
+## Related
+
+- [PATH: kb/reference/mcp-templates.md] — template catalog and CLI
+- [PATH: kb/reference/extension-api.md] — extension API surface

package/kb/reference/mcp-templates.md

@@ -2,33 +2,58 @@
 title: "MCP Server Templates"
 category: reference
 service: ai-toolkit
-tags: [mcp, templates, servers, configuration]
-version: "1.0.0"
+tags: [mcp, templates, servers, configuration, editors]
+version: "1.1.0"
 created: "2026-04-07"
-last_updated: "2026-04-07"
-description: "Reference for 25 MCP server configuration templates: GitHub, PostgreSQL, Slack, Sentry, and more."
+last_updated: "2026-04-12"
+description: "Reference for 25 MCP server templates plus native editor MCP installation support."
 ---
 
 # MCP Server Templates
 
 ## Overview
 
-ai-toolkit ships 25 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the `mcpServers` block for a specific service. Templates are merged into the project's `.mcp.json` via the `ai-toolkit mcp` CLI subcommand.
+ai-toolkit ships 25 ready-to-use MCP server configuration templates in `app/mcp-templates/`. Each template is a JSON file that defines the canonical `mcpServers` block for a specific service. Templates can be merged into the project's `.mcp.json` and rendered into editor-native MCP config files via the `ai-toolkit mcp` CLI subcommand.
 
 ## CLI
 
 ```bash
 ai-toolkit mcp list               # List all available templates
+ai-toolkit mcp editors            # List editors with native MCP adapters
 ai-toolkit mcp show <name>        # Print a template's JSON config
 ai-toolkit mcp add <name>         # Merge a template into .mcp.json
 ai-toolkit mcp add <n1> <n2>      # Add multiple templates at once
-ai-toolkit mcp remove <name>      # Remove a server entry from .mcp.json
+ai-toolkit mcp install --editor cursor --scope project github --target .
+ai-toolkit mcp install --editor codex context7
+ai-toolkit mcp remove <name>      # Remove from .mcp.json or native editor config
 ```
 
 **Implementation:** `scripts/mcp_manager.py`
 
 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 additional transport metadata: GitHub Copilot
+- TOML clients: Codex CLI (`[mcp_servers.<name>]`)
+
+When `install` runs with `--scope project`, ai-toolkit also updates the project's `.mcp.json` so it remains the source of truth for later syncs.
+
+## Editor Support Matrix
+
+| Editor | Scope | Native Config Path | Notes |
+|--------|-------|--------------------|-------|
+| `claude` | project + global | `.claude/settings.local.json`, `~/.claude/settings.json` | Preserves existing hooks and env keys |
+| `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 |
+| `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`).
+
 ## Template List
 
 | Name | Description | Required Env Vars |
@@ -108,3 +133,4 @@ export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...
 
 - [PATH: kb/reference/extension-api.md] — `mcp add` as part of the extension API
 - [PATH: kb/reference/architecture-overview.md] — overall install model
+- [PATH: kb/reference/mcp-editor-compatibility.md] — native editor MCP support matrix