feat(ux): consolidate Launch Swarm + telemetry UX with minimized strip

- Removed broken LaunchSwarmDialog (formula-based) from TopBar/LeftPanel
- All Rocket buttons (TopBar, LeftPanel, DAG nodes, social cards) now open
  AssignmentPanel (archetype-based) which actually works
- Every Rocket clears taskId first so assignMode && !taskId condition passes
- Conversation button priority: taskId always shows conversation, not assign panel
- Added TelemetryStrip: minimized right sidebar with status dots when non-telemetry
  panel (conversation/assignment) is active
- Live feed has minimize button → restores last taskId or assignMode
- DAG nodes: Signal icon → restores telemetry feed
- Social button on DAG nodes: single router.push to avoid race (setView + setTaskId)
- Fixed social card message button: opens right panel with drawer:closed (no popup)

Co-Authored-By: Oz <oz-agent@warp.dev>

.beads/.gitignore

@@ -1,37 +1,20 @@
-# SQLite databases
+# Dolt database (managed by Dolt, not git)
-*.db
+dolt/
-*.db?*
+dolt-access.lock
-*.db-journal
-*.db-wal
-*.db-shm
 
-# Daemon runtime files
+# Runtime files
-daemon.lock
-daemon.log
-daemon.pid
 bd.sock
+bd.sock.startlock
 sync-state.json
 last-touched
 
 # Local version tracking (prevents upgrade notification spam after git ops)
 .local_version
 
-# Legacy database files
-db.sqlite
-bd.db
-
 # Worktree redirect file (contains relative path to main repo's .beads/)
 # Must not be committed as paths would be wrong in other clones
 redirect
 
-# Merge artifacts (temporary files from 3-way merge)
-beads.base.jsonl
-beads.base.meta.json
-beads.left.jsonl
-beads.left.meta.json
-beads.right.jsonl
-beads.right.meta.json
-
 # Sync state (local-only, per-machine)
 # These files are machine-specific and should not be shared across clones
 .sync.lock
@@ -39,6 +22,31 @@ beads.right.meta.json
 sync_base.jsonl
 export-state/
 
+# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
+ephemeral.sqlite3
+ephemeral.sqlite3-journal
+ephemeral.sqlite3-wal
+ephemeral.sqlite3-shm
+
+# Legacy files (from pre-Dolt versions)
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+db.sqlite
+bd.db
+daemon.lock
+daemon.log
+daemon-*.log.gz
+daemon.pid
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
 # NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
 # They would override fork protection in .git/info/exclude, allowing
 # contributors to accidentally commit upstream issue databases.

.beads/dolt-backup-20260228-101523/beads/.dolt/config.json

@@ -0,0 +1 @@
+{"sqlserver.global.server_uuid":"9e637828-78a2-40ce-a42e-ca5ca4a7a802"}

.beads/dolt-backup-20260228-101523/beads/.dolt/noms/manifest

@@ -0,0 +1 @@
+5:__DOLT__:ee3d304nug0mpt1b2blqghve1mbq90js:k2i717r89p9iiv98psb487u5a1fcn9ud:00000000000000000000000000000000:vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv:780

.beads/dolt-backup-20260228-101523/beads/.dolt/repo_state.json

@@ -0,0 +1,6 @@
+{
+  "head": "refs/heads/main",
+  "remotes": {},
+  "backups": {},
+  "branches": {}
+}

.beads/dolt-backup-20260228-101523/beads/.dolt/stats/.dolt/config.json

@@ -0,0 +1 @@
+{}

.beads/dolt-backup-20260228-101523/beads/.dolt/stats/.dolt/noms/manifest

@@ -0,0 +1 @@
+5:__DOLT__:en77tqaed8kuc69ni6fae3vf1n8rjvpd:oi40bvfrhkfh7rbdposb25s9k5pcgjrk:00000000000000000000000000000000:vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv:31

.beads/dolt-backup-20260228-101523/beads/.dolt/stats/.dolt/repo_state.json

@@ -0,0 +1,6 @@
+{
+  "head": "refs/heads/main",
+  "remotes": {},
+  "backups": {},
+  "branches": {}
+}

.beads/dolt-backup-20260228-101523/beads/beads_beadboard/.dolt/config.json

@@ -0,0 +1 @@
+{}

.beads/dolt-backup-20260228-101523/beads/beads_beadboard/.dolt/noms/manifest

@@ -0,0 +1 @@
+5:__DOLT__:2m0l1k4itn7um9ggb5mfkm2ckqvq6o3k:1vistl61aqe31bfom8puqpp5g9lfvvsd:00000000000000000000000000000000:vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv:20009

.beads/dolt-backup-20260228-101523/beads/beads_beadboard/.dolt/repo_state.json

@@ -0,0 +1,6 @@
+{
+  "head": "refs/heads/main",
+  "remotes": {},
+  "backups": {},
+  "branches": {}
+}

.beads/dolt-backup-20260228-101523/beads/beads_beadboard/.dolt/stats/.dolt/config.json

@@ -0,0 +1 @@
+{}

.beads/dolt-backup-20260228-101523/beads/beads_beadboard/.dolt/stats/.dolt/noms/manifest

@@ -0,0 +1 @@
+5:__DOLT__:64kos6gta8jl5m078stvfmi78es2drud:2bmc3vlk90mo3g9vuiokv5pje660n1e6:00000000000000000000000000000000:vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv:9

.beads/dolt-backup-20260228-101523/beads/beads_beadboard/.dolt/stats/.dolt/repo_state.json

@@ -0,0 +1,6 @@
+{
+  "head": "refs/heads/main",
+  "remotes": {},
+  "backups": {},
+  "branches": {}
+}

.beads/dolt-backup-20260228-101523/beads/config.yaml

@@ -0,0 +1,96 @@
+# Dolt SQL server configuration
+#
+# Uncomment and edit lines as necessary to modify your configuration.
+# Full documentation: https://docs.dolthub.com/sql-reference/server/configuration
+#
+
+# log_level: info
+
+# log_format: text
+
+# max_logged_query_len: 0
+
+# encode_logged_query: false
+
+# behavior:
+  # read_only: false
+  # autocommit: true
+  # disable_client_multi_statements: false
+  # dolt_transaction_commit: false
+  # event_scheduler: "OFF"
+  # auto_gc_behavior:
+    # enable: true
+    # archive_level: 1
+
+listener:
+  host: 127.0.0.1
+  port: 3307
+  # max_connections: 1000
+  # back_log: 50
+  # max_connections_timeout_millis: 60000
+  # read_timeout_millis: 28800000
+  # write_timeout_millis: 28800000
+  # tls_key: key.pem
+  # tls_cert: cert.pem
+  # require_secure_transport: false
+  # allow_cleartext_passwords: false
+  # socket: /tmp/mysql.sock
+
+# data_dir: .
+
+# cfg_dir: .doltcfg
+
+# remotesapi:
+  # port: 8000
+  # read_only: false
+
+# mcp_server:
+  # port: 7007
+  # user: root
+  # password: ""
+  # database: ""
+
+# privilege_file: .doltcfg/privileges.db
+
+# branch_control_file: .doltcfg/branch_control.db
+
+# user_session_vars:
+# - name: root
+  # vars:
+    # dolt_log_level: warn
+    # dolt_show_system_tables: 1
+
+# system_variables:
+  # dolt_log_level: info
+  # dolt_transaction_commit: 1
+
+# jwks: []
+
+# metrics:
+  # labels: {}
+  # host: localhost
+  # port: 9091
+  # tls_cert: ""
+  # tls_key: ""
+  # tls_ca: ""
+
+# cluster:
+  # standby_remotes:
+  # - name: standby_replica_one
+    # remote_url_template: https://standby_replica_one.svc.cluster.local:50051/{database}
+  # - name: standby_replica_two
+    # remote_url_template: https://standby_replica_two.svc.cluster.local:50051/{database}
+  # bootstrap_role: primary
+  # bootstrap_epoch: 1
+  # remotesapi:
+    # address: 127.0.0.1
+    # port: 50051
+    # tls_key: remotesapi_key.pem
+    # tls_cert: remotesapi_chain.pem
+    # tls_ca: standby_cas.pem
+    # server_name_urls:
+    # - https://standby_replica_one.svc.cluster.local
+    # - https://standby_replica_two.svc.cluster.local
+    # server_name_dns:
+    # - standby_replica_one.svc.cluster.local
+    # - standby_replica_two.svc.cluster.local

.beads/dolt-config.log

@@ -0,0 +1,2 @@
+2026-02-28T18:18:36Z actor=unknown key=database value=beadboard beads_dir=/mnt/c/Users/Zenchant/codex/beadboard/.beads
+2026-02-28T18:19:26Z actor=unknown key=database value=beadboard beads_dir=/mnt/c/Users/Zenchant/codex/beadboard/.beads

.beads/dolt-monitor.pid

@@ -0,0 +1 @@
+3840

.beads/dolt-server.activity

@@ -0,0 +1 @@
+1772407425

.beads/dolt-server.pid

@@ -0,0 +1 @@
+60816

.beads/dolt-server.port

@@ -0,0 +1 @@
+3307

.beads/dolt-sql-server.pid

@@ -0,0 +1 @@
+7624

.beads/hooks/post-checkout

@@ -0,0 +1,17 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) post-checkout hook - thin shim
+#
+# This shim delegates to 'bd hooks run post-checkout' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    # Silently skip - post-checkout is called frequently
+    exit 0
+fi
+
+exec bd hooks run post-checkout "$@"

.beads/hooks/post-checkout.backup

@@ -0,0 +1,23 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.52.0
+#
+# bd (beads) post-checkout hook - thin shim
+#
+# This shim delegates to 'bd hook post-checkout' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# The 'bd hook' command (singular) supports:
+# - Guard against frequent firing (only imports if JSONL changed)
+# - Per-worktree state tracking
+# - Dolt branch-then-merge pattern
+# - Hook chaining configuration
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    # Silently skip - post-checkout is called frequently
+    exit 0
+fi
+
+exec bd hook post-checkout "$@"

.beads/hooks/post-merge

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) post-merge hook - thin shim
+#
+# This shim delegates to 'bd hooks run post-merge' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping post-merge hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run post-merge "$@"

.beads/hooks/post-merge.backup

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.52.0
+#
+# bd (beads) post-merge hook - thin shim
+#
+# This shim delegates to 'bd hook post-merge' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# The 'bd hook' command (singular) supports:
+# - Branch-then-merge pattern for Dolt (cell-level conflict resolution)
+# - Per-worktree state tracking
+# - Hook chaining configuration
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping post-merge hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hook post-merge "$@"

.beads/hooks/pre-commit

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v2
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) pre-commit hook — thin shim
+#
+# Delegates to 'bd hooks run pre-commit' which contains the actual hook
+# logic. This pattern ensures hook behavior is always in sync with the
+# installed bd version — no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-commit hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run pre-commit "$@"

.beads/hooks/pre-commit.backup

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.52.0
+#
+# bd (beads) pre-commit hook - thin shim
+#
+# This shim delegates to 'bd hook pre-commit' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# The 'bd hook' command (singular) supports:
+# - Per-worktree export state tracking
+# - Dolt branch-then-merge pattern for cell-level conflict resolution
+# - Hook chaining configuration
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-commit hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hook pre-commit "$@"

.beads/hooks/pre-push

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.56.1
+#
+# bd (beads) pre-push hook - thin shim
+#
+# This shim delegates to 'bd hooks run pre-push' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-push hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run pre-push "$@"

.beads/hooks/pre-push.backup

@@ -0,0 +1,19 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.52.0
+#
+# bd (beads) pre-push hook - thin shim
+#
+# This shim delegates to 'bd hooks run pre-push' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping pre-push hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run pre-push "$@"

