wicked-brain 0.12.1 → 0.13.0

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

@@ -17,15 +17,10 @@ You answer questions from the brain's content by dispatching a query subagent.
 
 ## Config
 
-Resolve the brain config via the shared resolution in
-wicked-brain:init § "Resolving the brain config". In short: try
-`~/.wicked-brain/projects/{cwd_basename}/_meta/config.json` first, fall back
-to `~/.wicked-brain/_meta/config.json` (legacy flat), else trigger
-wicked-brain:init. Read the resolved file for brain path and server port.
-
-Do NOT read a bare relative `_meta/config.json` — the model will resolve it
-against the current working directory and brain files will end up in the
-project root.
+Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
+`--brain <path>` to override the auto-detected brain, or set
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
+init required) and writes an audit record to `{brain}/calls/` per call.
 
 ## Parameters
 
@@ -37,7 +32,7 @@ Dispatch a query subagent with these instructions:
 
 ```
 You are a research agent for the digital brain at {brain_path}.
-Server: http://localhost:{port}/api
+Server interactions: use `npx wicked-brain-call <action> [--param k=v ...]`.
 
 Question: "{question}"
 
@@ -95,9 +90,7 @@ Run multiple searches if key terms suggest different angles.
 
 Search the brain for relevant content:
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"search","params":{"query":"{term}","limit":10,"session_id":"{session_id}"}}'
+npx wicked-brain-call search --param query={term} --param limit=10 --param session_id={session_id}
 ```
 
 Pass a session_id with every search call. This enables access tracking for
@@ -108,9 +101,7 @@ used for access-log tracking and diversity ranking across repeated searches.
 
 If the question implies recency ("recently", "this week", "latest"), add a `since` parameter to the search with an ISO 8601 timestamp. For example, for "this week" use the date 7 days ago:
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"search","params":{"query":"{term}","limit":10,"session_id":"{session_id}","since":"{iso8601_date}"}}'
+npx wicked-brain-call search --param query={term} --param limit=10 --param session_id={session_id} --param since={iso8601_date}
 ```
 
 Also search with grep for exact phrases (use your Grep tool when available —
@@ -154,9 +145,7 @@ Check the content for [[wikilinks]]. If following them would provide useful cont
 
 Check backlinks — what else references the content you found:
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"backlinks","params":{"id":"{result_path}"}}'
+npx wicked-brain-call backlinks --param id={result_path}
 ```
 
 ## Step 4: Synthesize answer

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

@@ -17,21 +17,19 @@ compact, navigable list.
 
 ## Cross-Platform Notes
 
-- Uses `curl` for server API calls (Windows 10+, macOS, Linux)
+This skill uses `npx wicked-brain-call` for all server interaction. The CLI
+works on macOS, Linux, and Windows; it discovers the brain, auto-starts the
+server, and writes a per-call audit record under `{brain}/calls/`.
+
 - File reads use the agent-native Read tool
 - Paths always use forward slashes
 
 ## Config
 
-Resolve the brain config via the shared resolution in
-wicked-brain:init § "Resolving the brain config". In short: try
-`~/.wicked-brain/projects/{cwd_basename}/_meta/config.json` first, fall back
-to `~/.wicked-brain/_meta/config.json` (legacy flat), else trigger
-wicked-brain:init. Read the resolved file for brain path and server port.
-
-Do NOT read a bare relative `_meta/config.json` — the model will resolve it
-against the current working directory and brain files will end up in the
-project root.
+Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
+`--brain <path>` to override the auto-detected brain, or set
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
+init required) and writes an audit record to `{brain}/calls/` per call.
 
 ## Parameters
 
@@ -48,9 +46,7 @@ project root.
 Start with the aggregate view so the user can see the landscape before the list:
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"memory_stats"}'
+npx wicked-brain-call memory_stats
 ```
 
 Render `total`, `by_type`, `by_tier`, `by_age` as a one-line header.
@@ -58,9 +54,7 @@ Render `total`, `by_type`, `by_tier`, `by_age` as a one-line header.
 ### Step 2: Fetch candidates
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"recent_memories","params":{"days":{days},"limit":{limit * 3}}}'
+npx wicked-brain-call recent_memories --param days={days} --param limit={limit * 3}
 ```
 
 Over-fetch by 3x so agent-side type/tier filtering still returns a useful page.

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

@@ -30,15 +30,10 @@ For the brain path default:
 
 ## Config
 
