Priority used the filled circle also mapped to status-blocked, so agents
misread ready work as blocked (GH#4996). Render P-labels only; document
the convention for agents; keep ● for blocked status alone.
Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
repo = "{{var}}" in a formula gate step is substituted at pour time (bd mol
pour --var ...), not at cook --persist time; and bd gate discover requires a
workflow name hint for a cross-repo gate and ignores the local branch filter
unless --branch is passed explicitly.
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
- Delete queryGitHubRuns (unreferenced since queries are scoped per-repo).
- docs/workflows/gates.md: metadata.repo inheritance on an ad-hoc gate created
with `bd gate create` only applies to gh:run/gh:pr gates (SF4); reword to
say so instead of implying it for all gate types.
- createGateIssue wrote {"repo":...} metadata for any gate type; gate it with
the same isGitHubGateType helper repoMetadataForGate (SF4) already uses, so
a repo field on a human/timer/bead gate step - unrelated, ordinary metadata
for those types - is not mistaken for a GitHub repo selector.
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
createGateIssue built the gate issue directly without copying any
metadata, and formula.Gate had no field for it, so the declarative
cross-repo gate configuration documented for ad-hoc `bd gate create`
gates ("set the gate's string metadata.repo value") had no formula
equivalent. Add Gate.Repo (json/toml `repo`), thread it through
variable extraction and pour-time substitution alongside the other
gate fields, and propagate it onto the created gate issue's metadata
in createGateIssue. Validation of the value stays at check time
(githubRepoFromIssue), matching how any other gate's repo metadata is
validated. Document the new field in docs/workflows/gates.md.
Agent-Signature: claude-sonnet-5-medium on behalf of matt wilkie
* docs: caveat --parent label inheritance with size/effort labels (#4562)
Children inherit parent labels by default. Examples that use --parent with
size/effort labels on epics silently double-label every child, which breaks
effort queries. Document --no-inherit-labels in labels.md and parent-create
examples (skill, quickstart, molecules, multi-agent coordination).
* docs(labels): consolidate example commands and fix issue-ref style
Maintainer commit per vishnujayvel's request on PR #5123: fold the
two-step "create then label" example under Size/Effort Estimates into
one bd create -l invocation, and normalize the bare #2100 reference
to the GH#NNNN style used elsewhere in the docs.
Agent-Signature: claude-code-sonnet-medium on behalf of matt wilkie
* docs: revert no-op --no-inherit-labels edits, cross-link instead (GH#4562)
--no-inherit-labels was a no-op in the quickstart/molecules/coordination
examples (none created labels), inverting the deliberate #2100 default
for readers who don't have the problem yet. Revert those three plus the
same no-op edit in the plugin's INTEGRATION_PATTERNS.md to match main,
and add a one-line cross-link to the labels.md caveat/worked example
instead, per maphew's review on #5123.
---------
Co-authored-by: matt wilkie <maphew@gmail.com>
- 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)
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).
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).
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.
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/.