@monoes/monomindcli 2.9.21 → 2.9.23

package/.claude/commands/github/sync-coordinator.md

@@ -76,7 +76,7 @@ Bash(`gh api repos/:owner/:repo/contents/packages/@monomind/cli/CLAUDE.md \
   -f sha="$(gh api repos/:owner/:repo/contents/packages/@monomind/cli/CLAUDE.md?ref=sync/documentation --jq '.sha' 2>/dev/null || echo '')")`)
 
 // Store sync state in memory
-mcp__monomind__memory_store {
+mcp__monomind__memory_pattern-store {
   key: "sync/documentation/status",
   value: { timestamp: Date.now(), status: "synchronized", files: ["CLAUDE.md"] }
 }
@@ -184,7 +184,7 @@ Generated with Claude Code using Monomind swarm coordination`
   ]}
   
   // Store comprehensive sync state
-  mcp__monomind__memory_store {
+  mcp__monomind__memory_pattern-store {
     key: "sync/complete/status",
     value: {
       timestamp: Date.now(),

package/.claude/commands/hooks/README.md

@@ -30,9 +30,8 @@ session-restore   Restore a previous session
 route             Route task to optimal agent using learned patterns
 explain           Explain routing decision with transparency
 pretrain          Bootstrap intelligence from repository (4-step pipeline + embeddings)
-build-agents      Generate optimized agent configs from pretrain data
 metrics           View learning metrics dashboard
-transfer          Transfer patterns via IPFS registry or from another project
+transfer          Transfer patterns from another local project
 list              List all registered hooks
 worker            Background worker management (12 workers)
 progress          Check v1 implementation progress

package/.claude/commands/hooks/overview.md

@@ -37,7 +37,6 @@ All hooks are invoked as `npx monomind hooks <subcommand>`:
 | `route` | Route task to optimal agent |
 | `explain` | Explain routing decision |
 | `pretrain` | Bootstrap intelligence from repo (4-step pipeline) |
-| `build-agents` | Generate optimized agent configs from pretrain data |
 | `metrics` | View learning metrics dashboard |
 | `model-route` | Route to optimal model (haiku/sonnet/opus) |
 | `model-outcome` | Record model routing result |
@@ -60,7 +59,7 @@ All hooks are invoked as `npx monomind hooks <subcommand>`:
 | `statusline` | Generate dynamic statusline display |
 | `list` | List all registered hooks |
 | `progress` | Check v1 implementation progress |
-| `transfer` | Transfer patterns via IPFS or from another project |
+| `transfer` | Transfer patterns from another local project |
 
 ## Claude Code Integration
 

package/.claude/commands/hooks/setup.md

@@ -100,9 +100,6 @@ npx monomind hooks pretrain
 
 # Deep analysis only, no embeddings
 npx monomind hooks pretrain --depth deep --no-with-embeddings
-
-# Generate optimized agent configs from pretrain data
-npx monomind hooks build-agents
 ```
 
 ### Session Persistence

package/.claude/commands/mastermind/createtask.md

@@ -42,7 +42,7 @@ Parse `$ARGUMENTS`:
 Run ALL in parallel (skip errors):
 1. `mcp__monomind__monograph_suggest` with first 200 chars of `RAW_CONTENT`
 2. `mcp__monomind__monograph_query` for module/component names found in `RAW_CONTENT` (up to 5)
-3. `mcp__monomind__memory_search` with input summary
+3. `mcp__monomind__memory_pattern-search` with input summary
 4. Read `README.md` (first 200 lines)
 5. Read first found: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`
 6. Repo name from `git remote get-url origin` (strip path, strip `.git`) — store as `REPO_NAME`
@@ -282,7 +282,7 @@ For each task, in prerequisite order:
 
 **File mode (default):** The frontmatter in `TASK_FILE` already records `recommended_mode`. No additional storage needed.
 
-**Monotask mode:** Call `mcp__monomind__memory_store` with:
+**Monotask mode:** Call `mcp__monomind__memory_pattern-store` with:
 ```json
 {
   "key": "task-strategy:<REPO_NAME>:<timestamp>",

package/.claude/commands/mastermind/do.md

@@ -103,7 +103,7 @@ Group tasks by `context_group`:
 
 **File mode:** Read `recommended_mode` from the frontmatter of `TASK_FILE`. Use as the default.
 
-**Monotask mode:** Call `mcp__monomind__memory_search` with `"task-strategy:<REPO_NAME>"`. If found, use `recommended_execution_mode` as default.
+**Monotask mode:** Call `mcp__monomind__memory_pattern-search` with `"task-strategy:<REPO_NAME>"`. If found, use `recommended_execution_mode` as default.
 
 ### 2e: Choose execution mode
 
@@ -328,7 +328,7 @@ Collect in parallel (skip any that error):
 
 1. **README**: Read `README.md` (first 200 lines).
 2. **Package manifest**: Read whichever exists first: `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`.
-3. **Memory search**: Call `mcp__monomind__memory_search` with the first task's title.
+3. **Memory search**: Call `mcp__monomind__memory_pattern-search` with the first task's title.
 4. **Knowledge graph**: Call `mcp__monomind__monograph_suggest` with the first task's title.
 
 Bundle into `PROJECT_CONTEXT` and include in every agent prompt.
@@ -500,7 +500,7 @@ To repeat this command on a schedule, wrap it with `/mastermind:repeat`.
 
 ### Store execution outcome in session memory
 
-Call `mcp__monomind__memory_store` with:
+Call `mcp__monomind__memory_pattern-store` with:
 ```json
 {
   "key": "execution-outcome:<REPO_NAME>:<timestamp>",

package/.claude/commands/mastermind/help.md

@@ -111,8 +111,8 @@ npx monomind performance benchmark --suite all
 
 ```javascript
 // Memory
-mcp__monomind__memory_store({ key: "...", value: "...", namespace: "..." })
-mcp__monomind__memory_search({ query: "...", namespace: "..." })
+mcp__monomind__memory_pattern-store({ key: "...", value: "...", namespace: "..." })
+mcp__monomind__memory_pattern-search({ query: "...", namespace: "..." })
 
 // Knowledge graph
 mcp__monomind__monograph_suggest({ task: "..." })

package/.claude/commands/mastermind/ideate.md

@@ -39,7 +39,7 @@ Collect ALL of the following in parallel (skip any that error):
 
 4. **Knowledge graph**: Call `mcp__monomind__monograph_suggest` with the user's prompt (`$ARGUMENTS`). Skip if it errors or returns empty.
 
-5. **Memory search**: Call `mcp__monomind__memory_search` with the user's prompt (`$ARGUMENTS`). Use the top 5 results.
+5. **Memory search**: Call `mcp__monomind__memory_pattern-search` with the user's prompt (`$ARGUMENTS`). Use the top 5 results.
 
 Bundle all gathered information into a single `PROJECT_CONTEXT` string for downstream agents.
 

package/.claude/commands/mastermind/improve.md

@@ -43,7 +43,7 @@ Collect ALL of the following in parallel (skip any that error):
 
 4. **Knowledge graph**: Call `mcp__monomind__monograph_suggest` with the user's prompt (`$ARGUMENTS`). Skip if it errors or returns empty.
 
-5. **Memory search**: Call `mcp__monomind__memory_search` with the user's prompt (`$ARGUMENTS`). Use the top 5 results.
+5. **Memory search**: Call `mcp__monomind__memory_pattern-search` with the user's prompt (`$ARGUMENTS`). Use the top 5 results.
 
 Bundle all gathered information into a single `PROJECT_CONTEXT` string for downstream agents.
 

package/.claude/commands/mastermind/memory.md

@@ -188,10 +188,10 @@ npx monomind memory import --input ./backup.json --namespace archive
 
 ```javascript
 // Store
-mcp__monomind__memory_store({ key: "pattern/auth", value: "JWT + refresh", namespace: "patterns" })
+mcp__monomind__memory_pattern-store({ key: "pattern/auth", value: "JWT + refresh", namespace: "patterns" })
 
 // Search
-mcp__monomind__memory_search({ query: "authentication", namespace: "patterns" })
+mcp__monomind__memory_pattern-search({ query: "authentication", namespace: "patterns" })
 
 // Retrieve
 mcp__monomind__memory_retrieve({ key: "pattern/auth", namespace: "patterns" })

package/.claude/commands/mastermind/{swarm.md → monoswarm.md}

@@ -13,20 +13,19 @@ Multi-agent swarm coordination with hierarchical topology, distributed memory, a
 | `status` | Show current swarm status and progress |
 | `stop` | Stop swarm execution |
 | `scale` | Scale swarm agent count up or down |
-| `coordinate` | Launch v1 15-agent hierarchical-mesh coordination |
 
 ## init — Initialize a Swarm
 
 ```bash
 # Default (hierarchical, 15 agents)
-npx monomind swarm init
+npx monomind monoswarm init
 
 # Anti-drift configuration (recommended)
-npx monomind swarm init --topology hierarchical --max-agents 8 --strategy specialized
+npx monomind monoswarm init --topology hierarchical --max-agents 8 --strategy specialized
 
 # v1 15-agent hierarchical-mesh
-npx monomind swarm init --v1-mode
-npx monomind swarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized
+npx monomind monoswarm init --v1-mode
+npx monomind monoswarm init --topology hierarchical-mesh --max-agents 15 --strategy specialized
 ```
 
 **Flags:**
@@ -48,7 +47,7 @@ npx monomind swarm init --topology hierarchical-mesh --max-agents 15 --strategy
 | `mesh` | Research, analysis — broad coverage |
 | `star` | Parallel testing, parallel maintenance |
 | `ring` | Sequential pipeline processing |
-| `hybrid` | Dynamic topology switching |
+| `hybrid` | Topology label recorded in swarm state; coordination behavior is chosen by the caller — no automatic reconfiguration |
 
 ## Strategies
 
@@ -58,10 +57,10 @@ npx monomind swarm init --topology hierarchical-mesh --max-agents 15 --strategy
 
 ```bash
 # Start a development swarm
-npx monomind swarm start -o "Build REST API with authentication" -s development
+npx monomind monoswarm start -o "Build REST API with authentication" -s development
 
 # Parallel research swarm
-npx monomind swarm start -o "Analyze performance bottlenecks" -s research --parallel
+npx monomind monoswarm start -o "Analyze performance bottlenecks" -s research --parallel
 ```
 
 **Flags:**
@@ -77,20 +76,20 @@ npx monomind swarm start -o "Analyze performance bottlenecks" -s research --para
 
 ```bash
 # Overall status
-npx monomind swarm status
+npx monomind monoswarm status
 
 # Status for a specific swarm ID
-npx monomind swarm status swarm-abc123
+npx monomind monoswarm status swarm-abc123
 ```
 
 ## stop — Stop a Swarm
 
 ```bash
 # Graceful stop (saves state by default)
-npx monomind swarm stop swarm-abc123
+npx monomind monoswarm stop swarm-abc123
 
 # Force immediate stop
-npx monomind swarm stop swarm-abc123 --force
+npx monomind monoswarm stop swarm-abc123 --force
 ```
 
 **Flags:**
@@ -104,24 +103,12 @@ npx monomind swarm stop swarm-abc123 --force
 
 ```bash
 # Scale to 12 agents
-npx monomind swarm scale swarm-abc123 --agents 12
+npx monomind monoswarm scale swarm-abc123 --agents 12
 
 # Scale a specific agent type
-npx monomind swarm scale swarm-abc123 --agents 8 --type coder
+npx monomind monoswarm scale swarm-abc123 --agents 8 --type coder
 ```
 
-## coordinate — v1 15-Agent Coordination
-
-```bash
-# Full v1 15-agent hierarchical mesh
-npx monomind swarm coordinate
-
-# Subset of agents
-npx monomind swarm coordinate --agents 8
-```
-
-Activates the v1 agent roster: Queen Coordinator, Security Architect, Security Auditor, Test Architect, Core Architect, Memory Specialist, Swarm Specialist, Integration Architect, Performance Engineer, CLI Developer, Hooks Developer, MCP Specialist, Project Coordinator, Documentation Lead, DevOps Engineer.
-
 ## MCP Tools
 
 ```javascript

package/.claude/commands/mastermind/topology.md

@@ -1,6 +1,6 @@
 ---
 name: mastermind-topology
-description: Swarm & Hive-Mind architecture picker — presents all topologies, consensus protocols, and strategies, then gives one concrete recommendation for the current task
+description: Monoswarm architecture picker — presents all topologies, consensus protocols, and strategies, then gives one concrete recommendation for the current task
 ---
 
 IMPORTANT: Do NOT dump all the reference content at once. Follow the two-phase flow below exactly.

package/.claude/commands/memory/README.md

@@ -56,9 +56,9 @@ npx monomind memory import --input backup.json --merge
 
 | Tool | Purpose |
 |---|---|
-| `mcp__monomind__memory_store` | Store a memory entry |
+| `mcp__monomind__memory_pattern-store` | Store a memory entry |
 | `mcp__monomind__memory_retrieve` | Retrieve by key |
-| `mcp__monomind__memory_search` | Search memory |
+| `mcp__monomind__memory_pattern-search` | Search memory |
 | `mcp__monomind__memory_list` | List entries |
 | `mcp__monomind__memory_delete` | Delete entries |
 | `mcp__monomind__memory_stats` | Usage statistics |

package/.claude/commands/memory/memory-search.md

@@ -61,7 +61,7 @@ Use `--build-hnsw` when searching large memory stores (1,000+ entries). The pure
 ## MCP Tool
 
 ```javascript
-mcp__monomind__memory_search({
+mcp__monomind__memory_pattern-search({
   query: "authentication patterns",
   namespace: "default",
   limit: 10,

package/.claude/commands/monoswarm/README.md

@@ -0,0 +1,59 @@
+---
+name: monoswarm-README
+description: Monoswarm skill index — lists all available multi-agent coordination and vote-consensus skills for Monomind
+---
+
+# Monoswarm Skills
+
+Multi-agent swarm coordination, with optional vote-based consensus, for Monomind.
+
+## Core Skills
+
+- [monoswarm](./monoswarm.md) — Main skill: how to start and coordinate a run, plus the vote/consensus tool reference
+
+## Strategy Skills
+
+- [analysis](./analysis.md) — Distributed analysis via coordinated agents
+- [development](./development.md) — Coordinated development teams
+- [research](./research.md) — Parallel information gathering
+- [testing](./testing.md) — Distributed test execution
+- [maintenance](./maintenance.md) — System maintenance coordination
+- [optimization](./optimization.md) — Performance optimization runs
+- [examples](./examples.md) — Common patterns and recipes
+
+## Lifecycle & Vote Commands
+
+- [init](./init.md) — Initialize a run with topology and vote-strategy settings
+- [spawn](./spawn.md) — Register worker agent records into the run
+- [status](./status.md) — Show run status, workers, and metrics
+- [stop](./stop.md) — Shut down the run
+- [consensus](./consensus.md) — Manage proposals and voting
+- [memory](./memory.md) — Access the run's shared memory
+
+## Real Tools (11 total)
+
+```
+monoswarm_init            Create the run state file (topology, vote strategy, empty worker list)
+monoswarm_agent_add       Register worker records into the agent store and run
+monoswarm_status          Read run status: lead, workers, task/vote metrics
+monoswarm_join            Add an existing agent id to the run's worker list
+monoswarm_leave           Remove an agent id from the run's worker list
+monoswarm_vote            Propose/vote/check status on threshold-based decisions
+monoswarm_notice          Write a message into the run's shared memory
+monoswarm_memory          Get/set/delete/list keys in the run's shared memory
+monoswarm_audit_list      List signed vote decision records
+monoswarm_audit_verify    Verify a vote decision's signatures
+monoswarm_shutdown        Clear run workers from the agent store, reset run state
+```
+
+## Quick Start
+
+```bash
+# Initialize and start a run via CLI
+npx monomind swarm init --topology hierarchical --max-agents 8
+npx monomind swarm start "Build REST API" --strategy development
+npx monomind swarm status
+```
+
+For vote-based decisions, use the MCP tools directly — see
+[monoswarm](./monoswarm.md) and [consensus](./consensus.md).

package/.claude/commands/monoswarm/consensus.md

@@ -0,0 +1,61 @@
+---
+name: monoswarm:consensus
+---
+
+# monoswarm vote
+
+Propose or vote on a threshold-based decision — vote-count bookkeeping over one
+JSON state file. See `doc/concepts/monoswarm.md` for how the mechanism works.
+
+There is no `npx monomind monoswarm vote` CLI command — this is invoked
+directly as an MCP tool call (see below).
+
+## Parameters
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `action` | string | — | `propose`, `vote`, `status`, `list` (required) |
+| `proposalId` | string | — | Proposal ID (required for `vote` and `status`) |
+| `type` | string | — | Proposal type (used with `propose`) |
+| `value` | any | — | Proposal value (used with `propose`) |
+| `vote` | boolean | — | `true` = for, `false` = against (used with `vote`) |
+| `voterId` | string | — | Voter agent ID (used with `vote`) |
+| `strategy` | string | run's configured strategy, else `majority` | `majority`, `supermajority`, `unanimous`, `threshold` |
+| `term` | number | — | Term number (majority-strategy re-proposals) |
+| `timeoutMs` | number | `30000` | Timeout in ms for re-proposal |
+
+## Examples
+
+```javascript
+// List all pending proposals
+mcp__monomind__monoswarm_vote({ action: "list" })
+
+// Create a new proposal
+mcp__monomind__monoswarm_vote({
+  action: "propose",
+  type: "config-change",
+  value: { maxAgents: 20 }
+})
+
+// Vote on a proposal
+mcp__monomind__monoswarm_vote({
+  action: "vote",
+  proposalId: "proposal-abc123",
+  vote: true,
+  voterId: "agent-1"
+})
+
+// Check proposal status
+mcp__monomind__monoswarm_vote({ action: "status", proposalId: "proposal-abc123" })
+```
+
+## Actions
+
+- **`list`** — Show all pending proposals
+- **`propose`** — Create a new proposal (requires `type` and `value`)
+- **`vote`** — Cast a vote on a proposal (requires `proposalId`, `vote`, and `voterId`)
+- **`status`** — Check the current vote tally for a proposal (requires `proposalId`)
+
+Resolved decisions are HMAC-signed and appended to a tamper-evident JSONL
+audit trail. Verify with `mcp__monomind__monoswarm_audit_verify { decisionId }`;
+list history with `mcp__monomind__monoswarm_audit_list { limit }`.

package/.claude/commands/monoswarm/init.md

@@ -0,0 +1,68 @@
+---
+name: monoswarm:init
+---
+
+# monoswarm init
+
+Initialize a monoswarm run with topology and (optionally) vote-strategy settings.
+
+There is no `npx monomind monoswarm init` CLI command for the vote/consensus
+side — that part is invoked directly as an MCP tool call. For plain agent
+coordination without voting, use `npx monomind swarm init` (see `monoswarm.md`).
+
+```javascript
+mcp__monomind__monoswarm_init({
+  topology: "hierarchical",
+  voteStrategy: "supermajority",
+  maxAgents: 15,
+  persist: true,
+  memoryBackend: "hybrid"
+})
+```
+
+## Parameters
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `topology` | string | `mesh` | `mesh`, `hierarchical`, `ring`, `star` |
+| `voteStrategy` | string | `supermajority` | `majority`, `supermajority`, `unanimous`, `threshold` |
+| `maxAgents` | number | `15` | Maximum number of agents (bookkeeping only, not enforced by a scheduler) |
+| `persist` | boolean | `true` | Whether to persist state to disk |
+| `memoryBackend` | string | `hybrid` | Label stored with the config — not validated against a real backend list |
+| `leadId` | string | `lead-<timestamp>` | Initial lead/coordinator agent ID |
+
+`gossip` and `crdt` are **not implemented** as vote strategies — passing
+either is rejected with an error listing the supported set.
+
+## Examples
+
+```javascript
+// Initialize with recommended settings
+mcp__monomind__monoswarm_init({})
+
+// Hierarchical topology with a supermajority vote bar
+mcp__monomind__monoswarm_init({ topology: "hierarchical", voteStrategy: "supermajority" })
+
+// Larger run with a plain majority vote bar
+mcp__monomind__monoswarm_init({ topology: "mesh", voteStrategy: "majority", maxAgents: 20 })
+
+// Minimal run with no persistence
+mcp__monomind__monoswarm_init({ topology: "hierarchical", voteStrategy: "majority", persist: false })
+```
+
+## Topology Guide
+
+- **`hierarchical`** — Lead controls workers directly. Best for small teams (< 8 agents). Prevents drift.
+- **`mesh`** — Fully connected peers. Best when all agents are equals.
+- **`ring`** — Circular communication pattern.
+- **`star`** — Central coordinator with spokes.
+
+## Vote Strategy Guide
+
+- **`supermajority`** — Requires 2f+1 votes. Tolerates f < n/3 dissenting voters. Default.
+- **`majority`** — Simple majority. Tolerates f < n/2.
+- **`unanimous`** — Rejects on the first dissenting vote.
+- **`threshold`** — Caller-supplied vote count or fraction.
+
+These are vote-threshold implementations over one JSON state file — see
+`doc/concepts/monoswarm.md` for how the mechanism works.

package/.claude/commands/monoswarm/memory.md

@@ -0,0 +1,55 @@
+---
+name: monoswarm:memory
+---
+
+# monoswarm memory
+
+Access and manage monoswarm shared memory — a key-value blob on the run's
+state file, readable/writable by all agents coordinating in the current run.
+
+There is no `npx monomind monoswarm memory` CLI command — this is invoked
+directly as an MCP tool call (see below).
+
+## Parameters
+
+| Param | Type | Default | Description |
+|---|---|---|---|
+| `action` | string | `list` | Action: `get`, `set`, `delete`, `list` |
+| `key` | string | — | Memory key (required for `get`, `set`, `delete`) |
+| `value` | any | — | Value to store (required for `set`) |
+
+## Examples
+
+```javascript
+// List all keys in shared memory
+mcp__monomind__monoswarm_memory({ action: "list" })
+
+// Store a value
+mcp__monomind__monoswarm_memory({ action: "set", key: "project-goal", value: "Build auth module" })
+
+// Retrieve a value
+mcp__monomind__monoswarm_memory({ action: "get", key: "project-goal" })
+
+// Delete a key
+mcp__monomind__monoswarm_memory({ action: "delete", key: "project-goal" })
+```
+
+## Actions
+
+- **`list`** — Show all keys currently in shared memory with count (default)
+- **`get`** — Retrieve the value at a key (requires `key`)
+- **`set`** — Store a value at a key (requires `key` and `value`)
+- **`delete`** — Remove a key from shared memory (requires `key`)
+
+## Relationship to `monomind memory`
+
+`monoswarm memory` operates on the **run's shared memory namespace** — a
+single JSON blob on the run state file, visible to all agents coordinating
+in the current run. This is distinct from the global memory tools
+(`memory_pattern-store` / `memory_pattern-search` / CLI `monomind memory`), which are
+backed by local SQLite (with `sql.js`/WASM as a fallback) — not LanceDB,
+which has been fully removed from this codebase.
+
+Use monoswarm memory for transient inter-agent coordination data (task
+results, intermediate state). Use global memory for patterns and knowledge
+that should persist across sessions.

package/.claude/commands/monoswarm/monoswarm.md

@@ -0,0 +1,139 @@
+---
+name: monoswarm-monoswarm
+description: Main monoswarm skill — initializes and starts multi-agent swarms for research, development, analysis, testing, optimization, and maintenance tasks, with optional vote-based consensus
+---
+
+# Monoswarm Orchestration
+
+Start and coordinate multi-agent swarms for complex tasks. Queen-led,
+vote-based coordination for decisions that need a recorded outcome.
+
+## How to Invoke
+
+In Claude Code, load this skill:
+```
+Skill("monoswarm:monoswarm")
+```
+
+Then describe what you want to accomplish:
+> "Start a development swarm to build a REST API with auth endpoints."
+> "Run a research swarm on AI agent coordination patterns."
+
+---
+
+## CLI Reference
+
+```bash
+# Initialize a swarm
+npx monomind swarm init --topology hierarchical --max-agents 8 --strategy specialized
+
+# Start a swarm with an objective
+npx monomind swarm start "Build REST API" --strategy development --parallel
+
+# Check swarm status
+npx monomind swarm status
+
+# Stop the swarm
+npx monomind swarm stop
+
+# Scale agents
+npx monomind swarm scale <swarm-id> --agents 12
+```
+
+## MCP Tools
+
+```javascript
+// Initialize swarm
+mcp__monomind__swarm_init({
+  topology: "hierarchical",
+  maxAgents: 8,
+  strategy: "specialized"
+})
+
+// Check status
+mcp__monomind__swarm_status({ swarmId: "current" })
+
+// Coordinate tasks
+mcp__monomind__coordination_orchestrate({ task: "build feature", strategy: "parallel" })
+
+// Spawn an agent
+mcp__monomind__agent_spawn({ type: "coder", capabilities: ["typescript", "api"] })
+
+// Shut down swarm
+mcp__monomind__swarm_shutdown({ swarmId: "current" })
+```
+
+## Strategy Selection
+
+| Strategy | Topology | Use when |
+|----------|----------|----------|
+| research | mesh | Gathering information from multiple sources in parallel |
+| development | hierarchical | Building features with architect → coder → tester flow |
+| analysis | mesh | Distributed codebase or performance analysis |
+| testing | star | Parallel test suite execution |
+| optimization | mesh | Performance profiling and bottleneck resolution |
+| maintenance | star | Sequential dependency updates with checkpoints |
+
+## Vote-Based Consensus (Optional)
+
+There is no `npx monomind monoswarm consensus` CLI subcommand — vote/decision
+functionality is available **exclusively via MCP tools**
+(`mcp__monomind__monoswarm_*`). Invoke the tools directly, or use one of the
+slash commands in this directory, which call the tools for you.
+
+### Real Tools (11 total)
+
+| Tool | Description |
+|---|---|
+| `monoswarm_init` | Create the run state file (topology, vote strategy, empty worker list) |
+| `monoswarm_agent_add` | Write worker agent records into the agent store and register them |
+| `monoswarm_status` | Read run status: lead, workers, task/vote metrics |
+| `monoswarm_join` | Add an existing agent id to the run's worker list |
+| `monoswarm_leave` | Remove an agent id from the run's worker list |
+| `monoswarm_vote` | Propose/vote/check status on threshold-based decisions |
+| `monoswarm_notice` | Write a message into the run's shared memory for all workers to read |
+| `monoswarm_memory` | Get/set/delete/list keys in the run's shared memory namespace |
+| `monoswarm_audit_list` | List signed vote decision records |
+| `monoswarm_audit_verify` | Verify a vote decision's signatures |
+| `monoswarm_shutdown` | Clear run workers from the agent store and reset run state |
+
+### Vote Strategies (`monoswarm_vote`'s `strategy` param)
+
+Vote-threshold bookkeeping over one JSON state file — see
+`doc/concepts/monoswarm.md` for how the mechanism works.
+
+| Strategy | Description |
+|---|---|
+| `supermajority` | Requires 2f+1 votes — tolerates f < n/3 dissenting voters (default) |
+| `majority` | Simple majority — tolerates f < n/2 |
+| `unanimous` | Rejects on the first dissenting vote |
+| `threshold` | Caller-supplied vote count or fraction |
+
+`gossip` and `crdt` are planned but not implemented — both `monoswarm_init`
+and `monoswarm_vote` reject them with an error.
+
+### Quick Start
+
+```javascript
+// 1. Initialize with recommended topology
+mcp__monomind__monoswarm_init({ topology: "hierarchical", voteStrategy: "supermajority" })
+
+// 2. Add worker agents
+mcp__monomind__monoswarm_agent_add({ count: 5, role: "specialist" })
+
+// 3. Check status
+mcp__monomind__monoswarm_status({ verbose: true })
+
+// 4. Shut down when done
+mcp__monomind__monoswarm_shutdown({ graceful: true })
+```
+
+Note: `monoswarm_agent_add` only writes bookkeeping records into the agent
+store and the run's worker list — it does not start any process, thread, or
+agent. Real concurrency comes from Claude Code's Task tool.
+
+## See Also
+- `monoswarm:examples` — Common patterns with full code
+- `monoswarm:consensus` — Vote proposal/vote details
+- `monoswarm:memory` — Shared memory reference
+- `monoswarm:status` — Status output reference