@softspark/ai-toolkit 1.8.0 → 2.0.0

package/llms-full.txt

@@ -17,7 +17,6 @@
 - [Plan: Offline-First SLM Profile — Lightweight Mode for Local Models](kb/history/completed/offline-slm-profile-plan-20260411.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
-- [Plan: Local Dashboard — `ai-toolkit ui`](kb/planning/local-dashboard-plan.md)
 - [SOP: Claude Toolkit Maintenance](kb/procedures/maintenance-sop.md)
 - [SOP: Release Preparation](kb/procedures/release-preparation-sop.md)
 - [SOP: Release Verification](kb/procedures/release-verification-sop.md)
@@ -313,10 +312,10 @@ Create a configuration inheritance system where projects can extend a shared bas
 | FR3 | Constitution immutability — Articles I-V cannot be modified | Must | 100% block rate on modification attempts |
 | FR4 | Override validation with `override: true` + `justification` | Must | Missing justification → error |
 | FR5 | `enforce` block constraints (minHookProfile, requiredPlugins, forbidOverride, requiredAgents) | Must | All 4 constraint types enforced |
-| FR6 | Install/update integration — resolve extends during install | Must | `install --local` detects `.ai-toolkit.json` |
+| FR6 | Install/update integration — resolve extends during install | Must | `install --local` detects `.softspark-toolkit.json` |
 | FR7 | `config diff` command — show project vs base differences | Must | All merge layers visible |
 | FR8 | `config validate` command — schema + enforcement validation | Must | Exit 0/1 for pass/fail |
-| FR9 | `config init` — interactive project config setup | Should | Guided flow produces valid `.ai-toolkit.json` |
+| FR9 | `config init` — interactive project config setup | Should | Guided flow produces valid `.softspark-toolkit.json` |
 | FR10 | `config create-base` — scaffold npm base config package | Should | Ready-to-publish package with `package.json` |
 | FR11 | Lock file for reproducible installs | Should | Identical resolved config across team members |
 | FR12 | Audit trail in `state.json` | Should | Resolved version + overrides recorded |
@@ -344,7 +343,7 @@ Project Level (per-repository):
 ══════════════════════════════
 
   my-service/
-  ├── .ai-toolkit.json             ← project config with "extends"
+  ├── .softspark-toolkit.json             ← project config with "extends"
   ├── .claude/
   │   ├── CLAUDE.md                ← generated (base + project merged)
   │   └── settings.json            ← generated (base hooks + project hooks merged)
@@ -359,7 +358,7 @@ Merge Pipeline:
   ai-toolkit defaults (manifest.json) ← Layer 1: toolkit defaults
           │
           ▼
-  .ai-toolkit.json                  ← Layer 2: project overrides
+  .softspark-toolkit.json                  ← Layer 2: project overrides
           │
           ▼
   Resolved Configuration             ← Final: CLAUDE.md, settings.json, etc.
@@ -370,7 +369,7 @@ Merge Pipeline:
 ```
 1. Load base config from "extends" (npm package, git URL, or local path)
 2. Merge with ai-toolkit defaults (manifest.json profiles)
-3. Apply project-level overrides from .ai-toolkit.json
+3. Apply project-level overrides from .softspark-toolkit.json
 4. Validate merged config (constitution immutability, schema validation)
 5. Generate output files (CLAUDE.md, settings.json, agent symlinks, etc.)
 ```
@@ -381,7 +380,7 @@ Merge Pipeline:
 
 | # | Feature | Priority | Status | Est. Time | Notes |
 |---|---------|----------|--------|-----------|-------|
-| 1.1 | `.ai-toolkit.json` schema definition | P0 | **Done** | 1d | `scripts/schemas/ai-toolkit-config.schema.json` |
+| 1.1 | `.softspark-toolkit.json` schema definition | P0 | **Done** | 1d | `scripts/schemas/ai-toolkit-config.schema.json` |
 | 1.2 | Config resolver (npm, git, local path) | P0 | **Done** | 3d | `scripts/config_resolver.py` (~330 LOC) |
 | 1.3 | Merge engine (layered merge with override semantics) | P0 | **Done** | 3d | `scripts/config_merger.py` (~340 LOC) |
 | 1.4 | Constitution immutability guard | P0 | **Done** | 1d | In config_merger.py `_merge_constitution()` |
@@ -390,8 +389,8 @@ Merge Pipeline:
 | 2.3 | `ai-toolkit config validate` command | P0 | **Done** | 1d | `scripts/config_cli.py` `cmd_validate()` |
 | 2.4 | `ai-toolkit config init` command | P1 | **Done** | 1.5d | Interactive + flag-driven, validates extends |
 | 2.5 | `ai-toolkit config create-base` command | P1 | **Done** | 2d | `scripts/config_scaffold.py` — full npm package scaffold |
-| 3.1 | Audit trail in state.json | P1 | **Done** | 1d | `install_state.py` extends field + `.ai-toolkit-extends.json` |
-| 3.2 | Lock file (`.ai-toolkit.lock.json`) | P1 | **Done** | 1.5d | `scripts/config_lock.py` — generate/consume/staleness check |
+| 3.1 | Audit trail in state.json | P1 | **Done** | 1d | `install_state.py` extends field + `.softspark-toolkit-extends.json` |
+| 3.2 | Lock file (`.softspark-toolkit.lock.json`) | P1 | **Done** | 1.5d | `scripts/config_lock.py` — generate/consume/staleness check |
 | 3.3 | Base config scaffolder (npm package template) | P1 | **Done** | 1.5d | Part of `config_scaffold.py` `create_base_package()` |
 | 3.4 | CI enforcement (`ai-toolkit config check`) | P2 | **Done** | 1d | `config_cli.py` `cmd_check()` — JSON output, exit codes |
 | 4.1 | Tests | P1 | **Done** | 3d | 39 tests: resolver (7), merger (13), CLI (10), install integration (9) |
@@ -449,7 +448,7 @@ Audit trail (3.1) ──┐
 
 ### Phase 1: Core Engine (week 1-2)
 
-#### 1.1 Configuration Schema (`.ai-toolkit.json`)
+#### 1.1 Configuration Schema (`.softspark-toolkit.json`)
 
 > **v1 scope:** The full schema below shows the target state. v1 implements only: `extends`, `profile`, `agents`, `rules`, `constitution`, and `enforce`. See section 6a for the v1/v2 field breakdown.
 
@@ -591,9 +590,9 @@ Audit trail (3.1) ──┐
 | Local path | `"extends": "../shared-config"` | Resolve relative to project root |
 | ~~Multiple bases~~ | ~~`"extends": ["@mycompany/base", "@mycompany/typescript-extra"]`~~ | Deferred to v2 — multi-base merge ordering is a complexity trap |
 
-**Cache directory:** `~/.ai-toolkit/config-cache/`
+**Cache directory:** `~/.softspark/ai-toolkit/config-cache/`
 ```
-~/.ai-toolkit/config-cache/
+~/.softspark/ai-toolkit/config-cache/
   @mycompany/
     ai-toolkit-config/
       2.1.0/
@@ -651,7 +650,7 @@ def resolve_extends(extends_value: str, project_root: str,
 **Max recursion depth:** 5 levels (prevent circular extends). Circular detection via visited set.
 
 **Offline handling:** If the npm/git source is unavailable:
-1. Check cache (`~/.ai-toolkit/config-cache/`)
+1. Check cache (`~/.softspark/ai-toolkit/config-cache/`)
 2. If cached version found → use with warning: "Using cached config v2.1.0 (offline)"
 3. If not cached → error with instructions: "Run `ai-toolkit config update` when online"
 
@@ -792,7 +791,7 @@ def merge_constitution(base: dict, project: dict) -> dict:
 
 ```python
 # During install --local:
-# 1. Check for .ai-toolkit.json in project root
+# 1. Check for .softspark-toolkit.json in project root
 # 2. If found and has "extends":
 #    a. Resolve base config(s)
 #    b. Merge base → project
@@ -803,7 +802,7 @@ def merge_constitution(base: dict, project: dict) -> dict:
 
 **CLI flags:**
 ```bash
-ai-toolkit install --local                           # auto-detect .ai-toolkit.json
+ai-toolkit install --local                           # auto-detect .softspark-toolkit.json
 ai-toolkit install --local --config ./custom.json    # explicit config file
 ai-toolkit update --local                            # re-resolve extends + update
 ai-toolkit update --local --refresh-base             # force re-fetch base config
@@ -851,7 +850,7 @@ ai-toolkit config diff
 ai-toolkit config validate
 
 # Checks:
-# ✓ .ai-toolkit.json schema valid
+# ✓ .softspark-toolkit.json schema valid
 # ✓ extends: @mycompany/ai-toolkit-config@2.1.0 resolved
 # ✓ No forbidden overrides
 # ✓ Required plugins installed: security-pack
@@ -876,12 +875,12 @@ ai-toolkit config init
 # Flow:
 # 1. "Does your organization have a shared ai-toolkit config? [y/n]"
 #    → y: "npm package name or git URL:" → resolves + validates
-#    → n: creates minimal .ai-toolkit.json without extends
+#    → n: creates minimal .softspark-toolkit.json without extends
 # 2. "Which profile? [minimal/standard/strict]" → default from base or standard
 # 3. "Which persona? [none/backend-lead/frontend-lead/devops-eng/junior-dev]"
 # 4. Auto-detect languages from project
 # 5. Auto-detect editors from project files
-# 6. Write .ai-toolkit.json
+# 6. Write .softspark-toolkit.json
 # 7. Run ai-toolkit install --local
 ```
 
@@ -945,7 +944,7 @@ ai-toolkit config create-base @mycompany/ai-toolkit-config
 
 ---
 
-#### 3.2 Lock File (`.ai-toolkit.lock.json`)
+#### 3.2 Lock File (`.softspark-toolkit.lock.json`)
 
 **Purpose:** Pin the exact resolved version of base configs for reproducible installs across team members and CI.
 
@@ -957,7 +956,7 @@ ai-toolkit config create-base @mycompany/ai-toolkit-config
       "version": "2.1.0",
       "resolved": "https://registry.npmjs.org/@mycompany/ai-toolkit-config/-/ai-toolkit-config-2.1.0.tgz",
       "integrity": "sha512-abc123...",
-      "cached": "~/.ai-toolkit/config-cache/@mycompany/ai-toolkit-config/2.1.0/"
+      "cached": "~/.softspark/ai-toolkit/config-cache/@mycompany/ai-toolkit-config/2.1.0/"
     }
   },
   "generated_at": "2026-04-10T10:30:00Z",
