@softspark/ai-toolkit 4.11.0 → 4.12.0

package/AGENTS.md

@@ -653,138 +653,3 @@ Default response mode is **concise**. The `brand-voice` skill (when present) aut
 * Cite as `path:line` — instead of paragraphs describing where things live.
 * Escalate to verbose only for: architecture / RFC / ADR / trade-off documents, or when the user asks for detail.
 <!-- TOOLKIT:ai-toolkit END -->
-
-<!-- TOOLKIT:jira-mcp START -->
-<!-- Auto-injected by ai-toolkit. Re-run to update. -->
-
-# Jira MCP Server
-
-Tools: `sync_tasks`, `read_cached_tasks`, `update_task_status`, `update_task`, `add_task_comment`, `delete_task`, `delete_comment`, `reassign_task`, `get_task_statuses`, `get_task_details`, `get_project_language`, `log_task_time`, `get_task_time_tracking`, `list_comment_templates`, `add_templated_comment`, `list_task_templates`, `create_task`, `create_monthly_tasks`, `search_tasks`
-
-## Key Rules
-
-- **Always `sync_tasks` first** before reading, because the cache may be stale.
-- **Language first:** before writing ANY comment, description, or task content, call `get_project_language(project_key)` or check the `language` field in `get_task_details` response. Write ALL content in the project's configured language. Never assume Polish or English. Always check first.
-- **Time format:** `"2h 30m"`, using hours and minutes only, never days.
-- **Status changes:** call `get_task_statuses` first to check valid transitions.
-- **Multi-instance:** project key determines which Jira instance is used (mapped in config.json).
-- **Comments are ADF:** `add_task_comment` converts markdown to ADF (Atlassian Document Format) automatically.
-- **Delete guard:** `delete_task` is allowed only for the task creator, and `delete_comment` is allowed only for the comment author. Both require explicit `user_approved=true`.
-- **Templates:** use `list_comment_templates` to discover available templates, then `add_templated_comment` with `template_id` + `variables`.
-
-## Writing Style
-
-- **Write like a real team member:** use plain, direct language that sounds like an engineer writing to another human, not like polished AI copy or marketing text.
-- **No em dash and no double-hyphen separator in prose:** do not use those punctuation patterns in generated comments, descriptions, docs, or summaries. Use commas, periods, or parentheses instead.
-- **Avoid stock AI phrases:** do not use phrases like "worth noting", "it is important to understand", "in today's dynamic environment", "overall", "in conclusion", or similar generic filler.
-- **Prefer concrete wording:** use specific facts, actions, examples, and decisions instead of abstract claims or padded qualifiers.
-- **Avoid repetitive rhythm:** do not make every sentence or bullet sound structurally identical. Vary sentence length and openings when writing longer text.
-- **Keep summaries short:** do not add forced wrap-up paragraphs unless the user explicitly asks for a summary.
-- **Use a workmanlike tone:** prefer a slightly rough, practical style over text that sounds overly smooth, symmetrical, or "LLM-clean".
-
-## Workflow
-
-1. `sync_tasks(jql="assignee=currentUser() AND status!=Done")` to fetch fresh data
-2. `read_cached_tasks()` to work offline
-3. `get_task_details(task_key="PROJ-123")` for a deep dive into description and comments as markdown
-4. `update_task_status(...)` / `add_task_comment(...)` / `log_task_time(...)` to mutate data
-
-## Comment Templates (built-in)
-
-| ID | Use for |
-|----|---------|
-| `status-update` | Progress report with completed/next/blockers |
-| `blocker-notification` | Escalate blocking issue |
-| `handoff-transition` | Task handoff between people |
-| `review-request` | Request code review |
-| `sprint-update` | Sprint progress report |
-| `bug-report` | Structured bug report |
-| `deployment-note` | Deployment documentation |
-| `time-log-summary` | Time logging with description |
-
-## CLI Commands
-
-| Command | Description |
-|---------|-------------|
-| `jira-mcp` | Start MCP server (default) |
-| `jira-mcp serve` | Start MCP server (explicit) |
-| `jira-mcp create <path>` | Create tasks from config file (dry-run by default) |
-| `jira-mcp create-monthly` | Create monthly admin tasks from built-in templates |
-| `jira-mcp template add <type> <path>` | Install a template override from a local markdown file |
-| `jira-mcp template list [type]` | List active comment/task templates |
-| `jira-mcp template show <type> <id>` | Show the active template file content |
-| `jira-mcp template remove <type> <id>` | Remove a user-installed template override |
-| `jira-mcp config init` | Initialize global config (~/.softspark/jira-mcp/) |
-| `jira-mcp config add-project <key> <url>` | Add Jira project mapping |
-| `jira-mcp config remove-project <key>` | Remove a project |
-| `jira-mcp config list-projects` | Show configured projects with language |
-| `jira-mcp config set-credentials` | Set API credentials |
-| `jira-mcp config set-default <key>` | Set default project |
-| `jira-mcp config set-language <lang>` | Set global default language |
-| `jira-mcp config set-project-language <key> <lang>` | Set language for a specific project |
-| `jira-mcp cache sync-workflows` | Cache status transitions |
-| `jira-mcp cache sync-users` | Cache user list for reassignment |
-| `jira-mcp cache list-workflows` | Show cached workflows |
-| `jira-mcp cache list-users` | Show cached users |
-
-## Architecture
-
-Four layers. Each depends only on layers below.
-
-1. **Types & Config** (`config/`, `errors/`, `*/types.ts`), pure data with zero runtime deps
-2. **Infrastructure** (`connector/`, `cache/`, `adf/`, `templates/`), I/O and external APIs
-3. **Business Logic** (`operations/`, `bulk/`), orchestrating infrastructure
-4. **Entry Points** (`tools/`, `cli/`, `server.ts`), thin dispatchers
-
-## Coding Conventions
-
-- **Strict TypeScript**: `strict: true`, NO `any`, `readonly` interfaces, `import type`, `.js` imports
-- **Zod schemas** for all external data: `type Foo = z.infer<typeof FooSchema>`
-- **Error classes**: extend `JiraMcpError` with `code` property
-- **ADF round-trip**: `markdownToAdf()` for writes and `adfToMarkdown()` for reads. NEVER throw.
-- **InstancePool**: singleton, lazy connectors, dedup by URL
-- **Dual-write**: after Jira mutation, update local cache, return API result
-- **Dry-run default**: `--execute` required for destructive operations
-- **DI pattern**: handlers accept `deps?` parameter for testing
-- **Config path**: ALWAYS `~/.softspark/jira-mcp/` via `GLOBAL_CONFIG_DIR`, with no manual config and no env vars in MCP client setup
-- **SoftSpark standard**: all open-source tools use `~/.softspark/<tool-name>/`. See SOP in rag-mcp `kb/procedures/softspark-config-standard.md`
-
-## Testing
-
-- **Vitest**: 70% coverage threshold, `vi.fn()` for mocks
-- **No real Jira API calls** in tests, use `tests/fixtures/mocks.ts`
-- **Filesystem tests**: `os.tmpdir()` + `mkdtemp()`, NEVER write to `~/.softspark/`
-- Quick pre-commit: `npm run typecheck && npm run lint && npm test && npm run build`
-
-## KB & SOPs
-
-- `kb/reference/` for architecture, API, configuration, ADF, caching, and templates
-- `kb/howto/` for setup, multi-instance usage, and CLI usage
-- `kb/procedures/` for `sop-pre-commit`, `sop-release`, and `sop-post-release-testing`
-
-<!-- TOOLKIT:jira-mcp END -->
-
-<!-- TOOLKIT:rag-mcp-rules START -->
-<!-- Auto-injected by ai-toolkit. Re-run to update. -->
-
-## INSTANT ACTION RULE (GOLDEN RULE)
-
-**ANY technical question? -> INSTANTLY call `smart_query()` OR `hybrid_search_kb()` BEFORE outputting text!**
-
-1. **Search First:** `smart_query()` or `hybrid_search_kb()` (NEVER skip, even if you "know").
-2. **Cite Sources:** always include `[PATH: kb/...]`.
-3. **Strict Order:** Semantic Search -> Files -> External Docs -> General Knowledge.
-
-Default tool: `smart_query()`. Use `hybrid_search_kb()` for speed, `crag_search()` for vague queries, `multi_hop_search()` for complex reasoning.
-
-## kb_id vs file_path
-
-- `get_document(path=...)` takes `kb_id` from search results (e.g., `local/softspark/project/reference/api.md`)
-- `Read`/`Edit` take filesystem `file_path` (e.g., `./reference/api.md`)
-- **DO NOT CONFUSE** these fields.
-
-## SOPs
-
-ALWAYS check `kb/procedures/` first: `smart_query("SOP for <task>")`.
-
-<!-- TOOLKIT:rag-mcp-rules END -->

