@softspark/ai-toolkit 3.0.1 → 3.1.0

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
@@ -81,8 +82,11 @@
 - **commit**: Create Conventional Commits with pre-commit validation
 - **content-moderation-patterns**: Loaded when user builds content moderation, safety filters, or policy enforcement with Claude. Covers pre-filter vs LLM-classify, category design, confidence thresholds, and human-in-the-loop.
 - **council**: 4-perspective decision evaluation for architecture choices. Use when user wants multi-angle analysis, needs to decide between alternatives, or mentions 'council', 'evaluate decision', 'pros cons'.
+- **cpp-rules**: C++ coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .cpp, .cc, .cxx, .hpp, .h, CMakeLists.txt, Makefile, GoogleTest, clang-tidy. Load when writing, reviewing, or editing C++ code.
 - **csharp-patterns**: C# and .NET development patterns: LINQ, async/await, dependency injection, records, nullable reference types, ASP.NET Core minimal APIs, EF Core, MediatR. Triggers: C#, .NET, dotnet, ASP.NET, EF Core, LINQ, IServiceCollection, record type, async C#, nullable reference types. Load when writing or reviewing C#/.NET code.
+- **csharp-rules**: C#/.NET coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .cs, .csproj, .sln, ASP.NET, ASP.NET Core, EF Core, LINQ, NUnit, xUnit, dotnet. Load when writing, reviewing, or editing C#/.NET code.
 - **cve-scan**: Scan project dependencies for known CVEs using native audit tools (npm, pip, composer, cargo, go, bundler, dart)
+- **dart-rules**: Dart/Flutter coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget. Load when writing, reviewing, or editing Dart/Flutter code.
 - **database-patterns**: Database schema design and query optimization: normalization, indexing strategies, joins, N+1, transactions, isolation levels, partitioning, EXPLAIN plans. Triggers: schema, table design, index, slow query, N+1, PostgreSQL, MySQL, SQL Server, SQL, EXPLAIN, query plan, transaction, deadlock. Load when designing tables or tuning queries.
 - **debug**: Debug errors and trace root causes systematically using logs, health checks, and hypothesis-driven investigation. Use when a bug or error message is in hand — not for architectural questions or when there is no reproducible symptom.
 - **debugging-tactics**: Root-cause debugging with 4-phase method: investigation, hypothesis, validation, fix. No fix without RCA. Triggers: bug, error, exception, stack trace, not working, intermittent, flaky, crash, regression, fails sometimes, why is X happening, broken after. Load when user reports a bug or asks to investigate failing code.
@@ -100,6 +104,7 @@
 - **fix**: Apply a targeted fix to a known bug or lint error and verify it with the same command that surfaced the problem. Use when the root cause is already identified — not for unknown symptoms or open-ended debugging.
 - **flutter-patterns**: Flutter and Dart development patterns: widget composition, state management (Riverpod/Bloc/Provider), navigation, async, platform channels, performance. Triggers: Flutter, Dart, widget, StatefulWidget, Riverpod, Bloc, Provider, pubspec, Navigator, platform channel, hot reload, StatelessWidget. Load when writing or reviewing Flutter code.
 - **git-mastery**: Advanced Git workflows: interactive rebase, bisect, reflog, cherry-pick, worktrees, history rewriting, submodules, large-file migration (LFS/filter-repo). Triggers: git rebase, bisect, cherry-pick, reflog, force push, history rewrite, detached HEAD, merge conflict, worktree, squash, fixup, submodule. Load when user needs non-trivial Git operations.
+- **golang-rules**: Go coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .go, go.mod, go.sum, Gin, Echo, Gorilla, testing, gofmt. Load when writing, reviewing, or editing Go code.
 - **grill-me**: Stress-test a plan or design through relentless Socratic questioning, walking down each decision branch until reaching shared understanding. Use when user wants to stress-test a plan, get grilled, validate assumptions, or mentions 'grill me'.
 - **health**: Report service and infrastructure health status via liveness/readiness checks, resource usage, and quick diagnostics. Use when the user asks whether services are up or degraded — not for deep debugging of a known error.
 - **hipaa-validate**: Validate code against HIPAA policy: PHI exposure, missing audit logging, unencrypted transmission/storage, access control gaps, temp file exposure, and missing BAA references
@@ -109,11 +114,14 @@
 - **instinct-review**: Review, promote, or remove learned instincts extracted from past sessions (`.claude/instincts/*.md`). Use when the user wants to curate the instinct list — not to extract new instincts or edit memory.
 - **introspect**: Agent self-debugging and recovery. Use when stuck in loops, making repeated errors, or quality degrades. Triggers: introspect, self-debug, stuck, loop, why failing.
 - **java-patterns**: Java development patterns: Spring Boot, CompletableFuture, records, sealed types, streams, JPA/Hibernate, Maven/Gradle, virtual threads (Loom). Triggers: Java, Spring, Spring Boot, JPA, Hibernate, Maven, Gradle, CompletableFuture, record type, sealed class, virtual thread. Load when writing or reviewing Java code.
