@softspark/ai-toolkit 4.14.0 → 4.15.0

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.8.0"
+version: "1.10.0"
 created: "2026-04-23"
-last_updated: "2026-07-10"
+last_updated: "2026-07-14"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code, Claude Chat/Cowork, and 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -68,9 +68,10 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
 | Config paths | `.cursorrules` (**legacy** — no longer in cursor.com/docs/rules; deprecated ~0.43–0.45 in favor of `.cursor/rules/*.mdc`, still read, no removal deadline; we keep emitting for back-compat), `.cursor/rules/*.mdc` (plain `.md` files in `.cursor/rules/` are **ignored** by the rules system), `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/hooks.json`, `~/.cursor/hooks.json` (user-level hooks scope; enterprise system paths + dashboard team hooks not adopted, class C), `.cursor/skills/*/SKILL.md`, `~/.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `~/.cursor/agents/*.md` |
 | Compat read paths | skills: `.agents/skills/`, `~/.agents/skills/`, `.claude/skills/`, `~/.claude/skills/`, `.codex/skills/`, `~/.codex/skills/`; subagents: `.claude/agents/`, `~/.claude/agents/`, `.codex/agents/`, `~/.codex/agents/` (`.cursor/` wins on name conflicts) |
-| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (profile=full local **and** global `~/.cursor/hooks.json`), `scripts/generate_cursor_agents.py` (profile=full), `scripts/generate_cursor_skills.py` (profile=full pointer) |
+| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py`, `scripts/generate_cursor_hooks.py` (complete version-1 event set plus self-contained `.cursor/hooks/ai-toolkit/cursor_hook.py`; profile=full local **and** global `~/.cursor/hooks.json`), `scripts/generate_cursor_agents.py` (profile=full), `scripts/generate_cursor_skills.py` (profile=full pointer) |
 | Global install | Cursor is in `GLOBAL_CAPABLE_EDITORS` for **hooks only**: `ai-toolkit install --editors cursor` writes `~/.cursor/hooks.json` (profile ≥ standard). RULES stay project-local (Cursor's only global rules surface is the Settings UI). |
 | Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
+| Hook compatibility | Cursor 3.11 project hooks run locally and in cloud agents from repository `.cursor/hooks.json`; cloud VMs do not load `~/.cursor/hooks.json`. The generated project manifest uses only documented command-entry keys, calls a repo-relative runtime, covers conversation hooks including `afterAgentResponse` and `afterAgentThought`, preserves user entries, and caps `stop`/`subagentStop` follow-up loops at 5. |
 
 ### Windsurf
 
@@ -96,12 +97,13 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `github-copilot` |
 | Docs | https://docs.github.com/en/copilot |
 | Release notes | https://github.blog/changelog/label/copilot/ |
-| Config paths | **Repo (`.github/`):** `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/prompts/*.prompt.md`, `AGENTS.md`, `.github/hooks/*.json`. **Copilot CLI user-level (`~/.copilot/`, `COPILOT_HOME` override):** `~/.copilot/copilot-instructions.md`, `~/.copilot/instructions/*.instructions.md`, `~/.copilot/agents/*.agent.md`, `~/.copilot/skills/<name>/SKILL.md`, `~/.copilot/hooks/`, `~/.copilot/settings.json`, `~/.copilot/mcp-config.json` |
-| Compat read paths | skills: Copilot CLI reads personal `~/.copilot/skills` and `~/.agents/skills` (the latter populated by our codex/roo global installs) and project `.github/skills`, `.claude/skills`, `.agents/skills` — so toolkit skills are already Copilot-visible. (Note: since CLI 1.0.61 a session using `COPILOT_HOME`/`--config-dir` stops reading `~/.agents/skills`.) |
-| Our generators | `scripts/generate_copilot.py` (repo `.github/` and, with `config_root=~/.copilot`, global CLI instructions) |
-| Global install | Copilot is in `GLOBAL_CAPABLE_EDITORS`: `ai-toolkit install --editors copilot` writes `~/.copilot/copilot-instructions.md` + `~/.copilot/instructions/ai-toolkit-*.instructions.md` (read by Copilot CLI). VS Code Copilot uses profile-level locations and GitHub.com uses repo files, so the project `.github/` emission stays. |
+| Native docs | [Hooks reference](https://docs.github.com/en/copilot/reference/hooks-reference), [skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills), [CLI config directory](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-config-dir-reference) |
+| Config paths | **Repo (`.github/`):** `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/prompts/*.prompt.md`, `.github/agents/*.agent.md`, `.github/skills/<name>/SKILL.md`, `.github/hooks/*.json`, `AGENTS.md`. **Copilot CLI user-level (`~/.copilot/`, `COPILOT_HOME` override):** `copilot-instructions.md`, `instructions/*.instructions.md`, `agents/*.agent.md`, `skills/<name>/SKILL.md`, `hooks/*.json`, `settings.json`, `mcp-config.json` below the active config root. |
+| Compat read paths | Copilot also discovers project `.claude/skills` and `.agents/skills`, and personal `~/.agents/skills`. ai-toolkit nevertheless materializes self-contained native skills under `.github/skills` and the active Copilot config root so assets and helper scripts remain available and `COPILOT_HOME` sessions do not depend on fallback discovery. |
+| Our generators | `scripts/generate_copilot.py` (instructions, prompts, agents, and portable skill directories), `scripts/generate_copilot_hooks.py` (native version-1 hook config plus self-contained runtime) |
+| Global install | `ai-toolkit install --editors copilot` writes instructions, agents, skills, and, for profile ≥ `standard`, native hooks below `$COPILOT_HOME` when set or `~/.copilot` otherwise. VS Code Copilot and GitHub.com use repo `.github/` files, so local emission remains required. |
 | Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, `AGENTS.md`, MCP, skills, CLI hooks, `~/.copilot/` |
-| Tier notes | Custom agents (`.github/agents/*.agent.md`) and repo-level MCP config are Pro/Pro+/Business/Enterprise only and intentionally not integrated (class C per ecosystem-sync SOP). Copilot code review reads the nearest `AGENTS.md` automatically since the 2026-06-18 GA (all tiers); `ai-toolkit install --local --editors copilot` injects a `TOOLKIT:copilot-agents` section generated from `generate_agents_md.py` without clobbering Codex/opencode sections in the same file. The 4000-char cap on `copilot-instructions.md` / `*.instructions.md` was also removed (2026-06-12). |
+| Compatibility notes | Custom agents use native `.agent.md` files with `name` and `description`; `tools` is omitted instead of guessing editor-specific aliases. Prompt and skill bodies remove Claude-only interpolation and delegation APIs. Hooks use the GitHub version-1 schema, camelCase event names, native decision payloads, and a repository/config-root-contained Python runtime instead of Claude hook scripts. Project MCP remains owned by the editor MCP sync path. Copilot code review also reads the nearest `AGENTS.md`; local install keeps its generated section separate from Codex/OpenCode sections. |
 
 ### Gemini CLI
 
@@ -178,27 +180,27 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `google-antigravity` |
 | Docs | https://antigravity.google/docs (JavaScript SPA — use bundle strings / sitemap to verify) |
 | Changelog | https://antigravity.google/changelog (SPA; changelog entries embedded in main-*.js) |
-| Config paths | `.agents/rules/*.md`, `.agents/workflows/*.md` (plural is the Antigravity 2.0 default; singular `.agent/rules`, `.agent/workflows` still read as fallback), `.agent/skills/*/SKILL.md` (IDE), `.agents/skills/*/SKILL.md` (CLI), `.agents/hooks.json` (CLI hooks), `.agents/mcp_config.json` (CLI MCP), `AGENTS.md`, `GEMINI.md` |
+| Config paths | `.agents/rules/*.md`, `.agents/workflows/*.md` (plural is the Antigravity 2.0 default; singular `.agent/rules`, `.agent/workflows` still read as fallback), `.agent/skills/*/SKILL.md` (IDE), `.agents/skills/*/SKILL.md` (CLI), `.agents/hooks.json` (CLI hooks), `.agents/mcp_config.json` (workspace MCP), `AGENTS.md`, `GEMINI.md` |
 | Global config paths | Skills: `~/.gemini/config/skills/*/SKILL.md` (shared across all Antigravity products) and `~/.gemini/antigravity-cli/skills/*/SKILL.md` (CLI-private) — both documented in the official Skills codelab. MCP: `~/.gemini/config/mcp_config.json` (shared global, resolved by CLI v1.0.14; the `~/.gemini/antigravity-cli/mcp_config.json` path is legacy). Rules: `~/.gemini/GEMINI.md` (dual-owner with Gemini CLI — Antigravity's IDE "+ Global" writes the same file; gemini-cli#16058 closed "not planned"). Hooks: `~/.gemini/config/hooks.json` (shared, since CLI v1.0.8). |
-| Our generators | `scripts/generate_antigravity.py` (rules + workflows + skill pointer dual-emitted to `.agent/skills/` and `.agents/skills/`; `generate_global()` writes the pointer to the two HOME skill dirs) |
-| Global install | `ai-toolkit install --editors antigravity` writes the skill pointer to `~/.gemini/config/skills/` and `~/.gemini/antigravity-cli/skills/`. Rules stay project-local (no mergeable global rules file beyond the Gemini-CLI-shared `~/.gemini/GEMINI.md`, covered by `--editors gemini`). |
+| Our generators | `scripts/generate_antigravity.py` (rules + workflows + skill pointer dual-emitted to `.agent/skills/` and `.agents/skills/`; `generate_global()` writes the pointer to the two HOME skill dirs). Native MCP project/global merge and removal are provided by `scripts/mcp_editors.py`. |
+| Global install | `ai-toolkit install --editors antigravity` writes the skill pointer to `~/.gemini/config/skills/` and `~/.gemini/antigravity-cli/skills/`. Rules stay project-local (no mergeable global rules file beyond the Gemini-CLI-shared `~/.gemini/GEMINI.md`, covered by `--editors gemini`). `ai-toolkit mcp install --editor antigravity <template>` writes the global MCP config; add `--scope project --target <repo>` for `.agents/mcp_config.json`. |
 | Tracked capabilities | Antigravity, agent manager, artifacts, MCP, workflows, rules, skills, hooks, `AGENTS.md`, `GEMINI.md`, agent permissions, global skills, `~/.gemini/config/mcp_config.json` |
-| CLI notes | Antigravity CLI (GA 2026-05-19; latest CLI v1.0.14 2026-06-30, IDE 2.2.1). Hooks are IDE + CLI (`.agents/hooks.json` workspace, `~/.gemini/config/hooks.json` global; event set `PreToolUse`/`PostToolUse`/`PreInvocation`/`PostInvocation`/`Stop` — `PreInvocation`/`PostInvocation` have no Claude equivalent; shell tool is `run_command` with args at `.toolCall.args.CommandLine`). MCP: `url` is natively supported since CLI v1.0.5 (registry's old "url/httpUrl fail silently" note is stale); `serverUrl` works everywhere incl. IDE. **MCP adapter + a `generate_antigravity_hooks.py` are not yet shipped** (backlog). |
-| Doc access note | Docs are JS-SPA — verify via `main-*.js` bundle strings or community skill repos. `WebFetch` returns an empty shell. The sitemap.xml is stale (omits the `cli-*` doc pages), so sitemap-based monitoring misses CLI doc additions. |
+| CLI notes | Antigravity CLI (GA 2026-05-19; latest CLI v1.0.14 2026-06-30, IDE 2.2.1). Hooks are IDE + CLI (`.agents/hooks.json` workspace, `~/.gemini/config/hooks.json` global; event set `PreToolUse`/`PostToolUse`/`PreInvocation`/`PostInvocation`/`Stop` — `PreInvocation`/`PostInvocation` have no Claude equivalent; shell tool is `run_command` with args at `.toolCall.args.CommandLine`). MCP: the official 2.1.4 changelog (2026-06-11) confirms that `url` is accepted alongside `serverUrl`; `httpUrl` is not documented and the adapter rejects it. The native adapter preserves documented `args`, `env`, `cwd`, `headers`, `authProviderType`, `oauth`, `disabled`, and `disabledTools` fields. A `generate_antigravity_hooks.py` remains backlog. |
+| Doc access note | Docs are a JavaScript SPA, but the official search index exposes the current MCP guide and changelog text. Verify changelog claims against the dated official entry because the MCP guide's warning can lag schema releases. |
 
 ### Codex CLI
 
 | Field | Value |
 |-------|-------|
 | ID | `codex-cli` |
-| Docs | https://developers.openai.com/codex (live docs site; config pages split into `/codex/config-basic`, `/codex/config-reference`, `/codex/config-advanced` plus `/codex/hooks`, `/codex/skills`, `/codex/guides/agents-md`; latest verified local/release: codex-cli 0.144.1, 2026-07-10) |
+| Docs | https://learn.chatgpt.com/docs/codex/cli (official Codex CLI documentation; the previous `https://developers.openai.com/codex` endpoint now redirects to the generic ChatGPT Learn overview; latest verified local/npm release: codex-cli 0.144.4, 2026-07-14) |
 | Release notes | https://github.com/openai/codex/releases |
-| Config paths | **Instructions:** project `AGENTS.md` (root→cwd chain, closest wins) and global `~/.codex/AGENTS.md` (`$CODEX_HOME/AGENTS.md`; `~/.codex/AGENTS.override.md` takes precedence). NOTE: `~/AGENTS.md` is NOT a global-instruction surface — Codex only reads it if a session's cwd is exactly `$HOME`. Plus `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `~/.codex/hooks.json`, `.codex/config.toml` (project layers, root→cwd, closest wins, trusted projects only), `~/.codex/config.toml`. |
-| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
+| Config paths | **Instructions:** project `AGENTS.md` (root→cwd chain, closest wins) and global `~/.codex/AGENTS.md` (`$CODEX_HOME/AGENTS.md`; `~/.codex/AGENTS.override.md` takes precedence). NOTE: `~/AGENTS.md` is NOT a global-instruction surface — Codex only reads it if a session's cwd is exactly `$HOME`. Plus `.agents/skills/*/SKILL.md`, `.codex/agents/*.toml`, `~/.codex/agents/*.toml`, `.codex/hooks.json`, `~/.codex/hooks.json`, `.codex/config.toml` (project layers, root→cwd, closest wins, trusted projects only), `~/.codex/config.toml`. |
+| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_agents.py` (native custom-agent TOML), `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | Rules delivery | Universal coding rules are inlined into `AGENTS.md` (Codex reads instructions only from AGENTS.md, not `.agents/rules/`); language rules ship as `<lang>-rules` skills under `.agents/skills/`. Global install writes `~/.codex/AGENTS.md` (not `~/AGENTS.md`, which Codex never loads globally); plugin-pack rules are marker-injected into the same file. `project_doc_max_bytes` default is 32 KiB and Codex silently truncates AGENTS.md past that (see codex-cli-compatibility.md). |
 | Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire 9 of these to shared toolkit hook scripts (via `generate_codex_hooks.py` AND `inject-hook` propagation, kept in sync), mirroring the Claude Code mapping in `app/hooks.json`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
 | Tracked handler types | `command` (emitted by default; the only handler Codex actually runs). `prompt` and `agent` are parsed by Codex but NOT yet executed, so hand-authored handlers of those types are inert. |
-| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
+| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path), `.codex/agents/*.toml` (native custom agents) |
 | Version probe | `codex --version` |
 
 ### opencode

package/kb/reference/windows-support.md

@@ -2,10 +2,10 @@
 title: "Windows Support"
 category: reference
 service: ai-toolkit
-tags: [windows, wsl, install, dependencies, hooks]
+tags: [windows, wsl, install, uninstall, dependencies, hooks, security]
 created: "2026-04-24"
-last_updated: "2026-04-24"
-description: "Windows support model for ai-toolkit: WSL, Git Bash, dependency detection, and hook runtime constraints."
+last_updated: "2026-07-14"
+description: "Windows support model for ai-toolkit: WSL, Git Bash, dependency detection, hooks, and fail-closed managed mutations."
 ---
 
 # Windows Support
@@ -39,6 +39,29 @@ ai-toolkit hooks are Bash scripts. On Windows, use WSL or Git Bash so Claude Cod
 
 Cross-platform hooks should keep the Bash entrypoint small and delegate complex work to Python or Node when Windows behavior diverges.
 
+## Managed Mutation Safety
+
+Managed cleanup by `ai-toolkit uninstall`, external hook injection/removal, and
+native Codex hook generation require POSIX `dir_fd` and `O_NOFOLLOW` support.
+These primitives are the platform prerequisite for pinning directories between
+a trusted configuration root and the file being changed, so a symlink swap
+cannot redirect a mutation outside that root. Absolute trusted roots are opened
+component by component from a stable filesystem-root descriptor; all target
+parsing, mutation, and rollback then use the pinned descriptors.
+
+- **WSL:** managed cleanup is supported.
+- **Native Windows Python, including invocation from Git Bash:** managed cleanup
+  is unavailable because Windows CPython does not expose the required POSIX
+  traversal primitives. Git Bash provides a shell, but it does not add those
+  primitives to Python.
+
+On an unsupported runtime, help, dry-run modes where available, component
+discovery, validation, cancellation, and other read-only operations remain
+available. A requested mutation exits non-zero before its transaction starts
+and reports `No files were changed`. Run the command from WSL to remove managed
+customizations, inject or remove external hooks, and generate/update native
+Codex hooks safely.
+
 ## Verification
 
 ```bash