package/CHANGELOG.md

@@ -7,6 +7,30 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.12.0 — Global-first editor installs + Codex path fix (2026-07-02)
+
+Minor release. Expands global (HOME-scoped) installs to every editor with a documented, merge-safe file surface, and fixes a Codex global-install bug where instructions landed in a file Codex never reads. Test count: 1203 → 1208.
+
+### Fixed
+- **Codex global instructions path** — `ai-toolkit install --editors codex` and `ai-toolkit plugin install --editor codex` wrote to `~/AGENTS.md`, which Codex never loads as global instructions, so global installs delivered zero instructions. Now write `~/.codex/AGENTS.md` (the documented `$CODEX_HOME/AGENTS.md`), strip the stale `~/AGENTS.md` toolkit section on upgrade, and warn when `~/.codex/AGENTS.override.md` would mask it.
+- **Codex plugin-pack rules** — pack rules were copied to `~/.agents/rules/`, a directory Codex never reads; now marker-injected into `~/.codex/AGENTS.md`, with legacy dead files cleaned on install/remove (`scripts/plugin.py`).
+- **`inject-hook` Codex event parity** — `CODEX_EVENTS` propagated only 5 of the 9 events `scripts/generate_codex_hooks.py` wires; added `PermissionRequest`, `SubagentStart`, `SubagentStop`, `PreCompact`.
+
+### Added
+- **Global native surfaces for 7 editors** — `install_ai_tools` now threads `--profile` and installs each editor's documented HOME surfaces (gated like the local install): **Gemini** (hooks `~/.gemini/settings.json`, `~/.gemini/commands/`, skills pointer), **Augment** (`~/.augment/agents/`, `~/.augment/commands/`, hooks), **Roo/Zoo** (skills via `~/.agents/skills`), **Windsurf** (`~/.config/devin/AGENTS.md` for Devin CLI), **Cursor** (`~/.cursor/hooks.json`), **GitHub Copilot** (`~/.copilot/` instructions), **Google Antigravity** (skill pointer to `~/.gemini/config/skills` and `~/.gemini/antigravity-cli/skills`).
+
+### Changed
+- **`GLOBAL_CAPABLE_EDITORS`** — added `cursor`, `copilot`, and `antigravity` (scoped: cursor = hooks, copilot = instructions, antigravity = skills; RULES stay project-local where no mergeable global file surface exists).
+- **`generate_copilot.py`** and **`generate_antigravity.py`** gained global layouts (`config_root=~/.copilot`; `generate_global()`).
+
+### Ecosystem
+- **Roo → Zoo Code** (class D) — `RooCodeInc/Roo-Code` archived (frozen v3.54.0, dead release feed); retargeted the feed to the successor `Zoo-Code-Org/Zoo-Code` and added skills/commands config paths. (class F) Global skill install via `~/.agents/skills`.
+- **Cursor** (class F) global `~/.cursor/hooks.json`; (class D) `.cursorrules` demoted to legacy (dropped from official rules docs).
+- **GitHub Copilot** (class F) documented `~/.copilot/` user-level surface adopted.
+- **Google Antigravity** (class F) global skill dirs adopted; `~/.gemini/config/mcp_config.json` global MCP path resolved and recorded (adapter is backlog).
+- **Gemini / Augment** (class F) hooks/commands/agents made global.
+- Version refresh: Gemini v0.49.0, Codex 0.142.5, Auggie 0.31.0, Antigravity CLI 1.0.14, Claude Code 2.1.198; Devin `read_config_from` 7-key matrix. Snapshot re-baselined via `scripts/ecosystem_doctor.py --update`.
+
 ## v4.11.0 — Claude rules-space fix + editor registry parity (2026-06-30)
 
 Minor release. Reduces Claude Code startup context pressure by moving ai-toolkit rules out of global/project `CLAUDE.md` inline blocks and into Claude Code rule files. Also finishes the editor registry sync by recording all Gemini generators in the canonical ecosystem registry. Test count: 1198 → 1203.