+- **java-rules**: Java coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .java, pom.xml, build.gradle, Spring, Spring Boot, JPA, Hibernate, JUnit, Maven, Gradle. Load when writing, reviewing, or editing Java code.
 - **json-mode-patterns**: Loaded when user needs structured JSON output from Claude. Covers tool-use-as-JSON-mode, schema design, parsing, partial recovery, and validation.
 - **kotlin-patterns**: Kotlin development patterns: coroutines, Flow, sealed classes, data classes, extension functions, null safety, Ktor, Jetpack Compose, KMP. Triggers: Kotlin, coroutine, Flow, suspend, Ktor, Android Kotlin, Jetpack Compose, sealed class, data class, KMP, kotlinx. Load when writing or reviewing Kotlin code.
+- **kotlin-rules**: Kotlin coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .kt, .kts, build.gradle.kts, Ktor, Jetpack Compose, coroutines, kotlinx. Load when writing, reviewing, or editing Kotlin code.
 - **lint**: Run the project's linter and type-checker with auto-detected toolchain (ruff/mypy, eslint/tsc, phpstan, golangci-lint, clippy, dart analyze). Use when the user asks for static-analysis feedback — not to run tests or refactor.
 - **mcp-builder**: Build production-grade MCP (Model Context Protocol) servers from scratch using the 4-phase methodology: research, implement, test, evaluate. Use when creating new MCP integrations for external APIs, databases, or internal services.
 - **mcp-patterns**: MCP (Model Context Protocol) server design: tool schemas, resource patterns, transport selection (stdio/SSE), client configuration, error handling, capability negotiation. Triggers: MCP, Model Context Protocol, MCP server, MCP tool, MCP resource, JSON-RPC, stdio transport, SSE transport, Claude Desktop config, Cursor MCP. Load when building or integrating MCP servers.
+- **medplum-rules**: Medplum (FHIR healthcare) coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: medplum.config.mts, medplum.config.ts, FHIR, Medplum, Bot, Subscription, Questionnaire. Load when writing, reviewing, or editing Medplum (FHIR healthcare) code.
 - **mem-search**: Search past coding sessions using natural language. Finds relevant observations, decisions, and context from previous work.
 - **migrate**: Run or create database migrations with the detected tool (Alembic, Prisma, Laravel, Django, Flyway, Drizzle) and verify backups exist first. Use when the user asks to apply, roll back, or generate a migration — not for general schema design.
 - **migration-patterns**: Zero-downtime database migration patterns: expand-contract, double-write, backfill, blue-green schema changes, feature flags, rollback safety, online DDL. Triggers: migration, schema change, zero-downtime, expand-contract, double-write, backfill, ALTER TABLE, column rename, safe deploy, online DDL. Load when planning non-trivial DB schema changes.
@@ -125,6 +133,7 @@
 - **panic**: Emergency kill switch that halts all agent activity via a lockfile gate. Use when agents are looping, misbehaving, or the user wants to stop everything NOW — not for normal workflow interruptions.
 - **performance-profiling**: Performance measurement and optimization: four golden signals (latency/traffic/errors/saturation), p50/p95/p99, baseline-change-measure loop, flame graphs, load testing. Triggers: performance, slow, latency, p99, flame graph, profile, bottleneck, optimization, load test, benchmark, CPU profiling, memory leak. Load when diagnosing or optimizing slow code or services.
 - **persona**: Switch engineering persona at runtime: backend-lead, frontend-lead, devops-eng, junior-dev
+- **php-rules**: PHP coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .php, composer.json, Laravel, Symfony, PHPUnit, PSR-12, Composer. Load when writing, reviewing, or editing PHP code.
 - **plan**: Breaks down feature requests and project goals into phased implementation plans with task lists, agent assignments, dependency graphs, and success criteria. Use when the user asks to plan a feature, create an implementation roadmap, break down a coding task, or outline project phases.
 - **plan-writing**: Implementation plan and pre-mortem drafting: phase breakdown, success criteria, risks, rollback plan, acceptance tests, estimated effort. Triggers: implementation plan, pre-mortem, phased plan, project plan, task breakdown, success criteria, rollback strategy, risk register. Load when user asks to write a plan or pre-mortem document.
 - **plugin-creator**: Creates experimental opt-in plugin packs with manifests, conventions, and optional module scaffolding for Claude and Codex runtimes
@@ -133,6 +142,7 @@
 - **prd-to-plan**: Convert a PRD into a phased implementation plan using tracer-bullet vertical slices. Use when user wants to break down a PRD, create an implementation plan, plan phases from a PRD, or mentions tracer bullets.
 - **predict**: Analyzes code diffs and file changes to identify potential regressions, maps dependency impact across the codebase, and generates a risk-scored impact report. Use when reviewing pull requests, assessing code change risk, checking for breaking changes, or analyzing the blast radius of a diff.
 - **prompt-caching-patterns**: Loaded when user builds with Anthropic API and needs to cut cost or latency via prompt caching. Covers TTL, cache breakpoints, stacking, invalidation, and measuring hit rate.
