@softspark/ai-toolkit 2.11.0 → 3.0.0

package/kb/procedures/release-preparation-sop.md

@@ -2,11 +2,11 @@
 title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
-tags: [sop, release, version, publish, changelog, semver, provenance, sarif]
-version: "1.7.0"
+tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem]
+version: "1.9.0"
 created: "2026-04-10"
-last_updated: "2026-04-18"
-description: "Step-by-step checklist for preparing a new ai-toolkit release — version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0."
+last_updated: "2026-04-23"
+description: "Step-by-step checklist for preparing a new ai-toolkit release — ecosystem-sync drift check, version sync, changelog, artifact regeneration, validation, and tagging. Run BEFORE every git tag. Includes mandatory Provenance, SARIF, and checksum-pin checks added in v2.8.0, the single-run npm test discipline added in v1.8.0, and the ecosystem-sync gate added in v1.9.0."
 ---
 
 # SOP: Release Preparation
@@ -17,20 +17,33 @@ Run this **before** tagging. After tagging and publishing, run the
 
 **Pipeline:**
 ```
-Release Preparation (this SOP) → git tag → CI publish → Release Verification SOP
+Ecosystem Sync SOP (drift check + generator updates)
+      ↓
+Release Preparation (this SOP)
+      ↓
+git tag → CI publish → Release Verification SOP
 ```
 
