viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(ux): consolidate Launch Swarm + telemetry UX with minimized strip

Browse source 
- Removed broken LaunchSwarmDialog (formula-based) from TopBar/LeftPanel
- All Rocket buttons (TopBar, LeftPanel, DAG nodes, social cards) now open
  AssignmentPanel (archetype-based) which actually works
- Every Rocket clears taskId first so assignMode && !taskId condition passes
- Conversation button priority: taskId always shows conversation, not assign panel
- Added TelemetryStrip: minimized right sidebar with status dots when non-telemetry
  panel (conversation/assignment) is active
- Live feed has minimize button → restores last taskId or assignMode
- DAG nodes: Signal icon → restores telemetry feed
- Social button on DAG nodes: single router.push to avoid race (setView + setTaskId)
- Fixed social card message button: opens right panel with drawer:closed (no popup)

Co-Authored-By: Oz <oz-agent@warp.dev>
This commit is contained in:
zenchantlive 2026-03-01 18:17:58 -08:00
parent 65d69ecbbc
commit c246ceaf21
165 changed files with 13730 additions and 1132 deletions
Download patch file Download diff file Expand all files Collapse all files

50
help/cli/agent-help.txt Normal file
View file

@ -0,0 +1,50 @@
Manage state on agent beads for ZFC-compliant state reporting.
Agent beads (labeled gt:agent) can self-report their state using these commands.
This enables the Witness and other monitoring systems to track agent health.
States:
idle - Agent is waiting for work
spawning - Agent is starting up
running - Agent is executing (general)
working - Agent is actively working on a task
stuck - Agent is blocked and needs help
done - Agent completed its current work
stopped - Agent has cleanly shut down
dead - Agent died without clean shutdown (set by Witness via timeout)
Examples:
bd agent state gt-emma running # Set emma's state to running
bd agent heartbeat gt-emma # Update emma's last_activity timestamp
bd agent show gt-emma # Show emma's agent details
Usage:
bd agent [command]
Available Commands:
backfill-labels Backfill role_type/rig labels on existing agent beads
heartbeat Update agent last_activity timestamp
show Show agent bead details
state Set agent state
Flags:
-h, --help help for agent
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output
Use "bd agent [command] --help" for more information about a command.

31
help/cli/bd-branch-help.txt Normal file
View file

@ -0,0 +1,31 @@
List all branches or create a new branch.
This command requires the Dolt storage backend. Without arguments,
it lists all branches. With an argument, it creates a new branch.
Examples:
bd branch # List all branches
bd branch feature-xyz # Create a new branch named feature-xyz
Usage:
bd branch [name] [flags]
Flags:
-h, --help help for branch
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output

0
help/cli/bd-config-list.txt Normal file
View file

61
help/cli/bd-create-help.txt Normal file
View file

@ -0,0 +1,61 @@
Create a new issue (or multiple issues from markdown file)
Usage:
bd create [title] [flags]
Aliases:
create, new
Flags:
--acceptance string Acceptance criteria
--agent-rig string Agent's rig name (requires --type=agent)
--append-notes string Append to existing notes (with newline separator)
-a, --assignee string Assignee
--body-file string Read description from file (use - for stdin)
--defer string Defer until date (issue hidden from bd ready until then). Same formats as --due
--deps strings Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20')
-d, --description string Issue description
--design string Design notes
--dry-run Preview what would be created without actually creating
--due string Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15
--ephemeral Create as ephemeral (short-lived, subject to TTL compaction)
-e, --estimate int Time estimate in minutes (e.g., 60 for 1 hour)
--event-actor string Entity URI who caused this event (requires --type=event)
--event-category string Event category (e.g., patrol.muted, agent.started) (requires --type=event)
--event-payload string Event-specific JSON data (requires --type=event)
--event-target string Entity URI or bead ID affected (requires --type=event)
--external-ref string External reference (e.g., 'gh-9', 'jira-ABC')
-f, --file string Create multiple issues from markdown file
--force Force creation even if prefix doesn't match database prefix
-h, --help help for create
--id string Explicit issue ID (e.g., 'bd-42' for partitioning)
-l, --labels strings Labels (comma-separated)
--metadata string Set custom metadata (JSON string or @file.json to read from file)
--mol-type string Molecule type: swarm (multi-polecat), patrol (recurring ops), work (default)
--no-inherit-labels Don't inherit labels from parent issue
--notes string Additional notes
--parent string Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
--prefix string Create issue in rig by prefix (e.g., --prefix bd- or --prefix bd or --prefix beads)
-p, --priority string Priority (0-4 or P0-P4, 0=highest) (default "2")
--repo string Target repository for issue (overrides auto-routing)
--rig string Create issue in a different rig (e.g., --rig beads)
--silent Output only the issue ID (for scripting)
--spec-id string Link to specification document
--title string Issue title (alternative to positional argument)
-t, --type string Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task")
--validate Validate description contains required sections for issue type
--waits-for string Spawner issue ID to wait for (creates waits-for dependency for fanout gate)
--waits-for-gate string Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children")
--wisp-type string Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd sync / bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
--json Output in JSON format
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables auto-sync
-v, --verbose Enable verbose/debug output

