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
34 lines
1.8 KiB
Markdown
34 lines
1.8 KiB
Markdown
---
|
|
title: Reference
|
|
description: 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](/core-concepts/index)).
|
|
|
|
## Pages in this section
|
|
|
|
- [Configuration](/reference/configuration) — every config key, environment
|
|
variable, default, and the precedence between them.
|
|
- [Git Integration](/reference/git-integration) — hooks, `refs/dolt/data`,
|
|
role detection, and branchless (jujutsu) workflows.
|
|
- [Git Worktrees Guide](/reference/worktrees) — how beads behaves across
|
|
worktrees sharing one repository.
|
|
- [Protected Branches](/reference/protected-branches) — sync-branch mode for
|
|
repos where direct pushes to main are blocked.
|
|
- [Advanced Features](/reference/advanced) — rename, merge, compaction, and
|
|
other power-user operations.
|
|
- [JSON Output Schema Contract](/reference/json-schema) — the stability
|
|
contract behind every `--json` flag.
|
|
- [Events Journal](/reference/events-journal) — the durable, replayable record
|
|
of committed mutations that external tooling tails, and its boundaries.
|
|
- [Observability (OpenTelemetry)](/reference/observability) — traces and
|
|
metrics bd can emit, and how to point them at a collector.
|
|
- [Troubleshooting](/reference/troubleshooting) — symptom-first fixes for
|
|
common failures (deeper runbooks live in [Recovery](/recovery/index)).
|
|
- [Antivirus False Positives](/reference/antivirus) — Windows AV heuristics
|
|
and binary verification.
|
|
- [FAQ](/reference/faq) — beads vs other trackers, and the questions
|
|
everyone asks in week one.
|
|
- [CLI Reference](/cli-reference/index) — the generated page-per-command
|
|
reference, nested below as a collapsible group.
|