@softspark/ai-toolkit 4.2.4 → 4.3.0

package/app/hooks/revert-guard.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# revert-guard.sh — Block git revert/restore on files edited in this session.
+#
+# Fires on: PreToolUse
+# Matcher: Bash
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+#
+# Constitution Art. VI.2 ("Fix Every Found Bug"): when a session has produced
+# edits, a `git checkout/restore/reset --hard/clean -fd` on those files is
+# almost always discarding work-in-progress instead of fixing the root cause.
+# Block it unless the user explicitly opted in.
+#
+# Escape hatch: set CLAUDE_REVERT_OK=1 (per-call) to bypass.
+# Exit codes:
+#   0  allow command
+#   2  block (per Claude Code hooks spec)
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_locate-toolkit.sh
+source "$(dirname "$0")/_locate-toolkit.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+
+INPUT=$(cat)
+COMMAND=$(hook_command)
+
+[ -z "$COMMAND" ] && exit 0
+[ "${CLAUDE_REVERT_OK:-0}" = "1" ] && exit 0
+[ -z "$TOOLKIT_DIR" ] && exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# Strip leading words so we can match the git verb.
+# Only act on commands whose first token is `git`.
+read -r FIRST _rest <<<"$COMMAND"
+[ "$FIRST" = "git" ] || exit 0
+
+# Helper: emit block message on stderr and exit 2.
+_block() {
+    local reason="$1"
+    local detail="$2"
+    cat >&2 <<EOF
+revert-guard: BLOCKED — $reason
+Constitution Art. VI.2: do not revert work-in-progress. Fix the root cause instead.
+
+Affected: $detail
+
+If you really need to discard changes, re-run with:
+    CLAUDE_REVERT_OK=1 $COMMAND
+EOF
+    exit 2
+}
+
+# git reset --hard / git clean -fd: clobber-style, scope = all session edits.
+if printf '%s' "$COMMAND" | grep -Eq 'reset[[:space:]]+(-+[A-Za-z-]+[[:space:]]+)*--hard|clean[[:space:]]+-[A-Za-z]*[df]'; then
+    edited=$(python3 "$TOOLKIT_DIR/scripts/session_state.py" list 2>/dev/null | head -10)
+    if [ -n "$edited" ]; then
+        _block "destructive 'git reset --hard' / 'git clean' with session edits in tree" "$edited"
+    fi
+    exit 0
+fi
+
+# git checkout / git restore: only block when `--` separator is present
+# (file-restore form). Bare `git checkout branch-name` is allowed.
+if printf '%s' "$COMMAND" | grep -Eq '(checkout|restore)([[:space:]].*)?[[:space:]]--[[:space:]]'; then
+    files=$(printf '%s' "$COMMAND" | awk -F' -- ' '{print $2}')
+    [ -z "$files" ] && exit 0
+    blocked=""
+    for f in $files; do
+        # Resolve relative paths against $PWD.
+        case "$f" in
+            /*) abs="$f" ;;
+            *)  abs="$PWD/$f" ;;
+        esac
+        if python3 "$TOOLKIT_DIR/scripts/session_state.py" was-edited "$abs" >/dev/null 2>&1; then
+            blocked="$blocked $f"
+        fi
+    done
+    if [ -n "$blocked" ]; then
+        _block "restoring file(s) edited in this session" "$blocked"
+    fi
+fi
+
+exit 0

package/app/hooks/search-tracker.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# search-tracker.sh — Clear search-required flag when a search tool runs.
+#
+# Fires on: PostToolUse
+# Matcher: mcp__rag-mcp__smart_query|mcp__rag-mcp__hybrid_search_kb|mcp__rag-mcp__crag_search|mcp__rag-mcp__multi_hop_search|WebSearch|WebFetch
+# Non-blocking: always exits 0.
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+#
+# Paired with user-prompt-submit.sh (sets the flag) and stop-search-check.sh
+# (blocks Stop when flag still present). Together they implement the Step 0
+# "search before answering" rule from global CLAUDE.md.
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+
+FLAG="$HOME/.softspark/ai-toolkit/state/search-required.flag"
+rm -f "$FLAG" 2>/dev/null
+exit 0

package/app/hooks/session-start.sh

@@ -8,9 +8,21 @@
 echo "MANDATORY: Before answering ANY technical question, apply ALL rules from your CLAUDE.md files (global + project). Follow the exact order of operations defined there. Do NOT skip mandatory steps even if you think you already know the answer."
 echo "REMINDER: When writing features or fixing bugs, ensure tests cover the changes. When modifying API, config, or setup, update relevant documentation. Propose these steps to the user — do not silently skip them."
 
+# shellcheck source=_locate-toolkit.sh
+source "$(dirname "$0")/_locate-toolkit.sh"
+
+# 1a. Reset per-session edit state (used by revert-guard, test-cohesion, quality-gate)
+SESSION_ID_INPUT=""
+if [ ! -t 0 ]; then
+    STDIN_PAYLOAD="$(cat)"
+    SESSION_ID_INPUT="$(printf '%s' "$STDIN_PAYLOAD" | jq -r '.session_id // empty' 2>/dev/null)"
+fi
+if [ -n "$TOOLKIT_DIR" ] && command -v python3 >/dev/null 2>&1; then
+    python3 "$TOOLKIT_DIR/scripts/session_state.py" reset \
+        ${SESSION_ID_INPUT:+--session-id "$SESSION_ID_INPUT"} >/dev/null 2>&1 || true
+fi
+
 # 2. Check for updates (cached, max once per 24h, non-blocking)
-TOOLKIT_DIR="$(npm root -g 2>/dev/null)/@softspark/ai-toolkit"
-[ ! -d "$TOOLKIT_DIR" ] && TOOLKIT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
 VERSION_MSG=$(python3 "$TOOLKIT_DIR/scripts/version_check.py" 2>/dev/null)
 if [ -n "$VERSION_MSG" ]; then
     echo "$VERSION_MSG"

package/app/hooks/stop-search-check.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# stop-search-check.sh — Block Stop when search-first rule was skipped.
+#
+# Fires on: Stop
+# Matcher: all
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal.
+#
+# If user-prompt-submit.sh set the search-required flag and no search tool
+# was invoked (search-tracker.sh would have cleared it), this hook continues
+# the conversation with a JSON `decision: block` payload so Claude reads the
+# reminder and calls smart_query() before the next response.
+#
+# Override (one-off): CLAUDE_SKIP_SEARCH_FIRST=1
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+# shellcheck source=_search-capability.sh
+source "$(dirname "$0")/_search-capability.sh"
+
+[ "${CLAUDE_SKIP_SEARCH_FIRST:-0}" = "1" ] && exit 0
+
+FLAG="$HOME/.softspark/ai-toolkit/state/search-required.flag"
+[ -f "$FLAG" ] || exit 0
+
+if ! ai_toolkit_has_search_provider; then
+    rm -f "$FLAG" 2>/dev/null
+    exit 0
+fi
+
+# Read the original prompt (line 2 of the flag file) for the reminder.
+PROMPT_PREVIEW=$(sed -n '2p' "$FLAG" 2>/dev/null | head -c 200)
+rm -f "$FLAG" 2>/dev/null  # one-shot; do not loop forever
+
+hook_emit_block "Stop" "Step 0 violated: you responded to a technical prompt without calling smart_query() or hybrid_search_kb() first. Per global CLAUDE.md GOLDEN RULE: search KB BEFORE answering. Prompt was: \"${PROMPT_PREVIEW}...\". Now: call the search tool, then continue your reply. Override (one-off): CLAUDE_SKIP_SEARCH_FIRST=1."
+exit 0

package/app/hooks/test-cohesion-map.json

@@ -0,0 +1,77 @@
+[
+    {
+        "match": "app/hooks/quality-gate.sh",
+        "tests": ["tests/test_hooks.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks/quality-check.sh",
+        "tests": ["tests/test_hooks.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks/revert-guard.sh",
+        "tests": ["tests/test_revert_guard_hook.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks/test-cohesion.sh",
+        "tests": ["tests/test_test_cohesion_hook.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks/config-desync-guard.sh",
+        "tests": ["tests/test_config_desync_guard.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks/instructions-audit.sh",
+        "tests": ["tests/test_instructions_audit.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks/user-prompt-submit.sh",
+        "tests": ["tests/test_hooks.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks/*.sh",
+        "tests": ["tests/test_hooks.bats", "tests/test_hooks_per_editor.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "app/hooks.json",
+        "tests": ["tests/test_hooks.bats", "tests/test_merge_hooks_statusline.bats", "tests/test_hooks_per_editor.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "scripts/merge-hooks.py",
+        "tests": ["tests/test_merge_hooks_statusline.bats", "tests/test_inject_hook.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "scripts/session_state.py",
+        "tests": ["tests/test_session_state.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "scripts/test_cohesion.py",
+        "tests": ["tests/test_test_cohesion_resolver.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "scripts/inject_hook_cli.py",
+        "tests": ["tests/test_inject_hook.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "scripts/inject_rule_cli.py",
+        "tests": ["tests/test_inject.bats"],
+        "runner": "bats"
+    },
+    {
+        "match": "scripts/validate.py",
+        "tests": ["tests/test_validate.bats", "tests/test_validate_negative.bats"],
+        "runner": "bats"
+    }
+]

package/app/hooks/test-cohesion.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# test-cohesion.sh — Run related tests after edits, block if they fail.
+#
+# Fires on: PostToolUse
+# Matcher: Edit|MultiEdit|Write
+# Skipped when TOOLKIT_HOOK_PROFILE=minimal or CLAUDE_HOOK_BOOTSTRAP=1.
+#
+# Constitution Art. VI.3 ("Tests and Docs Follow Behavior"): when source code
+# changes, the matching tests must pass before the agent can continue. This
+# hook resolves a per-project test-cohesion map and runs only the related
+# test files (NOT the full suite).
+#
+# Map lookup (first found wins):
+#   1. $PWD/.claude/test-cohesion-map.json (project-local)
+#   2. $TOOLKIT_DIR/app/hooks/test-cohesion-map.json (toolkit default)
+#
+# Escape hatches:
+#   CLAUDE_HOOK_BOOTSTRAP=1   bypass (used when editing the hook itself)
+#   CLAUDE_SKIP_COHESION=1    one-off bypass
+#
+# Exit codes:
+#   0  no map / no match / tests passed
+#   2  related test command failed
+
+# shellcheck source=_profile-check.sh
+source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_locate-toolkit.sh
+source "$(dirname "$0")/_locate-toolkit.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+
+[ "${CLAUDE_HOOK_BOOTSTRAP:-0}" = "1" ] && exit 0
+[ "${CLAUDE_SKIP_COHESION:-0}" = "1" ] && exit 0
+
+INPUT=$(cat)
+FILE_PATH=$(hook_file_path)
+
+[ -z "$FILE_PATH" ] && exit 0
+[ -z "$TOOLKIT_DIR" ] && exit 0
+command -v python3 >/dev/null 2>&1 || exit 0
+
+REPO_ROOT="$PWD"
+# Prefer git repo root when available; fall back to PWD.
+if command -v git >/dev/null 2>&1; then
+    git_root=$(git rev-parse --show-toplevel 2>/dev/null)
+    [ -n "$git_root" ] && REPO_ROOT="$git_root"
+fi
+
+# Resolve symlinks on both sides so the cohesion-map glob can match files
+# under symlinked roots (e.g. /tmp -> /private/tmp on macOS).
+REAL_FILE=$(python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$FILE_PATH" 2>/dev/null)
+REAL_REPO=$(python3 -c "import os,sys; print(os.path.realpath(sys.argv[1]))" "$REPO_ROOT" 2>/dev/null)
+[ -z "$REAL_FILE" ] && REAL_FILE="$FILE_PATH"
+[ -z "$REAL_REPO" ] && REAL_REPO="$REPO_ROOT"
+
+COMMANDS=$(python3 "$TOOLKIT_DIR/scripts/test_cohesion.py" resolve \
+    --changed-paths "$REAL_FILE" --repo-root "$REAL_REPO" 2>/dev/null)
+[ -z "$COMMANDS" ] && exit 0
+
+# Run each resolved command. Block on first failure.
+LOG_DIR="$HOME/.softspark/ai-toolkit/state"
+mkdir -p "$LOG_DIR" 2>/dev/null
+LOG_FILE="$LOG_DIR/test-cohesion-last.log"
+
+cd "$REAL_REPO" || exit 0
+FAILED=""
+while IFS= read -r cmd; do
+    [ -z "$cmd" ] && continue
+    if ! bash -c "$cmd" >"$LOG_FILE" 2>&1; then
+        FAILED="$cmd"
+        break
+    fi
+done <<<"$COMMANDS"
+
+if [ -n "$FAILED" ]; then
+    cat >&2 <<EOF
+test-cohesion: BLOCKED — tests for ${FILE_PATH} failed.
+Constitution Art. VI.3: tests must pass before continuing.
+
+Command:
+    $FAILED
+
+Last log (truncated):
+$(tail -20 "$LOG_FILE")
+
+Fix the failing test OR update it to match the new behavior (Art. VI.3).
+Override (one-off): CLAUDE_SKIP_COHESION=1
+EOF
+    exit 2
+fi
+
+[ "${AI_TOOLKIT_HOOK_FORMAT:-}" = "json" ] || echo "test-cohesion: related tests passed for ${FILE_PATH}"
+exit 0

package/app/hooks/track-usage.sh

@@ -11,7 +11,9 @@ STATS_FILE="${HOME}/.softspark/ai-toolkit/stats.json"
 
 # Read prompt from stdin (Claude Code passes JSON with .prompt field)
 INPUT=$(cat)
-PROMPT_TEXT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+PROMPT_TEXT=$(hook_prompt)
 [ -z "$PROMPT_TEXT" ] && exit 0
 
 # Only track if prompt starts with a slash command

package/app/hooks/user-prompt-submit.sh

@@ -7,21 +7,48 @@
 
 # shellcheck source=_profile-check.sh
 source "$(dirname "$0")/_profile-check.sh"
+# shellcheck source=_hook-io.sh
+source "$(dirname "$0")/_hook-io.sh"
+# shellcheck source=_search-capability.sh
+source "$(dirname "$0")/_search-capability.sh"
 
 # Read prompt from stdin (Claude Code passes JSON with .prompt field)
 INPUT=$(cat)
-PROMPT_TEXT=$(echo "$INPUT" | jq -r '.prompt // empty' 2>/dev/null)
+PROMPT_TEXT=$(hook_prompt)
 LOWERED="$(printf '%s' "$PROMPT_TEXT" | tr '[:upper:]' '[:lower:]')"
 
-echo "STOP. Execute Step 0 before responding: check your CLAUDE.md for search-first rules. If search-first rules exist, call the required search tool NOW — before any other tool or text output. If you skip this step, the user will interrupt you."
+# Heuristic search-required flag (paired with search-tracker.sh + Stop check).
+# Set only when a search provider is detectable or strict mode is requested.
+# Cleared by search-tracker.sh after smart_query / hybrid_search_kb / web runs.
+PROMPT_LEN=${#PROMPT_TEXT}
+STATE_DIR="$HOME/.softspark/ai-toolkit/state"
+FLAG="$STATE_DIR/search-required.flag"
+mkdir -p "$STATE_DIR" 2>/dev/null
+if [ "$PROMPT_LEN" -gt 30 ] && \
+   [ "${CLAUDE_SKIP_SEARCH_FIRST:-0}" != "1" ] && \
+   ai_toolkit_has_search_provider; then
+    printf '%s\n%s\n' "$(date -u +%s)" "$PROMPT_TEXT" > "$FLAG" 2>/dev/null
+else
+    rm -f "$FLAG" 2>/dev/null
+fi
+
+if ai_toolkit_has_search_provider; then
+    CONTEXT_MSG="STOP. Execute Step 0 before responding: check your CLAUDE.md for search-first rules. If search-first rules exist and a search tool is available, call the required search tool NOW — before any other tool or text output."
+else
+    CONTEXT_MSG="Search-first note: no ai-toolkit search provider was detected, so search-first enforcement is advisory only. Use available local evidence; do not call unavailable RAG/MCP tools."
+fi
 
 if printf '%s' "$LOWERED" | grep -Eq 'architecture|design|migration|deploy|rollback|refactor|plugin|workflow'; then
-    echo "UserPromptSubmit: task looks architectural or multi-step. Use plan mode, define success criteria, and validate before marking done."
+    CONTEXT_MSG="$CONTEXT_MSG
+UserPromptSubmit: task looks architectural or multi-step. Use plan mode, define success criteria, and validate before marking done."
 elif printf '%s' "$LOWERED" | grep -Eq 'bug|error|fail|failing|incident|outage|debug'; then
-    echo "UserPromptSubmit: debugging request detected. Gather evidence first, then propose the smallest safe fix and targeted tests."
+    CONTEXT_MSG="$CONTEXT_MSG
+UserPromptSubmit: debugging request detected. Gather evidence first, then propose the smallest safe fix and targeted tests."
 else
-    echo "UserPromptSubmit: apply KB-first research, keep changes minimal, and update tests/docs when behavior changes."
+    CONTEXT_MSG="$CONTEXT_MSG
+UserPromptSubmit: apply KB-first research, keep changes minimal, and update tests/docs when behavior changes."
 fi
 
-exit 0
+hook_emit_context "$CONTEXT_MSG"
 
+exit 0

package/app/hooks.json

@@ -39,7 +39,7 @@
                 "hooks": [
                     {
                         "type": "command",
-                        "command": "bash ~/.softspark/ai-toolkit/hooks/notify-waiting.sh"
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/notify-waiting.sh\""
                     }
                 ]
             }
@@ -84,6 +84,16 @@
                         "command": "\"$HOME/.softspark/ai-toolkit/hooks/commit-quality.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Bash",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/revert-guard.sh\""
+                    }
+                ]
             }
         ],
         "UserPromptSubmit": [
@@ -128,6 +138,26 @@
                         "command": "\"$HOME/.softspark/ai-toolkit/hooks/governance-capture.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "Edit|MultiEdit|Write",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/test-cohesion.sh\""
+                    }
+                ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "mcp__rag-mcp__smart_query|mcp__rag-mcp__hybrid_search_kb|mcp__rag-mcp__crag_search|mcp__rag-mcp__multi_hop_search|mcp__rag-mcp__verify_answer|WebSearch|WebFetch",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/search-tracker.sh\""
+                    }
+                ]
             }
         ],
         "Stop": [
@@ -160,6 +190,16 @@
                         "command": "\"$HOME/.softspark/ai-toolkit/hooks/quality-gate.sh\""
                     }
                 ]
+            },
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/stop-search-check.sh\""
+                    }
+                ]
             }
         ],
         "TaskCompleted": [
@@ -243,6 +283,30 @@
                     }
                 ]
             }
+        ],
+        "InstructionsLoaded": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/instructions-audit.sh\""
+                    }
+                ]
+            }
+        ],
+        "ConfigChange": [
+            {
+                "_source": "ai-toolkit",
+                "matcher": "user_settings",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "\"$HOME/.softspark/ai-toolkit/hooks/config-desync-guard.sh\""
+                    }
+                ]
+            }
         ]
     },
     "statusLine": {

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-05-12T10:01:38Z",
+  "last_run": "2026-05-12T19:04:22Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,7 +24,7 @@
       }
     },
     "augment": {
-      "docs_hash": "b746d5dbbc5a2936",
+      "docs_hash": "ceaf27b7126f44dd",
       "headings": [
         "Agent",
         "Chat",
@@ -57,7 +57,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "9e0292a9f92392e0",
+      "docs_hash": "6ea2ec6ef023c1bd",
       "headings": [
         "Claude Code overview",
         "Documentation Index",
@@ -137,7 +137,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "3f963da56d00add9",
+      "docs_hash": "c8fb328bf1954fc2",
       "headings": [
         "About",
         "Contributing",
@@ -189,7 +189,7 @@
       "version": "codex-cli 0.130.0"
     },
     "cursor": {
-      "docs_hash": "705adfd617433088",
+      "docs_hash": "787203a4eee076f7",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -205,7 +205,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "93694630a3d04327",
+      "docs_hash": "26555623f610ff8e",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -244,7 +244,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "d9b9fcdfe3b67469",
+      "docs_hash": "1566c05f84f5c1a7",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -353,7 +353,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "66295add1d0f0645",
+      "docs_hash": "7a8a7569f81eba1b",
       "headings": [
         "Advanced",
         "App Deploys",

package/bin/ai-toolkit.js

@@ -69,6 +69,8 @@ const COMMANDS = {
   'remove-rule': 'Unregister a rule from ~/.softspark/ai-toolkit/rules/ and remove its block from CLAUDE.md',
   'inject-hook': 'Inject external hooks (file or URL) into ~/.claude/settings.json (URL hooks auto-refresh on update)',
   'remove-hook': 'Remove injected hooks by source name from ~/.claude/settings.json (also unregisters URL source)',
+  'inject-mcp': 'Inject external MCP template (file or URL) into ~/.mcp.json + all editor MCP configs (URL templates auto-refresh on update)',
+  'remove-mcp': 'Remove injected MCP servers by source name from ~/.mcp.json and all editor configs',
   validate: 'Verify toolkit integrity',
   doctor: 'Check install health, hooks, and artifact drift',
   eject: 'Export standalone config (no symlinks, no toolkit dependency)',
@@ -257,6 +259,14 @@ function showHelp() {
   console.log('\nOptions for remove-hook:');
   console.log('  <source-name>   Source tag to remove (also unregisters URL source if present)');
   console.log('  [target-dir]    Target dir containing .claude/settings.json (default: $HOME)');
+  console.log('\nOptions for inject-mcp:');
+  console.log('  <template-file-or-url>  Path to JSON file or HTTPS URL with {"mcpServers": {...}}');
+  console.log('  [target-dir]            Target dir for .mcp.json + editor configs (default: $HOME)');
+  console.log('  --name <name>           Override source name (default: filename/URL stem)');
+  console.log('  --force                 Overwrite servers tagged with a different _source');
+  console.log('\nOptions for remove-mcp:');
+  console.log('  <source-name>   Source tag to remove (also unregisters URL source and cleans editor configs)');
+  console.log('  [target-dir]    Target dir containing .mcp.json (default: $HOME)');
   console.log('\nOptions for add-rule:');
   console.log('  <rule-file>     Path to .md rule file or HTTPS URL to register globally');
   console.log('  [rule-name]     Override rule name (default: filename/URL stem without .md)');
@@ -417,6 +427,37 @@ function handleRemoveHook(args) {
   run(scriptPath('inject_hook_cli.py'), ['--remove', sourceName, targetDir]);
 }
 
+/**
+ * Handle `ai-toolkit inject-mcp` -- injects external MCP template (file or URL) into .mcp.json
+ * and propagates to all editor MCP configs.
+ * @param {string[]} args
+ */
+function handleInjectMcp(args) {
+  const source = args[0];
+  if (!source) {
+    console.error('Usage: ai-toolkit inject-mcp <template-file-or-url> [target-dir] [--name <name>] [--force]');
+    process.exit(1);
+  }
+  const isUrl = source.startsWith('https://') || source.startsWith('http://');
+  const resolvedSource = isUrl ? source : path.resolve(CWD, source);
+  const remaining = args.slice(1);
+  run(scriptPath('inject_mcp_cli.py'), [resolvedSource, ...remaining]);
+}
+
+/**
+ * Handle `ai-toolkit remove-mcp` -- removes injected MCP servers by source name.
+ * @param {string[]} args
+ */
+function handleRemoveMcp(args) {
+  const sourceName = args[0];
+  if (!sourceName) {
+    console.error('Usage: ai-toolkit remove-mcp <template-source-name> [target-dir]');
+    process.exit(1);
+  }
+  const targetDir = args[1] || process.env.HOME;
+  run(scriptPath('inject_mcp_cli.py'), ['--remove', sourceName, targetDir]);
+}
+
 /**
  * Handle `ai-toolkit mcp` -- delegates to mcp_manager.py with subcommand.
  * @param {string[]} args
@@ -566,6 +607,8 @@ const SPECIAL_HANDLERS = {
   'add-rule':     handleAddRule,
   'inject-hook':  handleInjectHook,
   'remove-hook':  handleRemoveHook,
+  'inject-mcp':   handleInjectMcp,
+  'remove-mcp':   handleRemoveMcp,
   'llms-txt':     (_args) => generateLlmsTxt(),
   'antigravity-rules': (_args) => run(scriptPath('generate_antigravity.py'), [CWD]),
   'cursor-mdc':   (_args) => run(scriptPath('generate_cursor_mdc.py'), [CWD]),

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

@@ -144,7 +144,7 @@ ai-toolkit doctor
 - Environment: node, bash, python3, bats
 - Global Install: .claude exists, agents/skills symlinks (0 broken), settings.json hooks
 - Hook Scripts: all present and executable
-- Hook Configuration: 12 events registered
+- Hook Configuration: 14 events registered
 - Generated Artifacts: AGENTS.md, llms.txt, llms-full.txt
 - Planned Assets: plugin.json, benchmarks, plugin packs
 - Benchmark Freshness: < 30 days
@@ -194,7 +194,7 @@ python3 scripts/audit_skills.py --ci
 
 **Verify validate.py:**
 - [ ] Agents >= 44, Skills >= 99, Tests >= 900
-- [ ] Hook events: 12, Hook scripts: >= 20
+- [ ] Hook events: 14, Hook scripts: >= 30
 - [ ] Plugin packs >= 10, KB documents >= 20
 - [ ] `Errors: 0 | Warnings: 0` → `VALIDATION PASSED`
 

package/kb/reference/architecture-overview.md

@@ -264,7 +264,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 ## Quality Hooks
 
-22 entries across 12 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
+28 entries across 14 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
 
 | Hook | Trigger | Script | Action |
 |------|---------|--------|--------|