75
help/cli/bd-daemon-help.txt Normal file
View file

@ -0,0 +1,75 @@
Manage the background daemon that automatically syncs issues with git remote.
The daemon will:
- Poll for changes at configurable intervals (default: 5 seconds)
- Export pending database changes to JSONL
- Auto-commit changes if --auto-commit flag set
- Auto-push commits if --auto-push flag set
- Pull remote changes periodically
- Auto-import when remote changes detected
Common operations:
bd daemon start Start the daemon (background)
bd daemon start --foreground Start in foreground (for systemd/supervisord)
bd daemon stop Stop current workspace daemon
bd daemon status Show daemon status
bd daemon status --all Show all daemons with health check
bd daemon logs View daemon logs
bd daemon restart Restart daemon
bd daemon killall Stop all running daemons
Run 'bd daemon --help' to see all subcommands.
Usage:
bd daemon [flags]
bd daemon [command]
Available Commands:
health Check health of all bd daemons
killall Stop all running bd daemons
list List all running bd daemons
logs View logs for a specific bd daemon
restart Restart a specific bd daemon
start Start the background daemon
status Show daemon status
stop Stop a specific bd daemon
Flags:
--auto-commit Automatically commit changes
--auto-pull Automatically pull from remote (default: true when sync.branch configured)
--auto-push Automatically push commits
--federation Enable federation mode (runs dolt sql-server with remotesapi)
--federation-port int MySQL port for federation mode dolt sql-server (default 3307)
--foreground Run in foreground (don't daemonize)
--health Check daemon health (deprecated: use 'bd daemon status --all')
-h, --help help for daemon
--interval duration Sync check interval (default 5s)
--json Output JSON format
--local Run in local-only mode (no git required, no sync)
--log string Log file path (default: .beads/daemon.log)
--log-json Output logs in JSON format (structured logging)
--log-level string Log level (debug, info, warn, error) (default "info")
--metrics Show detailed daemon metrics
--remotesapi-port int remotesapi port for peer-to-peer sync in federation mode (default 8080)
--start Start the daemon (deprecated: use 'bd daemon start')
--status Show daemon status (deprecated: use 'bd daemon status')
--stop Stop running daemon (deprecated: use 'bd daemon stop')
--stop-all Stop all running bd daemons (deprecated: use 'bd daemon killall')
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output
Use "bd daemon [command] --help" for more information about a command.

34
help/cli/bd-diff-help.txt Normal file
View file

@ -0,0 +1,34 @@
Show the differences in issues between two commits or branches.
This command requires the Dolt storage backend. The refs can be:
- Commit hashes (e.g., abc123def)
- Branch names (e.g., main, feature-branch)
- Special refs like HEAD, HEAD~1
Examples:
bd diff main feature-branch # Compare main to feature branch
bd diff HEAD~5 HEAD # Show changes in last 5 commits
bd diff abc123 def456 # Compare two specific commits
Usage:
bd diff <from-ref> <to-ref> [flags]
Flags:
-h, --help help for diff
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output

75
help/cli/bd-dolt-help.txt Normal file
View file

@ -0,0 +1,75 @@
Configure and manage Dolt database settings and server lifecycle.
Beads uses a dolt sql-server for all database operations. The server is
auto-started transparently when needed. Use these commands for explicit
control or diagnostics.
Server lifecycle:
bd dolt start Start the Dolt server for this project
bd dolt stop Stop the Dolt server for this project
bd dolt status Show Dolt server status
Configuration:
bd dolt show Show current Dolt configuration with connection test
bd dolt set <k> <v> Set a configuration value
bd dolt test Test server connection
Version control:
bd dolt commit Commit pending changes
bd dolt push Push commits to Dolt remote
bd dolt pull Pull commits from Dolt remote
Remote management:
bd dolt remote add <name> <url> Add a Dolt remote
bd dolt remote list List configured remotes
bd dolt remote remove <name> Remove a Dolt remote
Configuration keys for 'bd dolt set':
database Database name (default: issue prefix or "beads")
host Server host (default: 127.0.0.1)
port Server port (auto-detected; override with bd dolt set port <N>)
user MySQL user (default: root)
data-dir Custom dolt data directory (absolute path; default: .beads/dolt)
Flags for 'bd dolt set':
--update-config Also write to config.yaml for team-wide defaults
Examples:
bd dolt set database myproject
bd dolt set host 192.168.1.100 --update-config
bd dolt set data-dir /home/user/.beads-dolt/myproject
bd dolt test
Usage:
bd dolt [command]
Available Commands:
clean-databases Drop stale test/polecat databases from the Dolt server
commit Create a Dolt commit from pending changes
killall Kill all orphan Dolt server processes
pull Pull commits from Dolt remote
push Push commits to Dolt remote
remote Manage Dolt remotes
set Set a Dolt configuration value
show Show current Dolt configuration with connection status
start Start the Dolt SQL server for this project
status Show Dolt server status
stop Stop the Dolt SQL server for this project
test Test connection to Dolt server
Flags:
-h, --help help for dolt
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd sync / bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
--json Output in JSON format
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables auto-sync
-v, --verbose Enable verbose/debug output
Use "bd dolt [command] --help" for more information about a command.

74
help/cli/bd-list-help.txt Normal file
View file

@ -0,0 +1,74 @@
List issues
Usage:
bd list [flags]
Flags:
--all Show all issues including closed (overrides default filter)
-a, --assignee string Filter by assignee
--closed-after string Filter issues closed after date (YYYY-MM-DD or RFC3339)
--closed-before string Filter issues closed before date (YYYY-MM-DD or RFC3339)
--created-after string Filter issues created after date (YYYY-MM-DD or RFC3339)
--created-before string Filter issues created before date (YYYY-MM-DD or RFC3339)
--defer-after string Filter issues deferred after date (supports relative: +6h, tomorrow)
--defer-before string Filter issues deferred before date (supports relative: +6h, tomorrow)
--deferred Show only issues with defer_until set
--desc-contains string Filter by description substring (case-insensitive)
--due-after string Filter issues due after date (supports relative: +6h, tomorrow)
--due-before string Filter issues due before date (supports relative: +6h, tomorrow)
--empty-description Filter issues with empty or missing description
--filter-parent string Alias for --parent
--format string Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template
-h, --help help for list
--id string Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)
--include-gates Include gate issues in output (normally hidden)
--include-templates Include template molecules in output
-l, --label strings Filter by labels (AND: must have ALL). Can combine with --label-any
--label-any strings Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
--label-pattern string Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)
--label-regex string Filter by label regex pattern (e.g., 'tech-(debt|legacy)')
-n, --limit int Limit results (default 50, use 0 for unlimited) (default 50)
--long Show detailed multi-line output for each issue
--mol-type string Filter by molecule type: swarm, patrol, or work
--no-assignee Filter issues with no assignee
--no-labels Filter issues with no labels
--no-pager Disable pager output
--no-pinned Exclude pinned issues
--notes-contains string Filter by notes substring (case-insensitive)
--overdue Show only issues with due_at in the past (not closed)
--parent string Filter by parent issue ID (shows children of specified issue)
--pinned Show only pinned issues
--pretty Display issues in a tree format with status/priority symbols
-p, --priority string Priority (0-4 or P0-P4, 0=highest)
--priority-max string Filter by maximum priority (inclusive, 0-4 or P0-P4)
--priority-min string Filter by minimum priority (inclusive, 0-4 or P0-P4)
--ready Show only ready issues (status=open, excludes hooked/in_progress/blocked/deferred)
-r, --reverse Reverse sort order
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
--spec string Filter by spec_id prefix
-s, --status string Filter by status (open, in_progress, blocked, deferred, closed)
--title string Filter by title text (case-insensitive substring match)
--title-contains string Filter by title substring (case-insensitive)
--tree Alias for --pretty: hierarchical tree format
-t, --type string Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule
--updated-after string Filter issues updated after date (YYYY-MM-DD or RFC3339)
--updated-before string Filter issues updated before date (YYYY-MM-DD or RFC3339)
-w, --watch Watch for changes and auto-update display (implies --pretty)
--wisp-type string Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output

