From d71601d98ea69e554eeff3f4b36b5c7844e20a0b Mon Sep 17 00:00:00 2001
From: Adam Spiers <github@adamspiers.org>
Date: Sun, 28 Dec 2025 01:20:00 +0000
Subject: [PATCH] docs: fix README and PLUGIN.md documentation issues (#763)

docs: fix README and PLUGIN.md documentation issues

- Clarify that bd ready shows issues ready to work on (#512)
- Update git hooks install command from deprecated script to bd hooks install (#513)
- Fix Claude Code plugin local install: use ./beads not ., clarify shell vs CC commands (#514)

Fixes #512, #513, #514
---
 docs/FAQ.md             |  2 +-
 docs/PLUGIN.md          | 14 ++++++++++----
 docs/TROUBLESHOOTING.md |  2 +-
 3 files changed, 12 insertions(+), 6 deletions(-)

diff --git a/docs/FAQ.md b/docs/FAQ.md
index 360416fa..1406ab03 100644
--- a/docs/FAQ.md
+++ b/docs/FAQ.md
@@ -199,7 +199,7 @@ bd automatically:
 
 **Optional**: For immediate export (no 5-second wait) and guaranteed import after git operations, install the git hooks:
 ```bash
-cd examples/git-hooks && ./install.sh
+bd hooks install
 ```
 
 **Disable auto-sync** if needed:
diff --git a/docs/PLUGIN.md b/docs/PLUGIN.md
index 559b1846..3f9e5260 100644
--- a/docs/PLUGIN.md
+++ b/docs/PLUGIN.md
@@ -40,17 +40,23 @@ There are two ways to install the beads plugin:
 #### Option 2: Local Development
 
 ```bash
-# Clone the repository
+# Clone the repository (shell command)
 git clone https://github.com/steveyegge/beads
 cd beads
+```
 
-# Add local marketplace
-/plugin marketplace add .
+Then in Claude Code:
+
+```
+# Add local marketplace (Claude Code command)
+/plugin marketplace add ./beads
 
 # Install plugin
 /plugin install beads
 ```
 
+**Note:** If you want to install the plugin from a different repo, first `cd` to that repo's directory in your terminal, then use `./beads` (or the relative path to the beads directory) in Claude Code.
+
 ### Restart Claude Code
 
 After installation, restart Claude Code to activate the MCP server.
@@ -282,7 +288,7 @@ git commit -m "Add feature tracking"
 
 # After pull, JSONL auto-imports
 git pull
-bd ready  # Fresh data from git!
+bd ready  # Shows issues ready to work on (with fresh data from git)
 ```
 
 ## Updating
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 241dfba1..3a519c3b 100644
--- a/docs/TROUBLESHOOTING.md
+++ b/docs/TROUBLESHOOTING.md
@@ -402,7 +402,7 @@ bd export -o .beads/issues.jsonl
 bd import -i .beads/issues.jsonl
 
 # Install git hooks for guaranteed sync
-cd examples/git-hooks && ./install.sh
+bd hooks install
 ```
 
 If you disabled auto-sync with `--no-auto-flush` or `--no-auto-import`, remove those flags or use `bd sync` manually.