beads-docs

# Writing beads docs This is the house style for `docs/` — the beads user documentation, published as a Mintlify site. The goal is docs that motivate before they jargon, say the same thing the same way everywhere, show concepts as pictures and snippets instead of walls of prose, and never drift from the code. Apply it to any page you create, edit, or review. The audience of `docs/` is a **user** of beads — a human or agent installing `bd`, tracking work, and syncing it. Contributor-facing material lives in `engdocs/` and `AGENTS.md` and follows different rules (it may describe the implementation literally). When this skill says "the docs," it means `docs/`. ## 1. The canonical model Beads is a dependency-aware issue graph with a workflow layer on top. Teach it consistently and link to the canonical concept page — **`docs/core-concepts/index.md`** — rather than re-explaining it. | Concept | Role | Key idea | |---|---|---| | **bead** (issue) | the unit of work | one tracked item with a hash ID (`bd-a1b2`), type, status, priority; "bead" and "issue" name the same thing | | **dependency** | ordering | `blocks` edges hide a bead from agents until its blockers close; `parent-child`, `related`, `discovered-from` organize without blocking | | **ready work** | what `bd ready` computes | open beads with no open blockers, excluding in_progress, blocked, deferred, and hooked — the claimable frontier | | **formula** | workflow source | a TOML/JSON file defining a DAG of steps; `bd co...