From ba6f06e98bac0dc82695b48a7d2bb583543239e5 Mon Sep 17 00:00:00 2001
From: John Lam <jflam@microsoft.com>
Date: Sat, 29 Nov 2025 22:07:00 -0800
Subject: [PATCH] fix(docs): correct bd dep add syntax and semantics

Fixed incorrect bd dep documentation in prime.go, cursor.go, and aider.go

- Added missing 'add' subcommand (was 'bd dep <from> <to>', now 'bd dep add <issue> <depends-on>')
- Corrected semantics (docs claimed 'from blocks to' but actual behavior is 'issue depends on depends-on')

This fixes AI agents and users consistently creating dependencies in the wrong direction.

Co-authored-by: jflam <jflam@users.noreply.github.com>
---
 cmd/bd/prime.go        | 4 ++--
 cmd/bd/setup/aider.go  | 2 +-
 cmd/bd/setup/cursor.go | 2 +-
 3 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/cmd/bd/prime.go b/cmd/bd/prime.go
index 10514d09..5776aacb 100644
--- a/cmd/bd/prime.go
+++ b/cmd/bd/prime.go
@@ -227,7 +227,7 @@ bd sync            # Push to remote
 - ` + "`bd close <id> --reason=\"explanation\"`" + ` - Close with reason
 
 ### Dependencies & Blocking
-- ` + "`bd dep <from> <to>`" + ` - Add blocker dependency (from blocks to)
+- ` + "`bd dep add <issue> <depends-on>`" + ` - Add dependency (issue depends on depends-on)
 - ` + "`bd blocked`" + ` - Show all blocked issues
 - ` + "`bd show <id>`" + ` - See what's blocking/blocked by this issue
 
@@ -252,7 +252,7 @@ bd update <id> --status=in_progress  # Claim it
 ` + "```bash" + `
 bd create --title="Implement feature X" --type=feature
 bd create --title="Write tests for X" --type=task
-bd dep beads-xxx beads-yyy  # Feature blocks tests
+bd dep add beads-yyy beads-xxx  # Tests depend on Feature (Feature blocks tests)
 ` + "```" + `
 `
 	fmt.Print(context)
diff --git a/cmd/bd/setup/aider.go b/cmd/bd/setup/aider.go
index 8d702a12..3b4ce31e 100644
--- a/cmd/bd/setup/aider.go
+++ b/cmd/bd/setup/aider.go
@@ -33,7 +33,7 @@ This project uses **Beads (bd)** for issue tracking. Aider requires explicit com
 - ` + "`bd create --title=\"...\" --type=task`" + ` - Create new issue
 - ` + "`bd update <id> --status=in_progress`" + ` - Claim work
 - ` + "`bd close <id>`" + ` - Mark complete
-- ` + "`bd dep <from> <to>`" + ` - Add dependency (from blocks to)
+- ` + "`bd dep add <issue> <depends-on>`" + ` - Add dependency (issue depends on depends-on)
 - ` + "`bd sync`" + ` - Sync with git remote
 
 ## Workflow Pattern to Suggest
diff --git a/cmd/bd/setup/cursor.go b/cmd/bd/setup/cursor.go
index 5dfa4a72..32484830 100644
--- a/cmd/bd/setup/cursor.go
+++ b/cmd/bd/setup/cursor.go
@@ -27,7 +27,7 @@ bd list --status=open                 # List all open issues
 bd create --title="..." --type=task  # Create new issue
 bd update <id> --status=in_progress  # Claim work
 bd close <id>                         # Mark complete
-bd dep <from> <to>                    # Add dependency (from blocks to)
+bd dep add <issue> <depends-on>       # Add dependency (issue depends on depends-on)
 bd sync                               # Sync with git remote
 ` + "```" + `