@softspark/ai-toolkit 3.0.0 → 3.0.2

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

@@ -3,9 +3,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.1.0"
+version: "1.2.0"
 created: "2026-04-23"
-last_updated: "2026-04-23"
+last_updated: "2026-04-24"
 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."
 ---
 
@@ -49,7 +49,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
 | Config paths | `.cursorrules`, `.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` |
+| 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) |
 | Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
 
 ### Windsurf
@@ -62,7 +62,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full) |
 | 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) |
 
@@ -86,7 +86,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| 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`, `Stop`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` |
 | Version probe | `gemini --version` |
 | Latest upstream | v0.39.0 (2026-04-23) |
@@ -136,7 +136,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| 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 |
 | SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
 
@@ -160,7 +160,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | 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) |

package/kb/reference/windows-support.md

@@ -0,0 +1,50 @@
+---
+title: "Windows Support"
+category: reference
+service: ai-toolkit
+tags: [windows, wsl, install, dependencies, hooks]
+created: "2026-04-24"
+last_updated: "2026-04-24"
+description: "Windows support model for ai-toolkit: WSL, Git Bash, dependency detection, and hook runtime constraints."
+---
+
+# Windows Support
+
+ai-toolkit supports Windows through two practical modes:
+
+1. **WSL recommended** — best compatibility for Bash hooks, POSIX paths, symlinks, and editor configs.
+2. **Native Windows with Git Bash** — supported for CLI usage when Bash is available on `PATH`.
+
+## Dependency Detection
+
+`scripts/check_deps.py` now emits install hints for Windows package managers:
+
+| Manager | Command Prefix |
+|---------|----------------|
+| winget | `winget install` |
+| Chocolatey | `choco install -y` |
+| Scoop | `scoop install` |
+
+Required dependency package IDs:
+
+| Dependency | winget | Chocolatey | Scoop |
+|------------|--------|------------|-------|
+| Python 3 | `Python.Python.3` | `python` | `python` |
+| Git | `Git.Git` | `git` | `git` |
+| Node.js | `OpenJS.NodeJS` | `nodejs` | `nodejs` |
+
+## Hook Runtime
+
+ai-toolkit hooks are Bash scripts. On Windows, use WSL or Git Bash so Claude Code can execute `~/.softspark/ai-toolkit/hooks/*.sh`.
+
+Cross-platform hooks should keep the Bash entrypoint small and delegate complex work to Python or Node when Windows behavior diverges.
+
+## Verification
+
+```bash
+ai-toolkit doctor
+python3 scripts/check_deps.py
+python3 scripts/validate.py
+```
+
+The Windows support contract is covered by `tests/test_windows_support.bats`.

package/llms-full.txt

@@ -58,6 +58,7 @@
 - [Supported Tools Registry](kb/reference/supported-tools-registry.md)
 - [Config Sync](kb/reference/sync.md)
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
+- [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)
 
 ## Skills
@@ -4242,10 +4243,10 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem]
-version: "1.9.0"
+version: "1.10.0"
 created: "2026-04-10"
-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."
+last_updated: "2026-04-24"
+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, the ecosystem-sync gate added in v1.9.0, and the registry-vs-generators drift gate added in v1.10.0."
 ---
 
 # SOP: Release Preparation
@@ -4517,7 +4518,15 @@ 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
 
-# Run npm test ONCE, cache output, parse from file. The suite is 669+ bats
+# Registry / generator drift (added in 1.10.0). Meta-generators excluded.
+META="generate_agents_md.py|generate_llms_txt.py"
+diff \
+  <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) \
+  <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) \
+  && echo "OK: registry matches filesystem" \
+  || { echo "DRIFT: update supported-tools-registry.md before tagging"; exit 1; }
+
+# Run npm test ONCE, cache output, parse from file. The suite is 900+ 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
@@ -4530,11 +4539,12 @@ echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp
 - `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
+- Registry drift: `OK: registry matches filesystem`. If `DRIFT:` appears, add the missing `scripts/generate_*.py` rows to `kb/reference/supported-tools-registry.md` before tagging.
 - `npm test`: `1..N` with zero `not ok` (read from the cached `/tmp/npm-test.log`, do not rerun)
 
 **One-liner:**
 ```bash