@@ -969,7 +968,7 @@ ai-toolkit config create-base @mycompany/ai-toolkit-config
 - `ai-toolkit install --local` → uses lock file if present (like `npm ci`)
 - `ai-toolkit update --local` → re-resolves and updates lock file (like `npm install`)
 - `ai-toolkit update --local --refresh-base` → force re-fetch ignoring cache
-- `.ai-toolkit.lock.json` should be committed to git (team synchronization)
+- `.softspark-toolkit.lock.json` should be committed to git (team synchronization)
 
 ---
 
@@ -983,7 +982,7 @@ ai-toolkit config check
 # Exit codes:
 # 0 — project complies with base config
 # 1 — violations found (missing required plugins, forbidden overrides, etc.)
-# 2 — .ai-toolkit.json not found
+# 2 — .softspark-toolkit.json not found
 ```
 
 **GitHub Actions example:**
@@ -1056,7 +1055,7 @@ v1 ships with a minimal schema. Each additional field adds merge logic, validati
 | **Offline** | Cached configs used when registry unavailable, with clear warning. |
 | **Security** | No secret exposure in config files or audit trail. npm auth via `.npmrc` (user-managed). `execFile` for npm CLI (no shell injection). |
 | **Error messages** | Every validation error includes: what failed, which config layer caused it, and what to do (e.g., "Contact your team lead to request an exemption"). |
-| **Backward compatibility** | 100% — projects without `.ai-toolkit.json` work exactly as today. Zero behavioral changes for existing users. |
+| **Backward compatibility** | 100% — projects without `.softspark-toolkit.json` work exactly as today. Zero behavioral changes for existing users. |
 | **Maintainability** | Each new schema field requires: merge logic, validation, diff output, test. Budget 0.5d per new field. |
 | **Quality gates** | `ruff check scripts/config_*.py` (0 errors), `mypy --strict scripts/config_*.py` (0 errors). Run before every commit. |
 | **Type safety** | 100% public API type hints (all function signatures). >60% internal. Use `TypedDict` for config schemas, `dataclass` for resolved configs. |
@@ -1073,7 +1072,7 @@ v1 ships with a minimal schema. Each additional field adds merge logic, validati
 | Constitution protection | 100% (Articles I-V immutable) |
 | Override justification | Required for all overrides |
 | Enforce constraints | 4 types (minHookProfile, requiredPlugins, forbidOverride, requiredAgents) |
-| Backward compatibility | 100% (projects without .ai-toolkit.json work as today) |
+| Backward compatibility | 100% (projects without .softspark-toolkit.json work as today) |
 | CI enforcement | Exit code 0/1 for governance compliance |
 | Lock file | Reproducible installs across team members |
 | Scaffold command | Ready-to-publish npm package template |
@@ -1099,7 +1098,7 @@ v1 ships with a minimal schema. Each additional field adds merge logic, validati
 
 ## 9. Pre-Mortem
 
-1. **"Config file fatigue"** — developers already have `.eslintrc`, `tsconfig.json`, `.prettierrc`. Another `.ai-toolkit.json` may feel like bloat. Mitigation: file is optional, all features work without it. The DX gain (organizational governance without per-repo updates) justifies the file.
+1. **"Config file fatigue"** — developers already have `.eslintrc`, `tsconfig.json`, `.prettierrc`. Another `.softspark-toolkit.json` may feel like bloat. Mitigation: file is optional, all features work without it. The DX gain (organizational governance without per-repo updates) justifies the file.
 2. **"Base config never gets updated"** — team lead creates base config, nobody maintains it. Mitigation: `ai-toolkit config check` in CI catches drift; lock file staleness warnings.
 3. **"Override justification is annoying"** — developers will write "needed" as justification. Mitigation: CI check can enforce minimum justification length (>20 chars); code review culture catches low-effort justifications.
 4. **"Merge semantics are confusing"** — "does project override or extend the base agent list?" Mitigation: explicit semantics documented in schema; `ai-toolkit config diff` shows exactly what happened.
@@ -1125,7 +1124,7 @@ v1 ships with a minimal schema. Each additional field adds merge logic, validati
 
 **MVP (ship first, ~3.5 weeks):**
 1. [x] Approve plan
-2. [x] Define `.ai-toolkit.json` JSON Schema — v1 scope only (1.1)
+2. [x] Define `.softspark-toolkit.json` JSON Schema — v1 scope only (1.1)
 3. [x] Implement config resolver (npm, git, local) with caching (1.2)
 4. [x] Implement merge engine with override validation (1.3)
 5. [x] Implement constitution immutability guard (1.4)
@@ -1162,17 +1161,15 @@ v1 ships with a minimal schema. Each additional field adds merge logic, validati
 
 ## 13. Cross-Plan Dependencies
 
-This plan shares modification targets with two other proposed plans:
+This plan shares modification targets with the Offline SLM plan:
 
-| Shared File | This Plan | Local Dashboard Plan | Offline SLM Plan |
-|-------------|-----------|---------------------|-----------------|
-| `scripts/install.py` | +80 LOC (extends resolution) | — | +30 LOC (offline-slm profile) |
-| `manifest.json` | +10 LOC (schema refs) | — | +5 LOC (offline-slm profile) |
-| `bin/ai-toolkit.js` | +40 LOC (config subcommands) | +15 LOC (ui command) | +10 LOC (compile-slm command) |
+| Shared File | This Plan | Offline SLM Plan |
+|-------------|-----------|-----------------|
+| `scripts/install.py` | +80 LOC (extends resolution) | +30 LOC (offline-slm profile) |
+| `manifest.json` | +10 LOC (schema refs) | +5 LOC (offline-slm profile) |
+| `bin/ai-toolkit.js` | +40 LOC (config subcommands) | +10 LOC (compile-slm command) |
 
-**If implementing in parallel:** coordinate merge order for shared files. Recommended sequence: Offline SLM (smallest changes) → Enterprise Config → Dashboard (no install.py changes).
-
-**Dashboard integration note:** If this plan ships before the Dashboard plan, the Dashboard's Config page (2.6) should display `.ai-toolkit.json` / `extends` status and the `config diff` output.
+**If implementing in parallel:** coordinate merge order for shared files. Recommended sequence: Offline SLM (smallest changes) → Enterprise Config.
 
 ---
 
@@ -1272,8 +1269,8 @@ ai-toolkit compile-slm [--budget 4096] [--persona backend-lead] [--lang typescri
   │    extended (16K) — near-full toolkit (for 32B+ models)   │
   │                                                          │
   │  Output Files:                                           │
-  │    ~/.ai-toolkit/compiled/slm-system-prompt.md           │
-  │    ~/.ai-toolkit/compiled/slm-skills-reference.md        │
+  │    ~/.softspark/ai-toolkit/compiled/slm-system-prompt.md           │
+  │    ~/.softspark/ai-toolkit/compiled/slm-skills-reference.md        │
   │    CLAUDE.md (or equivalent) — auto-generated            │
   │                                                          │
   │  Integration Targets:                                    │
@@ -1613,7 +1610,7 @@ ai-toolkit install --profile offline-slm
 # What happens:
 # 1. Standard install of core components
 # 2. Runs compile_slm.py with auto-detected settings
-# 3. Writes compiled output to ~/.ai-toolkit/compiled/
+# 3. Writes compiled output to ~/.softspark/ai-toolkit/compiled/
 # 4. Generates integration instructions for detected local model tools
 # 5. state.json records profile as "offline-slm"
 ```
