fix: improve JSONL-only mode detection and error messages (GH #534)

- Add JSONL-only mode detection in ensureStoreActive() with context-aware
  error messages that suggest correct actions based on project state
- Improve error messages in main.go to detect JSONL presence and suggest
  appropriate solutions (bd init, --no-db flag, or config.yaml setting)
- Update documentation to use issues.jsonl as canonical filename:
  - AGENT_INSTRUCTIONS.md, README.md, resolve-beads-conflict.md
  - docs/GIT_INTEGRATION.md
- Update hook template comments to clarify issues.jsonl is canonical
  while maintaining backward compatibility for beads.jsonl

Fixes #534

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

Co-Authored-By: Claude <noreply@anthropic.com>

cmd/bd/direct_mode.go

@@ -2,6 +2,7 @@ package main
 
 import (
 	"fmt"
+	"os"
 	"path/filepath"
 
 	"github.com/steveyegge/beads/internal/beads"
@@ -62,7 +63,25 @@ func ensureStoreActive() error {
 		if found := beads.FindDatabasePath(); found != "" {
 			dbPath = found
 		} else {
-			return fmt.Errorf("no beads database found. Hint: run 'bd init' in this directory")
+			// Check if this is a JSONL-only project (bd-534)
+			beadsDir := beads.FindBeadsDir()
+			if beadsDir != "" {
+				jsonlPath := filepath.Join(beadsDir, "issues.jsonl")
+				if _, err := os.Stat(jsonlPath); err == nil {
+					// JSONL exists - check if no-db mode is configured
+					if isNoDbModeConfigured(beadsDir) {
+						return fmt.Errorf("this project uses JSONL-only mode (no SQLite database).\n" +
+							"Hint: use 'bd --no-db <command>' or set 'no-db: true' in config.yaml")
+					}
+					// JSONL exists but no-db not configured - fresh clone scenario
+					return fmt.Errorf("found JSONL file but no database: %s\n"+
+						"Hint: run 'bd init' to create the database and import issues,\n"+
+						"      or use 'bd --no-db' for JSONL-only mode", jsonlPath)
+				}
+			}
+			return fmt.Errorf("no beads database found.\n" +
+				"Hint: run 'bd init' to create a database in the current directory,\n" +
+				"      or use 'bd --no-db' for JSONL-only mode")
 		}
 	}
 

cmd/bd/main.go

@@ -329,8 +329,25 @@ var rootCmd = &cobra.Command{
 				// - import: auto-initializes database if missing
 				// - setup: creates editor integration files (no DB needed)
 				if cmd.Name() != "import" && cmd.Name() != "setup" {
-					// No database found - error out instead of falling back to ~/.beads
+					// No database found - provide context-aware error message (bd-534)
 					fmt.Fprintf(os.Stderr, "Error: no beads database found\n")
+
+					// Check if JSONL exists without no-db mode configured
+					if beadsDir != "" {
+						jsonlPath := filepath.Join(beadsDir, "issues.jsonl")
+						if _, err := os.Stat(jsonlPath); err == nil {
+							// JSONL exists but no-db mode not configured
+							fmt.Fprintf(os.Stderr, "\nFound JSONL file: %s\n", jsonlPath)
+							fmt.Fprintf(os.Stderr, "This looks like a fresh clone or JSONL-only project.\n\n")
+							fmt.Fprintf(os.Stderr, "Options:\n")
+							fmt.Fprintf(os.Stderr, "  • Run 'bd init' to create database and import issues\n")
+							fmt.Fprintf(os.Stderr, "  • Use 'bd --no-db %s' for JSONL-only mode\n", cmd.Name())
+							fmt.Fprintf(os.Stderr, "  • Add 'no-db: true' to .beads/config.yaml for permanent JSONL-only mode\n")
+							os.Exit(1)
+						}
+					}
+
+					// Generic error - no beads directory or JSONL found
 					fmt.Fprintf(os.Stderr, "Hint: run 'bd init' to create a database in the current directory\n")
 					fmt.Fprintf(os.Stderr, "      or use 'bd --no-db' to work with JSONL only (no SQLite)\n")
 					fmt.Fprintf(os.Stderr, "      or set BEADS_DIR to point to your .beads directory\n")

cmd/bd/templates/hooks/pre-commit

@@ -4,7 +4,7 @@
 # bd (beads) pre-commit hook
 #
 # This hook ensures that any pending bd issue changes are flushed to
-# .beads/beads.jsonl before the commit is created, preventing the
+# .beads/issues.jsonl before the commit is created, preventing the
 # race condition where daemon auto-flush fires after the commit.
 #
 # When sync-branch is configured in config.yaml, .beads changes are committed
@@ -52,7 +52,7 @@ if ! bd sync --flush-only >/dev/null 2>&1; then
     exit 1
 fi
 
-# Stage all tracked JSONL files (beads.jsonl, issues.jsonl for backward compat, deletions.jsonl for deletion propagation)
+# 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