-python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && npm test
+python3 scripts/validate.py --strict && python3 scripts/audit_skills.py --ci && python3 scripts/audit_skills.py --sarif > audit.sarif && diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE 'generate_agents_md\.py|generate_llms_txt\.py' | sort -u) && npm test
 ```
 
 **If tests fail:** Fix the issue, do NOT skip. Common failures:
@@ -4678,10 +4688,10 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.3.0"
+version: "1.4.0"
 created: "2026-04-08"
-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)."
+last_updated: "2026-04-24"
+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 added the single-run npm test discipline; v1.4.0 adds v3.0.0 deep-coverage checks (--profile full, --codex-skills, breaking-change surfaces, idempotence, registry drift, live-JSON parse) and refreshes stale thresholds."
 ---
 
 # SOP: Release Verification
@@ -4727,6 +4737,10 @@ python3 scripts/audit_skills.py --ci                        # 10. Security audit
 python3 scripts/audit_skills.py --sarif | python3 -c "import json,sys; assert json.load(sys.stdin)['version']=='2.1.0'; print('SARIF OK')"   # 11. SARIF 2.1.0 well-formed?
 python3 scripts/audit_skills.py --permissions | head -30    # 12. Broad-access skills reviewed?
 npm view @softspark/ai-toolkit@X.Y.Z --json | python3 -c "import json,sys; d=json.load(sys.stdin); assert d['dist']['attestations']['provenance']['predicateType']=='https://slsa.dev/provenance/v1'; print('PROVENANCE OK')"   # 13. Provenance attested on npm?
+
+# Deep-coverage verification (Phase 9, v3.0.0+)
+META="generate_agents_md.py|generate_llms_txt.py"
+diff <(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u) <(ls scripts/generate_*.py | grep -vE "$META" | sort -u) && echo "OK: registry matches"   # 14. Registry <-> generators drift?
 ```
 
 ---
@@ -4792,8 +4806,8 @@ ai-toolkit status
 ```
 
 **Verify `--dry-run`:**
-- [ ] Agents >= 40
-- [ ] Skills >= 80
+- [ ] Agents >= 44
+- [ ] Skills >= 99
 - [ ] Hooks merged into settings.json
 - [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
 
@@ -4843,7 +4857,7 @@ cd - && rm -rf /tmp/ai-toolkit-verify
 - [ ] Would create: CLAUDE.md
 - [ ] Would create: .claude/settings.local.json
 - [ ] Would inject: .claude/constitution.md
-- [ ] Editors: all 8 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity)
+- [ ] Editors: all 11 listed (copilot, cursor, windsurf, cline, roo, aider, augment, antigravity, codex, gemini, opencode)
 - [ ] Would generate configs for each editor (legacy + directory-based)
 - [ ] Would install: .git/hooks/pre-commit
 - [ ] Would inject language rules (auto-detected)
@@ -4864,7 +4878,7 @@ python3 scripts/audit_skills.py --ci
 ```
 
 **Verify validate.py:**