-Resolve the brain config via the shared resolution in
-wicked-brain:init § "Resolving the brain config". In short: try
-`~/.wicked-brain/projects/{cwd_basename}/_meta/config.json` first, fall back
-to `~/.wicked-brain/_meta/config.json` (legacy flat), else trigger
-wicked-brain:init. Read the resolved file for brain path and server port.
-
-Do NOT read a bare relative `_meta/config.json` — the model will resolve it
-against the current working directory and brain files will end up in the
-project root.
+Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
+`--brain <path>` to override the auto-detected brain, or set
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
+init required) and writes an audit record to `{brain}/calls/` per call.
 
 ## Parameters
 
@@ -76,13 +71,15 @@ Build a list of accessible brains with their absolute paths.
 
 ### Step 2: Ensure server is running
 
+`wicked-brain-call` auto-starts the server on first invocation. If you want
+to be defensive, run a probe up front:
+
 ```bash
-curl -s -f -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"health","params":{}}'
+npx wicked-brain-call health
 ```
 
-If connection refused, trigger wicked-brain:server auto-start pattern.
+Exit code 0 means the server is up. Exit code 2 indicates an infra failure
+(server could not be reached or spawned).
 
 ### Step 3: Dispatch search subagents in parallel
 
@@ -104,9 +101,7 @@ 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}}}'
+npx wicked-brain-call search --param query={query} --param limit={limit} --brain {brain_path}
 ```
 
 Parse the JSON response to get results.
@@ -136,9 +131,7 @@ After all subagents return:
 If the merged results have 0 matches across all brains, the query is a "search miss."
 Log it so the brain can learn:
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"search_misses","params":{"query":"{original_query}","session_id":"{session_id}"}}'
+npx wicked-brain-call search_misses --param query={original_query} --param session_id={session_id}
 ```
 
 Note: This logging happens server-side automatically when search returns 0 results.

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

@@ -1,21 +1,23 @@
 ---
 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.
+  Manages the wicked-brain background server. Most callers should use
+  `wicked-brain-call` directly — it auto-starts the server. This skill is
+  for explicit lifecycle management: start, stop, status, or recovery from
+  a stuck process.
 ---
 
 # wicked-brain:server
 
-You manage the wicked-brain background server. This skill is triggered automatically
-when another brain skill cannot reach the server.
+Manage the wicked-brain background server lifecycle explicitly. **Most skills
+do not need this** — `npx wicked-brain-call <action>` will spawn the server
+on first call (lock-guarded against races) and reuse it thereafter.
 
 ## 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.
+This skill uses `npx wicked-brain-call` for all server interaction. The CLI
+works on macOS, Linux, and Windows; it discovers the brain, auto-starts the
+server, and writes a per-call audit record under `{brain}/calls/`.
 
 For the brain path default:
 - macOS/Linux: `~/.wicked-brain/projects/{cwd_basename}`
@@ -23,71 +25,47 @@ For the brain path default:
 
 ## Config
 
-Resolve the brain config via the shared resolution in
-wicked-brain:init § "Resolving the brain config". In short: try
-`~/.wicked-brain/projects/{cwd_basename}/_meta/config.json` first, fall back
-to `~/.wicked-brain/_meta/config.json` (legacy flat), else trigger
-wicked-brain:init. Read the resolved file to get `brain_path` and `server_port`.
+Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
+`--brain <path>` to override the auto-detected brain, or set
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
+init required) and writes an audit record to `{brain}/calls/` per call.
 
-If the calling skill already passed `brain_path`, use that directly instead of
-re-resolving.
+## When to use
 
-Do NOT read a bare relative `_meta/config.json` — the model will resolve it
-against the current working directory and brain files will end up in the
-project root.
+- Explicitly start, stop, or check the server (rare — `wicked-brain-call`
+  handles this for you on every call)
+- Recover from a stuck or stale server process
 
-## When to use
+## Canonical commands
+
+```bash
+npx wicked-brain-call --status [--brain {brain_path}]
+npx wicked-brain-call --start  [--brain {brain_path}]
+npx wicked-brain-call --stop   [--brain {brain_path}]
+```
+
+`--status` reports whether a live server is answering on the configured port,
+the bound port, and the brain id. `--start` spawns the server (idempotent —
+no-op if already running). `--stop` signals the recorded PID and clears the
+PID file.
+
+If the user reports "the brain server seems wedged":
 
