@softspark/ai-toolkit 3.2.1 → 3.4.0

package/CHANGELOG.md

@@ -7,6 +7,48 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.4.0 — Local-path source tracking & orphan detection (2026-05-06)
+
+Minor release. Closes the visibility gap for rules and hooks installed from local files: `add-rule` and `inject-hook` now record the origin path in `sources.json`, and `status` flags any rule files on disk that have no source recorded.
+
+### Added
+
+- **`register_path_source()` in `scripts/rule_sources.py` and `scripts/hook_sources.py`** — records `{"path": <abs_path>, "fetched_at": ..., "sha256": ...}` for local-file injections. Schema-compatible with existing URL entries (mutually exclusive `url` vs `path` field, `schema_version` unchanged at 1).
+- **`add-rule` registers local paths** — `scripts/add_rule.py` now calls `register_path_source` after copying a local file, and prints the origin path with a hint to re-run `add-rule` to refresh.
+- **`inject-hook` registers local paths** — `scripts/inject_hook_cli.py` writes a `path`-tracked entry into `~/.softspark/ai-toolkit/hooks/external/sources.json` for file-sourced hooks. URL behavior unchanged. Registration failures are non-fatal — injection always proceeds.
+- **`ai-toolkit status` distinguishes URL vs local sources** — local-path entries display the absolute path with a `[local]` tag; URL entries display the URL. Format: `rule  <name>  <- <origin>[ [local]] (<fetched_at>)`.
+- **Orphan rule detection in `status`** — files in `~/.softspark/ai-toolkit/rules/` that have no entry in `sources.json` are listed as `(orphan, no source recorded — re-run add-rule)`. Surfaces rules registered before the registry existed (pre-v3.3.0).
+
+### Migration
+
+- Existing URL-tracked sources continue to work unchanged.
+- To upgrade an orphan local rule into the registry, re-run `ai-toolkit add-rule <path>` from the rule's source directory. The new run records the path.
+
+---
+
+## v3.3.0 — External-source visibility & skill-listing budget default (2026-05-06)
+
+Minor release. Two coordinated install-time additions: `ai-toolkit status` now surfaces every registered external rule and hook, and fresh installs / updates set a sane `skillListingBudgetFraction` so all 112 skill descriptions stay loadable in Claude Code.
+
+### Added
+
+- **`ai-toolkit status` shows external sources** — `scripts/install_steps/install_state.py` reads `~/.softspark/ai-toolkit/rules/sources.json` and `~/.softspark/ai-toolkit/hooks/external/sources.json` and prints an `External sources:` section listing each registered rule/hook with its source URL and last-fetched timestamp. The section is omitted entirely when no external sources are registered. Closes the long-standing gap where `add-rule`/`inject-hook` had no read-side counterpart.
+- **`skillListingBudgetFraction` default in `~/.claude/settings.json`** — new `_install_skill_listing_budget()` step in `scripts/install_steps/hooks.py` writes `"skillListingBudgetFraction": 0.02` on install/update, but only when the key is absent. Existing user values are never overwritten. Prevents Claude Code's default 1% budget from truncating ~60 of the toolkit's 112 skill descriptions.
+
+### Changed
+
+- **`ai-toolkit status` help text** — updated in `bin/ai-toolkit.js` to mention external rules/hooks alongside modules, version, and profile.
+
+
+
+Patch release. Lint-only fix in the default status line hook — no behavior change.
+
+### Fixed
+
+- **`app/hooks/ai-toolkit-statusline.sh` shellcheck warnings** — removed the unused `C_GRAY` color variable (SC2034) and replaced the deprecated `[ p -o q ]` form with `{ [ p ] || [ q ]; }` (SC2166). CI shellcheck gate at `--severity=warning` now passes clean across `app/hooks/*.sh`.
+
+---
+
 ## v3.2.1 — Statusline shellcheck cleanup (2026-05-04)
 
 Patch release. Lint-only fix in the default status line hook — no behavior change.

package/README.md

@@ -6,7 +6,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-112-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1038%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1046%20passing-success)](tests/)
 
 <p align="center">
   <img src="assets/ai-toolkit-readme-hero.png" alt="ai-toolkit 3 README hero showing one toolkit for 12 AI editors" width="900">
@@ -14,11 +14,13 @@
 
 ---
 
-## What's New in v3.2.1
+## What's New in v3.4.0
 
-Patch release. Shellcheck cleanup of the default status line hook — no behavior change.
+Minor release. Closes the visibility gap for rules and hooks installed from local files.
 
