Add command documentation and improve daemon UX

- Added human-readable uptime formatting (51m 59s vs 3119.4 seconds)
- Fixed daemon stop race condition with SIGKILL
- Added markdown docs for 19 commands: blocked, comments, compact, daemon,
  delete, dep, epic, export, import, label, list, quickstart, rename-prefix,
  renumber, reopen, repos, restore, stale, sync
- Closed: bd-159, bd-152, bd-168
- Deleted test issues: bd-144, bd-145

Amp-Thread-ID: https://ampcode.com/threads/T-9f7c3fed-62de-4bcd-a059-8c1b77cdb841
Co-authored-by: Amp <amp@ampcode.com>

commands/blocked.md

@@ -0,0 +1,15 @@
+---
+description: Show blocked issues
+argument-hint: []
+---
+
+Show all issues that are blocked by dependencies.
+
+Use `bd blocked` to see which issues have blockers preventing them from being worked on. This is the inverse of `bd ready` - it shows what's NOT ready.
+
+Blocked issues have one or more dependencies with type "blocks" that are still open. Once all blocking dependencies are closed, the issue becomes ready and will appear in `bd ready`.
+
+Useful for:
+- Understanding why work is stuck
+- Identifying critical path items
+- Planning dependency resolution

commands/comments.md

@@ -0,0 +1,28 @@
+---
+description: View or manage comments on an issue
+argument-hint: [issue-id]
+---
+
+View or add comments to a beads issue.
+
+## View Comments
+
+To view all comments on an issue:
+- $1: Issue ID (e.g., bd-123)
+
+Use the beads CLI `bd comments <issue-id>` to list all comments. Show them to the user with timestamps and authors.
+
+## Add Comment
+
+To add a comment:
+- $1: "add"
+- $2: Issue ID
+- $3: Comment text (or use -f flag for file input)
+
+Use `bd comments add <issue-id> "comment text"` to add a comment. Confirm the comment was added successfully.
+
+Comments are useful for:
+- Progress updates during work
+- Design notes or technical decisions
+- Links to related resources
+- Questions or blockers

commands/compact.md

@@ -0,0 +1,31 @@
+---
+description: Compact old closed issues using semantic summarization
+argument-hint: [--all] [--id issue-id] [--dry-run]
+---
+
+Reduce database size by summarizing closed issues no longer actively referenced.
+
+## Compaction Tiers
+
+- **Tier 1**: Semantic compression (30+ days closed, ~70% size reduction)
+- **Tier 2**: Ultra compression (90+ days closed, ~95% size reduction)
+
+## Usage
+
+- **Preview candidates**: `bd compact --dry-run`
+- **Compact all eligible**: `bd compact --all`
+- **Compact specific issue**: `bd compact --id bd-42`
+- **Force compact**: `bd compact --id bd-42 --force` (bypass age checks)
+- **View statistics**: `bd compact --stats`
+
+## Options
+
+- **--tier**: Choose compaction tier (1 or 2, default: 1)
+- **--workers**: Parallel workers (default: 5)
+- **--batch-size**: Issues per batch (default: 10)
+
+## Important
+
+This is **permanent graceful decay** - original content is discarded. Use `bd restore <id>` to view full history from git if needed.
+
+Useful for long-running projects to keep database size manageable.

commands/daemon.md

@@ -0,0 +1,35 @@
+---
+description: Run background sync daemon
+argument-hint: [--global] [--stop] [--status] [--health]
+---
+
+Run a background daemon that manages database connections and optionally syncs with git.
+
+## Daemon Modes
+
+- **Local daemon**: Socket at `.beads/bd.sock` (per-repository)
+- **Global daemon**: Socket at `~/.beads/bd.sock` (all repositories)
+
+## Common Operations
+
+- **Start**: `bd daemon` or `bd daemon --global`
+- **Stop**: `bd daemon --stop` or `bd daemon --global --stop`
+- **Status**: `bd daemon --status` or `bd daemon --global --status`
+- **Health**: `bd daemon --health` - shows uptime, cache stats, performance metrics
+- **Metrics**: `bd daemon --metrics` - detailed operational telemetry
+
+## Sync Options
+
+- **--auto-commit**: Automatically commit JSONL changes
+- **--auto-push**: Automatically push commits to remote
+- **--interval**: Sync check interval (default: 5m)
+
+## Migration
+
+- **--migrate-to-global**: Migrate from local to global daemon
+
+The daemon provides:
+- Connection pooling and caching
+- Better performance for frequent operations
+- Automatic JSONL sync
+- Optional git sync

commands/delete.md

