@softspark/ai-toolkit 4.31.0 → 4.32.0

package/CHANGELOG.md

@@ -7,6 +7,95 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.32.0 - Context budget: scoped rules, scoped language skills, doctor budget checks (2026-09-04)
+
+### Added
+
+- **`install --language-skills detected|all`.** Language knowledge skills
+  (`<lang>-rules`, `<lang>-patterns`) for languages no registered project uses
+  are turned off through `skillOverrides` in `~/.claude/settings.json`. The
+  entries the toolkit wrote are tracked in `state.json` and restored when a
+  newly registered project brings the language back; a user's own override is
+  never touched; with no registered project on disk nothing is disabled. `all`
+  restores everything and persists the choice.
+- **`doctor` check 12, Context Budget.** Estimated resident tokens of the
+  model-visible skill listing (against `skillListingBudgetFraction`), the agent
+  listing, and always-loaded user memory, plus skills with zero recorded use in
+  both Claude Code's counters and the toolkit's `stats.json`. Read-only; prints
+  the `skillOverrides` key to paste.
+- **`doctor` check 13, Permission Rules.** Warns on `permissions.allow`
+  wildcards that pre-approve execution or writes: interpreters, task runners,
+  package installs, `gh api`, `curl`/`wget`, `git fetch`/`pull`, destructive
+  commands, `find -exec`. Never edits.
+- **`validate.py` skill description budget.** Error over 1024 characters (the
+  Agent Skills cap), warning over 400, and an error for an unquoted description
+  containing `: ` or ` #` (strict YAML drops every field, `allowed-tools`
+  included). Applied to plugin-pack skills too.
+- **`git-team` common rule.** Branching, pull-request, and review conventions
+  moved out of `git-workflow` into a rule that ships with `--profile strict`
+  only, via a new `profiles:` frontmatter gate. See `DECISIONS.md`.
+- **One frontmatter parser.** `scripts/frontmatter.py` now parses the whole
+  toolkit subset (scalars, quoted scalars, `>-`/`|` blocks, block and flow
+  lists, nested maps) strictly and is the only parser; twelve private
+  strip/parse copies in `validate.py`, `doctor.py`, `install_steps/ai_tools.py`,
+  `claude_app.py`, `compile_slm.py`, `surface_manifest.py`, `instruction_core.py`,
+  `check_split.py`, `codex_skill_adapter.py`, `generate_opencode_skills.py`, and
+  `generate_language_rules_skills.py` are gone. Every shipped `app/` and `kb/`
+  Markdown file parses under the strict grammar (pytest corpus test).
+- **Repo dev tooling, stdlib runtime.** `requirements-dev.txt` + `pytest.ini`
+  + `mypy.ini` (pytest, ruff, mypy) and a `python-quality` CI job:
+  `npm run test:py` (348 pytest tests under `tests/python/`), `npm run lint:py`
+  (ruff `E,F`, rule set in `package.json`), `npm run typecheck:py` (mypy
+  `--strict` over an allowlist). No `pyproject.toml`: the toolkit's own
+  `quality-gate.sh` reads one as "Python project, run `ruff check .`", which
+  is not what an npm-first repo wants. Nothing is added to the published
+  package or to user machines. See `DECISIONS.md` for why no runtime
+  dependency.
+
+### Changed
+
+- **Common rules are path-scoped from their source.** `app/rules/common/*.md`
+  may declare `paths:`; the generated `.claude/rules/ai-toolkit-*.md` copies it.
+  `testing` and `performance` load only for matching files; `coding-style`,
+  `git-workflow`, and `security` stay always-on. The `.claude/CLAUDE.md` index
+  now lists which rules are always-on and which are path-scoped instead of
+  claiming lazy loading for all of them.
+- **Stop hooks `quality-check.sh` and `save-session.sh` run with
+  `"async": true`.** Both are advisory and always exit 0; the linter was the
+  bulk of a 3.3 s median Stop chain. `quality-gate.sh` (exit 2) and
+  `stop-search-check.sh` stay synchronous.
+- **`git-workflow` is the solo-safe core** (commit format, no secrets, `main`
+  deployable, tags, recovery). Version 2.0.0.
+
+### Fixed
+
+- **`quality-gate.sh` runs ruff only for projects that configured it.** A bare
+  `pyproject.toml` (build metadata, pytest/mypy tables) used to trigger
+  `ruff check .` on every Stop under whatever ruff configuration the machine
+  resolves; found when this repository's own gate went red on 348 unrelated
+  findings. Ruff now needs `ruff.toml`, `.ruff.toml`, or a `[tool.ruff]` table.
+- **Codex/DSH skill sync no longer flattens nested frontmatter.** Native
+  (non-adapted) skills had their frontmatter re-rendered line by line, which
+  turned a `hooks:` block into stray top-level `PreToolUse:` / `- matcher:`
+  lines. The frontmatter now passes through verbatim.
+- **Hook merge de-duplicates legacy untagged toolkit hooks by command identity.**
+  Scheduling fields (`async`, `timeout`, `statusMessage`, ...) no longer defeat
+  the match, so adding one in `app/hooks.json` does not leave existing installs
+  running the old and the new copy side by side. Fixed in both
+  `scripts/merge-hooks.py` and `scripts/inject_hook_cli.py`.
+- **Test count.** Bats increased from 1931 to 1966; 348 pytest tests added under
+  `tests/python/` (run by the new `python-quality` CI job).
+
+### Ecosystem
+
+- Ecosystem doctor run for this minor release: 12 tools drifted since the
+  v4.30.3 snapshot, all class A (content edits with no heading delta) or class
+  C (Cline gained a "Resources" heading, Codex CLI a "ChatGPT Work" heading;
+  neither adds a surface the toolkit integrates). Tracked versions moved:
+  Claude Code 2.1.252 -> 2.1.260 (its hooks documentation now lists the
+  `async` command-hook field this release relies on), Codex CLI 0.151.0 ->
+  0.153.2. No generator changed; snapshot refreshed.
+
 ## v4.31.0 - Toolkit rules reach every editor (2026-09-03)
 
 ### Added

package/README.md

@@ -6,25 +6,30 @@
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-114-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1931%20passing-success)](tests/)
-
-## What's New in v4.31.0
-
-**v4.31.0** corrects the post-release health check for the managed DSH and
-plugin-owned MCP release:
-
-- `ai-toolkit doctor` now extracts `1.0.80` from the official Copilot CLI output
-  `GitHub Copilot CLI 1.0.80.` instead of treating sentence punctuation as an
-  invalid SemVer suffix.
-- Complete-token validation remains fail closed for malformed versions such as
-  `1.2.3.4`, invalid prerelease identifiers, and leading-zero numeric fields.
-- The DSH cold-add regression keeps its legacy-timeout coverage with macOS CI
-  process-startup headroom, removing the release-blocking timing flake.
-- Release tags now require green Ubuntu and macOS branch CI for the exact commit
-  before the publish workflow can start.
-- The release retains the explicit DSH lifecycle, plugin-owned MCP/rules, portable
-  recovery gates, and the exact DSH package set published in v4.30.2. Test count:
-  1920 -> 1931.
+[![Tests](https://img.shields.io/badge/tests-1966%20passing-success)](tests/)
+
+## What's New in v4.32.0
+
+**v4.32.0** cuts what every session pays for before you type, and adds the
+checks that keep it cut:
+
+- Common rules are path-scoped from their source: `testing` and `performance`
+  load only for matching files, and the project `.claude/CLAUDE.md` index says
+  which rules are always-on instead of claiming lazy loading for all of them.
+- Language knowledge skills follow your projects: `install --language-skills
+  detected` (default) turns off `<lang>-rules`/`<lang>-patterns` skills for
+  languages no registered project uses, reversibly, and restores them when a
+  project brings the language back.
+- `ai-toolkit doctor` gains a Context Budget check (est. resident tokens,
+  zero-use skills) and a Permission Rules check (over-broad `permissions.allow`
+  wildcards). Both read-only.
+- One strict frontmatter parser replaces twelve private copies; `validate.py`
+  now rejects descriptions over 1024 characters or unquoted ones containing
+  `: `. Every shipped Markdown file parses under the strict grammar.
+- Team-only git conventions moved to a `git-team` rule that ships with
+  `--profile strict`; `quality-gate.sh` lints with ruff only when the project
+  configured ruff; advisory Stop hooks run in the background. Test count:
+  1931 -> 1966 bats + 348 pytest.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -62,6 +67,8 @@ npx @softspark/ai-toolkit install
 
 **That's it.** Claude Code picks up 114 skills, 44 agents, quality hooks, and the safety constitution automatically.
 
+Language knowledge skills (`rust-rules`, `kotlin-patterns`, ...) are scoped to the languages your registered projects use: once you have run `ai-toolkit install --local` in at least one project, the global install turns the other languages' skills off through `skillOverrides` in `~/.claude/settings.json` so their descriptions stop loading into every session. A new project in a new language turns its skills back on. `ai-toolkit install --language-skills all` keeps every language skill on and remembers that choice; `ai-toolkit doctor` shows the resulting context budget.
+
 **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

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

@@ -3,7 +3,7 @@
   "name": "ai-toolkit",
   "displayName": "AI Toolkit",
   "description": "Professional-grade engineering skills, agents, rules, and lifecycle guardrails for Claude Code, Claude Chat, and Cowork.",
-  "version": "4.31.0",
+  "version": "4.32.0",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/claude-app/hooks/hooks.json

@@ -151,7 +151,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.sh\""
+            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/quality-check.sh\"",
+            "async": true
           }
         ]
       },
@@ -160,7 +161,8 @@
         "hooks": [
           {
             "type": "command",
-            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/save-session.sh\""
+            "command": "AI_TOOLKIT_DIR=\"${CLAUDE_PLUGIN_ROOT}\" \"${CLAUDE_PLUGIN_ROOT}/hooks/save-session.sh\"",
+            "async": true
           }
         ]
       },

package/app/claude-app/skills/ai-toolkit-rules/SKILL.md

@@ -207,27 +207,22 @@ Default response mode for this project is **concise**. The `brand-voice` skill (
 - Magic numbers/strings: use named constants.
 - Mutable global state: use dependency injection instead.
 
-## Source: `app/rules/common/git-workflow.md`
-
-# Git Workflow Rules
+## Source: `app/rules/common/git-team.md`
 
-## Commit Messages
-- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
-- First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
-- Body (optional): explain *why*, not *what*. The diff shows what.
-- Reference tickets: `fix: prevent duplicate orders (PROJ-456)`.
+# Git Team Workflow Rules
 
-## Commit Practices
-- Commit small, atomic changes. One commit = one logical change.
-- Never commit: secrets, `.env` files, build artifacts, large binaries.
-- Never commit broken code to `main`. Use feature branches.
-- Squash fixup commits before merging to keep history clean.
+These rules assume more than one person merges into `main`. They ship only with
+the `strict` profile; a solo maintainer who commits straight to `main` is not
+doing anything wrong, and a reviewer that keeps flagging "use a feature branch"
+in that setting is noise. The solo-safe core (commit format, no secrets, no
+force-push) lives in `git-workflow`.
 
 ## Branching
-- `main` is always deployable. Protect it with required reviews and CI.
-- Feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Protect `main` with required reviews and CI. Never commit broken code to it.
+- Work on feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Rebase feature branches on `main` before opening a PR to keep linear history.
+- Squash fixup commits before merging to keep history clean.
 - Delete branches after merge. Stale branches are clutter.
-- Rebase feature branches on main before PR to keep linear history.
 
 ## Pull Requests
 - Keep PRs small: <400 lines changed. Split large features into stacked PRs.
@@ -240,6 +235,25 @@ Default response mode for this project is **concise**. The `brand-voice` skill (
 - Approve with comments if nits only. Block for: bugs, security, missing tests.
 - Respond to reviews within 24 hours. Do not let PRs rot.
 
+## Source: `app/rules/common/git-workflow.md`
+
+# Git Workflow Rules
+
+Solo-safe core: everything here holds whether one person or twenty merge into
+`main`. Branching, pull-request, and review conventions for teams live in
+`git-team` and ship only with the `strict` profile.
+
+## Commit Messages
+- Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
+- First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
+- Body (optional): explain *why*, not *what*. The diff shows what.
+- Reference tickets: `fix: prevent duplicate orders (PROJ-456)`.
+
+## Commit Practices
+- Commit small, atomic changes. One commit = one logical change.
+- Never commit: secrets, `.env` files, build artifacts, large binaries.
+- `main` is always deployable: run the project's gates before every commit that lands there.
+
 ## Tags and Releases
 - Use semantic versioning: MAJOR.MINOR.PATCH.
 - Tag releases: `git tag v1.2.3`. Automate changelog from commits.

package/app/hooks/quality-gate.sh

@@ -98,8 +98,15 @@ if [ -f .claude/test-cohesion-map.json ] || \
 fi
 
 if [ -f pyproject.toml ] || [ -f setup.py ]; then
-    if require_command ruff; then
-        run_required "ruff found errors" "head -30" ruff check .
+    # Lint only what the project itself configured. A bare pyproject.toml
+    # (build metadata, pytest/mypy tables) says nothing about ruff, and running
+    # `ruff check .` under whatever config the machine resolves turns the Stop
+    # gate red on findings the project never signed up for (v4.32.0 postmortem:
+    # 348 findings in a repo whose ruff rule set lives in a package.json script).
+    if [ -f ruff.toml ] || [ -f .ruff.toml ] || grep -qs '^\[tool\.ruff' pyproject.toml; then
+        if require_command ruff; then
+            run_required "ruff found errors" "head -30" ruff check .
+        fi
     fi
     if [ -d src ] && [ "$PROFILE" = "strict" ]; then
         if require_command mypy; then

package/app/hooks.json

@@ -167,7 +167,8 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/quality-check.sh\""
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/quality-check.sh\"",
+                        "async": true
                     }
                 ]
             },
@@ -177,7 +178,8 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/save-session.sh\""
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/save-session.sh\"",
+                        "async": true
                     }
                 ]
             },

package/app/rules/common/git-team.md

@@ -0,0 +1,33 @@
+---
+language: common
+category: git-team
+version: "1.0.0"
+profiles:
+  - "strict"
+---
+
+# Git Team Workflow Rules
+
+These rules assume more than one person merges into `main`. They ship only with
+the `strict` profile; a solo maintainer who commits straight to `main` is not
+doing anything wrong, and a reviewer that keeps flagging "use a feature branch"
+in that setting is noise. The solo-safe core (commit format, no secrets, no
+force-push) lives in `git-workflow`.
+
+## Branching
+- Protect `main` with required reviews and CI. Never commit broken code to it.
+- Work on feature branches: `feat/user-registration`, `fix/order-total-calc`.
+- Rebase feature branches on `main` before opening a PR to keep linear history.
+- Squash fixup commits before merging to keep history clean.
+- Delete branches after merge. Stale branches are clutter.
+
+## Pull Requests
+- Keep PRs small: <400 lines changed. Split large features into stacked PRs.
+- PR title follows conventional commit format.
+- Include: summary, test plan, and screenshots/recordings for UI changes.
+- Require at least one approval before merge.
+
+## Code Review
+- Review for: correctness, security, performance, readability.
+- Approve with comments if nits only. Block for: bugs, security, missing tests.
+- Respond to reviews within 24 hours. Do not let PRs rot.

package/app/rules/common/git-workflow.md

@@ -1,11 +1,15 @@
 ---
 language: common
 category: git-workflow
-version: "1.0.0"
+version: "2.0.0"
 ---
 
 # Git Workflow Rules
 
+Solo-safe core: everything here holds whether one person or twenty merge into
+`main`. Branching, pull-request, and review conventions for teams live in
+`git-team` and ship only with the `strict` profile.
+
 ## Commit Messages
 - Use conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`.
 - First line: imperative mood, max 72 chars (`feat: add user registration endpoint`).
@@ -15,25 +19,7 @@ version: "1.0.0"
 ## Commit Practices
 - Commit small, atomic changes. One commit = one logical change.
 - Never commit: secrets, `.env` files, build artifacts, large binaries.
-- Never commit broken code to `main`. Use feature branches.
-- Squash fixup commits before merging to keep history clean.
-
-## Branching
-- `main` is always deployable. Protect it with required reviews and CI.
-- Feature branches: `feat/user-registration`, `fix/order-total-calc`.
-- Delete branches after merge. Stale branches are clutter.
-- Rebase feature branches on main before PR to keep linear history.
-
-## Pull Requests
-- Keep PRs small: <400 lines changed. Split large features into stacked PRs.
-- PR title follows conventional commit format.
-- Include: summary, test plan, and screenshots/recordings for UI changes.
-- Require at least one approval before merge.
-
-## Code Review
-- Review for: correctness, security, performance, readability.
-- Approve with comments if nits only. Block for: bugs, security, missing tests.
-- Respond to reviews within 24 hours. Do not let PRs rot.
+- `main` is always deployable: run the project's gates before every commit that lands there.
 
 ## Tags and Releases
 - Use semantic versioning: MAJOR.MINOR.PATCH.

package/app/rules/common/performance.md

@@ -1,7 +1,31 @@
 ---
 language: common
 category: performance
-version: "1.0.0"
+version: "1.1.0"
+paths:
+  - "**/*.py"
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "**/*.go"
+  - "**/*.rs"
+  - "**/*.java"
+  - "**/*.kt"
+  - "**/*.kts"
+  - "**/*.swift"
+  - "**/*.dart"
+  - "**/*.cs"
+  - "**/*.php"
+  - "**/*.cpp"
+  - "**/*.cc"
+  - "**/*.cxx"
+  - "**/*.hpp"
+  - "**/*.h"
+  - "**/*.rb"
+  - "**/*.sql"
 ---
 
 # Universal Performance Rules

package/app/rules/common/testing.md

@@ -1,7 +1,13 @@
 ---
 language: common
 category: testing
-version: "1.0.0"
+version: "1.1.0"
+paths:
+  - "**/*.test.*"
+  - "**/*.spec.*"
+  - "**/test_*"
+  - "**/*_test.*"
+  - "**/tests/**"
 ---
 
 # Universal Testing Rules

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-09-01T07:58:08Z",
+  "last_run": "2026-09-04T08:36:45Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "83f1458d1a2060e9",
+      "docs_hash": "0e91c48495240138",
       "headings": [
         "Admin",
         "Auggie CLI",
@@ -66,7 +66,7 @@
       }
     },
     "claude-app": {
-      "docs_hash": "273703f5030fd2ab",
+      "docs_hash": "4ba2582ffb78c262",
       "headings": [
         "Add global and folder instructions",
         "Availability",
@@ -108,7 +108,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "eea5867f24e1ed91",
+      "docs_hash": "10fe9c9fa45efb7a",
       "headings": [
         "Core concepts",
         "Documentation Index",
@@ -174,10 +174,10 @@
         "userConfig": false,
         "workflows": true
       },
-      "version": "2.1.252 (Claude Code)"
+      "version": "2.1.260 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "13a2b874f0e0173c",
+      "docs_hash": "53d71ba66743ef56",
       "headings": [
         "API Reference",
         "Best Practices",
@@ -195,6 +195,7 @@
         "Kanban",
         "Observability",
         "On this page",
+        "Resources",
         "SDK",
         "Security & Governance",
         "Team Management",
@@ -224,7 +225,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "f7df4a0b9f583a2e",
+      "docs_hash": "5444e9c3b6b4d284",
       "headings": [
         "API",
         "API Reference",
@@ -241,6 +242,7 @@
         "Build with Codex",
         "Capabilities",
         "Categories",
+        "ChatGPT Work",
         "ChatGPT web",
         "ChatKit",
         "Choose a model",
@@ -363,10 +365,10 @@
         "plugin marketplace": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.151.0"
+      "version": "codex-cli 0.153.2"
     },
     "cursor": {
-      "docs_hash": "8665fb50dce5f322",
+      "docs_hash": "328f32fe1afe3e7e",
       "headings": [
         "Agent",
         "CLI",
@@ -399,7 +401,7 @@
       }
     },
     "dsh": {
-      "docs_hash": "265ff3799848801e",
+      "docs_hash": "217350a932acc7fb",
       "headings": [],
       "markers": {
         "Agent Preset": false,
@@ -410,7 +412,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "02285d342536bdeb",
+      "docs_hash": "b78dde41b3161819",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -451,7 +453,7 @@
       "version": "0.57.0"
     },
     "github-copilot": {
-      "docs_hash": "fd80b4ec446cec3f",
+      "docs_hash": "606c4417d0acebed",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot automations",
@@ -488,7 +490,7 @@
       }
     },
     "google-antigravity": {
-      "docs_hash": "9fe532d247c3e361",
+      "docs_hash": "8cbf9aaffb6b57bf",
       "headings": [],
       "markers": {
         "AGENTS.md": false,
@@ -515,7 +517,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "154885af5c7de582",
+      "docs_hash": "4dac69e305e60373",
       "headings": [
         "Add features",
         "Ask questions",
@@ -577,7 +579,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "4a3e8dc19dfdedd6",
+      "docs_hash": "121e915ebbd89355",
       "headings": [
         "Accounts",
         "Advanced",

package/bin/ai-toolkit.js

@@ -311,6 +311,8 @@ function showHelp() {
   console.log('                  dsh (explicit project target; requires --local; excluded from "all")');
   console.log('                  Default with --local: auto-detect from existing project files');
   console.log('  --auto-detect   Detect project languages and install matching rule modules');
+  console.log('  --language-skills <s>  detected (default): turn off <lang>-rules/<lang>-patterns skills for languages');
+  console.log('                  no registered project uses (skillOverrides, reversible); all: keep every language skill on');
   console.log('  --list, --dry-run  Dry-run: show what would be applied');
   console.log('\nOptions for create:');
   console.log('  skill <name> --template=<type>  Scaffold skill (types: linter, reviewer, generator, workflow, knowledge)');

package/kb/procedures/sop-maintenance.md

@@ -3,9 +3,9 @@ title: "SOP: AI Toolkit Maintenance"
 category: procedures
 service: ai-toolkit
 tags: [sop, maintenance, agents, skills, install]
-version: "3.4.0"
+version: "3.5.0"
 created: "2026-03-23"
-last_updated: "2026-08-06"
+last_updated: "2026-09-04"
 description: "Standard operating procedures for installing, maintaining, and evolving the ai-toolkit."
 ---
 
@@ -229,7 +229,9 @@ that runtime should receive the change.
    greets the user with a traceback, and one that reads stdin must answer an
    empty stdin with an error rather than blocking forever.
 3. Update `kb/reference/skills-catalog.md` and `app/ARCHITECTURE.md`
-4. Run `scripts/validate.py` — it checks the invocation, the body budget, and
+4. Run `scripts/validate.py` — it checks the invocation, the body budget, the
+   description budget (warn over 400 characters, error over 1024; unquoted
+   descriptions containing `: ` or ` #` are rejected, use `>-`), and
    `reference/` link resolution
 5. Run `python3 scripts/surface_manifest.py` before the next release to adopt the
    new skill into the protected surface