@@ -1716,7 +1713,7 @@ ollama run my-coder "implement the payment API"
 ```
 1. ai-toolkit compile-slm --model-size 14b
 2. Open LM Studio → Chat → System Prompt
-3. Paste contents of ~/.ai-toolkit/compiled/slm-system-prompt.md
+3. Paste contents of ~/.softspark/ai-toolkit/compiled/slm-system-prompt.md
 ```
 
 **Aider:**
@@ -1787,7 +1784,7 @@ Post-compilation checks:
 
 ## 6b. Cache Invalidation & Recompile Triggers
 
-Compiled output (`~/.ai-toolkit/compiled/slm-system-prompt.md`) is a **derived artifact** — it must be recompiled when inputs change:
+Compiled output (`~/.softspark/ai-toolkit/compiled/slm-system-prompt.md`) is a **derived artifact** — it must be recompiled when inputs change:
 
 | Trigger | Action |
 |---------|--------|
@@ -1806,7 +1803,7 @@ The offline-slm feature is purely additive — removing it is trivial:
 1. Delete `scripts/compile_slm.py`, `scripts/slm_token_counter.py`, `scripts/slm_compression.py`, `scripts/slm_integration.py`
 2. Remove `"offline-slm"` and `"offline-slm-extended"` from `manifest.json` profiles
 3. Remove `compile-slm` from `SCRIPT_COMMANDS` in `bin/ai-toolkit.js`
-4. Delete `~/.ai-toolkit/compiled/` directory (user-side)
+4. Delete `~/.softspark/ai-toolkit/compiled/` directory (user-side)
 5. No hooks, no state files, no config entries to clean up
 
 ---
@@ -1911,13 +1908,13 @@ For teams needing enforcement, recommend `--profile offline-slm` combined with a
 
 ## 13. Cross-Plan Dependencies
 
-This plan shares modification targets with two other proposed plans:
+This plan shares modification targets with the Enterprise Config plan:
 
-| Shared File | This Plan | Enterprise Config Plan | Local Dashboard Plan |
-|-------------|-----------|----------------------|---------------------|
-| `scripts/install.py` | +30 LOC (offline-slm profile) | +80 LOC (extends resolution) | — |
-| `manifest.json` | +5 LOC (offline-slm profile) | +10 LOC (schema refs) | — |
-| `bin/ai-toolkit.js` | +10 LOC (compile-slm command) | +40 LOC (config subcommands) | +15 LOC (ui command) |
+| Shared File | This Plan | Enterprise Config Plan |
+|-------------|-----------|----------------------|
+| `scripts/install.py` | +30 LOC (offline-slm profile) | +80 LOC (extends resolution) |
+| `manifest.json` | +5 LOC (offline-slm profile) | +10 LOC (schema refs) |
+| `bin/ai-toolkit.js` | +10 LOC (compile-slm command) | +40 LOC (config subcommands) |
 
 **If implementing in parallel:** this plan has the smallest changes to shared files — merge first to minimize conflicts.
 
@@ -1988,7 +1985,7 @@ Create `cloud-security-pack` plugin pack that provides deterministic, read-only
 - **Deterministic** — reproducible results, no LLM-driven regex (same pattern as `hipaa_scan.py`)
 - **False positive aware** — context graph resolves "public endpoint behind gateway/App Check/WAF"
 - **CI-ready** — `--output json` + `--output sarif` (SARIF v2.1.0 for GitHub Advanced Security), exit code 1 on HIGH, 0 otherwise
-- **Credential isolation** — keys stored in `~/.ai-toolkit/credentials/`, accessible only by this pack's scripts
+- **Credential isolation** — keys stored in `~/.softspark/ai-toolkit/credentials/`, accessible only by this pack's scripts
 - **Static-first** — static mode (no credentials) is the default, live mode is opt-in upgrade
 - **Incremental** — `--changed` flag scans only files modified since last commit (PR workflow)
 - **IaC via `terraform show -json`** — wraps Terraform's own JSON output instead of parsing HCL directly
