@softspark/ai-toolkit 3.0.0 → 3.0.2

package/CHANGELOG.md

@@ -7,6 +7,41 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.0.2 — Validation, Windows, Telemetry, and generate:all parity (2026-04-24)
+
+Patch release that closes known validation gaps, expands the hook-surface contracts, adds Windows dependency hints, exposes local product telemetry, and restores `npm run generate:all` parity with the CLI so registered custom rules reach every editor.
+
+### Added
+
+- **Hook surface validation** — `scripts/validate.py` now accepts the current Claude Code hook event surface, including `PostToolUseFailure`, `PostToolBatch`, and `UserPromptExpansion`.
+- **Hook handler contracts** — validation now checks supported handler types (`command`, `http`, `prompt`, `agent`, `mcp_tool`), required handler fields, and prompt/agent event compatibility.
+- **Language rule validation** — `scripts/validate.py` now checks `app/rules/<language>/*.md` frontmatter, category names, filename/category alignment, directory/language alignment, and required category coverage.
+- **Windows dependency hints** — `_common.detect_os()` recognizes Windows package managers (`winget`, Chocolatey, Scoop), and `check_deps.py` emits package install commands for Python, Git, Node, SQLite, and supported optional tooling.
+- **Product telemetry summary** — `ai-toolkit stats --summary` reports local usage telemetry; `--summary --json` emits machine-readable totals, coverage, unused catalog count, recent activity, and top skills.
+- **Dedicated gap tests** — added contracts for structured rules, Windows dependency support, council/brand-voice/introspect skill coverage, and `npm run generate:all` directory-rule generator coverage. Total test count: 945 -> 960.
+- **Windows Support KB** — new `kb/reference/windows-support.md` documents WSL, Git Bash, package managers, and hook runtime constraints.
+
+### Changed
+
+- **`package.json` `generate:all`** — now invokes all directory-based rule generators (`generate_cursor_mdc.py`, `generate_windsurf_rules.py`, `generate_roo_rules.py`, `generate_augment_rules.py`) so registered custom rules in `~/.softspark/ai-toolkit/rules/` propagate to every editor that supports per-rule module files. Restores parity with `ai-toolkit generate-all` (CLI).
+- **`app/skills/hook-creator/SKILL.md`** — documents the expanded hook event and handler type surface.
+- **`README.md` and `kb/reference/cli-reference.md`** — document `stats --summary` and Windows support.
+- **`kb/reference/hooks-catalog.md`** — documents the validated hook surface and non-command handler support.
+
+---
+
+## v3.0.1 — Release SOP Deep-Coverage Checks (2026-04-24)
+
+Doc-only patch. No code, generators, or runtime behavior changed.
+
+### Changed
+
+- **`kb/procedures/release-verification-sop.md` 1.3.0 -> 1.4.0** — added Phase 9 (six new checks for v3.0.0 native surfaces: `--profile full` emission, `--codex-skills` orthogonality, breaking-change surfaces at `standard`, install idempotence, live JSON parse, registry/generator drift). Refreshed stale thresholds (`Tests >= 350` -> `Tests >= 900`, `e.g., 669` -> `e.g., 945`). Editor list updated from 8 to 11 (+codex, +gemini, +opencode). Added HOME-scoped write safety warning.
+- **`kb/procedures/release-preparation-sop.md` 1.9.0 -> 1.10.0** — added the registry-vs-generators drift check to Phase 5 so a bad registry can never escape into a release.
+- **`kb/reference/supported-tools-registry.md` 1.1.0 -> 1.2.0** — enumerated the 11 new v3.0.0 generators (cursor_hooks/agents, windsurf_hooks, gemini_hooks/commands/skills, augment_hooks/agents/commands/skills, codex_skills) with profile and opt-in annotations.
+
+---
+
 ## v3.0.0 — Deep Coverage: Full Native Surface Utilization (2026-04-23)
 
 Skips `2.13.0`. Upgrade path is `2.12.x` -> `3.0.0`.

