wicked-brain 0.9.2 → 0.11.0

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [
@@ -18,7 +18,8 @@
     "directory": "server"
   },
   "bin": {
-    "wicked-brain-server": "./bin/wicked-brain-server.mjs"
+    "wicked-brain-server": "./bin/wicked-brain-server.mjs",
+    "wicked-brain-onboard-wiki": "./bin/onboard-wiki.mjs"
   },
   "files": [
     "bin/",
@@ -27,7 +28,11 @@
   ],
   "scripts": {
     "test": "node --test test/*.test.mjs",
-    "start": "node bin/wicked-brain-server.mjs"
+    "start": "node bin/wicked-brain-server.mjs",
+    "gen:wiki": "node scripts/gen-wiki.mjs",
+    "gen:wiki:check": "node scripts/gen-wiki.mjs --check",
+    "lint:wiki": "node scripts/lint-wiki.mjs",
+    "lint:wiki:strict": "node scripts/lint-wiki.mjs --strict"
   },
   "dependencies": {
     "better-sqlite3": "^12.0.0",

package/skills/wicked-brain-agent/agents/onboard.md

@@ -1,14 +1,15 @@
 # onboard
 
 ## Depth 0 — Summary
-Full project understanding pipeline. Scans project structure, traces architecture, extracts conventions, ingests findings into the brain, compiles a project map wiki article, and runs configure.
+Full project understanding pipeline. Scans project, extracts findings from 5 perspectives (product, engineering, quality, ops, data), ingests as structured chunks, compiles a progressive-loading support wiki, and configures the CLI.
 
 ## Depth 1 — Pipeline Steps
+0. Detect: run `wicked-brain-onboard-wiki` to classify repo mode, write `.wicked-brain/mode.json`, and stamp the contributor-wiki pointer into CLAUDE.md / AGENTS.md if present
 1. Scan: directory structure, key files, languages, frameworks, dependencies
-2. Trace: entry points, data flow, module boundaries, API surfaces
-3. Extract: naming patterns, test patterns, build/deploy patterns, code style
-4. Ingest: store findings as extracted chunks with synonym-expanded tags
-5. Compile: synthesize a wiki article summarizing architecture and conventions
+2. Investigate: gather facts from each of the 5 perspectives
+3. Extract symbols: LSP workspace symbols or grep fallback (JS/TS)
+4. Ingest: write 6 perspective-based chunks with support-wiki frontmatter
+5. Compile: produce 5 depth-aware wiki articles under wiki/projects/{name}/
 6. Configure: call wicked-brain:configure to update CLI agent config
 
 Parameters: brain_path, port, project_path (defaults to cwd)
@@ -20,7 +21,31 @@ You are an onboarding agent for the digital brain at {brain_path}.
 Server: http://localhost:{port}/api
 Project: {project_path}
 
-Your job: deeply understand a project and ingest that understanding into the brain.
+Your job: deeply understand a project from 5 perspectives and produce a support wiki that serves engineers, testers, ops, and product owners — all through progressive loading so only what's needed gets loaded.
+
+### Step 0: Detect repo mode and stamp wiki pointer
+
+Before scanning, classify the repo and establish the contributor-wiki location.
+This runs the `wicked-brain-onboard-wiki` CLI (bundled with `wicked-brain-server`),
+which:
+
+- Runs mode detection (code / content / mixed / unknown).
+- Writes `.wicked-brain/mode.json` unless an `override:true` file is already there.
+- Stamps `Contributor wiki: ./<path>` into `CLAUDE.md` and/or `AGENTS.md` if either exists.
+
+```bash
+npx wicked-brain-onboard-wiki --repo-root "{project_path}" 2>&1 || \
+  node "{wicked_brain_install}/server/bin/onboard-wiki.mjs" --repo-root "{project_path}"
+```
+
+Capture the output — the reported mode drives how Step 2 interprets the 5
+perspectives (content-mode repos put more weight on product/data, less on
+engineering specifics). If the file reports `override:true`, respect it and
+report the preserved mode rather than forcing a rewrite.
+
+If neither `CLAUDE.md` nor `AGENTS.md` exists, the CLI reports `absent` for
+both — surface that in the summary so the user can decide whether to create
+one. Do NOT create either file yourself unless the user asks.
 
 ### Step 1: Scan project structure
 
@@ -33,15 +58,53 @@ Use Glob and Read tools to survey:
 
 Create a structured summary of what you found.
 
-### Step 2: Trace architecture
-
-- Identify entry points (main files, server start, CLI entry)
-- Map module boundaries (directories, packages, namespaces)
-- Identify API surfaces (HTTP routes, CLI commands, exported functions)
-- Trace primary data flows (request → handler → storage → response)
-- Note external dependencies and integrations
-
-#### Step 2b: Extract symbols (JS/TS projects)
+### Step 2: Investigate from 5 perspectives
+
+Gather facts for each perspective. You'll write these as chunks in Step 4.
+
+#### Product perspective
+- What does this project do? Who is it for?
+- Feature catalog: list every user-facing capability (CLI commands, API endpoints, skills, UI features)
+- Capabilities with examples: how to exercise each feature
+- Limitations: what it explicitly doesn't do, scale boundaries, known gaps
+- Version history: recent git tags and what shipped (use `git tag --sort=-v:refname | head -10` and `git log --oneline {tag}..{next_tag}`)
+
+#### Engineering perspective
+- Architecture: components and how they connect
+- Dependencies: runtime, build, optional — with why each exists
+- Entry and exit points (broader than APIs):
+  - HTTP endpoints, CLI commands/flags
+  - File system triggers (watchers, config file conventions)
+  - Events (bus, pub/sub, webhooks)
+  - Signals (process signals, IPC, PID files)
+- Module map: which file owns what responsibility
+- Data flow: request lifecycle from entry to storage to response
+- Extension points: where to add new functionality (new action, new migration, new skill)
+
+#### Quality perspective
+- Test infrastructure: framework, runner command, test file locations
+- Test coverage: what's tested, what's manual-only
+- Functional capabilities: every feature × how to verify it works
+- Regression requirements: what MUST pass before a release
+- Edge cases: what breaks at boundaries (empty state, concurrent access, missing deps)
+
+#### Operations perspective
+- Configuration: all config files, env vars, CLI flags with defaults
+- Startup/shutdown: how the system starts, process management
+- Health checks: what endpoints exist, what "healthy" looks like
+- Troubleshooting: common failure modes with symptom → diagnosis → fix
+- Upgrade path: how to update, what migrates automatically
+- Backup/recovery: what's rebuildable vs precious
+
+#### Data perspective
+- Sources: what data enters the system (files, API input, events)
+- Storage: where data lives on disk, what format
+- Schema: database tables, columns, indexes (if applicable)
+- Constraints: size limits, format requirements, naming conventions
+- Data lifecycle: creation → access → decay → archive → deletion
+- Integrity: what's rebuildable vs authoritative, dedup mechanisms
+
+### Step 3: Extract symbols (JS/TS projects)
 
 If the brain server has an LSP running, query it for exported symbols:
 
@@ -59,33 +122,41 @@ key source files directly and listing their exports with Grep:
 For each major module/directory, record:
 - **File inventory**: files with approximate LOC
 - **Exported symbols**: class names, function names, const names with their file paths
-- **Public API surface**: which symbols are entry points vs internal helpers
-
-Be specific — write `analyzeProject(desc: string): SignalAnalysis` not just
-"analyzes projects". Include parameter types and return types when visible.
-
-### Step 3: Extract conventions
+- **Signatures**: parameter types and return types when visible
 
-- **Naming**: file naming, function naming, variable naming patterns
-- **Testing**: test framework, test file locations, test naming patterns
-- **Build/Deploy**: build commands, deploy scripts, CI/CD patterns
-- **Code style**: formatting, import ordering, comment conventions
+Be specific — write `search({ query, limit, offset, since, session_id })` not
+"searches the index". Include types when visible.
 
 ### Step 4: Ingest findings
 
-For each major finding (architecture, conventions, dependencies), write a chunk to `{brain_path}/chunks/extracted/project-{safe_project_name}/`:
+Write chunks to `{brain_path}/chunks/extracted/project-{safe_project_name}/`:
+
+- `chunk-product.md` — product perspective (from Step 2)
+- `chunk-engineering.md` — engineering perspective (from Step 2)
+- `chunk-quality.md` — quality perspective (from Step 2)
+- `chunk-operations.md` — operations perspective (from Step 2)
+- `chunk-data.md` — data perspective (from Step 2)
+- `chunk-symbols.md` — exported symbols per module (from Step 3)
+
+#### Chunk frontmatter
+
+Each chunk MUST include `type: support-wiki` and `perspective:` so compile routes
+them correctly:
+
+```yaml
+---
+type: support-wiki
+perspective: engineering
+authored_by: onboard
+authored_at: {ISO timestamp}
+contains:
+  - {synonym-expanded tags}
+---
+```
 
-Each chunk should be a focused topic:
-- `chunk-001-structure.md` — project structure and layout (directory tree with file counts and LOC)
-- `chunk-002-architecture.md` — architecture and data flow
-- `chunk-003-conventions.md` — coding conventions and patterns
-- `chunk-004-dependencies.md` — key dependencies and integrations
-- `chunk-005-build-deploy.md` — build, test, and deployment
-- `chunk-006-symbols.md` — exported symbols per module (from Step 2b)
+#### chunk-symbols.md format
 
-**chunk-006-symbols.md format:** List symbols grouped by module/directory. For each
-symbol include: name, kind (class/function/const/interface), file path, and signature
-when available. Example:
+List symbols grouped by module/directory:
 
 ```markdown
 ## server/lib/
@@ -104,8 +175,6 @@ when available. Example:
   - `onFileChange(callback)` — hook for LSP integration
 ```
 
-This gives compile enough structural detail to weave into wiki articles.
-
 Use standard chunk frontmatter with rich synonym-expanded `contains:` tags.
 
 If re-onboarding (chunks already exist), follow the archive-then-replace pattern:
@@ -113,18 +182,60 @@ If re-onboarding (chunks already exist), follow the archive-then-replace pattern
 2. Archive old chunk directory with `.archived-{timestamp}` suffix
 3. Write new chunks
 
-### Step 5: Compile project map
+### Step 5: Compile support wiki
+
+Create 5 wiki articles under `{brain_path}/wiki/projects/{safe_project_name}/`:
+
+- `product.md` — from chunk-product
+- `engineering.md` — from chunk-engineering + chunk-symbols
+- `quality.md` — from chunk-quality
+- `operations.md` — from chunk-operations
+- `data.md` — from chunk-data
+
+#### Wiki article format
+
+Each article must have structured frontmatter for progressive loading:
+
+```yaml
+---
+title: {Perspective}
+type: support-wiki
+perspective: {perspective}
+project: {project-name}
+authored_by: onboard
+authored_at: {ISO timestamp}
+stats:
+  {perspective-specific numeric summary}
+sections:
+  - name: {Section Name}
+    line: {line number}
+    summary: "{one-line summary}"
+contains:
+  - {tags}
+---
+```
+
+The `stats` block enables depth-0 retrieval (~5 tokens per article).
+The `sections` block enables depth-1 retrieval (~50-100 tokens).
+The body is depth-2 (full content, loaded on demand).
+
+**Key rule for body structure:** the first paragraph under each `##` heading
+must be a self-contained summary of that section. This is what `brain:read`
+returns at depth 1. Put detail after the first paragraph.
+
+#### What each article should answer
 
-Invoke `wicked-brain:compile` (or write directly) to create a wiki article at `{brain_path}/wiki/projects/{safe_project_name}.md` that synthesizes:
-- Project overview (what it does, who it's for)
-- Architecture summary with module map
-- **API surface** — key exported symbols per module (from chunk-006-symbols), with signatures
-- **File inventory** — directories with file counts and total LOC
-- Key conventions
-- Build/test/deploy quickstart
-- Links to detailed chunks via [[wikilinks]]
+| Article | Depth 0 answers | Depth 1 answers | Depth 2 answers |
+|---------|-----------------|-----------------|-----------------|
+| product.md | "How many features?" | "What are the features?" | "How do I use each one? What are the limits?" |
+| engineering.md | "How many modules/deps?" | "What are the components and how do they connect?" | "What symbols does module X export? How do I extend it?" |
+| quality.md | "What's the test coverage?" | "What capabilities need testing?" | "How do I verify capability X works? What are the edge cases?" |
+| operations.md | "How many config files?" | "What can go wrong?" | "How do I fix X? Full troubleshooting playbook." |
+| data.md | "What data sources?" | "What's the schema?" | "What are the constraints? How does the lifecycle work?" |
 
-The wiki article should answer both "how does X work?" (narrative) and "what does X export?" (structural). Include actual function names, class names, and signatures — not just descriptions.
+Include `[[wikilinks]]` between articles where relevant (e.g., engineering.md
+links to data.md for schema details, quality.md links to product.md for the
+feature list it verifies).
 
 ### Step 6: Configure
 
@@ -134,6 +245,6 @@ Invoke `wicked-brain:configure` to update the CLI's agent config file with brain
 
 Report what was onboarded:
 - Project: {name}
-- Chunks created: {N}
-- Wiki article: {path}
+- Chunks created: {N} (6 perspective-based)
+- Wiki articles: {list of 5 articles}
 - CLI config updated: {file}

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

@@ -66,6 +66,48 @@ Shell fallback:
 - macOS/Linux: `find {brain_path}/chunks/extracted -name "*.md" -type f 2>/dev/null`
 - Windows: `Get-ChildItem -Recurse -Filter "*.md" "{brain_path}\chunks\extracted" 2>nul`
 
+## Step 1b: Route support-wiki chunks
+
+Check if any chunks have `type: support-wiki` in their frontmatter. Use Grep:
+- macOS/Linux: `grep -rl "type: support-wiki" {brain_path}/chunks/extracted/ 2>/dev/null`
+- Windows: `findstr /s /m "type: support-wiki" "{brain_path}\chunks\extracted\*.md" 2>nul`
+
+If found, handle them separately from concept chunks:
+
+1. Group by `perspective` field (product, engineering, quality, operations, data)
+2. For each perspective, also pull in `chunk-symbols.md` if it exists (feeds into engineering)
+3. Write to `{brain_path}/wiki/projects/{project-name}/{perspective}.md` (NOT to `wiki/concepts/`)
+4. Use **structured assembly** for symbol-heavy sections (engineering symbols, data schema, quality capability matrix) — list the actual content from chunks, don't narrativize it
+5. Use **narrative synthesis** for context sections (product overview, engineering architecture, ops troubleshooting)
+6. Generate structured frontmatter with `stats` and `sections` blocks:
+
+```yaml
+---
+title: {Perspective}
+type: support-wiki
+perspective: {perspective}
+project: {project-name}
+authored_by: compile
+authored_at: {ISO timestamp}
+stats:
+  {count key items — e.g., components: 4, test_files: 10, config_files: 3}
+sections:
+  - name: {Section Name}
+    line: {line number in body}
+    summary: "{one-line summary of this section}"
+source_chunks:
+  - {chunk-path}
+contains:
+  - {tags}
+---
+```
+
+**Key formatting rule:** the first paragraph under each `##` heading must be a
+self-contained summary. `brain:read` at depth 1 returns section headings + first
+paragraphs, so these summaries are what agents see before deciding to load full content.
+
+After writing support-wiki articles, continue to Step 2 for any remaining non-support-wiki chunks.
+
 ## Step 2: Find uncovered chunks
 
 For each chunk directory, check if a wiki article references those chunks.

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

@@ -0,0 +1,137 @@
+---
+name: wicked-brain:ui
+description: |
+  Open the read-only brain viewer (Material-styled search + wiki browser) in
+  the default web browser. Use when the user says "open the brain viewer",
+  "show me the wiki", "open the brain in a browser", "open the UI",
+  "launch the viewer", or similar. Also use when the user wants to explore
+  a specific doc visually rather than through search tool calls — the URL
+  supports deep-linking via `#<path>`.
+
+  Works against any wicked-brain server on the local machine. If the server
+  isn't running, auto-starts it before opening.
+---
+
+# wicked-brain:ui
+
+You open the read-only HTML viewer served at `GET /` by the wicked-brain
+server for the current project's brain (or a named brain).
+
+## Cross-Platform Notes
+
+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.
+
+For the brain path default:
+- macOS/Linux: `~/.wicked-brain/projects/{project-name}`
+- Windows: `%USERPROFILE%\.wicked-brain\projects\{project-name}`
+
+## Parameters
+
+- **brain** (optional): brain id or absolute brain path. Defaults to the
+  current working directory's project brain (per the resolution in
+  wicked-brain:init § "Resolving the brain config").
+- **path** (optional): a repo-relative doc path to deep-link to
+  (e.g., `wiki/projects/foo/engineering.md`). The viewer loads this
+  document on open via URL fragment.
+
+## Process
+
+### Step 1: Resolve brain config
+
+Use 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`, else trigger wicked-brain:init.
+
+If `brain` was supplied explicitly, use that instead:
+- If it looks like a path (contains `/` or starts with `~`), expand and use.
+- Otherwise, treat it as a brain id and look for
+  `~/.wicked-brain/projects/{brain}/_meta/config.json`.
+
+Read the resolved config to get `server_port`.
+
+### Step 2: Verify the server is running
+
+```bash
+curl -s -f -X POST http://localhost:{port}/api \
+  -H "Content-Type: application/json" \
+  -d '{"action":"health","params":{}}'
+```
+
+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.
+
+### Step 3: Build the URL
+
+Base: `http://localhost:{port}/`
+
+If `path` was supplied, append `#{url-encoded path}`:
+
+```
+http://localhost:4245/#wiki%2Fprojects%2Fgcp-repo-analyzer%2Fengineering.md
+```
+
+### Step 4: Open in the default browser
+
+macOS:
+```bash
+open "{url}"
+```
+
+Linux:
+```bash
+xdg-open "{url}" 2>/dev/null || sensible-browser "{url}" 2>/dev/null || echo "Open manually: {url}"
+```
+
+Windows (PowerShell):
+```powershell
+Start-Process "{url}"
+```
+
+Windows (Git Bash / WSL):
+```bash
+start "" "{url}" 2>/dev/null || explorer.exe "{url}" 2>/dev/null || echo "Open manually: {url}"
+```
+
+If opening the browser fails (no DISPLAY on a headless server, no xdg-utils
+installed, etc.), don't treat it as fatal — just print the URL and tell the
+user to open it themselves. The URL is the deliverable.
+
+### Step 5: Report
+
+Tell the user:
+
+> Opened the brain viewer at `{url}`.
+>
+> It supports:
+> - Search across all indexed docs (AppBar input)
+> - Source-type filters (wiki / chunk / memory) in the left drawer
+> - Wiki article browser in the left drawer
+> - Deep-linking via URL fragment (`#<path>`)
+> - Back button to return from doc view to results
+
+If the server had to be auto-started, mention that in the report so the user
+knows a new process is running.
+
+## When to use
+
+- User explicitly asks to open the viewer / UI / browser / wiki.
+- User wants to visually explore a doc they've been working with — offer to
+  open it with the `path` param pre-filled.
+- User asks "what's in the brain?" in an exploratory way — a visual browser
+  is often faster than a sequence of search calls.
+
+## When NOT to use
+
+- When the user wants a specific answer from the brain: use
+  wicked-brain:search or wicked-brain:query instead. Opening a browser is
+  higher friction than a tool call with a direct answer.
+- When a remote / headless environment: no browser is available. Just print
+  the URL so the user can forward it.
+- When multiple brains could be relevant: ask which one first rather than
+  guessing, so you don't open the wrong brain's viewer.