beads/docs/reference
CI Bot 98a849fdeb docs(events): document the events journal and bd events (bd-opisf)
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
2026-08-09 01:58:17 +00:00
..
advanced.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
antivirus.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
configuration.md Revert "Simplify the supported backends: roll back the direct PostgreSQL and MySQL adapters" (#4857) 2026-07-16 16:35:51 -07:00
events-journal.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
faq.md docs: align user docs and CLI reference with the v1.1.0 release (#4874) 2026-07-17 14:17:28 -07:00
git-integration.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
index.md docs(events): document the events journal and bd events (bd-opisf) 2026-08-09 01:58:17 +00:00
json-schema.md docs: re-review and bump the three 90-day-stale freshness markers (#5394) 2026-08-07 02:35:11 -07:00
observability.md refactor(telemetry): adopt standard OTel SDK env vars with BD_OTEL_* back-compat (#3859) 2026-08-03 00:05:06 -07:00
protected-branches.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
troubleshooting.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00
worktrees.md docs: apply PR #4722 review feedback to user docs 2026-07-12 11:06:57 -07:00