@@ -0,0 +1,32 @@
+---
+description: Delete issues and clean up references
+argument-hint: [issue-ids...] [--force]
+---
+
+Delete one or more issues and clean up all references.
+
+## Safety Features
+
+- **Preview mode**: Default shows what would be deleted
+- **--force**: Required to actually delete
+- **--dry-run**: Preview collision detection
+- **Dependency checks**: Fails if issue has dependents (unless --cascade or --force)
+
+## Batch Deletion
+
+- Delete multiple: `bd delete bd-1 bd-2 bd-3 --force`
+- Delete from file: `bd delete --from-file deletions.txt --force`
+
+## Dependency Handling
+
+- **Default**: Fails if issue has dependents not in deletion set
+- **--cascade**: Recursively delete all dependent issues
+- **--force**: Delete and orphan dependents
+
+## What Gets Deleted
+
+1. All dependency links (any type, both directions)
+2. Text references updated to "[deleted:ID]" in connected issues
+3. Issue removed from database
+
+This operation cannot be undone. Use with caution!

commands/dep.md

@@ -0,0 +1,38 @@
+---
+description: Manage dependencies between issues
+argument-hint: [command] [from-id] [to-id]
+---
+
+Manage dependencies between beads issues.
+
+## Available Commands
+
+- **add**: Add a dependency between issues
+  - $1: "add"
+  - $2: From issue ID
+  - $3: To issue ID
+  - $4: Dependency type (blocks, related, parent-child, discovered-from)
+
+- **remove**: Remove a dependency
+  - $1: "remove"
+  - $2: From issue ID
+  - $3: To issue ID
+
+- **tree**: Show dependency tree for an issue
+  - $1: "tree"
+  - $2: Issue ID
+
+- **cycles**: Detect dependency cycles
+
+## Dependency Types
+
+- **blocks**: Hard blocker (from blocks to) - affects ready queue
+- **related**: Soft relationship - for context only
+- **parent-child**: Epic/subtask relationship
+- **discovered-from**: Track issues found during work
+
+## Examples
+
+- `bd dep add bd-10 bd-20 --type blocks`: bd-10 blocks bd-20
+- `bd dep tree bd-20`: Show what blocks bd-20 and what bd-20 blocks
+- `bd dep cycles`: Check for circular dependencies

commands/epic.md

@@ -0,0 +1,26 @@
+---
+description: Epic management commands
+argument-hint: [command]
+---
+
+Manage epics (large features composed of multiple issues).
+
+## Available Commands
+
+- **status**: Show epic completion status
+  - Shows progress for each epic
+  - Lists child issues and their states
+  - Calculates completion percentage
+
+- **close-eligible**: Close epics where all children are complete
+  - Automatically closes epics when all child issues are done
+  - Useful for bulk epic cleanup
+
+## Epic Workflow
+
+1. Create epic: `bd create "Large Feature" -t epic -p 1`
+2. Link subtasks: `bd dep add bd-10 bd-20 --type parent-child` (epic bd-10 is parent of task bd-20)
+3. Track progress: `bd epic status`
+4. Auto-close when done: `bd epic close-eligible`
+
+Epics use parent-child dependencies to track subtasks.

commands/export.md

@@ -0,0 +1,24 @@
+---
+description: Export issues to JSONL format
+argument-hint: [-o output-file]
+---
+
+Export all issues to JSON Lines format (one JSON object per line).
+
+## Usage
+
+- **To stdout**: `bd export`
+- **To file**: `bd export -o issues.jsonl`
+- **Filter by status**: `bd export --status open`
+
+Issues are sorted by ID for consistent diffs, making git diffs readable.
+
+## Automatic Export
+
+The daemon automatically exports to `.beads/issues.jsonl` after any CRUD operation (5-second debounce). Manual export is rarely needed unless you need a custom output location or filtered export.
+
+Export is used for:
+- Git version control
+- Backup
+- Sharing issues between repositories
+- Data migration

commands/import.md

@@ -0,0 +1,36 @@
+---
+description: Import issues from JSONL format
+argument-hint: [-i input-file]
+---
+
+Import issues from JSON Lines format (one JSON object per line).
+
+## Usage
+
+- **From stdin**: `bd import` (reads from stdin)
+- **From file**: `bd import -i issues.jsonl`
+- **Preview**: `bd import -i issues.jsonl --dry-run`
+- **Resolve collisions**: `bd import -i issues.jsonl --resolve-collisions`
+
+## Behavior
+
+- **Existing issues** (same ID): Updated with new data
+- **New issues**: Created
+- **Collisions** (same ID, different content): Detected and reported
+
+## Collision Handling
+
+When merging branches or pulling changes, ID collisions can occur:
+
+- **--dry-run**: Preview collisions without making changes
+- **--resolve-collisions**: Automatically remap colliding issues to new IDs
+- All text references and dependencies are automatically updated
+
+## Automatic Import
+
+The daemon automatically imports from `.beads/issues.jsonl` when it's newer than the database (e.g., after `git pull`). Manual import is rarely needed.
+
+## Options
+
+- **--skip-existing**: Skip updates to existing issues
+- **--strict**: Fail on dependency errors instead of warnings