package/README.md

@@ -6,19 +6,29 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-99-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-945%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-960%20passing-success)](tests/)
 
 ---
 
-## What's New in v3.0.0
+## What's New in v3.0.2
+
+**3.0.2 is a patch release** that closes known validation gaps, expands the validated hook surface, adds Windows dependency hints, exposes local product telemetry, and restores `npm run generate:all` parity with the CLI.
+
+- `validate.py` now checks hook handler types, required handler fields, prompt/agent event compatibility, and structured language-rule frontmatter/category coverage.
+- Hook docs and validation now cover `PostToolUseFailure`, `PostToolBatch`, `UserPromptExpansion`, plus `command`, `http`, `prompt`, `agent`, and `mcp_tool` handler types.
+- `ai-toolkit stats --summary` reports local product telemetry: total invocations, unique skills used, catalog coverage, unused skills, recent activity, and top skills.
+- Windows dependency detection now emits package hints for `winget`, Chocolatey, and Scoop; WSL remains the recommended runtime for Bash hooks.
+- `npm run generate:all` now invokes every directory-based rule generator, so registered custom rules in `~/.softspark/ai-toolkit/rules/` propagate to every editor that supports per-rule module files.
+
+### Carried from v3.0.0 (feature release)
 
 - **Deep coverage: every editor at 100% of its native surface.** New generators emit hooks, sub-agents, custom commands, and skill pointers per editor: `generate_cursor_agents.py`, `generate_cursor_hooks.py`, `generate_windsurf_hooks.py`, `generate_gemini_commands.py`, `generate_gemini_hooks.py`, `generate_gemini_skills.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`, `generate_augment_skills.py`, `generate_codex_skills.py`.
 - **`--profile full`** turns on every native surface across all supported editors in one flag. `minimal` / `standard` / `strict` retain prior semantics but `standard` now also wires Gemini hooks and the Copilot directory layout (see Breaking Changes).
 - **Opt-in Codex skill mirroring** via `--codex-skills`. Codex gets the full skill catalog materialized under `.agents/skills/`; other editors stay on pointer-skill or compat-read.
-- **58 new bats tests** covering native surface generators (`tests/test_native_surfaces.bats`, `tests/test_skills_native.bats`) plus per-editor suites for aider, antigravity, augment, claude-code, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf.
+- **58 new bats tests** covering native surface generators plus per-editor suites for aider, antigravity, augment, claude-code, cline, codex, copilot, cursor, gemini, opencode, roo, windsurf.
 - **Skill quality pass** (folded in from the 2.12 work that is now skipped): 62 skills upgraded to 4-5 / 5 on the meta-architect audit; `add_gotcha` added as a fifth mutation strategy.
 
-### Breaking changes
+### Breaking changes (from 3.0.0)
 
 - `--profile standard` now installs **Gemini hooks** automatically. To opt out, use `--profile minimal` or pass `--skip gemini-hooks`.
 - Copilot now uses the **directory layout** (`.github/copilot/`) instead of a single monolithic file. Existing single-file installs are preserved but new installs emit the directory form.
@@ -59,6 +69,8 @@ npx @softspark/ai-toolkit install
 
 **That's it.** Claude Code picks up 99 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
+**Windows:** WSL is the recommended runtime. Native Windows works when Git Bash is available for hook scripts; dependency hints cover `winget`, Chocolatey, and Scoop. See [Windows Support](kb/reference/windows-support.md).
+
 ### Update
 
 ```bash
@@ -154,7 +166,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (945 tests)
+├── tests/               # Bats test suite (960 tests)
 └── CHANGELOG.md
 ```
 
@@ -180,6 +192,8 @@ ai-toolkit/
 
 **Persistent memory** — `memory-pack` plugin: SQLite + FTS5 search across past sessions.
 
