wicked-brain 0.1.0

package/skills/wicked-brain-search/SKILL.md

@@ -0,0 +1,126 @@
+---
+name: wicked-brain:search
+description: |
+  Search the digital brain for relevant content. Dispatches parallel search
+  subagents across local and linked brains. Returns results at depth 0 with
+  deeper hints.
+  
+  Use when: "search brain for", "find in brain", "brain search", or when
+  looking for specific content across the knowledge base.
+---
+
+# wicked-brain:search
+
+You search the digital brain by dispatching parallel subagents — one per brain
+in the network (local + parents + links).
+
+## Cross-Platform Notes
+
+Commands in this skill work on macOS, Linux, and Windows. When a command has
+platform differences, alternatives are shown. Your native tools (Read, Write,
+Grep, Glob) work everywhere — prefer them over shell commands when possible.
+
+For the brain path default:
+- macOS/Linux: ~/.wicked-brain
+- Windows: %USERPROFILE%\.wicked-brain
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Parameters
+
+- **query** (required): what to search for
+- **limit** (default: 10): max results per brain
+- **depth** (default: 0): result detail level
+
+## Process
+
+### Step 1: Discover brains to search
+
+Use the Read tool on `{brain_path}/brain.json` to get parents and links.
+For each parent/link, check if it's accessible by reading `{brain_path}/{relative_path}/brain.json`.
+
+Build a list of accessible brains with their absolute paths.
+
+### Step 2: Ensure server is running
+
+```bash
+curl -s -f -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"health","params":{}}'
+```
+
+If connection refused, trigger wicked-brain:server auto-start pattern.
+
+### Step 3: Dispatch search subagents in parallel
+
+Launch one subagent per accessible brain **in the same message** (parallel dispatch).
+
+Each search subagent receives these instructions:
+
+```
+You are a search agent for the "{brain_id}" brain at {brain_path}.
+
+Search for: "{query}"
+
+## Step 1: Server search (FTS5)
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"search","params":{"query":"{query}","limit":{limit}}}'
+```
+
+Parse the JSON response to get results.
+
+## Step 2: File search (catches what FTS might miss)
+
+Search for exact phrases or patterns that FTS tokenization might split.
+Use your Grep tool (preferred) or shell fallback:
+- macOS/Linux: `grep -rl "{query}" {brain_path}/chunks/ {brain_path}/wiki/ 2>/dev/null | head -20`
+- Windows: `findstr /s /m "{query}" {brain_path}\chunks\*.md {brain_path}\wiki\*.md 2>nul`
+
+## Step 3: Merge and return
+
+Combine FTS results and grep matches. Deduplicate by path.
+For each result, read the first line of the file to get the title/summary.
+
+Return in this format:
+BRAIN: {brain_id}
+RESULTS:
+- {path} | score: {score} | {one-line summary}
+- {path} | score: {score} | {one-line summary}
+TOTAL: {count}
+```
+
+### Step 4: Merge results from all subagents
+
+After all subagents return:
+1. Collect all results
+2. Deduplicate by path (keep higher score)
+3. Sort by score descending
+4. Tag each result with its brain origin
+
+### Step 5: Return at requested depth
+
+**Depth 0 (default):**
+```
+Found {N} matches across {M} brains (showing top {limit}):
+
+1. {path} [{brain}] ({score})
+   {one-line summary}
+
+2. {path} [{brain}] ({score})
+   {one-line summary}
+
+...
+
+Unreachable brains: {list, if any}
+
+To read any result: wicked-brain:read {path} --depth 2
+```
+
+**Depth 1:** For each result, also include frontmatter + first paragraph.
+**Depth 2:** For each result, include full content (use sparingly — high token cost).

package/skills/wicked-brain-server/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: wicked-brain:server
+description: |
+  Manages the wicked-brain background server. Auto-triggered when any brain skill
+  gets a connection error. Starts the server, checks health, and reports status.
+  Users should never need to invoke this directly.
+---
+
+# wicked-brain:server
+
+You manage the wicked-brain background server. This skill is triggered automatically
+when another brain skill cannot reach the server.
+
+## Cross-Platform Notes
+
+Commands in this skill work on macOS, Linux, and Windows. When a command has
+platform differences, alternatives are shown. Your native tools (Read, Write,
+Grep, Glob) work everywhere — prefer them over shell commands when possible.
+
+For the brain path default:
+- macOS/Linux: ~/.wicked-brain
+- Windows: %USERPROFILE%\.wicked-brain
+
+## When to use
+
+- When a brain skill reports "connection refused" or similar error from curl
+- When asked to check or restart the brain server
+
+## Server check and start
+
+1. Read the file at `{brain_path}/_meta/config.json` to get the port and brain path.
+
+2. Try a health check:
+   ```bash
+   curl -s -f -X POST http://localhost:{port}/api \
+     -H "Content-Type: application/json" \
+     -d '{"action":"health","params":{}}'
+   ```
+
+3. If the health check succeeds, the server is running. Report the status.
+
+4. If connection refused:
+   a. Read the file at `{brain_path}/_meta/server.pid` to get the PID.
+
+   b. Check if the process is running:
+      - macOS/Linux: `kill -0 {pid} 2>/dev/null`
+      - Windows: `tasklist /FI "PID eq {pid}" 2>nul | findstr {pid}`
+      - Or use Python: `python3 -c "import os; os.kill({pid}, 0)" 2>/dev/null || python -c "import os; os.kill({pid}, 0)"`
+
+   c. If the process is dead or no PID file, start the server:
+      ```bash
+      npx wicked-brain-server --brain {brain_path} --port {port} &
+      ```
+      On Windows (PowerShell): `Start-Process npx -ArgumentList "wicked-brain-server","--brain","{brain_path}","--port","{port}" -NoNewWindow`
+
+   d. Wait 2 seconds, then retry the health check.
+   e. If still failing, tell the user:
+      "The brain server couldn't start automatically. Please run:
+       `npx wicked-brain-server --brain {brain_path} --port {port}`"
+
+## API pattern for other skills
+
+All skills that need the server should use this curl pattern:
+
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"{action}","params":{params_json}}'
+```
+
+`curl` works on macOS, Linux, and Windows 10+ (ships by default). If curl fails
+with connection refused, trigger this wicked-brain:server skill.