85
help/cli/bd-query-help.txt Normal file
View file

@ -0,0 +1,85 @@
Query issues using a simple query language that supports compound filters,
boolean operators, and date-relative expressions.
The query language enables complex filtering that would otherwise require
multiple flags or piping through jq.
Syntax:
field=value Equality comparison
field!=value Inequality comparison
field>value Greater than
field>=value Greater than or equal
field<value Less than
field<=value Less than or equal
Boolean operators (case-insensitive):
expr AND expr Both conditions must match
expr OR expr Either condition can match
NOT expr Negates the condition
(expr) Grouping with parentheses
Supported fields:
status Issue status (open, in_progress, blocked, deferred, closed)
priority Priority level (0-4)
type Issue type (bug, feature, task, epic, chore)
assignee Assigned user (use "none" for unassigned)
owner Issue owner
label Issue label (use "none" for unlabeled)
title Search in title (contains)
description Search in description (contains, "none" for empty)
notes Search in notes (contains)
created Creation date/time
updated Last update date/time
closed Close date/time
id Issue ID (supports wildcards: bd-*)
spec Spec ID (supports wildcards)
pinned Boolean (true/false)
ephemeral Boolean (true/false)
template Boolean (true/false)
parent Parent issue ID
mol_type Molecule type (swarm, patrol, work)
Date values:
Relative durations: 7d (7 days ago), 24h (24 hours ago), 2w (2 weeks ago)
Absolute dates: 2025-01-15, 2025-01-15T10:00:00Z
Natural language: tomorrow, "next monday", "in 3 days"
Examples:
bd query "status=open AND priority>1"
bd query "status=open AND priority<=2 AND updated>7d"
bd query "(status=open OR status=blocked) AND priority<2"
bd query "type=bug AND label=urgent"
bd query "NOT status=closed"
bd query "assignee=none AND type=task"
bd query "created>30d AND status!=closed"
bd query "label=frontend OR label=backend"
bd query "title=authentication AND priority=0"
Usage:
bd query [expression] [flags]
Flags:
-a, --all Include closed issues (default: exclude closed)
-h, --help help for query
-n, --limit int Limit results (default: 50, 0 = unlimited) (default 50)
--long Show detailed multi-line output for each issue
--parse-only Only parse the query and show the AST (for debugging)
-r, --reverse Reverse sort order
--sort string Sort by field: priority, created, updated, closed, status, id, title, type, assignee
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output

