monomind 1.16.6 → 1.16.8

package/packages/@monomind/cli/.claude/commands/monitoring/agents.md

@@ -0,0 +1,71 @@
+---
+name: monitoring:agents
+---
+
+# status agents
+
+Show detailed agent status — ID, type, current task, uptime, and success rate for all running agents.
+
+## Usage
+
+```bash
+npx monomind status agents [options]
+```
+
+## Options
+
+| Flag | Type | Description |
+|---|---|---|
+| `--format` | string | Output format: `json` |
+
+## Examples
+
+```bash
+# Show all agents
+npx monomind status agents
+
+# JSON output
+npx monomind status agents --format json
+```
+
+## Output Columns
+
+| Column | Description |
+|---|---|
+| ID | Agent identifier |
+| Type | Agent type (coder, reviewer, tester, etc.) |
+| Status | `healthy` / `degraded` / `stopped` |
+| Current Task | Task the agent is executing (or `-`) |
+| Uptime | How long the agent has been running |
+| Success | Task success rate (%) |
+
+## Related Commands
+
+```bash
+# Quick agent count overview (in main status)
+npx monomind status
+
+# Agent performance metrics by type
+npx monomind agent metrics
+
+# Agent health check
+npx monomind agent health
+
+# List all agents
+npx monomind agent list
+```
+
+## MCP Tool
+
+```javascript
+mcp__monomind__agent_list({
+  includeMetrics: true,
+  status: "all"
+})
+```
+
+## See Also
+
+- `status` — full system status including agents
+- `agent metrics` — performance metrics over time
+- `agent health` — per-agent health checks

package/packages/@monomind/cli/.claude/commands/monitoring/status.md

@@ -0,0 +1,108 @@
+---
+name: monitoring:status
+---
+
+# status
+
+Show system status — swarm health, agents, tasks, memory, and MCP server. The primary monitoring command.
+
+## Usage
+
+```bash
+npx monomind status [options]
+npx monomind status <subcommand>
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--watch` | `-w` | boolean | `false` | Continuously refresh status (live view) |
+| `--interval` | `-i` | number | `2` | Refresh interval in seconds (watch mode) |
+| `--health-check` | — | boolean | `false` | Run structured health checks and exit |
+| `--format` | — | string | — | Output format: `json` |
+
+## Subcommands
+
+| Subcommand | Description |
+|---|---|
+| `status agents` | Detailed agent status table (ID, type, current task, uptime, success rate) |
+| `status tasks` | Detailed task status table (ID, type, priority, agent, progress) |
+| `status memory` | Memory backend stats (entries, size, HNSW, performance metrics) |
+
+## Examples
+
+```bash
+# One-shot status snapshot
+npx monomind status
+
+# Live watch mode (refreshes every 2s)
+npx monomind status --watch
+
+# Watch with custom interval
+npx monomind status --watch -i 5
+
+# Health checks with pass/warn/fail output
+npx monomind status --health-check
+
+# JSON output for scripting
+npx monomind status --format json
+
+# Detailed agent table
+npx monomind status agents
+
+# Detailed task table
+npx monomind status tasks
+
+# Memory backend details
+npx monomind status memory
+```
+
+## Status Display Sections
+
+- **Swarm** — ID, topology, health (`healthy` / `degraded` / `stopped`), uptime
+- **Agents** — active / idle / total counts
+- **Tasks** — pending / running / completed / failed / total
+- **Memory** — backend, entries, size, search time, cache hit rate
+- **MCP Server** — running state, transport, port
+- **Performance** — CPU usage, memory usage, vector search speed
+
+## Health Check Mode
+
+`--health-check` runs structured checks and exits with code 0 (all pass) or 1 (any fail):
+
+| Check | Pass Condition |
+|---|---|
+| System Running | MCP/swarm reachable |
+| Swarm Health | status = `healthy` |
+| Agents Available | active > 0 |
+| MCP Server | running |
+| Memory Backend | backend != `none` |
+| Task Success Rate | < 5% failure rate |
+
+## Watch Mode
+
+`--watch` clears the screen and re-renders on each interval. Press `Ctrl+C` to exit.
+
+## MCP Tools (equivalent)
+
+```javascript
+// Swarm status
+mcp__monomind__swarm_status({ includeMetrics: true })
+
+// Memory stats
+mcp__monomind__memory_stats({})
+
+// Task summary
+mcp__monomind__task_summary({})
+
+// Agent list
+mcp__monomind__agent_list({ includeMetrics: true, status: "all" })
+```
+
+## See Also
+
+- `agent metrics` — performance metrics per agent type
+- `agent health` — agent-specific health check
+- `swarm status` — swarm-specific status
+- `doctor` — comprehensive system diagnostics

