---
purpose: Explain the repository Beads tracker and downstream patch records.
applies_to: Creating, updating, or closing repository issues.
entrypoint: Use br from the repository root.
verification: Run br show with the issue ID.
update_when: Tracker commands or downstream patch policy changes.
---

# Beads issue tracker

This repository tracks issues with `br` from
[Dicklesworthstone/beads_rust](https://github.com/Dicklesworthstone/beads_rust).

The shared issue state is `.beads/issues.jsonl`. Local SQLite databases,
locks, recovery files, and history backups are regenerated by `br` and ignored
by git.

Common commands:

```bash
br ready
br show <issue-id>
br create "Title" --type task --priority 2
br sync --import-only
br sync --flush-only
```

## Herdr downstream patches

Every Herdr downstream patch entry in its source manifest must reference an open
bead. The bead records the patch path, origin commit, why it remains necessary,
and the condition for removing it. Close the bead only after removing the patch
and verifying the affected package without it.
