diff --git a/.beads/.gitignore b/.beads/.gitignore
new file mode 100644
index 0000000..b6768db
--- /dev/null
+++ b/.beads/.gitignore
@@ -0,0 +1,66 @@
+# Dolt database and runtime state managed by bd, not git
+dolt/
+embeddeddolt/
+proxieddb/
+dolt-access.lock
+
+# Checkout-local config and identity. Copy config.yaml.example when using Beads.
+config.yaml
+metadata.json
+
+# Generated local docs/export snapshots
+README.md
+issues.jsonl
+events.jsonl
+
+# Runtime files
+bd.sock
+bd.sock.startlock
+sync-state.json
+last-touched
+.exclusive-lock
+daemon.*
+interactions.jsonl
+push-state.json
+*.lock
+
+# Credentials and local version tracking
+.beads-credential-key
+.local_version
+proxied_server_client_info.json
+
+# Worktree redirect and sync state
+redirect
+.sync.lock
+export-state/
+export-state.json
+
+# Ephemeral store
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
+
+# Dolt server management
+dolt-server.pid
+dolt-server.log
+dolt-server.lock
+dolt-server.port
+dolt-server.activity
+dolt-pprof/
+
+# Recovery and backup data
+*.corrupt.backup/
+backup/
+
+# Per-project environment file
+.env
+
+# Legacy files
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
diff --git a/.beads/config.yaml.example b/.beads/config.yaml.example
new file mode 100644
index 0000000..f3386d2
--- /dev/null
+++ b/.beads/config.yaml.example
@@ -0,0 +1,8 @@
+# Beads Configuration File
+# Copy this file to .beads/config.yaml when using Beads in this checkout.
+# Keep .beads/config.yaml local; do not commit it.
+# This file configures default behavior for bd commands in this repository.
+# Runtime identity and database state stay checkout-local and ignored.
+
+federation.remote: "git+https://github.com/EntityProcess/allagents-beads.git"
+sync.remote: "git+https://github.com/EntityProcess/allagents-beads.git"
diff --git a/.gitignore b/.gitignore
index 161f06a..2a31875 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,8 +41,11 @@ temp/
 .worktrees/
 allagents.worktrees/
 
-# Beads local Dolt database and runtime files
-.beads/
+# Beads local config and runtime files
+.beads/*
+!.beads/
+!.beads/.gitignore
+!.beads/config.yaml.example
 
 # Ralph runtime files (not config)
 .ralph/.call_count