-- [ ] Agents >= 40, Skills >= 80, Tests >= 350
+- [ ] Agents >= 44, Skills >= 99, Tests >= 900
 - [ ] Hook events: 12, Hook scripts: >= 20
 - [ ] Plugin packs >= 10, KB documents >= 20
 - [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
@@ -4892,7 +4906,7 @@ echo "exit:   $exit"
 
 **Verify:**
 - [ ] `exit == 0`
-- [ ] `ok == expected test count` (e.g., 669)
+- [ ] `ok == expected test count` (e.g., 945 on v3.0.0)
 - [ ] `not ok == 0`
 - [ ] Bats runs tests in parallel (4 jobs)
 - [ ] Groups: agents, autodetect, cli, generators, guards, hooks, inject,
@@ -4997,6 +5011,101 @@ AI_TOOLKIT_STRICT_PIN=1 ai-toolkit update --dry-run
 
 ---
 
+## Phase 9: Deep-Coverage Checks (v3.0.0+)
+
+These verify the native-surface generators shipped in v3.0.0 actually emit the right files for the right profiles, and that the tool registry stays in sync with shipped generators.
+
+> **Safety warning — HOME-scoped writes:** Running `--profile full` with `augment` in the editor list writes to `$HOME/.augment/settings.json` (Augment stores hooks under HOME, not per-project). Use `--dry-run` for verification unless you intend to carry ai-toolkit hook entries on this machine. The generator is marker-safe (only rewrites its own `_source: ai-toolkit` entries) but is still a side-effect.
+
+### 9.1 `--profile full` emits every native surface
+
+```bash
+D=/tmp/aitk-profile-full-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
+  --profile full --codex-skills --dry-run 2>&1 \
+  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.windsurf/hooks\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.codex/skills"
+```
+
+**Verify** — at least the following lines appear:
+- [ ] `.cursor/hooks.json` and `.cursor/agents/`
+- [ ] `.windsurf/hooks.json`
+- [ ] `.gemini/settings.json` hooks AND `.gemini/commands/`
+- [ ] `.augment/agents/` + `.augment/commands/` + `$HOME/.augment/settings.json`
+- [ ] `.codex/skills/` (opt-in via `--codex-skills`)
+
+### 9.2 `--codex-skills` is orthogonal to `--profile`
+
+```bash
+D=/tmp/aitk-codex-skills-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors codex --profile standard --codex-skills --dry-run 2>&1 \
+  | grep -q "Would generate: .codex/skills" && echo "OK: --codex-skills works without --profile full"
+ai-toolkit install --local --editors codex --profile full --dry-run 2>&1 \
+  | grep -q "Would generate: .codex/skills" && echo "FAIL: --profile full should NOT auto-emit .codex/skills" \
+  || echo "OK: --profile full alone does not auto-emit .codex/skills (correct — opt-in only)"
+```
+
+**Verify:**
+- [ ] `--codex-skills` emits `.codex/skills/` at any profile
+- [ ] `--profile full` alone does NOT emit `.codex/skills/` (must be opt-in)
+
+### 9.3 Breaking-change surfaces land on `--profile standard`
+
+v3.0.0 moved two surfaces from opt-in to default:
+- Copilot directory layout (`.github/instructions/`, `.github/prompts/`)
+- Gemini hooks (`.gemini/settings.json`)
+
+```bash
+D=/tmp/aitk-breaking-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors copilot,gemini --profile standard --dry-run 2>&1 \
+  | tee /tmp/aitk-breaking.log
+grep -q "\\.github/instructions/" /tmp/aitk-breaking.log && echo "OK: Copilot dir layout at standard"
+grep -q "\\.gemini/settings\\.json hooks" /tmp/aitk-breaking.log && echo "OK: Gemini hooks at standard"
+```
+
+**Verify both lines print `OK:`**. If either is missing, a regression has unwound the v3.0.0 breaking change.
+
+### 9.4 Install is idempotent
+
+```bash
+D=/tmp/aitk-idem-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
+SHA1=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+ai-toolkit install --local --editors cursor,gemini --profile full >/dev/null 2>&1
+SHA2=$(find .cursor .gemini -type f -exec shasum {} + | shasum | awk '{print $1}')
+[ "$SHA1" = "$SHA2" ] && echo "OK: idempotent" || echo "FAIL: install is not idempotent"
+```
+
+**Verify:** prints `OK: idempotent`. A second run must produce byte-identical files in every managed path.
+
+### 9.5 Live-install JSON outputs parse
+
+The bats suite validates JSON shape at generation time. This re-checks that what actually landed on disk after a live install parses without errors.
+
+```bash
+D=/tmp/aitk-json-${RANDOM} && mkdir -p "$D" && cd "$D" && git init -q
+ai-toolkit install --local --editors cursor,windsurf,gemini,augment --profile full >/dev/null 2>&1
+for f in .cursor/hooks.json .windsurf/hooks.json .gemini/settings.json $HOME/.augment/settings.json; do
+  [ -f "$f" ] && python3 -c "import json; json.load(open('$f'))" && echo "OK: $f"
+done
+```
+
+**Verify:** each emitted file prints `OK: <path>`. Any `json.decoder.JSONDecodeError` means the merge logic corrupted the output.
+
+### 9.6 Registry / generator drift check
+
+`kb/reference/supported-tools-registry.md` should enumerate every per-editor `scripts/generate_*.py` we ship. Meta-generators (`generate_agents_md.py`, `generate_llms_txt.py`) are excluded — they produce docs/artifacts, not editor configs.
+
+```bash
+META="generate_agents_md.py|generate_llms_txt.py"
+REG=$(grep -oE 'scripts/generate_[a-z_]+\.py' kb/reference/supported-tools-registry.md | sort -u)
+FS=$(ls scripts/generate_*.py | grep -vE "$META" | sort -u)
+diff <(echo "$REG") <(echo "$FS") && echo "OK: registry matches filesystem" || echo "DRIFT: update supported-tools-registry.md"
+```
+
+**Verify:** prints `OK: registry matches filesystem`. If not, add the missing rows to the registry before tagging the next release.
+
+---
+
 ## Troubleshooting
 
 ### `ai-toolkit: command not found`
@@ -5051,6 +5160,11 @@ ai-toolkit eject /tmp/test # retry
 | Tests | `npm test`: N/N passed, 0 failures |
 | Eject | Standalone `.claude/` with real files AND `output-styles/` directory |
 | Guards | Destructive commands blocked |
+| Deep coverage | `--profile full` emits all 9 v3.0.0 native surfaces; `--codex-skills` works orthogonally |
+| Breaking changes | Copilot directory layout + Gemini hooks emit at `--profile standard` (v3.0.0 contract) |
+| Idempotence | Second `install` run produces byte-identical output in every managed path |
+| Live JSON | Every generated `.json` file on disk parses as valid JSON |
+| Registry | `supported-tools-registry.md` enumerates every `scripts/generate_*.py` we ship |
 
 ---
 
@@ -6095,9 +6209,9 @@ The reference benchmark set is intentionally curated:
 title: "CLI Reference"
 category: reference
 service: ai-toolkit
-tags: [cli, commands, reference, install, update, plugin, mcp]
+tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
 created: "2026-04-13"
-last_updated: "2026-04-15"
+last_updated: "2026-04-24"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -6204,7 +6318,7 @@ Usage: ai-toolkit <command> [options]
 
 | Command | Description |
 |---------|-------------|
-| `stats` | Show skill usage statistics (`--reset` to clear, `--json` for raw output) |
+| `stats` | Show skill usage statistics (`--summary` for product telemetry, `--reset` to clear, `--json` for raw output) |
 | `benchmark --my-config` | Compare your config vs defaults vs ecosystem |
 | `benchmark-ecosystem` | Generate ecosystem benchmark snapshot |
 | `create skill <name>` | Scaffold new skill from template (`--template=linter\|reviewer\|generator\|workflow\|knowledge`) |
@@ -6212,6 +6326,17 @@ Usage: ai-toolkit <command> [options]
 | `compile-slm` | Compile toolkit into minimal SLM system prompt (`--budget`, `--model-size`, `--dry-run`) |
 | `evaluate` | Run skill evaluation suite |
 
+### `stats`
+
+```bash
+ai-toolkit stats                 # table of local skill usage
+ai-toolkit stats --summary       # product telemetry summary
+ai-toolkit stats --summary --json  # machine-readable telemetry
+ai-toolkit stats --reset         # clear local stats
+```
+
+`--summary` reports total invocations, unique skills used, catalog coverage, unused catalog skills, active skills in the last 7 days, and top skills. Data stays local in `~/.softspark/ai-toolkit/stats.json`.
+
 ## Install / Update Options
 
 ```bash
@@ -6425,7 +6550,7 @@ tags:
 doc_type: plan
 status: completed
 created: "2026-04-07"
-last_updated: "2026-04-09"
+last_updated: "2026-04-24"
 completion: "100%"
 description: "Implementation plan for features identified from competitive analysis of everything-claude-code and claude-mem. Focus on learning system, language rules, advanced hooks, MCP templates, and rag-mcp integration. COMPLETED: 8/9 features shipped (1 skipped). See kb/reference/ for permanent documentation."
 ---
@@ -6554,8 +6679,8 @@ app/rules/
 - [x] 13 languages × 5 rule files created (70 files: 13 dirs × 5 + 5 common)
 - [x] `ai-toolkit install --local` auto-detects language and injects rules (two-phase: marker files + extension scan)
 - [x] Manual override: `ai-toolkit install --local --lang typescript` (with aliases: go→golang, c++→cpp, cs→csharp)
-- [ ] validate.py checks rules format (not yet implemented)
-- [ ] Tests: >=13 (no test_rules file yet)
+- [x] validate.py checks rules format
+- [x] Tests: dedicated `tests/test_rules.bats`
 
 ---
 
@@ -6909,7 +7034,7 @@ context: fork
 - [x] `/council` invocable
 - [x] 4 perspectives generated
 - [x] Structured output with recommendation
-- [ ] Tests: dedicated council tests not yet written
+- [x] Tests: dedicated council skill contract
 
 ---
 
@@ -6928,7 +7053,7 @@ context: fork
 **Success Criteria:**
 - [x] Skill auto-loads when writing docs/content
 - [x] Anti-trope list prevents generic LLM rhetoric
-- [ ] Tests: dedicated brand-voice tests not yet written
+- [x] Tests: dedicated brand-voice skill contract
 
 ---
 
@@ -6950,7 +7075,7 @@ context: fork
 - [x] `/introspect` invocable when agent is stuck
 - [x] Classifies failure pattern
 - [x] Suggests recovery action
-- [ ] Tests: dedicated introspect tests not yet written
+- [x] Tests: dedicated introspect skill contract
 
 ---
 
@@ -7072,9 +7197,9 @@ npx @softspark/ai-toolkit inject-hook  ./rag-mcp-hooks.json    # NEW
 
 All major features shipped. Outstanding items:
 
-1. [ ] `validate.py` does not check rules format (1.1)
-2. [ ] No dedicated `test_rules` test file (1.1)
-3. [ ] No dedicated tests for council, brand-voice, introspect skills (3.1-3.3)
+1. [x] `validate.py` checks rules format (1.1)
+2. [x] Dedicated `test_rules` test file exists (1.1)
+3. [x] Dedicated tests exist for council, brand-voice, introspect skills (3.1-3.3)
 4. [x] `observe-session.sh` lives in rag-mcp (consumer), not ai-toolkit — by design
 
 ---
@@ -8046,9 +8171,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.4.2"
+version: "1.5.0"
 created: "2026-03-27"
-last_updated: "2026-04-09"
+last_updated: "2026-04-24"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -8058,6 +8183,12 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
+## Supported Surface
+
+`scripts/validate.py` validates both event names and handler shapes before release. The accepted lifecycle surface includes `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion` in addition to the installed ai-toolkit events below.
+
+Supported handler types are `command`, `http`, `prompt`, `agent`, and `mcp_tool`. ai-toolkit ships command hooks by default; non-command handlers are validated so external consumers can safely inject richer hook definitions through `inject-hook`.
+
 ## Installation
 
 ```bash
@@ -10687,9 +10818,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.1.0"
+version: "1.2.0"
 created: "2026-04-23"
-last_updated: "2026-04-23"
+last_updated: "2026-04-24"
 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."
 ---
 
@@ -10733,7 +10864,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
 | Config paths | `.cursorrules`, `.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` |
+| 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) |
 | Tracked capabilities | `cursorrules`, `.cursor/rules`, `AGENTS.md`, `mcp.json`, Composer, Agent Mode, hooks.json, subagents, skills, plugins |
 
 ### Windsurf