@@ -2149,7 +2146,7 @@ ai-toolkit credentials test aws
 
 **Storage structure:**
 ```
-~/.ai-toolkit/
+~/.softspark/ai-toolkit/
   credentials/
     gcp.json              # SA key file (copied, chmod 0600)
     gcp.meta.json         # { project_id, added_at, method: "file"|"gcloud" }
@@ -2174,7 +2171,7 @@ ai-toolkit credentials test aws
   - Connection works (GCP: `gcloud auth list`, AWS: `aws sts get-caller-identity`, Azure: `az account show`)
   - SA/role has **only read permissions** — **REFUSE to store** if write access detected (orchestration-review: warn-only is ignored by users). Override: `--force` flag with explicit acknowledgment
   - Project/subscription exists
-- `.gitignore`-proof — lives in `~/.ai-toolkit/`, never in project directory
+- `.gitignore`-proof — lives in `~/.softspark/ai-toolkit/`, never in project directory
 - Scripts access credentials via `gcp_auth.py` helper — single entry point, no direct file reads
 
 **Files to create/modify:**
@@ -3116,784 +3113,6 @@ Examples:
 
 ---
 
-## kb/planning/local-dashboard-plan.md
-
----
-title: "Plan: Local Dashboard — ai-toolkit ui"
-category: planning
-service: ai-toolkit
-tags:
-  - dashboard
-  - developer-experience
-  - web-ui
-  - tui
-  - configuration
-  - visualization
-doc_type: plan
-status: proposed
-created: "2026-04-10"
-last_updated: "2026-04-10"
-completion: "0%"
-description: "Ephemeral local web dashboard for ai-toolkit. Provides visual management of agents, skills, hooks, plugins, stats, credentials, and configuration profiles. Zero external dependencies — stdlib Node.js server with embedded HTML/CSS/JS. Launched via `ai-toolkit ui`."
----
-
-# Plan: Local Dashboard — `ai-toolkit ui`
-
-**Status:** Proposed
-**Completion:** 0%
-**Created:** 2026-04-10
-**Origin:** DX friction — managing 44 agents, 91 skills, 21 hooks, 11 plugin packs, and multiple profiles via CLI only creates a steep learning curve for new adopters. Visual management lowers the adoption barrier.
-**Estimated Effort:** 6-7 weeks (1 person)
-
----
-
-## 1. Objective
-
-Create an `ai-toolkit ui` command that launches an ephemeral local HTTP server serving a single-page web dashboard. The dashboard provides visual management of all toolkit components — no more memorizing CLI flags.
-
-**Key design principles:**
-- **Zero external dependencies** — stdlib Node.js `http` module, embedded HTML/CSS/JS (same approach as `visual-server.cjs` in `/write-a-prd`). Server lives in `app/dashboard/` (not `scripts/`) — aligns with `visual-server.cjs` precedent and the "scripts/ = Python stdlib only" convention
-- **Ephemeral** — auto-kills after 30 minutes of inactivity (matching existing companion pattern)
-- **Read-write** — reads state from `~/.ai-toolkit/state.json`, `~/.claude/settings.json`, `manifest.json`; writes config changes through existing CLI commands (never mutates files directly)
-- **Dark theme** — premium aesthetic, responsive, glassmorphism accents
-- **Offline** — no CDN dependencies, no external fonts, no analytics
-- **Port discovery** — starts on 3141, auto-increments if busy
-
----
-
-## 1a. Functional Requirements
-
-| ID | Requirement | Priority | Success Metric |
-|----|-------------|----------|----------------|
-| FR1 | HTTP server with auto-kill + port discovery | Must | Starts, auto-kills after 30 min, increments port if busy |
-| FR2 | Read API endpoints (status, agents, skills, hooks, plugins, stats, config, mcp) | Must | All 8 endpoints return valid JSON |
-| FR3 | Action execution via `POST /api/action` with SSE streaming | Must | Command output streamed, exit code returned |
-| FR4 | Overview page with health checks + component counts | Must | Live data, matches `ai-toolkit validate` output |
-| FR5 | Agents page with grid view + category filter | Must | All 44 agents parsed, 10 categories filterable |
-| FR6 | Skills page with type/effort filter + sortable table | Must | All 91 skills, 3 type badges |
-| FR7 | Hooks page with lifecycle diagram + profile toggle | Should | 21 hooks, 3 profiles toggleable |
-| FR8 | Plugins page with install/remove action buttons | Should | Action triggers CLI via POST /api/action |
-| FR9 | Config page with profile/persona management | Should | Reads + writes profiles via CLI |
-| FR10 | Stats page with inline SVG charts | Should | Bar chart + trend line minimum (v1) |
-| FR11 | MCP template browser with add/remove | Could | 25 templates browseable |
-| FR12 | Dark theme + glassmorphism CSS design system | Must | Zero external CSS/font deps |
-| FR13 | Client-side SPA routing (hash-based) | Must | Navigation without page reload |
-| FR14 | Responsive design (desktop, tablet, mobile) | Should | 3 breakpoints, usable on mobile |
-| FR15 | Command allowlist enforcement on /api/action | Must | Non-allowlisted commands → 403 |
-
----
-
-## 2. Architecture Overview
-
-```
-ai-toolkit ui [--port 3141] [--no-auto-kill]
-
-  ┌──────────────────────────────────────────────────────────┐
-  │                   Local Dashboard                         │
-  │                                                          │
-  │  Server: stdlib Node.js http (0 deps)                    │
-  │  Port: 3141 (auto-increment if busy)                    │
-  │  Auto-kill: 30 min idle (configurable)                   │
-  │                                                          │
-  │  Pages:                                                  │
-  │    /                        Overview + health             │
-  │    /agents                  44 agents — grid view         │
-  │    /skills                  91 skills — filterable table  │
-  │    /hooks                   21 hooks — lifecycle diagram  │
-  │    /plugins                 11 packs — install/remove     │
-  │    /config                  Profile / persona / modules   │
-  │    /stats                   Usage analytics + charts      │
-  │    /mcp                     MCP templates — add/remove    │
-  │    (credentials page deferred — requires cloud-security-pack CLI) │
-  │                                                          │
-  │  API (JSON, internal):                                   │
-  │    GET  /api/status         Toolkit state                 │
-  │    GET  /api/agents         Agent catalog                 │
-  │    GET  /api/skills         Skill catalog                 │
-  │    GET  /api/hooks          Hook definitions              │
-  │    GET  /api/plugins        Plugin packs + install state  │
-  │    GET  /api/stats          Usage statistics              │
-  │    GET  /api/config         Current configuration         │
-  │    GET  /api/mcp            MCP templates + installed     │
-  │    (credentials endpoint deferred — see Future section)   │
-  │    POST /api/action         Execute CLI command           │
-  │                                                          │
-  │  Static assets (inlined in server.js):                   │
-  │    HTML template (single page, client-side routing)      │
-  │    CSS  (dark theme, glassmorphism, responsive)          │
-  │    JS   (vanilla, fetch-based, no framework)             │
-  └──────────────────────────────────────────────────────────┘
-```
-
-### Action Execution Model
-
-All write operations go through `POST /api/action`:
-
-```json
-{
-  "command": "plugin",
-  "args": ["install", "memory-pack"]
-}
-```
-
-The server spawns `ai-toolkit <command> <args>` as a child process, streams stdout/stderr back via SSE (Server-Sent Events), and returns exit code. This ensures:
-1. All existing validation logic in CLI scripts executes
-2. No file mutation logic duplicated in the dashboard
-3. Audit trail identical to CLI usage
-
----
-
-## 3. Progress Tracking
-
-| # | Feature | Priority | Status | Est. Time | Notes |
-|---|---------|----------|--------|-----------|-------|
-| 1.1 | HTTP server + auto-kill + port discovery | P0 | Proposed | 1d | stdlib Node.js, ephemeral lifecycle |
-| 1.2 | API layer — read endpoints (status, agents, skills, hooks, plugins, stats, config, mcp) | P0 | Proposed | 2d | Parse frontmatter, state.json, hooks.json |
-| 1.3 | API layer — action execution endpoint | P0 | Proposed | 1d | Spawn CLI + SSE streaming |
-| 2.1 | Overview page (health, component counts, version) | P0 | Proposed | 1.5d | Dashboard landing page |
-| 2.2 | Agents page (grid + detail view + category filter) | P0 | Proposed | 2d | Parse agent .md frontmatter |
-| 2.3 | Skills page (filterable table + type badges + effort) | P0 | Proposed | 2d | Task / hybrid / knowledge taxonomy |
-| 2.4 | Hooks page (lifecycle diagram + profile toggle) | P1 | Proposed | 2d | Visual event → script mapping |
-| 2.5 | Plugins page (install/remove/status cards) | P1 | Proposed | 2d | Action buttons trigger CLI |
-| 2.6 | Config page (profile/persona/modules checkboxes) | P1 | Proposed | 2d | Read/write profiles |
-| 2.7 | Stats page (usage charts, skill invocation heatmap) | P1 | Proposed | 3.5d | Hand-drawn SVG charts (bar, heatmap, trend), no chart library |
-| 2.8 | MCP page (template browser, add/remove) | P2 | Proposed | 1.5d | 25 MCP templates |
-| 2.9 | ~~Credentials page~~ | — | Deferred | — | Requires cloud-security-pack CLI commands (not yet implemented) |
-| 3.1 | CSS design system (dark theme, glassmorphism, responsive) | P0 | Proposed | 2d | Premium aesthetic, zero external deps |
-| 3.2 | Client-side routing + navigation | P0 | Proposed | 1d | Hash-based SPA routing |
-| 4.1 | CLI command registration (`ai-toolkit ui`) | P0 | Proposed | 0.5d | bin/ai-toolkit.js integration |
-| 4.2 | Tests (bats + node:test) | P1 | Proposed | 3d | Server lifecycle (bats) + API endpoints + SSE streaming (node:test) |
-| 4.3 | Documentation | P1 | Proposed | 2.5d | README, CLAUDE.md, ARCHITECTURE.md, package.json, llms.txt, llms-full.txt, AGENTS.md, skills-catalog.md, architecture-overview.md |
-
-**Phasing:**
-- **Phase 1 (week 1-3):** Foundation — server, API, design system, overview page, agents page, skills page
-- **Phase 2 (week 3-5):** Interactive — hooks, plugins, config, action execution, stats
-- **Phase 3 (week 6-7):** Polish — MCP, responsive testing, tests, documentation (2.5d docs — all 9 docs per CLAUDE.md rules)
-
-> **Demand validation gate:** Ship Phase 1 (server + overview + agents + skills) as MVP. Announce, measure adoption (track `ai-toolkit ui` invocations via `stats.json`). Only build Phase 2 interactive pages if usage > 10 sessions/week across early adopters.
-
----
-
-## 4. Dependency Graph
-
-```
-                     Phase 1: Foundation (week 1-3)
-                     ================================
-HTTP server (1.1) ──────┐
-                        ├──► API read layer (1.2) ──► Overview page (2.1)
-CSS design system (3.1) ┤                          ├──► Agents page (2.2)
-Client routing (3.2) ───┘                          └──► Skills page (2.3)
-
-                     Phase 2: Interactive (week 3-5)
-                     =================================
-API action layer (1.3) ─┐
-                        ├──► Hooks page (2.4)
-                        ├──► Plugins page (2.5)
-                        ├──► Config page (2.6)
-                        └──► Stats page (2.7)
-
-                     Phase 3: Polish (week 6-7)
-                     ===========================
-                        ├──► MCP page (2.8)
-                        ├──► CLI registration (4.1)
-                        └──► Tests + docs (4.2, 4.3)
-```
-
----
-
-## 5. Detailed Implementation
-
-### Phase 1: Foundation (week 1-3)
-
-#### 1.1 HTTP Server + Lifecycle
-
-**File:** `app/dashboard/server.js`
-
-```javascript
-// Key design decisions:
-// 1. stdlib only — require('http'), require('fs'), require('path')
-// 2. Auto-kill timer — 30 min idle, reset on every request
-// 3. Port discovery — try 3141, increment until available
-// 4. Single-file deployment — HTML/CSS/JS embedded as template literals
-// 5. Same pattern as visual-brainstorming companion in /write-a-prd
-
-const AUTO_KILL_MS = 30 * 60 * 1000; // 30 minutes
-const DEFAULT_PORT = 3141;
-const MAX_PORT_ATTEMPTS = 10;
-```
-
-**CLI interface:**
-```bash
-ai-toolkit ui                    # open dashboard on port 3141
-ai-toolkit ui --port 4000        # custom port
-ai-toolkit ui --no-auto-kill     # disable 30 min auto-kill
-ai-toolkit ui --open             # auto-open browser (default: true)
-```
-
-**Lifecycle:**
-1. Start HTTP server on available port
-2. Open browser via `open` (macOS) / `xdg-open` (Linux)
-3. Reset idle timer on every request
-4. After 30 min inactivity → `process.exit(0)` with console message
-5. `Ctrl+C` → graceful shutdown
-
-**Security:**
-- Bind to `127.0.0.1` only (never `0.0.0.0`)
-- No authentication needed (localhost only, ephemeral)
-- POST `/api/action` validates command against allowlist (same commands as CLI)
-- No file uploads, no eval, no template injection
-
-**Files:**
-
-| File | Action | Description |
-|------|--------|-------------|
-| `app/dashboard/server.js` | CREATE | HTTP server + API + embedded UI |
-| `app/dashboard/api.js` | CREATE | API endpoint handlers |
-| `app/dashboard/assets.js` | CREATE | Embedded HTML/CSS/JS templates |
-
-**Success Criteria:**
-- [ ] Server starts on port 3141 (or next available)
-- [ ] Auto-kills after 30 min idle
-- [ ] Browser auto-opens on launch
-- [ ] Binds to 127.0.0.1 only
-- [ ] `Ctrl+C` graceful shutdown
-
----
-
-#### 1.2 API Layer — Read Endpoints
-
-All endpoints return JSON. Data sources:
-
-| Endpoint | Source | Description |
-|----------|--------|-------------|
-| `GET /api/status` | `~/.ai-toolkit/state.json` + `manifest.json` | Version, profile, installed modules |
-| `GET /api/agents` | `app/agents/*.md` frontmatter | Name, description, tools, triggers, category |
-| `GET /api/skills` | `app/skills/*/SKILL.md` frontmatter | Name, type, effort, agent, description |
-| `GET /api/hooks` | `app/hooks.json` | Event, script, description, profile |
-| `GET /api/plugins` | `app/plugins/*/plugin.json` + state | Name, domain, status, installed?, components |
-| `GET /api/stats` | `~/.ai-toolkit/stats.json` | Skill invocation counts, dates |
-| `GET /api/config` | `~/.ai-toolkit/state.json` + settings | Profile, persona, modules, hook profile |
-| `GET /api/mcp` | `app/mcp-templates/*.json` + `.mcp.json` | Available templates, installed servers |
-| ~~`GET /api/credentials`~~ | — | Deferred — requires cloud-security-pack CLI |
-
-**Frontmatter parser:** Reuse the YAML-subset parser pattern from existing `scripts/frontmatter.py` — port to JS (simple `---` delimited key-value extraction, covers all toolkit frontmatter which is flat YAML).
-
-**Response format (example):**
-```json
-{
-  "agents": [
-    {
-      "name": "backend-specialist",
-      "description": "Expert backend architect for Node.js, Python, PHP...",
-      "tools": ["Read", "Write", "Edit", "Bash", "Grep", "Glob"],
-      "triggers": ["backend", "server", "api", "endpoint"],
-      "category": "development",
-      "file": "app/agents/backend-specialist.md"
-    }
-  ],
-  "meta": { "count": 44, "categories": 10 }
-}
-```
-
-**Success Criteria:**
-- [ ] All 8 read endpoints return valid JSON
-- [ ] Agent frontmatter parsed for all 44 agents
-- [ ] Skill frontmatter parsed for all 91 skills
-- [ ] Stats endpoint handles missing stats.json gracefully
-
----
-
-#### 1.3 API Layer — Action Execution
-
-**Endpoint:** `POST /api/action`
-
-```json
-// Request
-{
-  "command": "plugin",
-  "args": ["install", "memory-pack"]
-}
-
-// Response (SSE stream)
-event: stdout
-data: Installing memory-pack...
-
-event: stdout
-data: ✓ Hooks installed
-
-event: done
-data: {"exitCode": 0, "duration": 1234}
-```
-
-**Command allowlist:**
-```javascript
-const ALLOWED_COMMANDS = [
-  'plugin install', 'plugin remove', 'plugin update', 'plugin clean',
-  'mcp add', 'mcp remove',
-  'install --profile', 'install --persona',
-  'update', 'validate', 'doctor', 'doctor --fix',
-  'stats', 'stats --reset',
-  // 'credentials add/remove/test' — deferred until cloud-security-pack CLI ships
-];
-```
-
-**Security:** Commands not in allowlist → 403. No shell injection — args passed as array to `execFile`, never interpolated into a string.
-
-**Success Criteria:**
-- [ ] SSE streaming of command output
-- [ ] Exit code returned in final event
-- [ ] Command allowlist enforced
-- [ ] No shell injection possible
-- [ ] Concurrent commands rejected (one at a time)
-
----
-
-### Phase 2: UI Pages (week 3-5)
-
-#### 2.1 Overview Page
-
-The landing page — first thing the user sees.
-
-**Layout:**
-```
-┌─────────────────────────────────────────────────┐
-│  ai-toolkit v1.5.1              [● running]     │
-├─────────────────────────────────────────────────┤
-│                                                 │
-│  ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐       │
-│  │  44  │  │  91  │  │  21  │  │  11  │       │
-│  │agents│  │skills│  │hooks │  │packs │       │
-│  └──────┘  └──────┘  └──────┘  └──────┘       │
-│                                                 │
-│  Profile: standard    Persona: (none)           │
-│  Hook Profile: standard                         │
-│  Node: v22.x    Python: 3.12                    │
-│                                                 │
-│  ┌─ Health ──────────────────────────────────┐  │
-│  │ ✓ Constitution symlinked                  │  │
-│  │ ✓ Hooks installed (21/21)                 │  │
-│  │ ✓ Agents symlinked (44/44)                │  │
-│  │ ⚠ 2 plugins not installed                 │  │
-│  │ ✓ MCP servers: 3 configured               │  │
-│  └───────────────────────────────────────────┘  │
-│                                                 │
-│  ┌─ Recent Activity ─────────────────────────┐  │
-│  │ /review  — 12 invocations (last: 2h ago)  │  │
-│  │ /commit  — 8 invocations (last: 5h ago)   │  │
-│  │ /test    — 6 invocations (last: 1d ago)   │  │
-│  └───────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────┘
-```
-
-**Data sources:** `/api/status` + `/api/stats` + `/api/plugins`
-
-**Success Criteria:**
-- [ ] Component counts rendered from live data
-- [ ] Health checks match `ai-toolkit validate` output
-- [ ] Recent activity from stats.json
-- [ ] Responsive on mobile-width screens
-
----
-
-#### 2.2 Agents Page
-
-**Layout:** Grid of agent cards, filterable by category (10 categories).
-
-**Card design:**
-```
-┌─────────────────────────────────┐
-│ 🔧 backend-specialist          │
-│                                 │
-│ Expert backend architect for    │
-│ Node.js, Python, PHP...        │
-│                                 │
-│ Tools: Read, Write, Edit, Bash  │
-│ Triggers: backend, server, api  │
-│                                 │
-│ [View Definition]               │
-└─────────────────────────────────┘
-```
-
-**Features:**
-- Category filter pills (development, security, data, infrastructure, etc.)
-- Search by name/description/trigger
-- Click card → modal with full agent definition (rendered markdown)
-- Agent count per category in filter pills
-
----
-
-#### 2.3 Skills Page
-
-**Layout:** Filterable table with type badges.
-
-| Skill | Type | Effort | Agent | Description |
-|-------|------|--------|-------|-------------|
-| /commit | task | medium | — | Structured commit with linting |
-| /review | hybrid | high | code-reviewer | Code review: quality, security |
-| clean-code | knowledge | — | — | Auto-loaded code quality patterns |
-
-**Features:**
-- Filter by type (task / hybrid / knowledge)
-- Filter by effort (low / medium / high / max)
-- Search by name/description
-- Sort by any column
-- Badge colors: task=blue, hybrid=purple, knowledge=green
-
----
-
-#### 2.4 Hooks Page
-
-**Layout:** Lifecycle diagram with profile toggle (minimal/standard/strict).
-
-**Visualization:**
-```
-Event Timeline (horizontal flow):
-  PreToolUse ──► ToolUse ──► PostToolUse ──► Notification
-       │              │             │              │
-  guard-path.sh   (tool exec)  quality-check.sh  track-usage.sh
-  guard-destructive.sh          session-context.sh
-```
-
-**Features:**
-- Lifecycle event diagram — visual mapping of event → hook script(s)
-- Profile toggle — show/hide hooks per profile (minimal hides most, strict shows all)
-- Hook detail panel — click hook name to see: script path, description, when it fires, which profile includes it
-- Profile diff — highlight which hooks are added/removed between profiles
-- Status indicators — green (installed), red (missing script), yellow (overridden by plugin)
-
-**Data source:** `app/hooks.json` + `~/.ai-toolkit/hooks/` filesystem check
-
-**Success Criteria:**
-- [ ] All 21 hooks rendered with correct lifecycle event
-- [ ] Profile toggle filters hooks correctly
-- [ ] Missing hook scripts shown with warning indicator
-- [ ] Hook detail panel shows script content preview
-
----
-
-#### 2.5 Plugins Page
-
-**Layout:** Cards with install/remove buttons.
-
-```
-┌─────────────────────────────────┐
-│ 🧩 memory-pack        ● installed │
-│                                 │
-│ SQLite-based persistent memory  │
-│ with FTS5 search across sessions│
-│                                 │
-│ Skills: 1  Hooks: 2  Agents: 0  │
-│ DB size: 2.4 MB  Obs: 1,234     │
-│                                 │
-│ [Update]  [Clean]  [Remove]     │
-└─────────────────────────────────┘
-```
-
-**Actions:** Install, update, remove, clean — all via `POST /api/action` → `ai-toolkit plugin <action> <name>`. SSE output shown in a slide-out console panel.
-
----
-
-#### 2.6 Config Page
-
-**Layout:** Form with current configuration, editable.
-
-**Sections:**
-1. **Profile selector:** minimal / standard / strict (radio buttons)
-2. **Persona selector:** none / backend-lead / frontend-lead / devops-eng / junior-dev
-3. **Hook profile:** minimal / standard / strict
-4. **Installed modules:** checkboxes for each module from manifest.json
-5. **Language rules:** detected languages + override checkboxes
-6. **Editor configs:** which editors are configured (read-only status)
-
-**Save:** Generates and executes the equivalent `ai-toolkit install --profile X --persona Y --modules A,B,C` command.
-
----
-
-#### 2.7 Stats Page
-
-**Layout:** Usage analytics with inline SVG charts.
-
-**Charts (SVG, hand-drawn — no chart library):**
-1. **Skill invocation bar chart** — top 15 most-used skills
-2. **Invocation heatmap** — 7x24 grid (day of week × hour) showing when skills are used
-3. **Effort distribution** — pie chart of low/medium/high/max invocations
-4. **Trend line** — daily invocations over last 30 days
-
-**Data source:** `~/.ai-toolkit/stats.json` (written by `track-usage.sh` hook)
-
-**SVG implementation notes:**
-- All charts rendered as inline SVG strings in `assets.js` — no external chart library
-- Bar chart: `<rect>` elements with calculated heights, axis labels as `<text>`
-- Heatmap: 7x24 grid of `<rect>` with color intensity mapped to invocation count (0=transparent, max=accent-primary)
-- Trend line: `<polyline>` with data points as `<circle>`, area fill via `<polygon>`
-- Pie chart: `<path>` arcs calculated from percentages (use `Math.cos`/`Math.sin` for arc endpoints)
-- All charts use CSS custom properties for colors (respects design system tokens)
-
-**Fallback:** If hand-drawn SVG proves too complex for 4 chart types in 3.5d budget, reduce to 2 charts (bar + trend) for v1 and defer heatmap + pie to v2.
-
-**Success Criteria:**
-- [ ] All 4 chart types render from live stats.json data
-- [ ] Empty state when stats.json missing: "No usage data yet — skills will appear here after first use"
-- [ ] Charts responsive (SVG viewBox scales to container width)
-- [ ] Tooltip on hover showing exact counts
-
----
-
-### Phase 3: Polish (week 6-7)
-
-#### 3.1 CSS Design System
-
-**Design tokens:**
-```css
-:root {
-  /* Dark theme palette */
-  --bg-primary: #0f0f14;
-  --bg-secondary: #1a1a24;
-  --bg-card: rgba(255, 255, 255, 0.04);
-  --bg-glass: rgba(255, 255, 255, 0.06);
-  --border-glass: rgba(255, 255, 255, 0.08);
-
-  /* Accent colors (derived from SoftSpark brand) */
-  --accent-primary: #6366f1;    /* indigo */
-  --accent-secondary: #8b5cf6;  /* violet */
-  --accent-success: #10b981;    /* emerald */
-  --accent-warning: #f59e0b;    /* amber */
-  --accent-danger: #ef4444;     /* red */
-
-  /* Typography */
-  --font-sans: system-ui, -apple-system, sans-serif;
-  --font-mono: 'SF Mono', 'Cascadia Code', monospace;
-
-  /* Spacing scale */
-  --space-xs: 4px;
-  --space-sm: 8px;
-  --space-md: 16px;
-  --space-lg: 24px;
-  --space-xl: 32px;
-
-  /* Glassmorphism */
-  --glass-blur: 12px;
-  --glass-bg: rgba(255, 255, 255, 0.05);
-  --glass-border: rgba(255, 255, 255, 0.1);
-}
-```
-
-**Components:**
-- Cards with glassmorphism backdrop-filter
-- Badge pills (type, effort, status)
-- Sidebar navigation with active state
-- Console output panel (slide-out, monospace)
-- Modal overlays for detail views
-- Toast notifications for action results
-- Skeleton loading states
-
-**Responsive breakpoints:**
-- Desktop: 1200px+ (sidebar + content)
-- Tablet: 768px-1199px (collapsed sidebar)
-- Mobile: <768px (hamburger menu, stacked cards)
-
----
-
-#### 4.1 CLI Command Registration
-
-**File:** `bin/ai-toolkit.js` — add to `COMMANDS` and `SPECIAL_HANDLERS`:
-
-```javascript
-// COMMANDS
-'ui': 'Launch local web dashboard for visual toolkit management',
-
-// SPECIAL_HANDLERS
-'ui': (args) => {
-  const serverPath = path.join(TOOLKIT_DIR, 'app', 'dashboard', 'server.js');
-  const child = require('child_process').spawn('node', [serverPath, ...args], {
-    stdio: 'inherit',
-    env: { ...process.env, TOOLKIT_DIR }
-  });
-  child.on('exit', (code) => process.exit(code || 0));
-},
-```
-
-**Files to modify:**
-
-| File | Action | Description |
-|------|--------|-------------|
-| `bin/ai-toolkit.js` | EDIT | Register `ui` command |
-| `app/dashboard/server.js` | CREATE | HTTP server (main) |
-| `app/dashboard/api.js` | CREATE | API handlers |
-| `app/dashboard/assets.js` | CREATE | Embedded HTML/CSS/JS |
-| `app/dashboard/frontmatter.js` | CREATE | JS frontmatter parser |
-| `tests/test_dashboard.bats` | CREATE | Server lifecycle tests |
-| `tests/test_dashboard_api.bats` | CREATE | API endpoint tests |
-
----
-
-## 6. File Summary
-
-| File | Action | LOC (est.) | Description |
-|------|--------|------------|-------------|
-| `app/dashboard/server.js` | CREATE | ~300 | HTTP server, lifecycle, routing |
-| `app/dashboard/api.js` | CREATE | ~400 | All API endpoint handlers |
-| `app/dashboard/assets.js` | CREATE | ~2800 | Embedded HTML + CSS + JS. Split internally: `getOverviewHTML()`, `getAgentsHTML()`, etc. — one exported function per page. Single file, multiple functions (not multiple files — preserves single-`require` deployment). If file exceeds 3000 LOC, extract to `assets/` directory with `index.js` barrel |
-| `app/dashboard/frontmatter.js` | CREATE | ~80 | Frontmatter parser (JS port) |
-| `bin/ai-toolkit.js` | EDIT | +15 | Register `ui` command |
-| `tests/test_dashboard.bats` | CREATE | ~100 | Server lifecycle tests |
-| `tests/test_dashboard_api.bats` | CREATE | ~150 | API endpoint tests |
-| **Total** | | **~3845** | |
-
----
-
-## 7. Success Criteria (Overall)
-
-| Metric | Target |
-|--------|--------|
-| Pages | 8 (overview, agents, skills, hooks, plugins, config, stats, mcp) |
-| API endpoints | 9 (8 read + 1 action) |
-| External dependencies | 0 (stdlib Node.js only) |
-| Server startup time | < 500ms |
-| Auto-kill | 30 min idle (configurable) |
-| Responsive breakpoints | 3 (desktop, tablet, mobile) |
-| Tests | 25+ |
-| Browser support | Chrome, Firefox, Safari (modern, no IE) |
-
----
-
-## 7a. Non-Functional Requirements
-
-| Category | Requirement |
-|----------|-------------|
-| **Performance** | Server startup < 500ms. Page render < 200ms. API responses < 100ms. |
-| **Memory** | Max RSS < 100MB (including embedded assets). No unbounded caching. |
-| **Concurrency** | Max 1 concurrent action execution. Queue or reject additional requests with 429. |
-| **Security** | Bind `127.0.0.1` only. CSP header: `default-src 'self' 'unsafe-inline'`. No CORS headers (same-origin only). Command allowlist enforced server-side. `execFile` with array args (no shell). |
-| **Accessibility** | Keyboard navigation for all interactive elements. Focus management on page transitions. Minimum 4.5:1 contrast ratio (WCAG AA). ARIA labels on icon-only buttons. |
-| **Error handling** | Missing/corrupt data files → graceful empty state with message. Server crash → exit code 1 with stderr diagnostic. API errors → JSON `{ "error": "..." }` with HTTP status. |
-| **Graceful degradation** | If `stats.json` missing → stats page shows "No data yet". If `state.json` missing → overview shows defaults. If agent/skill .md unreadable → skip with warning in console. |
-
----
-
-## 7b. Rollback & Feature Flag
-
-The dashboard is purely additive — removing it is trivial:
-1. Delete `app/dashboard/` directory
-2. Remove `ui` from `COMMANDS` and `SPECIAL_HANDLERS` in `bin/ai-toolkit.js`
-3. No config files, no state files, no hooks to clean up
-
-**Disable without removal:** `ai-toolkit ui --disabled` could print "Dashboard disabled" and exit. Alternatively, skip registering the `ui` command in `bin/ai-toolkit.js` behind a `manifest.json` module flag so users can opt out via `--skip dashboard`.
-
----
-
-## 7c. Testing Strategy
-
-| Layer | Framework | Coverage |
-|-------|-----------|----------|
-| Server lifecycle (start, port discovery, auto-kill, shutdown) | bats | 5+ tests |
-| API endpoints (all 8 read + action) | `node:test` (stdlib) | 15+ tests |
-| SSE streaming (stdout/stderr/done events) | `node:test` | 3+ tests |
-| Command allowlist enforcement | `node:test` | 5+ tests |
-| Frontmatter parser edge cases | `node:test` | 5+ tests |
-| Integration: full pipeline (start → API → action → stop) | `node:test` | 3+ tests |
-| **Total** | | **36+** |
-
-`node:test` is stdlib (Node 18+), zero dependencies. Bats tests are for CLI-level integration (process start/stop). JS tests cover API correctness.
-
----
-
-## 7d. Discoverability
-
-| Touchpoint | Action |
-|------------|--------|
-| `ai-toolkit install` output | Print banner: `Run 'ai-toolkit ui' to explore agents, skills, and plugins visually.` |
-| `ai-toolkit help` | Include `ui` in command list |
-| README.md | Screenshot/GIF of dashboard overview page |
-| First-run detection | If `stats.json` is empty, show a "Try the dashboard" suggestion after `ai-toolkit install` |
-
----
-
-## 8. Risks and Mitigation
-
-| Risk | Probability | Impact | Mitigation |
-|------|-------------|--------|------------|
-| Assets.js file too large (embedded HTML/CSS/JS) | Medium | Low | Split into multiple template modules, lazy-load pages |
-| Port conflict on 3141 | Low | Low | Auto-increment port, show clear message |
-| SSE not supported in old browsers | Low | Low | Fallback to polling for action results |
-| Frontmatter parser edge cases | Low | Medium | Match exact patterns used in existing toolkit metadata |
-| Config writes break installation | Low | High | All writes go through existing CLI commands — never direct file mutation |
-| Stats.json missing or empty | Medium | Low | Graceful empty state with "No usage data yet" message |
-
----
-
-## 9. Pre-Mortem
-
-1. **"Too many features per page"** — Dashboard tries to show everything. Users may feel overwhelmed. Mitigation: progressive disclosure — overview page shows summary only, detail pages are opt-in.
-2. **"Asset file becomes unmaintainable"** — ~2800 LOC of embedded HTML/CSS/JS is hard to iterate on. Mitigation: split into `assets/overview.js`, `assets/agents.js`, etc. with a build-free concatenation in server.js.
-3. **"Nobody uses it"** — CLI users may prefer CLI. Mitigation: dashboard is opt-in, never required. Add `ai-toolkit ui` suggestion to `ai-toolkit install` output for new users.
-4. **"Action execution feels disconnected"** — SSE console output may confuse users unfamiliar with CLI. Mitigation: rich UI feedback (progress bars, success/error toasts) layered on top of raw output.
-5. **"Charts look bad without a library"** — Hand-drawn SVG charts may look amateur. Mitigation: keep charts simple (bar + heatmap), use consistent design tokens, test extensively.
-
----
-
-## 10. Next Actions
-
-1. [ ] Approve plan
-2. [ ] Create `app/dashboard/server.js` with HTTP server + lifecycle (1.1)
-3. [ ] Create API layer — read endpoints (1.2)
-4. [ ] Create CSS design system + client routing (3.1, 3.2)
-5. [ ] Build Overview page (2.1)
-6. [ ] Build Agents page (2.2)
-7. [ ] Build Skills page (2.3)
-8. [ ] Add action execution API (1.3)
-9. [ ] Build Hooks, Plugins, Config pages (2.4, 2.5, 2.6)
-10. [ ] Build Stats page with SVG charts (2.7)
-11. [ ] Build MCP page (2.8)
-12. [ ] Register CLI command (4.1)
-13. [ ] Tests — bats + node:test (4.2)
-14. [ ] Documentation — all 9 docs per CLAUDE.md rules (4.3)
-
----
-
-## 11. Future (Deferred)
-
-| Feature | Reason for deferral | Prerequisite |
-|---------|-------------------|--------------|
-| Credentials page (2.9) | CLI has no `credentials` commands yet | cloud-security-pack CLI implementation |
-| `ai-toolkit ui --static` | Generate a single standalone HTML file (no server) — covers 80% of catalog value at 20% complexity | Post-v1 evaluation of actual usage patterns |
-| Guided onboarding flow | Interactive wizard for new users | Post-v1, based on user feedback |
-| Light theme toggle | Dark-only for v1 | CSS variable architecture makes this easy later |
-
----
-
-## 10. Market Positioning
-
-**Target users:**
-1. **New adopters** — developers evaluating ai-toolkit who want to understand what's included before committing to a profile
-2. **Team leads** — visual overview of which agents, skills, and plugins are active across team setups
-3. **Plugin explorers** — developers browsing available plugin packs without memorizing CLI commands
-4. **Onboarding** — new team members getting oriented with the toolkit's capabilities
-
-**Competitive advantage:** No existing AI coding toolkit provides a zero-dependency ephemeral web dashboard for visual management. Backstage is 1000x heavier (requires Kubernetes, PostgreSQL). TUI tools (mise, lazygit) lack visual richness. The ephemeral auto-kill design means zero operational burden.
-
-**Discovery opportunity:** The dashboard serves as a self-documenting catalog — users discover agents and skills they didn't know existed, increasing toolkit utilization.
-
----
-
-## 12. Cross-Plan Dependencies
-
-This plan shares modification targets with two other proposed plans:
-
-| Shared File | This Plan | Enterprise Config Plan | Offline SLM Plan |
-|-------------|-----------|----------------------|-----------------|
-| `bin/ai-toolkit.js` | +15 LOC (ui command) | +40 LOC (config subcommands) | +10 LOC (compile-slm command) |
-
-**If Enterprise Config ships first:** Dashboard Config page (2.6) should display `.ai-toolkit.json` / `extends` status and `config diff` output. Add an API endpoint `GET /api/config/extends` reading resolved extends state from `state.json`.
-
-**If Offline SLM ships first:** Dashboard Overview page (2.1) should display `offline-slm` profile status and link to compiled output. Stats page may show limited data (SLM providers don't emit hook-based stats).
-
----
-
-**Last Updated:** 2026-04-10
-
----
-
 ## kb/procedures/maintenance-sop.md
 
 ---
@@ -3941,7 +3160,7 @@ ai-toolkit install --local --lang python,typescript
 ai-toolkit install --local --lang python --editors all  # language rules propagated to all editors
 ```
 
