From 6b6d2dc4af23eb46c21b0060ae500868c7df295f Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Sat, 13 Dec 2025 09:58:27 +1100
Subject: [PATCH] docs: fix README and PLUGIN.md documentation issues
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 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

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 README.md      |  6 +++---
 docs/PLUGIN.md | 11 ++++++++---
 2 files changed, 11 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 503d80f8..57e3539c 100644
--- a/README.md
+++ b/README.md
@@ -322,8 +322,8 @@ git push
 git pull
 # bd automatically detects JSONL is newer and imports on next command
 
-bd ready  # Fresh data from git!
-bd list   # Shows issues from other machines
+bd ready  # Shows issues ready to work on (with fresh data from git)
+bd list   # Lists all issues, including those from other machines
 ```
 
 **Manual sync (optional):**
@@ -333,7 +333,7 @@ bd sync  # Immediately flush pending changes and import latest JSONL
 
 **For zero-lag sync**, install the git hooks:
 ```bash
-cd examples/git-hooks && ./install.sh
+bd hooks install
 ```
 
 This adds:
diff --git a/docs/PLUGIN.md b/docs/PLUGIN.md
index 23c2bd04..72fc4b08 100644
--- a/docs/PLUGIN.md
+++ b/docs/PLUGIN.md
@@ -40,17 +40,22 @@ 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 - note: use ./beads not .)
+/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.