+- **python-rules**: Python coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .py, .pyi, pyproject.toml, requirements.txt, Pipfile, FastAPI, Django, Flask, pytest, SQLAlchemy, ruff, mypy. Load when writing, reviewing, or editing Python code.
 - **qa-session**: Interactive QA session where user reports bugs conversationally and agent files GitHub issues with domain language. Explores codebase in background for context. Use when user wants to report bugs, do QA, file issues conversationally, or mentions QA session.
 - **rag-patterns**: RAG architecture: embeddings, chunking strategies, hybrid search (BM25 + vector), reranking, CRAG/self-correcting, multi-hop reasoning, evaluation metrics. Triggers: RAG, embedding, vector search, pgvector, Qdrant, Pinecone, Weaviate, chunking, reranker, retrieval, hybrid search, semantic search, knowledge base, cosine similarity. Load when building or tuning RAG systems.
 - **refactor**: Refactor code for quality and maintainability
@@ -142,7 +152,9 @@
 - **review**: Review code for quality, security, and correctness
 - **rollback**: Roll back a git commit, database migration, or deployment to a previous known-good state with safety checks and health verification. Use when the user wants to revert recent changes safely — not to undo local edits or halt the whole system.
 - **ruby-patterns**: Ruby and Rails development patterns: blocks, metaprogramming, ActiveRecord, Sidekiq, RSpec, Sorbet/RBS, Hanami, Roda, Rack middleware. Triggers: Ruby, Rails, ActiveRecord, Sidekiq, RSpec, gem, Gemfile, bundler, rake, Hanami, Sorbet. Load when writing or reviewing Ruby code.
+- **ruby-rules**: Ruby coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop. Load when writing, reviewing, or editing Ruby code.
 - **rust-patterns**: Rust development patterns: ownership, borrowing, lifetimes, async (Tokio), error handling (Result/anyhow/thiserror), traits, macros, zero-cost abstractions, unsafe boundaries. Triggers: Rust, borrow checker, lifetime, Tokio, async Rust, cargo, trait, impl, Result, unsafe, lifetime annotation, clippy. Load when writing or reviewing Rust code.
+- **rust-rules**: Rust coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test. Load when writing, reviewing, or editing Rust code.
 - **search**: Search the knowledge base with semantic and hybrid modes
 - **security-patterns**: Application security: OWASP Top 10, authN/authZ, input validation, secrets management, TLS, CSRF/XSS/SQLi, session handling, JWT, rate limiting, CSP. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, encryption, TLS, authentication, authorization, CSP, CORS, password hashing. Load when touching auth code, handling user input, or doing security review.
 - **seo-validate**: Validate code against SEO best practices: W3C semantics, meta/OG tags, Schema.org, hreflang, Core Web Vitals (LCP/INP/CLS), resource hints, GEO, SPA/SSG/CSR crawlability, technical SEO, accessibility-for-SEO. Supports React/Next/Nuxt/Astro/Gatsby/SvelteKit/Remix/Angular/Vue/static HTML.
@@ -151,12 +163,14 @@
 - **subagent-development**: Execute implementation plans using fresh subagents per task with two-stage review: spec compliance first, then code quality. Use when executing plans with independent tasks.
 - **swarm**: Execute tasks via Map-Reduce, Consensus, or Relay swarms
 - **swift-patterns**: Swift and iOS development patterns: SwiftUI, Combine, async/await, property wrappers, actors, Swift Package Manager, Core Data, UIKit interop, @MainActor. Triggers: Swift, SwiftUI, Combine, iOS, Xcode, actor, property wrapper, Core Data, SPM, UIKit, @MainActor, @State, @Binding. Load when writing or reviewing Swift code.
+- **swift-rules**: Swift coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .swift, Package.swift, .xcodeproj, SwiftUI, Combine, async/await, XCTest. Load when writing, reviewing, or editing Swift code.
 - **tdd**: Test-driven development with red-green-refactor loop and vertical slices. Use when user wants TDD, test-first development, red-green-refactor, or building features with tests driving the implementation.
 - **teams**: Launches pre-configured multi-agent teams for code review, debugging, feature development, security audits, and database migrations. Use when the user asks to start a multi-agent workflow, coordinate agent teams, run a team review, or needs parallel agent collaboration on a complex task.
 - **test**: Run the project's test suite with coverage reporting, auto-detecting the framework (pytest, vitest, jest, flutter test, go test, cargo test, phpunit). Use when the user asks to run existing tests — not to author new ones test-first.
 - **testing-patterns**: Testing strategy and craft: pyramid vs trophy, unit/integration/e2e split, fixtures, mocks vs fakes vs stubs, AAA pattern, flaky test diagnosis, coverage goals, property-based testing. Triggers: test, testing strategy, fixture, mock, stub, AAA, unit test, integration test, e2e, Playwright, Cypress, flaky, coverage, TDD, test pyramid. Load when writing, reviewing, or designing test suites.
 - **triage-issue**: Triage a bug by deeply exploring the codebase for root cause, then create a GitHub issue with a TDD-based fix plan. Mostly hands-off — minimal user interaction. Use when user reports a bug, wants to investigate an issue, mentions triage, or wants a fix plan.
 - **typescript-patterns**: TypeScript type safety patterns: strict mode, generics, conditional types, template literals, discriminated unions, branded types, Zod, satisfies operator, const assertions. Triggers: TypeScript, TS, generics, conditional type, utility type, strict, Zod, satisfies, discriminated union, type safety, type narrowing, template literal type. Load when writing or reviewing TypeScript code.