@@ -10746,7 +10877,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| Our generators | `scripts/generate_windsurf.py`, `scripts/generate_windsurf_rules.py`, `scripts/generate_windsurf_hooks.py` (profile=full) |
 | 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) |
 
@@ -10770,7 +10901,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| 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`, `Stop`, `SKILL.md`, `activate_skill`, custom commands, `gemini-extension.json` |
 | Version probe | `gemini --version` |
 | Latest upstream | v0.39.0 (2026-04-23) |
@@ -10820,7 +10951,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| 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 |
 | SPA caveat | Mintlify Next.js SPA; use `https://docs.augmentcode.com/<path>.md` siblings (discoverable via `/llms.txt`) for machine reads |
 
@@ -10844,7 +10975,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_rules.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | 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) |
@@ -11213,6 +11344,61 @@ Agents follow a research-before-action protocol enforced via rules:
 
 ---
 
+## kb/reference/windows-support.md
+
+---
+title: "Windows Support"
+category: reference
+service: ai-toolkit
+tags: [windows, wsl, install, dependencies, hooks]
+created: "2026-04-24"
+last_updated: "2026-04-24"
+description: "Windows support model for ai-toolkit: WSL, Git Bash, dependency detection, and hook runtime constraints."
+---
+
+# Windows Support
+
+ai-toolkit supports Windows through two practical modes:
+
+1. **WSL recommended** — best compatibility for Bash hooks, POSIX paths, symlinks, and editor configs.
+2. **Native Windows with Git Bash** — supported for CLI usage when Bash is available on `PATH`.
+
+## Dependency Detection
+
+`scripts/check_deps.py` now emits install hints for Windows package managers:
+
+| Manager | Command Prefix |
+|---------|----------------|
+| winget | `winget install` |
+| Chocolatey | `choco install -y` |
+| Scoop | `scoop install` |
+
+Required dependency package IDs:
+
+| Dependency | winget | Chocolatey | Scoop |
+|------------|--------|------------|-------|
+| Python 3 | `Python.Python.3` | `python` | `python` |
+| Git | `Git.Git` | `git` | `git` |
+| Node.js | `OpenJS.NodeJS` | `nodejs` | `nodejs` |
+
+## Hook Runtime
+
+ai-toolkit hooks are Bash scripts. On Windows, use WSL or Git Bash so Claude Code can execute `~/.softspark/ai-toolkit/hooks/*.sh`.
+
+Cross-platform hooks should keep the Bash entrypoint small and delegate complex work to Python or Node when Windows behavior diverges.
+
+## Verification
+
+```bash
+ai-toolkit doctor
+python3 scripts/check_deps.py
+python3 scripts/validate.py
+```
+
+The Windows support contract is covered by `tests/test_windows_support.bats`.
+
+---
+
 ## kb/troubleshooting/README.md
 
 ---

