wicked-brain 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [

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

@@ -35,6 +35,12 @@ Read agent definitions from the `agents/` subdirectory relative to this skill fi
 
 ## Dispatch Mode
 
+Dispatching a named agent (rather than running inline) gives it isolated
+context, a longer token budget, and access to file-writing tools. This makes
+it better suited for heavy background tasks — consolidation, full project
+onboarding, or large-scale compilation — where inline execution would exhaust
+context or produce incomplete results.
+
 1. Read the requested agent's `.md` file from `agents/` at depth 2
 2. Dispatch as a subagent with those instructions using the host CLI's mechanism:
    - Claude Code: use `Agent` tool

package/skills/wicked-brain-agent/platform/claude/wicked-brain-onboard.md

@@ -24,18 +24,41 @@ Create a structured summary of what you found.
 
 ### Step 2: Trace architecture
 
-- Identify entry points (main files, server start, CLI entry)
+- Identify entry points — look for: `main.js`, `index.js/ts`, `server.js`,
+  `app.py`, `main.go`, `src/main.*`, `bin/` executables, `__main__.py`
 - Map module boundaries (directories, packages, namespaces)
-- Identify API surfaces (HTTP routes, CLI commands, exported functions)
+- Identify API surfaces — look for: Express/Fastify route definitions
+  (`app.get`, `router.post`), CLI command registrations (`program.command`,
+  `click.command`, `cobra.Command`), exported function signatures in index files
+- Identify database schemas — look for: migration files, ORM model definitions,
+  `CREATE TABLE` statements, schema files (`.prisma`, `schema.rb`, `models/`)
 - Trace primary data flows (request -> handler -> storage -> response)
 - Note external dependencies and integrations
 
 ### Step 3: Extract conventions
 
 - **Naming**: file naming, function naming, variable naming patterns
-- **Testing**: test framework, test file locations, test naming patterns
+- **Testing**: test framework, test file locations, test naming patterns —
+  look for: `*.test.*`, `*.spec.*`, `test_*.py`, files in `test/` or `__tests__/`
 - **Build/Deploy**: build commands, deploy scripts, CI/CD patterns
-- **Code style**: formatting, import ordering, comment conventions
+- **Code style**: formatting, import ordering, comment conventions — look for:
+  `.eslintrc*`, `.eslintrc.json`, `pyproject.toml` (ruff/black config),
+  `.prettierrc`, `rustfmt.toml`, import grouping in existing source files
+
+### Monorepo guidance
+
+If the project has multiple top-level packages or apps (e.g., a `packages/`,
+`apps/`, or `services/` directory with independent `package.json` / `pyproject.toml`
+files), treat each package as a separate chunk group:
+- Write chunks to `{brain_path}/chunks/extracted/project-{safe_project_name}-{package_name}/`
+- Also write a shared overview chunk at `project-{safe_project_name}/chunk-000-overview.md`
+  that summarises the monorepo layout, inter-package relationships, and shared tooling.
+
+### Re-onboarding
+
+Re-onboarding is triggered **manually** by the user saying "re-onboard this
+project" (or equivalent). It does not run automatically. When re-onboarding,
+follow the archive-then-replace pattern described in Step 4 below.
 
 ### Step 4: Ingest findings
 

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

@@ -21,6 +21,21 @@ of executing repetitive tool calls inline.
 - Bulk search across many terms
 - Any operation touching more than 5 files
 
+## When NOT to use batch
+
+If processing fewer than ~10 files, inline ingest is simpler and easier to
+debug — write a batch script only when the repetition would noticeably flood
+context or where a single script run is meaningfully faster.
+
+## Error recovery
+
+If a batch script crashes mid-way, do not re-index everything from scratch.
+Check which files were already indexed using the server's `search` or `stats`
+action, then resume from the first unprocessed file. The `stats` action returns
+the total indexed document count; `search` can confirm whether a specific file
+path is already in the index. Design batch scripts to skip files whose chunk IDs
+are already present in the index (check before writing).
+
 ## Why scripts over tool calls
 
 | Approach | Context cost | Speed | Reliability |
@@ -75,7 +90,9 @@ Or keep it for re-runs — the user can run it manually too.
 - Node.js scripts are fully cross-platform (same code on macOS/Linux/Windows)
 - Python scripts are fully cross-platform
 - Shell scripts need macOS/Linux + Windows variants — avoid if Node or Python available
-- Use `fetch()` (Node 18+) instead of `curl` in scripts — it's native and cross-platform
+- Use `fetch()` (Node 18+) instead of `curl` in scripts — it's native and cross-platform.
+  `fetch()` requires Node 18 or later. If running Node 16 or older, install `node-fetch`
+  (`npm install node-fetch`) and import it: `import fetch from 'node-fetch';`
 - Use `node:fs` and `node:path` — they handle platform differences
 
 ## Template: Node.js batch script
@@ -84,6 +101,9 @@ See wicked-brain:ingest for a complete example. The key structure:
 
 ```javascript
 #!/usr/bin/env node
+// Note: fetch() is built-in from Node 18+. For Node 16 or older, run:
+//   npm install node-fetch  and change the line below to:
+//   import fetch from 'node-fetch';
 import { ... } from "node:fs";
 import { ... } from "node:path";
 

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

@@ -69,6 +69,18 @@ Shell fallback:
 
 Focus on chunks NOT referenced by any wiki article.
 
+**Chunk prioritization:** When there are many uncovered chunks, process them in
+this order:
+1. Most recently modified (check file mtime or `authored_at` frontmatter field)
+2. Highest backlink count (use `{"action":"backlinks","params":{"id":"{chunk-path}"}}` — more backlinks = more referenced by other content)
+
+**Existing wiki articles:** For each existing wiki article, compare the
+`source_hashes` in its frontmatter against the current content hash of each
+source chunk (first 8 chars of the chunk body's SHA-256). If all hashes match,
+the source chunks are unchanged — skip re-compilation for that article. If any
+hash has changed, re-compile the article and update it in place (overwrite the
+file, update `authored_at` and `source_hashes`).
+
 ## Step 3: Read uncovered chunks
 
 Read uncovered chunks (frontmatter + body) to understand their content.

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

@@ -50,11 +50,19 @@ Check for these signals in order (first match wins):
 | `COPILOT_CLI` env var or `.github/` exists | Copilot CLI | `.github/copilot-instructions.md` |
 | `.cursor/` exists | Cursor | `.cursor/rules/wicked-brain.md` |
 | `.antigravity/` exists | Antigravity | `.antigravity/rules/wicked-brain.md` |
-| None | Fallback | `CLAUDE.md` |
+| None matched | Fallback | ask the user |
+
+If no signal matches, tell the user: "I couldn't detect your CLI automatically.
+Which agent config file should I write to?" Accept a user-specified path and
+write to that file directly.
 
 ### Step 3: Write config section
 
-Read the target config file. Find the `## wicked-brain` section (if it exists, replace it). If it doesn't exist, append it.
+Read the target config file. If a `## wicked-brain` section already exists,
+update it in place — replace from the `## wicked-brain` heading to the next
+`##`-level heading (or end of file) with the new content. Do NOT append a
+duplicate section. If no `## wicked-brain` section exists, append it at the
+end of the file.
 
 Write a section like this (adapt content to actual brain state):
 

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

@@ -76,11 +76,25 @@ inferences on content from `chunks/inferred/` — that would be inference-of-inf
 which causes confidence laundering (inferred content cites inferred content, making
 unreliable chains appear well-sourced).
 
+**Why this matters:** Each inference step introduces uncertainty. When you infer from
+already-inferred content, errors and assumptions compound silently across the chain.
+The result is chunks that sound authoritative but are actually several degrees removed
+from any real source. A `confidence: 0.6` chunk derived from another `confidence: 0.6`
+chunk is not `confidence: 0.6` — it is substantially less reliable, but the metadata
+won't show it. Only raw source material (extracted chunks, actual files) provides a
+trustworthy evidence base.
+
 - If you find relevant content in `chunks/inferred/`, you may note it as background
   context but do NOT cite it as a `source_chunk` or use it as evidence for new inferences.
 - Every entry in `source_chunks` in your output MUST start with `chunks/extracted/`.
 - If a gap cannot be filled using only extracted chunks as evidence, skip it.
 
+**Bootstrapping caveat:** If the brain contains no `chunks/extracted/` files at all
+(e.g., very early stage with only inferred chunks), do NOT proceed silently. Stop and
+inform the user: "The brain has no extracted source chunks — enhancement requires raw
+source material. Run wicked-brain:ingest to add source files first." This prevents
+a silent chain of inferences with no grounding.
+
 ## Step 3: Write inferred chunks
 
 For each gap, write a new chunk to `{brain_path}/chunks/inferred/{topic}/chunk-NNN.md`:

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

@@ -38,7 +38,19 @@ Ask these questions (provide defaults):
    - Default (Windows): `%USERPROFILE%\.wicked-brain`
 2. "What should this brain be called?" — Default: directory name
 
-### Step 2: Create directory structure
+### Step 2: Dispatch onboard agent (fire and continue)
+
+Immediately dispatch the `wicked-brain-onboard` agent for the current project — don't wait for Steps 3–6 to finish first.
+
+Pass it:
+- `brain_path`: the path confirmed in Step 1
+- `project_path`: the current working directory
+
+**Sequencing rationale:** Onboard starts with a read-only scanning phase (Glob, Grep, Read across the project). That scanning takes meaningful time. Steps 3–6 below are fast — just creating a handful of files and directories. They will complete well before onboard finishes scanning and reaches its write phase (where it needs `brain_path` dirs to exist). So it is safe to fire onboard now and proceed immediately with Steps 3–6; the brain dirs will be in place long before onboard needs them.
+
+Continue with Steps 3–6 immediately after dispatching.
+
+### Step 3: Create directory structure
 
 Use your native Write/mkdir tools to create these directories and files.
 
@@ -61,7 +73,7 @@ mkdir -p {brain_path}/raw {brain_path}/chunks/extracted {brain_path}/chunks/infe
 New-Item -ItemType Directory -Force -Path "{brain_path}\raw","{brain_path}\chunks\extracted","{brain_path}\chunks\inferred","{brain_path}\wiki\concepts","{brain_path}\wiki\topics","{brain_path}\_meta"
 ```
 
-### Step 3: Write brain.json
+### Step 4: Write brain.json
 
 Write to `{brain_path}/brain.json`:
 ```json
@@ -76,7 +88,7 @@ Write to `{brain_path}/brain.json`:
 
 Where `{id}` is the directory name (lowercase, hyphens for spaces) and `{name}` is what the user provided.
 
-### Step 4: Write config
+### Step 5: Write config
 
 Write to `{brain_path}/_meta/config.json`:
 ```json
@@ -87,7 +99,7 @@ Write to `{brain_path}/_meta/config.json`:
 }
 ```
 
-### Step 5: Initialize the event log
+### Step 6: Initialize the event log
 
 Use your Write tool to create an empty file at `{brain_path}/_meta/log.jsonl`.
 
@@ -101,10 +113,7 @@ touch {brain_path}/_meta/log.jsonl
 New-Item -ItemType File -Force -Path "{brain_path}\_meta\log.jsonl"
 ```
 
-### Step 6: Confirm
+### Step 7: Confirm
 
 Tell the user:
-"Brain initialized at `{brain_path}`. You can now:
-- `wicked-brain:ingest` to add source files
-- `wicked-brain:search` to search content
-- `wicked-brain:status` to check brain health"
+"Brain initialized at `{brain_path}`. Onboarding agent is running in the background to index the project."

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

@@ -46,7 +46,8 @@ Use your Grep tool (preferred):
 
 Shell fallback:
 - macOS/Linux: `grep -roh '\[\[[^]]*\]\]' {brain_path}/wiki/ {brain_path}/chunks/ 2>/dev/null | sort -u`
-- Windows: `findstr /s /r "\[\[" "{brain_path}\wiki\*.md" "{brain_path}\chunks\*.md" 2>nul`
+- Windows (findstr): `findstr /s /r "\[\[" "{brain_path}\wiki\*.md" "{brain_path}\chunks\*.md" 2>nul`
+- Windows (PowerShell preferred): `Get-ChildItem -Recurse -Path "{brain_path}\wiki","{brain_path}\chunks" -Filter "*.md" | Select-String -Pattern '\[\[' | Select-Object Path,LineNumber,Line`
 
 For each link, use the Read tool to check if the target file exists.
 
@@ -63,7 +64,8 @@ Shell fallback:
 - Windows:
   ```powershell
   Get-ChildItem -Recurse -Filter "chunk-*.md" "{brain_path}\chunks"
-  findstr /s /m "chunk-" "{brain_path}\wiki\*.md" 2>nul
+  findstr /s /r /m "chunk-" "{brain_path}\wiki\*.md" 2>nul
+  # PowerShell preferred: Get-ChildItem -Recurse -Path "{brain_path}\wiki" -Filter "*.md" | Select-String -Pattern "chunk-" -List | Select-Object -ExpandProperty Path
   ```
 
 ### Stale entries
@@ -103,5 +105,15 @@ For each issue found:
 - **message**: what's wrong
 - **fix**: suggested fix (or "auto-fixed" if you fixed it)
 
+Auto-fix items include (apply silently, then report as "auto-fixed"):
+- Missing frontmatter fields: fill with safe defaults (e.g., `confidence: low`, `indexed_at: now`)
+- Orphaned index entries: remove entries from the SQLite index whose source file no longer exists
+
+Manual review required (flag as error or warning — do NOT auto-fix):
+- Factual contradictions between articles
+- Duplicate content covering the same concept in different files
+- Broken wikilinks where the correct target is ambiguous
+- Stale wiki articles where the underlying chunk content has changed substantially
+
 Auto-fix broken links and missing fields where possible. Report everything else.
 ```

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

@@ -26,10 +26,18 @@ For the brain path default:
 
 - `curl` works on macOS, Linux, and Windows 10+
 - File paths must be absolute
-- On Windows, use forward slashes in JSON: `"file":"C:/Users/me/project/file.ts"`
+- On Windows, use forward slashes in file URIs passed to the server. Most LSP
+  servers accept `file:///C:/Users/me/project/file.ts` (forward slashes, three
+  leading slashes). Do not use backslashes in URIs even on Windows.
 - Language server install commands assume the package manager is in PATH
 - For Windows PowerShell without npm/pip in PATH, guide the user to install manually
 
+**Debugging LSP issues:** If an LSP server appears to hang or returns no
+results on the first request, it may require a workspace initialization
+sequence before accepting queries. Try calling `lsp-health` first — the server
+layer sends an `initialize` handshake on first contact. If hang persists, check
+whether the language server process is running and review its stderr logs.
+
 ## Config
 
 Read `_meta/config.json` for brain path and server port.

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

@@ -99,6 +99,44 @@ indexed_at: "{ISO 8601 timestamp}"
 {memory content}
 ```
 
+#### Tier definitions
+
+- **working**: Active, session-specific context. Expires quickly (hours to days). Use for in-progress decisions, temporary notes, and things only relevant to the current task.
+- **episodic**: Specific events or decisions from past sessions. Medium longevity. Use for "we decided X on date Y" or "this happened in project Z".
+- **semantic**: Generalized patterns and facts extracted from experience. Permanent by default. Use for stable conventions, recurring patterns, and distilled knowledge that transcends any single session.
+
+New memories always start at `tier: working`. Consolidation (wicked-brain:consolidate) promotes them to `episodic` or `semantic` based on access frequency and age.
+
+#### Complete example
+
+```yaml
+---
+type: decision
+tier: working
+confidence: 0.9
+importance: 7
+ttl_days: null
+session_origin: "2026-04-07T14:23:00Z"
+contains:
+  - jwt
+  - json-web-token
+  - authentication
+  - auth
+  - tokens
+  - session
+  - security
+  - expiry
+  - 15-minutes
+  - access-control
+entities:
+  people: []
+  systems: ["auth-service", "api-gateway"]
+indexed_at: "2026-04-07T14:23:01Z"
+---
+
+Decided to use JWT with a 15-minute expiry for the auth-service API. Refresh tokens stored in HttpOnly cookies with 7-day TTL. Rationale: short access token lifetime limits blast radius if a token is leaked.
+```
+
 The server's file watcher will auto-index this file.
 
 ### Step 6: Log the store event

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

@@ -44,7 +44,10 @@ Example:
 ### Check learned synonyms first
 
 Before generating synonyms, check if `{brain_path}/_meta/synonyms.json` exists.
-If it does, read it. Format:
+If it does, read it. If it does not exist, skip synonym expansion and proceed
+with LLM-generated synonyms only — `synonyms.json` is auto-generated by
+`wicked-brain:retag` and will be absent on fresh brains.
+Format:
 
 ```json
 {
@@ -89,6 +92,9 @@ curl -s -X POST http://localhost:{port}/api \
 
 Pass a session_id with every search call. This enables access tracking for
 consolidation. Use a consistent session_id for the entire conversation.
+`session_id` is any string that identifies the current conversation or session
+(e.g., a timestamp like `"1712345678"` or a UUID like `"a1b2-c3d4"`). It is
+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
@@ -97,11 +103,20 @@ curl -s -X POST http://localhost:{port}/api \
   -d '{"action":"search","params":{"query":"{term}","limit":10,"session_id":"{session_id}","since":"{iso8601_date}"}}'
 ```
 
-Also search with grep for exact phrases:
+Also search with grep for exact phrases (use your Grep tool when available —
+it is cross-platform and preferred over shell commands):
+
+macOS/Linux shell fallback:
 ```bash
 grep -rl "{key_terms}" {brain_path}/chunks/ {brain_path}/wiki/ 2>/dev/null | head -10
 ```
 
+Windows PowerShell fallback:
+```powershell
+Get-ChildItem -Recurse -Path "{brain_path}\chunks","{brain_path}\wiki" -Filter "*.md" |
+  Select-String -Pattern "{key_terms}" -List | Select-Object -First 10 -ExpandProperty Path
+```
+
 ### Log synonym effectiveness
 
 For each synonym-expanded search term, log whether it produced results:

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

@@ -44,11 +44,19 @@ Body content here...
 
 Split the file on the second `---` line. Everything before is frontmatter, everything after is body.
 
+If the frontmatter delimiters are missing or the YAML is unparseable, do not
+fail — return the raw file content with a warning: "Note: frontmatter missing
+or unparseable. Showing raw content." Continue with empty frontmatter and the
+full file text as body.
+
 ### Step 3: Count stats
 
 - **word_count**: split body on whitespace, count words
 - **link_count**: count occurrences of `[[` in the body (each `[[...]]` is one link)
-- **related**: extract all `[[target]]` and `[[brain::target]]` patterns
+- **related**: extract all wikilink targets from the body. Wikilink formats:
+  - `[[path/to/chunk]]` — path is relative to the brain root
+  - `[[label|path/to/chunk]]` — display label with explicit path (label is shown to the reader; path is the target)
+  - `[[brain-id::path/to/chunk]]` — cross-brain link
 
 ### Step 4: Return at requested depth
 

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

@@ -55,6 +55,12 @@ For each existing tag, look it up in the synonym map. Learned expansions take
 priority over LLM-generated ones. Supplement with LLM expansions for tags
 not in the map.
 
+**Fallback behavior:** If `synonyms.json` is missing or cannot be parsed (malformed
+JSON, permission error, etc.), do not fail. Simply skip the synonym-map lookup for
+that document and proceed with LLM-only expansion. Never abort the retag operation
+because of a missing or broken synonyms file — it is an optional accelerant, not a
+hard dependency.
+
 - For each existing tag, add 1-3 synonyms or related terms
 - Extract additional keywords from the content summary
 - Apply the same expansion rules as wicked-brain:memory store:
@@ -77,3 +83,14 @@ Report:
 - Files under threshold
 - Files updated (or would-be-updated in dry run)
 - Sample of expanded tags for verification
+
+## Performance Guidance
+
+For brains with 1000+ chunks, process files in batches of 100 rather than all at once.
+After each batch, report progress (e.g., "Updated 100/1247 files...") so the user can
+see the operation is running.
+
+The operation is safe to interrupt and resume: retag only updates existing chunks in
+place and never deletes data. On resume, Step 2's tag-count filter will naturally skip
+files that were already expanded in a previous run (they will meet the `min_tags`
+threshold). No state file or checkpoint is needed.

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

@@ -56,7 +56,13 @@ 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).
+Launch one subagent per accessible brain using parallel dispatch:
+
+- **Claude Code:** use the Agent tool, launching all subagents in a single message so they run concurrently.
+- **Other CLIs with subagent support:** use the CLI's native parallel dispatch mechanism (e.g., Gemini CLI's parallel tool calls).
+- **No subagent support:** run each brain search sequentially and collect results before merging.
+
+Each subagent call passes the brain-specific instructions below.
 
 Each search subagent receives these instructions:
 

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

@@ -36,10 +36,10 @@ For the brain path default:
      -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 the health check succeeds, the server is running. Report the status.
-
-4. If connection refused:
+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:
@@ -51,7 +51,10 @@ For the brain path default:
       ```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`
+      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:

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

@@ -46,7 +46,7 @@ curl -s -X POST http://localhost:{port}/api \
   -d '{"action":"stats","params":{}}'
 ```
 
-If connection refused, start the server (see wicked-brain:server skill), then retry.
+If connection refused, invoke the `wicked-brain:server` skill to start the server, then retry.
 
 ### Step 3: Return at requested depth
 
@@ -67,7 +67,8 @@ Check parent/link accessibility by using the Read tool on
 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)
-- Show topic distribution for the last 7 days by searching with a `since` filter:
+- 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" \

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

@@ -103,6 +103,11 @@ For each pid file found:
 
 ### Step 6: Verify migration
 
+`npx wicked-brain-server` automatically applies all pending schema migrations on
+startup — users do not need to run a separate migration command. Each new server
+version may add tables or columns to the SQLite database; migrations are numbered,
+run in order, and are idempotent (safe to re-run).
+
 After server restart, verify the server started successfully and migrations ran:
 
 ```bash
@@ -111,9 +116,19 @@ curl -s -X POST http://localhost:{port}/api \
   -d '{"action":"health"}'
 ```
 
-If health check fails, check server logs for migration errors. The server runs
-numbered schema migrations on startup — each new version may add tables or columns
-to the SQLite database. Migrations are automatic and idempotent.
+If the health check fails, the migration may have errored. To diagnose:
+1. Check whether the server process is actually running:
+   - Read `{brain_path}/_meta/server.pid` to get the PID.
+   - macOS/Linux: `ps -p {pid}` — if the process is absent, the server crashed on startup.
+   - Windows: `tasklist /FI "PID eq {pid}"`
+2. The server logs migration errors to **stderr**. If you launched it in the
+   foreground, the error will be visible in the terminal. If launched in the
+   background, redirect stderr to a file:
+   `npx wicked-brain-server --brain "{brain_path}" --port {port} 2>{brain_path}/_meta/server-error.log`
+   then read `{brain_path}/_meta/server-error.log`.
+3. Common causes: the SQLite file is locked by another process, or the database
+   file is corrupted. Stop all server instances and retry, or delete `.brain.db`
+   to force a clean rebuild (data is re-indexed from source files on next ingest).
 
 ### Step 7: Report