-When `--editors` is combined with `--lang` (or auto-detected languages), language rules are propagated to all configured editors as `ai-toolkit-lang-<lang>` files — not just Claude's `CLAUDE.md`. Similarly, registered custom rules (`~/.ai-toolkit/rules/`) are propagated to directory-based editor configs as `ai-toolkit-custom-<name>` files.
+When `--editors` is combined with `--lang` (or auto-detected languages), language rules are propagated to all configured editors as `ai-toolkit-lang-<lang>` files — not just Claude's `CLAUDE.md`. Similarly, registered custom rules (`~/.softspark/ai-toolkit/rules/`) are propagated to directory-based editor configs as `ai-toolkit-custom-<name>` files.
 
 **Note:** Hooks are global-only — merged into `~/.claude/settings.json` by `ai-toolkit install`. Project-local `--local` does not install hooks; any legacy `.claude/hooks.json` is removed automatically.
 
@@ -4019,7 +3238,7 @@ Third-party repos (jira-mcp, rag-mcp, etc.) can register their own rules globall
 
 ```bash
 ai-toolkit add-rule ./my-project-rules.md
-# → copies to ~/.ai-toolkit/rules/my-project-rules.md
+# → copies to ~/.softspark/ai-toolkit/rules/my-project-rules.md
 
 ai-toolkit update
 # → injects the rule into ~/.claude/CLAUDE.md and all global editor configs
@@ -4107,7 +3326,7 @@ Install copies hooks/scripts, verifies agents+skills are linked, merges hooks in
 
 Memory-pack auto-prunes observations older than 90 days on every session end (configurable via `MEMORY_RETENTION_DAYS`).
 
-State tracked in `~/.ai-toolkit/plugins.json`.
+State tracked in `~/.softspark/ai-toolkit/plugins.json`.
 
 ## Adding a KB Document
 
@@ -5194,7 +4413,7 @@ ai-toolkit/
     agents/                  # Agent definitions (.md + YAML frontmatter)
     skills/                  # skills: task, hybrid, knowledge
     rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
-    hooks/                   # Hook scripts (copied to ~/.ai-toolkit/hooks/)
+    hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
     constitution.md          # Immutable safety rules, 5 articles (marker-injected)
     ARCHITECTURE.md          # System architecture reference (marker-injected)
@@ -5241,7 +4460,7 @@ All components use merge-friendly strategies — user content is never overwritt
 ```
 Machine (global)                              Project (local)
 ──────────────────────────────────────────    ──────────────────────────────────────