@@ -305,6 +307,7 @@ bats tests/test_install.bats tests/test_codex.bats
 bats tests/test_claude_app.bats tests/test_hooks_per_editor.bats
 python3 scripts/claude_app.py verify
 python3 scripts/validate.py --strict
+npm run test:py   # pytest over scripts/ logic incl. the frontmatter corpus test (dev venv, see CONTRIBUTING.md)
 ```
 
 ## Managing Plugins

package/kb/reference/cli-reference.md

@@ -4,7 +4,7 @@ category: reference
 service: ai-toolkit
 tags: [cli, commands, reference, install, update, plugin, mcp, telemetry]
 created: "2026-04-13"
-last_updated: "2026-08-19"
+last_updated: "2026-09-04"
 description: "Complete CLI reference for all ai-toolkit commands, options, and flags."
 ---
 
@@ -19,6 +19,7 @@ Usage: ai-toolkit <command> [options]
 | Command | Description |
 |---------|-------------|
 | `install` | First-time global install into `~/.claude/` + Cursor, Windsurf, Gemini |
+| `install --language-skills detected\|all` | `detected` (default): turn off `<lang>-rules`/`<lang>-patterns` skills for languages no registered project uses, via `skillOverrides` in `~/.claude/settings.json` (entries are tracked in `state.json` and restored when a project brings the language back; a user's own override is never touched); `all`: keep every language skill on. The choice persists across `install`/`update` |
 | `install --local` | Claude Code configs only; add `--editors all` or `--editors cursor,aider` for other tools |
 | `update` | Re-apply toolkit after `npm install -g @softspark/ai-toolkit@latest` |
 | `update --local` | Re-apply + auto-detect editors from existing project files |
@@ -26,7 +27,7 @@ Usage: ai-toolkit <command> [options]
 | `status` | Show installed modules and version |
 | `uninstall` | Remove toolkit from `~/.claude/` |
 | `validate` | Verify toolkit integrity (`--strict` for CI-grade, warnings = errors) |
-| `doctor` | Diagnose install health, hooks, quick-win assets, and artifact drift |
+| `doctor` | Diagnose install health, hooks, quick-win assets, artifact drift, context budget (est. resident tokens of the skill/agent listings and user rules, plus skills with zero recorded use; read-only, prints the `skillOverrides` key to paste), and permission rules (`permissions.allow` wildcards on interpreters, task runners, package installs, `gh api`, `curl`, `git fetch`, destructive commands; warns only, never edits) |
 | `doctor --fix` | Auto-repair broken symlinks, missing hooks, stale artifacts |
 | `eject [dir]` | Export standalone config (no symlinks, no toolkit dependency) |
 | `claude-app export [--output FILE] [--no-custom-rules] [--verify]` | Build an uploadable Claude Chat/Desktop/Cowork plugin ZIP and global-instructions file |