docs: update paths for claude-plugin subdirectory structure (GH#985) (#1007)

Update documentation and scripts to reflect the plugin move from
root level to claude-plugin/ subdirectory:

- Fix command links in docs/DAEMON.md, docs/SYNC.md, examples/
- Update plugin.json path references in RELEASING.md, AGENT_INSTRUCTIONS.md
- Update scripts/bump-version.sh and scripts/check-versions.sh
- Update skill documentation paths in claude-plugin/skills/beads/

The marketplace.json correctly stays at .claude-plugin/ (root level)
while plugin.json moved to claude-plugin/.claude-plugin/.

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

AGENT_INSTRUCTIONS.md

@@ -343,7 +343,7 @@ git push origin main
 **Files updated automatically:**
 
 - `cmd/bd/version.go` - CLI version
-- `.claude-plugin/plugin.json` - Plugin version
+- `claude-plugin/.claude-plugin/plugin.json` - Plugin version
 - `.claude-plugin/marketplace.json` - Marketplace version
 - `integrations/beads-mcp/pyproject.toml` - MCP server version
 - `README.md` - Documentation version

RELEASING.md

@@ -134,7 +134,7 @@ This updates:
 - `cmd/bd/version.go` - CLI version constant
 - `integrations/beads-mcp/pyproject.toml` - MCP server version
 - `integrations/beads-mcp/src/beads_mcp/__init__.py` - MCP Python version
-- `.claude-plugin/plugin.json` - Plugin version
+- `claude-plugin/.claude-plugin/plugin.json` - Plugin version
 - `.claude-plugin/marketplace.json` - Marketplace version
 - `npm-package/package.json` - npm package version
 - `cmd/bd/templates/hooks/*` - Git hook versions
@@ -338,11 +338,11 @@ Update the Claude Code marketplace metadata files:
 # Change version to match current release
 vim .claude-plugin/marketplace.json
 
-# Update .claude-plugin/plugin.json if needed
+# Update claude-plugin/.claude-plugin/plugin.json if needed
-vim .claude-plugin/plugin.json
+vim claude-plugin/.claude-plugin/plugin.json
 
 # Commit changes
-git add .claude-plugin/
+git add .claude-plugin/ claude-plugin/.claude-plugin/
 git commit -m "chore: Update Claude Code marketplace to v0.22.0"
 ```
 

claude-plugin/skills/beads/CLAUDE.md

@@ -66,7 +66,7 @@ After skill updates:
 
 ```bash
 # Verify SKILL.md is within token budget
-wc -w skills/beads/SKILL.md  # Target: 400-600 words
+wc -w claude-plugin/skills/beads/SKILL.md  # Target: 400-600 words
 
 # Verify links resolve
 # (Manual check: ensure all resource links in SKILL.md exist)

claude-plugin/skills/beads/README.md

@@ -107,7 +107,7 @@ NEXT: Implement rate limiting"
 
 ## Contributing
 
-This skill is maintained at [github.com/steveyegge/beads](https://github.com/steveyegge/beads) in the `skills/beads/` directory.
+This skill is maintained at [github.com/steveyegge/beads](https://github.com/steveyegge/beads) in the `claude-plugin/skills/beads/` directory.
 
 Issues and PRs welcome for:
 - Documentation improvements

docs/DAEMON.md

@@ -592,4 +592,4 @@ bd daemons killall
 - [AGENTS.md](../AGENTS.md) - Main agent workflow guide
 - [EXCLUSIVE_LOCK.md](EXCLUSIVE_LOCK.md) - External tool integration
 - [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflow and merge strategies
-- [commands/daemons.md](../commands/daemons.md) - Daemon command reference
+- [commands/daemons.md](../claude-plugin/commands/daemons.md) - Daemon command reference

docs/SYNC.md

@@ -3,7 +3,7 @@
 This document explains the design decisions behind `bd sync` - why it works the way it does, and the problems each design choice solves.
 
 > **Looking for something else?**
-> - Command usage: [commands/sync.md](/commands/sync.md) (Reference)
+> - Command usage: [commands/sync.md](/claude-plugin/commands/sync.md) (Reference)
 > - Troubleshooting: [website/docs/recovery/sync-failures.md](/website/docs/recovery/sync-failures.md) (How-To)
 > - Deletion behavior: [docs/DELETIONS.md](/docs/DELETIONS.md) (Explanation)
 

examples/protected-branch/README.md

@@ -278,4 +278,4 @@ jobs:
 
 - [docs/PROTECTED_BRANCHES.md](../../docs/PROTECTED_BRANCHES.md) - Complete guide
 - [AGENTS.md](../../AGENTS.md) - Agent integration instructions
-- [commands/sync.md](../../commands/sync.md) - `bd sync` command reference
+- [commands/sync.md](../../claude-plugin/commands/sync.md) - `bd sync` command reference

scripts/README.md

@@ -88,7 +88,7 @@ Bumps the version number across all beads components in a single command.
 
 Updates version in all these files:
 - `cmd/bd/version.go` - bd CLI version constant
-- `.claude-plugin/plugin.json` - Plugin version
+- `claude-plugin/.claude-plugin/plugin.json` - Plugin version
 - `.claude-plugin/marketplace.json` - Marketplace plugin version
 - `integrations/beads-mcp/pyproject.toml` - MCP server version
 - `README.md` - Alpha status version

scripts/bump-version.sh

@@ -313,9 +313,9 @@ main() {
         "Version = \"$CURRENT_VERSION\"" \
         "Version = \"$NEW_VERSION\""
 
-    # 2. Update .claude-plugin/plugin.json
+    # 2. Update claude-plugin/.claude-plugin/plugin.json
-    echo "  • .claude-plugin/plugin.json"
+    echo "  • claude-plugin/.claude-plugin/plugin.json"
-    update_file ".claude-plugin/plugin.json" \
+    update_file "claude-plugin/.claude-plugin/plugin.json" \
         "\"version\": \"$CURRENT_VERSION\"" \
         "\"version\": \"$NEW_VERSION\""
 
@@ -383,7 +383,7 @@ main() {
     echo "Verifying version consistency..."
     VERSIONS=(
         "$(grep 'Version = ' cmd/bd/version.go | sed 's/.*"\(.*\)".*/\1/')"
-        "$(jq -r '.version' .claude-plugin/plugin.json)"
+        "$(jq -r '.version' claude-plugin/.claude-plugin/plugin.json)"
         "$(jq -r '.plugins[0].version' .claude-plugin/marketplace.json)"
         "$(grep 'version = ' integrations/beads-mcp/pyproject.toml | head -1 | sed 's/.*"\(.*\)".*/\1/')"
         "$(grep '__version__ = ' integrations/beads-mcp/src/beads_mcp/__init__.py | sed 's/.*"\(.*\)".*/\1/')"
@@ -722,7 +722,7 @@ main() {
         echo "Creating git commit..."
 
         git add cmd/bd/version.go \
-                .claude-plugin/plugin.json \
+                claude-plugin/.claude-plugin/plugin.json \
                 .claude-plugin/marketplace.json \
                 integrations/beads-mcp/pyproject.toml \
                 integrations/beads-mcp/src/beads_mcp/__init__.py \

scripts/check-versions.sh

@@ -43,8 +43,8 @@ check_version "integrations/beads-mcp/src/beads_mcp/__init__.py" \
     "$(grep '__version__ = ' integrations/beads-mcp/src/beads_mcp/__init__.py 2>/dev/null | sed 's/.*"\(.*\)".*/\1/')" \
     "MCP __init__.py"
 
-check_version ".claude-plugin/plugin.json" \
+check_version "claude-plugin/.claude-plugin/plugin.json" \
-    "$(jq -r '.version' .claude-plugin/plugin.json 2>/dev/null)" \
+    "$(jq -r '.version' claude-plugin/.claude-plugin/plugin.json 2>/dev/null)" \
     "Claude plugin.json"
 
 check_version ".claude-plugin/marketplace.json" \