@softspark/ai-toolkit 4.14.0 → 4.15.0

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.2.0"
+version: "3.3.0"
 created: "2026-03-26"
-last_updated: "2026-07-10"
+last_updated: "2026-07-14"
 description: "Reference description of Claude Code global install, Claude app plugin export, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -19,10 +19,11 @@ That means one machine-level install provides agents, skills, hooks, constitutio
 
 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`.
+the settings UI, not a stable merge-safe file. Codex supports both project and
+user installs: project files stay in the repository, while user files use the
+active `CODEX_HOME` (default `~/.codex`) and shared user skills use
+`$HOME/.agents/skills/`. Experimental plugin packs can add a layer to the same
+Codex user surface.
 
 Claude Chat/Desktop/Cowork is a separate runtime. It does not read the
 filesystem surfaces under `~/.claude`; it receives ai-toolkit through an
@@ -53,12 +54,14 @@ The `--profile` flag controls how much of each editor's native surface is activa
 
 | Profile | What runs | Use when |
 |---------|-----------|----------|
-| `minimal` | Agents and skills only. No editor generators beyond pointer skills for editors that require them. | You want the smallest possible footprint, or you manage editor configs by hand. |
-| `standard` (default) | Claude Code + editor rule files. Includes **Gemini hooks** and the **Copilot directory layout** (v3.0.0 change from prior `standard`). | Day-to-day installs. Most users. |
+| `minimal` | Smallest editor surface. Copilot still receives its root instructions, native agents, and self-contained skills; Codex still receives instructions, agents, skills, and native safety hooks. | You want the smallest supported footprint. |
+| `standard` (default) | Claude Code + editor rule files. Includes Gemini hooks and native Copilot instructions, agents, portable skills, and hooks. | Day-to-day installs. Most users. |
 | `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 skill catalog under `.agents/skills/` for Codex. Other editors stay on compat-read or the per-editor pointer skill.
+Codex installs materialize the full skill catalog under `.agents/skills/`
+regardless of profile. The legacy `--codex-skills` flag only requests an
+explicit second refresh of that same mirror and is no longer required.
 
 ## Global Editor Targets
 
@@ -100,14 +103,14 @@ with documented, file-based config surfaces:
 - `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.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`: `~/.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`
+- `codex`: `$CODEX_HOME/AGENTS.md`, `$CODEX_HOME/agents/*.toml`, `$CODEX_HOME/hooks.json`, `$CODEX_HOME/ai-toolkit-hooks/*`, plus `$HOME/.agents/skills/*`; `CODEX_HOME` defaults to `~/.codex`, and `~/AGENTS.md` is not Codex's user-instruction file
 - `opencode`: `~/.config/opencode/*`
 
 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).
+- `copilot`: instructions, native agents, portable skills, and native hooks under `$COPILOT_HOME` when set or `~/.copilot` otherwise. The hook config is `hooks/ai-toolkit.json`; its self-contained runtime is `hooks/ai-toolkit/copilot_hook.py`. VS Code and GitHub.com still use repo `.github/` files, which 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
@@ -134,7 +137,15 @@ These files still stay local to a repository as part of the core install model:
 - project `.agents/rules/*.md`
 - project `.agents/skills/*`
 - project `.codex/hooks.json`
+- project `.codex/hooks/*`
+- project `.codex/agents/*.toml`
+- project `.codex/config.toml` when Codex MCP servers are selected
 - `.github/copilot-instructions.md`
+- `.github/instructions/ai-toolkit-*.instructions.md`
+- `.github/prompts/ai-toolkit-*.prompt.md`
+- `.github/agents/ai-toolkit-*.agent.md`
+- `.github/skills/ai-toolkit-*/SKILL.md` plus required assets and helper scripts
+- `.github/hooks/ai-toolkit.json` plus `.github/hooks/ai-toolkit/copilot_hook.py` (profile ≥ `standard`)
 - `.clinerules`
 - `.roomodes`
 - `.aider.conf.yml`
