mirror of
https://github.com/gastownhall/beads.git
synced 2026-09-14 20:17:24 +08:00
CI Bot
98a849fdeb
Adds docs/reference/events-journal.md: what the journal is (a durable, replayable, clone-local record of committed mutations), how to enable it, the record contract and its seven ops, the typed truncation error and how a consumer recovers, manual pruning and the retention floors, the boundaries (per replica, per branch, sync/raw SQL/store-open/compaction non-coverage), and how the dolt_ignored tables sit in Dolt. Every technical claim is derived from the code on this branch — cmd/bd events help text, the issueops journal engine, the migrations, and the config defaults — and states the same contract the CLI help does. It lands in Reference rather than Core Concepts because the page specifies a machine-facing contract rather than teaching the bead/dependency model; it sits beside the JSON output contract and observability, the two other pages an integrator reads. A short orientation section separates the three event-ish systems (script hooks, audit history, the journal) so a reader picks the right one, and reference/advanced.md no longer claims there is no `bd events` command. CHANGELOG records the new commands, the opt-in journal and its three config keys, the events_journal_truncated failure mode, and is_blocked joining the documented /v0 issue schemas. Both the page and migration 0064's down script also record the one destructive outcome that raises no error: dropping and recreating the journal tables, or losing bd_events_seq, restarts the sequence space at 1, so a parked consumer's checkpoint sits above the new head and reads as "caught up" forever. Nothing about the new journal looks pruned, so the typed truncation error cannot report it — the only remedy is to re-baseline, and the only defence is saying so where someone will be standing when it happens. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Agent-Signature: claude-code-claude-opus-5[1m]-unknown-reasoning on behalf of julianknutsen
1.8 KiB
1.8 KiB
title, description
| 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. - Events Journal — the durable, replayable record of committed mutations that external tooling tails, and its boundaries.
- 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.
- CLI Reference — the generated page-per-command reference, nested below as a collapsible group.