-~/.claude/                                    ~/.ai-toolkit/
+~/.claude/                                    ~/.softspark/ai-toolkit/
   agents/*.md    → per-file symlinks             rules/     ← registered rules
   skills/*/      → per-dir symlinks              hooks/     ← hook scripts (copied)
   settings.json  ← hooks merged here
@@ -5281,8 +4500,8 @@ Each editor gets directory-based format (`.cursor/rules/*.mdc`, `.windsurf/rules
 | `update` | `~/.claude/` | Re-apply after npm update or after add-rule/remove-rule |
 | `update --local` | `./` | Re-apply + refresh project-local configs |
 | `uninstall` | `~/.claude/` | Strips toolkit components (preserves user content) |
-| `add-rule <file>` | `~/.ai-toolkit/rules/` | Register rule — auto-applied on every `update` |
-| `remove-rule <name>` | `~/.ai-toolkit/rules/` + `~/.claude/CLAUDE.md` | Unregister rule and remove its block |
+| `add-rule <file>` | `~/.softspark/ai-toolkit/rules/` | Register rule — auto-applied on every `update` |
+| `remove-rule <name>` | `~/.softspark/ai-toolkit/rules/` + `~/.claude/CLAUDE.md` | Unregister rule and remove its block |
 | `validate` | toolkit | Integrity check |
 | `doctor` | toolkit | Install health, hooks, benchmark freshness, and artifact drift diagnostics |
 | `benchmark-ecosystem` | toolkit | Benchmark snapshot for official Claude Code and external ecosystem repos |
@@ -5412,7 +4631,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 | PreCompact | Before compaction | `pre-compact-save.sh` | Timestamped context snapshot to audit trail |
 | SessionEnd | Session end | `session-end.sh` | Persist handoff note for the next session |
 
-Scripts at `~/.ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
+Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
 
 ## Constitution (5 Articles)
 
@@ -5531,7 +4750,7 @@ affaan-m/everything-claude-code             152     397      2
 
 ## Data Sources
 
-- User config: `~/.claude/agents/`, `~/.claude/skills/`, `~/.ai-toolkit/hooks/`
+- User config: `~/.claude/agents/`, `~/.claude/skills/`, `~/.softspark/ai-toolkit/hooks/`
 - Toolkit: `app/agents/`, `app/skills/`, `app/hooks/`
 - Ecosystem: `benchmarks/ecosystem-dashboard.json`
 
@@ -6151,7 +5370,7 @@ All entries are tagged with "_source": "<source-name>" for idempotent updates.
 | `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers | Yes |
 | `inject-hook <file.json>` | `~/.claude/settings.json` | JSON `_source` tag | Yes |
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip by `_source` | Yes |
-| `add-rule <file.md>` | `~/.ai-toolkit/rules/` | File copy + re-inject all | Yes |
+| `add-rule <file.md>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all | Yes |
 
 **Success Criteria:**
 - [x] `inject-hook ./my-hooks.json` merges hooks with auto-derived `_source` tag
@@ -6230,7 +5449,7 @@ All entries are tagged with "_source": "<source-name>" for idempotent updates.
 }
 ```
 
-**State tracking (~/.ai-toolkit/state.json):**
+**State tracking (~/.softspark/ai-toolkit/state.json):**
 ```json
 {
   "installed_version": "1.2.1",
@@ -6571,7 +5790,7 @@ description: "Comprehensive guide for setting up and using ai-toolkit configurat
 
 ## Overview
 
-Configuration inheritance enables organizations to define a shared base config published as an npm package, Git URL, or local path. Individual projects extend this base via an `extends` field in `.ai-toolkit.json`. Changes to the base propagate automatically on `ai-toolkit update --local`.
+Configuration inheritance enables organizations to define a shared base config published as an npm package, Git URL, or local path. Individual projects extend this base via an `extends` field in `.softspark-toolkit.json`. Changes to the base propagate automatically on `ai-toolkit update --local`.
 
 **Pattern:** Mirrors ESLint's `extends`, TypeScript's `extends`, and Prettier's shared configs.
 
@@ -6600,7 +5819,7 @@ ai-toolkit config init --extends @mycompany/ai-toolkit-config
 ai-toolkit install --local
 ```
 
-Or manually create `.ai-toolkit.json`:
+Or manually create `.softspark-toolkit.json`:
 
 ```json
 {
@@ -6624,7 +5843,7 @@ ai-toolkit config check       # CI enforcement check
 
 ## Configuration Reference
 
-### Project config (`.ai-toolkit.json`)
+### Project config (`.softspark-toolkit.json`)
 
 | Field | Type | Description |
 |-------|------|-------------|
@@ -6748,7 +5967,7 @@ Requirements:
 
 ### `ai-toolkit config validate [path]`
 
-Validates `.ai-toolkit.json` schema, resolves extends, checks enforcement.
+Validates `.softspark-toolkit.json` schema, resolves extends, checks enforcement.
 
 ```bash
 ai-toolkit config validate
@@ -6773,7 +5992,7 @@ ai-toolkit config diff
 
 ### `ai-toolkit config init [flags]`
 
-Create `.ai-toolkit.json` interactively or with flags.
+Create `.softspark-toolkit.json` interactively or with flags.
 
 ```bash
 ai-toolkit config init                                    # interactive
@@ -6814,12 +6033,12 @@ GitHub Actions example:
 
 ## Lock File
 
-`.ai-toolkit.lock.json` pins exact resolved versions for reproducible installs.
+`.softspark-toolkit.lock.json` pins exact resolved versions for reproducible installs.
 
 - `install --local` → creates/updates lock file
 - `update --local` → re-resolves and updates lock file
 - `update --local --refresh-base` → force re-fetch ignoring cache
-- Commit `.ai-toolkit.lock.json` to git for team synchronization
+- Commit `.softspark-toolkit.lock.json` to git for team synchronization
 
 ```json
 {
@@ -6828,7 +6047,7 @@ GitHub Actions example:
     "@mycompany/ai-toolkit-config": {
       "version": "2.1.0",
       "integrity": "sha256:abc123...",
-      "cached": "~/.ai-toolkit/config-cache/@mycompany/ai-toolkit-config/2.1.0/"
+      "cached": "~/.softspark/ai-toolkit/config-cache/@mycompany/ai-toolkit-config/2.1.0/"
     }
   }
 }
@@ -6840,7 +6059,7 @@ GitHub Actions example:
 
 When npm/git is unavailable:
 
-1. Checks cache (`~/.ai-toolkit/config-cache/`)
+1. Checks cache (`~/.softspark/ai-toolkit/config-cache/`)
 2. If cached version found → uses with warning
 3. If not cached → error with instructions
 
@@ -6912,7 +6131,7 @@ This design is intentional: ai-toolkit is a generic toolkit. Consumers (MCP serv
 | `remove-rule <name>` | `~/.claude/CLAUDE.md` | Strip markers by block name | Yes |
 | `inject-hook <file.json>` | `~/.claude/settings.json` | JSON `_source` tag per entry | Yes |
 | `remove-hook <name>` | `~/.claude/settings.json` | Strip all entries with matching `_source` | Yes |
-| `add-rule <file.md>` | `~/.ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
+| `add-rule <file.md>` | `~/.softspark/ai-toolkit/rules/` | File copy + re-inject all rules on next `update` | Yes |
 | `mcp add <name...>` | `.mcp.json` | Merge `mcpServers` block from template | Yes |
 
 ## inject-rule
@@ -7094,8 +6313,8 @@ That means one machine-level install provides agents, skills, hooks, and rules t
 | `ai-toolkit install --local --lang <lang>` | current project | explicit language selection for rules (e.g. `--lang typescript`, `--lang go,python`); auto-detected when omitted |
 | `ai-toolkit install --modules <list>` | `~/.claude/` | selective module install (e.g. `--modules core,agents,rules-typescript`) |
 | `ai-toolkit update --local` | current project | refresh project configs; auto-detects editors from existing files |
-| `ai-toolkit add-rule` | `~/.ai-toolkit/rules/` | register a global rule |
-| `ai-toolkit remove-rule` | `~/.ai-toolkit/rules/` | unregister a global rule |
+| `ai-toolkit add-rule` | `~/.softspark/ai-toolkit/rules/` | register a global rule |
+| `ai-toolkit remove-rule` | `~/.softspark/ai-toolkit/rules/` | unregister a global rule |
 
 ## Why global install is the default
 
@@ -7350,17 +6569,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`
 
@@ -7372,7 +6591,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:**
@@ -7387,7 +6606,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"):
@@ -7401,7 +6620,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:
@@ -7417,7 +6636,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).
@@ -7430,7 +6649,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.
@@ -7443,10 +6662,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`
 
@@ -7454,7 +6673,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.
@@ -7467,7 +6686,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:
@@ -7485,7 +6704,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:
@@ -7501,7 +6720,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`.
@@ -7514,7 +6733,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.
@@ -7527,7 +6746,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.
@@ -7540,7 +6759,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):**
@@ -7558,7 +6777,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.
@@ -7585,7 +6804,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.
@@ -7596,7 +6815,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.
@@ -7607,10 +6826,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`
 
@@ -7618,10 +6837,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`
 
@@ -7629,7 +6848,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.
@@ -7640,10 +6859,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
 
@@ -7662,7 +6881,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)
@@ -7687,7 +6906,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
@@ -7717,7 +6936,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
 ```
 
@@ -7758,9 +6977,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
@@ -7788,7 +7007,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
 
@@ -8075,7 +7294,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
@@ -8176,7 +7395,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
@@ -8190,7 +7409,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
 {
@@ -8214,7 +7433,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
 
@@ -8504,11 +7723,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
 
@@ -8525,8 +7744,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)
@@ -9082,7 +8301,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
 
@@ -9098,7 +8317,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)
@@ -9133,7 +8352,7 @@ 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
 ```
 
@@ -9171,8 +8390,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` |
@@ -9182,7 +8401,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)