- Rewrite docs/core-concepts/index.md as 'How Beads Works' — the one canonical concept page (modeled on Gas City's how-gas-city-works): problem-first framing, the bead -> dependencies -> ready-work loop, hash IDs, the formula -> proto -> molecule/wisp pipeline, gates, Dolt sync, federation, and storage modes, led by four mermaid diagrams. Other pages link here instead of re-deriving the model. - Fact fixes caught while writing (verified against source/live help): hash IDs are content-derived SHA-256 (internal/types/id_generator.go), not random; bd pour/bd wisp/bd pin/bd hook are not commands (the real surface is bd mol pour, bd mol wisp, bd assign, bd update --claim); wisps are not stored in .beads-wisp/; cross-repo dependency syntax is external:<project>:<capability> (cmd/bd/dep.go); recovery index claimed SQLite errors in a Dolt product. - Section overview pages: rewrite workflows/index, extend recovery, multi-agent, and integrations indexes to list every child with one-line summaries; add reference/index and put it in the nav. - New concept diagrams: sequential-vs-hash ID merge collision (core-concepts/hash-ids) and embedded-vs-server mode (architecture/dolt). - website/README.md: real build/verify instructions and parallel-run status for the Docusaurus site. - Repoint example READMEs and page labels at the real quickstart page.
1.5 KiB
1.5 KiB
| title | description |
|---|---|
| Reference | Lookup material — configuration, git integration, JSON contracts, observability, troubleshooting, and the FAQ. |
Lookup material for beads: the pages here specify contracts and edge cases rather than teach concepts (that's How Beads Works).
Pages in this section
- Configuration — every config key, environment variable, default, and the precedence between them.
- Git Integration — hooks,
refs/dolt/data, role detection, and branchless (jujutsu) workflows. - Git Worktrees Guide — how beads behaves across worktrees sharing one repository.
- Protected Branches — sync-branch mode for repos where direct pushes to main are blocked.
- Advanced Features — rename, merge, compaction, and other power-user operations.
- JSON Output Schema Contract — the stability
contract behind every
--jsonflag. - Observability (OpenTelemetry) — traces and metrics bd can emit, and how to point them at a collector.
- Troubleshooting — symptom-first fixes for common failures (deeper runbooks live in Recovery).
- Antivirus False Positives — Windows AV heuristics and binary verification.
- FAQ — beads vs other trackers, and the questions everyone asks in week one.