Commit graph

4 commits

Author SHA1 Message Date
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
5f6bd2c87a docs: fix integration-page fact errors; restore three lost source edits
A second adversarial fact-check pass (372 claims across the 21 integration
and remaining getting-started pages: 291 verified, 22 contradicted) drove
these corrections, each reproduced against the binary or repo source:

- junie.md: the recipe-written MCP config invokes `bd mcp`, which does not
  exist in current builds — the page now warns about that and points at
  the working standalone beads-mcp server config. (The recipe itself,
  cmd/bd/setup/junie.go, still writes the dead config — recorded as a
  product follow-up, out of docs scope.)
- claude-code-plugin.md: the plugin (v1.1.0 manifest) ships skills,
  commands, and hooks — no MCP server. Removed the bundled-server claims,
  uv prerequisite, phantom `init` tool, stale 0.9.2 version pin, and the
  unverified env-var list; MCP guidance now points at the standalone
  server. installation.md's plugin-MCP troubleshooting entry updated to
  the same reality.
- upgrading.md: `bd migrate --cleanup` doesn't exist; the doctor
  migration-skew note was inverted (the check DOES run in embedded mode —
  cmd/bd/doctor/migration_skew.go); `dolt sql-server --stop` is not a
  flag.
- sync-setup.md: `bd vc log` doesn't exist (vc has commit/merge/status);
  use `bd history`.
- azure-devops.md: sync flag table listed phantom --label/--status/--type
  (real: --states/--types/--issues); error strings now quote the actual
  binary messages (MDX-safe).
- github-copilot.md: beads-mcp has no --version flag; verify with
  pip show beads-mcp. aider.md's config sample now matches the generated
  file byte-for-byte.

Also restores three source edits that a mid-script failure silently
dropped from the earlier printed-paths commit (whose message claimed
them): bd mol pour's help no longer says molecules are "synced with git",
the claude recipe's stale ProjectPath metadata
(.claude/settings.local.json -> .claude/settings.json), and the shared
recipe template's quickstart URL. CLI docs regenerated accordingly.

Gates: docsync, docsmint, recipes tests, generate-cli-docs.sh --check,
mint broken-links (no broken links), vet — all pass.
2026-07-12 10:37:18 -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
a86a2c5dfc docs: port user docs into the Mintlify site tree under docs/
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/.
2026-07-12 10:37:07 -07:00
Renamed from docs/SYNC_SETUP.md (Browse further)