package/llms.txt

@@ -58,4 +58,5 @@
 - [Supported Tools Registry](kb/reference/supported-tools-registry.md)
 - [Config Sync](kb/reference/sync.md)
 - [Unique Features & Differentiators](kb/reference/unique-features.md)
+- [Windows Support](kb/reference/windows-support.md)
 - [Troubleshooting](kb/troubleshooting/README.md)

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "AI coding toolkit: 99 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",
@@ -62,7 +62,11 @@
     "generate:codex-rules": "python3 scripts/generate_codex_rules.py .",
     "generate:opencode-agents": "python3 scripts/generate_opencode_agents.py .",
     "generate:opencode-commands": "python3 scripts/generate_opencode_commands.py .",
-    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:cursor && npm run generate:windsurf && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:aider && npm run generate:llms"
+    "generate:cursor-mdc": "python3 scripts/generate_cursor_mdc.py .",
+    "generate:windsurf-rules": "python3 scripts/generate_windsurf_rules.py .",
+    "generate:roo-rules": "python3 scripts/generate_roo_rules.py .",
+    "generate:augment-rules": "python3 scripts/generate_augment_rules.py .",
+    "generate:all": "npm run generate:agents && npm run generate:codex-rules && npm run generate:opencode-agents && npm run generate:opencode-commands && npm run generate:cursor && npm run generate:cursor-mdc && npm run generate:windsurf && npm run generate:windsurf-rules && npm run generate:copilot && npm run generate:gemini && npm run generate:cline && npm run generate:roo && npm run generate:roo-rules && npm run generate:aider && npm run generate:augment-rules && npm run generate:llms"
   },
   "files": [
     "bin/",

package/scripts/_common.py

@@ -165,6 +165,27 @@ def detect_os() -> dict[str, str]:
             "install_cmd": install_cmd,
         }
 
+    if system == "windows":
+        managers = (
+            ("winget", "winget install"),
+            ("choco", "choco install -y"),
+            ("scoop", "scoop install"),
+        )
+        for manager, install_cmd in managers:
+            if shutil.which(manager):
+                return {
+                    "os": "Windows",
+                    "distro": platform.version(),
+                    "pkg_manager": manager,
+                    "install_cmd": install_cmd,
+                }
+        return {
+            "os": "Windows",
+            "distro": platform.version(),
+            "pkg_manager": "none",
+            "install_cmd": "",
+        }
+
     return {
         "os": system,
         "distro": "",