package/packages/@monomind/cli/.claude/commands/monobrowse.md

@@ -0,0 +1,21 @@
+---
+name: monobrowse
+description: Launch monomind browse for web UI testing and automation — native TypeScript CDP client, no external binary needed
+---
+
+Invoke the agent-browser-testing skill to test or automate a web UI.
+
+`monomind browse` is built-in — no install needed. Invoke the skill:
+
+Skill("agent-browser-testing")
+
+Pass the user's argument (if any) as the URL or task description: $1
+
+Use the full monomind browse workflow:
+1. `npx monomind browse open <url>`
+2. `npx monomind browse snapshot -i`
+3. Act using element refs (@e1, @e2, ...)
+4. Re-snapshot to verify
+5. Report results (PASS / FAIL / WARN)
+
+Examples: `/monobrowse`, `/monobrowse https://example.com`, `/monobrowse test the login flow`

package/packages/@monomind/cli/.claude/commands/monograph/README.md

@@ -0,0 +1,102 @@
+---
+name: monograph:README
+description: Monograph skills index — build, search, and explore the knowledge graph across code, docs, and PDFs using real CLI subcommands and MCP tools
+---
+
+# Monograph Commands
+
+Knowledge graph for code and documents — build, search, and explore relationships across your entire codebase and documentation.
+
+Alias: `monomind kg`
+
+## CLI Subcommands
+
+| Subcommand | Description |
+|---|---|
+| `monograph build` | Build knowledge graph from code + docs + PDFs |
+| `monograph wiki` | Scan all docs and PDFs into a searchable knowledge graph |
+| `monograph search` | Search the graph (BM25 / semantic / hybrid) |
+| `monograph stats` | Show node/edge counts and top concepts |
+| `monograph watch` | Watch for file changes and rebuild incrementally |
+
+## Quick Reference
+
+```bash
+# First-time build (code + all docs)
+npx monomind monograph build
+
+# Doc/wiki-focused build with Claude semantic extraction
+npx monomind monograph wiki --llm
+
+# Search
+npx monomind monograph search -q "authentication flow"
+npx monomind monograph search -q "pipeline" --mode semantic --label Section
+
+# Stats
+npx monomind monograph stats --top 20
+
+# Auto-rebuild on changes
+npx monomind monograph watch
+```
+
+## Files
+
+- [monograph-build.md](./monograph-build.md) — Full build (code + docs + PDFs)
+- [monograph-wiki.md](./monograph-wiki.md) — Doc/PDF-focused wiki build
+- [monograph-search.md](./monograph-search.md) — Search the knowledge graph
+- [monograph-stats.md](./monograph-stats.md) — Graph statistics
+- [monograph-watch.md](./monograph-watch.md) — Watch mode (incremental rebuild)
+
+## MCP Tools
+
+The monograph MCP tools (available in Claude Code via monomind MCP server) provide programmatic access to the graph without invoking the CLI:
+
+| Tool | Use When |
+|---|---|
+| `mcp__monomind__monograph_build` | Build/rebuild the graph |
+| `mcp__monomind__monograph_query` | BM25 keyword search; returns file + line number |
+| `mcp__monomind__monograph_suggest` | Start every task — returns relevant files ranked by task description |
+| `mcp__monomind__monograph_god_nodes` | Find high-centrality internal files |
+| `mcp__monomind__monograph_stats` | Node/edge counts |
+| `mcp__monomind__monograph_report` | Generate GRAPH_REPORT.md |
+| `mcp__monomind__monograph_shortest_path` | How two modules are connected |
+| `mcp__monomind__monograph_community` | Files forming a cohesive cluster |
+| `mcp__monomind__monograph_surprises` | Unexpected cross-community edges |
+| `mcp__monomind__monograph_export` | Export graph in various formats |
+| `mcp__monomind__monograph_watch` | Start watch mode via MCP |
+| `mcp__monomind__monograph_watch_stop` | Stop watch mode |
+| `mcp__monomind__monograph_context` | 360-degree view of a file: importers, imports, siblings |
+| `mcp__monomind__monograph_health` | Index staleness (commits behind HEAD) |
+
+## Node Types
+
+| Type | Description |
+|---|---|
+| `File` | Source code or document file |
+| `Section` | Markdown heading or document section |
+| `Function` | Code function or method |
+| `Class` | Code class or interface |
+| `Concept` | Extracted semantic concept |
+| `PDF` | PDF document chunk |
+
+## Edge Types
+
+| Relation | Meaning |
+|---|---|
+| `IMPORTS` | Code import dependency |
+| `DEFINES` | File defines symbol |
+| `TAGGED_AS` | Section tagged with concept |
+| `CO_OCCURS` | Concepts appear together |
+| `INFERRED` | Claude-extracted semantic relationship |
+| `DESCRIBES` / `CAUSES` / `PART_OF` | LLM-enriched semantic edges |
+
+## When to Use CLI vs MCP
+
+- **CLI** (`npx monomind monograph ...`) — One-time builds, manual searches, watching from terminal
+- **MCP tools** (`mcp__monomind__monograph_*`) — Claude Code integration, programmatic queries during tasks
+
+## See Also
+
+- `memory` — Vector memory storage (separate from graph)
+- `hooks intelligence` — Pattern learning
+- CLAUDE.md Knowledge Graph section — workflow guidance for multi-file tasks

