diff --git a/.beads/.gitignore b/.beads/.gitignore
new file mode 100644
index 0000000..18f762a
--- /dev/null
+++ b/.beads/.gitignore
@@ -0,0 +1,83 @@
+# Dolt database (managed by Dolt, not git)
+dolt/
+embeddeddolt/
+proxieddb/
+
+# Generated local docs/export snapshots
+README.md
+issues.jsonl
+events.jsonl
+interactions.jsonl
+
+# Runtime files
+bd.sock
+bd.sock.startlock
+sync-state.json
+last-touched
+.exclusive-lock
+
+# Daemon runtime (lock, log, pid)
+daemon.*
+
+# Push state (runtime, per-machine)
+push-state.json
+
+# Lock files (various runtime locks)
+*.lock
+
+# Credential key (encryption key for federation peer auth — never commit)
+.beads-credential-key
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+proxied_server_client_info.json
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+export-state/
+export-state.json
+last_pull
+
+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
+
+# Dolt server management (auto-started by bd)
+dolt-server.pid
+dolt-server.log
+dolt-server.lock
+dolt-server.port
+dolt-server.activity
+
+# Debug-mode pprof artifacts (written when dolt.debug: true in config.yaml)
+dolt-pprof/
+
+# Corrupt backup directories (created by bd doctor --fix recovery)
+*.corrupt.backup/
+
+# Backup data (auto-exported JSONL, local-only)
+backup/
+
+# Per-project environment file (Dolt connection config, GH#2520)
+.env
+
+# Legacy files (from pre-Dolt versions)
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
+# NOTE: Do NOT add negation patterns here.
+# They would override fork protection in .git/info/exclude.
+# Config files (metadata.json, config.yaml) are tracked by git by default
+# since no pattern above ignores them.
diff --git a/.beads/config.yaml b/.beads/config.yaml
new file mode 100644
index 0000000..861325d
--- /dev/null
+++ b/.beads/config.yaml
@@ -0,0 +1,68 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: JSONL-only, no Dolt database
+# When true, .beads/issues.jsonl is the only local store
+# no-db: false
+
+# Enable JSON output by default
+# json: false
+
+# Feedback title formatting for mutating commands (create/update/close/dep/edit)
+# 0 = hide titles, N > 0 = truncate to N characters
+# output:
+#   title-length: 255
+
+# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)
+# actor: ""
+
+# Export events (audit trail) to .beads/events.jsonl on each flush/sync
+# When enabled, new events are appended incrementally using a high-water mark.
+# Use 'bd export --events' to trigger manually regardless of this setting.
+# events-export: false
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct database
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Dolt-native backup (periodic backup for off-machine recovery)
+# This is full database backup only. Cross-machine sync uses Dolt remotes.
+# backup:
+#   enabled: false     # Disable auto-backup entirely
+#   interval: 15m      # Minimum time between auto-backups
+#   git-push: false    # Disable git push (backup locally only)
+#   git-repo: ""       # Separate git repo for backups (default: project repo)
+
+# Optional JSONL auto-export for viewers, interchange, and issue-level migration.
+# Disabled by default; enable only when an integration needs fresh .beads/issues.jsonl.
+# Use relative paths under .beads/ for JSONL import/export filenames.
+# export:
+#   auto: false
+#   path: issues.jsonl
+#   interval: 60s
+#   git-add: false
+# import:
+#   path: issues.jsonl
+
+# Integration settings (access with 'bd config get/set')
+# Non-secret keys (stored in the database):
+# - jira.url, jira.project
+# - linear.team_id
+# - github.org, github.repo
+#
+# Secret keys (stored in this file but prefer env vars to avoid git exposure):
+# - linear.api_key  → use LINEAR_API_KEY env var instead
+# - github.token    → use GITHUB_TOKEN env var instead
+
+sync.remote: "git+https://github.com/EntityProcess/allagents"
\ No newline at end of file
diff --git a/.beads/metadata.json b/.beads/metadata.json
new file mode 100644
index 0000000..8ee7f18
--- /dev/null
+++ b/.beads/metadata.json
@@ -0,0 +1,7 @@
+{
+  "database": "dolt",
+  "backend": "dolt",
+  "dolt_mode": "embedded",
+  "dolt_database": "allagents",
+  "project_id": "82b512b7-0232-45ba-94c5-448de92d1afc"
+}
\ No newline at end of file
diff --git a/.gitignore b/.gitignore
index 161f06a..6895676 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,8 +41,11 @@ temp/
 .worktrees/
 allagents.worktrees/
 
-# Beads local Dolt database and runtime files
-.beads/
+# Beads / Dolt files
+.dolt/
+*.db
+.beads-credential-key
+.beads/proxieddb/
 
 # Ralph runtime files (not config)
 .ralph/.call_count
diff --git a/AGENTS.md b/AGENTS.md
index 6e47df4..be0bb62 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -57,6 +57,10 @@ bun install
 - Temporary plans and design notes may live under `.claude/plans/` while work is in progress.
 - Once implementation is complete, delete stale plan files and update durable docs for any user-facing behavior changes.
 
+### Beads
+- Run `bd bootstrap` after cloning if the local issue database is missing; do not re-run `bd init` for this already-initialized repository.
+- Beads syncs through the public AllAgents GitHub repository. Treat all issue content as public.
+
 ## PR & Commit Titles
 - Prefer conventional commit style for branch-facing titles: `type(scope): summary`.
 - Use the repository's normal types where they fit, such as `feat`, `fix`, `docs`, `style`, `refactor`, `test`, and `chore`.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2768a08..51549fb 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,6 +27,13 @@ bun run dev workspace init test-ws
 bun run dev update
 ```
 
+## Issue Tracking
+
+AllAgents uses repo-local Beads state synced through this public GitHub
+repository. After cloning, run `bd bootstrap` to download the issue database;
+do not run `bd init`, because the project identity is already tracked. Treat
+issue titles, descriptions, comments, and attachments as public data.
+
 ## Before Submitting a PR
 
 - PR explains what changed and why