+- **typescript-rules**: TypeScript/JavaScript coding rules from ai-toolkit: coding-style, frameworks, patterns, security, testing. Triggers: .ts, .tsx, .js, .jsx, package.json, tsconfig.json, React, Next.js, Vue, Vite, Vitest, Jest, ESLint. Load when writing, reviewing, or editing TypeScript/JavaScript code.
 - **ubiquitous-language**: Extract a DDD-style ubiquitous language glossary from the conversation, flagging ambiguities and proposing canonical terms. Saves to UBIQUITOUS_LANGUAGE.md. Use when user wants to define domain terms, build a glossary, harden terminology, or mentions DDD or domain model.
 - **verification-before-completion**: Loaded when agent is about to claim work is complete, fixed, or passing — requires running verification commands and confirming output before making any success claims. Evidence before assertions, always.
 - **workflow**: Start and manage autonomous agent workflows
@@ -310,7 +324,7 @@ Definition of "100% coverage" chosen: **each editor works at 100% of its native
 
 | # | Decision | Rule |
 |---|----------|------|
-| 1 | Skill propagation | `.claude/skills/` canonical. Cursor/Windsurf/opencode → compat-read (nothing). Augment/Gemini/Antigravity → **pointer skill** (1 file per editor). Codex → opt-in `--codex-skills` flag emits full mirror |
+| 1 | Skill propagation | `.claude/skills/` canonical. Cursor/Windsurf/opencode → compat-read (nothing). Augment/Gemini/Antigravity → **pointer skill** (1 file per editor). Codex → native `.agents/skills/` mirror |
 | 2 | Global writes | Only `~/.claude/`. Cursor/Windsurf/opencode get global coverage via compat-read. Augment/Gemini/Roo require `--local` |
 | 3 | Surface activation | **`--profile full`** turns on every native surface. `standard` stays close to today's defaults but adds niepodważalne wypełnienia (Copilot wiring + Gemini hooks). `minimal` unchanged |
 | 4 | Default behavior | `--editors <name>` alone uses `standard`. Users who want the full stack pass `--profile full` |
@@ -354,13 +368,13 @@ Definition of "100% coverage" chosen: **each editor works at 100% of its native
 **Owned files**
 - New: `scripts/generate_gemini_skills.py` (`.gemini/skills/ai-toolkit-skill-catalogue/SKILL.md` — pointer)
 - New: `scripts/generate_augment_skills.py` (`.augment/skills/ai-toolkit-skill-catalogue/SKILL.md` — pointer)
-- New: `scripts/generate_codex_skills.py` (full mirror to `.codex/skills/<name>/SKILL.md` — gated by `--codex-skills` flag)
+- New: `scripts/generate_codex_skills.py` (Codex-native mirror to `.agents/skills/<name>/SKILL.md`)
 - New: `tests/test_skills_native.bats` (≥15 tests)
 
 **Must-haves**
 - Pointer pattern same as Antigravity: 1 file per editor referencing `~/.claude/skills/<name>` and listing the catalogue.
 - Codex mirror respects `user-invocable: false` (knowledge skills stay, task skills stay — Codex reads them all).
-- `--codex-skills` must be opt-in; default OFF.
+- Codex skills use the upstream `.agents/skills` discovery path.
 
 ### Bucket 4 — Install wiring + profile full + docs (devops-implementer)
 
@@ -701,7 +715,7 @@ Orchestrator's final output:
 
 ### Open items flagged for future passes
 
-1. **Native `.codex/skills/*/SKILL.md` emission** (class B) — would write ~99 skill directories. Needs opt-in flag + minor bump.
+1. **Native `.agents/skills/*/SKILL.md` emission** (class B) — writes the Codex skill catalog to the upstream discovery path.
 2. **`.opencode/skills/` duplication** — deferred indefinitely; `.claude/skills/` fallback already works.
 3. **New generators needed**: `generate_gemini_hooks.py`, `generate_augment_agents.py`, `generate_augment_commands.py`, `generate_augment_hooks.py`.
 4. **Cross-editor hooks unification**: Cursor and Windsurf both shipped `.cursor/hooks.json` and `.windsurf/hooks.json` — worth a dedicated shared-schema pass rather than per-editor copies.
@@ -4242,9 +4256,9 @@ title: "SOP: Release Preparation"
 category: procedures
 service: ai-toolkit
 tags: [sop, release, version, publish, changelog, semver, provenance, sarif, ecosystem]
-version: "1.10.0"
+version: "1.10.1"
 created: "2026-04-10"
-last_updated: "2026-04-24"
+last_updated: "2026-04-28"
 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."
 ---
 
@@ -4518,7 +4532,7 @@ python3 scripts/audit_skills.py --sarif > audit.sarif       # MANDATORY — GHAS
 python3 scripts/audit_skills.py --permissions               # review Bash/Write/Edit footprint
 
 # Registry / generator drift (added in 1.10.0). Meta-generators excluded.
-META="generate_agents_md.py|generate_llms_txt.py"
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.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) \
@@ -4543,7 +4557,7 @@ echo "ok: $(grep -c '^ok ' /tmp/npm-test.log) | not ok: $(grep -c '^not ok' /tmp
 
 **One-liner:**
 ```bash
-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
+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|generate_language_rules_skills\.py' | sort -u) && npm test
 ```
 
 **If tests fail:** Fix the issue, do NOT skip. Common failures:
@@ -4687,9 +4701,9 @@ title: "SOP: Release Verification"
 category: procedures
 service: ai-toolkit
 tags: [sop, verification, release, smoke-test, install, update, qa, provenance, sarif]
-version: "1.4.0"
+version: "1.4.1"
 created: "2026-04-08"
-last_updated: "2026-04-24"
+last_updated: "2026-04-28"
 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."
 ---
 
@@ -4738,7 +4752,7 @@ python3 scripts/audit_skills.py --permissions | head -30    # 12. Broad-access s
 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"
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.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?
 ```
 
@@ -4808,7 +4822,7 @@ ai-toolkit status
 - [ ] Agents >= 44
 - [ ] Skills >= 99
 - [ ] Hooks merged into settings.json
-- [ ] "Other AI Tools" section lists cursor, windsurf, gemini, augment (antigravity via --local)
+- [ ] "Other AI Tools" section lists documented global targets only: aider, augment, cline, codex, gemini, opencode, roo, windsurf (Cursor, Copilot, Antigravity via --local for rules)
 
 **Verify `status`:**
 - [ ] Version matches expected
@@ -5022,7 +5036,7 @@ These verify the native-surface generators shipped in v3.0.0 actually emit the r
 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"
+  | grep -E "\\.cursor/(hooks\\.json|agents)|\\.windsurf/hooks\\.json|\\.gemini/(settings\\.json|commands)|\\.augment/(agents|commands)|\\.agents/skills"
 ```
 
 **Verify** — at least the following lines appear:
@@ -5030,22 +5044,21 @@ ai-toolkit install --local --editors cursor,windsurf,gemini,augment,codex \
 - [ ] `.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`)
+- [ ] `.agents/skills/` (Codex native discovery path; refreshed by `--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"
+  | grep -q "Would refresh: .agents/skills" && echo "OK: --codex-skills refreshes .agents/skills 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)"
+  | grep -q "Would generate: .agents/skills" && echo "OK: Codex skills use .agents/skills at profile full"
 ```
 
 **Verify:**
-- [ ] `--codex-skills` emits `.codex/skills/` at any profile
-- [ ] `--profile full` alone does NOT emit `.codex/skills/` (must be opt-in)
+- [ ] `--codex-skills` refreshes `.agents/skills/` at any profile
+- [ ] `--profile full` never emits `.codex/skills/`; Codex skills use `.agents/skills/`
 
 ### 9.3 Breaking-change surfaces land on `--profile standard`
 
@@ -5095,7 +5108,7 @@ done
 `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"
+META="generate_agents_md.py|generate_llms_txt.py|generate_language_rules_skills.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"
@@ -5710,7 +5723,7 @@ Three tiers determine how to approach a task:
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 31 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 36 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 49 |
 
 ## Multi-Agent Execution
 
@@ -6208,9 +6221,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."
 ---
 
@@ -6317,7 +6330,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`) |
@@ -6325,6 +6338,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
@@ -6538,7 +6562,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."
 ---
@@ -6667,8 +6691,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`
 
 ---
 
@@ -7022,7 +7046,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
 
 ---
 
@@ -7041,7 +7065,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
 
 ---
 
@@ -7063,7 +7087,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
 
 ---
 
@@ -7185,9 +7209,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
 
 ---
@@ -7819,9 +7843,9 @@ title: "Global Install Model"
 category: reference
 service: ai-toolkit
 tags: [install, global, claude, codex, plugins, local-setup]
-version: "3.0.0"
+version: "3.0.1"
 created: "2026-03-26"
-last_updated: "2026-04-23"
+last_updated: "2026-04-28"
 description: "Reference description of the global install target, project-local editor setup, global Codex plugin layering, and command responsibilities in ai-toolkit."
 ---
 
@@ -7833,9 +7857,12 @@ description: "Reference description of the global install target, project-local
 
 That means one machine-level install provides agents, skills, hooks, and rules to every project without committing toolkit boilerplate into each repository.
 
-Codex remains project-local for the core toolkit install, but experimental
-plugin packs can now layer a global Codex target in `HOME` when explicitly
-installed with `ai-toolkit plugin install --editor codex`.
+Other editor targets are opt-in and only use documented file surfaces. Cursor
+rules stay project-local because Cursor's global user rules are managed through
+the settings UI, not a stable merge-safe file. Codex remains project-local for
+the core toolkit install, but experimental plugin packs can layer a global
+Codex target in `HOME` when explicitly installed with
+`ai-toolkit plugin install --editor codex`.
 
 ## Command Responsibilities
 
@@ -7866,7 +7893,25 @@ The `--profile` flag controls how much of each editor's native surface is activa
 | `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.
