Commit graph

15 commits

Author SHA1 Message Date
Julian Knutsen
7505e173f2
chore(release): forward-port v1.2.2 to main (version record, retracts, recovery guide, gate record) (#5782) 2026-08-14 21:45:02 -07:00
Steve Yegge
4ad99760b8 docs(federation): GCS/S3 BYO-bucket federation quickstart (wy-jpd3.8)
The gs:// remote path works — full clone of a 115k-chunk production DB in
5 seconds, incremental syncs in ~4s, ADC auth, zero servers — but nothing
in the docs said "point two machines at a bucket and you have a
federation", so discovering it meant reading Dolt internals.

New page docs/multi-agent/bucket-federation.md walks the whole path:
create the bucket path -> bd dolt remote add + bd dolt push to seed ->
bd init --remote to birth the second replica -> bd sync on a timer, with
the exit-code table a timer branches on and the three rules that set the
interval (staleness is the interval; lease TTL and reclaim grace must
exceed it; a longer interval means more conflicts, because updated_at is
touched by every mutation).

Carries the measured cost from a production two-machine deployment
(28s cold push, 5s clone, ~4s incremental push, ~1s pull+merge at ~1.3k
issues / ~115k chunks) and the failure modes that path actually hits:
raw `dolt remote add` leaving the SQL server blind to the remote, a
fresh machine with no Dolt commit identity failing even a no-op merge,
server-mode credentials being whatever the server inherited at startup
(GH#6), remote-name drift between replicas, conflict resolution through
the dolt_conflicts tables, and one bucket path per database.

Registered in the Mintlify nav and cross-linked from the multi-agent
index and from the federation guide, which keeps DoltHub as the
zero-config default and points here for the BYO-cloud story.
2026-08-12 04:15:56 -07:00
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
Kevin Chan
59cfc4a000
[codex] Add Kiro setup recipe (#4535)
* Add Kiro setup recipe

* docs: register integrations/kiro in docs.json navigation

The docsync guard (TestEveryDocsPageIsPublished) requires every docs/ page
in the Mintlify nav; it landed after this PR was written.

Agent-Signature: claude-fable-5-high on behalf of maphew
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01P3JtQ3ukoVmfg6LCKcKBBh

---------

Co-authored-by: matt wilkie <maphew@gmail.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
2026-07-27 22:28:43 -07:00
Steve Yegge
f6d8d56ac7
Merge pull request #4864 from gastownhall/docs/bd-okqpv-history-squash-runbook
docs(recovery): history-squash runbook (bd-okqpv / wy-7lmdp)
2026-07-17 20:38:17 -07:00
Chris Sells
d2f87d50de
docs(pipeline): pin the CLI docs to the released bd; repair main's broken CLI reference (#4876)
* docs(pipeline): pin the generated CLI docs to the released bd; repair main's CLI reference

The #4874 squash-merge raced the docs-autofix bot: the bot had pushed a
regeneration from main's source onto the PR branch, so the squash landed a
contradictory mix — the release-aligned hand-written docs plus a CLI
reference re-documenting unreleased commands and flags, with docs.json
referencing four pages (heartbeat, migrate-personal, reclaim, unclaim)
whose files do not exist. That broken nav fails the docsync guard on main
and on every branch cut from it. This restores the intended end state of
#4874 and lands the pin that prevents the race from recurring.

- Regenerate the CLI reference from a bd built from the v1.1.0 tag (CI's
  canonical pure-Go build), removing the unreleased commands/flags and
  fixing the dangling nav entries.
- docs/cli-docs.pin names the release tag; scripts/resolve-docs-bd.sh
  builds and caches a canonical pure-Go bd from that tag, fetching the tag
  first in shallow CI checkouts.
- generate-cli-docs.sh, check-doc-flags.sh, and check-cli-docs-drift.sh
  resolve bd through the pin and ignore a supplied binary while pinned
  (BD_DOCS_IGNORE_PIN=1 bypasses), so the drift gates and the autofix bot
  now enforce docs-match-release instead of docs-match-main.
- tools/docsmint detects the pre-overhaul Docusaurus staging layout that
  bd <= v1.1.0 emits and converts it to the generic form before its normal
  Mintlify transform (tested); removable once the pin reaches a release
  whose emitter writes build/cli-docs.
- check-doc-flags.sh: run without timeout(1) on macOS instead of failing
  Check 4.
- Decision record: engdocs/decisions/2026-07-17-docs-release-pin.md; the
  beads-docs skill §8 updated to match.

* lint: annotate gosec G705 false positive in the docsmint legacy bridge

Same class as the existing nav-splice annotation: a developer tool writing
repo Markdown, not a web-output sink.
2026-07-17 18:03:28 -07:00
Chris Sells
8c974d8dc4
docs: align user docs and CLI reference with the v1.1.0 release (#4874)
* docs: align user docs and CLI reference with the v1.1.0 release

The Mintlify site publishes from main, so the docs had drifted ahead of the
latest release — documenting features that no released binary ships.

- Remove architecture/storage-backends: v1.1.0 supports only Dolt (the
  SQLite/Postgres/MySQL backends are post-tag work on main). Redirect the
  old routes to /architecture/dolt and drop the alternate-backend claims
  from README, core-concepts, architecture index, and FAQ.
- Stamp the docs homepage with the release: "These docs are for the 1.1.0
  release" plus a link to the v1.1.0 release notes.
- Regenerate the CLI reference (docs/cli-reference/, docs/CLI_REFERENCE.md,
  docs.json nav) from the released v1.1.0 binary via tools/docsmint: removes
  pages for post-1.1.0 commands (heartbeat, migrate-personal, reclaim,
  unclaim) and post-1.1.0 flags.
- Fix hand-written pages that referenced post-1.1.0 CLI surface, verified
  against the v1.1.0 binary: bd dep relate/unrelate (not top-level
  relate/unrelate), bd admin reset (not bd reset), bd hooks list (not
  status), bd history / bd vc status (not vc log/diff), release the claim
  via bd assign + bd update (no bd unclaim), drop bd migrate-personal and
  bd daemon mentions, and reduce the Cursor integration page to the rules
  file that v1.1.0's bd setup cursor actually installs.
- Stop documenting the BD_ALLOW_REMOTE_MIGRATE escape hatch (and the
  nonexistent-in-1.1.0 bd migrate --force): the remote-migrate gate prints
  its own operator guidance by design; docs now defer to it.

* docs: auto-regenerate CLI reference

Applied from the cli-docs-freshness-patch artifact of https://github.com/gastownhall/beads/actions/runs/29613329749
(generated with CI's canonical pinned build). See
scripts/check-cli-docs-drift.sh for how drift is attributed.

---------

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
2026-07-17 14:17:28 -07:00
Steve Yegge
d431fe8b55 docs(recovery): history-squash runbook — shed reachable history dolt gc can't reclaim (bd-okqpv)
Fenced-window procedure: backup, soft-reset squash to a baseline commit,
drop stale refs, gc --full, force re-publish, re-clone everywhere else.
Motivated by the wyvern deployment's 3.6G of reachable lease-churn
history (wy-7lmdp).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-17 01:53:45 -07:00
matt wilkie
ee7e494147
docs: redirect legacy GitHub Pages site to Mintlify (#4759)
* docs: redirect legacy Pages site to Mintlify (mybd-aokv)

Agent-Signature: codex-gpt-5.6-sol-high on behalf of matt wilkie

* docs: harden legacy Pages redirect

Agent-Signature: codex-gpt-5.6-terra-medium on behalf of matt wilkie
2026-07-13 14:19:13 -07:00
Chris Sells
69e33099b8 docs: apply PR #4722 review feedback to user docs
- FAQ: fix bulk migration/export commands (tracker pull/push need explicit
  IDs; bulk lives on sync --pull-only / --pull / --push-only / --push) and
  correct the cross-project isolation claim (hydration + external targets)
- quickstart: replace the broken DOLT.md blob URL with site links
- installation: Quick Install Script heading matches its macOS/Linux/FreeBSD
  body
- rewrite 33 stale SCREAMING_CASE link labels to the target pages' titles
- add description frontmatter to the 55 authored pages missing it
- docs.json: wildcard redirects for the old /next/ and version-prefixed
  route spaces (1.0.0, 1.0.4, 1.0.5)
2026-07-12 11:06:57 -07:00
Chris Sells
cf2711f13e docs(nav): nest the CLI Reference under Reference
The 113-page generated CLI Reference moves from a top-level nav group to
a nested group inside Reference — Mintlify renders nested groups
collapsed by default, so the command list no longer dominates the
sidebar. The docsmint nav splice is depth-agnostic (indentation is
derived from the pages key's line), verified by regenerating and by
re-pointing its test fixture at the nested shape. Reference overview and
the beads-docs skill IA note updated.
2026-07-12 10:37:17 -07:00
Chris Sells
874e74bdf3 docs: replace pointer stubs with Mintlify redirects
Per decision 6: the eleven pointer stubs at old top-level docs/ paths are
deleted; the docs.json redirects array now maps every moved page's old
route to its new home (43 entries covering the full pre-port top-level
namespace). The docsync exemption list shrinks to the one generated file
(docs/CLI_REFERENCE.md). Plugin and npm-package quickstart pointers now
link the real in-repo page.

Old GitHub deep links to the deleted paths 404 from here on — accepted in
the decision record; bd's own printed paths are updated to the new
locations in the next commit, so only already-released binaries are
affected.
2026-07-12 10:37:17 -07:00
Chris Sells
73a4d95fbc docs(emitter): bd emits generic Markdown only; Mintlify targeting moves to tools/docsmint
Per the decision record (engdocs/decisions/2026-07-10-mintlify-docs-overhaul.md):
bd's doc generator is vendor-neutral. `bd help --docs-root` now writes
docs/CLI_REFERENCE.md plus a generic per-command tree (title/description
frontmatter, portable CommonMark, HTML-comment markers) into build/cli-docs/
— uncommitted staging, gitignored. All site-generator-specific output leaves
the binary: Docusaurus frontmatter, sidebarPositionMap, the website/ writers,
the Mintlify writers, the docs.json nav splice, and the --docs-version
snapshot flag are gone from cmd/bd.

tools/docsmint (Go, unit-tested) is the Mintlify post-processor: it turns
the staging tree into the committed docs/cli-reference/ pages (JSX comment
markers, extensionless route links) and splices the CLI Reference pages
array in docs/docs.json. scripts/generate-cli-docs.sh runs both stages;
--check seeds the committed artifacts into a scratch root, regenerates, and
diffs, exactly as before.

Regenerated output: the 113 pages are byte-identical through the new
pipeline; docs.json nav ordering is now plain filename sort;
docs/CLI_REFERENCE.md drops the removed --docs-version flag.

`bd help --doc <cmd>` stdout is likewise generic now (no Docusaurus
id/slug/sidebar_position).
2026-07-12 10:37:07 -07:00
Chris Sells
54a7547b0d docs: canonical concept page, section overviews, and concept diagrams
- 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.
2026-07-12 10:37:07 -07:00
Chris Sells
4ea6fa3ac0 docs(emitter): emit Mintlify CLI reference and generated docs.json nav
bd help --docs-root now additionally writes docs/cli-reference/ in Mintlify
form (frontmatter title as H1, extensionless root-relative links, JSX
auto-generated markers since Mintlify parses .md through MDX) and rewrites
the CLI Reference pages array inside docs/docs.json via a textual splice
that leaves the rest of the file byte-identical — the ~113 nav entries are
never hand-maintained. The Docusaurus outputs (docs/CLI_REFERENCE.md,
website/docs/cli-reference/, versioned snapshots) are unchanged.

generate-cli-docs.sh --check seeds docs/docs.json and docs/cli-reference/
into its scratch root and diffs both; check-cli-docs-drift.sh adds them to
GEN_PATHSPECS and the regeneration fingerprint; docs-autofix-push.sh
allowlists the new generated paths; check-doc-flags.sh scans the new
docs/ subdirectories and requires command coverage in docs/cli-reference/.

Includes the initial docs/docs.json scaffold (nav mirrors the Docusaurus
sidebar IA) and the generated docs/cli-reference/ pages.

TDD: new emitter behavior covered in cmd/bd/help_all_test.go
(Mintlify page format, nav splice correctness + idempotence, bare-root
generation without docs.json).
2026-07-12 10:37:07 -07:00