commands/label.md

@@ -0,0 +1,33 @@
+---
+description: Manage issue labels
+argument-hint: [command] [issue-id] [label]
+---
+
+Manage labels on beads issues. Labels provide flexible cross-cutting metadata beyond structured fields (status, priority, type).
+
+## Available Commands
+
+- **add**: Add a label to an issue
+  - $1: "add"
+  - $2: Issue ID
+  - $3: Label name
+
+- **remove**: Remove a label from an issue
+  - $1: "remove"
+  - $2: Issue ID
+  - $3: Label name
+
+- **list**: List labels on a specific issue
+  - $1: "list"
+  - $2: Issue ID
+
+- **list-all**: Show all labels used across all issues
+
+## Common Label Use Cases
+
+- Technical scope: `backend`, `frontend`, `api`, `database`
+- Quality gates: `needs-review`, `needs-tests`, `security-review`
+- Effort sizing: `quick-win`, `complex`, `spike`
+- Context: `technical-debt`, `documentation`, `performance`
+
+Use `bd label add <issue-id> <label>` to tag issues with contextual metadata.

commands/list.md

@@ -0,0 +1,30 @@
+---
+description: List issues with optional filters
+argument-hint: [--status] [--priority] [--type] [--assignee] [--label]
+---
+
+List beads issues with optional filtering.
+
+## Filters
+
+- **--status, -s**: Filter by status (open, in_progress, blocked, closed)
+- **--priority, -p**: Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)
+- **--type, -t**: Filter by type (bug, feature, task, epic, chore)
+- **--assignee, -a**: Filter by assignee
+- **--label, -l**: Filter by labels (comma-separated, must have ALL labels)
+- **--title**: Filter by title text (case-insensitive substring match)
+- **--limit, -n**: Limit number of results
+
+## Examples
+
+- `bd list --status open --priority 1`: High priority open issues
+- `bd list --type bug --assignee alice`: Alice's assigned bugs
+- `bd list --label backend,needs-review`: Backend issues needing review
+- `bd list --title "auth"`: Issues with "auth" in the title
+
+## Output Formats
+
+- Default: Human-readable table
+- `--json`: JSON format for scripting
+- `--format digraph`: Graph format for golang.org/x/tools/cmd/digraph
+- `--format dot`: Graphviz DOT format

commands/quickstart.md

@@ -0,0 +1,17 @@
+---
+description: Quick start guide for bd workflows
+argument-hint: []
+---
+
+Display a quick start guide showing common bd workflows and patterns.
+
+Use `bd quickstart` to see:
+- Getting started with bd
+- Common workflow patterns
+- Basic commands
+- Dependency management
+- Git integration
+
+This is an interactive tutorial that walks through the essential bd commands and concepts for new users.
+
+No arguments needed - just run `bd quickstart` to see the full guide.

commands/rename-prefix.md

@@ -0,0 +1,24 @@
+---
+description: Rename the issue prefix for all issues
+argument-hint: <new-prefix> [--dry-run]
+---
+
+Rename the issue prefix for all issues in the database.
+
+Updates all issue IDs and all text references across all fields.
+
+## Prefix Rules
+
+- Max length: 8 characters
+- Allowed: lowercase letters, numbers, hyphens
+- Must start with a letter
+- Must end with a hyphen (e.g., 'kw-', 'work-')
+
+## Usage
+
+- **Preview**: `bd rename-prefix kw- --dry-run`
+- **Apply**: `bd rename-prefix kw-`
+
+Example: Rename from 'knowledge-work-' to 'kw-'
+
+All dependencies and text references are automatically updated.

commands/renumber.md