+`--codex-skills` is an independent opt-in flag (not part of profile) that materializes the full skill catalog under `.agents/skills/` for Codex. Other editors stay on compat-read or the per-editor pointer skill.
+
+## Global Editor Targets
+
+`ai-toolkit install --editors <name>` can write global files only for editors
+with documented, file-based config surfaces:
+
+- `windsurf`: `~/.codeium/windsurf/memories/global_rules.md`
+- `gemini`: `~/.gemini/GEMINI.md`
+- `augment`: `~/.augment/rules/ai-toolkit.md`
+- `cline`: `~/Documents/Cline/Rules/ai-toolkit-*.md`
+- `roo`: `~/.roo/rules/ai-toolkit-*.md`
+- `aider`: `~/.aider.conf.yml` plus `~/.aider-ai-toolkit-CONVENTIONS.md` when the YAML file does not already exist
+- `codex`: `~/AGENTS.md`, `~/.agents/rules/*`, `~/.agents/skills/*`, `~/.codex/hooks.json`
+- `opencode`: `~/.config/opencode/*`
+
+Cursor, GitHub Copilot, and Google Antigravity rule installs stay project-local.
+Their global MCP support, where available, is handled by `ai-toolkit mcp
+install`, not by the rule installer.
 
 ## Why global install is the default
 
@@ -7882,6 +7927,7 @@ These files still stay local to a repository as part of the core install model:
 - `.claude/settings.local.json`
 - `.mcp.json`
 - `.cursor/mcp.json`
+- `.roo/mcp.json`
 - `.github/mcp.json`
 - `.claude/constitution.md`
 - project `AGENTS.md`
@@ -7935,6 +7981,7 @@ If `.mcp.json` exists in the current project, `ai-toolkit install --local` mirro
 - `.claude/settings.local.json`
 - `.cursor/mcp.json` when `--editors cursor` is selected
 - `.github/mcp.json` when `--editors copilot` is selected
+- `.roo/mcp.json` when `--editors roo` is selected
 
 Global-only editor MCP configs are not written during `install --local`. Use `ai-toolkit mcp install --editor <name...>` for those targets.
 
@@ -8159,9 +8206,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."
 ---
 
@@ -8171,6 +8218,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
@@ -8705,19 +8758,22 @@ title: "Language Rules System"
 category: reference
 service: ai-toolkit
 tags: [rules, languages, coding-style, testing, patterns, security]
-version: "1.0.0"
+version: "2.0.0"
 created: "2026-04-07"
-last_updated: "2026-04-07"
-description: "Reference for the language-specific rules system: 14 languages, 5 categories per language, auto-detection."
+last_updated: "2026-04-28"
+description: "Reference for the language-specific rules system: 13 per-language rule sets shipped as knowledge skills, plus a common set inlined into CLAUDE.md."
 ---
 
 # Language Rules System
 
 ## Overview
 
-ai-toolkit ships language-specific rule files covering 14 languages/platforms plus a common set (see README.md for current count). Rules are plain Markdown files injected into `CLAUDE.md` via `ai-toolkit install --local`. They provide coding-style, testing, patterns, frameworks, and security guidance specific to each language.
+ai-toolkit ships rule content for 13 languages/platforms plus a language-agnostic common set. Source files live under `app/rules/` and are split into two delivery channels by `ai-toolkit install --local`:
+
+- **Common rules** (`app/rules/common/*.md`): full content is inlined into the project's `.claude/CLAUDE.md` under a single `<!-- TOOLKIT:language-rules START -->` marker. They cover coding-style, git-workflow, performance, security, and testing — concerns that apply regardless of language, so they stay always visible.
+- **Per-language rules** (`app/rules/<lang>/*.md`): emitted at build time as `<lang>-rules` knowledge skills under `app/skills/`. Each skill is `user-invocable: false`, so Claude loads it via the Agent Skills progressive-disclosure mechanism only when its description triggers match (file extensions, framework names, or matching keywords in the prompt).
 
-Rules are distinct from skills: rules are injected as static text into `CLAUDE.md` and are always visible to Claude, whereas skills are loaded contextually by agents.
+The skills are generated from the rule files via `python3 scripts/generate_language_rules_skills.py`, which is idempotent and rerun-safe. Other editors (Cursor, Windsurf, Cline, Roo, Augment, Codex, Copilot, Antigravity, Gemini, opencode) still receive the full per-language rule content via their own generators in `scripts/dir_rules_shared.py::build_language_rules()` — Claude is the only target where the per-language content is now skill-delivered rather than inlined.
 
 ## File Structure
 
@@ -8754,7 +8810,7 @@ app/rules/
 └── medplum/
 ```
 
-**Total: 14 directories × 5 files each + 3 standalone = 73 rule files** (see README.md for canonical count)
+**Total: 13 per-language directories × 5 files + 1 common directory × 5 files + 3 standalone files** (see README.md for canonical count). Per-language directories ship as `<lang>-rules` knowledge skills; the common directory is inlined into CLAUDE.md.
 
 ## Supported Languages
 
@@ -8839,15 +8895,45 @@ ai-toolkit install --local --modules core,agents
 
 The `--lang` flag accepts comma-separated language names and converts them to `rules-<lang>` modules. Common aliases are supported: `go` → `golang`, `c++` → `cpp`, `c#`/`cs` → `csharp`. Using `--lang` implies `--local` and disables auto-detection.
 