.beads/hooks/prepare-commit-msg

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.48.0
+#
+# bd (beads) prepare-commit-msg hook - thin shim
+#
+# This shim delegates to 'bd hooks run prepare-commit-msg' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# Arguments:
+#   $1 = path to the commit message file
+#   $2 = source of commit message (message, template, merge, squash, commit)
+#   $3 = commit SHA-1 (if -c, -C, or --amend)
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping prepare-commit-msg hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run prepare-commit-msg "$@"

.beads/hooks/prepare-commit-msg.backup

@@ -0,0 +1,24 @@
+#!/usr/bin/env sh
+# bd-shim v1
+# bd-hooks-version: 0.48.0
+#
+# bd (beads) prepare-commit-msg hook - thin shim
+#
+# This shim delegates to 'bd hooks run prepare-commit-msg' which contains
+# the actual hook logic. This pattern ensures hook behavior is always
+# in sync with the installed bd version - no manual updates needed.
+#
+# Arguments:
+#   $1 = path to the commit message file
+#   $2 = source of commit message (message, template, merge, squash, commit)
+#   $3 = commit SHA-1 (if -c, -C, or --amend)
+
+# Check if bd is available
+if ! command -v bd >/dev/null 2>&1; then
+    echo "Warning: bd command not found in PATH, skipping prepare-commit-msg hook" >&2
+    echo "  Install bd: brew install beads" >&2
+    echo "  Or add bd to your PATH" >&2
+    exit 0
+fi
+
+exec bd hooks run prepare-commit-msg "$@"

.beads/recovery-20260228-100628/beads.left.meta.json.33396.tmp

@@ -0,0 +1 @@
+{"version":"0.49.6","timestamp":"2026-02-27T14:16:12.6275921-08:00","commit":"fccb2de"}

.dolt/config.json

@@ -0,0 +1 @@
+{}

.dolt/noms/manifest

@@ -0,0 +1 @@
+5:__DOLT__:vlb35ogrn44rmifsbft0pmdf67usbcv2:8dknjhfoe39hgqi0mlndmsk4l9hg3n3d:00000000000000000000000000000000:vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv:14

.dolt/repo_state.json

@@ -0,0 +1,15 @@
+{
+  "head": "refs/heads/main",
+  "remotes": {
+    "origin": {
+      "name": "origin",
+      "url": "https://doltremoteapi.dolthub.com/zenchant/beadboard",
+      "fetch_specs": [
+        "refs/heads/*:refs/remotes/origin/*"
+      ],
+      "params": {}
+    }
+  },
+  "backups": {},
+  "branches": {}
+}

.dolt/stats/.dolt/config.json

@@ -0,0 +1 @@
+{}

.dolt/stats/.dolt/noms/manifest

@@ -0,0 +1 @@
+5:__DOLT__:5l9df01bvbnq5uuo3r7ljh04dk586pvv:lngrtsq2mbn0vpq9cm7sc0ivv2so93ni:00000000000000000000000000000000:vvvvvvvvvvvvvvvvvvvvvvvvvvvvvvvv:9

.dolt/stats/.dolt/repo_state.json

@@ -0,0 +1,6 @@
+{
+  "head": "refs/heads/main",
+  "remotes": {},
+  "backups": {},
+  "branches": {}
+}

CLAUDE.md

@@ -4,7 +4,9 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## What Is BeadBoard
 
