Merge GH#409

examples/contributor-workflow/README.md

@@ -58,7 +58,7 @@ When you create issues as a contributor:
 bd create "Fix authentication bug" -p 1
 ```
 
-Beads automatically routes this to your planning repo (`~/.beads-planning/.beads/beads.jsonl`), not the current repo.
+Beads automatically routes this to your planning repo (`~/.beads-planning/.beads/issues.jsonl`), not the current repo.
 
 ### Viewing Issues
 

examples/git-hooks/README.md

@@ -129,11 +129,11 @@ This solves bd-my64: changes made between commit and push (or pending debounced
 After a git pull or merge, the hook runs:
 
 ```bash
-bd import -i .beads/beads.jsonl
+bd import -i .beads/issues.jsonl
 ```
 
 This ensures your local database reflects the merged state. The hook:
-- Only runs if `.beads/beads.jsonl` exists (also checks `issues.jsonl` for backward compat)
+- Only runs if `.beads/issues.jsonl` exists (also checks `issues.jsonl` for backward compat)
 - Imports any new issues or updates from the merge
 - Warns on failure but doesn't block the merge
 

examples/git-hooks/pre-commit

@@ -23,20 +23,12 @@ if ! command -v bd >/dev/null 2>&1; then
     exit 0
 fi
 
-# Check if we're in a bd workspace with an actual database
-# Just having a .beads directory isn't enough - it must be properly initialized
+# Check if we're in a bd workspace
 if [ ! -d .beads ]; then
     # Not a bd workspace, nothing to do
     exit 0
 fi
 
-# Verify beads is actually initialized (has database or config)
-# This handles the case where .beads was removed from git but directory lingers
-if [ ! -f .beads/beads.db ] && [ ! -f .beads/config.yaml ] && [ ! -f .beads/issues.jsonl ]; then
-    # Directory exists but beads not initialized, nothing to do
-    exit 0
-fi
-
 # Check if sync-branch is configured in config.yaml or env var
 # If so, .beads changes go to a separate branch via worktree, not the current branch
 SYNC_BRANCH="${BEADS_SYNC_BRANCH:-}"
@@ -54,27 +46,18 @@ fi
 # Flush pending changes to JSONL
 # Use --flush-only to skip git operations (we're already in a git hook)
 # Suppress output unless there's an error
-# Note: We don't block commits on flush failure - beads issues shouldn't prevent code commits
+# Note: We warn but don't fail - this allows commits to proceed even if
+# beads has issues (e.g., user removed .beads from their branch)
 if ! bd sync --flush-only >/dev/null 2>&1; then
     echo "Warning: Failed to flush bd changes to JSONL" >&2
     echo "Run 'bd sync --flush-only' manually to diagnose" >&2
-    # Continue with commit - don't block code changes due to beads issues
+    # Don't block the commit - user may have removed beads or have other issues
 fi
 
-# Stage all tracked JSONL files (issues.jsonl is canonical, beads.jsonl for backward compat, deletions.jsonl for deletion propagation)
-# For worktrees, .beads is in the main repo's working tree, not the worktree,
-# so we can't use git add. Skip staging for worktrees.
-if [ "$(git rev-parse --git-dir)" = "$(git rev-parse --git-common-dir)" ]; then
-    # Regular repo: files are in the working tree, safe to add
-    # git add is harmless if file doesn't exist
-    for f in .beads/beads.jsonl .beads/issues.jsonl .beads/deletions.jsonl; do
-        [ -f "$f" ] && git add "$f" 2>/dev/null || true
-    done
-else
-    # Worktree: .beads is in the main repo's working tree, not this worktree
-    # Git rejects adding files outside the worktree, so we skip it.
-    # The main repo will see the changes on the next pull/sync.
-    :  # do nothing
-fi
+# Stage all tracked JSONL files (beads.jsonl, issues.jsonl for backward compat, deletions.jsonl for deletion propagation)
+# git add is harmless if file doesn't exist
+for f in .beads/beads.jsonl .beads/issues.jsonl .beads/deletions.jsonl; do
+    [ -f "$f" ] && git add "$f" 2>/dev/null || true
+done
 
 exit 0

examples/protected-branch/README.md

@@ -176,11 +176,11 @@ my-project/
 │   ├── beads-worktrees/       # Hidden worktree directory
 │   │   └── beads-metadata/    # Lightweight checkout of sync branch
 │   │       └── .beads/
-│   │           └── beads.jsonl
+│   │           └── issues.jsonl
 │   └── ...
 ├── .beads/                    # Main beads directory (in your workspace)
 │   ├── beads.db               # SQLite database
-│   ├── beads.jsonl            # JSONL export
+│   ├── issues.jsonl            # JSONL export
 │   └── bd.sock                # Daemon socket (if running)
 ├── src/                       # Your application code
 │   └── ...
@@ -209,7 +209,7 @@ my-project/
 
 ### Troubleshooting
 
-**"Merge conflicts in beads.jsonl"**
+**"Merge conflicts in issues.jsonl"**
 
 JSONL is append-only and line-based, so conflicts are rare. If they occur:
 1. Both versions are usually valid - keep both lines

examples/team-workflow/README.md

@@ -244,20 +244,20 @@ Hash-based IDs prevent most conflicts. If conflicts occur:
 ```bash
 # During git pull/merge
 git pull origin beads-metadata
-# CONFLICT in .beads/beads.jsonl
+# CONFLICT in .beads/issues.jsonl
 
 # Option 1: Accept remote
-git checkout --theirs .beads/beads.jsonl
-bd import -i .beads/beads.jsonl
+git checkout --theirs .beads/issues.jsonl
+bd import -i .beads/issues.jsonl
 
 # Option 2: Accept local
-git checkout --ours .beads/beads.jsonl
-bd import -i .beads/beads.jsonl
+git checkout --ours .beads/issues.jsonl
+bd import -i .beads/issues.jsonl
 
 # Option 3: Use beads-merge tool (recommended)
 # See docs/GIT_INTEGRATION.md for merge conflict resolution
 
-git add .beads/beads.jsonl
+git add .beads/issues.jsonl
 git commit
 ```
 
@@ -299,7 +299,7 @@ git commit
 
 ### Q: How do team members see each other's issues?
 
-A: Issues are stored in `.beads/beads.jsonl` which is version-controlled. Pull from git to sync.
+A: Issues are stored in `.beads/issues.jsonl` which is version-controlled. Pull from git to sync.
 
 ```bash
 git pull
@@ -372,9 +372,9 @@ bd daemon --start --auto-commit --auto-push
 Use beads-merge or resolve manually (see [GIT_INTEGRATION.md](../../docs/GIT_INTEGRATION.md)):
 
 ```bash
-git checkout --theirs .beads/beads.jsonl
-bd import -i .beads/beads.jsonl
-git add .beads/beads.jsonl
+git checkout --theirs .beads/issues.jsonl
+bd import -i .beads/issues.jsonl
+git add .beads/issues.jsonl
 git commit
 ```