@@ -0,0 +1,29 @@
+---
+description: Renumber all issues sequentially
+argument-hint: [--dry-run] [--force]
+---
+
+Renumber all issues sequentially to eliminate gaps in the ID space.
+
+## What It Does
+
+- Renumber all issues starting from 1 (keeps chronological order)
+- Update all dependency links (all types)
+- Update all text references in descriptions, notes, acceptance criteria
+- Show mapping report: old ID -> new ID
+- Export updated database to JSONL
+
+## Usage
+
+- **Preview**: `bd renumber --dry-run`
+- **Apply**: `bd renumber --force`
+
+## Risks
+
+⚠️ **Warning**: This operation cannot be undone!
+
+- May break external references in GitHub issues, docs, commits
+- Git history may become confusing
+- Backup recommended before running
+
+Use sparingly - only when ID gaps are problematic.

commands/reopen.md

@@ -0,0 +1,22 @@
+---
+description: Reopen closed issues
+argument-hint: [issue-ids...] [--reason]
+---
+
+Reopen one or more closed issues.
+
+Sets status to 'open' and clears the closed_at timestamp. Emits a Reopened event.
+
+## Usage
+
+- **Reopen single**: `bd reopen bd-42`
+- **Reopen multiple**: `bd reopen bd-42 bd-43 bd-44`
+- **With reason**: `bd reopen bd-42 --reason "Found regression"`
+
+More explicit than `bd update --status open` - specifically designed for reopening workflow.
+
+Common reasons for reopening:
+- Regression found
+- Requirements changed
+- Incomplete implementation
+- New information discovered

commands/repos.md

@@ -0,0 +1,25 @@
+---
+description: Manage work across multiple repositories
+argument-hint: [command]
+---
+
+Manage work across multiple repositories when using a global daemon.
+
+**Requires**: Running global daemon (`bd daemon --global`)
+
+## Available Commands
+
+- **list**: List all cached repositories
+- **ready**: Show ready work across all repositories
+  - `--group`: Group results by repository
+- **stats**: Show combined statistics across all repositories
+- **clear-cache**: Clear all cached repository connections
+
+## Usage
+
+- `bd repos list` - See all repositories connected to global daemon
+- `bd repos ready` - View all ready work across projects
+- `bd repos ready --group` - Group ready work by repository
+- `bd repos stats` - Combined statistics from all repos
+
+Useful for managing multiple beads projects from a single global daemon.

commands/restore.md

@@ -0,0 +1,28 @@
+---
+description: Restore full history of compacted issue from git
+argument-hint: <issue-id>
+---
+
+Restore full history of a compacted issue from git version control.
+
+When an issue is compacted, the git commit hash is saved. This command:
+
+1. Reads the compacted_at_commit from the database
+2. Checks out that commit temporarily
+3. Reads the full issue from JSONL at that point in history
+4. Displays the full issue history (description, events, etc.)
+5. Returns to the current git state
+
+## Usage
+
+`bd restore bd-42`
+
+This is **read-only** - it does not modify the database or git state.
+
+Useful for:
+- Reviewing old issues after compaction
+- Recovering forgotten context
+- Audit trails
+- Historical research
+
+Requires git repository with issue history.

commands/stale.md

@@ -0,0 +1,25 @@
+---
+description: Show orphaned claims and dead executors
+argument-hint: [--release] [--threshold]
+---
+
+Show issues stuck in_progress with execution_state where the executor is dead or stopped.
+
+Helps identify orphaned work that needs manual recovery.
+
+## Stale Detection
+
+An issue is stale if:
+- It has an execution_state (claimed by an executor)
+- AND the executor status is 'stopped'
+- OR the executor's last_heartbeat is older than threshold
+
+Default threshold: 300 seconds (5 minutes)
+
+## Usage
+
+- **List stale issues**: `bd stale`
+- **Custom threshold**: `bd stale --threshold 600` (10 minutes)
+- **Auto-release**: `bd stale --release` (automatically release all stale issues)
+
+Useful for parallel execution systems where workers may crash or get stopped.

commands/sync.md

@@ -0,0 +1,28 @@
+---
+description: Synchronize issues with git remote
+argument-hint: [--dry-run] [--message]
+---
+
+Synchronize issues with git remote in a single operation.
+
+## Sync Steps
+
+1. Export pending changes to JSONL
+2. Commit changes to git
+3. Pull from remote (with conflict resolution)
+4. Import updated JSONL
+5. Push local commits to remote
+
+Wraps the entire git-based sync workflow for multi-device use.
+
+## Usage
+
+- **Basic sync**: `bd sync`
+- **Preview**: `bd sync --dry-run`
+- **Custom message**: `bd sync --message "Closed sprint issues"`
+- **Pull only**: `bd sync --no-push`
+- **Push only**: `bd sync --no-pull`
+
+## Note
+
+Most users should rely on the daemon's automatic sync (`bd daemon --auto-commit --auto-push`) instead of running manual sync. This command is useful for one-off syncs or when not using the daemon.