# Beads Village MCP - Quick Reference

> Works with `bd` (Go) or `br` (Rust) backends. Auto-detected: **br preferred**. Override: `BEADS_BACKEND=bd|br`.

## Workflow

```
# Leader: init(team, leader=true) → add(tags=["role"]) → assign(id, role) → monitor
# Worker: init(team, role="fe") → claim() → reserve(paths) → work → done(id, msg?) → restart
```

## Tools (23 core + 6 br-only = 29 max)

### Lifecycle
- `init(ws?, team?, role?, leader?, start_tui?)` — Join workspace (ALWAYS FIRST; `start_tui` is deprecated no-op)
- `claim()` — Get next task (auto-filtered by role)
- `done(id, msg?)` — Complete task, auto-releases files (msg optional but strongly recommended)

### Issues
- `add(title, desc?, typ?, pri?, tags?, parent?, deps?)` — Create issue
- `assign(id, role, notify?)` — Assign to role (leader only)
- `ls(status?, limit?, offset?)` — List issues (open/closed/ready/in_progress/all)
- `show(id)` — Get issue details

### File Locking
- `reserve(paths, reason?, ttl?, mode?, region?)` — Lock before editing (mode: exclusive/shared, region: edit scope hint)
- `release(paths?)` — Unlock (empty=all)
- `reservations()` — Check active locks (shows mode/region)

### Messaging
- `msg(subj, body?, to?, global?, cc?, thread?, ack_required?, importance?)` — Send/broadcast
- `inbox(n?, unread?, global?, thread?)` — Check messages
- `search_messages(query, status?, limit?)` — FTS5 search across messages
- `ack_message(id)` — Acknowledge a message (auto-replies to sender)

### Status & Maintenance
- `status(include_agents?, include_bv?)` — Workspace overview + teammate discovery
- `sync()` — Sync with git
- `cleanup(days?)` — Remove old closed issues
- `doctor()` — Fix database

### Dashboard & Graph (requires bv)
- `village_tui()` — TUI dashboard
- `bv_insights()` / `bv_plan()` / `bv_priority(limit?)` / `bv_diff(since?, as_of?)`

### br-Only (error with install hint on bd)
- `search(query, status?, label?, limit?)` — Full-text search
- `stale(days?, status?)` — Find stale issues
- `changelog(since?, since_tag?)` — Generate changelog
- `graph(issue?, all?, compact?)` — Dependency graph
- `defer(ids, until?)` / `undefer(ids)` — Schedule for later

## Quick Facts

**Types**: task (default), bug, feature, epic, chore
**Priority**: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog
**Roles**: `fe`, `be`, `mobile`, `devops`, `qa`
**Response fields**: `id`=ID, `t`=title, `p`=priority(0-4), `s`=status, `f`=from, `b`=body, `ts`=timestamp, `ws`=workspace, `team`=team, `role`=agent role, `leader`=bool, `tags`=role tags, `global`=from team hub, `imp`=importance

## Rules

1. Always `init()` first — everything else fails without it
2. Always `reserve()` before editing files
3. Always include `desc` when creating issues
4. `release()` before switching tasks
5. File side-issues with `add()` for work >2min
6. Restart session after `done()`

## Example

```python
# Leader
init(team="proj", leader=true)
add(title="Login API", tags=["be"])
add(title="Login form", tags=["fe"])

# Worker
init(team="proj", role="be")
claim()  # Gets "Login API" (auto-filtered)
reserve(paths=["src/auth.py"], reason="bd-42")
[implement]
done(id="bd-42", msg="JWT auth implemented")
msg(subj="API Ready", body="POST /auth/login live", global=true, to="all")
```