@@ -145,20 +156,39 @@ These files still stay local to a repository as part of the core install model:
 
 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`.
+Claude Code hooks do **not** live in project-local settings. They are merged only into global `~/.claude/settings.json`. Editor-native generators may emit project-local hook files when that editor documents them; Copilot uses `.github/hooks/*.json` and Codex uses `.codex/hooks.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/`.
+## Copilot Install Behavior
+
+`ai-toolkit install --local --editors copilot` always emits root `AGENTS.md`,
+`.github/copilot-instructions.md`, native `.github/agents`, and portable,
+self-contained `.github/skills`. Profiles `standard`, `strict`, and `full`
+add scoped `.github/instructions`, `.github/prompts`, and native version-1
+`.github/hooks`. Profile `minimal` omits those three additional directories.
+
+Global install emits personal instructions, scoped instructions, agents, and
+skills under the active Copilot config root; profile `standard` and above adds
+hooks. Personal prompt files are not a documented Copilot CLI user surface and
+are not generated. `COPILOT_HOME` replaces `~/.copilot` for every generated
+Copilot surface, including `mcp-config.json`. Existing user files and user-added
+skill assets are preserved; reserved managed-path collisions and symlinked
+config roots are rejected instead of overwritten.
+
+Codex hook bundles are self-contained. Project `.codex/hooks.json` commands
+reference executable assets in `.codex/hooks/`; user `$CODEX_HOME/hooks.json`
+commands reference `$CODEX_HOME/ai-toolkit-hooks/`. Neither bundle depends on
+Claude's shared `~/.softspark/ai-toolkit/hooks/` installation.
 
 ## Codex Local Install Behavior
 
 `ai-toolkit install --local --editors codex` creates:
 
 - `AGENTS.md`
-- `.agents/rules/*.md`
 - `.agents/skills/*`
 - `.codex/hooks.json`
+- `.codex/hooks/*`
+- `.codex/agents/*.toml`
+- `.codex/config.toml` when project MCP servers are selected
 
 Native Codex-compatible skills are linked directly. Claude-oriented skills that
 depend on `Agent`, `Team*`, or `Task*` primitives are translated into generated
@@ -168,12 +198,13 @@ Codex wrappers so the project still receives the full skill catalog.
 
 `ai-toolkit plugin install --editor codex <pack>` additionally targets:
 
-- `~/.codex/AGENTS.md` (base instructions; pack rules are marker-injected here, not written as unread `~/.agents/rules/` files)
-- `~/.agents/skills/*`
-- `~/.codex/hooks.json`
+- `$CODEX_HOME/AGENTS.md` (pack rules are marker-injected here)
+- `$HOME/.agents/skills/*`
+- `$CODEX_HOME/hooks.json`
+- `$CODEX_HOME/ai-toolkit-hooks/plugin-<pack>-*`
 
-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
+This is an explicit, opt-in layer on top of the normal Codex user install.
+Runtime state is tracked in
 `~/.softspark/ai-toolkit/plugins.json` per target (`claude`, `codex`).
 
 ## MCP Local Sync Behavior
@@ -183,6 +214,7 @@ If `.mcp.json` exists in the current project, `ai-toolkit install --local` mirro
 - `.cursor/mcp.json` when `--editors cursor` is selected
 - `.github/mcp.json` when `--editors copilot` is selected
 - `.roo/mcp.json` when `--editors roo` is selected
+- `.codex/config.toml` when `--editors codex` 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/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.6.0"
+version: "1.7.0"
 created: "2026-03-27"
-last_updated: "2026-06-10"
+last_updated: "2026-07-14"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -426,7 +426,7 @@ First-match-wins per file. Built-in runners: `bats`, `pytest`, `vitest`, `jest`.
 | Script | `~/.softspark/ai-toolkit/hooks/search-tracker.sh` |
 | Fires | After any search-style tool call |
 
-**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Codex Stop enforcement also scans the recent `~/.codex/log/codex-tui.log` window for `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"`-style entries because Codex MCP tool calls may not fire the shared `PostToolUse` tracker. Together the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
+**Action:** Clears `~/.softspark/ai-toolkit/state/search-required-<session_id>.flag` (per-session, keyed by `session_id` from the hook stdin payload, falling back to `transcript_path` basename, then `default`). Pairs with `user-prompt-submit.sh` (sets the flag on long technical prompts only when a search provider is detected or strict mode is enabled) and `stop-search-check.sh` (blocks Stop if the calling session's flag is still set). Search provider detection parses actual MCP server names from `mcpServers`, `mcp_servers`, or `mcp` config blocks; hook matchers and permission allowlists do not count as providers. Codex Stop enforcement also scans the recent `$CODEX_HOME/log/codex-tui.log` window (default `~/.codex/log/codex-tui.log`) for `ToolCall: mcp__...__smart_query` and `tool.name="smart_query"`-style entries because Codex MCP tool calls may not fire the shared `PostToolUse` tracker. Together the hooks enforce the global CLAUDE.md GOLDEN RULE without breaking offline/no-RAG installs and without cross-session interference when multiple Claude Code windows run in parallel.
 
 Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -439,7 +439,7 @@ Non-blocking (exit 0). Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/stop-search-check.sh` |
 | Fires | When Claude finishes a response |
 
-**Action:** If `search-required-<session_id>.flag` for the calling session is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked. On Codex, where MCP search tools may not trigger the shared `PostToolUse` tracker, the hook also checks `~/.codex/log/codex-tui.log` for search tool calls after the flag timestamp before blocking. Flags are scoped by `session_id` from the hook stdin payload so a Stop in session B never consumes session A's flag (and vice versa). Stale per-session flags older than 60 minutes are GC'd on the next `SessionStart`.
+**Action:** If `search-required-<session_id>.flag` for the calling session is still present (no search tool ran during this turn) and a search provider is still detectable, emits `{"decision":"block","reason":"..."}` to continue the conversation with a search-first reminder. If no RAG/Web provider is detected, it clears the stale flag and exits 0, so offline/no-MCP users are not blocked. On Codex, where MCP search tools may not trigger the shared `PostToolUse` tracker, the hook also checks `$CODEX_HOME/log/codex-tui.log` (default `~/.codex/log/codex-tui.log`) for search tool calls after the flag timestamp before blocking. Flags are scoped by `session_id` from the hook stdin payload so a Stop in session B never consumes session A's flag (and vice versa). Stale per-session flags older than 60 minutes are GC'd on the next `SessionStart`.
 
 **Overrides:** `CLAUDE_SKIP_SEARCH_FIRST=1`, `AI_TOOLKIT_SEARCH_FIRST=off`, or `AI_TOOLKIT_SEARCH_FIRST=strict` to force enforcement. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -562,15 +562,15 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
     └── ConfigChange       → config-desync-guard.sh
 ```
 
-**Key design decisions:**
+**Claude Code design decisions:**
 - Scripts **copied** (not symlinked) — user can customize without breaking git
 - Hooks in `settings.json` (not `hooks.json`) — Claude Code only reads settings files
 - `_source: "ai-toolkit"` tag on every entry — allows idempotent merge/strip
-- Hooks are **global only** — `--local` does not install hooks into project settings
+- Claude hooks are **global only** — `--local` does not install them into project settings
 
-## Per-Editor Native Hooks (profile=full)
+## Per-Editor Native Hooks
 
-Beyond the global Claude Code hooks above, full-profile project installs emit native hook files for editors that support their own hook lifecycle. All reuse the same `~/.softspark/ai-toolkit/hooks/*.sh` scripts and the `_source: ai-toolkit` merge tag.
+Beyond the global Claude Code hooks above, editor profiles emit native hook files for runtimes that support their own lifecycle. The profile threshold and command/output contract are editor-specific; generators must not assume Claude event names or exit semantics.
 
 | Editor | File | Generator | Format |
 |--------|------|-----------|--------|
@@ -578,6 +578,42 @@ Beyond the global Claude Code hooks above, full-profile project installs emit na
 | Devin CLI | `.devin/hooks.v1.json` | `generate_devin_hooks.py` | Claude-compatible (the replacement for Cascade) |
 | Gemini CLI | `.gemini/settings.json` (hooks block) | `generate_gemini_hooks.py` | Gemini `BeforeTool`/`AfterTool` events |
 | Augment | `.augment/settings.json` (hooks block) | `generate_augment_hooks.py` | Claude-style events |
+| GitHub Copilot | `.github/hooks/ai-toolkit.json`; user `$COPILOT_HOME/hooks/ai-toolkit.json` | `generate_copilot_hooks.py` | GitHub version 1, camelCase events (profile ≥ `standard`) |
+| Codex CLI | `.codex/hooks.json`; user `$CODEX_HOME/hooks.json` | `generate_codex_hooks.py` | Native Codex schema, PascalCase events, command ownership markers |
+
+### Cursor hooks (`.cursor/hooks.json`)
+
+Cursor hooks follow the native [version-1 hooks contract](https://cursor.com/docs/hooks):
+
+- **Cloud:** cloud agents load only repository `.cursor/hooks.json`; they cannot read user-level `~/.cursor/hooks.json`. Project commands call the adjacent self-contained `.cursor/hooks/ai-toolkit/cursor_hook.py` runtime and contain no host `~/.softspark` dependency.
+- **Events:** the generator emits the complete documented Agent, Tab, and workspace lifecycle event set, including Cursor 3.11 conversation events `beforeSubmitPrompt`, `afterAgentResponse`, `afterAgentThought`, `subagentStart`, `subagentStop`, `preCompact`, and `stop`.
+- **Schema:** managed entries use only documented `command`, `timeout`, and `loop_limit` fields. Regeneration recognizes the runtime command as its ownership marker and removes legacy `_source: ai-toolkit` entries without emitting that non-standard key again.
+- **Safety:** destructive shell commands return Cursor's native `permission: deny` response and exit 2. A failed detected quality gate returns a bounded `followup_message`; `stop` and `subagentStop` declare `loop_limit: 5`, with an earlier three-failure circuit breaker in the runtime.
+- **Preservation:** unrelated top-level settings and user hook entries survive regeneration. Config and runtime replacement is staged and rejects symlinked destinations or a user-owned runtime collision.
+
+### GitHub Copilot hooks (`.github/hooks/ai-toolkit.json`)
+
+Copilot hooks follow GitHub's native [hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference), not Claude's settings schema:
+
+- **Locations:** repository hooks live in `.github/hooks/*.json`; user hooks live in `hooks/*.json` below `$COPILOT_HOME` or `~/.copilot`.
+- **File shape:** top-level `version: 1` plus a `hooks` object containing camelCase events.
+- **Runtime:** `ai-toolkit.json` calls the adjacent self-contained `ai-toolkit/copilot_hook.py`; local hooks do not depend on a package checkout or `~/.softspark` scripts.
+- **Native decisions:** `preToolUse` returns `permissionDecision`, `permissionDecisionReason`, and optional `modifiedArgs`. `agentStop` returns `decision` plus `reason`. Context events use `additionalContext`.
+- **Failure semantics:** the runtime uses GitHub's event-specific stdout and exit-code contracts. It does not reuse Claude's generic exit-2 blocking behavior.
+- **Loop safety:** a failing `agentStop` quality gate can block twice; the third consecutive failure opens the circuit so the session cannot loop forever.
+- **Ownership:** generated configs carry `AI_TOOLKIT_HOOK_OWNER=ai-toolkit`; unrelated hook files are not edited.
+
+### Codex CLI hooks (`.codex/hooks.json`)
+
+Codex hooks follow the native [Codex hooks contract](https://learn.chatgpt.com/docs/hooks):
+
+- **Locations:** repository hooks live in `.codex/hooks.json`; user hooks live in `$CODEX_HOME/hooks.json` (default `~/.codex/hooks.json`). Project hooks load only for a trusted `.codex` layer.
+- **Assets:** repository commands use self-contained `.codex/hooks/*`; user commands use `$CODEX_HOME/ai-toolkit-hooks/*`. They do not call Claude's `~/.softspark/ai-toolkit/hooks/` paths.
+- **Events:** Codex documents 10 events. ai-toolkit wires 9: `SessionStart`, `PreToolUse`, `PostToolUse`, `PermissionRequest`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `PreCompact`, and `Stop`. `PostCompact` is intentionally unwired.
+- **Compaction:** `PreCompact` runs `codex-pre-compact.sh`, a Codex-native reminder that refers to the active `AGENTS.md` chain, plan, and git state. It does not run Claude's `pre-compact.sh` or `pre-compact-save.sh` payload adapters.
+- **Ownership:** native JSON contains no private `_source` keys. Core handlers carry `AI_TOOLKIT_HOOK_OWNER=ai-toolkit` in their command; plugin and external handlers use exact source-specific command markers.
+- **Preservation:** generation replaces only toolkit-owned handlers and assets. Unrelated user handlers and plugin-owned handlers remain intact.
+- **Trust:** installation never bypasses trust. Review the active definitions with `/hooks` after install or update.
 
 ### Devin CLI hooks (`.devin/hooks.v1.json`)
 

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

@@ -2,10 +2,10 @@
 title: "AI Toolkit - MCP Editor Compatibility"
 category: reference
 service: ai-toolkit
-tags: [mcp, editors, compatibility, codex, cursor]
-version: "1.1.0"
+tags: [mcp, editors, compatibility, codex, cursor, antigravity]
+version: "1.3.0"
 created: "2026-04-12"
-last_updated: "2026-05-30"
+last_updated: "2026-07-14"
 description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
 ---
 
@@ -21,13 +21,14 @@ ai-toolkit keeps `.mcp.json` as the project-level canonical template format and
 |--------|-------|--------------------|------------------|
 | 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 |
+| GitHub Copilot | project + global | `.github/mcp.json`, `$COPILOT_HOME/mcp-config.json` (default `~/.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 |
+| Google Antigravity | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Preserves documented `command`, `serverUrl`, and `url` transports plus optional authentication, disablement, and tool-filter fields |
 | 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 |
-| Codex CLI | global | `~/.codex/config.toml` | Renders JSON templates as TOML `mcp_servers` tables |
+| Codex CLI | project + global | `.codex/config.toml`, `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) | Renders validated TOML `mcp_servers` tables inside a managed block while preserving unrelated bytes and comments |
 
 ## Unsupported for Automatic Install
 
@@ -36,13 +37,14 @@ These editors are still supported by ai-toolkit for rules and instructions, but
 | Editor | Reason |
 |--------|--------|
 | 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 antigravity --scope project context7 --target .
+ai-toolkit mcp install --editor codex --scope project context7 --target .
 ai-toolkit mcp install --editor codex context7
 ai-toolkit mcp remove github --editor cursor --scope project --target .
 ```
@@ -53,7 +55,26 @@ 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
+- `.agents/mcp_config.json` when `--editors antigravity` is selected
 - `.roo/mcp.json` when `--editors roo` is selected
+- `.codex/config.toml` when `--editors codex` is selected; project config is
+  active only after the repository `.codex` layer is trusted
+
+Codex project and user config preserve unrelated TOML text. ai-toolkit owns only
+the marker-bounded MCP block it generates. Invalid TOML, unsupported transport
+fields, and symlinked config roots are rejected without rewriting the file.
+Portable `type` metadata is translated only when it matches the Codex transport:
+`http` requires `url`, while `local` and `stdio` require `command`. The adapter
+removes that metadata from native TOML and rejects SSE, unknown types, and
+conflicting transport fields before writing.
+
+Antigravity project and global configs preserve unrelated top-level keys and
+user-owned servers. The adapter accepts both `serverUrl` and `url` for remote
+servers, as documented by the Antigravity 2.1.4 changelog, but rejects the
+unsupported legacy `httpUrl` field before any file in the transaction changes.
+
+`CODEX_HOME` and `COPILOT_HOME` replace their editors' default user config
+roots. They never relocate project files.
 
 Global-only clients are configured explicitly via `ai-toolkit mcp install --editor ...`.
 

package/kb/reference/mcp-templates.md

@@ -3,9 +3,9 @@ title: "MCP Server Templates"
 category: reference
 service: ai-toolkit
 tags: [mcp, templates, servers, configuration, editors, inject-mcp, external-templates]
-version: "1.2.0"
+version: "1.4.0"
 created: "2026-04-07"
-last_updated: "2026-05-12"
+last_updated: "2026-07-14"
 description: "Reference for 26 built-in MCP server templates, external template injection via inject-mcp, and native editor MCP installation support."
 ---
 
@@ -26,6 +26,8 @@ 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 install --editor cursor --scope project github --target .
+ai-toolkit mcp install --editor antigravity --scope project context7 --target .
+ai-toolkit mcp install --editor codex --scope project context7 --target .
 ai-toolkit mcp install --editor codex context7
 ai-toolkit mcp remove <name>      # Remove from .mcp.json or native editor config
 ```
@@ -35,7 +37,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, Roo Code, Windsurf, Cline, Augment
+- JSON clients with `mcpServers` blocks: Claude Code, Cursor, Gemini CLI, Google Antigravity, Roo Code, Windsurf, Cline, Augment
 - JSON clients with additional transport metadata: GitHub Copilot
 - TOML clients: Codex CLI (`[mcp_servers.<name>]`)
 
@@ -47,15 +49,19 @@ When `install` runs with `--scope project`, ai-toolkit also updates the project'
 |--------|-------|--------------------|-------|
 | `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 |
+| `copilot` | project + global | `.github/mcp.json`, `$COPILOT_HOME/mcp-config.json` (default `~/.copilot/mcp-config.json`) | Adds `type` and `tools: ["*"]` automatically |
 | `gemini` | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Uses Gemini CLI `mcpServers` format |
+| `antigravity` | project + global | `.agents/mcp_config.json`, `~/.gemini/config/mcp_config.json` | Preserves `url` or `serverUrl` remote transports and Antigravity authentication/tool-control fields |
 | `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 |
+| `codex` | project + global | `.codex/config.toml`, `$CODEX_HOME/config.toml` (default `~/.codex/config.toml`) | Validated TOML `mcp_servers` tables in a marker-bounded managed block; unrelated TOML/comments preserved |
 
-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`).
+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`, `antigravity`, `roo`, `codex`). Codex
+loads `.codex/config.toml` only for trusted project layers.
 
 ## Template List
 

package/kb/reference/opencode-compatibility.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - opencode Compatibility"
 category: reference
 service: ai-toolkit
 tags: [opencode, compatibility, install, skills, hooks, mcp, plugins]
-version: "1.0.0"
+version: "1.0.1"
 created: "2026-04-16"
-last_updated: "2026-04-16"
+last_updated: "2026-07-14"
 description: "Reference for how ai-toolkit integrates with opencode — AGENTS.md, subagents, slash commands, JS plugin hook bridge, and MCP merge into opencode.json."
 ---
 
@@ -44,16 +44,16 @@ Files land directly under `~/.config/opencode/` (no `.opencode/` nesting) becaus
 | Feature            | Claude Code | Codex CLI       | opencode                                  |
 |--------------------|-------------|-----------------|-------------------------------------------|
 | Rules file         | `CLAUDE.md` | `AGENTS.md`     | `AGENTS.md` + `CLAUDE.md` fallback        |
-| Subagents          | Yes         | No              | Yes (`mode: subagent`)                    |
+| Subagents          | Yes         | Yes (`.codex/agents/*.toml`) | Yes (`mode: subagent`)          |
 | Slash commands     | Skills      | Adapted skills  | Native commands with frontmatter          |
 | MCP                | Yes         | Yes             | Yes (`opencode.json`)                     |
 | Lifecycle hooks    | JSON config | `.codex/hooks`  | JS/TS plugins (~30+ events)               |
-| Global config dir  | `~/.claude` | `~/.codex`      | `~/.config/opencode`                      |
-| Project config dir | `.claude`   | `.agents`       | `.opencode`                               |
+| Global config dir  | `~/.claude` | `$CODEX_HOME` (default `~/.codex`) | `~/.config/opencode`       |
+| Project config dir | `.claude`   | `.codex` + `.agents/skills` | `.opencode`                    |
 
 ## Shared AGENTS.md
 
-opencode and Codex CLI both read `AGENTS.md`. The toolkit emits two distinct marker-bounded sections in a single file, so installing both editors does not clobber either. The Codex section is produced by `generate_codex.py`; the opencode section is produced by `generate_opencode.py`. Both sections reuse `codex_skill_adapter.py` because both editors lack Claude-only orchestration primitives (`Agent`, `TeamCreate`, `TaskCreate`).
+opencode and Codex CLI both read `AGENTS.md`. The toolkit emits two distinct marker-bounded sections in a single file, so installing both editors does not clobber either. The Codex section is produced by `generate_codex.py`; the opencode section is produced by `generate_opencode.py`. OpenCode commands use a platform-specific portable renderer for Claude-only orchestration primitives, so generated content uses OpenCode-native wording.
 
 ## Subagent Translation Model
 
@@ -73,6 +73,12 @@ Only user-invocable skills (`user-invocable: true` or no `disable-model-invocati
 
 Each command file carries the prompt in its markdown body (built from the SKILL.md body). opencode reads the body as the prompt; the `template` field is JSON-config-only and is ignored in `.md` command files.
 
+OpenCode natively interpolates `$ARGUMENTS` and positional placeholders `$1`
+through `$9` in command bodies. The renderer preserves those placeholders for
+OpenCode while translating Claude-only skill-directory variables and runtime
+APIs. Codex output uses a separate renderer and converts prompt placeholders to
+durable user-input prose.
+
 ## Hook Bridge (JS Plugin)
 
 `.opencode/plugins/ai-toolkit-hooks.js` is a single-file plugin that maps opencode events to the shared Bash hooks in `~/.softspark/ai-toolkit/hooks/`:
@@ -129,7 +135,7 @@ User-authored opencode files and user-authored `opencode.json` keys are never de
 ## Behavioral Limits
 
 - opencode does not expose the full Claude hook event surface; only the events in the mapping table above are bridged. Claude-only events (`TaskCompleted`, `TeammateIdle`, `SubagentStart`, `SubagentStop`, `PreCompact`) are silently skipped.
-- Multi-agent orchestration skills (`/orchestrate`, `/workflow`, `/swarm`, `/subagent-development`) run through the Codex adaptation layer — they use opencode subagents and explicit file ownership instead of Claude's `Agent`/`TaskCreate` primitives.
+- Multi-agent orchestration skills (`/orchestrate`, `/workflow`, `/swarm`, `/subagent-development`) run through the OpenCode renderer and use OpenCode-native subagents with explicit file ownership.
 
 ## Verification
 

package/kb/reference/plugin-pack-conventions.md

@@ -3,9 +3,9 @@ title: "Plugin Pack Conventions"
 category: reference
 service: ai-toolkit
 tags: [plugins, plugin-packs, conventions, manifests, hooks, policy-packs]
-version: "1.0.0"
+version: "1.1.0"
 created: "2026-03-28"
-last_updated: "2026-04-13"
+last_updated: "2026-07-14"
 description: "Conventions for experimental ai-toolkit plugin packs, policy packs, hook packs, and plugin-creator scaffolding across Claude Code and Codex runtimes."
 ---
 
@@ -87,11 +87,11 @@ ai-toolkit plugin status --editor all              # show installed packs with r
 ### What `plugin install` Does
 
 1. **Parses** `--editor claude|codex|all` (default: `claude`)
-2. **Copies** plugin-specific hooks to `~/.softspark/ai-toolkit/hooks/plugin-<pack>-<hook>.sh`
-3. **Copies** plugin-specific scripts to `~/.softspark/ai-toolkit/plugin-scripts/<pack>/`
+2. **Copies** plugin-specific hooks to runtime-owned storage: Claude uses `~/.softspark/ai-toolkit/hooks/plugin-<pack>-<hook>.sh`; Codex uses `$CODEX_HOME/ai-toolkit-hooks/plugin-<pack>-<hook>.sh`
+3. **Copies** shared plugin scripts to `~/.softspark/ai-toolkit/plugin-scripts/<pack>/`
 4. **Runs** init scripts if present (e.g. `init_db.py` for memory-pack — safe to re-run, preserves data)
 5. **Claude Code target**: links missing agents/skills into `~/.claude/`, injects plugin-local rules into `~/.claude/CLAUDE.md`, and merges plugin hook entries into `~/.claude/settings.json`
-6. **Codex target**: bootstraps global Codex assets in `HOME` (`~/AGENTS.md`, `~/.agents/skills`, `~/.agents/rules`, `~/.codex/hooks.json`) and then layers plugin-specific rules/hooks on top
+6. **Codex target**: bootstraps `$CODEX_HOME/AGENTS.md`, `$HOME/.agents/skills`, `$CODEX_HOME/hooks.json`, and self-contained `$CODEX_HOME/ai-toolkit-hooks`, then layers plugin-specific rules and hooks on top; it does not write `~/AGENTS.md` or `.agents/rules/`
 7. **Records** installed state per runtime in `~/.softspark/ai-toolkit/plugins.json`
 
 ### What `plugin update` Does
@@ -111,8 +111,8 @@ ai-toolkit plugin status --editor all              # show installed packs with r
 ### What `plugin remove` Does
 
 1. **Claude Code target**: strips plugin hook entries from `~/.claude/settings.json` and removes plugin-local rule sections from `~/.claude/CLAUDE.md`
-2. **Codex target**: strips plugin hook entries from `~/.codex/hooks.json` and removes `~/.agents/rules/plugin-<pack>-*.md`
-3. **Shared assets** (`~/.softspark/ai-toolkit/hooks/plugin-*`, `plugin-scripts/<pack>/`) are removed only when no remaining runtime still uses that pack
+2. **Codex target**: strips only command handlers carrying the exact `AI_TOOLKIT_HOOK_OWNER=ai-toolkit-plugin-<pack>` marker from `$CODEX_HOME/hooks.json`, removes owned `$CODEX_HOME/ai-toolkit-hooks/plugin-<pack>-*` assets, and removes the pack's marker-bounded sections from `$CODEX_HOME/AGENTS.md`
+3. **Claude/shared assets** (`~/.softspark/ai-toolkit/hooks/plugin-*`, `plugin-scripts/<pack>/`) are removed only when no remaining runtime still uses that pack
 4. **Updates** `plugins.json` state per runtime
 5. **Leaves** core agents/skills untouched (they belong to the base install)
 6. **Leaves** plugin data intact (e.g. `memory.db` — use `clean` to prune)

package/kb/reference/skills-catalog.md

@@ -77,7 +77,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **cve-scan** | `/cve-scan` | medium | Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, ruby, dart) |
 | **docs** | `/docs` | high | Generate/update docs: README, API docs, architecture notes, changelogs (Tier 1 — single agent) |
 | **explain** | `/explain` | medium | Explain architecture of a file/module using Mermaid diagrams |
-| **orchestrate** | `/orchestrate` | max | Custom multi-agent parallelism — Tier 3, native in Claude, Codex-adapted to `spawn_agent` workflows |
+| **orchestrate** | `/orchestrate` | max | Custom multi-agent parallelism — Tier 3, native in Claude, Codex-adapted with semantic subagent guidance |
 | **swarm** | `/swarm` | max | Massive parallelism: map-reduce, consensus, relay — Tier 3 |
 | **workflow** | `/workflow` | max | 15 predefined multi-agent workflow types — Tier 2, Codex-adapted to native subagent orchestration |
 | **instinct-review** | `/instinct-review` | low | Review, curate, and manage learned instincts from past sessions |
@@ -257,8 +257,8 @@ Codex CLI receives the full skill catalog during `ai-toolkit install --local --e
 Claude Chat/Desktop/Cowork receives this same catalog through `ai-toolkit claude-app export`. The export also adds an app-only `ai-toolkit-rules` skill because the Claude app does not read Claude Code's `CLAUDE.md` or `.claude/rules/` surfaces.
 
 - Native Codex-compatible skills are symlinked directly into `.agents/skills/`
-- Claude-oriented orchestration skills are generated as Codex wrappers
-- Adapted wrappers translate `Agent`, `Team*`, and `Task*` guidance to `spawn_agent`, `send_input`, `wait_agent`, `close_agent`, and `update_plan`
+- Skills with Claude-only tools, placeholders, path variables, or orchestration APIs are generated as Codex wrappers
+- Adapted wrappers describe subagent control, waiting, and planning as durable current-client semantics without embedding guessed tool signatures
 
 Common adapted skills: