diff --git a/.gitignore b/.gitignore
index 56cee90c..0b504ab4 100644
--- a/.gitignore
+++ b/.gitignore
@@ -9,6 +9,7 @@
 # Test binaries
 *.test
 *.out
+/bd-test
 
 # Go workspace file
 go.work
diff --git a/cmd/bd/autoflush.go b/cmd/bd/autoflush.go
index 3d5dbc3e..8b079639 100644
--- a/cmd/bd/autoflush.go
+++ b/cmd/bd/autoflush.go
@@ -14,7 +14,7 @@ import (
 	"time"
 
 	"github.com/fatih/color"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/types"
 	"golang.org/x/mod/semver"
 )
diff --git a/cmd/bd/daemon.go b/cmd/bd/daemon.go
index 1fa1df28..7d773efc 100644
--- a/cmd/bd/daemon.go
+++ b/cmd/bd/daemon.go
@@ -9,7 +9,7 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/daemon"
 	"github.com/steveyegge/beads/internal/rpc"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
diff --git a/cmd/bd/daemon_config.go b/cmd/bd/daemon_config.go
index bd3a1551..714758b9 100644
--- a/cmd/bd/daemon_config.go
+++ b/cmd/bd/daemon_config.go
@@ -6,7 +6,7 @@ import (
 	"path/filepath"
 	"strconv"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 )
 
 // getGlobalBeadsDir returns the global beads directory (~/.beads)
diff --git a/cmd/bd/daemon_sync.go b/cmd/bd/daemon_sync.go
index df2f8e31..f86b44ec 100644
--- a/cmd/bd/daemon_sync.go
+++ b/cmd/bd/daemon_sync.go
@@ -10,7 +10,7 @@ import (
 	"sort"
 	"time"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/storage"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
diff --git a/cmd/bd/direct_mode.go b/cmd/bd/direct_mode.go
index 40b5a54d..9f18345a 100644
--- a/cmd/bd/direct_mode.go
+++ b/cmd/bd/direct_mode.go
@@ -4,7 +4,7 @@ import (
 	"fmt"
 	"os"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
 )
 
diff --git a/cmd/bd/doctor.go b/cmd/bd/doctor.go
index 44b4ff60..b8949cae 100644
--- a/cmd/bd/doctor.go
+++ b/cmd/bd/doctor.go
@@ -14,7 +14,7 @@ import (
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/configfile"
 	"github.com/steveyegge/beads/internal/daemon"
 	_ "github.com/ncruces/go-sqlite3/driver"
diff --git a/cmd/bd/init.go b/cmd/bd/init.go
index 4463a548..8aa5d0ba 100644
--- a/cmd/bd/init.go
+++ b/cmd/bd/init.go
@@ -10,7 +10,7 @@ import (
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/config"
 	"github.com/steveyegge/beads/internal/configfile"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
diff --git a/cmd/bd/main.go b/cmd/bd/main.go
index cfa53a0a..2a7d556f 100644
--- a/cmd/bd/main.go
+++ b/cmd/bd/main.go
@@ -9,7 +9,7 @@ import (
 	"time"
 
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/config"
 	"github.com/steveyegge/beads/internal/rpc"
 	"github.com/steveyegge/beads/internal/storage"
diff --git a/cmd/bd/migrate.go b/cmd/bd/migrate.go
index 7cf00afc..94e5a6cf 100644
--- a/cmd/bd/migrate.go
+++ b/cmd/bd/migrate.go
@@ -11,7 +11,7 @@ import (
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/configfile"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
diff --git a/cmd/bd/migrate_hash_ids.go b/cmd/bd/migrate_hash_ids.go
index c280e97b..6d62c6cb 100644
--- a/cmd/bd/migrate_hash_ids.go
+++ b/cmd/bd/migrate_hash_ids.go
@@ -15,7 +15,7 @@ import (
 
 	"github.com/fatih/color"
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/storage/sqlite"
 	"github.com/steveyegge/beads/internal/types"
 )
diff --git a/cmd/bd/version.go b/cmd/bd/version.go
index c00512e6..16f0f496 100644
--- a/cmd/bd/version.go
+++ b/cmd/bd/version.go
@@ -5,7 +5,7 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/rpc"
 )
 
diff --git a/cmd/bd/worktree.go b/cmd/bd/worktree.go
index 597bd5b4..8cfbdbe0 100644
--- a/cmd/bd/worktree.go
+++ b/cmd/bd/worktree.go
@@ -7,7 +7,7 @@ import (
 	"path/filepath"
 	"strings"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 )
 
 // isGitWorktree detects if the current directory is in a git worktree
diff --git a/ADVANCED.md b/docs/ADVANCED.md
similarity index 100%
rename from ADVANCED.md
rename to docs/ADVANCED.md
diff --git a/ATTRIBUTION.md b/docs/ATTRIBUTION.md
similarity index 100%
rename from ATTRIBUTION.md
rename to docs/ATTRIBUTION.md
diff --git a/CLAUDE.md b/docs/CLAUDE.md
similarity index 100%
rename from CLAUDE.md
rename to docs/CLAUDE.md
diff --git a/CONFIG.md b/docs/CONFIG.md
similarity index 100%
rename from CONFIG.md
rename to docs/CONFIG.md
diff --git a/EXCLUSIVE_LOCK.md b/docs/EXCLUSIVE_LOCK.md
similarity index 100%
rename from EXCLUSIVE_LOCK.md
rename to docs/EXCLUSIVE_LOCK.md
diff --git a/EXTENDING.md b/docs/EXTENDING.md
similarity index 100%
rename from EXTENDING.md
rename to docs/EXTENDING.md
diff --git a/FAQ.md b/docs/FAQ.md
similarity index 100%
rename from FAQ.md
rename to docs/FAQ.md
diff --git a/INSTALLING.md b/docs/INSTALLING.md
similarity index 100%
rename from INSTALLING.md
rename to docs/INSTALLING.md
diff --git a/LABELS.md b/docs/LABELS.md
similarity index 100%
rename from LABELS.md
rename to docs/LABELS.md
diff --git a/PLUGIN.md b/docs/PLUGIN.md
similarity index 100%
rename from PLUGIN.md
rename to docs/PLUGIN.md
diff --git a/QUICKSTART.md b/docs/QUICKSTART.md
similarity index 100%
rename from QUICKSTART.md
rename to docs/QUICKSTART.md
diff --git a/README_TESTING.md b/docs/README_TESTING.md
similarity index 100%
rename from README_TESTING.md
rename to docs/README_TESTING.md
diff --git a/TEST_OPTIMIZATION.md b/docs/TEST_OPTIMIZATION.md
similarity index 100%
rename from TEST_OPTIMIZATION.md
rename to docs/TEST_OPTIMIZATION.md
diff --git a/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
similarity index 100%
rename from TROUBLESHOOTING.md
rename to docs/TROUBLESHOOTING.md
diff --git a/examples/bd-example-extension-go/main.go b/examples/bd-example-extension-go/main.go
index b6964451..725b30f4 100644
--- a/examples/bd-example-extension-go/main.go
+++ b/examples/bd-example-extension-go/main.go
@@ -10,7 +10,7 @@ import (
 	"log"
 	"time"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 )
 
 //go:embed schema.sql
diff --git a/examples/library-usage/main.go b/examples/library-usage/main.go
index 90026203..75a635d3 100644
--- a/examples/library-usage/main.go
+++ b/examples/library-usage/main.go
@@ -10,7 +10,7 @@ import (
 	"log"
 	"time"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 )
 
 func main() {
diff --git a/examples/library-usage/main_test.go b/examples/library-usage/main_test.go
index 261819e0..87b222f3 100644
--- a/examples/library-usage/main_test.go
+++ b/examples/library-usage/main_test.go
@@ -6,7 +6,7 @@ import (
 	"path/filepath"
 	"testing"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 )
 
 // TestExampleCompiles ensures the example code compiles and basic API works
diff --git a/beads.go b/internal/beads/beads.go
similarity index 100%
rename from beads.go
rename to internal/beads/beads.go
diff --git a/beads_hash_multiclone_test.go b/internal/beads/beads_hash_multiclone_test.go
similarity index 100%
rename from beads_hash_multiclone_test.go
rename to internal/beads/beads_hash_multiclone_test.go
diff --git a/beads_integration_test.go b/internal/beads/beads_integration_test.go
similarity index 99%
rename from beads_integration_test.go
rename to internal/beads/beads_integration_test.go
index be62a7ea..59d443d7 100644
--- a/beads_integration_test.go
+++ b/internal/beads/beads_integration_test.go
@@ -11,7 +11,7 @@ import (
 	"testing"
 	"time"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 )
 
 // integrationTestHelper provides common test setup and assertion methods
diff --git a/beads_multidb_test.go b/internal/beads/beads_multidb_test.go
similarity index 100%
rename from beads_multidb_test.go
rename to internal/beads/beads_multidb_test.go
diff --git a/beads_test.go b/internal/beads/beads_test.go
similarity index 100%
rename from beads_test.go
rename to internal/beads/beads_test.go
diff --git a/fingerprint.go b/internal/beads/fingerprint.go
similarity index 100%
rename from fingerprint.go
rename to internal/beads/fingerprint.go
diff --git a/routing_integration_test.go b/internal/beads/routing_integration_test.go
similarity index 100%
rename from routing_integration_test.go
rename to internal/beads/routing_integration_test.go
diff --git a/internal/daemonrunner/daemon.go b/internal/daemonrunner/daemon.go
index dbb92942..6c824ff8 100644
--- a/internal/daemonrunner/daemon.go
+++ b/internal/daemonrunner/daemon.go
@@ -10,7 +10,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 	"github.com/steveyegge/beads/internal/daemon"
 	"github.com/steveyegge/beads/internal/rpc"
 	"github.com/steveyegge/beads/internal/storage"
diff --git a/internal/daemonrunner/fingerprint.go b/internal/daemonrunner/fingerprint.go
index 66f77545..958006e0 100644
--- a/internal/daemonrunner/fingerprint.go
+++ b/internal/daemonrunner/fingerprint.go
@@ -4,7 +4,7 @@ import (
 	"context"
 	"fmt"
 
-	"github.com/steveyegge/beads"
+	"github.com/steveyegge/beads/internal/beads"
 )
 
 func (d *Daemon) validateDatabaseFingerprint() error {