package/packages/@monomind/cli/.claude/commands/monograph/monograph-build.md

@@ -0,0 +1,79 @@
+---
+name: monograph:monograph-build
+description: Build the knowledge graph from code, docs (md/txt/rst), and PDFs — full index with optional Claude LLM semantic extraction
+---
+
+# monograph build
+
+Build the knowledge graph from code, docs (md/txt/rst), and PDFs.
+
+## Usage
+
+```bash
+npx monomind monograph build [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path to index |
+| `--code-only` | — | boolean | `false` | Index only code files, skip documents |
+| `--llm` | — | boolean | `false` | Enable Claude semantic extraction (requires `ANTHROPIC_API_KEY`) |
+| `--llm-sections` | — | number | `50` | Max sections to enrich with LLM |
+| `--force` | `-f` | boolean | `false` | Force full rebuild even if index is fresh |
+
+## Examples
+
+```bash
+# Build code + all documents (default)
+npx monomind monograph build
+
+# Code only — skip docs and PDFs
+npx monomind monograph build --code-only
+
+# With Claude semantic extraction
+npx monomind monograph build --llm
+
+# Enrich up to 200 sections with Claude
+npx monomind monograph build --llm --llm-sections 200
+
+# Index a specific path
+npx monomind monograph build -p ./src
+
+# Force full rebuild
+npx monomind monograph build --force
+```
+
+## What Gets Indexed
+
+- **Code files** — functions, classes, imports, exports → structured graph nodes
+- **Markdown/MDX** — headings become `Section` nodes; links become edges
+- **Plain text / RST** — chunked into `Section` nodes
+- **PDFs** — text extracted and chunked into nodes
+
+Ignored directories: `node_modules`, `.git`, `dist`, `build`, `__pycache__`, `.cache`, `coverage`, `.monomind`, `vendor`, `target`
+
+## LLM Enrichment
+
+When `--llm` is passed and `ANTHROPIC_API_KEY` is set, Claude extracts typed semantic relationships between sections (e.g. `DESCRIBES`, `CAUSES`, `PART_OF`). These become `INFERRED` edges in the graph, enabling richer semantic search.
+
+## Output
+
+After build, the graph is stored at `.monomind/monograph.db`. Run `monograph stats` to see node/edge counts.
+
+## MCP Tool
+
+```javascript
+mcp__monomind__monograph_build({
+  path: "./",
+  codeOnly: false,
+  force: false
+})
+```
+
+## See Also
+
+- `monograph wiki` — doc/PDF-focused build with better output for documentation projects
+- `monograph stats` — view what was indexed
+- `monograph watch` — auto-rebuild on file changes

package/packages/@monomind/cli/.claude/commands/monograph/monograph-search.md

@@ -0,0 +1,96 @@
+---
+name: monograph:monograph-search
+description: Search the knowledge graph using BM25 keyword search, semantic (embedding) search, or hybrid RRF-merged results — filter by node type (Section, Function, Class, File, Concept)
+---
+
+# monograph search
+
+Search the knowledge graph using BM25 keyword search, semantic (embedding) search, or hybrid RRF-merged results.
+
+## Usage
+
+```bash
+npx monomind monograph search [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Required | Description |
+|---|---|---|---|---|---|
+| `--query` | `-q` | string | — | yes | Search query text |
+| `--limit` | `-l` | number | `15` | no | Maximum results to return |
+| `--label` | — | string | — | no | Filter by node type: `Section`, `Function`, `Concept`, `File`, `Class` |
+| `--mode` | `-m` | string | `hybrid` | no | Search mode: `bm25`, `semantic`, `hybrid` |
+| `--path` | `-p` | string | cwd | no | Root path (location of `.monomind/monograph.db`) |
+
+## Examples
+
+```bash
+# Hybrid search (default) — best general-purpose
+npx monomind monograph search -q "authentication flow"
+
+# Keyword search — exact term matching
+npx monomind monograph search -q "JWT" --mode bm25
+
+# Semantic search — concept/meaning matching
+npx monomind monograph search -q "pipeline architecture" --mode semantic
+
+# Filter to doc sections only
+npx monomind monograph search -q "API design" --label Section
+
+# Find function definitions
+npx monomind monograph search -q "parseToken" --label Function
+
+# More results
+npx monomind monograph search -q "error handling" -l 30
+```
+
+## Search Modes
+
+| Mode | Algorithm | Best For |
+|---|---|---|
+| `hybrid` | RRF merge of BM25 + semantic | General purpose (recommended) |
+| `bm25` | Full-text BM25 ranking | Exact term matching, known symbol names |
+| `semantic` | Embedding cosine similarity | Conceptual queries, meaning-based lookup |
+
+Hybrid mode runs both BM25 and semantic internally, then merges with Reciprocal Rank Fusion (RRF).
+
+## Node Labels (--label filter)
+
+| Label | Represents |
+|---|---|
+| `File` | Source or document files |
+| `Section` | Markdown headings / doc sections |
+| `Function` | Code functions and methods |
+| `Class` | Code classes and interfaces |
+| `Concept` | Extracted semantic concepts |
+
+## Prerequisites
+
+Run `monograph build` or `monograph wiki` first to create the index.
+
+```bash
+# If you see "No knowledge graph found":
+npx monomind monograph build
+```
+
+## MCP Tool
+
+The MCP equivalent for Claude Code integration:
+
+```javascript
+mcp__monomind__monograph_query({
+  query: "authentication flow",
+  limit: 15,
+  label: "Section",
+  mode: "hybrid"
+})
+```
+
+Use `mcp__monomind__monograph_suggest` for task-oriented lookup that returns files ranked by relevance to your current work.
+
+## See Also
+
+- `monograph build` — build the graph index
+- `monograph stats` — see what's indexed
+- `monograph wiki` — doc-focused build

package/packages/@monomind/cli/.claude/commands/monograph/monograph-stats.md

@@ -0,0 +1,53 @@
+---
+name: monograph:monograph-stats
+description: Show knowledge graph statistics — node counts by type, edge type breakdown, and top concepts by importance score
+---
+
+# monograph stats
+
+Show knowledge graph statistics — node counts by type, edge type breakdown, and top concepts by importance.
+
+## Usage
+
+```bash
+npx monomind monograph stats [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path (location of `.monomind/monograph.db`) |
+| `--top` | — | number | `10` | Number of top concepts to show |
+
+## Examples
+
+```bash
+# Show graph statistics
+npx monomind monograph stats
+
+# Show top 20 concepts
+npx monomind monograph stats --top 20
+
+# Stats for a different project path
+npx monomind monograph stats -p ./other-project
+```
+
+## Output
+
+- **Nodes table** — count per node type (`File`, `Section`, `Function`, `Class`, `Concept`) with bar chart
+- **Edges table** — count per relation type (`IMPORTS`, `TAGGED_AS`, `CO_OCCURS`, `INFERRED`, etc.)
+- **Top N Concepts** — ranked by importance score and section count, shown with star ratings
+- **Summary line** — CO_OCCURS edge count and LLM-inferred edge count
+
+## MCP Tool
+
+```javascript
+mcp__monomind__monograph_stats()
+```
+
+## See Also
+
+- `monograph build` — build or rebuild the graph
+- `monograph search` — search across nodes
+- `monograph watch` — auto-rebuild on changes

package/packages/@monomind/cli/.claude/commands/monograph/monograph-watch.md

@@ -0,0 +1,63 @@
+---
+name: monograph:monograph-watch
+description: Watch for file changes and incrementally rebuild the knowledge graph — keeps the graph fresh during active development or documentation writing
+---
+
+# monograph watch
+
+Watch for file changes and incrementally rebuild the knowledge graph. Keeps the graph fresh during active development.
+
+## Usage
+
+```bash
+npx monomind monograph watch [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path to watch |
+| `--llm` | — | boolean | `false` | Enable LLM enrichment on each rebuild (requires `ANTHROPIC_API_KEY`) |
+
+## Examples
+
+```bash
+# Watch and rebuild on any file change
+npx monomind monograph watch
+
+# Watch with Claude semantic enrichment on each rebuild
+npx monomind monograph watch --llm
+
+# Watch a specific path
+npx monomind monograph watch -p ./docs
+```
+
+## Behavior
+
+- Runs until `Ctrl+C`
+- Detects changes to code files, markdown, text, RST, and PDFs
+- Triggers incremental rebuild (only changed files re-processed)
+- Outputs progress per phase as changes are detected
+
+## When to Use
+
+- During active documentation writing — graph stays current as you write
+- During refactoring — relationships update as imports change
+- CI environments — run in background to keep graph fresh for search queries
+
+## MCP Tools
+
+```javascript
+// Start watch via MCP
+mcp__monomind__monograph_watch({ path: "./" })
+
+// Stop watch via MCP
+mcp__monomind__monograph_watch_stop()
+```
+
+## See Also
+
+- `monograph build` — one-time full build
+- `monograph wiki` — doc-focused build
+- `monograph stats` — check current graph state

package/packages/@monomind/cli/.claude/commands/monograph/monograph-wiki.md

@@ -0,0 +1,91 @@
+---
+name: monograph:monograph-wiki
+description: Scan all docs and PDFs and build a searchable knowledge graph — optimized for documentation-heavy projects with Claude LLM semantic extraction
+---
+
+# monograph wiki
+
+Scan all docs and PDFs in the project and build a searchable knowledge graph. Optimized for documentation-heavy projects.
+
+## Usage
+
+```bash
+npx monomind monograph wiki [options]
+```
+
+## Options
+
+| Flag | Short | Type | Default | Description |
+|---|---|---|---|---|
+| `--path` | `-p` | string | cwd | Root path to scan |
+| `--llm` | — | boolean | `false` | Enrich with Claude semantic extraction (requires `ANTHROPIC_API_KEY`) |
+| `--llm-sections` | — | number | `100` | Max sections for LLM enrichment |
+| `--force` | `-f` | boolean | `false` | Force full rebuild |
+
+## Examples
+
+```bash
+# Build knowledge graph from all docs and PDFs
+npx monomind monograph wiki
+
+# With Claude semantic extraction
+npx monomind monograph wiki --llm
+
+# Deep enrichment — process 200 sections with Claude
+npx monomind monograph wiki --llm --llm-sections 200
+
+# Specific docs folder
+npx monomind monograph wiki -p ./docs
+
+# Force full rebuild
+npx monomind monograph wiki --force
+```
+
+## What Gets Indexed
+
+Scans for files with extensions: `.md`, `.mdx`, `.txt`, `.rst`, `.pdf`
+
+| Type | Processing |
+|---|---|
+| `.md` / `.mdx` | Headings → `Section` nodes with hierarchical structure |
+| `.txt` / `.rst` | Chunked → `Section` nodes |
+| `.pdf` | Text extracted → PDF chunk nodes |
+
+## Difference from `build`
+
+| | `build` | `wiki` |
+|---|---|---|
+| Code files | Yes | No |
+| Documents | Yes | Yes |
+| PDFs | Yes | Yes |
+| LLM default sections | 50 | 100 |
+| Best for | Mixed projects | Doc-heavy / knowledge bases |
+
+## LLM Enrichment
+
+With `--llm`, Claude extracts semantic relationships between sections:
+- `DESCRIBES` — section explains a concept
+- `CAUSES` — one event leads to another
+- `PART_OF` — hierarchical membership
+- `CO_OCCURS` — concepts appear together
+
+These `INFERRED` edges make semantic search significantly more accurate.
+
+## After Build
+
+```bash
+# Search your wiki
+npx monomind monograph search -q "your query"
+
+# View statistics
+npx monomind monograph stats
+
+# Auto-rebuild on edits
+npx monomind monograph watch
+```
+
+## See Also
+
+- `monograph build` — full build including code files
+- `monograph search` — search the graph
+- `monograph stats` — node/edge breakdown