@softspark/ai-toolkit 4.31.0 → 4.32.1

package/CHANGELOG.md

@@ -7,6 +7,127 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.32.1 - Plugin removal leaves nothing behind (2026-09-04)
+
+Both fixes come from running the post-release SOPs on v4.32.0 in an isolated
+sandbox; both defects predate that release (identical on v4.31.0).
+
+### Fixed
+
+- **`plugin remove` deletes the hooks and scripts a pack installed.** The
+  Claude and Codex install paths copied `hooks/plugin-<pack>-*` and
+  `plugin-scripts/<pack>/*` into `~/.softspark/ai-toolkit` but never recorded
+  them in `shared_asset_ownership`, so removal found no owner and preserved
+  every file as "untracked": each pack left 4-5 files behind. Install now
+  records sha256/mode/inode for what it copied; removal deletes only entries
+  this editor consumes that no other editor still uses and that are unchanged
+  on disk, preserves an edited file with a `WARN preserved changed plugin
+  asset` line, and drops the empty `plugin-scripts/<pack>/` directory.
+  `tests/test_plugin_asset_removal.bats` covers install, zero-residue removal,
+  user-edited preservation, two-editor sharing, and reinstall.
+- **Five skill scripts answer `--help`.** `doc-inventory.py`,
+  `dependency-graph.py`, `migration-status.py`, `refactor-scan.py`, and
+  `complexity.py` treated `--help` as a path and returned a JSON error.
+  `tests/test_skill_scripts_help.bats` now probes every documented
+  `${CLAUDE_SKILL_DIR}` invocation with `--help` (exit 0, no traceback), the
+  same check as post-release SOP Phase 4b. The probe uses `perl alarm` as its
+  hang guard, not GNU `timeout`, which the macOS CI runner does not have.
+- **`pre_deploy_check.py` no longer crashes on Linux.** It probed for docker
+  by running the shell builtin `command -v` through `subprocess`, which only
+  works on macOS (a `/usr/bin/command` binary exists there); on Linux it raised
+  `FileNotFoundError` before any check ran. Now `shutil.which`. Caught by the
+  new `--help` probe on the Ubuntu CI runner, which is the point of that test.
+- **Test count.** Bats increased from 1966 to 1972.
+
+## 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,25 @@
 [![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-1972%20passing-success)](tests/)
+
+## What's New in v4.32.1
+
+**v4.32.1** fixes two defects the post-release SOPs found on v4.32.0 (both
+older than that release):
+
+- `ai-toolkit plugin remove` now deletes the hooks and scripts a pack
+  installed under `~/.softspark/ai-toolkit`. Install records what it copied;
+  removal deletes only unchanged, unshared files and names anything it
+  preserves. Every pack used to leave 4-5 files behind.
+- Five skill scripts (`doc-inventory`, `dependency-graph`, `migration-status`,
+  `refactor-scan`, `complexity`) answer `--help` instead of treating it as a
+  path; a new test probes every documented skill script with `--help`.
+- Still in this train from v4.32.0: path-scoped common rules, language skills
+  scoped to your registered projects (`--language-skills`), `doctor` Context
+  Budget and Permission Rules checks, one strict frontmatter parser, and the
+  `git-team` rule for `--profile strict`. Test count: 1966 -> 1972 bats +
+  348 pytest.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -62,6 +62,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.1",
   "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/app/skills/analyze/scripts/complexity.py

@@ -125,6 +125,9 @@ def _summary(root: Path, all_files: list[Path]) -> tuple[int, int]:
 
 def main() -> None:
     """Entry point: analyse directory and print text report to stdout."""
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: complexity.py [directory]\n\nReport per-file code complexity for directory (default: cwd).")
+        return
     root = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd().resolve()
     now = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
 

package/app/skills/deploy/scripts/pre_deploy_check.py

@@ -16,6 +16,7 @@ Usage::
 from __future__ import annotations
 
 import json
+import shutil
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -50,12 +51,15 @@ def _git_branch() -> str:
 
 
 def _docker_available() -> bool:
-    """Return True if the ``docker`` command is on PATH."""
-    result = _run(["command", "-v", "docker"])
-    # Fallback: just try docker --version
-    if result.returncode != 0:
-        result = _run(["docker", "--version"])
-    return result.returncode == 0
+    """Return True if the ``docker`` command is on PATH.
+
+    ``command -v`` is a shell builtin; running it through ``subprocess`` only
+    worked on macOS, which ships a ``/usr/bin/command`` binary. On Linux it
+    raised ``FileNotFoundError`` before any check ran (v4.32.1).
+    """
+    if shutil.which("docker") is None:
+        return False
+    return _run(["docker", "--version"]).returncode == 0
 
 
 def _docker_services_running() -> bool:
@@ -155,6 +159,9 @@ def _run_checks(env: str) -> _CheckCollector:
 
 def main() -> None:
     """Entry point: run checks and print JSON result to stdout."""
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: pre_deploy_check.py [environment]\n\nRun pre-deployment checks for environment (default: staging) and print JSON.")
+        return
     env = sys.argv[1] if len(sys.argv) > 1 else "staging"
     branch = _git_branch()
     collector = _run_checks(env)

package/app/skills/docs/scripts/doc-inventory.py

@@ -130,6 +130,9 @@ def get_mtime(filepath: str) -> float:
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: doc-inventory.py [directory]\n\nInventory documentation files under directory (default: cwd) as JSON.")
+        return
     root = os.path.abspath(sys.argv[1]) if len(sys.argv) > 1 else os.getcwd()
     if not os.path.isdir(root):
         print(json.dumps({"error": f"Not a directory: {root}"}))

package/app/skills/explain/scripts/dependency-graph.py

@@ -159,6 +159,9 @@ def generate_mermaid(target_name: str, imports: list, imported_by: list) -> str:
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: dependency-graph.py <file_or_directory>\n\nPrint the import/dependency graph of a file or directory as JSON.")
+        return
     if len(sys.argv) < 2:
         print(json.dumps({"error": "Usage: dependency-graph.py <file_or_directory>"}))
         sys.exit(1)

package/app/skills/migrate/scripts/migration-status.py

@@ -182,6 +182,9 @@ def detect(project_dir: Path) -> dict[str, object]:
 
 def main() -> None:
     """Entry point: detect migration tool and print JSON result to stdout."""
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: migration-status.py [project_dir]\n\nDetect the migration tool in project_dir (default: cwd) and report its status as JSON.")
+        return
     project_dir = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path.cwd()
     if not project_dir.is_dir():
         print(json.dumps({"error": f"Not a directory: {project_dir}"}))

package/app/skills/refactor/scripts/refactor-scan.py

@@ -154,6 +154,9 @@ def analyze_file(filepath: str, project_root: str) -> dict:
 
 
 def main():
+    if len(sys.argv) > 1 and sys.argv[1] in ("-h", "--help"):
+        print("Usage: refactor-scan.py <file_or_directory>\n\nScan a file or directory for refactoring candidates and print JSON.")
+        return
     if len(sys.argv) < 2:
         print(json.dumps({"error": "Usage: refactor-scan.py <file_or_directory>"}))
         sys.exit(1)