package/README.md

@@ -6,17 +6,17 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-108-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1203%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1208%20passing-success)](tests/)
 
-## What's New in v4.11.0
+## What's New in v4.12.0
 
-v4.11.0 reduces Claude Code startup/global rule pressure and refreshes the editor registry.
+v4.12.0 makes global (HOME-scoped) installs first-class for every editor with a documented file surface, and fixes a Codex global-install bug.
 
-- **Claude rules-space fix**: global `ai-toolkit install/update` now writes toolkit and registered rules to `~/.claude/rules/ai-toolkit-*.md`, while `install --local` writes common project rules to `.claude/rules/ai-toolkit-*.md` with Claude Code `paths` frontmatter.
-- **Language/global rules docs refreshed**: the KB now documents the split between Claude global user rules, project rules, language-rule skills, and other editors' native rule files.
-- **Gemini registry parity restored**: `scripts/ecosystem_tools.json` now lists the Gemini hooks, commands, and skills generators already used by installer profiles.
-- **Ecosystem snapshot refreshed**: the doctor baseline is updated after class A/C upstream documentation drift review.
-- **Test count**: 1198 → 1203.
+- **Codex global path fix**: `install --editors codex` now writes `~/.codex/AGENTS.md` (the file Codex actually reads) instead of the never-loaded `~/AGENTS.md`; upgrades strip the stale section.
+- **Global installs for 7 editors**: Gemini (hooks/commands/skills), Augment (agents/commands/hooks), Roo/Zoo (skills), Windsurf (`~/.config/devin/AGENTS.md`), plus new global support for Cursor (`~/.cursor/hooks.json`), GitHub Copilot (`~/.copilot/`), and Antigravity (skill pointer).
+- **Roo → Zoo Code**: retargeted the dead `RooCodeInc/Roo-Code` release feed to the active successor `Zoo-Code-Org/Zoo-Code`.
+- **Ecosystem refresh**: Gemini v0.49.0, Codex 0.142.5, Auggie 0.31.0, Antigravity CLI 1.0.14, Claude Code 2.1.198; snapshot re-baselined.
+- **Test count**: 1203 → 1208.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -149,7 +149,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1203 tests)
+├── tests/               # Bats test suite (1208 tests)
 └── CHANGELOG.md
 ```
 

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

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

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-06-30T16:52:43Z",
+  "last_run": "2026-07-01T22:55:24Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "1140b2d05814d7fd",
+      "docs_hash": "04b55a2b2d496b45",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "3101b3cd58375aec",
+      "docs_hash": "338d55540b385861",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -122,10 +122,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.196 (Claude Code)"
+      "version": "2.1.198 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "a934200d22b48f17",
+      "docs_hash": "80209baf691558e2",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -172,7 +172,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "36f437b3356b4706",
+      "docs_hash": "ad6bbf5e29c7155f",
       "headings": [
         "API",
         "API Reference",
@@ -243,7 +243,7 @@
       "version": "codex-cli 0.142.0"
     },
     "cursor": {
-      "docs_hash": "d8aed06363805889",
+      "docs_hash": "080c1289cb353e6c",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -259,7 +259,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "85e8f47e8ef0acda",
+      "docs_hash": "a0ff94dabdb6cd8a",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -302,7 +302,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "df772638c69033d7",
+      "docs_hash": "1f9817b3477c576b",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -353,7 +353,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "791633f4156abbe8",
+      "docs_hash": "28dcd5b88aeb84e0",
       "headings": [
         "Add features",
         "Ask questions",
@@ -413,7 +413,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "bb6e6119f2c068d6",
+      "docs_hash": "b457c990c531efc4",
       "headings": [
         "Accounts",
         "Advanced",

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

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

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

@@ -73,16 +73,22 @@ The `ai-toolkit-*` prefix in `~/.claude/rules/` is reserved for installer-manage
 `ai-toolkit install --editors <name>` can write global files only for editors
 with documented, file-based config surfaces:
 
-- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md`
-- `gemini`: `~/.gemini/GEMINI.md`
-- `augment`: `~/.augment/rules/ai-toolkit.md`
+- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md` plus `~/.codeium/windsurf/skills/ai-toolkit-skill-catalogue/SKILL.md` plus `~/.config/devin/AGENTS.md` (Devin CLI global rules — the Desktop `global_rules.md` path is not imported by `read_config_from.windsurf`)
+- `gemini`: `~/.gemini/GEMINI.md`; hooks at `~/.gemini/settings.json` (profile ≥ standard); `~/.gemini/commands/` and `~/.gemini/skills/` pointer (profile full)
+- `augment`: `~/.augment/rules/ai-toolkit.md`; `~/.augment/agents/`, `~/.augment/commands/`, and hooks in `~/.augment/settings.json` (profile full)
 - `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md` plus `~/.cline/skills/ai-toolkit-skill-catalogue/SKILL.md`
-- `roo`: `~/.roo/rules/ai-toolkit-*.md`
+- `roo`: `~/.roo/rules/ai-toolkit-*.md` plus `~/.agents/skills/*` (Roo/Zoo native skill discovery; skipped when `codex` is also selected, which fills the same dir)
 - `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
-- `codex`: `~/AGENTS.md` (coding rules inlined), `~/.agents/skills/*`, `~/.codex/hooks.json`
+- `codex`: `~/.codex/AGENTS.md` (coding rules inlined; the documented global instruction file — NOT `~/AGENTS.md`, which Codex never loads as global instructions), `~/.agents/skills/*`, `~/.codex/hooks.json`
 - `opencode`: `~/.config/opencode/*`
 
-Cursor, GitHub Copilot, and Google Antigravity rule installs stay project-local.
+Cursor, GitHub Copilot, and Google Antigravity now have partial global support,
+scoped to whatever documented HOME file surface each exposes:
+
+- `cursor`: `~/.cursor/hooks.json` (safety/quality hooks; profile ≥ standard). Cursor RULES stay project-local — their only global surface is the Settings UI.
+- `copilot`: `~/.copilot/copilot-instructions.md` plus `~/.copilot/instructions/ai-toolkit-*.instructions.md` (read by Copilot CLI; VS Code and GitHub.com still use repo `.github/` files, which the local install emits).
+- `antigravity`: skill pointer at `~/.gemini/config/skills/` and `~/.gemini/antigravity-cli/skills/`. Antigravity RULES stay project-local.
+
 Their global MCP support, where available, is handled by `ai-toolkit mcp
 install`, not by the rule installer.
 
@@ -141,8 +147,7 @@ Codex wrappers so the project still receives the full skill catalog.
 
 `ai-toolkit plugin install --editor codex <pack>` additionally targets:
 
-- `~/AGENTS.md`
-- `~/.agents/rules/*.md`
+- `~/.codex/AGENTS.md` (base instructions; pack rules are marker-injected here, not written as unread `~/.agents/rules/` files)
 - `~/.agents/skills/*`
 - `~/.codex/hooks.json`
 

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

@@ -49,9 +49,10 @@ 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` (plain `.md` files in `.cursor/rules/` are **ignored** by the rules system), `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `~/.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `~/.cursor/agents/*.md`, `.cursor/hooks.json` |
+| 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), `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` (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 |
 
 ### Windsurf
@@ -63,8 +64,9 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Changelog | https://docs.devin.ai/desktop/changelog (windsurf.com/changelog 308-permanent-redirects here) |
 | Stable docs mirror | https://docs.devin.ai/desktop/... per-page .md twins; legacy `.windsurf/`, `.windsurfrules`, `~/.codeium/windsurf/` paths still read as fallback (new canonical: `.devin/`) |
 | Config paths | **Primary (Devin Desktop):** `.devin/rules/*.md`, `.devin/workflows/*.md`, `.devin/skills/*/SKILL.md`, `.devin/hooks.v1.json` (Devin CLI hooks, Claude format), `.devin/config.json`, `.devin/config.local.json`, `~/.config/devin/config.json` (Devin Local MCP/permissions). **Legacy fallback:** `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `.windsurf/skills/*/SKILL.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/skills/*/SKILL.md`, `~/.codeium/windsurf/mcp_config.json`. Plus `AGENTS.md`. |