38
help/cli/bd-vc-help.txt Normal file
View file

@ -0,0 +1,38 @@
Version control operations for the beads database.
These commands require the Dolt storage backend. They provide git-like
version control for your issue data, including branching, merging, and
viewing history.
Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access.
This subcommand provides additional operations like merge and commit.
Usage:
bd vc [command]
Available Commands:
commit Create a commit with all staged changes
merge Merge a branch into the current branch
status Show current branch and uncommitted changes
Flags:
-h, --help help for vc
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output
Use "bd vc [command] --help" for more information about a command.

136
help/cli/bd_help.txt Normal file
View file

@ -0,0 +1,136 @@
Issues chained together like beads. A lightweight issue tracker with first-class dependency support.
Usage:
bd [flags]
bd [command]
Maintenance:
rename-prefix Rename the issue prefix for all issues in the database
repair Repair corrupted database by cleaning orphaned references
resolve-conflicts Resolve git merge conflicts in JSONL files
Integrations & Advanced:
Working With Issues:
children List child beads of a parent
close Close one or more issues
comments View or manage comments on an issue
create Create a new issue (or multiple issues from markdown file)
create-form Create a new issue using an interactive form
delete Delete one or more issues and clean up references
edit Edit an issue field in $EDITOR
gate Manage async coordination gates
label Manage issue labels
list List issues
merge-slot Manage merge-slot gates for serialized conflict resolution
move Move an issue to a different rig with dependency remapping
promote Promote a wisp to a permanent bead
q Quick capture: create issue and output only ID
query Query issues using a simple query language
refile Move an issue to a different rig
reopen Reopen one or more closed issues
search Search issues by text query
set-state Set operational state (creates event + updates label)
show Show issue details
state Query the current value of a state dimension
todo Manage TODO items (convenience wrapper for task issues)
update Update one or more issues
Views & Reports:
activity Show real-time molecule state feed
count Count issues matching filters
diff Show changes between two commits or branches (requires Dolt backend)
find-duplicates Find semantically similar issues using text analysis or AI
history Show version history for an issue (requires Dolt backend)
lint Check issues for missing template sections
stale Show stale issues (not updated recently)
status Show issue database overview and statistics
types List valid issue types
Dependencies & Structure:
dep Manage dependencies
duplicate Mark an issue as a duplicate of another
duplicates Find and optionally merge duplicate issues
epic Epic management commands
graph Display issue dependency graph
supersede Mark an issue as superseded by a newer one
swarm Swarm management for structured epics
Sync & Data:
branch List or create branches (requires Dolt backend)
daemon Manage background sync daemon
export Export issues to JSONL or Obsidian format
federation Manage peer-to-peer federation (requires CGO)
import Import issues from JSONL format
merge Git merge driver for beads JSONL files
restore Restore full history of a compacted issue from git
sync Export database to JSONL (sync with git)
vc Version control operations (requires Dolt backend)
Setup & Configuration:
backend Manage storage backend configuration
config Manage configuration settings
hooks Manage git hooks for bd auto-sync
human Show essential commands for human users
info Show database and daemon information
init Initialize bd in the current directory
kv Key-value store commands
onboard Display minimal snippet for AGENTS.md
prime Output AI-optimized workflow context
quickstart Quick start guide for bd
setup Setup integration with AI editors
where Show active beads location
Maintenance:
doctor Check and fix beads installation health (start here)
migrate Database migration commands
preflight Show PR readiness checklist
upgrade Check and manage bd version upgrades
worktree Manage git worktrees for parallel development
Integrations & Advanced:
admin Administrative commands for database maintenance
jira Jira integration commands
linear Linear integration commands
repo Manage multiple repository configuration
Additional Commands:
agent Manage agent bead state
audit Record and label agent interactions (append-only JSONL)
blocked Show blocked issues
completion Generate the autocompletion script for the specified shell
cook Compile a formula into a proto (ephemeral by default)
defer Defer one or more issues for later
formula Manage workflow formulas
gitlab GitLab integration commands
help Help about any command
hook Execute a git hook (called by hook scripts)
mail Delegate to mail provider (e.g., gt mail)
mol Molecule commands (work templates)
orphans Identify orphaned issues (referenced in commits but still open)
ready Show ready work (open, no blockers)
rename Rename an issue ID
ship Publish a capability for cross-project dependencies
slot Manage agent bead slots
undefer Undefer one or more issues (restore to open)
version Print version information
Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
-h, --help help for bd
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output
-V, --version Print version information
Use "bd [command] --help" for more information about a command.