package/skills/wicked-brain-status/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: wicked-brain:status
+description: |
+  Show brain health, stats, and orientation with progressive loading.
+  Depth 0: summary. Depth 1: + topic distribution. Depth 2: full orientation.
+  
+  Use when: "brain status", "what's in my brain", "brain health", or when
+  orienting at the start of a session.
+---
+
+# wicked-brain:status
+
+You report the brain's current state using progressive loading.
+
+## Cross-Platform Notes
+
+Commands in this skill work on macOS, Linux, and Windows. When a command has
+platform differences, alternatives are shown. Your native tools (Read, Write,
+Grep, Glob) work everywhere — prefer them over shell commands when possible.
+
+For the brain path default:
+- macOS/Linux: ~/.wicked-brain
+- Windows: %USERPROFILE%\.wicked-brain
+
+## Config
+
+Read `_meta/config.json` for brain path and server port.
+If it doesn't exist, trigger wicked-brain:init.
+
+## Parameters
+
+- **depth** (default: 0): how much to return
+
+## Process
+
+### Step 1: Read brain.json
+
+Use the Read tool on `{brain_path}/brain.json` to get id, name, parents, links.
+
+### Step 2: Get server stats
+
+Ensure the server is running (use the wicked-brain:server auto-start pattern):
+```bash
+curl -s -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"stats","params":{}}'
+```
+
+If connection refused, start the server (see wicked-brain:server skill), then retry.
+
+### Step 3: Return at requested depth
+
+**Depth 0:**
+```
+Brain: {name} ({id})
+Chunks: {total_chunks} | Wiki articles: {total_wiki_articles}
+Last indexed: {last_indexed}
+Linked brains: {list of parents and links with accessible/inaccessible status}
+```
+
+Check parent/link accessibility by using the Read tool on
+`{brain_path}/{relative_link_path}/brain.json`. Shell fallback:
+- macOS/Linux: `cat {brain_path}/{relative_link_path}/brain.json 2>/dev/null`
+- Windows: `Get-Content "{brain_path}\{relative_link_path}\brain.json" 2>nul`
+
+**Depth 1:**
+Depth 0 plus:
+- Use the Read tool on `_meta/log.jsonl` (last 50 lines) to identify topic distribution from recent tag events.
+  Shell fallback: `tail -50 {brain_path}/_meta/log.jsonl` (macOS/Linux) or `Get-Content "{brain_path}\_meta\log.jsonl" -Tail 50` (Windows PowerShell)
+- List the top 10 most common tags
+- Flag any staleness warnings (sources modified after last ingest)
+
+**Depth 2:**
+Depth 1 plus:
+- Read `_meta/log.jsonl` fully for recent activity (last 7 days)
+- List coverage gaps (chunks with no wiki article referencing them)
+- Full linked brain details

