* docs: align user docs and CLI reference with the v1.1.0 release The Mintlify site publishes from main, so the docs had drifted ahead of the latest release — documenting features that no released binary ships. - Remove architecture/storage-backends: v1.1.0 supports only Dolt (the SQLite/Postgres/MySQL backends are post-tag work on main). Redirect the old routes to /architecture/dolt and drop the alternate-backend claims from README, core-concepts, architecture index, and FAQ. - Stamp the docs homepage with the release: "These docs are for the 1.1.0 release" plus a link to the v1.1.0 release notes. - Regenerate the CLI reference (docs/cli-reference/, docs/CLI_REFERENCE.md, docs.json nav) from the released v1.1.0 binary via tools/docsmint: removes pages for post-1.1.0 commands (heartbeat, migrate-personal, reclaim, unclaim) and post-1.1.0 flags. - Fix hand-written pages that referenced post-1.1.0 CLI surface, verified against the v1.1.0 binary: bd dep relate/unrelate (not top-level relate/unrelate), bd admin reset (not bd reset), bd hooks list (not status), bd history / bd vc status (not vc log/diff), release the claim via bd assign + bd update (no bd unclaim), drop bd migrate-personal and bd daemon mentions, and reduce the Cursor integration page to the rules file that v1.1.0's bd setup cursor actually installs. - Stop documenting the BD_ALLOW_REMOTE_MIGRATE escape hatch (and the nonexistent-in-1.1.0 bd migrate --force): the remote-migrate gate prints its own operator guidance by design; docs now defer to it. * docs: auto-regenerate CLI reference Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29613329749 (generated with CI's canonical pinned build). See scripts/check-cli-docs-drift.sh for how drift is attributed. --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
3.5 KiB
3.5 KiB
| title | description |
|---|---|
| Issues & Dependencies | The issue model: fields, types, priorities, and the dependencies that decide what work is ready |
Understanding the issue model in beads.
Issue Structure
Every issue has:
bd show bd-42 --json
{
"id": "bd-42",
"title": "Implement authentication",
"description": "Add JWT-based auth",
"type": "feature",
"status": "open",
"priority": 1,
"labels": ["backend", "security"],
"created_at": "2024-01-15T10:30:00Z",
"updated_at": "2024-01-15T10:30:00Z"
}
Issue Types
| Type | Use Case |
|---|---|
bug |
Something broken that needs fixing |
feature |
New functionality |
task |
Work item (tests, docs, refactoring) |
epic |
Large feature with subtasks |
chore |
Maintenance (dependencies, tooling) |
Priorities
| Priority | Level | Examples |
|---|---|---|
| 0 | Critical | Security, data loss, broken builds |
| 1 | High | Major features, important bugs |
| 2 | Medium | Nice-to-have features, minor bugs |
| 3 | Low | Polish, optimization |
| 4 | Backlog | Future ideas |
Creating Issues
# Basic issue
bd create "Fix login bug" -t bug -p 1
# With description
bd create "Add password reset" \
--description="Users need to reset forgotten passwords via email" \
-t feature -p 2
# With labels
bd create "Update dependencies" -t chore -l "maintenance,security"
# JSON output for agents
bd create "Task" -t task --json
Dependencies
Blocking Dependencies
The blocks relationship affects the ready queue:
# Add dependency: bd-2 depends on bd-1
bd dep add bd-2 bd-1
# View dependencies
bd dep tree bd-2
# See blocked issues
bd blocked
# See ready work (not blocked)
bd ready
Structural Relationships
These don't affect the ready queue:
# Parent-child (epic subtasks)
bd create "Epic" -t epic
bd create "Subtask" --parent bd-42
# Discovered-from (found during work)
bd create "Found bug" --deps discovered-from:bd-42
# Related (soft link)
bd dep relate bd-1 bd-2
Dependency Types
| Type | Description | Ready Queue Impact |
|---|---|---|
blocks |
Hard dependency | Yes - blocked items not ready |
parent-child |
Epic/subtask hierarchy | No |
discovered-from |
Tracks origin of discovery | No |
related |
Soft relationship | No |
Hierarchical Issues
For large features, use hierarchical IDs:
# Create epic
bd create "Auth System" -t epic -p 1
# Returns: bd-a3f8e9
# Child tasks auto-number
bd create "Design login UI" --parent bd-a3f8e9 # bd-a3f8e9.1
bd create "Backend validation" --parent bd-a3f8e9 # bd-a3f8e9.2
# View hierarchy
bd dep tree bd-a3f8e9
Updating Issues
# Change status
bd update bd-42 --claim
# Change priority
bd update bd-42 --priority 0
# Add labels
bd update bd-42 --add-label urgent
# Multiple changes
bd update bd-42 --claim --priority 1 --add-label "in-review"
Closing Issues
# Simple close
bd close bd-42
# With reason
bd close bd-42 --reason "Implemented in PR #123"
# JSON output
bd close bd-42 --json
Searching and Filtering
# By status
bd list --status open
bd list --status in_progress
# By priority
bd list --priority 1
bd list --priority 0,1 # Multiple
# By type
bd list --type bug
bd list --type feature,task
# By label
bd list --label-any urgent,critical
bd list --label-all backend,security
# Combined filters
bd list --status open --priority 1 --type bug --json