beads/docs/GETTING_STARTED_ANALYSIS.md
matt wilkie e2e4975044
Document supported go install modes (bd-o5a) (#3480)
- Removed bare first-party go install .../cmd/bd@latest guidance from docs,
    website docs, plugin/npm docs, examples, and doctor hints.
  - Standardized on:
      - CGO_ENABLED=0 go install ... for server-mode only
      - CGO_ENABLED=1 GOFLAGS=-tags=gms_pure_go go install ... for embedded-
        capable
  - Added scripts/check-go-install-guidance.sh and wired it into CI.
  - Updated default.nix to use gms_pure_go instead of ICU flags.

  Validation passed locally:

  - make test
  - golangci-lint run --build-tags=gms_pure_go ./...
  - ./scripts/check-go-install-guidance.sh
  - ./scripts/check-build-tags.sh
  - go test -tags gms_pure_go ./cmd/bd/doctor
  - doc flag check
2026-04-25 11:30:19 -07:00

300 lines
12 KiB
Markdown

# Analysis: Getting Started Documentation vs. Reality
**Date:** 2026-04-05
**Requested by:** @csells
**Question:** "How much of the getting started docs are genuinely necessary and how many point to errors that should be fixed?"
## Executive Summary
The getting started documentation is **~3x longer than it needs to be**, largely
because it documents workarounds for problems that should be fixed in the tool
itself. Of the ~1,600 lines across the core getting-started docs (README quick
start, QUICKSTART.md, INSTALLING.md, SETUP.md), roughly:
| Category | Est. Lines | % of Total | Verdict |
|----------|-----------|------------|---------|
| **Genuinely necessary** (core concepts, happy path) | ~400 | 25% | Keep |
| **Useful reference** (platform variants, IDE matrix) | ~350 | 22% | Keep but consolidate |
| **Workarounds for fixable UX issues** | ~450 | 28% | Fix the tool, delete the docs |
| **Redundant/duplicated across files** | ~400 | 25% | Consolidate into one place |
**Bottom line:** About half the getting-started surface area compensates for
tool-level UX gaps. If those gaps were fixed, the docs could shrink by ~50% and
the remaining docs would be more effective because users wouldn't have to read
past noise to find the signal.
---
## Part 1: What's Genuinely Necessary
These sections earn their keep. A new user *needs* this information and the tool
can't reasonably convey it automatically.
### 1.1 Core concept: "What is this and why would I use it?"
- **README.md** quick pitch (lines 1-30): Necessary. Explains the value prop.
- **QUICKSTART.md** "Why Beads?" section (lines 1-30): Good concrete example
showing flat tracker vs. dependency-aware ready queue.
### 1.2 The actual happy path (5 commands)
```bash
brew install beads # or npm install -g @beads/bd
cd your-project
bd init
bd create "Task" -p 1
bd ready
```
This is the irreducible core. Everything else is either reference or
workaround.
### 1.3 Dependency concepts
- `bd dep add`, `bd dep tree`, `bd ready --explain` — these are the
differentiating feature. The QUICKSTART walkthrough (lines 98-230) is
well-written and necessary.
### 1.4 Team sync basics
- "Add a Dolt remote, push, pull" — ~20 lines. Necessary for multi-machine use.
### 1.5 IDE setup matrix
- The table in INSTALLING.md (lines 22-31) mapping environments to components
is genuinely useful. Users need to know "I use Cursor, what do I install?"
---
## Part 2: Workarounds That Point to Fixable Errors
These documentation sections exist because the tool has a UX gap. Each one
represents a place where the *tool should be smarter* so the *docs can be
shorter*.
### 2.1 `bd: command not found` / PATH issues (~40 lines across 3 files)
**Appears in:** INSTALLING.md, TROUBLESHOOTING.md, QUICKSTART.md
**The fix:** The install script already tries to handle PATH. But `bd` should
print a one-liner after install: "Add this to your shell profile: `export
PATH=...`" — or better, the Homebrew formula and npm package should handle
this automatically (Homebrew already does). The `go install` path is the
problem child.
**Recommendation:** Remove `go install` from the "Quick Install" section
entirely. It's a developer/contributor path, not a user path. Move it to
CONTRIBUTING.md. The happy path should be `brew install beads` or `npm install
-g @beads/bd` — both handle PATH automatically.
### 2.2 CGO / ICU / build dependency issues (~80 lines)
**Appears in:** INSTALLING.md (lines 107-130), README.md (lines 75-91),
CONTRIBUTING.md
**Root cause:** Users who run plain CGO-enabled `go install` take the upstream
ICU regex path. Supported `go install` forms avoid ICU by using either
`CGO_ENABLED=0` (server-mode only) or `GOFLAGS=-tags=gms_pure_go`
(embedded-capable). Prebuilt binaries don't need any of this.
**The fix:** Same as above — stop promoting plain `go install` as a primary
install method. The prebuilt binary path (Homebrew, npm, install script)
requires zero build dependencies. The two supported `go install` forms belong
in the full installation docs, not the happy path.
### 2.3 `zsh: killed bd` / macOS crashes (~20 lines, duplicated in 2 files)
**Appears in:** INSTALLING.md, TROUBLESHOOTING.md (identical content)
**The fix:** This only affects `go install` without CGO. If `go install` is
demoted to a contributor path, this goes away for users. For contributors,
`make install` already handles it.
### 2.4 Windows Controlled Folder Access / Firewall (~40 lines)
**Appears in:** TROUBLESHOOTING.md
**The fix:** `bd init` should detect when it fails to create `.beads/` and
print a helpful message: "Windows Controlled Folder Access may be blocking
bd.exe. Add bd.exe to the whitelist in Windows Security settings." Currently
it hangs indefinitely, which is the real bug.
### 2.5 Multiple `bd` binaries in PATH (~30 lines)
**Appears in:** TROUBLESHOOTING.md
**The fix:** `bd version` (or `bd doctor`) should check for multiple `bd`
binaries in PATH and warn. Many CLI tools do this (e.g., `brew doctor`).
### 2.6 Port conflicts with multiple projects (~30 lines)
**Appears in:** TROUBLESHOOTING.md
**The fix:** Embedded mode (the default) doesn't have port conflicts. This
only applies to server mode. The docs should note this is server-mode-only
and `bd init` in server mode should detect port conflicts and suggest shared
server mode.
### 2.7 "Database is locked" (~20 lines)
**Appears in:** TROUBLESHOOTING.md
**The fix:** Embedded mode uses file locking. `bd` should detect the lock,
identify the holding PID, and print: "Another bd process (PID 12345) is using
the database. Wait for it to finish or kill it." Instead of a raw SQLite error.
### 2.8 Circuit breaker / stale state file (~50 lines)
**Appears in:** TROUBLESHOOTING.md
**Root cause:** A `/tmp/beads-dolt-circuit-*.json` file persists and blocks
all operations. Users have to know to manually delete it.
**The fix:** `bd doctor --fix` should clear stale circuit breaker files. Or
better: the circuit breaker should auto-reset after a configurable cooldown
(it has a 30s cooldown, but the state file persists across reboots on macOS
because `/tmp` -> `/private/tmp` isn't cleared).
### 2.9 `bd doctor` not working in embedded mode (~15 lines)
**Appears in:** TROUBLESHOOTING.md (indirectly), doctor.go code
**The fix:** This is the default mode! `bd doctor` should work in the default
mode. Telling users to switch to server mode to use the diagnostic tool is
backwards.
### 2.10 Sandbox mode documentation (~80 lines)
**Appears in:** TROUBLESHOOTING.md
**The fix:** Sandbox mode is auto-detected since v0.21.1. The docs still
describe manual `--sandbox` flag usage extensively. The auto-detection section
should be the primary content; the manual flags should be a small footnote.
### 2.11 Git hooks timeout / permission issues (~40 lines)
**Appears in:** TROUBLESHOOTING.md
**The fix:** `bd hooks install` should set correct permissions automatically
(it may already, but users still hit this). The timeout issue should be
documented in `bd hooks install` output, not buried in troubleshooting.
### 2.12 Antivirus false positives (~40 lines + separate ANTIVIRUS.md)
**Appears in:** TROUBLESHOOTING.md, docs/ANTIVIRUS.md
**The fix:** Code signing. The docs acknowledge this ("Future plans for code
signing"). Until then, the install script should print a note on Windows.
The extensive troubleshooting section is a band-aid.
---
## Part 3: Redundancy and Structural Issues
### 3.1 Installation instructions appear in 4 places
| Location | Content |
|----------|---------|
| README.md lines 65-99 | Homebrew, Go, npm, build from source |
| INSTALLING.md (full file) | Same + platform-specific + troubleshooting |
| QUICKSTART.md lines 33-38 | `go build` from source |
| CONTRIBUTING.md lines 16-31 | Clone + build from source |
**Recommendation:** README.md should have a 3-line install section linking to
INSTALLING.md. QUICKSTART.md should say "Install bd (see INSTALLING.md)" and
skip the build commands. CONTRIBUTING.md should cover dev setup only.
### 3.2 QUICKSTART.md uses `./bd` (local binary) syntax
The quickstart shows `./bd create`, `./bd ready`, etc. — suggesting the user
built from source and is running a local binary. This is the contributor
experience, not the user experience. Users who installed via Homebrew/npm
would just run `bd`.
**The fix:** Change all `./bd` references to `bd` in QUICKSTART.md.
### 3.3 The role/contributor/maintainer explanation is over-documented
Lines 69-96 in QUICKSTART.md + lines 60-63 in README.md + FAQ entries.
The `bd init` wizard already asks and explains this interactively.
**Recommendation:** One paragraph in QUICKSTART.md, link to a reference doc
for details.
### 3.4 SETUP.md is enormous (555 lines) for a `bd setup <tool>` reference
Most of SETUP.md documents `bd setup --check`, `bd setup --remove`, flags for
each of 10+ tools, comparison tables, custom recipes, etc.
**Recommendation:** This is reference documentation, not getting-started
documentation. Move it out of the getting-started path. Most users need
exactly: `bd setup claude` or `bd setup cursor`. One line each.
### 3.5 Database maintenance in QUICKSTART.md
Lines 295-340 cover compaction, cleanup, and migration — in a "quickstart"
doc. A new user creating their first issue doesn't need to know about
database garbage collection.
**Recommendation:** Move to ADVANCED.md or a dedicated MAINTENANCE.md.
### 3.6 Notion sync in QUICKSTART.md
Lines 257-290 cover Notion integration in the quickstart. This is an advanced
integration, not a getting-started topic.
---
## Part 4: Specific Recommendations
### Immediate wins (tool changes that eliminate doc sections)
1. **Demote `go install` to contributor docs** — eliminates CGO/ICU/PATH docs
for users (~120 lines saved across files)
2. **Fix `bd init` hang on Windows Controlled Folder Access** — detect the
failure and print a message instead of hanging
3. **Make `bd doctor` work in embedded mode** — this is the default mode
4. **Auto-clear stale circuit breaker files** — or make `bd doctor --fix`
handle them
5. **Detect multiple `bd` binaries in PATH** — warn in `bd version` output
6. **Print better error for locked database** — show PID of holder
### Immediate wins (doc changes only)
1. **Change `./bd` to `bd` in QUICKSTART.md** — reflects actual user experience
2. **Remove database maintenance from QUICKSTART.md** — move to ADVANCED.md
3. **Remove Notion sync from QUICKSTART.md** — move to integrations doc
4. **Consolidate install instructions** — one canonical location (INSTALLING.md),
links from everywhere else
5. **Trim SETUP.md from quickstart path** — it's reference, not onboarding
6. **Reduce role/contributor docs in quickstart** — trust the interactive wizard
### Dream state: The ideal getting-started experience
```bash
brew install beads # or: npm install -g @beads/bd
cd my-project
bd init # creates database, detects role, installs hooks
bd create "My first task" -p 1
bd ready # shows the task
```
Five commands. No CGO. No PATH fiddling. No Dolt installation. No role
configuration docs. No circuit breaker files to delete. The tool handles it.
The docs for this should be ~50 lines in README.md plus a link to the
QUICKSTART walkthrough (~150 lines covering dependencies and the ready queue).
Everything else is reference documentation, not getting-started documentation.
---
## Appendix: Files Reviewed
| File | Lines | Role in Getting Started |
|------|-------|------------------------|
| README.md | 190 | Entry point, quick start, feature overview |
| docs/QUICKSTART.md | 355 | Tutorial walkthrough |
| docs/INSTALLING.md | 535 | Installation for all platforms |
| docs/SETUP.md | 555 | IDE/editor integration setup |
| docs/TROUBLESHOOTING.md | 1030 | Error recovery |
| docs/FAQ.md | 513 | Common questions |
| CONTRIBUTING.md | 367 | Developer setup |
| docs/SYNC_SETUP.md | ~100 | Multi-machine sync |
| AGENT_INSTRUCTIONS.md | ~100 | Agent dev workflow |
Also reviewed: `cmd/bd/init.go` (actual init flow), `cmd/bd/prime.go` (context
injection), `cmd/bd/doctor.go` (health checks), `scripts/install.sh` (installer).