Three generated-content defects from the adversarial review, all
structurally invisible to the drift gate (generated-vs-generated):
- Usage lines now mirror Cobra's help template: a runnable command shows
its UseLine, a command with subcommands shows '<path> [command]', both
when both apply. Previously bare UseLine() stamped 'bd mol [flags]' on
30 parent pages — a line the binary never prints.
- The generated CLI index publishes the Global Flags block; the binary
prints it on every --help but no page carried it.
- docsmint neutralizes prose lines that Mintlify's prebuild would dedent
into MDX ESM blocks (a line beginning 'export'/'import' outside a
fence gets wrapped in a code span). This is why /cli-reference/mail
returned HTTP 200 while rendering only a parse-error placeholder —
reproduced, fixed, and covered by a planted-hazard test; fenced
content stays verbatim.
Also rewords check-cli-docs-drift.sh's early-PASS message, which
asserted 'the supplied binary differs' as the cause when uncommitted
local edits produce the same result.
All 113 pages + docs/CLI_REFERENCE.md regenerated through the pipeline;
TDD'd in cmd/bd/help_all_test.go and tools/docsmint/docsmint_test.go.
Verified live: /cli-reference/mail renders real content, zero parse
errors; generate-cli-docs.sh --check, docsync, freshness, and
mint broken-links all pass on this tree.
Every fix verified against the binary or a traced source call path:
- How Beads Works: parent-child DOES affect ready work (a blocked parent
blocks its children — the blocked-state SQL inherits it), hash-ID
inputs are title/description/creator/creation-time plus a collision
nonce (live generator is internal/idgen, not the legacy one), and
bead gates dropped from the gates bullet (currently unresolvable).
- Graph-link type strings are hyphenated (relates-to, replies-to);
underscore forms are rejected by the parser. Fixed corpus-wide
including the README feature bullet.
- upgrading.md: the version-era table's boundaries were refuted by git
archaeology (embedded Dolt shipped in v0.60.0 and always used
.beads/embeddeddolt/; nothing changed at the claimed v0.63.3
boundary) — replaced with a layout-based identification table.
- Phantom .beads/dolt/sql-server.log path in sync-failures and the FAQ;
the managed server writes .beads/dolt-server.log.
- FAQ: ID growth matches DefaultAdaptiveConfig (min 3, max 8,
probability-driven), dependency-type wording no longer claims exactly
four types, and unmeasured performance figures are hedged instead of
stated as facts.
- quickstart: bd migrate --cleanup doesn't exist; init installs hooks
by default (no prompt) and has no merge-driver step; ready output
quote and bd restore recovery source corrected.
- formulas.md: step types map to issue types (task/bug/feature/epic/
chore; anything else falls back to task — human/gate are not step
types), and there is no built-in formula search tier.
- todo.md: bd update takes --set-labels, not --labels.
- graph-links.md: broken #dependencies fragment → #add-dependencies.
Adversarial review falsified this page: 10 of its 12 checkable claims
contradicted the binary. It taught a phantom TOML gate schema (approvers,
require_all, duration, event, status, action, merged — all silently
dropped by the parser), phantom subcommands (bd gate approve/skip), a
nonexistent pending/open/closed state model, list-valued waits_for, and
7d durations that time.ParseDuration rejects.
Rewritten from source: the four-field [steps.gate] schema
(type/id/await_id/timeout per internal/formula/types.go), the real
subcommand set (list/create/show/resolve/check/add-waiter), gate types
with their closers (human resolves manually; timer and gh:* close via
bd gate check; bead gates currently unresolvable — multi-rig routing
removed), needs vs waits_for fan-in semantics, and a worked example
taken from beads' own release formula.
Closure: every TOML construct on the page round-trips intact through
bd formula show --json (gh:run/human/timer gates, needs, waits_for).
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.
make diagrams-excalidraw renders committed .excalidraw sources under
docs/diagrams/excalidraw/ to SVGs in docs/diagrams/excalidraw-rendered/
(idempotent, @swiftlysingh/excalidraw-cli via npx), matching the Gas City
convention. No diagrams authored yet — the nine existing diagrams stay
mermaid. The beads-docs skill names the real target and paths.
Per decision 7, bd's user-facing strings now reference the Mintlify-era
paths: prime policy-profiles help, storage-backend comparison help
(store_factory_nocgo, init --backend), init-safety help (recovery
playbooks now docs/recovery/init-safety.md; the ADR reference now
engdocs/adr/), the pk-fork-refused recovery URL (dolt.go), doctor's plugin
suggestions (claude.go) and managed-handoff pointer, aider setup guidance
and the shared recipe template (quickstart URL), and the agent instruction
templates (sync-concepts URL, quickstart URL). bd mol pour's help no
longer claims molecules are 'synced with git' — they sync via Dolt like
any other bead.
Also corrects the stale claude recipe ProjectPath metadata
(.claude/settings.local.json -> .claude/settings.json; the dedicated
installer has written settings.json since the migration sweep).
This repo's AGENTS.md managed section is refreshed to the new template
body (hash bacef91e, has-remote variant preserved), and agents.md.tmpl's
embedded marker matches. Template tests updated to pin the new fragment;
CLI docs regenerated.
Recorded, not fixed (behavior-level, see the decision record):
routing.mode's maintainer/contributor no-op values and the
sync.require_confirmation_on_mass_delete key with no consumer.
Note: TestCheckBeadsRole_NotConfigured/_NotGitRepo in cmd/bd/doctor fail
on any machine with beads.role in the global git config (no HOME
isolation) — pre-existing, unrelated to this change.
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.
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).
Sixteen same-ground pairs reconciled: the ported website page won and every
fact living only in the older docs/ original was merged in before deleting
it (INSTALLING, SETUP, ARCHITECTURE, CONFIG, GIT_INTEGRATION, ADVANCED,
TROUBLESHOOTING, FAQ, MOLECULES, ROUTING, MULTI_REPO_AGENTS, and the five
agent-integration guides). The two divergent FAQs are now one canonical
FAQ with the comparison-first framing leading and pre-1.0 version gating
removed.
The routing pair inverted: the ported page described a routing system that
does not exist (bd routes, bd hydrate, .beads/routes.jsonl); the page was
rebuilt from the accurate sources (ROUTING.md + MULTI_REPO_AGENTS.md)
against the real surface (routing.mode config, role detection,
repos.primary/additional hydration, --repo override).
Every claim was verified against the Go source or the generated CLI
reference. Phantom surfaces removed across the corpus: bd pin/hook/pour/
wisp/routes/hydrate/reserve/lock/merge/stats, bd hooks status, bd vc
conflicts/log, bd dolt set shared-server, fictional beads_* MCP tool names
(real names taken from beads-mcp server.py), import.orphan_handling and
export.error_policy config keys, database.wal_mode/cache_size, stale
.beads/dolt/sql-server.log paths, and SQLite-era file paths. Notable
corrections: min_hash_length default is 3, .beads/metadata.json is
git-tracked, tombstone status is removed, wisps live in the main database
under an ephemeral flag.
Freshness markers moved with their content (configuration, ide-setup) and
the freshness gate + DOC_INVENTORY ledger now point at the new locations.
Load-bearing anchors preserved: #branchless-workflows-jujutsu--jj,
#circuit-breaker-server-appears-down-failing-fast, #extensible-database,
#multi-repo-hydration. Pointer stubs remain at docs/{SETUP,INSTALLING,
GIT_INTEGRATION}.md because released binaries print those paths
(allowlisted in the docsync guard).
Gates: go test ./test/docsync PASS; generate-cli-docs.sh --check PASS;
check-doc-freshness.sh PASS; mint broken-links: no broken links; mint dev
serves all sections (11 routes spot-checked at 200).
README drops from 254 to ~190 lines: the server-mode connection table,
Unix-socket note, prune/purge maintenance semantics (including
reference-aware protection), and backup/migration walkthrough move into
docs/architecture/dolt.md, which now owns that material once. The README
keeps the pitch, quick start, features, essential commands, and a
condensed storage-modes summary with links, and gains a hero mermaid
diagram of the create -> ready -> claim -> close loop (GitHub renders
mermaid natively).
The ported workflow pages documented commands that do not exist in bd:
bd pour, bd wisp create/list/show/delete/cleanup, bd pin, bd hook, and a
.beads-wisp/ storage directory. Verified against the live binary: the
real surface is bd cook, bd mol pour, bd mol wisp (+ list/gc), bd mol
squash/burn, bd create --ephemeral, and bd purge; wisps are rows in the
main database with Ephemeral=true, excluded from federation push by
default, not a separate gitignored store.
Rewrote workflows/wisps.md around the verified lifecycle
(create -> execute -> squash or burn), fixed formulas.md instantiation
examples, dropped the design-doc status header from adaptive-ids, and
linked the home page's concept table to the canonical pages.
- 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.
- mint.sh + make docs-dev: local preview of the docs/ Mintlify site
(Node 22 handling modeled on the Gas City wrapper).
- test/docsync: Go guard keeping docs/ and docs.json in exact
correspondence — every nav entry has a file, every page is in the nav
(tiny stub allowlist for paths released bd binaries print), published
pages use root-relative extensionless links that resolve, and engdocs/
plus curated root markdown keep exact GitHub-style paths. Wired into
make check-docs.
- .github/workflows/docs-mintlify.yml: docsync + baseline-aware
mint broken-links check on PRs touching docs/**.
- Retire scripts/sync-website-docs.sh and its mirror-drift gate: the six
mirrored files now live once in the Mintlify site; the committed
Docusaurus mirrors stay frozen so the parallel-run site keeps building.
- Repoint inbound links to moved docs across README, guides, examples,
npm-package, plugin resources, and Go comments; add docs/SYNC_CONCEPTS.md
pointer stub (bd's agent templates print that path). Runtime strings in
cmd/bd (prime.go, store_factory_nocgo.go, init_git_hooks.go) still print
old paths — covered by stubs, flagged in the PR.
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).
Port the website's current (non-versioned) authored pages into docs/ as
Mintlify pages: frontmatter title as H1 (body H1s removed), Docusaurus
admonitions converted to Mintlify components, root-relative extensionless
links, mermaid fences kept as-is. website/docs/** is untouched and keeps
serving the Docusaurus site until cutover.
git-mv the user-facing docs/ originals with no website twin into the new
IA (core-concepts/, architecture/, workflows/, recovery/, multi-agent/,
integrations/, reference/), converted to Mintlify form. The six files
previously mirrored by sync-website-docs.sh now live once in the site.
ERROR_HANDLING.md and CONTRIBUTOR_NAMESPACE_ISOLATION.md move to engdocs/
(contributor pattern guide and design doc per content review).
Pointer stubs remain at docs/{DOLT,STORAGE-BACKENDS,PLUGIN,RECOVERY,
JSON_SCHEMA}.md because released bd binaries print those paths; QUICKSTART
and DOLT-BACKEND stay as existing pointer stubs.
Corrected while porting: the intro's storage diagram claimed data lives at
.beads/dolt/; embedded mode (the default) uses .beads/embeddeddolt/
(internal/storage/embeddeddolt/store.go), server mode uses .beads/dolt/.
Relocate contributor- and maintainer-facing material out of docs/ so the
directory can become the user-facing Mintlify site. Moves preserve subpaths
(adr/, design/, staged-for-removal/ intact). messaging.md, UI_PHILOSOPHY.md,
and AGENT_SIGNING.md move per their DOC_INVENTORY dispositions (design doc,
design philosophy, maintainer convention).
Inbound links updated repo-wide: root guides, CONTRIBUTING, AGENTS,
workflows, lint config, scripts (check-doc-freshness now resolves the
inventory at engdocs/DOC_INVENTORY.md), Go comments, and the synced website
metadata page (regenerated via sync-website-docs.sh + generate-llms-full.sh).
The emitted help text in cmd/bd/init_safety_help.go still references
docs/adr/0002-init-safety-invariants.md; changing it would change bd's
runtime output, which is out of scope for this branch (flagged in the PR).
* fix(label): support comma-separated multi-label add/remove; fail hard on bad issue IDs (bd-vu5kv)
'bd label add <id> a b c' silently applied only 'c': the grammar treats
the last arg as THE label and everything before it as issue IDs, and
unresolvable IDs were skipped with a stderr warning while the command
exited 0. An agent hit this in the wild and only noticed because
'bd ready --label ...' came back empty.
Two changes:
- The final positional arg now splits on commas, so
'bd label add bd-123 a,b,c' adds all three labels in one transaction
(same convention as 'bd create --labels a,b,c'). Same for remove.
- Issue-ID args that fail to resolve are now a hard error before any
mutation, instead of warn-and-continue. When several ID-position args
fail, the error hints at the comma-separated form, which is exactly
the space-separated-labels mistake.
The reserved 'provides:' check now runs against every label in the
list. Regenerated CLI reference docs (freshness probe) and updated
docs/LABELS.md.
Closes bd-vu5kv
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_012VBUR4qkHbssPomBDuJgkQ
* docs: sync website label mirrors
Agent-Signature: codex-gpt-5.6-terra-high on behalf of matt wilkie
---------
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
Routine issue history already lands in the database events tables. Stop creating or appending the interactions JSONL sidecar by default, add audit.enabled for explicit sidecar use, and expose database events via bd history --events.
Fixesgastownhall/beads#4687
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
Cursor support is anemic compared to Claude Code and Codex. It ships
only a static rules file: no agent lifecycle hooks, so `bd prime`
context is never injected at session start and is silently lost after
context compaction, and it has no `bd init` auto-install, no `--global`
scope, no shared agent skill, and no `bd doctor` coverage.
This PR brings Cursor up to the same footing as the tier-1 integrations.
- `bd setup cursor` now installs agent lifecycle hooks
(`.cursor/hooks.json`) alongside the rules file, wiring
sessionStart/preCompact/postToolUse to a hidden `bd cursor-hook`
command so Beads context survives compaction:
* sessionStart injects full `bd prime` context into new sessions
* preCompact arms a one-shot refresh marker
* postToolUse re-injects `bd prime` once after a compaction, then
no-ops
- `bd init` auto-installs Cursor (rules + skill + hooks) and stages
`.cursor/`
- `bd setup cursor --global` writes `~/.cursor/hooks.json` +
`~/.agents/skills/beads`
- Canonical rules: `.cursor/rules/beads.mdc` wraps the shared
`recipes.Template` instead of a hand-maintained copy
- Shared agent skill (`.agents/skills/beads`), removed only once neither
Cursor nor Codex still relies on it
- `bd doctor` reports Cursor Integration, Settings Health, and Hook
Completeness checks with agent-mode enrichment
Shared hook mechanics (prime runner + one-shot refresh marker) are
factored into `cmd/bd/agent_hook.go` and reused by codex-hook.
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rebase of PR #4601 (feat/choose-your-own-backend) onto current origin/main,
squashed to a single commit because the original 73-commit history built and then
removed the uowStore derisk spike incrementally, which does not replay cleanly
over the 125 commits main has since advanced (notably #4679, the ready-work
counts fix, which merged to main and is now inherited rather than re-applied).
The full pre-rebase history remains on the original branch tip for reference.
Contents (multi-backend feature + the six review follow-ups):
- bd init --backend=postgres|mysql|sqlite provisioning behind the Dolt-parity
seam; the three SQL backends share *sqlkit.Store over pluggable dialects and
carry a generated typed-unsupported shell for the non-core surface.
- Passwords in init DSNs are redacted before persisting to metadata.json (driver
parser + re-parse verification), with a negative-test matrix proving no secret
survives (pgdialect + mysql).
- The uowStore derisk spike and its report artifacts are removed; the shell
generator now lives in internal/storage/unsupportedgen (neutral name).
- Compile-time guard `var _ storage.DoltStorage = (*Store)(nil)` on each backend
plus a regen-idempotence test keep the generated skip lists honest.
- sqlkit exposes CountReadyWork so every SQL backend satisfies
storage.ReadyWorkCounter and inherits the shared page-pushed ready-counts path.
- Commercial/product names scrubbed from the feature's own code for vendor
neutrality.
Rebase reconciliations: adopted main's metadata-load hardening in the store
factories alongside the backend dispatch; combined the config interface
(GetMetadata + ReconcileVersion) and the conformance registrations (ReadyCounts +
Claim/lease); took main's versions of the shared-infra concurrency (uow
doltserver_tx) and delete-cascade (domain/issue_delete) evolutions; implemented
the interface's new UnclaimIssue on sqlkit (delegating to issueops) and added it
to the skip lists.
Verified: go build (cgo + CGO_ENABLED=0) and go vet clean; unit tests
(sqlbuild/issueops/pgdialect/mysql/unsupportedgen) and the SQLite conformance
suite green (RunAll, incl. ReadyCounts equivalence and Claim/lease on the real
sqlkit backend).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add a short upgrade checklist to the README, installing docs, live website installation pages, and upgrade guide so remote-backed migration rules are visible from common entry points.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
Add DOC_INVENTORY.md disposition rows for four docs/ files created after
the 2026-05-08 review (CI_REQUIRED_CHECK_TOPOLOGY.md, COPILOT_CLI_INTEGRATION.md,
RELATED_PROJECTS.md, SYNC_CONCEPTS.md), all spot-checked healthy and kept.
Note SYNC_CONCEPTS.md as the sanctioned website-mirror source per
.github/workflows/deploy-docs.yml and its widespread cross-doc linking.
Delete docs/superpowers/plans/2026-05-03-unclaim-command.md and
docs/superpowers/specs/2026-05-03-unclaim-command-design.md: PR-passenger
planning/spec artifacts from a contributor's personal multi-agent rig, the
same class removed in commit 187ba85f3 (#4632). Content stays in git
history; the now-empty docs/superpowers/ tree is removed with them, and
their removal is recorded as inventory rows.
Refresh the Reviewed: date on DOC_INVENTORY.md and
staged-for-removal/MANIFEST.md to 2026-07-07. Note in the manifest that all
11 staged entries reach the 2-month threshold around 2026-09-09 with zero
rescue activity so far, and that the next docs health check executes the
deletion.
Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
* fix(config): derive tracker config namespaces from the registry
`bd config set ado.org <org>` warned "not a recognized config key" (and
unhelpfully suggested "ai.org") even though ADO is a registered tracker
and the value persists correctly. The recognizer's allowlist hardcoded
jira./linear./github. but had drifted — it never gained ado. (GH#4427).
Rather than just add "ado.", make the tracker registry the single source
of truth: drop the hardcoded tracker prefixes from recognizedConfigPrefixes
and derive them at runtime from tracker.List() via a new
allRecognizedConfigPrefixes helper, used by both isRecognizedConfigKey and
suggestConfigKey. This eliminates the drift class so the next tracker is
covered automatically. As a bonus, a genuine typo near a tracker name
(e.g. "add.org") now suggests "ado.org" instead of "ai.org".
Also adds the missing tracker namespaces (gitlab, ado, notion) to the
'Common namespaces' help text.
Tests: extend TestIsRecognizedConfigKey with ado/gitlab/notion/linear/github
keys, add TestTrackerConfigPrefixesRecognized asserting every registered
tracker prefix is recognized, and a suggester case.
Fixesgastownhall/beads#4427
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: regenerate CLI reference for registry-derived config namespaces
The config-key registry change surfaces gitlab.*, ado.*, and notion.*
in the 'bd config set' help text; regenerate the committed CLI docs to
match so the doc-freshness gate passes.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Fix four doc-seam duplications (mybd-melg):
1. AGENT_INSTRUCTIONS.md's "Release Process (Maintainers)" duplicated
RELEASING.md with a divergent 7-step manual process, cited a
nonexistent ./scripts/update-homebrew.sh, and used a stale 0.9.3
example. Replaced the section body with a pointer to RELEASING.md.
2. CONTRIBUTING.md's "Testing Guidelines" was a parallel test-running
guide that never linked docs/TESTING.md, and was self-contradictory
("make test" listed as both the fast tier and the full suite;
described a -short two-tier strategy scripts/test.sh does not
implement). Cut the command matrix, kept only contributor etiquette
(what to run before a PR, expectations), and pointed to
docs/TESTING.md and docs/TESTING_PHILOSOPHY.md.
3. Moved FEDERATION-SETUP.md to docs/FEDERATION.md as the canonical
federation home. Left a short pointer stub at the root path (inbound
links from website quickstart pages and llms-full.txt keep
resolving). Folded DOLT.md's federation section (architecture
diagram, sync/status/topology commands, credentials) into
docs/FEDERATION.md, then reduced DOLT.md's section to a summary
paragraph plus a link. While merging, corrected the stale "Planned
Features" list (list-peers/sync/status are implemented; only
single-peer push/pull remain unexposed - bd federation sync already
covers both directions) and the stale --json output example.
Added a docs/DOC_INVENTORY.md row for docs/FEDERATION.md.
4. Folded the two divergent hand-maintained "Landing the Plane" /
session-completion protocols (AGENTS.md, AGENT_INSTRUCTIONS.md) into
one canonical copy in AGENTS.md - union of the still-true content
(explicit quality-gate commands, cleanup commands, and the
next-session hand-off prompt format from AGENT_INSTRUCTIONS.md).
Reduced the AGENT_INSTRUCTIONS.md copy to a pointer.
Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
* fix(dolt): report pre-push fsck timeout as timeout, not dangling chunk reference (GH#4258)
When dolt fsck exceeds its 30-second deadline, exec.CommandContext SIGKILLs
the process. The killed run typically produces empty output, which fell through
to the generic failure path and was wrapped as ErrDanglingReference
("dangling chunk reference: aborting push..."), a false corruption report on
healthy but large stores (root-caused by a user: 2.6 GB store needed 67.8 s;
CALL DOLT_GC() shrank it to 24 MB and fsck to 0.5 s).
This commit: adds ErrFSCKTimeout sentinel; extracts classifyFSCKFailure to
distinguish five fsck failure modes (non-empty output routes by content;
parent Canceled → plain cancellation; parent DeadlineExceeded → ErrFSCKTimeout
pointing at the caller's timeout, e.g. dolt.auto-push-timeout for auto-push,
noting BEADS_FSCK_TIMEOUT cannot extend it; fsck's own timeout → ErrFSCKTimeout
with BEADS_FSCK_TIMEOUT guidance; generic empty-output → ErrDanglingReference);
makes the timeout overridable via BEADS_FSCK_TIMEOUT (mirrors BEADS_PRIME_TIMEOUT
pattern); updates doc comments; and adds unit tests for all five branches plus
the timeout-duration helper. Parent-context vs own-timeout classification
prevents misdirecting users to BEADS_FSCK_TIMEOUT when the caller's deadline
(e.g. auto-push-timeout) is the real constraint, and avoids a false
"dangling chunk reference" on user Ctrl-C.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
* docs(config): document fsck timeout override
Document the BEADS_FSCK_TIMEOUT runtime override alongside the Dolt push timeout settings so users can discover the new PR #4650 recovery knob.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* feat(migrate): add --force flag as CLI twin of BD_ALLOW_REMOTE_MIGRATE
The remote-migrate gate (#4259) refuses to auto-apply pending schema
migrations to a remote-backed database because two clones migrating
independently fork the schema unrecoverably. Until now the only unlock
was the env var BD_ALLOW_REMOTE_MIGRATE=1, which is awkward at the CLI
and can leak into child processes (git hooks, dolt subprocesses). The
--force flag is the natural CLI form of the designated-migrator escape
hatch: it is set before both autoMigrateOnVersionBump and the main store
open in the root PersistentPreRunE via a package-level bool, so it never
leaks out of the process. The env var remains supported for scripted/CI
use and is documented as a parenthetical alongside the new primary form.
Agent-Signature: claude-sonnet-4-6-high on behalf of matt wilkie
* fix(embeddeddolt): point lenient-gate guidance at bd migrate --force
The soft-fail (warn-and-continue) gate warning for read-only and
working-set-reconcile opens still named the env-var escape hatch; align
it with the new primary form introduced for the strict gate.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
* fix(migrate): reject --force with preview flags; harden override lifecycle
Review findings on the --force flag (cross-vendor: codex gpt-5.5 + claude
opus):
- --force combined with --dry-run/--inspect must fail before the store
opens: with the gate overridden, the open itself applies pending
migrations, so the preview flag would be honored only after the
destructive work it exists to prevent (codex P2).
- Set-or-clear the override unconditionally so it is self-clearing under
any future in-process root-command reuse (reviewer nit).
- Lock the agent-safety contract against the new flag form: AgentDirective
must not embed 'bd migrate --force' any more than the env form (nit).
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Follow-up to #4585: the agent.profile prime/config help text landed
without a CLI docs regen, tripping check-doc-flags.sh on main
(strict freshness probe, no PR diff base to attribute drift).
Regenerated with CGO_ENABLED=0 -tags gms_pure_go per AGENTS.md.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
docs/PROJECT_CHARTER.md's "Storage Boundary" section has stated since it was
written that beads packages should not depend on the Dolt engine directly
outside the storage adapter, but nothing checked that mechanically - it was
social-only convention. Add a depguard rule (golangci-lint v2 schema) that
denies any `github.com/dolthub/` import from packages outside
internal/storage/** and internal/doltserver/**, with a message pointing back
at the charter section.
Two pre-existing imports are carved out as justified exceptions via the
rule's `files` negation list, each with an inline comment explaining why:
- cmd/bd/proxied_server.go - imports dolt server config (servercfg, filesys)
to launch/manage a real `dolt sql-server` process; candidate for later
migration behind the storage adapter.
- internal/metrics/flusher.go, internal/metrics/metrics.go - import
DoltHub's eventkit analytics/telemetry client, which is not the Dolt
storage engine and is out of scope for this boundary. These two files get
a second, narrowly-scoped depguard rule
(dolt-storage-boundary-metrics-exception) that allows only
github.com/dolthub/eventkit and still denies every other dolthub import
(e.g. the engine itself), so metrics can't become a backdoor around the
boundary.
Verified against the CI-pinned golangci-lint v2.9.0
(--timeout=5m --build-tags=gms_pure_go ./...): clean with the new rules, and
two temporary probes were reverted after confirming they fail as expected -
a blank import of github.com/dolthub/driver/v2 in cmd/bd, and a blank import
of github.com/dolthub/go-mysql-server/sql in internal/metrics/metrics.go
(the latter proves the metrics exception allows eventkit only, not the
engine).
Agent-Signature: claude-sonnet-5-high on behalf of matt wilkie
Clarify that VictoriaLogs and BD_OTEL_LOGS_URL are reserved for future log export, while current telemetry export is metrics/stdout only.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* feat(prime): add agent.profile config + BD_AGENT_PROFILE runtime knob (mybd-44me)
PR #4220 added the conservative/minimal/team-maintainer PROFILE VOCABULARY
to the generated Beads block and `bd prime` output, but selection stayed
implicit (driven by no-push / ephemeral-branch / no-git-remote checks).
This answers gh#3423 (follow-up to #4220) by adding first-class runtime
plumbing:
- New `agent.profile` config key (default "conservative"), validated with
a safe fallback to conservative on an unrecognized value (mirrors the
existing GetSovereignty() pattern in internal/config/sync.go).
- `BD_AGENT_PROFILE` env override, wired for free via viper's existing
AutomaticEnv + BD prefix/key-replacer wiring (no new BindEnv needed).
- `bd prime` now layers the explicit profile on top of its existing
implicit branches: when agent.profile=team-maintainer and no hard git
constraint applies (not stealth/local-only/ephemeral/no-push), the
close-protocol wording becomes definitive ("commit/sync/push as part of
routine work") instead of the prior ambiguous "may... when enabled"
text. Unset/conservative/minimal leaves existing wording unchanged.
- docs/SETUP.md and docs/CONFIG.md now point at the actual knob instead
of "edit your own AGENTS.md".
Deliberately out of scope: the generated AGENTS.md/CLAUDE.md template
text in internal/templates/agents/defaults/*.md and
internal/recipes/template.go still describes profiles narratively for
tools without config-file access; changing those golden templates is a
larger, separate follow-up.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Agent-Signature: claude-opus-4-8-high on behalf of matt wilkie
* fix(config): register agent. prefix as recognized config key
bd config set agent.profile team-maintainer succeeded but printed a
false "not a recognized config key" warning because cmd/bd/config.go's
allowlist never learned about the agent.* namespace added alongside
the agent.profile knob. Add "agent." to recognizedConfigPrefixes and
cover it in the isRecognizedConfigKey test.
Addresses Codex cross-vendor review finding (2026-07-07) on PR #4585.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* docs: remove stale sync-branch worktree guidance
Clarify that current protected-branch and worktree workflows use Dolt-native sync rather than the removed sync.branch branch/worktree model.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* docs: fix broken command references and anchor in PR #4593
PROTECTED_BRANCHES.md staged a nonexistent .gitattributes file instead
of the .gitignore that bd init actually creates, and told users to run
the nonexistent `bd vc conflicts` command instead of `bd vc merge
<branch> --strategy [ours|theirs]`. FAQ.md and TROUBLESHOOTING.md still
linked to the old "Beads-Created Worktrees (Sync Branch)" anchor in
WORKTREES.md, which was renamed to "Legacy Cleanup" earlier in this PR.
Addresses Codex cross-vendor review finding (2026-07-07).
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
* fix(import): respect import.auto=false on empty DB in bd update (fixes#4304, mybd-3fvn)
shouldRunAutoImportJSONL gated the empty-database upgrade-recovery
auto-import (maybeAutoImportJSONL, GH#2994) on read-only/global/server-mode
flags only. It never consulted the import.auto config key, so
BD_IMPORT_AUTO=false (or import.auto: false in config.yaml) had no effect on
this path -- only the separate git-hook sync importer (importJSONLForSync)
honored it. Any write command (e.g. bd update) against a fresh/empty
database with a stale issues.jsonl present would silently auto-import it and
report success, exactly as reported in #4304.
Add the missing config.GetBool("import.auto") check to
shouldRunAutoImportJSONL. Explicit `bd import` is unaffected: it already
short-circuits on cmd.Name() == "import" regardless of this flag.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FWVnjn3Bq4PSG1akpFpKnY
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
* fix(config): route import.auto through YAML config
bd config set import.auto previously treated the startup gate as a database-backed key, so the value landed where the auto-import checks never read it. Mark it YAML-only like import.path and cover both direct and config set-many routing tables.
Agent-Signature: codex-gpt-5.5-high on behalf of matt wilkie
* fix(config): exempt config-set of import.auto=false from pre-run auto-import
Running `bd config set import.auto false` (or `config set-many ...
import.auto=false`) triggered the very auto-import it was meant to
disable: shouldRunAutoImportJSONL runs in PersistentPreRun before the
config command writes the new value, so it still saw the old default
(true) and imported first when a stale .beads/issues.jsonl sat next to
an empty database. Add isDisablingImportAutoViaConfigCommand to detect
this specific invocation and skip the pre-run import so the master
switch takes effect on the same command that sets it.
Addresses Codex cross-vendor review finding (2026-07-07) on PR #4595
(mybd-ycu4).
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
---------
Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
The release-gates/ directory (16 files) and two docs/plans/ files
(schema-skew-guard.md, reference-aware-prune.md) are internal artifacts
from a contributor's personal multi-agent development rig: release-gate
checklists and PM handoff plans referencing bead IDs (be-*) from a
private tracker that does not exist in this repo. They arrived as
passengers on otherwise-valuable contribution PRs between April and
July 2026 and have no readers here - the user-facing documentation for
those features landed in --help text and README via the same PRs.
Removing them keeps the tree free of files that reference untraceable
issue IDs and confuse both human readers and coding agents that treat
docs/plans/ as authoritative. Content remains available in git history.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Main went red at the 'Check doc flags freshness' gate: 64d67e09
(chore(dolt): converge bd dolt clean-databases prefix list) updated the
command help text without regenerating the generated docs. Regenerated
with scripts/generate-cli-docs.sh (pinned pure-Go binary); delta is the
prefix list line in both generated files, nothing else.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
Why: the help text advertised --gated on bd mol ready but Cobra flags do not propagate between sibling commands, so the advertised flag was a hard error; this registers it on molReadyGatedCmd directly. Landed manually (auto-merge disabled) after the branch was updated past the #4623 main-CI fixes and the full check suite ran green.
Co-Authored-By: Scott Hamilton <scotthamilton77@gmail.com>
Co-Authored-By: matt wilkie <maphew@gmail.com>
bd q is designed for scripting and agent integration, but batch-creating
epic breakdowns required falling back to the heavier bd create --parent.
Mirrors create.go's parent handling: validate the parent exists, inherit
its labels (create's default), reserve the hierarchical child ID via
GetNextChildID/WithReservedChildCounter, add the parent-child dependency
after CreateIssue, and follow up with the post-write Dolt commit
(GH#2009 pattern). Output stays ID-only.
Closes#4596
Assisted-by: Claude:claude-fable-5 [Cursor]
Co-authored-by: Cursor <cursoragent@cursor.com>
The hand-port of gastownhall/beads#3759 (PR #4613) added inline help text
to `bd linear sync` but deliberately skipped a docs regen to avoid
pulling in unrelated churn. "Check doc flags freshness" failed on main
afterward because `docs/CLI_REFERENCE.md` and the website CLI reference
pages had also drifted from several other recent merges (new issue types
spike/story/milestone, the `bd unclaim` command, `bd formula schema`
flag, `bd types --sections`) - the freshness check compares the whole
generated doc set, not per-PR.
Regenerated via `./scripts/generate-cli-docs.sh` using a pinned
CGO_ENABLED=0 -tags gms_pure_go build of bd, confirming no federation
churn (identical diff whether generated via the script's own build or
the pinned pure-Go binary). `./scripts/generate-cli-docs.sh --check`
now passes.
Agent-Signature: claude-fable-5-high on behalf of matt wilkie
* feat: Add bd unclaim command to release stuck issues
- Add UnclaimIssue method to storage interface and implementations
- Add bd unclaim CLI command: clears assignee, resets status to 'open'
- Improve claim error message when issue has assignee but status is 'open'
(now suggests using bd unclaim)
- Update documentation: CLI_REFERENCE.md, QUICKSTART.md, setup templates
- Add unclaim tests
- Fix telemetry wrapper to implement UnclaimIssue method
- Add test mocks for UnclaimIssue in jira tests
* docs: regenerate CLI reference for bd unclaim
Runs scripts/generate-cli-docs.sh to add the bd unclaim entry that
gastownhall/beads#3694 introduced but whose CLI_REFERENCE.md/website
delta was lost in the conflict resolution during the cherry-pick.
Scoped to only the unclaim addition; unrelated doc drift already
present on main (formula/lint/types/linear entries) is left untouched.
Agent-Signature: claude-fable-5-medium on behalf of matt wilkie
---------
Co-authored-by: Abner S. Alves Junior <abnersajr@gmail.com>
- Fix bd lint --help and --type flag to list all 9 types (not just 4)
- Fix bd create --type flag to include spike, story, milestone
- Add bd types --sections flag displaying RequiredSections() from code
- Fix docs/CLI_REFERENCE.md section requirements table
- Fix bead-checklists.md to match code (decision: Rationale not "Chosen option",
chore/spike/story/milestone corrected)
* feat(preflight): implement --fix mode for vendorHash and version sync
- Add fixNixHash(): uses sentinel-hash trick with nix build to compute
and write the correct vendorHash into default.nix when go.sum has
uncommitted changes; prints clear error if nix not in PATH
- Add fixVersionSync(): syncs cmd/bd/version.go to match default.nix
version field (default.nix is source of truth)
- Add runFixes(): wires both to --fix flag with human-readable and
--json output modes
- Remove outdated 'not yet implemented / bd-lfak.3-5' stub
- Preserve original file permissions on all writes
Closes be-xra8, be-roho
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: sync CLI_REFERENCE.md --fix help text with live CLI (be-xra8, be-roho)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs(preflight): regenerate website CLI reference for --fix flag (be-laor)
Update website/docs and both versioned_docs variants to reflect --fix
flag description change from 'not yet implemented' to 'vendorHash, version sync'.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* chore: release gate PASS for be-xra8+be-roho (bd preflight --fix mode)
---------
Co-authored-by: Jim Wordelman <jim@wordelman.name>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
InstrumentedStorage was fully implemented in internal/telemetry/storage.go
but never instantiated. As a result bd.storage.* metrics, bd.issue.count
snapshots, and per-operation storage spans never reached any backend, even
when an OTel exporter was wired up. Only bd.db.pool_* gauges (registered
separately inside the dolt store) were emitted.
Two structural changes are needed before the wiring can compile:
1. WrapStorage now operates on storage.DoltStorage instead of
storage.Storage. The store variable in cmd/bd/main.go is typed
DoltStorage, as is the input to NewHookFiringStore, so a decorator that
only implements Storage cannot sit in the chain. InstrumentedStorage
embeds DoltStorage to passthrough capability sub-interfaces
(VersionControl, HistoryViewer, SyncStore, etc.) — those operations
already have their own dolt.* spans inside the dolt layer, so wrapping
them here would double-count.
2. storage.UnwrapStore now peels arbitrary chains of decorators via a
small Unwrapper interface (Unwrap() DoltStorage). The previous
implementation only knew about *HookFiringStore and would have left
InstrumentedStorage in front of the concrete store, breaking the ~25
cmd/bd type assertions to optional capability interfaces (StoreLocator,
BackupStore, RawDBAccessor, etc.). HookFiringStore.Inner() is renamed
to Unwrap() — internal package, no external callers.
Chain composition is extracted into wireStorageDecorators in a new
cmd/bd/storage_chain.go file so the wiring is unit-testable. Six tests
cover the cartesian product of telemetry on/off × hooks on/off/nil-runner
and assert the chain layout via type assertions and Unwrap. The
TelemetryOn_HookOn case is the direct regression test for this bug — if
a future refactor drops the WrapStorage call from the helper, that test
fails. docs/OBSERVABILITY.md gains a local verification snippet.
Co-authored-by: matt wilkie <maphew@gmail.com>
* feat(formula): add bd formula schema reflection-driven primitive index (beads-9ib)
Generates internal/formula/schema_gen.go from types.go via go:generate,
exposing all 18 exported structs (Formula, Step, LoopSpec, OnCompleteSpec,
etc.) with field types, json/toml tags, required-flag, and doc comments.
Surfaced via:
bd formula schema # list every primitive
bd formula schema loop # show LoopSpec fields
bd formula primitives on_complete # alias + snake_case match
bd formula schema --json # machine-readable
Lookup prefers exact match over Spec/Rule(s) suffix-strip, so "gate"
resolves to Gate (not GateRule). Fields tagged json:"-" (Step.SourceFormula,
Step.SourceLocation) are excluded.
TestSchemaGenIsCurrent re-runs the AST walker in-memory and byte-diffs
against the committed schema_gen.go, so a new struct in types.go without
a regen will fail CI.
Item 2 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(formula): point bd formula --help at the primitive index (beads-lnf)
Extends the cobra Long descriptions on `formula`, `formula list`, and
`formula show` so an agent reading any of them is told that
`bd formula schema` (alias `primitives`), the curated
`examples/formulas/primitives/` directory, and the website primitives
reference exist. Without these pointers, agents land on the formula
surface and conclude there is no primitive index — which is the exact
failure mode GH#3621 is closing.
Adds cmd/bd/testdata/formula_help.txt as the regression gate: a
scripttest that runs `bd formula --help` (plus `--help` on the list
and show subcommands) and asserts the four pointers are present. If
someone deletes a pointer, the snapshot fails.
website/docs/cli-reference/formula.md is auto-generated from the Long
descriptions via `bd help --doc formula`, so the website doc inherits
the pointers on its next regeneration with no manual edit.
Item 1 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(formula): curated primitive examples + smoke harness (beads-0sp)
Adds examples/formulas/primitives/ with one minimal `.formula.toml` per
empirically wired primitive in internal/formula/types.go:
loop-count LoopSpec.count expand body 3x → .iter1.work…
loop-range LoopSpec.range/var {n} substitutes into title
children-epic Step.Children epic + children w/ sibling needs
branch-fanin ComposeRules.Branch fork-join, deploy depends on 3 sibs
condition Step.Condition var-driven step inclusion
gate-timer Step.Gate sibling gate-typed issue blocks step
Each fixture has a header doc-comment explaining the primitive in
plain language; README.md indexes them with a one-line description
each and points back at `bd formula schema`.
cmd/bd/formula_primitives_test.go is the smoke harness: for each
fixture it parses, cooks through the full transformation pipeline
(loops → branches → gates → advice → expansions → conditions), and
asserts the primitive's observable effect on the cooked subgraph
(issue IDs, blocking deps, substituted titles, gate await_type).
Cooks against an in-memory subgraph rather than a Dolt-backed temp
DB so the harness exercises the primitive transformation, not the
persistence/auto-export infrastructure.
A subtest fails if a fixture is added to the directory without a
registered assertion in cases[] — the harness exists to prove
primitives are wired, not just that fixtures parse.
Explicitly omits an `on_complete` fixture; that primitive is a
runtime no-op as of v1.0.3 and ships with beads-i02's resolution,
not this epic.
Item 3 of GH#3621.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(formula): satisfy CI gosec G306 + regen CLI doc for new help text
Two CI fixes for the formula primitives PR:
- internal/formula/cmd/schemagen/main.go:26 — drop WriteFile perms
from 0644 to 0600 (gosec G306).
- website/docs/cli-reference/formula.md and the v1.0.0 mirror —
regenerated from the updated `bd formula --help` Long text via
scripts/generate-cli-docs.sh, using a CGO_ENABLED=0 bd build to
match CI.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(formula): distinguish schema from wired primitives
* fix(formula): regen schema_gen.go for rebase onto current main
Upstream main's Formula struct gained an Intent field after PR #3781 was
opened; regenerate schema_gen.go via go generate so
TestSchemaGenIsCurrent passes after rebasing the PR's commits onto
current main.
Maintainer fix-merge for gastownhall/beads#3781.
Agent-Signature: claude-fable-5-medium on behalf of matt wilkie
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: matt wilkie <maphew@gmail.com>
Introduces docs/RELATED_PROJECTS.md as a place for adjacent or
complementary projects (distinct from COMMUNITY_TOOLS.md, which lists
Beads integrations). Seeds it with one entry — scry — a marker-indexed
recall graph for AI coding agents that composes naturally with Beads:
task graph + recall layer.
Co-authored-by: scryspec-worker <scryspec-worker@reflecttech.ai>
Co-authored-by: matt wilkie <maphew@gmail.com>