-Language rules are injected into the project `CLAUDE.md` between named markers:
+Common rules are injected into the project `CLAUDE.md` between a single named marker (the per-language markers from v1.x are no longer used):
 
 ```
-<!-- TOOLKIT:rules-typescript START -->
-... TypeScript rules content ...
-<!-- TOOLKIT:rules-typescript END -->
+<!-- TOOLKIT:language-rules START -->
+# Language Rules
+
+Common (language-agnostic) rules apply to every change in this project.
+Language-specific rules live in `<lang>-rules` knowledge skills (e.g.
+`python-rules`, `typescript-rules`) and load automatically when their
+triggers match.
+
+Detected languages: `python-rules`, `typescript-rules`.
+
+---
+
+... full content of app/rules/common/*.md inlined here ...
+<!-- TOOLKIT:language-rules END -->
+```
+
+Re-running `install --local` is idempotent — the existing block is replaced, not duplicated. Per-language rules are not injected into `CLAUDE.md` for Claude — they are loaded contextually via their respective `<lang>-rules` knowledge skills.
+
+### Generating language-rules skills
+
+The `<lang>-rules` skills under `app/skills/` are produced by:
+
+```bash
+python3 scripts/generate_language_rules_skills.py            # write all
+python3 scripts/generate_language_rules_skills.py --check    # dry-run, exit 1 on diff
+python3 scripts/generate_language_rules_skills.py --langs python,rust  # subset
 ```
 
-Re-running `install --local` is idempotent — existing blocks are replaced, not duplicated.
+The generator reads `app/rules/<lang>/*.md`, strips YAML frontmatter, concatenates the categories, and writes `app/skills/<lang>-rules/SKILL.md` with frontmatter:
+
+- `name: <lang>-rules`
+- `description: ...` — language label, rule categories, and concrete trigger keywords (file extensions, framework names) so the skill activates reliably when Claude is working on that language.
+- `user-invocable: false` — knowledge skill, no slash command.
+- `allowed-tools: Read` — the skill body is reference content, not an action.
+
+Rerunning the generator is idempotent. Editing rule files under `app/rules/<lang>/` and rerunning the generator is the canonical way to update a language skill.
 
 ## Manifest Module Names
 
@@ -8872,13 +8958,16 @@ Language rules are tracked as modules in `manifest.json`:
 
 ## Rules vs Skills
 
-| | Rules | Skills |
-|---|-------|--------|
-| Location | `app/rules/` | `app/skills/` |
-| Delivery | Injected into `CLAUDE.md` text | Loaded from `~/.claude/skills/` |
-| Visibility | Always visible in context | Loaded contextually by agents |
-| Scope | Per-language static guidance | Domain-specific agent behavior |
-| Install | `--local` only | Global install |
+| | Common rules | Per-language rules | Other skills |
+|---|---|---|---|
+| Source | `app/rules/common/` | `app/rules/<lang>/` | `app/skills/<name>/SKILL.md` |
+| Delivery to Claude | Inlined into project `CLAUDE.md` (`--local`) | Generated as `<lang>-rules` knowledge skills, loaded contextually | Loaded contextually by description match |
+| Visibility | Always in context | Loaded when triggers match (file extensions, framework names) | Loaded when triggers match |
+| Scope | Language-agnostic standards (security, git, testing, perf, style) | Per-language coding-style, frameworks, patterns, security, testing | Domain skills (testing, debugging, RAG, etc.) |
+| Install | `ai-toolkit install --local` | Global install (skills directory is symlinked) | Global install |
+| Other editors | Inlined into editor-specific rule files | Inlined into editor-specific rule files (still full content, not skills) | N/A |
+
+Per-language content delivered as a knowledge skill is the same Markdown that other editors receive inlined. The split exists only for Claude, where the Agent Skills progressive-disclosure mechanism keeps the system prompt small.
 
 ## Related Documentation
 
@@ -9065,9 +9154,9 @@ title: "AI Toolkit - MCP Editor Compatibility"
 category: reference
 service: ai-toolkit
 tags: [mcp, editors, compatibility, codex, cursor]
-version: "1.0.0"
+version: "1.1.0"
 created: "2026-04-12"
-last_updated: "2026-04-12"
+last_updated: "2026-04-28"
 description: "Official MCP support matrix and native config targets for editors supported by ai-toolkit."
 ---
 
@@ -9085,6 +9174,7 @@ ai-toolkit keeps `.mcp.json` as the project-level canonical template format and
 | Cursor | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors `mcpServers` directly |
 | GitHub Copilot | project + global | `.github/mcp.json`, `~/.copilot/mcp-config.json` | Adds Copilot-required `type` and `tools` fields |
 | Gemini CLI | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Merges `mcpServers` into settings JSON |
+| Roo Code | project | `.roo/mcp.json` | Mirrors `mcpServers` into the documented project-level MCP file |
 | Windsurf | global | `~/.codeium/windsurf/mcp_config.json` | Global-only JSON config |
 | Cline | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only JSON config |
 | Augment | global | `~/.augment/settings.json` | Global-only JSON settings file |
@@ -9096,7 +9186,6 @@ These editors are still supported by ai-toolkit for rules and instructions, but
 
 | Editor | Reason |
 |--------|--------|
-| Roo Code | MCP support exists, but no verified official file path was adopted in ai-toolkit |
 | Aider | No verified native MCP config surface was adopted in ai-toolkit |
 | Google Antigravity | MCP can be configured via UI/import flows, but no stable file target was adopted in ai-toolkit |
 