-| Compat read paths | skills: `.agents/skills/`, `~/.agents/skills/`, (with Claude Code config-reading) `.claude/skills/`, `~/.claude/skills/`. **Hooks: Devin CLI reads `.claude/settings.json` + `~/.claude/settings.json` hooks directly (`read_config_from.claude` default on), so globally-installed toolkit hooks work under Devin with no project-local file.** |
-| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py` (dual-emits `.devin/` + `.windsurf/`), `scripts/generate_windsurf_hooks.py` (profile=full; **Cascade-scoped, deprecated, drop after 2026-07-01**), `scripts/generate_devin_hooks.py` (profile=full; `.devin/hooks.v1.json`, Claude-format Devin CLI hooks), `scripts/generate_windsurf_skills.py` (global + profile=full pointer, dual-emits) |
+| Compat read paths | skills: `.agents/skills/`, `~/.agents/skills/`, (with Claude Code config-reading) `.claude/skills/`, `~/.claude/skills/`. **Hooks: Devin CLI reads `.claude/settings.json` + `~/.claude/settings.json` hooks directly (`read_config_from.claude` default on), so globally-installed toolkit hooks work under Devin with no project-local file.** `read_config_from` now has **7 keys** (all default true): `agents_standard`, `cursor`, `windsurf`, `claude`, `opencode`, `vscode`, `zed` — so Devin CLI also imports MCP from `~/.config/opencode/opencode.json` (our opencode global install), `~/.config/zed/settings.json`, and `.vscode/mcp.json`. |
+| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py` (dual-emits `.devin/` + `.windsurf/`), `scripts/generate_windsurf_hooks.py` (profile=full; **Cascade-scoped, drop in the first release after 2026-07-01**), `scripts/generate_devin_hooks.py` (profile=full; `.devin/hooks.v1.json`, Claude-format Devin CLI hooks), `scripts/generate_windsurf_skills.py` (global + profile=full pointer, dual-emits) |
+| Global install | `ai-toolkit install --editors windsurf` writes `~/.codeium/windsurf/memories/global_rules.md` + skills pointer **and** `~/.config/devin/AGENTS.md` (Devin CLI global rules — the Desktop `global_rules.md` path is absent from `read_config_from.windsurf`, so editor-only Devin CLI installs need this). |
 | Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, skills, MCP, memories, hooks |
 | Activation modes emitted | always_on (agents/security/quality), glob (testing + language rules), model_decision (code-style/workflow) |
 | Hooks migration | **Done.** Cascade `.windsurf/hooks.json` (`agent_action_name`/`tool_info` format) dies 2026-07-01 with no Devin fallback. `generate_devin_hooks.py` emits `.devin/hooks.v1.json` in the Claude-compatible format Devin CLI uses: Claude-style events (PreToolUse/PostToolUse/UserPromptSubmit/Stop/SessionStart), matchers on Devin tool names (`read`/`edit`/`exec`/`mcp__*`), blocking via flat `{"decision":"block","reason":...}` + exit 2 (no `AI_TOOLKIT_HOOK_FORMAT=json` — Devin does not use Claude's `hookSpecificOutput` envelope). `post_setup_worktree`→`SessionStart`; `post_cascade_response`→`Stop` (no response text on stdin). Both hook generators run at profile=full during the transition; drop `generate_windsurf_hooks.py` in the first release after 2026-07-01. |
@@ -77,9 +79,11 @@ 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 | `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, `.github/prompts/*.prompt.md`, `AGENTS.md` |
-| Our generators | `scripts/generate_copilot.py` |
-| Tracked capabilities | `copilot-instructions.md`, Copilot Chat, Copilot Workspace, Copilot cloud agent, `applyTo`, custom agents, prompt files, `instructions.md`, `AGENTS.md`, MCP |
+| 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. |
+| 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). |
 
 ### Gemini CLI
@@ -91,9 +95,10 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Release notes | https://github.com/google-gemini/gemini-cli/releases |
 | Config paths | `GEMINI.md`, `.gemini/settings.json`, `~/.gemini/settings.json`, `.gemini/commands/*.toml`, `.gemini/skills/*/SKILL.md`, `.agents/skills/*/SKILL.md`, `~/.gemini/skills/*/SKILL.md`, `~/.agents/skills/*/SKILL.md` (the `.agents/skills` alias wins over `.gemini/skills` within the same tier), `.gemini/extensions/gemini-extension.json` |
 | Our generators | `scripts/generate_gemini.py`, `scripts/generate_gemini_hooks.py` (profile>=standard), `scripts/generate_gemini_commands.py` (profile=full), `scripts/generate_gemini_skills.py` (profile=full) |
-| Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeToolSelection`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `Notification`, `PreCompress`, `SessionStart`, `SessionEnd`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` (no native `Stop` event — generator maps Stop-equivalent to `AfterAgent`; 11 documented hook events total) |
+| Global install | `ai-toolkit install --editors gemini` writes `~/.gemini/GEMINI.md` **plus** hooks at `~/.gemini/settings.json` (profile ≥ standard) and `~/.gemini/commands/` + `~/.gemini/skills/` pointer (profile=full) — all documented user-tier surfaces. A global-only Gemini user previously got zero hooks. |
+| Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeToolSelection`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `AfterModel`, `Notification`, `PreCompress`, `SessionStart`, `SessionEnd`, `SKILL.md`, `activate_skill`, custom commands, `.gemini/agents/*.md` subagents, `gemini-extension.json` (no native `Stop` event — generator maps Stop-equivalent to `AfterAgent`; 11 documented hook events total) |
 | Version probe | `gemini --version` |
-| Latest upstream | v0.47.0 (2026-06-18). NOTE: Gemini CLI dropped free/paid individual tiers on 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist and paid API keys keep Gemini CLI, so the integration stays. The 11 hook events are unchanged. v0.48 preview migrates the `coreTools` setting to `tools.core` (a tool-allowlist key we do not emit, so no generator change). |
+| Latest upstream | v0.49.0 (2026-06-25; the stable line skipped v0.48.0 — its preview content was promoted into v0.49.0). NOTE: Gemini CLI dropped free/paid individual tiers on 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist and paid API keys keep Gemini CLI, so the integration stays. The 11 hook events are unchanged. v0.49.0 completed the `coreTools` → `tools.core` migration (auto-migrated; `tools.exclude` deprecated) — both are tool-allowlist keys we do not emit, so no generator change. Watch item: `.gemini/agents/*.md` / `~/.gemini/agents/*.md` native subagents are documented but we do not yet emit them (candidate `generate_gemini_agents.py`). |
 
 ### Cline
 
@@ -114,12 +119,12 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Field | Value |
 |-------|-------|
 | ID | `roo-code` |
-| Docs | https://roocodeinc.github.io/Roo-Code (docs.roocode.com 301-redirects here) |
-| Release notes | https://github.com/RooCodeInc/Roo-Code/releases (**ARCHIVED** — repo read-only since 2026-05-15, frozen at v3.54.0; community fork reportedly continues) |
-| 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) |
+| Docs | https://roocodeinc.github.io/Roo-Code (frozen; docs.roocode.com 301-redirects here). Successor docs: https://docs.zoocode.dev |
+| Release notes | https://github.com/Zoo-Code-Org/Zoo-Code/releases (authoritative). **Original RooCodeInc/Roo-Code repo ARCHIVED/read-only since 2026-05-15, frozen at v3.54.0 — its feed is dead.** Successor project by former Roo contributors: **Zoo-Code-Org/Zoo-Code** (marketplace `ZooCodeOrganization.zoo-code`), active through v3.64.0 (2026-06-26). |
+| Config paths | `.roomodes` (JSON still fully supported), `.roo/rules/*.md`, `.roo/rules-{slug}/*.md`, `.roo/skills/*/SKILL.md`, `~/.roo/skills/*/SKILL.md`, `.agents/skills/*/SKILL.md`, `~/.agents/skills/*`, `.roo/commands/*.md`, `~/.roo/commands/*.md`, `.roo/mcp.json`, `~/.roo/rules/`, `mcp_settings.json` + global custom modes live in VS Code globalStorage (`<globalStorage>/rooveterinaryinc.roo-cline/settings/custom_modes.yaml`), NOT `~/.roo/custom_modes.yaml` |
 | 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. Global install writes only `~/.roo/rules/` because the exact global MCP settings path is UI-managed. |
+| Tracked capabilities | `roomodes`, custom modes, Code Actions, MCP, Orchestrator mode, `whenToUse`, `description`, `roleDefinition`, `groups`, skills, slash commands |
+| Notes | Config compat with the Zoo fork is total, so both generators stay valid unchanged. `.roomodes` includes `description`/`whenToUse` for every mode (since 2026-04); JSON is still accepted (YAML is upstream-preferred but not emitted). Global install writes `~/.roo/rules/` plus `~/.agents/skills/*` (Roo/Zoo native skill discovery, shipped v3.46.0/v3.47.2; skipped when `codex` is also selected). `~/.roo/commands/` (global slash commands, since v3.25) is a documented surface not yet generated. |
 
 ### Aider
 
@@ -144,7 +149,9 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Changelog | https://www.augmentcode.com/changelog |
 | Config paths | `.augment/rules/*.md`, `.augment-guidelines` (workspace root, legacy single-file), `~/.augment/user-guidelines.md`, `.augment/agents/*.md`, `.augment/commands/*.md`, `.augment/skills/*/SKILL.md`, `.augment/settings.json`, `.augment/settings.local.json`, `~/.augment/rules/*.md`, `~/.augment/settings.json`, `/etc/augment/settings.json`. Auggie CLI also discovers skills/commands from `.claude/` and `.agents/` (`.augment/` wins on precedence). |
 | Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py`, `scripts/generate_augment_agents.py` (profile=full), `scripts/generate_augment_commands.py` (profile=full), `scripts/generate_augment_hooks.py` (profile=full, HOME-scoped), `scripts/generate_augment_skills.py` (profile=full) |
-| Tracked capabilities | `.augment`, Agent mode, Next Edit, MCP, context engine, Auggie CLI, `always_apply`, `agent_requested`, subagents, custom commands, `SKILL.md`, `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `Stop`, `Notification`, ACP Mode |
+| Global install | `ai-toolkit install --editors augment` writes `~/.augment/rules/ai-toolkit.md` **plus** (profile=full) `~/.augment/agents/`, `~/.augment/commands/`, and hooks in `~/.augment/settings.json` — all documented user-tier surfaces. A global-only Augment user previously got no hooks/agents/commands. Skills need no global emission: Auggie natively reads `~/.claude/skills/`. |
+| Tracked capabilities | `.augment`, Agent mode, Next Edit, MCP, context engine, Auggie CLI, `always_apply`, `agent_requested`, subagents, custom commands, `SKILL.md`, `PreToolUse`, `PostToolUse`, `SessionStart`, `SessionEnd`, `Stop`, `Notification`, ACP Mode, plugins/marketplace |
+| Latest / notes | Auggie CLI v0.31.0. Since v0.30.0 (2026-06-25) `PreToolUse`/`PostToolUse` hooks fire during sub-agent sessions, so our wired hook groups now run concurrently from parallel sub-agents — hook payload identifier is `conversation_id` (not `session_id`), a concurrency note to track. `Notification` is enum-only (doctor flipped its marker) — no dedicated handler documented, so class C (do NOT wire). Plugins/marketplace (`auggie plugin marketplace add`, `.augment-plugin`/`.claude-plugin` layouts, `enabledPlugins`/`autoUpdateMarketplaces` in settings) documented but not yet a shipping target. |
 | SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
 
 ### Google Antigravity
@@ -155,9 +162,11 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
-| Our generators | `scripts/generate_antigravity.py` (rules + workflows + skill pointer dual-emitted to `.agent/skills/` and `.agents/skills/`) |
-| Tracked capabilities | Antigravity, agent manager, artifacts, MCP, workflows, rules, skills, hooks, `AGENTS.md`, `GEMINI.md`, agent permissions |
-| CLI notes | Antigravity CLI (GA 2026-05-19): hooks in `.agents/hooks.json` use Claude-style event names (`PreToolUse`, not Gemini's `BeforeTool`) with a JSON stdin/stdout decision contract; MCP config `.agents/mcp_config.json` requires `serverUrl` (legacy `url`/`httpUrl` fail silently). Global MCP config path is inconsistently reported across sources (`~/.gemini/antigravity-cli/` vs `~/.gemini/config/`) — only the workspace path is registered until verified via `agy inspect`. |
+| 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`). |
+| 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. |
 
 ### Codex CLI
@@ -165,13 +174,13 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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`; latest stable codex-cli 0.142.0, 2026-06) |
+| 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 stable codex-cli 0.142.5, 2026-07-01; 0.143.0 alpha) |
 | Release notes | https://github.com/openai/codex/releases |
-| Config paths | `AGENTS.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `.codex/config.toml` (project layers, root→cwd, closest wins, trusted projects only), `~/.codex/config.toml` |
+| 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`) |
-| 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/`. |
-| 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, 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); `prompt` and `agent` available upstream but authored by hand |
+| 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) |
 | Version probe | `codex --version` |