+**Local product telemetry** — `ai-toolkit stats --summary` reports total invocations, skill coverage, unused catalog skills, recent activity, and top skills from local usage data.
+
 **Persona presets** — 4 roles (backend-lead, frontend-lead, devops-eng, junior-dev) adjust style and priorities.
 
 **Config inheritance** — Enterprise `extends` system with constitution immutability and enforcement constraints. See [Enterprise Config Guide](kb/reference/enterprise-config-guide.md).

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

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

package/app/skills/hook-creator/SKILL.md

@@ -30,6 +30,8 @@ Create a new Claude Code hook following ai-toolkit conventions.
 |-------|-----------|---------|-------------|
 | `PreToolUse` | Before a tool executes | tool name (e.g. `Bash`) or `if:` rule | Safety guards, validation, `"defer"` for headless |
 | `PostToolUse` | After a tool executes | tool name | Feedback loops, logging, format-on-save |
+| `PostToolUseFailure` | After a tool fails | tool name | Failure telemetry, recovery hints |
+| `PostToolBatch` | After a batch of tool calls completes | any | Batch summaries, aggregate validation |
 
 ### Turn lifecycle
 
@@ -37,6 +39,7 @@ Create a new Claude Code hook following ai-toolkit conventions.
 |-------|-----------|---------|-------------|
 | `Stop` | Claude finishes responding | any | Quality checks, session save |
 | `StopFailure` | Turn ends due to an API error (rate limit, auth) | any | Alerting, fallback behavior |
+| `UserPromptExpansion` | Claude expands or rewrites a submitted prompt | any | Prompt policy and context shaping |
 
 ### Subagent lifecycle
 
@@ -88,12 +91,13 @@ Create a new Claude Code hook following ai-toolkit conventions.
 
 ## Hook Handler Types
 
-Claude Code supports four handler `type` values in `hooks.json`:
+Claude Code supports five handler `type` values in `hooks.json`:
 
 | Type | Purpose | Required fields |
 |------|---------|-----------------|
 | `command` | Run a shell script / binary | `command` (path + args) |
-| `prompt` | Inject a prompt to the fast inline model and use its verdict | Handler-managed |
+| `http` | Call a local or remote HTTP endpoint | `url` |
+| `prompt` | Inject a prompt to the fast inline model and use its verdict | `prompt` |
 | `agent` | Spawn a full subagent to evaluate the event (must target `Stop` / `SubagentStop`) | `agent` (agent name) |
 | `mcp_tool` | Invoke an MCP tool directly (no subprocess) | `server`, `tool`, `arguments` |
 
@@ -137,7 +141,7 @@ Claude Code supports four handler `type` values in `hooks.json`:
 Required fields:
 - `_source`: always `"ai-toolkit"` (used by merge/strip logic)
 - `matcher`: tool name or regex for Pre/PostToolUse, empty string for global events
-- `hooks[].type`: `"command"`, `"prompt"`, `"agent"`, or `"mcp_tool"` (ai-toolkit uses `"command"`)
+- `hooks[].type`: `"command"`, `"http"`, `"prompt"`, `"agent"`, or `"mcp_tool"` (ai-toolkit uses `"command"`)
 - `hooks[].command`: path to script using `$HOME/.softspark/ai-toolkit/hooks/` prefix (for `type: command`)
 
 Optional fields (read from Claude Code docs, not emitted by ai-toolkit by default):

package/app/skills/introspect/SKILL.md

@@ -61,7 +61,7 @@ Answer these three questions:
 
 ## Step 4: Select Recovery Action
 