-- 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":{}}'
-   ```
-   A successful response returns `{"status":"ok"}`. If the request succeeds,
-   the server is running — report the status and stop.
-
-3. 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.
-      Also pass `--source` if `source_path` is set in `{brain_path}/_meta/config.json`
-      (this roots LSP language servers at the ingested project so symbol
-      lookup and go-to-definition work correctly):
-      ```bash
-      npx wicked-brain-server --brain {brain_path} --port {port} [--source {source_path}] &
-      ```
-      On Windows (PowerShell):
-      ```powershell
-      Start-Process -FilePath "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}`"
+1. `npx wicked-brain-call --status --brain {brain_path}` to confirm.
+2. `npx wicked-brain-call --stop --brain {brain_path}` to terminate.
+3. `npx wicked-brain-call --start --brain {brain_path}` to relaunch.
+4. `npx wicked-brain-call health --brain {brain_path}` to verify.
 
 ## API pattern for other skills
 
-All skills that need the server should use this curl pattern:
+All skills should call the server through `wicked-brain-call`:
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"{action}","params":{params_json}}'
+npx wicked-brain-call <action>                                 # no params
+npx wicked-brain-call <action> --param key=value [--param ...] # simple params
+npx wicked-brain-call <action> '{"k":"v","nested":[1,2]}'      # complex JSON
+echo '{"k":"v"}' | npx wicked-brain-call <action> -            # stdin (kubectl-style)
 ```
 
-`curl` works on macOS, Linux, and Windows 10+ (ships by default). If curl fails
-with connection refused, trigger this wicked-brain:server skill.
+Exit codes: `0` = ok, `1` = API returned an error, `2` = infra failure
+(server unreachable or could not be spawned).

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

@@ -24,15 +24,10 @@ For the brain path default:
 
 ## Config
 
-Resolve the brain config via the shared resolution in
-wicked-brain:init § "Resolving the brain config". In short: try
-`~/.wicked-brain/projects/{cwd_basename}/_meta/config.json` first, fall back
-to `~/.wicked-brain/_meta/config.json` (legacy flat), else trigger
-wicked-brain:init. Read the resolved file for brain path and server port.
-
-Do NOT read a bare relative `_meta/config.json` — the model will resolve it
-against the current working directory and brain files will end up in the
-project root.
+Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
+`--brain <path>` to override the auto-detected brain, or set
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
+init required) and writes an audit record to `{brain}/calls/` per call.
 
 ## Parameters
 
@@ -46,14 +41,12 @@ 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):
+`wicked-brain-call` auto-starts the server on first invocation:
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"stats","params":{}}'
+npx wicked-brain-call stats
 ```
 
-If connection refused, invoke the `wicked-brain:server` skill to start the server, then retry.
+If the call exits with code 2 (infra failure), surface the error to the user.
 
 ### Step 3: Return at requested depth
 
@@ -77,17 +70,13 @@ Depth 0 plus:
 - Show topic distribution for the last 7 days by searching with a `since` filter.
   The `since` value must be ISO 8601 format (e.g., `2025-01-15T00:00:00Z`):
   ```bash
-  curl -s -X POST http://localhost:{port}/api \
-    -H "Content-Type: application/json" \
-    -d '{"action":"search","params":{"query":"*","limit":100,"since":"{iso8601_7_days_ago}"}}'
+  npx wicked-brain-call search --param query=* --param limit=100 --param since={iso8601_7_days_ago}
   ```
   Group results by path prefix (e.g., `chunks/extracted/`, `wiki/`) to show recent activity distribution.
 - List the top 10 most common tags
 - Flag wiki staleness warnings by calling `verify_wiki`:
   ```bash
-  curl -s -X POST http://localhost:{port}/api \
-    -H "Content-Type: application/json" \
-    -d '{"action":"verify_wiki","params":{}}'
+  npx wicked-brain-call verify_wiki
   ```
   Report one line per non-fresh bucket — only emit the lines where the count is > 0:
   ```
@@ -103,9 +92,7 @@ Depth 0 plus:
 Detect chunks that are frequently accessed but have never been compiled into wiki articles:
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"candidates","params":{"mode":"promote","limit":50}}'
+npx wicked-brain-call candidates --param mode=promote --param limit=50
 ```
 
 For each result where `access_count >= 5` and `session_diversity >= 3`, check whether any wiki article references it. Use the Grep tool on `{brain_path}/wiki/` searching for the chunk path string. If no wiki article references it, flag it as convergence debt:
@@ -120,9 +107,7 @@ If any convergence debt exists, suggest running `wicked-brain:compile` to promot
 Detect path prefixes that concentrate multiple contradictions:
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"contradictions","params":{}}'
+npx wicked-brain-call contradictions
 ```
 
 Group the returned contradiction links by path prefix: take the first two path segments of each linked path (e.g., a path `chunks/extracted/auth/session.md` yields prefix `chunks/extracted/auth/`). If any prefix has 2 or more contradiction links, flag it as a hotspot:
@@ -142,9 +127,7 @@ Check link integrity and surface knowledge gaps using two additional API calls.
 
 Get link health:
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"link_health","params":{}}'
+npx wicked-brain-call link_health
 ```
 
 Report:
@@ -154,9 +137,7 @@ Report:
 
 Get recent search misses:
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"search_misses","params":{"limit":20}}'
+npx wicked-brain-call search_misses --param limit=20
 ```
 
 Report the top recurring search miss queries to identify knowledge gaps. If a query appears multiple times, that topic is a strong candidate for ingestion or wiki article creation.

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

@@ -25,15 +25,10 @@ For the brain path default:
 
 ## Config
 
-Resolve the brain config via the shared resolution in
-wicked-brain:init § "Resolving the brain config". In short: try
-`~/.wicked-brain/projects/{cwd_basename}/_meta/config.json` first, fall back
-to `~/.wicked-brain/_meta/config.json` (legacy flat), else trigger
-wicked-brain:init. Read the resolved file for brain path and server port.
-
-Do NOT read a bare relative `_meta/config.json` — the model will resolve it
-against the current working directory and brain files will end up in the
-project root.
+Brain discovery + server lifecycle are handled by `wicked-brain-call`. Pass
+`--brain <path>` to override the auto-detected brain, or set
+`WICKED_BRAIN_PATH`. The CLI starts the server on first call (no manual
+init required) and writes an audit record to `{brain}/calls/` per call.
 
 ## Synonym File
 
@@ -99,17 +94,13 @@ for user review.
 **Step 1: Get recent search misses**
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"search_misses","params":{"limit":50}}'
+npx wicked-brain-call search_misses --param limit=50
 ```
 
 **Step 2: Get tag frequency**
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"tag_frequency","params":{}}'
+npx wicked-brain-call tag_frequency
 ```
 
 **Step 3: Cross-reference and suggest**

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

@@ -19,9 +19,15 @@ server for the current project's brain (or a named brain).
 
 ## Cross-Platform Notes
 
+Server interaction goes through `npx wicked-brain-call`, which works on
+macOS, Linux, and Windows; it discovers the brain, auto-starts the server,
+and writes a per-call audit record under `{brain}/calls/`.
+
 The only platform-specific piece is the "open a URL in the default browser"
-command. Everything else is curl + Read/Write. Fallbacks are provided for all
-three major platforms.
+command. The viewer is served at `GET /` on the same port the JSON API uses,
+so the URL still needs the bound `server_port` — read it from the resolved
+`{brain_path}/_meta/config.json` (the CLI writes the actual bound port back
+to that file on startup).
 
 For the brain path default:
 - macOS/Linux: `~/.wicked-brain/projects/{project-name}`
@@ -54,17 +60,17 @@ Read the resolved config to get `server_port`.
 
 ### Step 2: Verify the server is running
 
+`wicked-brain-call` auto-starts the server on first invocation, so a single
+health probe is enough:
+
 ```bash
-curl -s -f -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"health","params":{}}'
+npx wicked-brain-call health --brain {brain_path}
 ```
 
-If the call fails with connection refused, invoke the wicked-brain:server
-auto-start pattern — start the server against the resolved brain path and
-wait for health to return ok before continuing. Never open a browser at a
-URL that isn't serving yet; that produces a scary "can't connect" page the
-user then has to refresh.
+Exit code 0 confirms the server is up. Exit code 2 (infra failure) means the
+server could not be reached or spawned — surface the error and stop. Never
+open a browser at a URL that isn't serving yet; that produces a scary "can't
+connect" page the user then has to refresh.
 
 ### Step 3: Build the URL
 

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

@@ -166,9 +166,7 @@ run in order, and are idempotent (safe to re-run).
 After server restart, verify the server started successfully and migrations ran:
 
 ```bash
-curl -s -X POST http://localhost:{port}/api \
-  -H "Content-Type: application/json" \
-  -d '{"action":"health"}'
+npx wicked-brain-call health --brain "{brain_dir}"
 ```
 
 If the health check fails, the migration may have errored. To diagnose: