@softspark/ai-toolkit 4.6.0 → 4.8.0

package/llms-full.txt

@@ -4404,9 +4404,9 @@ title: "SOP: Claude Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "3.0.1"
+version: "3.1.0"
 created: "2026-03-23"
-last_updated: "2026-05-25"
+last_updated: "2026-06-10"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -4612,18 +4612,19 @@ Use this when Claude appears to ignore `CLAUDE.md`, `.claude/rules/*.md`, output
    - `https://code.claude.com/docs/en/settings`
    - `https://code.claude.com/docs/en/output-styles`
    - `https://code.claude.com/docs/en/hooks`
-2. **Verify instruction loading.** Run `/memory` in Claude Code and confirm the expected `CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/*.md` files are listed. Remember that Claude Code reads `CLAUDE.md`, not `AGENTS.md`, unless `CLAUDE.md` imports it.
-3. **Verify the active output style.** Check `.claude/settings.local.json` or `/config`. Output style changes apply after `/clear` or a new session.
-4. **Inspect installed hooks.** Ensure `~/.claude/settings.json` contains the ai-toolkit `UserPromptSubmit` and `Stop` entries. The governance hook must run with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json` so it injects `additionalContext` without noisy transcript output.
-5. **Reproduce the hook path directly.**
+2. **Isolate with safe mode (v2.1.169+).** Start a session with `claude --safe-mode` (or `CLAUDE_CODE_SAFE_MODE=1`) — it disables hooks, skills, agents, and CLAUDE.md. If the problem persists in safe mode, the cause is upstream, not toolkit customization; if it disappears, bisect toolkit components with `ai-toolkit update --only <component>`.
+3. **Verify instruction loading.** Run `/memory` in Claude Code and confirm the expected `CLAUDE.md`, `CLAUDE.local.md`, and `.claude/rules/*.md` files are listed. Remember that Claude Code reads `CLAUDE.md`, not `AGENTS.md`, unless `CLAUDE.md` imports it.
+4. **Verify the active output style.** Check `.claude/settings.local.json` or `/config`. Output style changes apply after `/clear` or a new session.
+5. **Inspect installed hooks.** Ensure `~/.claude/settings.json` contains the ai-toolkit `UserPromptSubmit` and `Stop` entries. The governance hook must run with `AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json` so it injects `additionalContext` without noisy transcript output.
+6. **Reproduce the hook path directly.**
    ```bash
    printf '{"session_id":"debug","prompt":"debug this technical rule issue"}' \
      | AI_TOOLKIT_SEARCH_FIRST=strict AI_TOOLKIT_HOOK_QUIET=1 AI_TOOLKIT_HOOK_FORMAT=json \
        ~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh
    ```
    The output must be valid JSON with `hookSpecificOutput.additionalContext`.
-6. **Check corrective enforcement.** If the assistant still skips required research, `stop-search-check.sh` should block Stop with the search-first message. If it does not, inspect `~/.softspark/ai-toolkit/state/search-required-*.flag` and the Codex/Claude transcript logs.
-7. **Repair drift.** Run:
+7. **Check corrective enforcement.** If the assistant still skips required research, `stop-search-check.sh` should block Stop with the search-first message. If it does not, inspect `~/.softspark/ai-toolkit/state/search-required-*.flag` and the Codex/Claude transcript logs.
+8. **Repair drift.** Run:
    ```bash
    ai-toolkit update --only hooks
    python3 scripts/ecosystem_doctor.py --tool claude-code --format text
@@ -5372,7 +5373,7 @@ python3 scripts/audit_skills.py --ci
 npm test
 
 # 5. Stage and commit
-git add AGENTS.md .agents/rules/ai-toolkit-*.md llms.txt llms-full.txt
+git add AGENTS.md llms.txt llms-full.txt
 git add -p  # stage your other changes
 git commit -m "feat: your change description"
 ```
@@ -6136,9 +6137,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.4.5"
+version: "1.4.6"
 created: "2026-03-23"
-last_updated: "2026-05-12"
+last_updated: "2026-06-10"
 description: "Architecture of ai-toolkit: directory layout, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -6242,7 +6243,7 @@ Machine (global)                              Project (local)
 - `--editors cursor,aider` — install only selected editors
 - (no flag) — auto-detect from existing project files; `update --local` picks up whatever editors already have configs
 
-Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules/*.md`, `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agents/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md` (universal coding rules inlined — Codex reads only AGENTS.md, not `.agents/rules/`), `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
+Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.devin/rules/*.md` + `.windsurf/rules/*.md` (dual-emit since the Devin Desktop rebrand), `.clinerules/*.md`, `.roo/rules/*.md`, `.augment/rules/ai-toolkit-*.md`, `.agents/rules/*.md`, `CONVENTIONS.md`). Full-profile installs also emit native skill pointer catalogues for Cursor, Windsurf, and Cline. Codex local install additionally generates `AGENTS.md` (universal coding rules inlined — Codex reads only AGENTS.md, not `.agents/rules/`), `.agents/skills/*`, and `.codex/hooks.json`. Hooks are global-only — not merged into project settings except for editor-native local hook files such as Codex `.codex/hooks.json`. Experimental plugin packs can also layer a global Codex target in `HOME` (`~/AGENTS.md`, `~/.agents/`, `~/.codex/hooks.json`) when installed with `ai-toolkit plugin install --editor codex`.
 
 If a project already has `.mcp.json`, local install mirrors its `mcpServers` entries into `.claude/settings.local.json` plus any selected editors with project-scoped native MCP files (`.cursor/mcp.json`, `.github/mcp.json`).
 
@@ -6266,7 +6267,7 @@ If a project already has `.mcp.json`, local install mirrors its `mcpServers` ent
 | `cursor-rules` | `./` | Generates `.cursorrules` (legacy) |
 | `cursor-mdc` | `./` | Generates `.cursor/rules/*.mdc` (recommended) |
 | `windsurf-rules` | `./` | Generates `.windsurfrules` (legacy) |
-| `windsurf-dir-rules` | `./` | Generates `.windsurf/rules/*.md` |
+| `windsurf-dir-rules` | `./` | Generates `.devin/rules/*.md` + `.windsurf/rules/*.md` (dual-emit) |
 | `copilot-instructions` | `./` | Generates `.github/copilot-instructions.md` |
 | `gemini-md` | `./` | Generates `GEMINI.md` |
 | `cline-rules` | `./` | Generates `.clinerules` (legacy) |
@@ -8899,9 +8900,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.7"
+version: "1.6.0"
 created: "2026-03-27"
-last_updated: "2026-05-25"
+last_updated: "2026-06-10"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -9467,6 +9468,31 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 - `_source: "ai-toolkit"` tag on every entry — allows idempotent merge/strip
 - Hooks are **global only** — `--local` does not install hooks into project settings
 
+## Per-Editor Native Hooks (profile=full)
+
+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.
+
+| Editor | File | Generator | Format |
+|--------|------|-----------|--------|
+| Cursor | `.cursor/hooks.json` | `generate_cursor_hooks.py` | Cursor hooks schema |
+| Windsurf (Cascade) | `.windsurf/hooks.json` | `generate_windsurf_hooks.py` | Cascade `agent_action_name`/`tool_info` — **deprecated, dies 2026-07-01** |
+| 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 |
+
+### Devin CLI hooks (`.devin/hooks.v1.json`)
+
+Windsurf rebranded to Devin Desktop (2026-06-02); the Cascade agent — and its `.windsurf/hooks.json` surface — is available only through **2026-07-01**. Devin Local / Devin CLI do **not** read `.windsurf/hooks.json` as a fallback, so hooks must be regenerated onto the Devin CLI format.
+
+Devin CLI uses a **Claude-compatible** hook format (docs.devin.ai/cli/extensibility/hooks). Key facts driving the generator:
+
+- **Standalone file shape:** in `.devin/hooks.v1.json` the entire file IS the hooks object — no top-level `"hooks"` wrapper key (unlike `.claude/settings.json`).
+- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SessionStart`. `post_setup_worktree` has no Devin equivalent (`session-context.sh` moves to `SessionStart`); `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
+- **Matchers:** regex against the Devin **tool name** (`read`, `edit`, `exec`, `grep`, `glob`, `mcp__<server>__<tool>`) — NOT Claude's `Bash`/`Edit`, so the shared guards reliably fire.
+- **Block contract:** the guard scripts emit `{"decision":"block","reason":...}` on stdout (plain mode) AND exit 2 — Devin honors both. Hooks run **without** `AI_TOOLKIT_HOOK_FORMAT=json` because Devin expects the flat `{"decision","reason"}` shape, not Claude's `hookSpecificOutput` envelope.
+- **Stdin payload:** flat `{ "hook_event_name", "tool_name", "tool_input" }` — already handled by `_hook-io.sh` via its `.tool_name` / `.tool_input.*` branches, so no normalizer change was needed.
+- **Global bonus:** Devin CLI reads `~/.claude/settings.json` + `.claude/settings.json` hooks directly (`read_config_from.claude` default on, since CLI `2026.3.20-2`), so a global `ai-toolkit install` already covers Devin even without the project-local file.
+
 ## Troubleshooting
 
 **Hooks not loading:**
@@ -11769,9 +11795,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.4.0"
+version: "1.6.0"
 created: "2026-04-23"
-last_updated: "2026-06-05"
+last_updated: "2026-06-10"
 description: "Human-readable view of scripts/ecosystem_tools.json — the canonical list of tools ai-toolkit integrates with (Claude Code + 11 editors), their documentation URLs, config paths, our generators, and tracked capability markers."
 ---
 
@@ -11794,13 +11820,14 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `claude-code` |
 | Docs | https://code.claude.com/docs (platform.claude.com/docs 307-redirects here) |
 | Release notes | https://github.com/anthropics/claude-code/releases |
-| Changelog | https://code.claude.com/docs/en/changelog (lists current 2.1.165) |
-| Config paths | `~/.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `~/.claude/themes/*.json` (v2.1.118+) |
+| Changelog | https://code.claude.com/docs/en/changelog (lists current 2.1.170) |
+| Config paths | `~/.claude/settings.json`, `.claude/settings.json` (project, committed), `.claude/settings.local.json`, `CLAUDE.md`, `.claude/rules/*.md`, `.claude/agents/*.md`, `.claude/skills/*/SKILL.md`, `~/.claude/themes/*.json` (v2.1.118+) |
 | Our generators | — (Claude Code is the primary target; toolkit content ships directly as `.md` files and `settings.json` merges) |
 | Tracked hook events | Core: `SessionStart`, `SessionEnd`, `UserPromptSubmit`, `Notification`, `MessageDisplay`. Tool: `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PostToolBatch`. Turn: `Stop`, `StopFailure`, `UserPromptExpansion`. Subagent: `SubagentStart`, `SubagentStop`. Compaction: `PreCompact`, `PostCompact`. Permissions: `PermissionRequest`, `PermissionDenied`. Elicitation: `Elicitation`, `ElicitationResult`. Teams: `TaskCreated`, `TaskCompleted`, `TeammateIdle`. Worktrees/env: `WorktreeCreate`, `WorktreeRemove`, `CwdChanged`, `FileChanged`, `ConfigChange`. Setup: `Setup`, `InstructionsLoaded` |
-| Tracked handler types | `command`, `prompt`, `agent`, `mcp_tool` |
+| Tracked handler types | `command`, `prompt`, `agent`, `mcp_tool`, `http` (POST event JSON to allowlisted URLs via `allowedHttpHookUrls`) |
 | Other capabilities | slash commands, MCP server/client, sub-agent, output style, `SKILL.md` (≥500 lines warn) |
 | Version probe | `claude --version` |
+| Notes | v2.1.169 added `disableBundledSkills` setting + `CLAUDE_CODE_DISABLE_BUNDLED_SKILLS` env var (hides bundled skills/built-in slash commands from the model; toolkit skills in `.claude/skills/` are unaffected — useful when toolkit skills overlap built-ins) and `claude --safe-mode` / `CLAUDE_CODE_SAFE_MODE` (starts with hooks, skills, agents, and CLAUDE.md disabled — first isolation step when debugging toolkit rule enforcement). `fallbackModel` settings key (v2.1.166) noted as not-adopted (class C, no toolkit surface writes model settings). |
 
 ---
 
@@ -11814,8 +11841,8 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://cursor.com/docs |
 | Changelog | https://cursor.com/changelog |
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
-| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `~/.cursor/skills/*/SKILL.md`, `.cursor/agents/*.md`, `.cursor/hooks.json` |
-| Compat read paths | `.agents/skills/`, `~/.agents/skills/`, `.claude/skills/`, `~/.claude/skills/`, `.codex/skills/`, `~/.codex/skills/` |
+| 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` |
+| 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) |
 | Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
 
@@ -11827,11 +11854,13 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://docs.devin.ai/desktop (Windsurf rebranded to Devin Desktop ~2026-06-02; docs.windsurf.com resolves here) |
 | 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 | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `.windsurf/skills/*/SKILL.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.md`, `~/.codeium/windsurf/skills/*/SKILL.md`, `~/.codeium/windsurf/mcp_config.json` |
-| Compat read paths | `.agents/skills/`, `~/.agents/skills/`, (with Claude Code config-reading) `.claude/skills/`, `~/.claude/skills/` |
-| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full), `scripts/generate_windsurf_skills.py` (global + profile=full pointer) |
+| 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) |
 | 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. |
+| Sunset notes | Cascade agent is available only through **2026-07-01**; Devin Local is the default agent since 2026-06-02. Devin CLI ("Devin for Terminal") shares the Devin Local harness, reads `AGENTS.md`, the standard `SKILL.md` format, and Claude-format hooks; not yet a separate registry entry. |
 
 ### GitHub Copilot
 
@@ -11852,11 +11881,11 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `gemini-cli` |
 | Docs | https://github.com/google-gemini/gemini-cli/tree/main/docs |
 | 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/extensions/gemini-extension.json` |
+| 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`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `SessionStart`, `SessionEnd`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` (no native `Stop` event — generator maps Stop-equivalent to `AfterAgent`) |
+| 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) |
 | Version probe | `gemini --version` |
-| Latest upstream | v0.45.1 (2026-06-04). NOTE: Gemini CLI drops free/paid tiers 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist keeps Gemini CLI. |
+| Latest upstream | v0.45.2 (2026-06-05). NOTE: Gemini CLI drops free/paid tiers 2026-06-18 in favor of Antigravity CLI (we ship `generate_antigravity.py`); enterprise Code Assist keeps Gemini CLI. |
 
 ### Cline
 
@@ -11865,9 +11894,10 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `cline` |
 | Docs | https://docs.cline.bot |
 | Release notes | https://github.com/cline/cline/releases |
-| Config paths | `.clinerules/*.md`, `.clinerules/workflows/*.md`, `.clinerules/skills/*/SKILL.md`, `.clinerules/hooks/` (project), `.cline/skills/*/SKILL.md`, `~/.cline/skills/*/SKILL.md`, `~/Documents/Cline/Rules/Hooks/` (global hooks), `~/.cline/data/settings/cline_mcp_settings.json`, `.claude/skills/*/SKILL.md` (native discovery, always-on since v3.57.0). NOTE: `.cline/rules/` and `.cline/hooks/` were removed as phantom paths — Cline reads rules from `.clinerules/`. |
+| Config paths | **Extension:** `.clinerules/*.md`, `.clinerules/workflows/*.md`, `.clinerules/skills/*/SKILL.md`, `.clinerules/hooks/` (project), `~/Documents/Cline/Rules/Hooks/` (global hooks), `~/.cline/data/settings/cline_mcp_settings.json`. **CLI/SDK unified layout** (docs.cline.bot/getting-started/config; `.clinerules` is deprecated there): `.cline/{rules,hooks,plugins,skills}/`, `~/.cline/{rules,hooks,plugins,skills}/`, `CLINE_HOOKS_DIR` env var. **Cross-tool:** `AGENTS.md` + `~/.agents/AGENTS.md` (first-class rules sources), `.claude/skills/*/SKILL.md` (native discovery, always-on since v3.57.0). |
 | Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py`, `scripts/generate_cline_skills.py` |
-| Tracked capabilities | `clinerules`, Plan Mode, Act Mode, MCP, custom modes, workflows, hooks, skills, subagents, conditional rules |
+| Tracked capabilities | `clinerules`, Plan Mode, Act Mode, MCP, custom modes, workflows, hooks, skills, subagents, conditional rules, `AGENTS.md`, plugins |
+| Plugins | `.cline/plugins/` + `~/.cline/plugins/` (JS/TS), `package.json` `cline.plugins` manifest; plugins can bundle skills. Not adopted as a distribution channel yet — candidate for shipping toolkit skills to CLI/SDK users. |
 | Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Project rules still use `.clinerules/` for compatibility; global rules are written to `~/Documents/Cline/Rules/` (the documented Cline global rules dir — `~/.cline/rules/` is not a Cline-read path). Skills are emitted as a pointer catalogue in `profile=full` and global installs. |
 | Global install | `ai-toolkit install --editors cline` writes documented global rules under `~/Documents/Cline/Rules/` and a skill pointer under `~/.cline/skills/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |
 
@@ -11904,9 +11934,9 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | ID | `augment` |
 | Docs | https://docs.augmentcode.com |
 | Changelog | https://www.augmentcode.com/changelog |
-| Config paths | `.augment/rules/*.md`, `.augment/guidelines.md` (legacy), `.augment/agents/*.md`, `.augment/commands/*.md`, `.augment/skills/*/SKILL.md`, `~/.augment/rules/*.md`, `~/.augment/settings.json`, `/etc/augment/settings.json` |
+| 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`, ACP Mode |
+| 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 |
 | SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
 
 ### Google Antigravity
@@ -11916,19 +11946,20 @@ 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`, `AGENTS.md`, `GEMINI.md` |
-| Our generators | `scripts/generate_antigravity.py` (rules + workflows + skill pointer) |
-| Tracked capabilities | Antigravity, agent manager, artifacts, MCP, workflows, rules, skills, `AGENTS.md`, `GEMINI.md`, agent permissions |
-| Doc access note | Docs are JS-SPA — verify via `main-*.js` bundle strings or community skill repos. `WebFetch` returns an empty shell. |
+| 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`. |
+| 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
 
 | Field | Value |
 |-------|-------|
 | ID | `codex-cli` |
-| Docs | https://developers.openai.com/codex (now a live docs site with `/codex/{hooks,skills,rules}` pages; latest stable rust-v0.137.0, 2026-06-04) |
+| 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.138.0, 2026-06) |
 | Release notes | https://github.com/openai/codex/releases |
-| Config paths | `AGENTS.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `~/.codex/config.toml` |
+| 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` |
 | 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 all 10 to shared toolkit hook scripts, mirroring the Claude Code mapping in `app/hooks.json`. |
@@ -11942,12 +11973,13 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 |-------|-------|
 | ID | `opencode` |
 | Docs | https://opencode.ai/docs |
-| Release notes | https://github.com/sst/opencode/releases |
-| Config paths | `opencode.json`, `.opencode/agents/*.md`, `.opencode/commands/*.md`, `.opencode/plugins/*`, `.opencode/skills/*/SKILL.md` (v1.14+), `AGENTS.md`, `.claude/skills/*/SKILL.md` (fallback discovery) |
+| Release notes | https://github.com/sst/opencode/releases (redirects to anomalyco/opencode) |
+| Config paths | `opencode.json`, `.opencode/agents/*.md`, `.opencode/commands/*.md`, `.opencode/plugins/*`, `.opencode/skills/*/SKILL.md` (v1.14+), `AGENTS.md`; skill fallback discovery: `.claude/skills/`, `.agents/skills/`, `~/.config/opencode/skills/`, `~/.claude/skills/`, `~/.agents/skills/` |
 | Our generators | `scripts/generate_opencode.py`, `scripts/generate_opencode_agents.py`, `scripts/generate_opencode_commands.py`, `scripts/generate_opencode_json.py`, `scripts/generate_opencode_plugin.py` |
 | Tracked plugin events | `session.created`, `session.compacted`, `session.deleted`, `message.updated`, `tool.execute.before`, `tool.execute.after`, `permission.asked`, `command.executed` |
 | Other capabilities | `opencode.json` config, primary + subagent modes, `@`-mention subagents, `/`-invocation commands, MCP (local + remote), plugin hooks in JS/TS, native `SKILL.md` discovery with Claude-compatible fallback, `permission.skill.*` matrix |
 | Version probe | `opencode --version` |
+| Watch item | v1.16.0 (2026-06-05) ships an experimental v2 skill registry (flat-file skills, `slash` frontmatter key) — undocumented as of 2026-06-09; re-check next sync before touching `generate_opencode*.py`. |
 
 ---
 

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.6.0",
+  "version": "4.8.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.6.0",
+  "version": "4.8.0",
   "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/ecosystem_tools.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "description": "Authoritative registry of tools ai-toolkit integrates with. Consumed by scripts/ecosystem_doctor.py to detect upstream doc/version drift.",
-  "last_updated": "2026-06-05",
+  "last_updated": "2026-06-10",
   "tools": [
     {
       "id": "claude-code",
@@ -14,8 +14,10 @@
       },
       "config_paths": [
         "~/.claude/settings.json",
+        ".claude/settings.json",
         ".claude/settings.local.json",
         "CLAUDE.md",
+        ".claude/rules/*.md",
         ".claude/agents/*.md",
         ".claude/skills/*/SKILL.md",
         "~/.claude/themes/*.json"
@@ -60,7 +62,8 @@
         "hook handler: command",
         "hook handler: prompt",
         "hook handler: agent",
-        "hook handler: mcp_tool"
+        "hook handler: mcp_tool",
+        "hook handler: http"
       ],
       "version_probe": {
         "kind": "command",
@@ -79,7 +82,6 @@
       "config_paths": [
         ".cursorrules",
         ".cursor/rules/*.mdc",
-        ".cursor/rules/*.md",
         "AGENTS.md",
         ".cursor/mcp.json",
         "~/.cursor/mcp.json",
@@ -92,6 +94,11 @@
         ".codex/skills/*/SKILL.md",
         "~/.codex/skills/*/SKILL.md",
         ".cursor/agents/*.md",
+        "~/.cursor/agents/*.md",
+        ".claude/agents/*.md",
+        "~/.claude/agents/*.md",
+        ".codex/agents/*.md",
+        "~/.codex/agents/*.md",
         ".cursor/hooks.json"
       ],
       "our_generators": [
@@ -125,6 +132,13 @@
         "changelog": "https://docs.devin.ai/desktop/changelog"
       },
       "config_paths": [
+        ".devin/rules/*.md",
+        ".devin/workflows/*.md",
+        ".devin/skills/*/SKILL.md",
+        ".devin/hooks.v1.json",
+        ".devin/config.json",
+        ".devin/config.local.json",
+        "~/.config/devin/config.json",
         ".windsurfrules",
         ".windsurf/rules/*.md",
         ".windsurf/workflows/*.md",
@@ -138,8 +152,11 @@
       "our_generators": [
         "scripts/generate_windsurf.py",
         "scripts/generate_windsurf_rules.py",
-        "scripts/generate_windsurf_skills.py"
+        "scripts/generate_windsurf_skills.py",
+        "scripts/generate_windsurf_hooks.py",
+        "scripts/generate_devin_hooks.py"
       ],
+      "status_note": "Windsurf rebranded to Devin Desktop on 2026-06-02. .devin/ is the primary read+write workspace tree; .windsurfrules, .windsurf/* and ~/.codeium/windsurf/* are legacy read-only fallbacks. Our generators dual-emit .devin/* + .windsurf/*. HOOKS MIGRATION (done): Cascade agent is available only through 2026-07-01 (Devin Local default since 2026-06-02), and the Cascade-scoped .windsurf/hooks.json (generate_windsurf_hooks.py, agent_action_name/tool_info format) dies with it — Devin CLI/Local do NOT read it as a fallback. generate_devin_hooks.py now emits .devin/hooks.v1.json in the Claude-compatible hook format Devin CLI uses (docs.devin.ai/cli/extensibility/hooks): Claude-style events (PreToolUse/PostToolUse/UserPromptSubmit/Stop/SessionStart) with matchers on Devin tool names (read/edit/exec/mcp__*), flat {decision,reason} block contract + exit 2. Globally-installed users ALSO inherit ~/.claude/settings.json hooks automatically (Devin read_config_from.claude defaults on). Both hook generators run at profile=full; drop generate_windsurf_hooks.py in the first release after 2026-07-01. Devin CLI ('Devin for Terminal', launched 2026-04-29) shares the Devin Local harness, reads AGENTS.md and the same SKILL.md standard; not yet tracked as a separate registry entry.",
       "capability_markers": [
         "Cascade",
         "windsurfrules",
@@ -204,6 +221,7 @@
         ".gemini/skills/*/SKILL.md",
         ".agents/skills/*/SKILL.md",
         "~/.gemini/skills/*/SKILL.md",
+        "~/.agents/skills/*/SKILL.md",
         ".gemini/extensions/gemini-extension.json"
       ],
       "our_generators": [
@@ -216,9 +234,13 @@
         "settings.json",
         "BeforeTool",
         "AfterTool",
+        "BeforeToolSelection",
         "BeforeAgent",
         "AfterAgent",
         "BeforeModel",
+        "AfterModel",
+        "Notification",
+        "PreCompress",
         "SessionStart",
         "SessionEnd",
         "SKILL.md",
@@ -246,11 +268,19 @@
         ".clinerules/workflows/*.md",
         ".clinerules/skills/*/SKILL.md",
         ".clinerules/hooks/",
+        ".cline/rules/*.md",
+        ".cline/hooks/",
+        ".cline/plugins/",
         ".cline/skills/*/SKILL.md",
+        "~/.cline/rules/",
+        "~/.cline/hooks/",
+        "~/.cline/plugins/",
         "~/.cline/skills/*/SKILL.md",
         "~/Documents/Cline/Rules/Hooks/",
         "~/.cline/data/settings/cline_mcp_settings.json",
-        ".claude/skills/*/SKILL.md"
+        ".claude/skills/*/SKILL.md",
+        "AGENTS.md",
+        "~/.agents/AGENTS.md"
       ],
       "our_generators": [
         "scripts/generate_cline.py",
@@ -267,7 +297,9 @@
         "hooks",
         "skills",
         "subagents",
-        "conditional rules"
+        "conditional rules",
+        "AGENTS.md",
+        "plugins"
       ],
       "version_probe": null
     },
@@ -357,11 +389,16 @@
       },
       "config_paths": [
         ".augment/rules/*.md",
-        ".augment/guidelines.md",
+        ".augment-guidelines",
         ".augment/agents/*.md",
         ".augment/commands/*.md",
         ".augment/skills/*/SKILL.md",
+        ".augment/settings.json",
+        ".augment/settings.local.json",
+        ".claude/skills/*/SKILL.md",
+        ".agents/skills/*/SKILL.md",
         "~/.augment/rules/*.md",
+        "~/.augment/user-guidelines.md",
         "~/.augment/agents/*.md",
         "~/.augment/commands/*.md",
         "~/.augment/settings.json",
@@ -369,7 +406,11 @@
       ],
       "our_generators": [
         "scripts/generate_augment.py",
-        "scripts/generate_augment_rules.py"
+        "scripts/generate_augment_rules.py",
+        "scripts/generate_augment_agents.py",
+        "scripts/generate_augment_commands.py",
+        "scripts/generate_augment_skills.py",
+        "scripts/generate_augment_hooks.py"
       ],
       "capability_markers": [
         ".augment",
@@ -388,6 +429,7 @@
         "SessionStart",
         "SessionEnd",
         "Stop",
+        "Notification",
         "ACP Mode"
       ],
       "version_probe": null
@@ -404,6 +446,9 @@
       "config_paths": [
         ".agents/rules/*.md",
         ".agents/workflows/*.md",
+        ".agents/skills/*/SKILL.md",
+        ".agents/hooks.json",
+        ".agents/mcp_config.json",
         ".agent/rules/*.md",
         ".agent/workflows/*.md",
         ".agent/skills/*/SKILL.md",
@@ -413,6 +458,7 @@
       "our_generators": [
         "scripts/generate_antigravity.py"
       ],
+      "status_note": "Antigravity CLI (GA 2026-05-19) reads workspace skills from .agents/skills/ (plural); the IDE still uses .agent/skills/ (singular) — our generator dual-emits the skill pointer to both. CLI hooks live in .agents/hooks.json with Claude-style event names (PreToolUse, not BeforeTool) and a JSON stdin/stdout decision contract. CLI MCP config is .agents/mcp_config.json with a required serverUrl field (url/httpUrl rejected silently); the GLOBAL MCP config path is reported inconsistently across sources (~/.gemini/antigravity-cli/ vs ~/.gemini/config/), so only the workspace path is registered until verified via agy inspect. Official docs are fully JS-rendered — the doctor is blind to them; verify changes manually each sync.",
       "capability_markers": [
         "Antigravity",
         "agent manager",
@@ -421,6 +467,7 @@
         "workflows",
         "rules",
         "skills",
+        "hooks",
         "AGENTS.md",
         "GEMINI.md",
         "agent permissions"
@@ -440,6 +487,7 @@
         "AGENTS.md",
         ".agents/skills/*/SKILL.md",
         ".codex/hooks.json",
+        ".codex/config.toml",
         "~/.codex/config.toml"
       ],
       "our_generators": [
@@ -489,8 +537,13 @@
         ".opencode/plugins/*",
         ".opencode/skills/*/SKILL.md",
         "AGENTS.md",
-        ".claude/skills/*/SKILL.md"
+        ".claude/skills/*/SKILL.md",
+        ".agents/skills/*/SKILL.md",
+        "~/.config/opencode/skills/*/SKILL.md",
+        "~/.claude/skills/*/SKILL.md",
+        "~/.agents/skills/*/SKILL.md"
       ],
+      "status_note": "opencode v1.16.0 (2026-06-05) ships an experimental v2 skill registry with flat-file skills and a 'slash' frontmatter key; undocumented as of 2026-06-09. Watch item: re-check next sync whether the v2 format reaches the documented SKILL.md spec before touching generate_opencode*.py. Note sst/opencode redirects to anomalyco/opencode.",
       "our_generators": [
         "scripts/generate_opencode.py",
         "scripts/generate_opencode_agents.py",

package/scripts/generate_antigravity.py

@@ -11,19 +11,19 @@ Antigravity reads rules from:
   * ``.agents/rules/*.md`` — per-category rule files (this generator)
   * ``.agents/workflows/*.md`` — workflow templates (this generator)
 
-Antigravity also supports the Agent Skills standard via ``.agent/skills/
-<skill-name>/SKILL.md`` (the changelog entry "Agent Skills now available in
-Antigravity" confirms this surface). We do not duplicate our full skill
-catalogue into ``.agent/skills/``; instead we emit a single pointer skill
-that teaches Antigravity to look up the real catalogue in
-``~/.softspark/ai-toolkit/app/skills/`` (global install) or
+Antigravity also supports the Agent Skills standard. The IDE reads
+``.agent/skills/<skill-name>/SKILL.md`` (singular), while the Antigravity CLI
+(GA 2026-05-19) reads ``.agents/skills/`` (plural) — so the skill pointer is
+dual-emitted to both. We do not duplicate our full skill catalogue; instead we
+emit a single pointer skill that teaches Antigravity to look up the real
+catalogue in ``~/.softspark/ai-toolkit/app/skills/`` (global install) or
 ``.claude/skills/`` (local install).
 
 Usage:
   python3 scripts/generate_antigravity.py [target-dir]
 
 Writes rules/workflows to target-dir/.agents/{rules,workflows}/ and the skill
-pointer to target-dir/.agent/skills/ (skills location is unchanged upstream).
+pointer to target-dir/.agent/skills/ (IDE) + target-dir/.agents/skills/ (CLI).
 """
 from __future__ import annotations
 
@@ -82,11 +82,17 @@ def _pointer_skill_md() -> str:
 
 
 def _write_skill_pointer(target_dir: Path) -> None:
-    """Write the pointer SKILL.md under .agent/skills/<name>/."""
-    skill_dir = target_dir / ".agent" / "skills" / POINTER_SKILL_NAME
-    skill_dir.mkdir(parents=True, exist_ok=True)
-    (skill_dir / "SKILL.md").write_text(_pointer_skill_md(), encoding="utf-8")
-    print(f"  Generated: .agent/skills/{POINTER_SKILL_NAME}/SKILL.md")
+    """Write the pointer SKILL.md for both the IDE and the CLI surface.
+
+    The IDE reads ``.agent/skills/`` (singular); the Antigravity CLI reads
+    ``.agents/skills/`` (plural).
+    """
+    content = _pointer_skill_md()
+    for tree in (".agent", ".agents"):
+        skill_dir = target_dir / tree / "skills" / POINTER_SKILL_NAME
+        skill_dir.mkdir(parents=True, exist_ok=True)
+        (skill_dir / "SKILL.md").write_text(content, encoding="utf-8")
+        print(f"  Generated: {tree}/skills/{POINTER_SKILL_NAME}/SKILL.md")
 
 
 # ---------------------------------------------------------------------------
@@ -97,10 +103,11 @@ def generate(target_dir: Path, *,
              language_modules: list[str] | None = None,
              rules_dir: Path | None = None,
              emit_skill_pointer: bool = True) -> None:
-    """Write ``.agents/rules/``, ``.agents/workflows/``, and ``.agent/skills/``.
+    """Write ``.agents/{rules,workflows}/`` and the dual skill pointers.
 
-    ``emit_skill_pointer`` controls whether the pointer SKILL.md is written.
-    Set to ``False`` if you manage ``.agent/skills/`` yourself.
+    ``emit_skill_pointer`` controls whether the pointer SKILL.md is written
+    to ``.agent/skills/`` (IDE) and ``.agents/skills/`` (CLI). Set to
+    ``False`` if you manage those directories yourself.
     """
     rules = dict(STANDARD_RULES)
     rules.update(build_language_rules(language_modules))

package/scripts/generate_cursor_mdc.py

@@ -1,9 +1,10 @@
 #!/usr/bin/env python3
 """Generate ``.cursor/rules/*.mdc`` files for Cursor IDE.
 
-Cursor reads rules from ``.cursor/rules/`` (since Cursor 0.45). Both ``.mdc``
-and plain ``.md`` extensions are accepted; we emit ``.mdc`` because only it
-carries the full YAML frontmatter used to control activation:
+Cursor reads rules from ``.cursor/rules/`` (since Cursor 0.45). Only ``.mdc``
+files are read — plain ``.md`` files in ``.cursor/rules/`` are ignored by the
+rules system (per cursor.com/docs/context/rules). ``.mdc`` carries the YAML
+frontmatter used to control activation:
 
   - ``alwaysApply: true``   — always in context
   - ``globs: ["**/*.ts"]``  — auto-attached for matching files