package/skills/wicked-brain-update/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: wicked-brain:update
+description: |
+  Check for and install wicked-brain updates. Compares installed version against
+  npm registry, updates skills across all detected CLIs, and updates the server.
+  
+  Use when: "update wicked-brain", "check for brain updates", "wicked-brain:update",
+  or periodically to stay current.
+---
+
+# wicked-brain:update
+
+You check for and install updates to the wicked-brain skills and server.
+
+## Cross-Platform Notes
+
+Commands in this skill work on macOS, Linux, and Windows. When a command has
+platform differences, alternatives are shown. Your native tools (Read, Write,
+Grep, Glob) work everywhere — prefer them over shell commands when possible.
+
+For the brain path default:
+- macOS/Linux: ~/.wicked-brain
+- Windows: %USERPROFILE%\.wicked-brain
+
+## When to use
+
+- User asks to update or check for updates
+- Periodically (suggest checking monthly)
+- After encountering unexpected behavior that might be fixed in a newer version
+
+## Process
+
+### Step 1: Check current version
+
+Read the installed server version:
+```bash
+wicked-brain-server --version 2>/dev/null || npx wicked-brain-server --version 2>/dev/null || echo "not installed"
+```
+
+If that doesn't work, check the package directly:
+```bash
+npm list -g wicked-brain-server --json 2>/dev/null | grep version
+```
+
+### Step 2: Check latest version on npm
+
+```bash
+npm view wicked-brain version 2>/dev/null
+```
+
+### Step 3: Compare versions
+
+If the installed version matches the latest, report:
+"wicked-brain is up to date (v{version})."
+
+If an update is available, ask the user:
+"wicked-brain v{new} is available (you have v{current}). Update now?"
+
+### Step 4: Update (if user approves)
+
+#### Update everything (skills + server)
+
+The server is bundled in the main package — one command updates both:
+
+```bash
+npx wicked-brain@latest
+```
+
+This re-runs the installer with the latest version, updating all skills across detected CLIs. The server binary updates automatically since it's part of the same package.
+
+### Step 5: Restart server if running
+
+Check if a brain server is running and restart it to pick up changes.
+
+Find running server PIDs by searching for `server.pid` files under `_meta/` directories
+in the home directory. Use your Glob tool if available.
+
+On macOS/Linux:
+```bash
+find ~ -name "server.pid" -path "*/_meta/*" 2>/dev/null
+```
+On Windows (PowerShell):
+```powershell
+Get-ChildItem -Recurse -Filter "server.pid" -Path $env:USERPROFILE -ErrorAction SilentlyContinue | Where-Object { $_.DirectoryName -match "_meta" }
+```
+
+For each pid file found:
+1. Read the file to get the PID.
+2. Check if the process is alive:
+   - macOS/Linux: `kill -0 {pid} 2>/dev/null`
+   - Windows: `tasklist /FI "PID eq {pid}" 2>nul | findstr {pid}`
+   - Or Python: `python3 -c "import os; os.kill({pid}, 0)" 2>/dev/null || python -c "import os; os.kill({pid}, 0)"`
+3. If alive, stop it:
+   - macOS/Linux: `kill {pid}`
+   - Windows: `Stop-Process -Id {pid}`
+4. Read `{brain_dir}/_meta/config.json` to get the port.
+5. Restart: `npx wicked-brain-server --brain "{brain_dir}" --port {port}`
+   On Windows: `Start-Process npx -ArgumentList "wicked-brain-server","--brain","{brain_dir}","--port","{port}" -NoNewWindow`
+
+### Step 6: Report
+
+Tell the user what was updated:
+- Server: v{old} -> v{new}
+- Skills: updated in {N} CLIs
+- Running servers: {N} restarted
+
+## Version check without updating
+
+If the user just wants to check (not update), stop after Step 3 and report
+the current vs. available version.