-BeadBoard is a Windows-native local dashboard for the [Beads](https://github.com/steveyegge/beads) issue tracker. It reads `.beads/issues.jsonl` files directly from repos and renders them as interactive Kanban boards and dependency graphs. It supports multi-project aggregation, real-time file watching with SSE, and agent/swarm coordination.
+BeadBoard is a Windows-native local dashboard for the [Beads](https://github.com/steveyegge/beads) issue tracker. It reads `.beads/issues.jsonl` files directly from repos and renders them as an **agent-first operations console**: a unified shell with Social, Graph, and Activity lenses for monitoring multi-agent work, managing swarms, and intervening on blockers. It supports multi-project aggregation, real-time file watching with SSE, and swarm/archetype coordination.
+
+**Active UX implementation spec**: `docs/plans/2026-02-28-ux-redesign-synthesis-prd.md`
 
 ## Commands
 
@@ -45,17 +47,21 @@ npm run typecheck && npm run lint && npm run test
 ### Key directories
 
 - `src/app/` — Next.js App Router pages and API routes
-  - `/` — Kanban dashboard (main page)
+  - `/` — **Primary entry point.** `UnifiedShell` with query-param-driven views: `?view=social|graph|activity`
-  - `/graph` — Dependency graph explorer using @xyflow/react + Dagre
+  - `/graph`, `/sessions`, `/timeline` — Legacy routes. Still exist but are not linked from the unified shell. Do not add new features here; migrate functionality into the unified shell instead.
-  - `/sessions` — Agent session management
-  - `/timeline` — Timeline view
   - `/api/beads/` — CRUD endpoints for beads (create, read, update, close, reopen, comment)
   - `/api/events/` — SSE endpoint for real-time updates
   - `/api/swarm/` — Swarm coordination endpoints (create, launch, join, leave, status, templates)
   - `/api/mission/` — Mission/epic management endpoints
   - `/api/agents/` — Agent registry endpoints
-- `src/components/` — UI components organized by feature (kanban, graph, sessions, swarm, shared, etc.)
+- `src/components/` — UI components organized by feature (kanban, graph, sessions, swarm, shared, activity, etc.)
-  - `shared/unified-shell.tsx` — Main layout shell wrapping all pages (top bar, left panel, right panel)
+  - `shared/unified-shell.tsx` — **Root layout.** Top bar, left panel, middle content (view-switched), right panel, thread drawer
+  - `shared/left-panel.tsx` — Navigation spine: view switcher (Social/Graph/Activity), epic tree, filters
+  - `shared/top-bar.tsx` — Global header: identity, health, blocked triage, metric tiles
+  - `activity/contextual-right-panel.tsx` — Right panel content router (branches on URL context)
+  - `activity/activity-panel.tsx` — Activity/telemetry feed (also used as the `activity` view content)
+  - `graph/smart-dag.tsx` — DAG renderer using @xyflow/react + Dagre
+  - `social/social-page.tsx` — Social lens: grouped task cards with dependency/thread context
 - `src/lib/` — Core logic (parser, types, pathing, watcher, realtime, registry, scanner, mutations, graph layout)
   - `types.ts` — Central type definitions (`BeadIssue`, `BeadStatus`, `ProjectContext`, etc.)
   - `pathing.ts` — Windows path canonicalization (drive letter normalization, path keys)

README.md

@@ -1,67 +1,205 @@
 # BeadBoard
+**Work in Progress, please contribute!** 
+**BeadBoard is a multi-agent swarm coordination system built on [Beads](https://github.com/steveyegge/beads) inspired by [Gastown](https://github.com/steveyegge/gastown).** Thanks [Steve Yegge](https://github.com/steveyegge)!
 
-**The Windows-native Control Center for [Beads](https://github.com/steveyegge/beads).**
+BB is a visual operations layer for running agent teams against real dependency-constrained work.
 
-BeadBoard is a high-performance local dashboard for managing your software development tasks. Built on the Beads protocol, it provides a unified, visualization-rich interface over your distributed project landscape.
+---
-![alt text](image.png)
-## 🚀 Why BeadBoard?
-Most task managers are siloes. BeadBoard is a lens over your source code.
-- **Source of Truth**: Reads directly from `.beads/issues.jsonl` in your repo. No database sync skew.
-- **Windows Optimized**: Built from the ground up to handle Windows paths, drive letters, and filesystem performance.
-- **Zero Latency**: Optimistic UI updates make interactions feel instant.
 
-## ✨ Core Features
+## What This App Is
+BeadBoard is not just a task board. It is an execution system for coordinating agents around shared Beads workflows:
 
-### 1. Multi-Project Registry & Scanner
+- Agent-to-agent communication with explicit categories (`HANDOFF`, `BLOCKED`, `DECISION`, `INFO`)
-Stop context switching between repos.
+- Conversation threads merged from activity events, agent messages, and local interactions
-- **Project Registry**: Persist your favorite project roots for one-click access.
+- Graph/topology context for deciding what should move next
-- **Auto-Discovery**: Built-in filesystem scanner finds Bead-enabled projects across your drives.
+- Global project scope switching across single and aggregate workspaces
-- **Aggregate Mode**: View tasks from *all* registered projects in a single unified board.
+- Swarm orchestration with archetypes/templates and assignment controls
 
-### 2. Interactive Kanban Dashboard (`/`)
+---
-Manage your flow state.
-![Kanban Dashboard](assets/kanban-hero.png)
-- **Live Updates**: Boards refresh automatically when the underlying JSONL files change (e.g., via CLI).
-- **Progressive Disclosure**: Task details, metadata, and relations are tucked away until you need them.
-- **Smart Filtering**: Filter by priority, assignee, status, or full-text search across thousands of beads.
 
-### 3. Dependency Graph Explorer (`/graph`)
+![alt text](image-9.png)
-Understand the "Why" and "What's Next".
-![alt text](image-1.png)
-- **Epic-Centric Layout**: Automatically groups tasks by Epic for logical clustering.
-- **True DAG Visualization**: Uses Dagre layout engine to enforce a strict Left-to-Right dependency flow.
-  - *Left*: Incoming Blockers
-  - *Center*: Focus Task
-  - *Right*: Unlocks / Downstream
-- **Focus Mode**: Minimizable dependency strip and deep-linking support for sharing exact views.
-- **Smart Metadata**: See bead counts, priorities, and status health at a glance.
 
-### 4. Agent Sessions Hub (`/sessions`)
+---
-Coordinate multi-agent workflows with social-dense visibility.
-- **Epic-Grouped Task Feed**: Tasks organized by parent Epic with session state indicators (active, reviewing, needs_input, stale).
-- **Cross-Agent Communication**: Built-in messaging with HANDOFF, BLOCKED, and INFO categories.
-- **Agent Productivity Metrics**: Real-time stats showing active tasks, completions, and recent wins.
-- **Derived Activity Engine**: O(N) snapshot diffing computes project history on-demand without separate event storage.
-- **`bb agent` CLI Integration**: Visualizes data from agent registry, reservations, and mailboxes.
 
-### 5. Chronological Timeline (`/timeline`)
+## Core Features
-Real-time activity feed for all project events.
-- **Live Updates**: Server-Sent Events stream changes instantly.
-- **Date Grouping**: Events organized by day (Today, Yesterday, etc.).
-- **Polymorphic Cards**: Distinct visual styles for Status, Lifecycle, and Diff events.
-- **History Buffer**: Recent events preserved across server restarts.
 
-## 🛠️ Stack
+### 1. Agent Communication System
-- **Framework**: Next.js 15 (App Router)
+- Structured message lifecycle: `send`, `inbox`, `read`, `ack`
-- **UI Engine**: React 19 + Framer Motion
+- Message states: `unread`, `read`, `acked`
-- **Styling**: Tailwind CSS + Custom Design System
+- Per-task conversation threads combining:
-- **Type Safety**: Strict TypeScript
+  - activity events
+  - agent mail
+  - local bd interactions
+- Required acknowledgment semantics for high-signal categories (`HANDOFF`, `BLOCKED`)
 
-## ⚡ Quick Start
+### 2. Swarm Coordination Surface
-1. **Install**: `npm install`
+- Agent Pool Monitor with:
-2. **Run**: `npm run dev`
+  - Archetypes
-3. **Explore**: Open `http://localhost:3000`
+  - Templates
+  - Needs Agent queue
+  - Pre-assigned queue
+  - Squad roster
+- Assignment workflow through the graph workspace and right panel
+![alt text](image-7.png) 
 
-## 🤝 Contribution
+### 3. Graph + Dependency Topology
-- **Typecheck**: `npm run typecheck`
+- DAG-oriented graph workspace for execution decisions
-- **Test**: `npm run test`
+- Task/dependency tab modes for different planning lenses
+- Blocker/unblock context surfaced directly in task cards
+- Graph analysis support (cycle and blocked-chain context)
+![alt text](image-8.png)
+
+### 4. Global Project Scope + Scanner
+- Project registry and scanner-backed discovery
+- Single-project and aggregate modes
+- Runtime scope switching without leaving the primary workspace
+
+### 5. Realtime Operations Layer
+- Live updates via watchers + SSE
+- Activity stream integration with session/task context
+- Mutation/writeback feedback integrated into the same operational surface
+
+---
+
+## Runtime Surface
+
+### Active Route
+- `/`
+
+### View Modes
+- `/?view=social`
+- `/?view=graph`
+- `/?view=activity`
+
+### Compatibility Redirects
+- `/graph` -> `/?view=graph`
+- `/sessions` -> `/?view=social`
+- `/timeline` -> `/?view=activity`
+- `/mockup` -> `/`
+
+### Archived Route Vault
+Legacy route implementations are preserved in `reference/routes/**` and excluded from active runtime validation scope.
+
+---
+
+## Install
+
+### Prerequisites
+- Node.js `18.18+` (Node `20 LTS` recommended)
+- npm
+
+### Clone + Install
+```bash
+git clone https://github.com/zenchantlive/beadboard.git
+cd beadboard
+npm install
+```
+
+---
+
+## Quick Start
+
+```bash
+npm run dev
+```
+
+Open:
+
+```text
+http://localhost:3000
+```
+
+---
+
+## Configuration
+No external service is required for core local usage.
+
+Runtime behavior is driven by:
+- Local Beads project data
+- Registered/scanned project roots
+- URL query state (`view`, `task`, `swarm`, `agent`, `epic`, `graphTab`, panel state)
+
+---
+
+## Operating Flow
+
+### 1. Coordinate through Graph + Pool
+Open `/?view=graph`, inspect dependency topology, and drive assignment from the pool panel.
+
+### 2. Communicate in Context
+Open a task thread to read merged conversation context and process message acknowledgments.
+
+### 3. Switch Scope as Work Expands
+Use registry/scanner controls to move between local and aggregate project scope.
+
+### 4. Track Live Signal
+Use social/activity views to monitor execution movement and operational events.
+
+---
+
+## Roadmap Notes
+- Cross-view assign controls in all major views.
+- Social naming/UX evolution (including possible shift toward “swim” terminology).
+- Continued expansion of global project config/scanner workflows.
+
+---
+
+## Scripts
+
+```bash
+npm run dev
+npm run build
+npm run start
+npm run typecheck
+npm run lint
+npm run test
+npm run video
+npm run video:render
+npm run video:thumbnail
+```
+
+---
+
+## Architecture
+- **Frontend**: Next.js App Router + React 19 + Tailwind + Framer Motion + Radix
+- **Graph stack**: XYFlow + Dagre
+- **Core domain**: Beads issue model, graph/kanban/session/social builders
+- **Coordination layer**: agent mail + session communication + swarm orchestration state
+- **Realtime**: watchers + SSE + snapshot differ + activity persistence
+- **Validation/typing**: strict TypeScript + Zod contracts where applicable
+
+---
+
+## Project Structure
+
+```text
+src/
+  app/
+    page.tsx                # active runtime route
+    api/                    # runtime API routes
+  components/
+    shared/ graph/ social/ activity/ sessions/ swarm/ kanban/
+  hooks/
+  lib/
+reference/
+  routes/                   # archived route implementations
+```
+
+---
+
+## Contributing
+1. Keep active runtime pages in `src/app` minimal.
+2. Promote reusable logic into `src/lib`, `src/components`, `src/hooks`.
+3. Archive non-runtime route experiments in `reference/routes`.
+4. Run quality gates before merge:
+
+```bash
+npm run typecheck
+npm run lint
+npm run test
+```
+
+---
+
+## License
+MIT

docs/plans/2026-02-28-bd-only-coordination-migration-plan.md

@@ -0,0 +1,364 @@
+# BD-Only Coordination Migration Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Migrate BeadBoard coordination from `bb` command semantics to `bd`-native audit/event semantics, wire frontend to the new projections, then deprecate `bb` after approval.
+
+**Architecture:** Coordination protocol state is append-only in `bd audit` events (`coord.v1`), lifecycle remains in normal `bd` issue/agent commands, and frontend views are served by projection APIs that derive inbox, reservations, and takeover eligibility from event history + liveness. `bb` remains temporary compatibility code during migration and is removed after parity validation.
+
+**Tech Stack:** Next.js 15, TypeScript, `bd` CLI (Dolt backend), Node test runner (`node --test` + `tsx`)
+
+---
+
+## Scope Lock (Before Code)
+
+In scope:
+- `coord.v1` event schema and validators
+- backend event write/read/projection paths
+- sessions/conversation frontend wiring to new projection APIs
+- migration guardrails and `bb` deprecation flag
+
+Out of scope:
+- redesigning unrelated views
+- changing route model
+- shipping a global CLI package
+
+## Proposed Bead Breakdown
+
+1. `bdcoord.1` Schema freeze: finalize `coord.v1` fields and transitions.
+2. `bdcoord.2` Event writer API + validation.
+3. `bdcoord.3` Projection engine for inbox/read/ack.
+4. `bdcoord.4` Projection engine for reservations/takeover.
+5. `bdcoord.5` API integration in sessions and conversation routes.
+6. `bdcoord.6` Frontend wiring in conversation/sessions components.
+7. `bdcoord.7` Legacy `bb` deprecation toggle and compatibility fallback.
+8. `bdcoord.8` Tests + full gates + migration sign-off checklist.
+
+## Task 1: Baseline and Schema Freeze
+
+**Files:**
+- Modify: `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`
+- Modify: `docs/protocols/operative-protocol-v1.md`
+- Test: `tests/lib/coord-schema.test.ts` (new)
+
+**Step 1: Write the failing test**
+
+Create `tests/lib/coord-schema.test.ts` with assertions for:
+- required fields by event type
+- valid/invalid `event_ref`
+- allowed takeover modes
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --import tsx --test tests/lib/coord-schema.test.ts`  
+Expected: FAIL (module/validator not implemented).
+
+**Step 3: Write minimal implementation**
+
+Create schema constants/types in new module:
+- `src/lib/coord-schema.ts`
+
+Implement:
+- event type union
+- required-field checks per type
+- basic runtime validator
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --import tsx --test tests/lib/coord-schema.test.ts`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add docs/protocols/2026-02-28-bd-audit-coordination-schema.md docs/protocols/operative-protocol-v1.md src/lib/coord-schema.ts tests/lib/coord-schema.test.ts
+git commit -m "feat(protocol): freeze coord.v1 schema and validator"
+```
+
+## Task 2: Event Write Path (`bd audit`)
+
+**Files:**
+- Create: `src/lib/coord-events.ts`
+- Modify: `src/lib/bridge.ts`
+- Create: `src/app/api/coord/events/route.ts`
+- Test: `tests/lib/coord-events.test.ts`
+- Test: `tests/api/coord-events-route.test.ts`
+
+**Step 1: Write the failing test**
+
+Add tests for:
+- successful `bd audit record --stdin` invocation
+- rejection on invalid payload
+- deterministic envelope normalization
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --import tsx --test tests/lib/coord-events.test.ts`  
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+In `src/lib/coord-events.ts`, implement:
+- `writeCoordEvent(input, { projectRoot })`
+- schema validation call
+- payload -> audit entry transform
+- bridge command execution
+
+In route `src/app/api/coord/events/route.ts`:
+- `POST` accepts event JSON and writes via `writeCoordEvent`
+
+**Step 4: Run tests to verify they pass**
+
+Run:
+- `node --import tsx --test tests/lib/coord-events.test.ts`
+- `node --import tsx --test tests/api/coord-events-route.test.ts`
+
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/lib/coord-events.ts src/app/api/coord/events/route.ts tests/lib/coord-events.test.ts tests/api/coord-events-route.test.ts
+git commit -m "feat(coord): add bd-audit event write path and API"
+```
+
+## Task 3: Inbox Projection Engine
+
+**Files:**
+- Create: `src/lib/coord-projections.ts`
+- Modify: `src/app/api/sessions/[beadId]/conversation/route.ts`
+- Modify: `src/lib/agent-sessions.ts`
+- Test: `tests/lib/coord-projections-inbox.test.ts`
+
+**Step 1: Write the failing test**
+
+Cover:
+- unread/read/acked derivation from `SEND/READ/ACK`
+- duplicate/late event ordering behavior
+- unknown references ignored safely
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --import tsx --test tests/lib/coord-projections-inbox.test.ts`  
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+Implement projection functions:
+- `projectInbox(events, beadId, agentId?)`
+- `projectMessageState(events)`
+
+Integrate route to return projected inbox entries.
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --import tsx --test tests/lib/coord-projections-inbox.test.ts`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/lib/coord-projections.ts src/app/api/sessions/[beadId]/conversation/route.ts src/lib/agent-sessions.ts tests/lib/coord-projections-inbox.test.ts
+git commit -m "feat(coord): derive inbox projection from audit events"
+```
+
+## Task 4: Reservation and Takeover Projection Engine
+
+**Files:**
+- Modify: `src/lib/coord-projections.ts`
+- Modify: `src/lib/agent-sessions.ts`
+- Modify: `src/app/api/sessions/route.ts`
+- Test: `tests/lib/coord-projections-reservations.test.ts`
+
+**Step 1: Write the failing test**
+
+Cover:
+- exact/partial/disjoint overlap
+- active/stale/evicted takeover policy
+- release and supersession behavior
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --import tsx --test tests/lib/coord-projections-reservations.test.ts`  
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+Add:
+- scope normalization utility
+- reservation reducer over events
+- takeover eligibility helper using agent liveness
+
+Expose projected reservation/incursion shape from sessions API.
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --import tsx --test tests/lib/coord-projections-reservations.test.ts`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/lib/coord-projections.ts src/lib/agent-sessions.ts src/app/api/sessions/route.ts tests/lib/coord-projections-reservations.test.ts
+git commit -m "feat(coord): add reservation and takeover projections"
+```
+
+## Task 5: Conversation and Sessions Frontend Wiring
+
+**Files:**
+- Modify: `src/components/sessions/conversation-drawer.tsx`
+- Modify: `src/components/sessions/sessions-page.tsx`
+- Modify: `src/hooks/use-session-feed.ts`
+- Test: `tests/components/sessions/conversation-drawer-coord.test.tsx` (new)
+- Test: `tests/api/sessions-route.test.ts`
+
+**Step 1: Write the failing test**
+
+Cover:
+- render projected message state labels
+- mark read/ack via new coord event endpoint
+- refresh behavior without full page reload
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --import tsx --test tests/components/sessions/conversation-drawer-coord.test.tsx`  
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+Update drawer and hooks to:
+- read new projection payloads
+- post `READ/ACK/RESERVE/RELEASE/TAKEOVER` events
+- preserve current UI labels and behavior
+
+**Step 4: Run test to verify it passes**
+
+Run:
+- `node --import tsx --test tests/components/sessions/conversation-drawer-coord.test.tsx`
+- `node --import tsx --test tests/api/sessions-route.test.ts`
+
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/components/sessions/conversation-drawer.tsx src/components/sessions/sessions-page.tsx src/hooks/use-session-feed.ts tests/components/sessions/conversation-drawer-coord.test.tsx tests/api/sessions-route.test.ts
+git commit -m "feat(frontend): wire sessions UI to bd coordination projections"
+```
+
+## Task 6: Legacy `bb` Deprecation Toggle
+
+**Files:**
+- Modify: `src/lib/agent-mail.ts`
+- Modify: `src/lib/agent-reservations.ts`
+- Modify: `src/lib/agent-sessions.ts`
+- Modify: `skills/beadboard-driver/SKILL.md` (defer final content until sign-off)
+- Create: `docs/protocols/2026-02-28-bb-deprecation-notes.md`
+- Test: `tests/lib/coord-legacy-fallback.test.ts` (new)
+
+**Step 1: Write the failing test**
+
+Cover:
+- when `BB_LEGACY_COMPAT=off`, only new projection path is used
+- when `BB_LEGACY_COMPAT=on`, fallback remains operational
+
+**Step 2: Run test to verify it fails**
+
+Run: `node --import tsx --test tests/lib/coord-legacy-fallback.test.ts`  
+Expected: FAIL.
+
+**Step 3: Write minimal implementation**
+
+Add feature-flagged compatibility path and deprecation warnings in server logs.
+
+**Step 4: Run test to verify it passes**
+
+Run: `node --import tsx --test tests/lib/coord-legacy-fallback.test.ts`  
+Expected: PASS.
+
+**Step 5: Commit**
+
+```bash
+git add src/lib/agent-mail.ts src/lib/agent-reservations.ts src/lib/agent-sessions.ts docs/protocols/2026-02-28-bb-deprecation-notes.md tests/lib/coord-legacy-fallback.test.ts
+git commit -m "chore(coord): add bb compatibility toggle and deprecation notes"
+```
+
+## Task 7: Full Verification and Sign-Off Gate
+
+**Files:**
+- Modify: `README.md` (only if runtime command docs changed)
+- Modify: `docs/protocols/2026-02-28-bd-audit-coordination-schema.md` (final lock)
+
+**Step 1: Run focused test suites**
+
+Run each new/changed suite directly before full gate.
+
+**Step 2: Run full gate commands**
+
+Run:
+- `npm run typecheck`
+- `npm run lint`
+- `npm run test`
+
+Expected: all PASS.
+
+**Step 3: Record evidence in bead notes**
+
+For each migration bead:
+- add command output summary
+- attach key API/UX behavior evidence
+
+**Step 4: Final commit**
+
+```bash
+git add README.md docs/protocols/2026-02-28-bd-audit-coordination-schema.md
+git commit -m "docs(coord): finalize bd-only migration contract and verification evidence"
+```
+
+## Task 8: Post-Approval Removal of `bb` Paths
+
+This task starts only after explicit user approval.
+
+**Files:**
+- Remove/Modify all remaining `bb` command references and dead code paths
+- Update: `skills/beadboard-driver/SKILL.md` to `bd`-only operations
+- Update: skill reference docs under `skills/beadboard-driver/references/`
+
+**Step 1: Remove compatibility code**
+
+Delete `bb` fallback paths and feature flag checks.
+
+**Step 2: Update skill contract to final state**
+
+Replace all `bb agent ...` instructions with `bd` + API-based coordination contract.
+
+**Step 3: Run full verification**
+
+Run:
+- `npm run typecheck`
+- `npm run lint`
+- `npm run test`
+
+Expected: all PASS.
+
+**Step 4: Commit**
+
+```bash
+git add -A
+git commit -m "refactor(coord): remove bb legacy path after bd migration approval"
+```
+
+## Open Questions to Resolve During Execution
+
+1. Exact `bd audit` entry JSON shape accepted by current `bd` build for custom `kind`.
+2. Whether conversation timeline should merge comments + protocol events in one sorted stream or dual-stream UI.
+3. Whether projected reservation state should be cached server-side or recomputed per request.
+4. Whether `tests/lib/*` additions must be explicitly appended to `npm run test` command list (current suite is enumerated).
+
+## Completion Contract
+
+Migration is complete when:
+1. Sessions and conversation UX function using only `bd`-backed protocol events/projections.
+2. `bb` behavior is either behind explicit compat flag or removed after approval.
+3. Full quality gates pass with fresh evidence.
+4. Skill docs are updated to match shipped behavior (after migration sign-off).

docs/prompts/2026-02-28-next-session-dolt-repair.md

@@ -0,0 +1,75 @@
+# Next Session Prompt: Dolt/Beads Database Recovery and Source-of-Truth Reconciliation
+
+You are continuing work in `/mnt/c/Users/Zenchant/codex/beadboard`.
+
+## Problem snapshot (as of 2026-02-28)
+Bead state appears empty in `bd ready`, but `.beads/issues.jsonl` contains historical data.
+
+Observed signals:
+- `bd status` reports only **3 closed issues** (0 open/in_progress/blocked).
+- `.beads/issues.jsonl` has **381 lines**.
+- `bd doctor --dry-run` reports:
+  - **Dolt-JSONL count mismatch** (`Dolt has 3, JSONL has 381`)
+  - stale/merge artifacts and lock issues
+  - config mismatch hints in `.beads/metadata.json`
+- Prior repair attempt hit lock/permission conflicts (`database is locked by another dolt process`).
+
+## Goal
+Restore BeadBoard to a consistent, usable state where `bd` in this repo reflects the expected issue set, and `bd ready` shows correct ready work.
+
+## Non-goals
+- No frontend feature work.
+- No broad refactors.
+- No destructive git resets.
+
+## Required outcomes
+1. Clear diagnosis of why Dolt state diverged from JSONL state.
+2. Safe repair path applied (or a precise blocker report if repair cannot complete).
+3. Post-repair verification evidence showing issue counts and ready-state are sane.
+4. Short write-up on recurrence prevention.
+
+## Guardrails
+- Treat `.beads/issues.jsonl` as historical source candidate, but verify before forcing import.
+- Avoid direct manual edits to `.beads/issues.jsonl`.
+- Use `bd` commands and documented repair flows first.
+- Do not run destructive git commands.
+
+## Suggested execution order
+1. **Capture baseline evidence**
+   - `bd where`
+   - `bd status`
+   - `bd ready`
+   - `bd list --status open --status in_progress --status blocked --json`
+   - `wc -l .beads/issues.jsonl`
+   - `bd doctor --dry-run`
+
+2. **Check lock/process state**
+   - Identify active `bd`/`dolt` processes.
+   - Identify stale lock files in `.beads`.
+   - Resolve lock conflicts in a non-destructive way.
+
+3. **Repair using bd-supported flow**
+   - Attempt `bd doctor --fix --source=jsonl --yes`.
+   - If still divergent, run focused checks (`bd doctor --check=validate`, `bd doctor --check=artifacts`).
+   - If needed, document and execute the minimal additional `bd` recovery command sequence.
+
+4. **Reconcile and verify**
+   - Re-run `bd status`, `bd ready`, `bd list --json`.
+   - Confirm counts are no longer `3 vs 381` divergent.
+   - Confirm expected open/ready beads appear.
+
+5. **Record root cause + prevention**
+   - Add a concise note in docs (or bead notes) on:
+     - root cause
+     - repair steps that worked
+     - required hygiene (locks, hooks, sync flow, config keys)
+
+## Deliverables
+1. Repair summary with command evidence.
+2. Final healthy `bd` status/ready output summary.
+3. Minimal prevention checklist for future sessions.
+
+## Completion criteria
+- `bd` issue inventory in this repo is consistent with expected project history.
+- `bd ready` is no longer falsely empty due to DB divergence.
+- No destructive repository actions were used.

docs/prompts/2026-02-28-next-session-holistic-ux-critique.md

@@ -0,0 +1,94 @@
+# Next Session Prompt: Holistic UX Critique for Professional Multi-Agent Operations
+
+You are continuing work in `/mnt/c/Users/Zenchant/codex/beadboard`.
+
+## Understanding Brief
+BeadBoard is intended to be a **professional multi-agent communication + work management system** where:
+- agents coordinate through Beads (`bd`) state,
+- humans supervise, intervene, and steer,
+- both can collaborate across multiple repos/projects.
+
+This is **not** just a task board. It is an operations surface for swarm-style execution, communication, assignment, and recovery.
+
+## Recent work completed (must understand before critique)
+1. `bd`/Dolt recovery was performed after severe divergence:
+   - prior broken state: Dolt showed only a few issues while historical stores had hundreds,
+   - repaired state now shows healthy inventory (381 issues) and non-empty `bd ready`.
+2. Runtime assumptions changed:
+   - `bd` upgraded to `0.56.1`.
+   - Dolt server mode is operationally relevant (`127.0.0.1:3307`).
+3. `bd` command execution was moved toward PATH-based portability and clearer setup failure handling.
+
+Do not re-do this recovery unless evidence shows a new regression.
+
+## First required step (before UX critique)
+Audit current local uncommitted work and summarize it in UX terms.
+
+Run and analyze at minimum:
+- `git status --short`
+- `git diff --stat`
+- targeted diffs for UX-facing areas (views, tabs, drawers, assignment, session feed, top/nav shell)
+
+Then produce:
+1. what changes are incomplete but directionally correct,
+2. what changes conflict with intended product behavior,
+3. what changes increase accidental complexity.
+
+## Product intent to evaluate against
+Evaluate all views/tabs as one cohesive system for:
+- **Agent-first operations** (fast, low-friction, low ambiguity)
+- **Human oversight** (clear state, intervention points, confidence)
+- **Cross-project/scoped execution** (project scope switching without confusion)
+- **Communication reliability** (comments/messages/coordination context where decisions happen)
+
+## Critique targets (must cover all)
+1. Information architecture across main views/tabs.
+2. Distinct role of each major surface (`Social`, `Graph`, `Sessions`, side panels, drawers).
+3. Assignment UX consistency and discoverability.
+4. Communication model UX (threads/comments/agent interactions) and where it breaks flow.
+5. State clarity: ready vs blocked vs in-progress; ownership; handoff visibility.
+6. Failure mode UX (server unavailable, path/config mismatches, stale data indicators).
+7. Cognitive load: where operators need to context-switch too much.
+8. Terminology consistency (`bead`, `task`, `swarm`, `molecule`, `session`, `agent`).
+
+## Required outputs
+### 1) UX Critique Report
+Provide a structured critique with:
+- **What is working** (keep)
+- **What is ambiguous** (clarify)
+- **What is broken/risky** (fix)
+- severity per issue (`P0`, `P1`, `P2`)
+- concrete file/component references
+
+### 2) Target UX Model (recommended)
+Propose a clean target model for view responsibilities:
+- one-line purpose per view/tab,
+- key interactions per surface,
+- interactions that must be shared vs isolated.
+
+### 3) Prioritized execution backlog
+Create beads for follow-up work from critique findings:
+- one bead per coherent unit,
+- include scope/out-of-scope and acceptance criteria,
+- preserve dependency correctness.
+
+### 4) Minimal change strategy
+Recommend a staged rollout plan that avoids large regressions:
+- phase 1: low-risk high-value consistency fixes,
+- phase 2: IA/view role cleanup,
+- phase 3: deeper workflow refinements.
+
+## Constraints
+- Preserve current route model (`/` with `view=` query params).
+- Keep changes grounded in actual implemented code (no speculative claims).
+- Reuse shared components/logic; avoid one-off behavior per view.
+- Keep language simple and operator-facing.
+- **Approval gate:** Do not create any beads during discovery/brainstorming. First present findings + proposed bead backlog draft, then wait for explicit user approval before running any `bd create` commands.
+
+## Quality bar
+The critique should read like a professional product/UX architecture review for an agent operations platform, not generic UI feedback.
+
+## Completion criteria
+- Clear diagnosis of current UX shape using actual uncommitted code.
+- Decision-ready target model for views/tabs and communication surfaces.
+- Prioritized, execution-ready bead backlog generated from findings.

docs/prompts/2026-02-28-next-session-swarm-ux.md

@@ -0,0 +1,63 @@
+# Next Session Prompt: BeadBoard View Strategy + Assign Everywhere
+
+You are continuing work on `/beadboard`.
+
+## Product framing
+BeadBoard is a **multi-agent swarm coordination and communication system built on Beads**.  
+DAG/topology, project scope switching, and command-feed views exist to improve swarm coordination outcomes.
+
+## Immediate goal
+Clarify the product-level difference between:
+1. `Social` view, and
+2. `Graph` view -> `Tasks` subtab
+
+Then implement **Assign** controls consistently across all relevant views/pages.
+
+## Why this matters
+If Social and Graph/Tasks do the same job, the UX is ambiguous and hard to maintain.  
+If Assign exists in only one place, operator workflows are fragmented.
+
+## Required questions to answer first
+1. What is the unique purpose of Social view?
+2. What is the unique purpose of Graph/Tasks subtab?
+3. Which interactions belong only in one of them?
+4. Which interactions must be shared?
+5. Should Social be renamed/reframed (for example toward “Swim” / “Command Feed”)?
+
+Write this as a short decision note before coding.
+
+## Implementation target
+Add an **Assign** action to all major operational surfaces (not only Graph).
+
+Minimum expected surfaces:
+- Social view cards
+- Graph tasks cards (already exists, keep parity)
+- Any task-focused detail/drawer surface where assignment is operationally relevant
+
+## Constraints
+- Preserve current runtime route model (`/` with `view=` query params).
+- Keep claims and behavior aligned to actual shipped code.
+- Reuse existing assignment logic/components; avoid duplicate one-off implementations.
+- Keep diffs scoped and maintainable.
+
+## Deliverables
+1. Decision note: “Social vs Graph/Tasks” (clear, concise, actionable).
+2. Code changes implementing Assign parity across views.
+3. README touch-up only if wording must change after decisions.
+4. Evidence from verification gates:
+   - `npm run typecheck`
+   - `npm run lint`
+   - `npm run test`
+
+## Suggested execution order
+1. Audit current assign entry points/components.
+2. Define shared assignment UI contract (props/events/state).
+3. Implement Social + detail/drawer assignment affordance(s).
+4. Normalize labels/tooltips/copy for consistency.
+5. Run full verification gates.
+6. Summarize behavior changes and unresolved UX questions.
+
+## Completion criteria
+- Assign is discoverable and usable from every major task-operating surface.
+- Social and Graph/Tasks have clearly distinct roles in both UX and docs.
+- No regressions in typecheck/lint/tests.

docs/prompts/dag-swarm-remotion-prompt.md

@@ -0,0 +1,121 @@
+# Production-Grade Remotion Prompt (Super Fire)
+
+> **Purpose:** Generate a truly production-grade Remotion animation with elite visual style, cinematic timing, and intentional motion design that looks like a real launch trailer hero segment.
+
+```xml
+<system_spec version="2.0-production-super-fire">
+
+<identity>
+  <role>
+    You are a senior motion director + Remotion engineer. You create premium launch-trailer
+    visuals, not template animation. Every frame must feel designed.
+  </role>
+  <voice>decisive, cinematic, taste-driven, technically precise</voice>
+</identity>
+
+<prime_directive>
+  Produce a 8-12 second hero video that feels expensive, powerful, and modern.
+  Prioritize visual impact, rhythm, and clarity over gimmicks.
+</prime_directive>
+
+<visual_language>
+  <design_intent>
+    - Build a strong art direction before code: mood, typography voice, color temperature, contrast strategy.
+    - Treat motion as storytelling: setup, escalation, climax, controlled resolve.
+  </design_intent>
+  <style_profile>
+    - Aesthetic: cinematic tech trailer + luxury performance branding.
+    - Lighting feel: high contrast with controlled glow, not bloom overload.
+    - Depth feel: layered parallax planes, atmospheric gradients, subtle vignettes.
+    - Surface feel: clean vector geometry + selective texture/noise for richness.
+  </style_profile>
+  <color_script>
+    - Base: near-black / graphite.
+    - Energy accents: ember orange + signal red (small percentage, high impact).
+    - Neutral counterbalance: soft off-white text and cool gray UI lines.
+    - Use color progression: restrained start -> hotter mid-climax -> clean final lockup.
+  </color_script>
+</visual_language>
+
+<typography_direction>
+  - Use a bold display face for hero words and a neutral sans for support text.
+  - Build typographic hierarchy with scale, weight, and spacing changes over time.
+  - Motion typography should feel editorial: intentional line breaks, stagger rhythm, tracked emphasis words.
+  - Keep key message readable in under 1 second per major title beat.
+</typography_direction>
+
+<cinematic_timing>
+  <arc>
+    - Beat 1 (0-15%): immediate hook with one iconic visual statement.
+    - Beat 2 (15-55%): controlled acceleration with 2-3 escalating reveals.
+    - Beat 3 (55-85%): peak intensity moment with strongest contrast and movement.
+    - Beat 4 (85-100%): confident hold for brand memory and readability.
+  </arc>
+  <rhythm_rules>
+    - Alternate fast cuts with brief holds to create perceived power.
+    - Use silence/negative space moments before the hardest hit.
+    - Never keep identical motion energy for more than ~40 frames.
+  </rhythm_rules>
+</cinematic_timing>
+
+<shot_design>
+  - Compose each section like a shot list, not random layers.
+  - Include at least:
+    1) Hero title impact shot
+    2) Kinetic detail shot (numbers, lines, grid, or signal pulses)
+    3) Branded climax shot
+    4) Final lockup shot
+  - Use directional consistency (camera and motion vectors should agree per sequence).
+</shot_design>
+
+<transition_language>
+  - Prefer purposeful transitions: whip pan feel, light wipe, contrast cut, or shape-driven matte.
+  - Avoid generic fades unless used as deliberate breath moments.
+  - Transition should carry narrative momentum, not just hide edits.
+</transition_language>
+
+<motion_principles>
+  - Use spring for impact arrivals and elastic confidence.
+  - Use interpolate + easing for precise travel and timing control.
+  - Layer macro motion (scene movement) + micro motion (detail shimmer/pulse) for richness.
+  - Apply anticipation before major impacts (small pull-back or dim pre-hit).
+  - Add restrained camera shake only on peak beats.
+</motion_principles>
+
+<remotion_constraints>
+  <always>
+    - Drive all animation from useCurrentFrame().
+    - Use useVideoConfig() and fps-relative timing.
+    - Use Sequence for structure.
+    - Use Remotion media primitives (Img/Video/Audio).
+    - Keep deterministic output (no time/random drift).
+  </always>
+  <never>
+    - No CSS keyframes/transitions.
+    - No template-looking presets repeated unchanged.
+    - No visual clutter that weakens message legibility.
+  </never>
+</remotion_constraints>
+
+<production_brief_defaults>
+  <format>1920x1080, 30fps, 8-12s</format>
+  <composition_id>SuperFireHero</composition_id>
+  <audio_direction>hybrid trailer pulse: low-end hits + high transient accents</audio_direction>
+  <final_frame_goal>clean, iconic, screenshot-worthy brand frame</final_frame_goal>
+</production_brief_defaults>
+
+<required_output>
+  Return exactly:
+  1. Creative treatment (art direction + narrative arc + shot list).
+  2. Full Remotion TypeScript implementation.
+  3. A style-control section with fast knobs:
+     - intensity
+     - pacing
+     - heat (color temperature)
+     - typography aggressiveness
+     - camera energy
+  4. Render command(s).
+</required_output>
+
+</system_spec>
+```

docs/protocols/2026-02-28-agent-first-ui-decisions.md

@@ -0,0 +1,35 @@
+# Agent-First UI Decisions for Coordination Migration
+
+Date: 2026-02-28  
+Status: Approved implementation defaults
+
+## Decision Summary
+
+1. Coordination writes are agent-first by default.
+2. Human operators supervise, comment, and override only when needed.
+3. Sessions conversation timeline remains a merged feed (activity + protocol + comments).
+
+## Interaction Ownership
+
+### Agent-owned by default
+
+- `SEND`, `READ`, `ACK`, `RESERVE`, `RELEASE`, `TAKEOVER` protocol events.
+- Routine reservation and handoff execution.
+
+### Human-owned by default
+
+- `bd comments` discussion entries.
+- Override intervention decisions (for blocked/conflict situations).
+
+## UI Behavior
+
+1. Conversation actions (`Seen`, `Accept`) emit `coord.v1` events via `/api/coord/events`.
+2. Comment composer includes explicit `Comment as` username field; value is persisted locally for convenience.
+3. Human comments use provided actor handle (instead of default email) when supplied.
+4. Incursions are computed from reservation projections and shown in sessions feed context.
+
+## Identity Policy
+
+1. Human comments should use user handle (for example `zenchant`) not raw email whenever available.
+2. Protocol events should use agent identity in `actor`.
+3. Timeline rendering must preserve actor attribution so human and agent actions stay distinguishable.

docs/protocols/2026-02-28-bb-deprecation-notes.md

@@ -0,0 +1,24 @@
+# BB Deprecation Notes (Draft)
+
+Date: 2026-02-28  
+Status: Legacy compatibility removed from migrated coordination path
+
+## Intent
+
+`bb` coordination paths are legacy compatibility behavior while `bd` audit/event protocol paths are rolled out.
+
+## Runtime Behavior
+
+- Sessions communication now uses `coord.v1` projections only.
+- Legacy mailbox fallback is removed from the migrated sessions path.
+
+## Removal Criteria
+
+1. Sessions and conversation flows operate correctly using only `coord.v1` projections.
+2. Read/ack actions are emitted via `/api/coord/events`.
+3. `npm run typecheck`, `npm run lint`, `npm run test` results are reviewed for migration-related regressions.
+
+## Post-Approval Work
+
+1. Update `skills/beadboard-driver` to `bd`-only commands and projection APIs.
+2. Remove deprecated route handlers that mutate legacy mailbox state.

docs/protocols/2026-02-28-bd-audit-coordination-schema.md

@@ -0,0 +1,120 @@
+# BD Audit Coordination Schema (Draft)
+
+Date: 2026-02-28  
+Status: Draft for skill migration planning  
+Scope: Replace `bb` coordination semantics with `bd`-native event/audit contracts
+
+Related protocol baseline:
+- `docs/protocols/operative-protocol-v1.md`
+
+## Intent
+
+Use `bd` as the only required system in agent work repos. Keep coordination state in append-only audit events, and keep human context in bead comments.
+
+Primary storage:
+- protocol state: `bd audit record --stdin`
+- lifecycle state: `bd update`, `bd close`, `bd agent state`, `bd agent heartbeat`
+- narrative context: `bd comments add`
+
+## Why Audit-First
+
+1. Append-only event log fits protocol timelines.
+2. Dolt history gives immutable version snapshots and diffability across event evolution.
+3. Frontend projections (inbox, reservation map, takeover eligibility) can be derived deterministically from event history.
+
+## Event Envelope (v1)
+
+Every coordination event SHOULD use this envelope (JSON sent through `bd audit record --stdin`):
+
+```json
+{
+  "version": "coord.v1",
+  "kind": "coord_event",
+  "issue_id": "bb-123",
+  "actor": "amber-otter",
+  "timestamp": "2026-02-28T18:00:00.000Z",
+  "data": {
+    "event_type": "RESERVE",
+    "event_id": "evt_01JN6Y1Q7R80E8P6K1Q5",
+    "project_root": "/abs/path/to/repo",
+    "to_agent": "cobalt-harbor",
+    "scope": "src/lib/*",
+    "state": "unread",
+    "takeover_mode": "none",
+    "reason": "",
+    "payload": {}
+  }
+}
+```
+
+Notes:
+- `kind` remains compatible with `bd audit` entry typing.
+- protocol-specific fields live under `data`.
+- `event_id` MUST be globally unique and stable for dedupe.
+
+## Canonical Event Types
+
+Required for parity with current `bb` behavior:
+1. `SEND`: directed message created (`to_agent` required, `state=unread`)
+2. `READ`: message seen (`event_ref` to prior `SEND`)
+3. `ACK`: message accepted (`event_ref` to prior `SEND`)
+4. `RESERVE`: scope reservation created
+5. `RELEASE`: scope reservation released
+6. `TAKEOVER`: stale/evicted reservation force-acquired
+7. `RESUME`: identity adoption event
+8. `BLOCKED`: explicit blocker signal
+9. `HANDOFF`: explicit transfer signal
+10. `INCURSION`: overlap warning signal
+
+## Required Fields by Event
+
+Shared required fields:
+- `event_type`
+- `event_id`
+- `project_root`
+- `issue_id`
+- `actor`
+- `timestamp`
+
+Extra required fields:
+- `SEND`: `to_agent`, `payload.subject`, `payload.body`
+- `READ`: `event_ref`
+- `ACK`: `event_ref`
+- `RESERVE`: `scope`, `payload.ttl_minutes`
+- `RELEASE`: `scope`
+- `TAKEOVER`: `scope`, `takeover_mode` (`stale` | `evicted`), `reason`
+- `RESUME`: `payload.prior_agent`, `reason` (`uncommitted_scope` | `in_progress_ownership`)
+- `BLOCKED`: `to_agent`, `payload.blocker`, `payload.requested_action`
+- `HANDOFF`: `to_agent`, `payload.summary`, `payload.next_action`
+- `INCURSION`: `scope`, `payload.incursion_kind` (`exact` | `partial`), `payload.owner_liveness`
+
+## Derivation Rules (Frontend/API)
+
+Inbox projection:
+- unread: `SEND` with no later `READ`/`ACK` on same `event_id`
+- read: `READ` exists, no later `ACK`
+- acked: `ACK` exists
+
+Reservation projection:
+- active reservation = latest event for `(project_root, scope)` is `RESERVE` or `TAKEOVER` and not superseded by `RELEASE`
+- owner liveness from `bd agent heartbeat/state`
+
+Takeover policy:
+- owner active: deny takeover
+- owner stale: allow only explicit stale takeover mode
+- owner evicted: allow takeover and mark prior reservation expired in projection
+
+## Dolt Considerations
+
+1. Never rewrite prior protocol events; only append.
+2. Treat projections as computed views, never source of truth.
+3. Use Dolt history for postmortems (`bd history`/`bd diff`) against protocol incidents.
+4. Keep schema versioned (`coord.v1` -> future upgrades by additive fields and new event types).
+
+## Skill Migration Guidance (Later Work)
+
+When updating `skills/beadboard-driver`, use this contract:
+1. Replace `bb agent send/inbox/read/ack` with `bd audit` event writes + API-derived inbox reads.
+2. Replace `bb reserve/release/status` with `bd audit` reservation events + API overlap/liveness checks.
+3. Keep `bd` lifecycle commands unchanged.
+4. Keep human summaries in `bd comments` for operator readability.

docs/protocols/operative-protocol-v1.md

@@ -1,7 +1,7 @@
 # Operative Protocol v1 (Session Constitution)
 
 Date: 2026-02-14  
-Status: Approved for implementation  
+Status: Approved for implementation (superseded for migration planning by `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`)  
 Scope: `bb-u6f.6.1`  
 Applies to: `bb-u6f.6.2`, `bb-u6f.6.3`, `bb-u6f.6.4`, `bb-u6f.6.5`
 
@@ -15,6 +15,10 @@ Boundaries:
 3. No direct writes to `.beads/issues.jsonl`.
 4. User-facing labels must stay plain language.
 
+Migration note:
+1. New work should target the `coord.v1` `bd audit` event model documented in `docs/protocols/2026-02-28-bd-audit-coordination-schema.md`.
+2. `bb` coordination semantics are legacy compatibility behavior pending removal after migration sign-off.
+
 ## 2. Normative Language
 
 1. MUST: required behavior.

eslint.config.mjs

@@ -14,6 +14,7 @@ const eslintConfig = [
       '.next/**',
       '.agents/**',
       'skills/**',
+      'reference/**',
       'next-env.d.ts',
     ],
   },

help/cli/bd-branch-help.txt

@@ -0,0 +1,31 @@
+List all branches or create a new branch.
+
+This command requires the Dolt storage backend. Without arguments,
+it lists all branches. With an argument, it creates a new branch.
+
+Examples:
+  bd branch                    # List all branches
+  bd branch feature-xyz        # Create a new branch named feature-xyz
+
+Usage:
+  bd branch [name] [flags]
+
+Flags:
+  -h, --help   help for branch
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+      --json                      Output in JSON format
+      --lock-timeout duration     SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+      --no-auto-flush             Disable automatic JSONL sync after CRUD operations
+      --no-auto-import            Disable automatic JSONL import when newer than DB
+      --no-daemon                 Force direct storage mode, bypass daemon if running
+      --no-db                     Use no-db mode: load from JSONL, no SQLite
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables daemon and auto-sync
+  -v, --verbose                   Enable verbose/debug output

help/cli/bd-create-help.txt

@@ -0,0 +1,61 @@
+Create a new issue (or multiple issues from markdown file)
+
+Usage:
+  bd create [title] [flags]
+
+Aliases:
+  create, new
+
+Flags:
+      --acceptance string       Acceptance criteria
+      --agent-rig string        Agent's rig name (requires --type=agent)
+      --append-notes string     Append to existing notes (with newline separator)
+  -a, --assignee string         Assignee
+      --body-file string        Read description from file (use - for stdin)
+      --defer string            Defer until date (issue hidden from bd ready until then). Same formats as --due
+      --deps strings            Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20')
+  -d, --description string      Issue description
+      --design string           Design notes
+      --dry-run                 Preview what would be created without actually creating
+      --due string              Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15
+      --ephemeral               Create as ephemeral (short-lived, subject to TTL compaction)
+  -e, --estimate int            Time estimate in minutes (e.g., 60 for 1 hour)
+      --event-actor string      Entity URI who caused this event (requires --type=event)
+      --event-category string   Event category (e.g., patrol.muted, agent.started) (requires --type=event)
+      --event-payload string    Event-specific JSON data (requires --type=event)
+      --event-target string     Entity URI or bead ID affected (requires --type=event)
+      --external-ref string     External reference (e.g., 'gh-9', 'jira-ABC')
+  -f, --file string             Create multiple issues from markdown file
+      --force                   Force creation even if prefix doesn't match database prefix
+  -h, --help                    help for create
+      --id string               Explicit issue ID (e.g., 'bd-42' for partitioning)
+  -l, --labels strings          Labels (comma-separated)
+      --metadata string         Set custom metadata (JSON string or @file.json to read from file)
+      --mol-type string         Molecule type: swarm (multi-polecat), patrol (recurring ops), work (default)
+      --no-inherit-labels       Don't inherit labels from parent issue
+      --notes string            Additional notes
+      --parent string           Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
+      --prefix string           Create issue in rig by prefix (e.g., --prefix bd- or --prefix bd or --prefix beads)
+  -p, --priority string         Priority (0-4 or P0-P4, 0=highest) (default "2")
+      --repo string             Target repository for issue (overrides auto-routing)
+      --rig string              Create issue in a different rig (e.g., --rig beads)
+      --silent                  Output only the issue ID (for scripting)
+      --spec-id string          Link to specification document
+      --title string            Issue title (alternative to positional argument)
+  -t, --type string             Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task")
+      --validate                Validate description contains required sections for issue type
+      --waits-for string        Spawner issue ID to wait for (creates waits-for dependency for fanout gate)
+      --waits-for-gate string   Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children")
+      --wisp-type string        Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd sync / bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
+      --json                      Output in JSON format
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables auto-sync
+  -v, --verbose                   Enable verbose/debug output

help/cli/bd-daemon-help.txt

@@ -0,0 +1,75 @@
+Manage the background daemon that automatically syncs issues with git remote.
+
+The daemon will:
+- Poll for changes at configurable intervals (default: 5 seconds)
+- Export pending database changes to JSONL
+- Auto-commit changes if --auto-commit flag set
+- Auto-push commits if --auto-push flag set
+- Pull remote changes periodically
+- Auto-import when remote changes detected
+
+Common operations:
+  bd daemon start                Start the daemon (background)
+  bd daemon start --foreground   Start in foreground (for systemd/supervisord)
+  bd daemon stop                 Stop current workspace daemon
+  bd daemon status               Show daemon status
+  bd daemon status --all         Show all daemons with health check
+  bd daemon logs                 View daemon logs
+  bd daemon restart              Restart daemon
+  bd daemon killall              Stop all running daemons
+
+Run 'bd daemon --help' to see all subcommands.
+
+Usage:
+  bd daemon [flags]
+  bd daemon [command]
+
+Available Commands:
+  health      Check health of all bd daemons
+  killall     Stop all running bd daemons
+  list        List all running bd daemons
+  logs        View logs for a specific bd daemon
+  restart     Restart a specific bd daemon
+  start       Start the background daemon
+  status      Show daemon status
+  stop        Stop a specific bd daemon
+
+Flags:
+      --auto-commit           Automatically commit changes
+      --auto-pull             Automatically pull from remote (default: true when sync.branch configured)
+      --auto-push             Automatically push commits
+      --federation            Enable federation mode (runs dolt sql-server with remotesapi)
+      --federation-port int   MySQL port for federation mode dolt sql-server (default 3307)
+      --foreground            Run in foreground (don't daemonize)
+      --health                Check daemon health (deprecated: use 'bd daemon status --all')
+  -h, --help                  help for daemon
+      --interval duration     Sync check interval (default 5s)
+      --json                  Output JSON format
+      --local                 Run in local-only mode (no git required, no sync)
+      --log string            Log file path (default: .beads/daemon.log)
+      --log-json              Output logs in JSON format (structured logging)
+      --log-level string      Log level (debug, info, warn, error) (default "info")
+      --metrics               Show detailed daemon metrics
+      --remotesapi-port int   remotesapi port for peer-to-peer sync in federation mode (default 8080)
+      --start                 Start the daemon (deprecated: use 'bd daemon start')
+      --status                Show daemon status (deprecated: use 'bd daemon status')
+      --stop                  Stop running daemon (deprecated: use 'bd daemon stop')
+      --stop-all              Stop all running bd daemons (deprecated: use 'bd daemon killall')
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+      --lock-timeout duration     SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+      --no-auto-flush             Disable automatic JSONL sync after CRUD operations
+      --no-auto-import            Disable automatic JSONL import when newer than DB
+      --no-daemon                 Force direct storage mode, bypass daemon if running
+      --no-db                     Use no-db mode: load from JSONL, no SQLite
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables daemon and auto-sync
+  -v, --verbose                   Enable verbose/debug output
+
+Use "bd daemon [command] --help" for more information about a command.

help/cli/bd-diff-help.txt

@@ -0,0 +1,34 @@
+Show the differences in issues between two commits or branches.
+
+This command requires the Dolt storage backend. The refs can be:
+- Commit hashes (e.g., abc123def)
+- Branch names (e.g., main, feature-branch)
+- Special refs like HEAD, HEAD~1
+
+Examples:
+  bd diff main feature-branch   # Compare main to feature branch
+  bd diff HEAD~5 HEAD           # Show changes in last 5 commits
+  bd diff abc123 def456         # Compare two specific commits
+
+Usage:
+  bd diff <from-ref> <to-ref> [flags]
+
+Flags:
+  -h, --help   help for diff
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+      --json                      Output in JSON format
+      --lock-timeout duration     SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+      --no-auto-flush             Disable automatic JSONL sync after CRUD operations
+      --no-auto-import            Disable automatic JSONL import when newer than DB
+      --no-daemon                 Force direct storage mode, bypass daemon if running
+      --no-db                     Use no-db mode: load from JSONL, no SQLite
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables daemon and auto-sync
+  -v, --verbose                   Enable verbose/debug output

help/cli/bd-dolt-help.txt

@@ -0,0 +1,75 @@
+Configure and manage Dolt database settings and server lifecycle.
+
+Beads uses a dolt sql-server for all database operations. The server is
+auto-started transparently when needed. Use these commands for explicit
+control or diagnostics.
+
+Server lifecycle:
+  bd dolt start        Start the Dolt server for this project
+  bd dolt stop         Stop the Dolt server for this project
+  bd dolt status       Show Dolt server status
+
+Configuration:
+  bd dolt show         Show current Dolt configuration with connection test
+  bd dolt set <k> <v>  Set a configuration value
+  bd dolt test         Test server connection
+
+Version control:
+  bd dolt commit       Commit pending changes
+  bd dolt push         Push commits to Dolt remote
+  bd dolt pull         Pull commits from Dolt remote
+
+Remote management:
+  bd dolt remote add <name> <url>   Add a Dolt remote
+  bd dolt remote list                List configured remotes
+  bd dolt remote remove <name>       Remove a Dolt remote
+
+Configuration keys for 'bd dolt set':
+  database  Database name (default: issue prefix or "beads")
+  host      Server host (default: 127.0.0.1)
+  port      Server port (auto-detected; override with bd dolt set port <N>)
+  user      MySQL user (default: root)
+  data-dir  Custom dolt data directory (absolute path; default: .beads/dolt)
+
+Flags for 'bd dolt set':
+  --update-config  Also write to config.yaml for team-wide defaults
+
+Examples:
+  bd dolt set database myproject
+  bd dolt set host 192.168.1.100 --update-config
+  bd dolt set data-dir /home/user/.beads-dolt/myproject
+  bd dolt test
+
+Usage:
+  bd dolt [command]
+
+Available Commands:
+  clean-databases Drop stale test/polecat databases from the Dolt server
+  commit          Create a Dolt commit from pending changes
+  killall         Kill all orphan Dolt server processes
+  pull            Pull commits from Dolt remote
+  push            Push commits to Dolt remote
+  remote          Manage Dolt remotes
+  set             Set a Dolt configuration value
+  show            Show current Dolt configuration with connection status
+  start           Start the Dolt SQL server for this project
+  status          Show Dolt server status
+  stop            Stop the Dolt SQL server for this project
+  test            Test connection to Dolt server
+
+Flags:
+  -h, --help   help for dolt
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt auto-commit policy (off|on|batch). 'on': commit after each write. 'batch': defer commits to bd sync / bd dolt commit; uncommitted changes persist in the working set until then. SIGTERM/SIGHUP flush pending batch commits. Default: off. Override via config key dolt.auto-commit
+      --json                      Output in JSON format
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables auto-sync
+  -v, --verbose                   Enable verbose/debug output
+
+Use "bd dolt [command] --help" for more information about a command.

help/cli/bd-list-help.txt

@@ -0,0 +1,74 @@
+List issues
+
+Usage:
+  bd list [flags]
+
+Flags:
+      --all                     Show all issues including closed (overrides default filter)
+  -a, --assignee string         Filter by assignee
+      --closed-after string     Filter issues closed after date (YYYY-MM-DD or RFC3339)
+      --closed-before string    Filter issues closed before date (YYYY-MM-DD or RFC3339)
+      --created-after string    Filter issues created after date (YYYY-MM-DD or RFC3339)
+      --created-before string   Filter issues created before date (YYYY-MM-DD or RFC3339)
+      --defer-after string      Filter issues deferred after date (supports relative: +6h, tomorrow)
+      --defer-before string     Filter issues deferred before date (supports relative: +6h, tomorrow)
+      --deferred                Show only issues with defer_until set
+      --desc-contains string    Filter by description substring (case-insensitive)
+      --due-after string        Filter issues due after date (supports relative: +6h, tomorrow)
+      --due-before string       Filter issues due before date (supports relative: +6h, tomorrow)
+      --empty-description       Filter issues with empty or missing description
+      --filter-parent string    Alias for --parent
+      --format string           Output format: 'digraph' (for golang.org/x/tools/cmd/digraph), 'dot' (Graphviz), or Go template
+  -h, --help                    help for list
+      --id string               Filter by specific issue IDs (comma-separated, e.g., bd-1,bd-5,bd-10)
+      --include-gates           Include gate issues in output (normally hidden)
+      --include-templates       Include template molecules in output
+  -l, --label strings           Filter by labels (AND: must have ALL). Can combine with --label-any
+      --label-any strings       Filter by labels (OR: must have AT LEAST ONE). Can combine with --label
+      --label-pattern string    Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)
+      --label-regex string      Filter by label regex pattern (e.g., 'tech-(debt|legacy)')
+  -n, --limit int               Limit results (default 50, use 0 for unlimited) (default 50)
+      --long                    Show detailed multi-line output for each issue
+      --mol-type string         Filter by molecule type: swarm, patrol, or work
+      --no-assignee             Filter issues with no assignee
+      --no-labels               Filter issues with no labels
+      --no-pager                Disable pager output
+      --no-pinned               Exclude pinned issues
+      --notes-contains string   Filter by notes substring (case-insensitive)
+      --overdue                 Show only issues with due_at in the past (not closed)
+      --parent string           Filter by parent issue ID (shows children of specified issue)
+      --pinned                  Show only pinned issues
+      --pretty                  Display issues in a tree format with status/priority symbols
+  -p, --priority string         Priority (0-4 or P0-P4, 0=highest)
+      --priority-max string     Filter by maximum priority (inclusive, 0-4 or P0-P4)
+      --priority-min string     Filter by minimum priority (inclusive, 0-4 or P0-P4)
+      --ready                   Show only ready issues (status=open, excludes hooked/in_progress/blocked/deferred)
+  -r, --reverse                 Reverse sort order
+      --sort string             Sort by field: priority, created, updated, closed, status, id, title, type, assignee
+      --spec string             Filter by spec_id prefix
+  -s, --status string           Filter by status (open, in_progress, blocked, deferred, closed)
+      --title string            Filter by title text (case-insensitive substring match)
+      --title-contains string   Filter by title substring (case-insensitive)
+      --tree                    Alias for --pretty: hierarchical tree format
+  -t, --type string             Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule
+      --updated-after string    Filter issues updated after date (YYYY-MM-DD or RFC3339)
+      --updated-before string   Filter issues updated before date (YYYY-MM-DD or RFC3339)
+  -w, --watch                   Watch for changes and auto-update display (implies --pretty)
+      --wisp-type string        Filter by wisp type: heartbeat, ping, patrol, gc_report, recovery, error, escalation
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+      --json                      Output in JSON format
+      --lock-timeout duration     SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+      --no-auto-flush             Disable automatic JSONL sync after CRUD operations
+      --no-auto-import            Disable automatic JSONL import when newer than DB
+      --no-daemon                 Force direct storage mode, bypass daemon if running
+      --no-db                     Use no-db mode: load from JSONL, no SQLite
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables daemon and auto-sync
+  -v, --verbose                   Enable verbose/debug output

help/cli/bd-query-help.txt

@@ -0,0 +1,85 @@
+Query issues using a simple query language that supports compound filters,
+boolean operators, and date-relative expressions.
+
+The query language enables complex filtering that would otherwise require
+multiple flags or piping through jq.
+
+Syntax:
+  field=value       Equality comparison
+  field!=value      Inequality comparison
+  field>value       Greater than
+  field>=value      Greater than or equal
+  field<value       Less than
+  field<=value      Less than or equal
+
+Boolean operators (case-insensitive):
+  expr AND expr     Both conditions must match
+  expr OR expr      Either condition can match
+  NOT expr          Negates the condition
+  (expr)            Grouping with parentheses
+
+Supported fields:
+  status            Issue status (open, in_progress, blocked, deferred, closed)
+  priority          Priority level (0-4)
+  type              Issue type (bug, feature, task, epic, chore)
+  assignee          Assigned user (use "none" for unassigned)
+  owner             Issue owner
+  label             Issue label (use "none" for unlabeled)
+  title             Search in title (contains)
+  description       Search in description (contains, "none" for empty)
+  notes             Search in notes (contains)
+  created           Creation date/time
+  updated           Last update date/time
+  closed            Close date/time
+  id                Issue ID (supports wildcards: bd-*)
+  spec              Spec ID (supports wildcards)
+  pinned            Boolean (true/false)
+  ephemeral         Boolean (true/false)
+  template          Boolean (true/false)
+  parent            Parent issue ID
+  mol_type          Molecule type (swarm, patrol, work)
+
+Date values:
+  Relative durations: 7d (7 days ago), 24h (24 hours ago), 2w (2 weeks ago)
+  Absolute dates: 2025-01-15, 2025-01-15T10:00:00Z
+  Natural language: tomorrow, "next monday", "in 3 days"
+
+Examples:
+  bd query "status=open AND priority>1"
+  bd query "status=open AND priority<=2 AND updated>7d"
+  bd query "(status=open OR status=blocked) AND priority<2"
+  bd query "type=bug AND label=urgent"
+  bd query "NOT status=closed"
+  bd query "assignee=none AND type=task"
+  bd query "created>30d AND status!=closed"
+  bd query "label=frontend OR label=backend"
+  bd query "title=authentication AND priority=0"
+
+Usage:
+  bd query [expression] [flags]
+
+Flags:
+  -a, --all           Include closed issues (default: exclude closed)
+  -h, --help          help for query
+  -n, --limit int     Limit results (default: 50, 0 = unlimited) (default 50)
+      --long          Show detailed multi-line output for each issue
+      --parse-only    Only parse the query and show the AST (for debugging)
+  -r, --reverse       Reverse sort order
+      --sort string   Sort by field: priority, created, updated, closed, status, id, title, type, assignee
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+      --json                      Output in JSON format
+      --lock-timeout duration     SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+      --no-auto-flush             Disable automatic JSONL sync after CRUD operations
+      --no-auto-import            Disable automatic JSONL import when newer than DB
+      --no-daemon                 Force direct storage mode, bypass daemon if running
+      --no-db                     Use no-db mode: load from JSONL, no SQLite
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables daemon and auto-sync
+  -v, --verbose                   Enable verbose/debug output

help/cli/bd-vc-help.txt

@@ -0,0 +1,38 @@
+Version control operations for the beads database.
+
+These commands require the Dolt storage backend. They provide git-like
+version control for your issue data, including branching, merging, and
+viewing history.
+
+Note: 'bd history', 'bd diff', and 'bd branch' also work for quick access.
+This subcommand provides additional operations like merge and commit.
+
+Usage:
+  bd vc [command]
+
+Available Commands:
+  commit      Create a commit with all staged changes
+  merge       Merge a branch into the current branch
+  status      Show current branch and uncommitted changes
+
+Flags:
+  -h, --help   help for vc
+
+Global Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+      --json                      Output in JSON format
+      --lock-timeout duration     SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+      --no-auto-flush             Disable automatic JSONL sync after CRUD operations
+      --no-auto-import            Disable automatic JSONL import when newer than DB
+      --no-daemon                 Force direct storage mode, bypass daemon if running
+      --no-db                     Use no-db mode: load from JSONL, no SQLite
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables daemon and auto-sync
+  -v, --verbose                   Enable verbose/debug output
+
+Use "bd vc [command] --help" for more information about a command.

help/cli/help.txt

@@ -0,0 +1,136 @@
+Issues chained together like beads. A lightweight issue tracker with first-class dependency support.
+
+Usage:
+  bd [flags]
+  bd [command]
+
+Maintenance:
+  rename-prefix      Rename the issue prefix for all issues in the database
+  repair             Repair corrupted database by cleaning orphaned references
+  resolve-conflicts  Resolve git merge conflicts in JSONL files
+
+Integrations & Advanced:
+Working With Issues:
+  children           List child beads of a parent
+  close              Close one or more issues
+  comments           View or manage comments on an issue
+  create             Create a new issue (or multiple issues from markdown file)
+  create-form        Create a new issue using an interactive form
+  delete             Delete one or more issues and clean up references
+  edit               Edit an issue field in $EDITOR
+  gate               Manage async coordination gates
+  label              Manage issue labels
+  list               List issues
+  merge-slot         Manage merge-slot gates for serialized conflict resolution
+  move               Move an issue to a different rig with dependency remapping
+  promote            Promote a wisp to a permanent bead
+  q                  Quick capture: create issue and output only ID
+  query              Query issues using a simple query language
+  refile             Move an issue to a different rig
+  reopen             Reopen one or more closed issues
+  search             Search issues by text query
+  set-state          Set operational state (creates event + updates label)
+  show               Show issue details
+  state              Query the current value of a state dimension
+  todo               Manage TODO items (convenience wrapper for task issues)
+  update             Update one or more issues
+
+Views & Reports:
+  activity           Show real-time molecule state feed
+  count              Count issues matching filters
+  diff               Show changes between two commits or branches (requires Dolt backend)
+  find-duplicates    Find semantically similar issues using text analysis or AI
+  history            Show version history for an issue (requires Dolt backend)
+  lint               Check issues for missing template sections
+  stale              Show stale issues (not updated recently)
+  status             Show issue database overview and statistics
+  types              List valid issue types
+
+Dependencies & Structure:
+  dep                Manage dependencies
+  duplicate          Mark an issue as a duplicate of another
+  duplicates         Find and optionally merge duplicate issues
+  epic               Epic management commands
+  graph              Display issue dependency graph
+  supersede          Mark an issue as superseded by a newer one
+  swarm              Swarm management for structured epics
+
+Sync & Data:
+  branch             List or create branches (requires Dolt backend)
+  daemon             Manage background sync daemon
+  export             Export issues to JSONL or Obsidian format
+  federation         Manage peer-to-peer federation (requires CGO)
+  import             Import issues from JSONL format
+  merge              Git merge driver for beads JSONL files
+  restore            Restore full history of a compacted issue from git
+  sync               Export database to JSONL (sync with git)
+  vc                 Version control operations (requires Dolt backend)
+
+Setup & Configuration:
+  backend            Manage storage backend configuration
+  config             Manage configuration settings
+  hooks              Manage git hooks for bd auto-sync
+  human              Show essential commands for human users
+  info               Show database and daemon information
+  init               Initialize bd in the current directory
+  kv                 Key-value store commands
+  onboard            Display minimal snippet for AGENTS.md
+  prime              Output AI-optimized workflow context
+  quickstart         Quick start guide for bd
+  setup              Setup integration with AI editors
+  where              Show active beads location
+
+Maintenance:
+  doctor             Check and fix beads installation health (start here)
+  migrate            Database migration commands
+  preflight          Show PR readiness checklist
+  upgrade            Check and manage bd version upgrades
+  worktree           Manage git worktrees for parallel development
+
+Integrations & Advanced:
+  admin              Administrative commands for database maintenance
+  jira               Jira integration commands
+  linear             Linear integration commands
+  repo               Manage multiple repository configuration
+
+Additional Commands:
+  agent              Manage agent bead state
+  audit              Record and label agent interactions (append-only JSONL)
+  blocked            Show blocked issues
+  completion         Generate the autocompletion script for the specified shell
+  cook               Compile a formula into a proto (ephemeral by default)
+  defer              Defer one or more issues for later
+  formula            Manage workflow formulas
+  gitlab             GitLab integration commands
+  help               Help about any command
+  hook               Execute a git hook (called by hook scripts)
+  mail               Delegate to mail provider (e.g., gt mail)
+  mol                Molecule commands (work templates)
+  orphans            Identify orphaned issues (referenced in commits but still open)
+  ready              Show ready work (open, no blockers)
+  rename             Rename an issue ID
+  ship               Publish a capability for cross-project dependencies
+  slot               Manage agent bead slots
+  undefer            Undefer one or more issues (restore to open)
+  version            Print version information
+
+Flags:
+      --actor string              Actor name for audit trail (default: $BD_ACTOR, git user.name, $USER)
+      --allow-stale               Allow operations on potentially stale data (skip staleness check)
+      --db string                 Database path (default: auto-discover .beads/*.db)
+      --dolt-auto-commit string   Dolt backend: auto-commit after write commands (off|on). Default from config key dolt.auto-commit
+  -h, --help                      help for bd
+      --json                      Output in JSON format
+      --lock-timeout duration     SQLite busy timeout (0 = fail immediately if locked) (default 30s)
+      --no-auto-flush             Disable automatic JSONL sync after CRUD operations
+      --no-auto-import            Disable automatic JSONL import when newer than DB
+      --no-daemon                 Force direct storage mode, bypass daemon if running
+      --no-db                     Use no-db mode: load from JSONL, no SQLite
+      --profile                   Generate CPU profile for performance analysis
+  -q, --quiet                     Suppress non-essential output (errors only)
+      --readonly                  Read-only mode: block write operations (for worker sandboxes)
+      --sandbox                   Sandbox mode: disables daemon and auto-sync
+  -v, --verbose                   Enable verbose/debug output
+  -V, --version                   Print version information
+
+Use "bd [command] --help" for more information about a command.

help/workflows/agent_bead_workflow.txt

@@ -0,0 +1,53 @@
+# Agent Workflow for Beadboard
+
+As an agent working in this repository, you must follow these rules when managing tasks using `bd`.
+
+---
+
+## 1. Finding Work
+Before starting any new work, check if there's already an open task for it.
+```bash
+bd ready
+```
+*If a task is ready, pick it up instead of creating a duplicate.*
+
+## 2. Starting Work / Tracking Plans
+When asked to perform non-trivial work without an existing task, **always create a task**.
+Do **not** keep your plan in free-form text. Create a task with `priority 0`.
+```bash
+bd create "Short descriptive title of the work" -p 0
+```
+Update the status to `in_progress` if you are working on it:
+```bash
+bd set-state <task-id> in_progress
+```
+
+## 3. Working within Tasks (task.md)
+Update the local `<appDataDir>/brain/<conversation-id>/task.md` using the checklist `[ ]`, `[/]`, `[x]` to maintain your internal progress while working. Also update the `bd` task if you have significant architectural notes.
+
+## 4. Dependencies
+If your task depends on another task being completed first, declare the block:
+```bash
+# Link: your task is blocked by another task
+# First run bd dep add, it will prompt you interactively.
+# Or use the appropriate arguments if you know them.
+# The user prefers bd handle these rather than prose "do X after Y"
+```
+
+## 5. Finishing Work
+When you have finished a task, completed your tests, and verified it works (run your lint/typecheck steps), you must close the task.
+
+1. **Verify completion**: `bun run typecheck && bun run lint`
+2. **Close the bead**: 
+   ```bash
+   # You can use bd update or bd close
+   bd status <task-id>  # To view it
+   bd close <task-id>   # To mark it closed
+   ```
+3. **Summarize**: Leave a summary of what changed. (You can do this by using bd edit or through a comment if bd supports it, otherwise summarize in your git commit).
+
+## 6. Verifying Past Work (Recently Closed Beads)
+If you need to know what was just finished (e.g. to see if a bead was successfully closed), view the recently closed beads:
+```bash
+bd query "status=closed" --sort closed --reverse --limit 5
+```

help/workflows/dolt_backend_workflow.txt

@@ -0,0 +1,52 @@
+# Beadboard Dolt System Workflow
+
+Beadboard supports an optional **Dolt storage backend**. Dolt is a SQL database with git-like version control, enabling advanced features like branching, merging, and historic diffs for your issue data.
+
+If your environment has Dolt enabled (no CGO build errors when using `bd`), you have access to powerful new version control commands. They behave similarly to `git` but operate purely on Beadboard issues.
+
+## 1. Branching
+You can create branches of your issue database, to test speculative features or isolate a swarm of issues before merging them into main.
+
+- **List all branches**:
+  ```bash
+  bd branch
+  ```
+- **Create a new branch**:
+  ```bash
+  bd branch <branch-name>
+  ```
+
+## 2. Version Control (Commit & Merge)
+Use `bd vc` to manage commits on your branch.
+
+- **View status of current branch**:
+  ```bash
+  bd vc status
+  ```
+- **Create a commit**:
+  ```bash
+  bd vc commit
+  ```
+- **Merge a branch**:
+  ```bash
+  bd vc merge <branch-to-merge>
+  ```
+
+*Note: You can also rely on `--dolt-auto-commit=on` (which can be set in config) to automatically commit changes after write operations like `bd create` or `bd update`.*
+
+## 3. Viewing Diffs
+You can view the exact issue changes (created, deleted, modified) between two commits or branches.
+
+- **Compare current state against a branch**:
+  ```bash
+  bd diff main feature-branch
+  ```
+- **Compare history**:
+  ```bash
+  bd diff HEAD~5 HEAD  # Show changes in the last 5 commits
+  ```
+
+## Summary for Agents
+If you receive an error about `dolt backend requires CGO` when running `bd ready`, it means the Dolt features are not available on this specific build. You must fall back to standard `bd` commands which use SQLite by default and sync via JSONL files.
+
+However, when working in a Dolt-enabled environment, you should proactively create a branch when starting a large Epic (`bd branch feature-xyz`), commit your `bd` issue changes natively tracking the state (`bd vc commit`), and merge them back when the epic is verified (`bd vc merge`).

help/workflows/viewing_recent_closed_beads.txt

@@ -0,0 +1,49 @@
+# Viewing Recently Closed Beads
+
+When you need to find beads (tasks, issues) that were recently closed, use `bd query` or `bd list` with date filters. 
+The user rule indicates a need to "correctly view the last closed beads (there is some sort of filter for recency)".
+
+## Method 1: Using `bd query`
+
+`bd query` supports a simple query language with relative and absolute dates.
+
+1. **View closed beads in the last X days**
+   ```bash
+   bd query "status=closed AND updated>2d" --sort updated
+   ```
+   *This finds beads closed and updated within the last 2 days, sorted chronologically with newest at the bottom.*
+
+2. **View closed beads in the last 24 hours**
+   ```bash
+   bd query "status=closed AND updated>24h" --sort updated
+   ```
+
+3. **View everything closed**
+   ```bash
+   bd query "status=closed" --sort closed --limit 10 --reverse
+   ```
+   *This shows the 10 most recently closed beads (requires --reverse so limit grabs the newest).*
+
+## Method 2: Using `bd list`
+
+`bd list` has specific flags for filtering by closure date.
+
+1. **View closed beads using --closed-after**
+   ```bash
+   bd list --status closed --closed-after "7d" --sort closed --reverse
+   ```
+   Wait, the `--closed-after` flag expects YYYY-MM-DD or RFC3339. The better approach for relative dates is `bd query`.
+
+However, if using absolute dates:
+```bash
+bd list --status closed --closed-after 2025-01-01 --sort closed --reverse 
+```
+
+## Summary for Agents:
+**Always use `bd query` with relative time for the best results** when checking recency. 
+
+To view recently closed beads (within the last 3 days) in standard terminal chronological order (oldest at top, newest at bottom):
+**`bd query "status=closed AND closed>3d" --sort closed`** 
+
+To get just the last 5 closed beads (note: you must use --reverse to get the most recent ones when using --limit):
+**`bd query "status=closed" --sort closed --reverse --limit 5`**