@softspark/ai-toolkit 1.9.0 → 2.0.0

package/kb/reference/hooks-catalog.md

@@ -13,17 +13,17 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.ai-toolkit/hooks/`.
+ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
 ## Installation
 
 ```bash
-ai-toolkit install    # copies scripts to ~/.ai-toolkit/hooks/, merges into settings.json
+ai-toolkit install    # copies scripts to ~/.softspark/ai-toolkit/hooks/, merges into settings.json
 ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 ```
 
 **File locations:**
-- Scripts: `~/.ai-toolkit/hooks/*.sh`
+- Scripts: `~/.softspark/ai-toolkit/hooks/*.sh`
 - Config: `~/.claude/settings.json` → `hooks` key
 - Source: `ai-toolkit/app/hooks/*.sh` + `app/hooks.json`
 
@@ -35,7 +35,7 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 |-------|-------|
 | Event | `SessionStart` |
 | Matcher | `startup\|compact` |
-| Script | `~/.ai-toolkit/hooks/session-start.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/session-start.sh` |
 | Fires | Session start + after context compaction |
 
 **Actions:**
@@ -50,7 +50,7 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 |-------|-------|
 | Event | `Notification` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/notify-waiting.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/notify-waiting.sh` |
 | Fires | Claude Code waiting for user input |
 
 **Action:** Cross-platform desktop notification ("Claude Code needs your attention"):
@@ -64,7 +64,7 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 |-------|-------|
 | Event | `PreToolUse` |
 | Matcher | `Bash` |
-| Script | `~/.ai-toolkit/hooks/guard-destructive.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/guard-destructive.sh` |
 | Fires | Before any Bash command |
 
 **Action:** Blocks (exit 2) commands matching destructive patterns:
@@ -80,7 +80,7 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 |-------|-------|
 | Event | `PreToolUse` |
 | Matcher | `Bash\|Read\|Edit\|Write\|MultiEdit\|Glob\|Grep\|NotebookEdit\|mcp__filesystem__.*` |
-| Script | `~/.ai-toolkit/hooks/guard-path.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/guard-path.sh` |
 | Fires | Before any file access tool (including Bash, MCP filesystem) |
 
 **Action:** Blocks (exit 2) when a path contains `/Users/<wrong>` or `/home/<wrong>` that doesn't match the actual `$HOME`. Prevents Claude from hallucinating or confusing similar usernames (common with non-ASCII names like Polish names).
@@ -93,7 +93,7 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 |-------|-------|
 | Event | `UserPromptSubmit` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/user-prompt-submit.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/user-prompt-submit.sh` |
 | Fires | Before Claude starts working on a submitted prompt |
 
 **Action:** Adds a lightweight governance reminder: plan mode for architectural work, evidence-first debugging, KB-first research, and validation expectations.
@@ -106,10 +106,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `UserPromptSubmit` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/track-usage.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/track-usage.sh` |
 | Fires | Before Claude starts working on a submitted prompt |
 
-**Action:** Records skill invocations (slash commands like `/commit`, `/review`) to `~/.ai-toolkit/stats.json` for local usage analytics. Non-slash prompts are ignored.
+**Action:** Records skill invocations (slash commands like `/commit`, `/review`) to `~/.softspark/ai-toolkit/stats.json` for local usage analytics. Non-slash prompts are ignored.
 
 ### PostToolUse (edit feedback) — `post-tool-use.sh`
 
@@ -117,7 +117,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `PostToolUse` |
 | Matcher | `Edit\|MultiEdit\|Write` |
-| Script | `~/.ai-toolkit/hooks/post-tool-use.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/post-tool-use.sh` |
 | Fires | After file edit/write tool operations |
 
 **Action:** Adds a lightweight reminder to run relevant validation, tests, and documentation updates after edits.
@@ -130,7 +130,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `Stop` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/quality-check.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/quality-check.sh` |
 | Fires | After every Claude response |
 
 **Action:** Runs language-appropriate linter:
@@ -148,7 +148,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `Stop` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/save-session.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
 
 **Action:** Writes enriched session context to `.claude/session-context.md` for cross-session persistence. Captures:
@@ -164,7 +164,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `TaskCompleted` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/quality-gate.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/quality-gate.sh` |
 | Fires | When an Agent Teams task is marked complete |
 
 **Action:** Runs lint/typecheck. **Blocks completion (exit 2)** if errors found. Strict profile also runs `mypy --strict`.
@@ -177,7 +177,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `SubagentStart` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/subagent-start.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/subagent-start.sh` |
 | Fires | When a subagent is spawned |
 
 **Action:** Reminds subagents to stay narrow in scope, gather evidence first, and return explicit validation notes.
@@ -190,7 +190,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `SubagentStop` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/subagent-stop.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/subagent-stop.sh` |
 | Fires | When a subagent completes |
 
 **Action:** Enforces a concise handoff checklist: findings, files touched, tests run, risks, and docs follow-up.
@@ -203,7 +203,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `PreCompact` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/pre-compact.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/pre-compact.sh` |
 | Fires | Before context compaction |
 
 **Actions (prioritized — higher priority items survive tighter token budgets):**
@@ -221,7 +221,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `SessionEnd` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/session-end.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
 | Fires | When a Claude session ends |
 
 **Action:** Writes `.claude/session-end.md` with a lightweight handoff note for the next session and reminds the next session to review preserved context.
@@ -248,7 +248,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `PreToolUse` |
 | Matcher | `Edit\|Write\|MultiEdit` |
-| Script | `~/.ai-toolkit/hooks/guard-config.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/guard-config.sh` |
 | Fires | Before any file write/edit operation |
 
 **Action:** Blocks (exit 2) edits to linter and formatter config files — `.eslintrc`, `.eslintrc.*`, `eslint.config.*`, `.prettierrc`, `.prettierrc.*`, `prettier.config.*`, `tsconfig.json`, `tsconfig.*.json` — unless the request contains an explicit acknowledgment phrase (e.g. "intentionally editing config"). Returns a human-readable explanation to Claude so it can ask the user for confirmation before retrying.
@@ -259,7 +259,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `SessionStart` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/mcp-health.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/mcp-health.sh` |
 | Fires | Session start |
 
 **Action:** Non-blocking (always exits 0). Reads MCP server definitions from `~/.claude/settings.json` and any local `.mcp.json`. For each configured server, checks whether the required runtime command (`npx`, `uvx`, `docker`, etc.) is available in `$PATH`. Emits warnings for any missing runtimes, including install hints (e.g. "npm install -g npx"). Helps surface MCP misconfiguration early without interrupting the session.
@@ -270,10 +270,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `PostToolUse` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/governance-capture.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/governance-capture.sh` |
 | Fires | After any tool use |
 
-**Action:** Non-blocking (always exits 0). Logs security-sensitive operations (Bash commands, file writes to sensitive paths, large writes) to `~/.ai-toolkit/governance.log` with ISO timestamp, session ID, tool name, and a content excerpt. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+**Action:** Non-blocking (always exits 0). Logs security-sensitive operations (Bash commands, file writes to sensitive paths, large writes) to `~/.softspark/ai-toolkit/governance.log` with ISO timestamp, session ID, tool name, and a content excerpt. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 ### PreCompact — `pre-compact-save.sh`
 
@@ -281,10 +281,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `PreCompact` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/pre-compact-save.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/pre-compact-save.sh` |
 | Fires | Before context compaction |
 
-**Action:** Saves a timestamped context snapshot to `~/.ai-toolkit/compactions/YYYY-MM-DD_HH-MM-SS.txt`. Captures session ID, working directory, git branch and status, and environment metadata. Provides an audit trail of what was in context at each compaction point. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+**Action:** Saves a timestamped context snapshot to `~/.softspark/ai-toolkit/compactions/YYYY-MM-DD_HH-MM-SS.txt`. Captures session ID, working directory, git branch and status, and environment metadata. Provides an audit trail of what was in context at each compaction point. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 ### PreToolUse (commit quality) — `commit-quality.sh`
 
@@ -292,7 +292,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `PreToolUse` |
 | Matcher | `Bash` |
-| Script | `~/.ai-toolkit/hooks/commit-quality.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/commit-quality.sh` |
 | Fires | Before any Bash command |
 
 **Action:** Non-blocking (always exits 0). Inspects Bash commands containing `git commit`. Extracts the commit message from the `-m` flag and checks it against Conventional Commits format (`type: description`, where type is one of feat/fix/docs/refactor/test/chore/ci/perf/style/revert). Emits an advisory warning if the message does not match — the commit is not blocked, only nudged. Commands without `git commit` or without a `-m` message (e.g. interactive commits) are ignored.
@@ -303,10 +303,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 |-------|-------|
 | Event | `SessionStart` |
 | Matcher | *(all)* |
-| Script | `~/.ai-toolkit/hooks/session-context.sh` |
+| Script | `~/.softspark/ai-toolkit/hooks/session-context.sh` |
 | Fires | Session start |
 
-**Action:** Captures an environment snapshot to `~/.ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+**Action:** Captures an environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 ## Runtime Profiles
 
@@ -325,7 +325,7 @@ Set in `.claude/settings.local.json`:
 ## Architecture
 
 ```
-~/.ai-toolkit/
+~/.softspark/ai-toolkit/
 ├── rules/          # Registered rules (add-rule.sh)
 └── hooks/          # Hook scripts (copied on install)
     ├── _profile-check.sh    # Shared: profile skip logic (sourced by hooks)
@@ -350,7 +350,7 @@ Set in `.claude/settings.local.json`:
     └── session-end.sh
 
 ~/.claude/settings.json
-└── hooks:          # Hook definitions referencing ~/.ai-toolkit/hooks/
+└── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
     ├── SessionStart     → session-start.sh, mcp-health.sh, session-context.sh
     ├── Notification     → osascript (inline)
     ├── PreToolUse       → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh
@@ -380,7 +380,7 @@ Set in `.claude/settings.local.json`:
 
 **Hook script not found:**
 ```bash
-ls ~/.ai-toolkit/hooks/     # should list 21 .sh files (plus _profile-check.sh helper)
+ls ~/.softspark/ai-toolkit/hooks/     # should list 21 .sh files (plus _profile-check.sh helper)
 ai-toolkit update            # re-copies scripts
 ```
 

package/kb/reference/integrations.md

@@ -25,9 +25,9 @@ ai-toolkit add-rule ./jira-rules.md
 ai-toolkit update   # inject now
 ```
 
-After registration, `ai-toolkit update` will always re-inject the rule. Registry location: `~/.ai-toolkit/rules/`.
+After registration, `ai-toolkit update` will always re-inject the rule. Registry location: `~/.softspark/ai-toolkit/rules/`.
 
-To unregister a rule (removes from `~/.ai-toolkit/rules/` and strips the block from `CLAUDE.md`):
+To unregister a rule (removes from `~/.softspark/ai-toolkit/rules/` and strips the block from `CLAUDE.md`):
 
 ```bash
 ai-toolkit remove-rule jira-rules
@@ -55,7 +55,7 @@ Content outside markers is never touched. Re-running updates only the marked blo
 
 1. Create `<name>-rules.md` in your repo with Claude-relevant conventions
 2. Register it: `ai-toolkit add-rule ./<name>-rules.md`
-3. Verify it appears in: `~/.ai-toolkit/rules/<name>-rules.md`
+3. Verify it appears in: `~/.softspark/ai-toolkit/rules/<name>-rules.md`
 4. On next `install` it will be listed in: `Rules injected: ... <name>-rules`
 5. Add an entry below documenting the integration
 

package/kb/reference/manifest-install.md

@@ -6,7 +6,7 @@ tags: [install, manifest, modules, profiles, auto-detect, state-tracking]
 version: "1.0.0"
 created: "2026-04-07"
 last_updated: "2026-04-07"
-description: "Reference for the manifest-driven install system: 17 modules, 4 profiles, auto-detection, and state tracking in ~/.ai-toolkit/state.json."
+description: "Reference for the manifest-driven install system: 17 modules, 4 profiles, auto-detection, and state tracking in ~/.softspark/ai-toolkit/state.json."
 ---
 
 # Manifest-Driven Install System
@@ -107,7 +107,7 @@ Lists all currently installed modules with version and install timestamp:
 
 ```bash
 ai-toolkit status
-# Installed modules (from ~/.ai-toolkit/state.json):
+# Installed modules (from ~/.softspark/ai-toolkit/state.json):
 #   core            v1.3.0   installed 2026-04-07T10:00:00Z
 #   agents          v1.3.0   installed 2026-04-07T10:00:00Z
 #   skills          v1.3.0   installed 2026-04-07T10:00:00Z
@@ -121,7 +121,7 @@ Re-applies installed modules, skipping files whose content hash has not changed
 
 ## State Tracking
 
-Installed module state is persisted to `~/.ai-toolkit/state.json`:
+Installed module state is persisted to `~/.softspark/ai-toolkit/state.json`:
 
 ```json
 {
@@ -145,7 +145,7 @@ Installed module state is persisted to `~/.ai-toolkit/state.json`:
 |------|---------|
 | `manifest.json` | Module and profile definitions |
 | `scripts/install_steps/detect_language.py` | Auto-detect project language from marker files |
-| `scripts/install_steps/install_state.py` | Read/write `~/.ai-toolkit/state.json` |
+| `scripts/install_steps/install_state.py` | Read/write `~/.softspark/ai-toolkit/state.json` |
 
 ## Backward Compatibility
 

package/kb/reference/plugin-pack-conventions.md

@@ -87,11 +87,11 @@ ai-toolkit plugin status             # show installed packs with data stats
 ### What `plugin install` Does
 
 1. **Verifies** referenced agents/skills exist in `~/.claude/` (links them from core if missing)
-2. **Copies** plugin-specific hooks to `~/.ai-toolkit/hooks/plugin-<pack>-<hook>.sh`
-3. **Copies** plugin-specific scripts to `~/.ai-toolkit/plugin-scripts/<pack>/`
+2. **Copies** plugin-specific hooks to `~/.softspark/ai-toolkit/hooks/plugin-<pack>-<hook>.sh`
+3. **Copies** plugin-specific scripts to `~/.softspark/ai-toolkit/plugin-scripts/<pack>/`
 4. **Runs** init scripts if present (e.g. `init_db.py` for memory-pack — safe to re-run, preserves data)
 5. **Merges** plugin hooks into `~/.claude/settings.json` (tagged with `_source: ai-toolkit-plugin-<name>`)
-6. **Records** installed state to `~/.ai-toolkit/plugins.json`
+6. **Records** installed state to `~/.softspark/ai-toolkit/plugins.json`
 
 ### What `plugin update` Does
 
@@ -108,8 +108,8 @@ ai-toolkit plugin status             # show installed packs with data stats
 
 ### What `plugin remove` Does
 
-1. **Removes** plugin hooks from `~/.ai-toolkit/hooks/`
-2. **Removes** plugin scripts from `~/.ai-toolkit/plugin-scripts/`
+1. **Removes** plugin hooks from `~/.softspark/ai-toolkit/hooks/`
+2. **Removes** plugin scripts from `~/.softspark/ai-toolkit/plugin-scripts/`
 3. **Strips** plugin hook entries from `settings.json` (by `_source` tag)
 4. **Updates** `plugins.json` state
 5. **Leaves** core agents/skills untouched (they belong to the base install)

package/kb/reference/stats.md

@@ -13,7 +13,7 @@ description: "Local usage tracking for skill invocations. CLI command, JSON form
 
 ## Overview
 
-`ai-toolkit stats` tracks how often each skill is invoked via slash commands. All data is local — stored in `~/.ai-toolkit/stats.json`. No telemetry, no network calls.
+`ai-toolkit stats` tracks how often each skill is invoked via slash commands. All data is local — stored in `~/.softspark/ai-toolkit/stats.json`. No telemetry, no network calls.
 
 ## CLI Commands
 
@@ -29,7 +29,7 @@ A `UserPromptSubmit` hook (`track-usage.sh`) fires on every prompt. When the pro
 
 ### Hook Details
 - **Event**: `UserPromptSubmit`
-- **Script**: `~/.ai-toolkit/hooks/track-usage.sh`
+- **Script**: `~/.softspark/ai-toolkit/hooks/track-usage.sh`
 - **Detection**: `grep -oE '^/[a-z][a-z0-9-]*'`
 - **Storage**: Atomic write via python3 `os.replace()`
 - **Overhead**: ~50ms (python3 startup + JSON read/write)
@@ -64,6 +64,6 @@ debug                               8  2026-03-27 16:45:00
 Total invocations: 65
 Unique skills: 3
 
-File: ~/.ai-toolkit/stats.json
+File: ~/.softspark/ai-toolkit/stats.json
 Reset: ai-toolkit stats --reset
 ```

package/kb/reference/sync.md

@@ -28,8 +28,8 @@ ai-toolkit sync --import <file|url>   # Import from file or URL
 
 | Data | Included | Source |
 |------|----------|--------|
-| Custom rules | Yes | `~/.ai-toolkit/rules/*.md` |
-| Usage stats | Yes | `~/.ai-toolkit/stats.json` |
+| Custom rules | Yes | `~/.softspark/ai-toolkit/rules/*.md` |
+| Usage stats | Yes | `~/.softspark/ai-toolkit/stats.json` |
 | Toolkit version | Yes (metadata) | `package.json` |
 | Agents/skills | No | Installed via `npm` |
 | Hooks | No | Installed via `ai-toolkit install` |
@@ -39,7 +39,7 @@ ai-toolkit sync --import <file|url>   # Import from file or URL
 ### First machine (export)
 ```bash
 ai-toolkit sync --push
-# Creates secret Gist, saves ID to ~/.ai-toolkit/.gist-id
+# Creates secret Gist, saves ID to ~/.softspark/ai-toolkit/.gist-id
 ```
 
 ### Second machine (import)