30
help/cli/epic-help.txt Normal file
View file

@ -0,0 +1,30 @@
Epic management commands
Usage:
bd epic [command]
Available Commands:
close-eligible Close epics where all children are complete
status Show epic completion status
Flags:
-h, --help help for epic
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output
Use "bd epic [command] --help" for more information about a command.

4
help/cli/epic.txt Normal file
View file

@ -0,0 +1,4 @@
✓ Created issue: beadboard-3xc
Title: Swarm Test: Order Processing System
Priority: P2
Status: open

136
help/cli/help.txt Normal file
View file

@ -0,0 +1,136 @@
Issues chained together like beads. A lightweight issue tracker with first-class dependency support.
Usage:
bd [flags]
bd [command]
Maintenance:
rename-prefix Rename the issue prefix for all issues in the database
repair Repair corrupted database by cleaning orphaned references
resolve-conflicts Resolve git merge conflicts in JSONL files
Integrations & Advanced:
Working With Issues:
children List child beads of a parent
close Close one or more issues
comments View or manage comments on an issue
create Create a new issue (or multiple issues from markdown file)
create-form Create a new issue using an interactive form
delete Delete one or more issues and clean up references
edit Edit an issue field in $EDITOR
gate Manage async coordination gates
label Manage issue labels
list List issues
merge-slot Manage merge-slot gates for serialized conflict resolution
move Move an issue to a different rig with dependency remapping
promote Promote a wisp to a permanent bead
q Quick capture: create issue and output only ID
query Query issues using a simple query language
refile Move an issue to a different rig
reopen Reopen one or more closed issues
search Search issues by text query
set-state Set operational state (creates event + updates label)
show Show issue details
state Query the current value of a state dimension
todo Manage TODO items (convenience wrapper for task issues)
update Update one or more issues
Views & Reports:
activity Show real-time molecule state feed
count Count issues matching filters
diff Show changes between two commits or branches (requires Dolt backend)
find-duplicates Find semantically similar issues using text analysis or AI
history Show version history for an issue (requires Dolt backend)
lint Check issues for missing template sections
stale Show stale issues (not updated recently)
status Show issue database overview and statistics
types List valid issue types
Dependencies & Structure:
dep Manage dependencies
duplicate Mark an issue as a duplicate of another
duplicates Find and optionally merge duplicate issues
epic Epic management commands
graph Display issue dependency graph
supersede Mark an issue as superseded by a newer one
swarm Swarm management for structured epics
Sync & Data:
branch List or create branches (requires Dolt backend)
daemon Manage background sync daemon
export Export issues to JSONL or Obsidian format
federation Manage peer-to-peer federation (requires CGO)
import Import issues from JSONL format
merge Git merge driver for beads JSONL files
restore Restore full history of a compacted issue from git
sync Export database to JSONL (sync with git)
vc Version control operations (requires Dolt backend)
Setup & Configuration:
backend Manage storage backend configuration
config Manage configuration settings
hooks Manage git hooks for bd auto-sync
human Show essential commands for human users
info Show database and daemon information
init Initialize bd in the current directory
kv Key-value store commands
onboard Display minimal snippet for AGENTS.md
prime Output AI-optimized workflow context
quickstart Quick start guide for bd
setup Setup integration with AI editors
where Show active beads location
Maintenance:
doctor Check and fix beads installation health (start here)
migrate Database migration commands
preflight Show PR readiness checklist
upgrade Check and manage bd version upgrades
worktree Manage git worktrees for parallel development
Integrations & Advanced:
admin Administrative commands for database maintenance
jira Jira integration commands
linear Linear integration commands
repo Manage multiple repository configuration
Additional Commands:
agent Manage agent bead state
audit Record and label agent interactions (append-only JSONL)
blocked Show blocked issues
completion Generate the autocompletion script for the specified shell
cook Compile a formula into a proto (ephemeral by default)
defer Defer one or more issues for later
formula Manage workflow formulas
gitlab GitLab integration commands
help Help about any command
hook Execute a git hook (called by hook scripts)
mail Delegate to mail provider (e.g., gt mail)
mol Molecule commands (work templates)
orphans Identify orphaned issues (referenced in commits but still open)
ready Show ready work (open, no blockers)
rename Rename an issue ID
ship Publish a capability for cross-project dependencies
slot Manage agent bead slots
undefer Undefer one or more issues (restore to open)
version Print version information
Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
-h, --help help for bd
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output
-V, --version Print version information
Use "bd [command] --help" for more information about a command.