-Apply the **smallest possible fix** — do not restart from scratch unless absolutely necessary:
+Choose the **smallest recovery action** and apply the smallest possible fix — do not restart from scratch unless absolutely necessary:
 
 | Pattern | Recovery Action |
 |---------|----------------|

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-04-23T13:13:00Z",
+  "last_run": "2026-04-24T08:04:02Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "91dbc84ba3b8652b",
+      "docs_hash": "5754553b0e436fd7",
       "headings": [
         "Agent",
         "Code Completions",
@@ -57,7 +57,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "a117026a47c684b9",
+      "docs_hash": "0c111b1b1f28960d",
       "headings": [
         "Claude Code overview",
         "\u200bGet started",
@@ -102,10 +102,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.118 (Claude Code)"
+      "version": "2.1.119 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "5ed2cada4d9b3fa6",
+      "docs_hash": "17c24d27216f70cf",
       "headings": [
         "Cline CLI",
         "Cline Documentation",
@@ -135,7 +135,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "d66e6b65d5c69da4",
+      "docs_hash": "7a7f5cdf9411c5e2",
       "headings": [
         "About",
         "Contributing",
@@ -154,7 +154,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 732",
+        "Releases 735",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -184,10 +184,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.122.0"
+      "version": "codex-cli 0.124.0"
     },
     "cursor": {
-      "docs_hash": "594d7b663fb8b3e1",
+      "docs_hash": "a94b8e8f685b0831",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -203,7 +203,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "51d03cce48332772",
+      "docs_hash": "9415ea08e344013d",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -242,7 +242,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "377b588e529c7deb",
+      "docs_hash": "8bcd2db0db925807",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -290,7 +290,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "81d548872ef2d912",
+      "docs_hash": "760fbf466036892f",
       "headings": [
         "Add features",
         "Ask questions",
@@ -351,7 +351,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "99ecee90bc1efe60",
+      "docs_hash": "81d0aafbf97b18c8",
       "headings": [
         "Advanced",
         "App Deploys",

package/bin/ai-toolkit.js

@@ -74,7 +74,7 @@ const COMMANDS = {
   benchmark: 'Benchmark toolkit (--my-config to compare your setup vs defaults vs ecosystem)',
   'benchmark-ecosystem': 'Generate ecosystem benchmark snapshot (GitHub metadata + offline fallback)',
   evaluate: 'Run skill evaluation suite',
-  stats: 'Show skill usage statistics (--reset to clear, --json for raw output)',
+  stats: 'Show skill usage statistics (--summary for product telemetry, --reset to clear)',
   create: 'Scaffold new skill from template (e.g. create skill my-lint --template=linter)',
   mcp: 'Manage MCP templates and install native editor MCP configs',
   config: 'Manage config inheritance (validate, diff, init, create-base, check)',
@@ -280,6 +280,10 @@ function showHelp() {
   console.log('                                Remove from .mcp.json or native editor configs');
   console.log('\nOptions for doctor:');
   console.log('  --fix           Auto-repair detected issues');
+  console.log('\nOptions for stats:');
+  console.log('  --summary       Show aggregated product telemetry (usage coverage, top skills, unused catalog)');
+  console.log('  --json          Emit raw stats, or machine-readable telemetry when combined with --summary');
+  console.log('  --reset         Clear local usage stats');
   console.log('\nOptions for eject:');
   console.log('  [target-dir]    Target directory (default: current directory)');
   console.log('');

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

@@ -3,10 +3,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
@@ -278,7 +278,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
@@ -291,11 +299,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:

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.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
@@ -52,6 +52,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?
 ```
 
 ---
@@ -117,8 +121,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)
 
@@ -168,7 +172,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)
@@ -189,7 +193,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`
@@ -217,7 +221,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,
@@ -322,6 +326,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`
@@ -376,3 +475,8 @@ 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 |

package/kb/reference/cli-reference.md

@@ -2,9 +2,9 @@
 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."
 ---
 
@@ -111,7 +111,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`) |
@@ -119,6 +119,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

package/kb/reference/competitive-features-implementation.md

@@ -13,7 +13,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."
 ---
@@ -142,8 +142,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`
 
 ---
 
@@ -497,7 +497,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
 
 ---
 
@@ -516,7 +516,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
 
 ---
 
@@ -538,7 +538,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
 
 ---
 
@@ -660,9 +660,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
 
 ---

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,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."
 ---
 
@@ -15,6 +15,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