-**Time:** 5-10 minutes
+**Time:** 10-20 minutes (includes ecosystem sync review)
 
 ---
 
 ## Quick Checklist (TL;DR)
 
 ```bash
+# 0. Ecosystem sync (mandatory for minor/major releases; optional for patch)
+#    Full procedure: kb/procedures/ecosystem-sync-sop.md
+python3 scripts/ecosystem_doctor.py --format text > /tmp/eco-report.txt
+cat /tmp/eco-report.txt
+# If drift detected: stop here, follow ecosystem-sync-sop.md Phase 2-4 to
+# classify each drift (A-F), update generators as needed, refresh snapshot,
+# THEN resume this SOP.
+python3 scripts/ecosystem_doctor.py --update    # after all drift resolved
+
 # 1. Decide version bump
 #    patch (1.4.2 → 1.4.3): bugfix, typo, doc fix
-#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag
-#    major (1.4.2 → 2.0.0): breaking change
+#    minor (1.4.2 → 1.5.0): new feature, new skill, new flag, any ecosystem-class-B/F change
+#    major (1.4.2 → 2.0.0): breaking change, any ecosystem-class-D removed path
 
 # 2. Sync version across all files
 python3 scripts/sync_version.py X.Y.Z          # if script exists, else manual
@@ -42,7 +55,7 @@ python3 scripts/generate_codex_rules.py .
 python3 scripts/generate_llms_txt.py > llms.txt
 python3 scripts/generate_llms_txt.py --full > llms-full.txt
 
-# 5. Validate + audit + SARIF + test
+# 5. Validate + audit + SARIF + test + ecosystem check
 python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > /tmp/audit.sarif && npm test
 
 # 5a. Supply-chain standard (v2.8.0+) — non-negotiable
@@ -50,6 +63,9 @@ grep -q -- '--provenance' .github/workflows/publish.yml || { echo "MISSING --pro
 grep -q 'id-token: write'   .github/workflows/publish.yml || { echo "MISSING id-token: write"; exit 1; }
 python3 scripts/audit_skills.py --permissions   # review Bash/Write/Edit footprint
 
+# 5b. Ecosystem gate — snapshot must be current before tag
+python3 scripts/ecosystem_doctor.py --offline --check || { echo "STALE ecosystem snapshot — re-run doctor"; exit 1; }
+
 # 6. Commit + tag + push
 git add -A && git commit -m "chore: release vX.Y.Z"
 git tag vX.Y.Z
@@ -58,6 +74,60 @@ git push origin main --tags
 
 ---
 
+## Phase 0: Ecosystem Sync (MANDATORY for minor/major)
+
+Before touching version numbers, confirm the toolkit is aligned with the current state of every editor / platform it integrates with. Skipping this phase ships a release whose generators may lag a month-old CLI refactor, a rename of `.cursorrules` to `.cursor/rules/`, or a new hook event we do not yet emit.
+
+**When this phase is mandatory:**
+- Minor release (X.Y.0) — always
+- Major release (X.0.0) — always
+- Patch release (X.Y.Z) — only if the patch touches a generator or install flow
+
+**When to skip:** pure doc-only patches, SOP edits, internal refactors that do not touch `scripts/generate_*` or `app/skills/*/SKILL.md`.
+
+### 0.1 Run the doctor
+
+```bash
+python3 scripts/ecosystem_doctor.py --format text | tee /tmp/eco-report.txt
+```
+
+Output classifies every registered tool as **Clean**, **Drift**, or **Errored**.
+
+### 0.2 Act on drift
+
+For each drifting tool, follow [ecosystem-sync-sop.md](ecosystem-sync-sop.md) Phase 2-4:
+
+| Drift class | Release impact |
+|-------------|----------------|
+| A (cosmetic reword) | No version impact — refresh snapshot, continue |
+| B (new feature — integrate) | **Minor** version bump at minimum; new generator or extended generator |
+| C (new feature — not adopted) | No impact — note in registry |
+| D (deprecation) | **Minor** or **major** depending on user impact; add migration warning |
+| E (feature promoted to default) | **Minor**; simplify generator, keep fallback comment |
+| F (feature newly globally available) | **Minor**; may require new generator or new config path |
+
+If any B/D/E/F changes land in this preparation pass, mention them explicitly in the CHANGELOG entry (Phase 3) under a `Ecosystem` subsection.
+
+### 0.3 Refresh snapshot
+
+Once every drift is resolved (either by code change or by re-classifying as acceptable):
+
+```bash
+python3 scripts/ecosystem_doctor.py --update
+```
+
+This writes the new baseline to `benchmarks/ecosystem-doctor-snapshot.json`. Commit it as part of the release commit.
+
+### 0.4 Gate
+
+```bash
+python3 scripts/ecosystem_doctor.py --offline --check
+```
+
+Must exit `0`. If it exits `1`, the snapshot is stale — rerun Phase 0.3 or review the remaining drift.
+
+---
+
 ## Phase 1: Determine Version Bump
 
 Follow [Semantic Versioning](https://semver.org/):
@@ -207,7 +277,13 @@ python3 scripts/validate.py --strict
 python3 scripts/audit_skills.py --ci
 python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS ingest
 python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint
-npm test
+
+# Run npm test ONCE, cache output, parse from file. The suite is 669+ bats
+# cases — rerunning it per check wastes minutes. Do not pipe npm test into
+# tail/grep multiple times in the same session.
+npm test > /tmp/npm-test.log 2>&1
+tail -3 /tmp/npm-test.log
+echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
 ```
 
 **Expected results:**
@@ -215,7 +291,7 @@ npm test
 - `audit_skills.py --ci`: `HIGH: 0 | WARN: 0` (INFO is acceptable)
 - `audit_skills.py --sarif`: valid JSON, non-empty `runs[0].tool.driver.rules`
 - `audit_skills.py --permissions`: review `Skills with Bash + Write + Edit` list — any newly-added skill with broad access MUST be justified in the CHANGELOG entry
-- `npm test`: `1..N` with zero `not ok`
+- `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
 
 **One-liner:**
 ```bash
@@ -332,13 +408,16 @@ git push origin --delete vX.Y.Z
 
 | # | Step | Command / Action | Pass Criteria |
 |---|------|-----------------|---------------|
+| 0a | Ecosystem drift check | `ecosystem_doctor.py --format text` | All tools Clean, or drift classified and resolved |
+| 0b | Ecosystem snapshot refresh | `ecosystem_doctor.py --update` | `benchmarks/ecosystem-doctor-snapshot.json` updated |
+| 0c | Ecosystem gate | `ecosystem_doctor.py --offline --check` | Exit 0 |
 | 1 | Version bump type | Decide patch/minor/major | — |
 | 2 | `package.json` version | Edit `"version"` | Matches target |
 | 3 | `manifest.json` version | Edit `"version"` | Matches target |
 | 4 | `plugin.json` version | Edit `"version"` | Matches target |
 | 5 | `package-lock.json` | `npm install --package-lock-only` | Matches target |
 | 6 | Count sync | Check `package.json` description, README | `validate.py` passes |
-| 7 | CHANGELOG.md | Add release entry | Entry exists for vX.Y.Z |
+| 7 | CHANGELOG.md | Add release entry (incl. `Ecosystem` subsection if any B/D/E/F drift) | Entry exists for vX.Y.Z |
 | 8 | Regenerate artifacts | `generate_agents_md.py`, `generate_codex_rules.py`, `generate_llms_txt.py` | No unexpected diff |
 | 9 | Validate | `validate.py --strict` | 0 errors, 0 warnings |
 | 10 | Security audit (CI mode) | `audit_skills.py --ci` | 0 HIGH |

package/kb/procedures/release-verification-sop.md

@@ -3,10 +3,10 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.2.0"
+version: "1.3.0"
 created: "2026-04-08"
-last_updated: "2026-04-18"
-description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard."
+last_updated: "2026-04-21"
+description: "End-to-end smoke test after installing or updating @softspark/ai-toolkit — verifies CLI, install, doctor, validation, tests, eject, npm provenance attestation, SARIF audit, and per-skill permissions. Reflects the v2.8.0 supply-chain standard. v1.3.0 adds the single-run npm test discipline (cache to file, parse ok/not-ok once)."
 ---
 
 # SOP: Release Verification
@@ -39,7 +39,7 @@ python3 scripts/generate_agents_md.py > AGENTS.md           # 1. Regenerate AGEN
 python3 scripts/generate_codex_rules.py .                   # 2. Refresh standard Codex rules
 python3 scripts/generate_llms_txt.py > llms.txt             # 3. Regenerate llms.txt
 python3 scripts/validate.py --strict                        # 4. Validation passed?
-npm test                                                    # 5. All tests passed?
+npm test > /tmp/npm-test.log 2>&1 && grep -c '^ok ' /tmp/npm-test.log && ! grep -q '^not ok' /tmp/npm-test.log  # 5. All tests passed? (single run, cached)
 
 # Post-install verification (Phases 1-7)
 ai-toolkit --version                                        # 6. Version OK?
@@ -204,15 +204,33 @@ python3 scripts/audit_skills.py --ci
 ## Phase 6: Tests (3-5 min)
 
 ```bash
-npm test
+# Run ONCE, capture to file, then parse. Full suite is 669+ bats cases —
+# re-running it per check (tail / grep ok / grep not ok piped separately)
+# wastes minutes every release. Always cache the output.
+npm test > /tmp/npm-test.log 2>&1
+exit=$?
+tail -3 /tmp/npm-test.log
+echo "ok:     $(grep -c '^ok '    /tmp/npm-test.log)"
+echo "not ok: $(grep -c '^not ok' /tmp/npm-test.log)"
+echo "exit:   $exit"
 ```
 
 **Verify:**
+- [ ] `exit == 0`
+- [ ] `ok == expected test count` (e.g., 669)
+- [ ] `not ok == 0`
 - [ ] Bats runs tests in parallel (4 jobs)
-- [ ] All `ok` — zero `not ok`
 - [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
       install, kb, mcp, readme, profiles, uninstall, validate
 
+**Anti-pattern — do NOT do this:**
+```bash
+# Runs the full suite THREE times. Adds 1-3 min and pressures CI capacity.
+npm test 2>&1 | tail -3
+npm test 2>&1 | grep -c '^ok '
+npm test 2>&1 | grep -c '^not ok'
+```
+
 **Key test areas:**
 - Guards: rm -rf, DROP TABLE, git push --force blocked
 - Install: idempotent, profiles, --only/--skip, orphan cleanup

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

@@ -3,9 +3,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "1.4.4"
+version: "3.0.0"
 created: "2026-03-26"
-last_updated: "2026-04-13"
+last_updated: "2026-04-23"
 description: "Reference description of the global install target, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -39,6 +39,19 @@ installed with `ai-toolkit plugin install --editor codex`.
 | `ai-toolkit plugin update --editor claude|codex|all <name>` | runtime-native config | re-apply plugin pack after toolkit updates |
 | `ai-toolkit plugin remove --editor claude|codex|all <name>` | runtime-native config | remove plugin pack from selected runtime(s) |
 
+## Install Profiles (v3.0.0)
+
+The `--profile` flag controls how much of each editor's native surface is activated.
+
+| Profile | What runs | Use when |
+|---------|-----------|----------|
+| `minimal` | Agents and skills only. No editor generators beyond pointer skills for editors that require them. | You want the smallest possible footprint, or you manage editor configs by hand. |
+| `standard` (default) | Claude Code + editor rule files. Includes **Gemini hooks** and the **Copilot directory layout** (v3.0.0 change from prior `standard`). | Day-to-day installs. Most users. |
+| `strict` | Everything in `standard` plus git-hook wiring for commit-time safety checks. | Solo dev or tight team with zero tolerance for drift. |
+| `full` | Every native surface across every editor: hooks, sub-agents, custom commands, skill pointers for Cursor / Windsurf / Gemini / Augment / Antigravity. | You want maximum coverage and understand that each editor will carry generated files under its own layout. |
+
+`--codex-skills` is an independent opt-in flag (not part of profile) that materializes the full `.claude/skills/` catalog under `.agents/skills/` for Codex. Other editors stay on compat-read or the per-editor pointer skill.
+
 ## Why global install is the default
 
 - less setup friction,

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

@@ -0,0 +1,229 @@
+---
+title: "Supported Tools Registry"
+category: reference
+service: ai-toolkit
+tags: [editors, platforms, generators, integration, ecosystem]
+version: "1.1.0"
+created: "2026-04-23"
+last_updated: "2026-04-23"
+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."
+---
+
+# Supported Tools Registry
+
+The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed by `scripts/ecosystem_doctor.py`. This document is a derived view — when the JSON changes, update this table too.
+
+## Tool Count: 12
+
+1 primary runtime (Claude Code) + 11 editor integrations.
+
+---
+
+## Primary Runtime
+
+### Claude Code
+
+| Field | Value |
+|-------|-------|
+| ID | `claude-code` |
+| Docs | https://platform.claude.com/docs/en/claude-code |
+| Release notes | https://github.com/anthropics/claude-code/releases |
+| Config paths | `~/.claude/settings.json`, `.claude/settings.local.json`, `CLAUDE.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`. Tool: `PreToolUse`, `PostToolUse`. Turn: `Stop`, `StopFailure`. 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` |
+| Other capabilities | slash commands, MCP server/client, sub-agent, output style, `SKILL.md` (≥500 lines warn) |
+| Version probe | `claude --version` |
+
+---
+
+## Editor Integrations
+
+### Cursor
+
+| Field | Value |
+|-------|-------|
+| ID | `cursor` |
+| 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/agents/*.md`, `.cursor/hooks.json`, `~/.cursor/hooks.json` |
+| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.codex/skills/`, `.codex/agents/` (Cursor cross-reads these so ai-toolkit's Claude install works automatically) |
+| Our generators | `scripts/generate_cursor_rules.py`, `scripts/generate_cursor_mdc.py` |
+| Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
+
+### Windsurf
+
+| Field | Value |
+|-------|-------|
+| ID | `windsurf` |
+| Docs | https://docs.windsurf.com |
+| Changelog | https://windsurf.com/changelog |
+| Stable docs mirror | https://docs.windsurf.com/llms.txt + per-page .md twins |
+| Config paths | `.windsurfrules`, `.windsurf/rules/*.md`, `.windsurf/workflows/*.md`, `AGENTS.md`, `~/.codeium/windsurf/memories/global_rules.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` |
+| Tracked capabilities | Cascade, `windsurfrules`, `AGENTS.md`, activation triggers (`always_on`/`glob`/`model_decision`), workflows, MCP, memories, hooks |
+| Activation modes emitted | always_on (agents/security/quality), glob (testing + language rules), model_decision (code-style/workflow) |
+
+### GitHub Copilot
+
+| Field | Value |
+|-------|-------|
+| 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`, MCP |
+| 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). |
+
+### Gemini CLI
+
+| Field | Value |
+|-------|-------|
+| 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` |
+| Our generators | `scripts/generate_gemini.py` |
+| Tracked capabilities | `GEMINI.md`, `mcpServers`, tools, `settings.json`, `BeforeTool`, `AfterTool`, `BeforeAgent`, `AfterAgent`, `BeforeModel`, `SessionStart`, `SessionEnd`, `Stop`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` |
+| Version probe | `gemini --version` |
+| Latest upstream | v0.39.0 (2026-04-23) |
+
+### Cline
+
+| Field | Value |
+|-------|-------|
+| ID | `cline` |
+| Docs | https://docs.cline.bot |
+| Release notes | https://github.com/cline/cline/releases |
+| Config paths | `.clinerules/*.md`, `.clinerules/workflows/*.md`, `.clinerules/hooks/`, `.cline/skills/`, `~/.cline/data/settings/cline_mcp_settings.json`, `~/Documents/Cline/Rules/` |
+| Our generators | `scripts/generate_cline.py`, `scripts/generate_cline_rules.py` |
+| Tracked capabilities | `clinerules`, Plan Mode, Act Mode, MCP, custom modes, workflows, hooks, skills, subagents, conditional rules |
+| Notes | Conditional rules (`paths:` YAML frontmatter) are emitted for testing and language-specific rules since 2026-04. Skills (`.cline/skills/`) and hooks (`.clinerules/hooks/`) remain experimental upstream and are not yet generated. |
+
+### Roo Code
+
+| Field | Value |
+|-------|-------|
+| ID | `roo-code` |
+| Docs | https://docs.roocode.com |
+| Release notes | https://github.com/RooCodeInc/Roo-Code/releases |
+| Config paths | `.roomodes`, `.roo/rules/*.md`, `.roo/rules-{slug}/*.md`, `.roo/mcp.json`, `~/.roo/rules/`, `~/.roo/settings/custom_modes.yaml`, `~/.roo/settings/mcp_settings.json` |
+| 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. |
+
+### Aider
+
+| Field | Value |
+|-------|-------|
+| ID | `aider` |
+| Docs | https://aider.chat/docs |
+| Changelog | https://aider.chat/HISTORY.html |
+| Config paths | `.aider.conf.yml`, `CONVENTIONS.md`, `~/.aider.conf.yml` |
+| Our generators | `scripts/generate_aider_conf.py`, `scripts/generate_conventions.py` |
+| Tracked capabilities | `.aider.conf.yml`, `CONVENTIONS.md`, `architect`, `auto-accept-architect`, `read`, `lint-cmd`, `test-cmd`, `commit-prompt`, `attribute-co-authored-by`, `chat-language`, `commit-language`, `watch-files`, `auto-commits` |
+| Version probe | `aider --version` |
+| Latest upstream | v0.86.1 (Aug 2025) |
+
+### Augment
+
+| Field | Value |
+|-------|-------|
+| 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` |
+| Our generators | `scripts/generate_augment.py`, `scripts/generate_augment_rules.py` |
+| 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 |
+| SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
+
+### Google Antigravity
+
+| Field | Value |
+|-------|-------|
+| 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 | `.agent/rules/*.md`, `.agent/workflows/*.md`, `.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. |
+
+### Codex CLI
+
+| Field | Value |
+|-------|-------|
+| ID | `codex-cli` |
+| Docs | https://github.com/openai/codex (redirects from developers.openai.com/codex) |
+| Release notes | https://github.com/openai/codex/releases |
+| Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.codex/hooks.json`, `.codex/skills/*/SKILL.md`, `~/.codex/config.toml` |
+| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py` |
+| Tracked hook events | `PreToolUse`, `PostToolUse`, `SessionStart`, `UserPromptSubmit`, `Stop`, `PermissionRequest` (6 events supported upstream in `config.toml`) |
+| Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
+| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.codex/skills/*/SKILL.md` (native discovery, not auto-emitted by ai-toolkit yet) |
+| Version probe | `codex --version` |
+
+### opencode
+
+| Field | Value |
+|-------|-------|
+| 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) |
+| 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` |
+
+---
+
+## How the Registry is Consumed
+
+```
+┌─────────────────────────┐
+│  ecosystem_tools.json   │  ← authoritative config (this doc mirrors it)
+└──────────┬──────────────┘
+           │ read
+           ▼
+┌─────────────────────────┐     ┌─────────────────────────────────┐
+│  ecosystem_doctor.py    │◄───►│  ecosystem-doctor-snapshot.json │  (last-seen state)
+└──────────┬──────────────┘     └─────────────────────────────────┘
+           │ emits
+           ▼
+    Drift report  (JSON or text)  →  human review  →  generator updates  →  commit
+```
+
+---
+
+## Adding a New Tool
+
+1. Append an entry to `scripts/ecosystem_tools.json` with all required fields (schema: `schema_version: 1`).
+2. Add a generator under `scripts/generate_<tool>_*.py` (or link to an existing one).
+3. Update this registry doc with a new section matching the format above.
+4. Baseline the snapshot: `python3 scripts/ecosystem_doctor.py --update --tool <id>`.
+5. Run the doctor again to confirm clean state: `python3 scripts/ecosystem_doctor.py --tool <id> --format text`.
+6. Update tool count at the top of this document.
+
+---
+
+## Removing a Tool
+
+1. Delete the tool's entry from `scripts/ecosystem_tools.json`.
+2. Delete its section from this document.
+3. Delete its snapshot entry from `benchmarks/ecosystem-doctor-snapshot.json` (or let the next `--update` prune it — currently not pruned automatically).
+4. Decide whether to keep the generator (`scripts/generate_<tool>_*.py`) for backwards compatibility or delete it.
+5. Remove references from `README.md`, `manifest.json` `description` field, and `kb/procedures/maintenance-sop.md` `Supported editors` line.
+
+---
+
+## Related
+
+- [Ecosystem Sync SOP](../procedures/ecosystem-sync-sop.md) — how to use the doctor
+- [MCP Editor Compatibility](./mcp-editor-compatibility.md) — MCP-specific subset
+- `scripts/ecosystem_tools.json` — source of truth
+- `scripts/ecosystem_doctor.py` — drift detector
+- `benchmarks/ecosystem-doctor-snapshot.json` — last-seen state