-- **Statusline lint cleanup** — `app/hooks/ai-toolkit-statusline.sh` now passes `shellcheck --severity=warning`: removed the unused `C_GRAY` color variable (SC2034) and replaced the deprecated `[ p -o q ]` form with `{ [ p ] || [ q ]; }` (SC2166).
+- **`add-rule` and `inject-hook` now track local paths** — file-sourced rules and hooks record `{"path": ..., "sha256": ...}` in `sources.json`, alongside the existing URL entries. URL flow unchanged.
+- **`status` distinguishes URL vs local sources** — local entries show the absolute origin path with a `[local]` tag; URL entries show the URL.
+- **Orphan rule detection** — rule files on disk that have no source recorded (e.g., installed before v3.3.0's registry existed) are listed in `status` with `(orphan, no source recorded — re-run add-rule)`. Run `add-rule <path>` again to register them.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -151,7 +153,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1038 tests)
+├── tests/               # Bats test suite (1046 tests)
 └── CHANGELOG.md
 ```
 

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

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

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-05-04T08:36:05Z",
+  "last_run": "2026-05-06T08:17:20Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,13 +24,12 @@
       }
     },
     "augment": {
-      "docs_hash": "f6b4c7fd64936879",
+      "docs_hash": "ac138d99235e1f3e",
       "headings": [
         "Agent",
         "Code Completions",
         "Documentation Index",
         "Introduction",
-        "Next Edit",
         "\u200bAuggie CLI",
         "\u200bGet started in minutes",
         "\u200bJetBrains IDEs",
@@ -43,7 +42,7 @@
         "Agent mode": false,
         "Auggie CLI": true,
         "MCP": true,
-        "Next Edit": true,
+        "Next Edit": false,
         "PostToolUse": false,
         "PreToolUse": false,
         "SKILL.md": false,
@@ -58,7 +57,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "7d2930e5f97e4126",
+      "docs_hash": "789113e1bc4cd34c",
       "headings": [
         "Claude Code overview",
         "Documentation Index",
@@ -104,10 +103,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.126 (Claude Code)"
+      "version": "2.1.131 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "eec0384d180243aa",
+      "docs_hash": "b4009dc8e6d40af9",
       "headings": [
         "Cline CLI",
         "Cline Documentation",
@@ -138,7 +137,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "5a4b2d4eeee1d675",
+      "docs_hash": "c6b51936294d38e7",
       "headings": [
         "About",
         "Contributing",
@@ -157,7 +156,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 757",
+        "Releases 765",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -187,10 +186,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.125.0"
+      "version": "codex-cli 0.128.0"
     },
     "cursor": {
-      "docs_hash": "4c3678f1353e012f",
+      "docs_hash": "8ed1f5cf7441b6c0",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -206,7 +205,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "20c254199b42f18c",
+      "docs_hash": "21a2f14121ff27fa",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -245,7 +244,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "6467b14babd06b26",
+      "docs_hash": "99a5ab7bd5f7556f",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -293,7 +292,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "c8c233106f166444",
+      "docs_hash": "fe845a4bffb6371b",
       "headings": [
         "Add features",
         "Ask questions",
@@ -354,7 +353,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "167ee1fc000f03d9",
+      "docs_hash": "9b2879646f041aea",
       "headings": [
         "Advanced",
         "App Deploys",

package/bin/ai-toolkit.js

@@ -62,7 +62,7 @@ const SCRIPT_COMMANDS = {
 const COMMANDS = {
   install: 'First-time global install into ~/.claude/ (use --local for project-local configs only)',
   update: 'Re-apply toolkit with saved modules from state.json (use --local for project-local only)',
-  status: 'Show installed modules, version, and profile from state.json',
+  status: 'Show installed modules, version, profile, and registered external rules/hooks',
   reset: 'Wipe and recreate project-local configs from scratch (requires --local)',
   uninstall: 'Remove ai-toolkit from ~/.claude/',
   'add-rule': 'Register a rule file or URL in ~/.softspark/ai-toolkit/rules/ (URL rules auto-refresh on update)',

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "3.2.1",
+  "version": "3.4.0",
   "description": "AI coding toolkit: 112 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",

package/scripts/add_rule.py

@@ -87,7 +87,11 @@ def main() -> None:
         dest = rules_dir / f"{rule_name}.md"
         shutil.copy2(rule_file, dest)
 
+        from rule_sources import register_path_source
+        register_path_source(rules_dir, rule_name, rule_file, content=dest.read_bytes())
+
         print(f"Registered: '{rule_name}' -> {dest}")
+        print(f"Source path: {rule_file.resolve()} (re-run add-rule to refresh)")
 
     print()
     print("Apply now:")

package/scripts/hook_sources.py

@@ -119,6 +119,32 @@ def register_url_source(
     save_sources(hooks_dir, sources)
 
 
+def register_path_source(
+    hooks_dir: Path | None,
+    hook_name: str,
+    path: Path,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a local-file source entry for a hook.
+
+    Stores the absolute origin path so subsequent ``ai-toolkit update`` runs
+    can detect drift, plus a sha256 of the injected content.
+    """
+    import re
+    if not hook_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", hook_name):
+        raise ValueError(f"Invalid hook name: {hook_name!r}")
+    hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR
+    sources = load_sources(hooks_dir)
+    entry: dict[str, Any] = {
+        "path": str(Path(path).resolve()),
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        entry["sha256"] = hashlib.sha256(content).hexdigest()
+    sources[hook_name] = entry
+    save_sources(hooks_dir, sources)
+
+
 def unregister_source(hooks_dir: Path | None, hook_name: str) -> bool:
     """Remove a source entry. Returns True if found and removed."""
     hooks_dir = hooks_dir or EXTERNAL_HOOKS_DIR

package/scripts/inject_hook_cli.py

@@ -377,6 +377,18 @@ def inject(hooks_file: str, target_dir: str, source_override: str = "") -> None:
     save_json(str(settings_path), settings)
     print(f"Injected hooks from '{source}' into {settings_path}")
 
+    # Register local-file source so `status` and future updates can see it.
+    # URL sources are already registered earlier inside _fetch_and_cache().
+    if not is_url:
+        try:
+            from hook_sources import register_path_source
+            register_path_source(
+                None, source, Path(hooks_file),
+                content=Path(hooks_file).read_bytes(),
+            )
+        except Exception as exc:  # registration failure must not block injection
+            print(f"Warning: could not register local source: {exc}", file=sys.stderr)
+
     # Propagate Codex-compatible events to ~/.codex/hooks.json
     _inject_codex(tagged, source, target_dir)
 

package/scripts/install_steps/hooks.py

@@ -26,6 +26,7 @@ def install_hooks(claude_dir: Path, hooks_scripts_dir: Path,
         if output_styles_dir.is_dir():
             print("  Would install: output styles to ~/.claude/output-styles/ + set outputStyle in settings.json")
         print("  Would set: env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in settings.json")
+        print("  Would set: skillListingBudgetFraction=0.02 in settings.json (only if absent)")
         return
 
     _copy_hook_scripts(claude_dir, hooks_scripts_dir)
@@ -44,6 +45,7 @@ def install_hooks(claude_dir: Path, hooks_scripts_dir: Path,
 
     _install_output_styles(claude_dir)
     _install_env_vars(claude_dir)
+    _install_skill_listing_budget(claude_dir)
 
 
 def _copy_hook_scripts(claude_dir: Path, hooks_scripts_dir: Path) -> None:
@@ -151,3 +153,27 @@ def _install_env_vars(claude_dir: Path) -> None:
         with open(settings_path, "w", encoding="utf-8") as f:
             json.dump(settings_data, f, indent=4)
         print("  Set: env vars in settings.json (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)")
+
+
+# Default for skill listing budget. 0.02 (~2% of context) keeps all 112+ skill
+# descriptions loadable without truncation. Only applied if the user has not
+# already set the key — explicit user overrides are preserved.
+SKILL_LISTING_BUDGET_DEFAULT = 0.02
+
+
+def _install_skill_listing_budget(claude_dir: Path) -> None:
+    """Set skillListingBudgetFraction default if user has not configured one."""
+    settings_path = claude_dir / "settings.json"
+    if settings_path.is_file():
+        with open(settings_path, encoding="utf-8") as f:
+            settings_data = json.load(f)
+    else:
+        settings_data = {}
+
+    if "skillListingBudgetFraction" in settings_data:
+        return
+
+    settings_data["skillListingBudgetFraction"] = SKILL_LISTING_BUDGET_DEFAULT
+    with open(settings_path, "w", encoding="utf-8") as f:
+        json.dump(settings_data, f, indent=4)
+    print(f"  Set: skillListingBudgetFraction = {SKILL_LISTING_BUDGET_DEFAULT} in settings.json")

package/scripts/install_steps/install_state.py

@@ -7,7 +7,48 @@ from datetime import datetime, timezone
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
-from paths import TOOLKIT_DATA_DIR, STATE_FILE
+from paths import TOOLKIT_DATA_DIR, STATE_FILE, RULES_DIR, EXTERNAL_HOOKS_DIR
+
+
+def _load_sources(sources_file: Path, key: str) -> list[tuple[str, str, str, str]]:
+    """Read a sources.json registry.
+
+    Returns a list of ``(name, origin, fetched_at, kind)`` tuples where
+    ``kind`` is ``"url"`` for remote sources, ``"local"`` for path-tracked
+    sources, and ``"unknown"`` if neither field is present.
+    """
+    if not sources_file.is_file():
+        return []
+    try:
+        with open(sources_file, encoding="utf-8") as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return []
+    entries = data.get(key, {}) if isinstance(data, dict) else {}
+    if not isinstance(entries, dict):
+        return []
+    out: list[tuple[str, str, str, str]] = []
+    for name, meta in sorted(entries.items()):
+        if not isinstance(meta, dict):
+            continue
+        if "url" in meta:
+            origin, kind = str(meta["url"]), "url"
+        elif "path" in meta:
+            origin, kind = str(meta["path"]), "local"
+        else:
+            origin, kind = "", "unknown"
+        out.append((name, origin, str(meta.get("fetched_at", "")), kind))
+    return out
+
+
+def _orphan_rule_files(rules_dir: Path, registered: set[str]) -> list[str]:
+    """Return rule names present on disk but missing from sources.json."""
+    if not rules_dir.is_dir():
+        return []
+    return sorted(
+        f.stem for f in rules_dir.glob("*.md")
+        if f.stem not in registered
+    )
 
 
 def _state_path() -> Path:
@@ -204,6 +245,23 @@ def print_status() -> None:
     if mcp:
         print(f"  MCP:        {', '.join(mcp)}")
 
+    ext_rules = _load_sources(RULES_DIR / "sources.json", "rules")
+    ext_hooks = _load_sources(EXTERNAL_HOOKS_DIR / "sources.json", "hooks")
+    rule_orphans = _orphan_rule_files(RULES_DIR, {n for n, _, _, _ in ext_rules})
+    if ext_rules or ext_hooks or rule_orphans:
+        print()
+        print("  External sources:")
+        for name, origin, fetched_at, kind in ext_rules:
+            tag = " [local]" if kind == "local" else ""
+            stamp = f" ({fetched_at})" if fetched_at else ""
+            print(f"    rule  {name}  <- {origin}{tag}{stamp}")
+        for name in rule_orphans:
+            print(f"    rule  {name}  <- (orphan, no source recorded — re-run add-rule)")
+        for name, origin, fetched_at, kind in ext_hooks:
+            tag = " [local]" if kind == "local" else ""
+            stamp = f" ({fetched_at})" if fetched_at else ""
+            print(f"    hook  {name}  <- {origin}{tag}{stamp}")
+
     extends = state.get("extends")
     if extends:
         print(f"  Extends:    {extends.get('source', 'unknown')}")

package/scripts/rule_sources.py

@@ -120,6 +120,32 @@ def register_url_source(
     save_sources(rules_dir, sources)
 
 
+def register_path_source(
+    rules_dir: Path | None,
+    rule_name: str,
+    path: Path,
+    content: bytes | None = None,
+) -> None:
+    """Add or update a local-file source entry.
+
+    Stores the absolute origin path (so future ``add-rule`` re-runs from the
+    same project register cleanly) plus a sha256 of the current content.
+    """
+    import re
+    if not rule_name or not re.fullmatch(r"[a-zA-Z0-9_-]+", rule_name):
+        raise ValueError(f"Invalid rule name: {rule_name!r}")
+    rules_dir = rules_dir or RULES_DIR
+    sources = load_sources(rules_dir)
+    entry: dict[str, Any] = {
+        "path": str(Path(path).resolve()),
+        "fetched_at": datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ"),
+    }
+    if content is not None:
+        entry["sha256"] = hashlib.sha256(content).hexdigest()
+    sources[rule_name] = entry
+    save_sources(rules_dir, sources)
+
+
 def unregister_source(rules_dir: Path | None, rule_name: str) -> bool:
     """Remove a source entry. Returns True if found and removed."""
     rules_dir = rules_dir or RULES_DIR