@@ -9115,6 +9204,7 @@ When `.mcp.json` exists in a project, `ai-toolkit install --local` mirrors its s
 - `.claude/settings.local.json`
 - `.cursor/mcp.json` when `--editors cursor` is selected
 - `.github/mcp.json` when `--editors copilot` is selected
+- `.roo/mcp.json` when `--editors roo` is selected
 
 Global-only clients are configured explicitly via `ai-toolkit mcp install --editor ...`.
 
@@ -9162,7 +9252,7 @@ ai-toolkit mcp remove <name>      # Remove from .mcp.json or native editor confi
 The `add` command merges the `mcpServers` block from the template into `.mcp.json`. If `.mcp.json` does not exist it is created. If the server name already exists in `.mcp.json`, the entry is overwritten with the template version.
 
 The `install` command renders the same canonical template into an editor-native config format:
-- JSON clients with `mcpServers` blocks: Claude Code, Cursor, Gemini CLI, Windsurf, Cline, Augment
+- JSON clients with `mcpServers` blocks: Claude Code, Cursor, Gemini CLI, Roo Code, Windsurf, Cline, Augment
 - JSON clients with additional transport metadata: GitHub Copilot
 - TOML clients: Codex CLI (`[mcp_servers.<name>]`)
 
@@ -9176,12 +9266,13 @@ When `install` runs with `--scope project`, ai-toolkit also updates the project'
 | `cursor` | project + global | `.cursor/mcp.json`, `~/.cursor/mcp.json` | Mirrors canonical `mcpServers` |
 | `copilot` | project + global | `.github/mcp.json`, `~/.copilot/mcp-config.json` | Adds `type` and `tools: ["*"]` automatically |
 | `gemini` | project + global | `.gemini/settings.json`, `~/.gemini/settings.json` | Uses Gemini CLI `mcpServers` format |
+| `roo` | project | `.roo/mcp.json` | Mirrors canonical `mcpServers` into Roo's project MCP file |
 | `windsurf` | global | `~/.codeium/windsurf/mcp_config.json` | Global-only official config |
 | `cline` | global | `~/.cline/data/settings/cline_mcp_settings.json` | Global-only official config |
 | `augment` | global | `~/.augment/settings.json` | Global-only settings file |
 | `codex` | global | `~/.codex/config.toml` | Rendered as TOML `mcp_servers` tables |
 
-Project-local `ai-toolkit install --local` also mirrors `.mcp.json` into Claude project settings plus selected project editors that have official repository/workspace MCP files (`cursor`, `copilot`).
+Project-local `ai-toolkit install --local` also mirrors `.mcp.json` into Claude project settings plus selected project editors that have official repository/workspace MCP files (`cursor`, `copilot`, `roo`).
 
 ## Template List
 
@@ -10800,9 +10891,9 @@ title: "Supported Tools Registry"
 category: reference
 service: ai-toolkit
 tags: [editors, platforms, generators, integration, ecosystem]
-version: "1.2.0"
+version: "1.2.1"
 created: "2026-04-23"
-last_updated: "2026-04-24"
+last_updated: "2026-04-28"
 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."
 ---
 
@@ -10844,8 +10935,8 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Docs | https://cursor.com/docs |
 | Changelog | https://cursor.com/changelog |
 | Stable docs mirror | https://cursor.com/llms.txt (all doc pages have .md twins) |
-| Config paths | `.cursorrules`, `.cursor/rules/*.mdc`, `.cursor/rules/*.md`, `AGENTS.md`, `.cursor/mcp.json`, `~/.cursor/mcp.json`, `.cursor/skills/*/SKILL.md`, `.cursor/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) |
+| 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` |
+| Compat read paths | `.claude/skills/`, `.claude/agents/`, `.agents/skills/` (Cursor cross-reads these so ai-toolkit's Claude/Codex installs work automatically) |
 | 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 |
 
@@ -10899,6 +10990,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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. |
+| Global install | `ai-toolkit install --editors cline` writes only documented global rules under `~/Documents/Cline/Rules/`; MCP remains managed by `ai-toolkit mcp install --editor cline`. |
 
 ### Roo Code
 
@@ -10907,10 +10999,10 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| Config paths | `.roomodes`, `.roo/rules/*.md`, `.roo/rules-{slug}/*.md`, `.roo/mcp.json`, `~/.roo/rules/`, `~/.roo/custom_modes.yaml`, `mcp_settings.json` (global via Roo settings UI) |
 | 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. |
+| Notes | `.roomodes` now includes `description` and `whenToUse` for every mode (since 2026-04). YAML `.roomodes` is upstream-preferred but not yet emitted — JSON is still accepted by Roo. Global install writes only `~/.roo/rules/` because the exact global MCP settings path is UI-managed. |
 
 ### Aider
 
@@ -10922,6 +11014,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| Global install | `ai-toolkit install --editors aider` creates `~/.aider.conf.yml` only when absent and always refreshes `~/.aider-ai-toolkit-CONVENTIONS.md`; existing YAML is preserved. |
 | Version probe | `aider --version` |
 | Latest upstream | v0.86.1 (Aug 2025) |
 
@@ -10956,11 +11049,11 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | 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` |
+| Config paths | `AGENTS.md`, `.agents/rules/*.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `~/.codex/config.toml` |
 | 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) |
+| Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |
 
 ### opencode
@@ -11326,6 +11419,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
 
 ---