32
help/cli/label-help.txt Normal file
View file

@ -0,0 +1,32 @@
Manage issue labels
Usage:
bd label [command]
Available Commands:
add Add a label to one or more issues
list List labels for an issue
list-all List all unique labels in the database
remove Remove a label from one or more issues
Flags:
-h, --help help for label
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output
Use "bd label [command] --help" for more information about a command.

42
help/cli/state-help.txt Normal file
View file

@ -0,0 +1,42 @@
Atomically set operational state on an issue.
This command:
1. Creates an event bead recording the state change (source of truth)
2. Removes any existing label for the dimension
3. Adds the new dimension:value label (fast lookup cache)
State labels follow the convention <dimension>:<value>, for example:
patrol:active, patrol:muted
mode:normal, mode:degraded
health:healthy, health:failing
Examples:
bd set-state witness-abc patrol=muted --reason "Investigating stuck polecat"
bd set-state witness-abc mode=degraded --reason "High error rate detected"
bd set-state witness-abc health=healthy
The --reason flag provides context for the event bead (recommended).
Usage:
bd set-state <issue-id> <dimension>=<value> [flags]
Flags:
-h, --help help for set-state
--reason string Reason for the state change (recorded in event)
Global Flags:
--actor string Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
--allow-stale Allow operations on potentially stale data (skip staleness check)
--db string Database path (default: auto-discover .beads/*.db)
--dolt-auto-commit string Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
--json Output in JSON format
--lock-timeout duration SQLite busy timeout (0 = fail immediately if locked) (default 30s)
--no-auto-flush Disable automatic JSONL sync after CRUD operations
--no-auto-import Disable automatic JSONL import when newer than DB
--no-daemon Force direct storage mode, bypass daemon if running
--no-db Use no-db mode: load from JSONL, no SQLite
--profile Generate CPU profile for performance analysis
-q, --quiet Suppress non-essential output (errors only)
--readonly Read-only mode: block write operations (for worker sandboxes)
--sandbox Sandbox mode: disables daemon and auto-sync
-v, --verbose Enable verbose/debug output

71
help/cli/true_agents.txt Normal file
View file

@ -0,0 +1,71 @@
bb-atf
bb-z6s
bb-54x
bb-nuy
bb-98c
bb-3ha
bb-22l
bb-5am
bb-dwz
bb-3dv
bb-only-ui-agent
bb-graph-agent-1
bb-ui-agent-2
bb-ui-agent-1
bb-verify-mlnavzwu
bb-final-mlnar702
bb-verify2-mlnaouad
bb-final-mlnalaqz
bb-bridge-fix-mlnaja4j
bb-verify-mlnadaip
bb-switch-mlna9nbo
bb-join-mlna9nbo
bb-invepic-mln9perd
bb-m2-mln9perd
bb-invalid-epic-mln9hraq
bb-m1-mln9perd
bb-leave-mln9perd
bb-member3-mln9hraq
bb-member2-mln9hraq
bb-member1-mln9hraq
bb-switch-mln9perd
bb-nolabel-test-mln9hraq
bb-join-mln9perd
bb-leave-test-mln9hraq
bb-idem-test-mln9hraq
bb-debug-mln9knzs
bb-switch-test-mln9hraq
bb-join-test-mln9hraq
bb-smoke-mln9e525
bb-idem-test-mln97lyt
bb-switch-test-mln97lyt
bb-join-test-mln97lyt
bb-switch-test-mln8xxn4
bb-join-test-mln8xxn4
bb-nolabel-test-mln8pdgh
bb-leave-test-mln8pdgh
bb-idem-test-mln8pdgh
bb-switch-test-mln8pdgh
bb-join-test-mln8pdgh
bb-leave-test-mln8hp8j
bb-idem-test-mln8hp8j
bb-switch-test-mln8hp8j
bb-join-test-mln8hp8j
bb-daemon-test-mln8e4tf
bb-fresh-test-mln8canu
bb-upd-test-mln8981k
bb-step-test-mln872rm
bb-debug-test-mln83q18
bb-switch-test-mln7xyls
bb-join-test-mln7xyls
bb-linus-swarm
bb-agent-graph-1
bb-1xj
bb-agent-a
bb-agent-b
bb-active-agent
bb-agent-ui-1
bb-green-falcon
bb-zenchantlive
bb-silver-castle
bb-test-agent