Merge branch 'main' of https://github.com/steveyegge/beads

.beads/issues.jsonl

@@ -1,5 +1,4 @@
 {"id":"bd-03r","title":"Document deletions manifest in AGENTS.md and README","description":"Parent: bd-imj\n\n## Task\nAdd documentation about the deletions manifest feature.\n\n## Locations to Update\n\n### AGENTS.md\n- Explain that deletions.jsonl is tracked in git\n- Document that `bd delete` records to the manifest\n- Explain cross-clone propagation mechanism\n\n### README.md  \n- Brief mention in .beads directory structure section\n- Link to detailed docs if needed\n\n### docs/deletions.md (new file)\n- Full technical documentation\n- Format specification\n- Pruning policy\n- Git history fallback\n- Troubleshooting\n\n## Acceptance Criteria\n- AGENTS.md updated with deletion workflow\n- README.md mentions deletions.jsonl purpose\n- New docs/deletions.md with complete reference","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T14:56:49.13027-08:00","updated_at":"2025-11-25T15:17:23.145944-08:00","closed_at":"2025-11-25T15:17:23.145944-08:00"}
-{"id":"bd-055","title":"Fix hyphenated prefix parsing in ExtractIssuePrefix (GH #395)","description":"","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-26T15:22:22.395177-08:00","updated_at":"2025-11-26T16:46:57.8927-08:00","closed_at":"2025-11-26T16:46:57.8927-08:00"}
 {"id":"bd-0b2","title":"Need --no-git-history flag to disable git history backfill during import","description":"During JSONL migration (beads.jsonl → issues.jsonl), the git history backfill mechanism causes data loss by finding issues in the old beads.jsonl git history and incorrectly treating them as deleted.\n\nA --no-git-history flag for 'bd import' and 'bd sync' would allow users to disable the git history fallback when it's causing problems.\n\nUse cases:\n- JSONL filename migrations\n- Repos with complex git history\n- Debugging import issues\n- Performance (skip slow git scans)\n\nRelated: bd-0gh (migration causes spurious deletions)","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-26T22:28:22.5286-08:00","updated_at":"2025-11-26T23:14:22.957335-08:00","closed_at":"2025-11-26T23:14:22.957335-08:00"}
 {"id":"bd-1pj6","title":"Proposal: Custom status states via config","description":"Proposal to add 'custom status states' via `bd config`.\nUsers could define an optional issue status enum (e.g., awaiting_review, review_in_progress) in the config.\nThis would enable multi-step pipelines to process issues where each step correlates to a specific status.\n\nExamples:\n- awaiting_verification\n- awaiting_docs\n- awaiting_testing\n","status":"open","priority":3,"issue_type":"feature","created_at":"2025-11-20T18:55:48.670499-05:00","updated_at":"2025-11-20T18:55:48.670499-05:00"}
 {"id":"bd-2em","title":"Expand checkHooksQuick to verify all hook versions","description":"Currently checkHooksQuick only checks post-merge hook version. Should also check pre-commit, pre-push, and post-checkout for completeness. Keep it lightweight but catch more outdated hooks.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-25T19:27:47.432243-08:00","updated_at":"2025-11-25T19:50:21.378464-08:00","closed_at":"2025-11-25T19:50:21.378464-08:00"}
@@ -11,7 +10,6 @@
 {"id":"bd-4l5","title":"bd prime: Detect ephemeral branches and adjust workflow output","description":"When 'bd prime' runs on a branch with no upstream (ephemeral branch), it should output a different SESSION CLOSE PROTOCOL.\n\n**Current output (wrong for ephemeral branches):**\n```\n[ ] 1. git status\n[ ] 2. git add \u003cfiles\u003e\n[ ] 3. bd sync\n[ ] 4. git commit -m \"...\"\n[ ] 5. bd sync\n[ ] 6. git push\n```\n\n**Needed output for ephemeral branches:**\n```\n[ ] 1. git status\n[ ] 2. git add \u003cfiles\u003e\n[ ] 3. bd sync --from-main  (pull updates from main)\n[ ] 4. git commit -m \"...\"\n[ ] 5. (no push - branch is ephemeral)\n```\n\n**Detection:** `git rev-parse --abbrev-ref --symbolic-full-name @{u}` returns error code 128 if no upstream.\n\nAlso update Sync \u0026 Collaboration section to mention `bd sync --from-main` for ephemeral branches.\n\n**Use case:** Gastown polecats work on ephemeral local branches that are never pushed. Their code gets merged to main via local merge, and beads changes stay local (communicated via gm mail to Overseer).","status":"closed","priority":1,"issue_type":"feature","created_at":"2025-11-25T16:55:24.984104-08:00","updated_at":"2025-11-25T17:12:46.604978-08:00","closed_at":"2025-11-25T17:12:46.604978-08:00"}
 {"id":"bd-4pv","title":"bd export only outputs 1 issue after auto-import corrupts database","description":"When auto-import runs and purges issues (due to git history backfill bug), subsequent 'bd export' only exports 1 issue even though the database should have many.\n\nReproduction:\n1. Have issues.jsonl with 55 issues\n2. Auto-import triggers and purges all issues via git history backfill\n3. Run 'bd export' - only exports 1 issue (the last one created before corruption)\n\nThe database gets into an inconsistent state where most issues are purged but export doesn't realize this.\n\nWorkaround: Rebuild database from scratch with 'rm .beads/beads.db \u0026\u0026 bd init --prefix bd'","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:40.828866-08:00","updated_at":"2025-11-26T22:28:40.828866-08:00"}
 {"id":"bd-4t7","title":"Auto-import runs during --no-auto-import operations via stats/ready commands","description":"Even when using --no-auto-import flag, certain commands like 'bd stats' and 'bd ready' still trigger auto-import internally, which can cause the git history backfill bug to corrupt data.\n\nExample:\n  bd stats --no-auto-import\n  # Still prints 'Purged bd-xxx (recovered from git history...)'\n\nThe flag should completely disable auto-import for the command, but it appears some code paths still trigger it.\n\nWorkaround: Use --allow-stale instead, or --sandbox mode.","status":"open","priority":2,"issue_type":"bug","created_at":"2025-11-26T22:28:59.305898-08:00","updated_at":"2025-11-26T22:28:59.305898-08:00"}
-{"id":"bd-6xd","title":"Standardize on issues.jsonl as canonical filename","description":"## Background\n\nThe codebase has confused and contradictory references to both `issues.jsonl` and `beads.jsonl`. This arose from a misconception that `issues.jsonl` was polluted with 100k test issues, but analysis shows:\n\n- issues.jsonl git history: 253 blobs, 54 MB total (max blob 2.1 MB)\n- beads.jsonl git history: 1140 blobs, 353 MB total (6.5x larger!)\n\nThe 'pollution' was never as big as remembered. Meanwhile, 99% of user installs use `issues.jsonl`.\n\n## The Problem\n\nCode has contradictory comments:\n```go\n// cmd/bd/autoimport.go:88\n// Try canonical JSONL filenames in precedence order (issues.jsonl is canonical)\n\n// internal/configfile/configfile.go:24\nJSONLExport: \"beads.jsonl\", // Default to canonical name (was issues.jsonl)\n```\n\n## Current State\n\n### Code References (excluding tests)\n- `beads.jsonl`: 51 references in Go code\n- `issues.jsonl`: 84 references in Go code\n\n### Documentation References\n- `beads.jsonl`: 59 references\n- `issues.jsonl`: 62 references\n\n## Proposed Solution\n\n1. Make `issues.jsonl` the **only** canonical name\n2. Support `beads.jsonl` only as legacy (auto-migrate to issues.jsonl)\n3. Switch beads repo itself back to using issues.jsonl\n4. Update all code and docs for consistency\n\n## Files Requiring Changes\n\n### High Priority (logic changes)\n- `internal/configfile/configfile.go` - Change default from beads.jsonl to issues.jsonl\n- `internal/beads/beads.go` - Reverse preference order, prefer issues.jsonl\n- `cmd/bd/version_tracking.go` - Reverse preference order\n- `cmd/bd/doctor/fix/database_config.go` - Reverse preference order\n- `cmd/bd/autoimport.go` - Already prefers issues.jsonl (correct)\n- `cmd/bd/init.go` - Update gitattributes setup, comments\n\n### Medium Priority (user-facing messages)\n- `cmd/bd/import.go` - Update example paths in error messages\n- `cmd/bd/sync.go` - Update diff display path\n- `cmd/bd/status.go` - Update git log path\n- `cmd/bd/staleness.go` - Update help message\n- `cmd/bd/init_contributor.go` - Update output messages\n- `cmd/bd/clean.go` - Update help text\n- `cmd/bd/cleanup.go` - Update help text\n\n### Lower Priority (internal/comments)\n- `internal/importer/importer.go` - Update comments and paths\n- `cmd/bd/merge.go` - Update comment\n- `cmd/bd/doctor.go` - Multiple references\n- `cmd/bd/doctor/fix/sync.go` - Variable naming\n- `cmd/bd/doctor/fix/deletions.go` - Path reference\n\n### Documentation\n- README.md - ~8 references to update\n- docs/DELETIONS.md\n- docs/CLI_REFERENCE.md\n- docs/ARCHITECTURE.md\n- docs/TROUBLESHOOTING.md\n- docs/PROTECTED_BRANCHES.md\n- docs/GIT_INTEGRATION.md\n- docs/MULTI_REPO_AGENTS.md\n- docs/MULTI_REPO_MIGRATION.md\n- docs/TESTING.md (acknowledges the inconsistency)\n\n## Migration Strategy\n\n1. Add migration in `bd init`: if beads.jsonl exists and issues.jsonl doesn't, rename it\n2. Update `bd doctor` to detect and offer to fix the naming\n3. Keep reading beads.jsonl as fallback for one version cycle\n4. Remove beads.jsonl fallback in future version\n\n## For Beads Repo Itself\n\n1. `git mv .beads/beads.jsonl .beads/issues.jsonl`\n2. Update .gitattributes if present\n3. Commit with clear message","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-26T19:33:34.169595-08:00","updated_at":"2025-11-26T21:00:34.038454-08:00","closed_at":"2025-11-26T21:00:34.038454-08:00"}
 {"id":"bd-736d","title":"Refactor path canonicalization into helper function","description":"The path canonicalization logic (filepath.Abs + EvalSymlinks) is duplicated in 3 places:\n- beads.go:131-137 (BEADS_DIR handling)\n- cmd/bd/main.go:446-451 (--no-db cleanup)\n- cmd/bd/nodb.go:26-31 (--no-db initialization)\n\nRefactoring suggestion:\nExtract to a helper function like:\n  func canonicalizePath(path string) string\n\nThis would:\n- Reduce code duplication\n- Make the logic easier to maintain\n- Ensure consistent behavior across all path handling\n\nRelated to bd-e16b implementation.","status":"closed","priority":3,"issue_type":"chore","created_at":"2025-11-02T18:33:47.727443-08:00","updated_at":"2025-11-25T22:27:33.738672-08:00","closed_at":"2025-11-25T22:27:33.738672-08:00"}
 {"id":"bd-81a","title":"Add programmatic tip injection API","description":"Allow tips to be programmatically injected at runtime based on detected conditions. This enables dynamic tips (not just pre-defined ones) to be shown with custom priority and frequency.","status":"closed","priority":2,"issue_type":"feature","created_at":"2025-11-11T23:29:46.645583-08:00","updated_at":"2025-11-25T17:52:35.096882-08:00","closed_at":"2025-11-25T17:52:35.096882-08:00","dependencies":[{"issue_id":"bd-81a","depends_on_id":"bd-d4i","type":"blocks","created_at":"2025-11-11T23:29:46.646327-08:00","created_by":"daemon"}]}
 {"id":"bd-8a5","title":"Refactor: deduplicate FindJSONLInDir and FindJSONLPath","description":"## Background\n\nAfter fixing bd-tqo, we now have two nearly identical functions for finding the JSONL file:\n- `autoimport.FindJSONLInDir(dbDir string)` in internal/autoimport/autoimport.go\n- `beads.FindJSONLPath(dbPath string)` in internal/beads/beads.go\n\nBoth implement the same logic:\n1. Prefer issues.jsonl\n2. Fall back to beads.jsonl for legacy support\n3. Skip deletions.jsonl and merge artifacts\n4. Default to issues.jsonl if nothing found\n\n## Problem\n\nCode duplication means bug fixes need to be applied in multiple places (as we just experienced with bd-tqo).\n\n## Proposed Solution\n\nExtract shared logic to a utility package that both can import. Options:\n1. Create `internal/jsonlpath` package with the core logic\n2. Have `autoimport` import `beads` and call `FindJSONLPath` (but APIs differ slightly)\n3. Move to `internal/utils` if appropriate\n\nNeed to verify no import cycles would be created.\n\n## Affected Files\n- internal/autoimport/autoimport.go\n- internal/beads/beads.go","status":"open","priority":4,"issue_type":"task","created_at":"2025-11-26T23:45:18.974339-08:00","updated_at":"2025-11-26T23:45:18.974339-08:00"}
@@ -43,9 +41,7 @@
 {"id":"bd-mnap","title":"Investigate performance issues in VS Code Copilot (Windows)","description":"Beads unusable in Windows 11 VS Code Copilot chat with Sonnet 4.5.\nSummary event happens every 3-4 turns, taking 3 minutes.\nCopilot summarizes after ~125k tokens despite model supporting 1M.\nLarge context size of beads might be triggering aggressive summarization.\nNeed workaround or optimization for context size.\n","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:30.124918-05:00","updated_at":"2025-11-20T18:56:30.124918-05:00"}
 {"id":"bd-nq41","title":"Fix Homebrew warning about Ruby file location","description":"Homebrew warning: Found Ruby file outside steveyegge/beads tap formula directory.\nWarning points to: /opt/homebrew/Library/Taps/steveyegge/homebrew-beads/bd.rb\nIt should likely be inside a Formula/ directory or similar structure expected by Homebrew taps.\n","status":"closed","priority":2,"issue_type":"chore","created_at":"2025-11-20T18:56:21.226579-05:00","updated_at":"2025-11-26T22:25:37.362928-08:00","closed_at":"2025-11-26T22:25:37.362928-08:00"}
 {"id":"bd-p6vp","title":"Clarify .beads/.gitattributes handling in Protected Branches docs","description":"Protected Branches docs quick start leaves untracked `.beads` directory and `.gitattributes`.\nQuestion: Are these changes meant to be checked into the protected branch?\nNeed to clarify if these should be ignored or committed, or if the instructions are missing a step.\n","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-20T18:56:25.79407-05:00","updated_at":"2025-11-26T22:25:47.574326-08:00","closed_at":"2025-11-26T22:25:47.574326-08:00"}
-{"id":"bd-pbj","title":"bd doctor --fix should run bd sync to commit untracked deletions.jsonl","description":"After running bd cleanup -f, the deletions.jsonl file is created but left untracked. bd doctor --fix should notice this and run bd sync to commit it.\n\nCurrent behavior:\n- bd cleanup -f creates/updates deletions.jsonl\n- git status shows deletions.jsonl as untracked\n- bd doctor --fix does not notice or fix this\n\nExpected behavior:\n- bd doctor --fix should detect untracked .beads/*.jsonl files\n- Should offer to run bd sync to commit them\n\nRelated: The git hooks were also missing deletions.jsonl from their staging loops - that's been fixed in this session.","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-26T20:29:33.901199-08:00","updated_at":"2025-11-26T20:33:03.296592-08:00","closed_at":"2025-11-26T20:33:03.296592-08:00"}
 {"id":"bd-qsm","title":"Auto-compact deletions during bd sync","description":"Parent: bd-imj\n\n## Task\nOptionally prune deletions manifest during sync when threshold exceeded.\n\n**Note: Opt-in feature** - disabled by default to avoid sync latency.\n\n## Implementation\n\nIn `bd sync`:\n```go\nfunc (s *Syncer) Sync() error {\n    // ... existing sync logic ...\n    \n    // Auto-compact only if enabled\n    if s.config.GetBool(\"deletions.auto_compact\", false) {\n        deletionCount := deletions.Count(\".beads/deletions.jsonl\")\n        threshold := s.config.GetInt(\"deletions.auto_compact_threshold\", 1000)\n        \n        if deletionCount \u003e threshold {\n            retentionDays := s.config.GetInt(\"deletions.retention_days\", 7)\n            if err := s.compactor.PruneDeletions(retentionDays); err != nil {\n                log.Warnf(\"Failed to auto-compact deletions: %v\", err)\n                // Non-fatal, continue sync\n            }\n        }\n    }\n    \n    // ... rest of sync ...\n}\n```\n\n## Configuration\n```yaml\ndeletions:\n  retention_days: 7\n  auto_compact: false              # Opt-in, disabled by default\n  auto_compact_threshold: 1000     # Trigger when \u003e N entries (if enabled)\n```\n\n## Acceptance Criteria\n- [ ] Auto-compact disabled by default\n- [ ] Enabled via config `deletions.auto_compact: true`\n- [ ] Sync checks deletion count only when enabled\n- [ ] Auto-prunes when threshold exceeded\n- [ ] Failure is non-fatal (logged warning)\n- [ ] Test: no compaction when disabled\n- [ ] Test: compaction triggers when enabled and threshold exceeded","status":"closed","priority":1,"issue_type":"task","created_at":"2025-11-25T09:57:04.522795-08:00","updated_at":"2025-11-25T15:03:01.469629-08:00","closed_at":"2025-11-25T15:03:01.469629-08:00"}
-{"id":"bd-red","title":"bd sync should only commit .beads/ files, not all staged changes","description":"Currently bd sync commits ALL staged files, not just .beads/*.jsonl. This can lead to:\n- Unintended commits of work-in-progress code\n- Surprise for users/agents who staged files but weren't ready to commit\n- Mixing beads sync commits with actual code changes\n\nExpected behavior: bd sync should only stage and commit .beads/ files, leaving other staged changes alone.\n\nOptions:\n1. Stash other staged changes, commit only .beads/, restore stash\n2. Use git add .beads/ \u0026\u0026 git commit -m '...' -- .beads/ to only commit beads files\n3. Warn if non-beads files are staged and require --force to proceed","status":"closed","priority":2,"issue_type":"bug","created_at":"2025-11-26T20:35:40.212006-08:00","updated_at":"2025-11-26T20:46:26.106545-08:00","closed_at":"2025-11-26T20:46:26.106545-08:00"}
 {"id":"bd-s0z","title":"Consider extracting error handling helpers","description":"Evaluate creating FatalError() and WarnError() helpers as suggested in ERROR_HANDLING.md to reduce boilerplate and enforce consistency. Prototype in a few files first to validate the approach.","status":"open","priority":4,"issue_type":"task","created_at":"2025-11-24T00:28:57.248959-08:00","updated_at":"2025-11-24T00:28:57.248959-08:00"}
 {"id":"bd-t3b","title":"Add test coverage for internal/config package","description":"","status":"open","priority":2,"issue_type":"task","created_at":"2025-11-20T21:21:22.91657-05:00","updated_at":"2025-11-20T21:21:22.91657-05:00","dependencies":[{"issue_id":"bd-t3b","depends_on_id":"bd-ge7","type":"blocks","created_at":"2025-11-20T21:21:31.201036-05:00","created_by":"daemon"}]}
 {"id":"bd-tne","title":"Add Claude setup tip with dynamic priority","description":"Add a predefined tip that suggests running `bd setup claude` when Claude Code is detected but not configured. This tip should have higher priority (shown more frequently) until the setup is complete.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-11-11T23:29:29.871324-08:00","updated_at":"2025-11-25T17:52:35.044989-08:00","closed_at":"2025-11-25T17:52:35.044989-08:00","dependencies":[{"issue_id":"bd-tne","depends_on_id":"bd-d4i","type":"blocks","created_at":"2025-11-11T23:29:29.872081-08:00","created_by":"daemon"}]}

examples/claude-code-skill/references/CLI_REFERENCE.md

@@ -1,477 +1,559 @@
-# CLI Reference
+# CLI Command Reference
 
-Complete command reference for bd (beads) CLI tool. All commands support `--json` flag for structured output.
+**For:** AI agents and developers using bd command-line interface
+**Version:** 0.21.0+
 
-## Contents
+## Quick Navigation
 
-- [Quick Reference](#quick-reference)
+- [Basic Operations](#basic-operations)
-- [Global Flags](#global-flags)
+- [Issue Management](#issue-management)
-- [Core Commands](#core-commands)
+- [Dependencies & Labels](#dependencies--labels)
-  - [bd ready](#bd-ready) - Find unblocked work
+- [Filtering & Search](#filtering--search)
-  - [bd create](#bd-create) - Create new issues
+- [Advanced Operations](#advanced-operations)
-  - [bd update](#bd-update) - Update issue status, priority, assignee
+- [Database Management](#database-management)
-  - [bd close](#bd-close) - Close completed work
-  - [bd show](#bd-show) - Show issue details
-  - [bd list](#bd-list) - List issues with filters
-- [Dependency Commands](#dependency-commands)
-  - [bd dep add](#bd-dep-add) - Create dependencies
-  - [bd dep tree](#bd-dep-tree) - Visualize dependency trees
-  - [bd dep cycles](#bd-dep-cycles) - Detect circular dependencies
-- [Monitoring Commands](#monitoring-commands)
-  - [bd stats](#bd-stats) - Project statistics
-  - [bd blocked](#bd-blocked) - Find blocked work
-- [Data Management Commands](#data-management-commands)
-  - [bd export](#bd-export) - Export database to JSONL
-  - [bd import](#bd-import) - Import issues from JSONL
-- [Setup Commands](#setup-commands)
-  - [bd init](#bd-init) - Initialize database
-  - [bd quickstart](#bd-quickstart) - Show quick start guide
-- [Common Workflows](#common-workflows)
-- [JSON Output](#json-output)
-- [Database Auto-Discovery](#database-auto-discovery)
-- [Git Integration](#git-integration)
-- [Tips](#tips)
 
-## Quick Reference
+## Basic Operations
 
-| Command | Purpose | Key Flags |
+### Check Status
-|---------|---------|-----------|
+
-| `bd ready` | Find unblocked work | `--priority`, `--assignee`, `--limit`, `--json` |
+```bash
-| `bd list` | List all issues with filters | `--status`, `--priority`, `--type`, `--assignee` |
+# Check database path and daemon status
-| `bd show` | Show issue details | `--json` |
+bd info --json
-| `bd create` | Create new issue | `-t`, `-p`, `-d`, `--design`, `--acceptance` |
+
-| `bd update` | Update existing issue | `--status`, `--priority`, `--design` |
+# Example output:
-| `bd close` | Close completed issue | `--reason` |
+# {
-| `bd dep add` | Add dependency | `--type` (blocks, related, parent-child, discovered-from) |
+#   "database_path": "/path/to/.beads/beads.db",
-| `bd dep tree` | Visualize dependency tree | (no flags) |
+#   "issue_prefix": "bd",
-| `bd dep cycles` | Detect circular dependencies | (no flags) |
+#   "daemon_running": true,
-| `bd stats` | Get project statistics | `--json` |
+#   "agent_mail_enabled": false
-| `bd blocked` | Find blocked issues | `--json` |
+# }
-| `bd export` | Export issues to JSONL | `--json` |
+```
-| `bd import` | Import issues from JSONL | `--dedupe-after`, `--dry-run` |
+
-| `bd init` | Initialize bd in directory | `--prefix` |
+### Find Work
-| `bd quickstart` | Show quick start guide | (no flags) |
+
+```bash
+# Find ready work (no blockers)
+bd ready --json
+
+# Find stale issues (not updated recently)
+bd stale --days 30 --json                    # Default: 30 days
+bd stale --days 90 --status in_progress --json  # Filter by status
+bd stale --limit 20 --json                   # Limit results
+```
+
+## Issue Management
+
+### Create Issues
+
+```bash
+# Basic creation
+# IMPORTANT: Always quote titles and descriptions with double quotes
+bd create "Issue title" -t bug|feature|task -p 0-4 -d "Description" --json
+
+# Create with explicit ID (for parallel workers)
+bd create "Issue title" --id worker1-100 -p 1 --json
+
+# Create with labels (--labels or --label work)
+bd create "Issue title" -t bug -p 1 -l bug,critical --json
+bd create "Issue title" -t bug -p 1 --label bug,critical --json
+
+# Examples with special characters (all require quoting):
+bd create "Fix: auth doesn't validate tokens" -t bug -p 1 --json
+bd create "Add support for OAuth 2.0" -d "Implement RFC 6749 (OAuth 2.0 spec)" --json
+
+# Create multiple issues from markdown file
+bd create -f feature-plan.md --json
+
+# Create epic with hierarchical child tasks
+bd create "Auth System" -t epic -p 1 --json         # Returns: bd-a3f8e9
+bd create "Login UI" -p 1 --json                     # Auto-assigned: bd-a3f8e9.1
+bd create "Backend validation" -p 1 --json           # Auto-assigned: bd-a3f8e9.2
+bd create "Tests" -p 1 --json                        # Auto-assigned: bd-a3f8e9.3
+
+# Create and link discovered work (one command)
+bd create "Found bug" -t bug -p 1 --deps discovered-from:<parent-id> --json
+```
+
+### Update Issues
+
+```bash
+# Update one or more issues
+bd update <id> [<id>...] --status in_progress --json
+bd update <id> [<id>...] --priority 1 --json
+
+# Edit issue fields in $EDITOR (HUMANS ONLY - not for agents)
+# NOTE: This command is intentionally NOT exposed via the MCP server
+# Agents should use 'bd update' with field-specific parameters instead
+bd edit <id>                    # Edit description
+bd edit <id> --title            # Edit title
+bd edit <id> --design           # Edit design notes
+bd edit <id> --notes            # Edit notes
+bd edit <id> --acceptance       # Edit acceptance criteria
+```
+
+### Close/Reopen Issues
+
+```bash
+# Complete work (supports multiple IDs)
+bd close <id> [<id>...] --reason "Done" --json
+
+# Reopen closed issues (supports multiple IDs)
+bd reopen <id> [<id>...] --reason "Reopening" --json
+```
+
+### View Issues
+
+```bash
+# Show dependency tree
+bd dep tree <id>
+
+# Get issue details (supports multiple IDs)
+bd show <id> [<id>...] --json
+```
+
+## Dependencies & Labels
+
+### Dependencies
+
+```bash
+# Link discovered work (old way - two commands)
+bd dep add <discovered-id> <parent-id> --type discovered-from
+
+# Create and link in one command (new way - preferred)
+bd create "Issue title" -t bug -p 1 --deps discovered-from:<parent-id> --json
+```
+
+### Labels
+
+```bash
+# Label management (supports multiple IDs)
+bd label add <id> [<id>...] <label> --json
+bd label remove <id> [<id>...] <label> --json
+bd label list <id> --json
+bd label list-all --json
+```
+
+## Filtering & Search
+
+### Basic Filters
+
+```bash
+# Filter by status, priority, type
+bd list --status open --priority 1 --json               # Status and priority
+bd list --assignee alice --json                         # By assignee
+bd list --type bug --json                               # By issue type
+bd list --id bd-123,bd-456 --json                       # Specific IDs
+```
+
+### Label Filters
+
+```bash
+# Labels (AND: must have ALL)
+bd list --label bug,critical --json
+
+# Labels (OR: has ANY)
+bd list --label-any frontend,backend --json
+```
+
+### Text Search
+
+```bash
+# Title search (substring)
+bd list --title "auth" --json
+
+# Pattern matching (case-insensitive substring)
+bd list --title-contains "auth" --json                  # Search in title
+bd list --desc-contains "implement" --json              # Search in description
+bd list --notes-contains "TODO" --json                  # Search in notes
+```
+
+### Date Range Filters
+
+```bash
+# Date range filters (YYYY-MM-DD or RFC3339)
+bd list --created-after 2024-01-01 --json               # Created after date
+bd list --created-before 2024-12-31 --json              # Created before date
+bd list --updated-after 2024-06-01 --json               # Updated after date
+bd list --updated-before 2024-12-31 --json              # Updated before date
+bd list --closed-after 2024-01-01 --json                # Closed after date
+bd list --closed-before 2024-12-31 --json               # Closed before date
+```
+
+### Empty/Null Checks
+
+```bash
+# Empty/null checks
+bd list --empty-description --json                      # Issues with no description
+bd list --no-assignee --json                            # Unassigned issues
+bd list --no-labels --json                              # Issues with no labels
+```
+
+### Priority Ranges
+
+```bash
+# Priority ranges
+bd list --priority-min 0 --priority-max 1 --json        # P0 and P1 only
+bd list --priority-min 2 --json                         # P2 and below
+```
+
+### Combine Filters
+
+```bash
+# Combine multiple filters
+bd list --status open --priority 1 --label-any urgent,critical --no-assignee --json
+```
 
 ## Global Flags
 
-Available for all commands:
+Global flags work with any bd command and must appear **before** the subcommand.
+
+### Sandbox Mode
+
+**Auto-detection (v0.21.1+):** bd automatically detects sandboxed environments and enables sandbox mode.
+
+When detected, you'll see: `ℹ️  Sandbox detected, using direct mode`
+
+**Manual override:**
 
 ```bash
---json                 # Output in JSON format
+# Explicitly enable sandbox mode
---db /path/to/db       # Specify database path (default: auto-discover)
+bd --sandbox <command>
---actor "name"         # Actor name for audit trail
+
---no-auto-flush        # Disable automatic JSONL sync
+# Equivalent to combining these flags:
---no-auto-import       # Disable automatic JSONL import
+bd --no-daemon --no-auto-flush --no-auto-import <command>
 ```
 
-## Core Commands
+**What it does:**
+- Disables daemon (uses direct SQLite mode)
+- Disables auto-export to JSONL
+- Disables auto-import from JSONL
 
-### bd ready
+**When to use:** Sandboxed environments where daemon can't be controlled (permission restrictions), or when auto-detection doesn't trigger.
 
-Find tasks with no blockers - ready to be worked on.
+### Staleness Control
 
 ```bash
-bd ready                      # All ready work
+# Skip staleness check (emergency escape hatch)
-bd ready --json               # JSON format
+bd --allow-stale <command>
-bd ready --priority 0         # Only priority 0 (critical)
+
-bd ready --assignee alice     # Only assigned to alice
+# Example: access database even if out of sync with JSONL
-bd ready --limit 5            # Limit to 5 results
+bd --allow-stale ready --json
+bd --allow-stale list --status open --json
 ```
 
-**Use at session start** to see available work.
+**Shows:** `⚠️  Staleness check skipped (--allow-stale), data may be out of sync`
 
----
+**⚠️ Caution:** May show stale or incomplete data. Use only when stuck and other options fail.
 
-### bd create
+### Force Import
-
-Create a new issue with optional metadata.
 
 ```bash
-bd create "Title"
+# Force metadata update even when DB appears synced
-bd create "Title" -t bug -p 0
+bd import --force -i .beads/beads.jsonl
-bd create "Title" -d "Description"
-bd create "Title" --design "Design notes"
-bd create "Title" --acceptance "Definition of done"
-bd create "Title" --assignee alice
 ```
 
-**Flags**:
+**When to use:** `bd import` reports "0 created, 0 updated" but staleness errors persist.
-- `-t, --type`: task (default), bug, feature, epic, chore
-- `-p, --priority`: 0-3 (default: 2)
-- `-d, --description`: Issue description
-- `--design`: Design notes
-- `--acceptance`: Acceptance criteria
-- `--assignee`: Who should work on this
 
----
+**Shows:** `Metadata updated (database already in sync with JSONL)`
 
-### bd update
+### Other Global Flags
-
-Update an existing issue's metadata.
 
 ```bash
-bd update issue-123 --status in_progress
+# JSON output for programmatic use
-bd update issue-123 --priority 0
+bd --json <command>
-bd update issue-123 --design "Decided to use Redis"
+
-bd update issue-123 --acceptance "Tests passing"
+# Force direct mode (bypass daemon)
+bd --no-daemon <command>
+
+# Disable auto-sync
+bd --no-auto-flush <command>    # Disable auto-export to JSONL
+bd --no-auto-import <command>   # Disable auto-import from JSONL
+
+# Custom database path
+bd --db /path/to/.beads/beads.db <command>
+
+# Custom actor for audit trail
+bd --actor alice <command>
 ```
 
-**Status values**: open, in_progress, blocked, closed
+**See also:**
+- [TROUBLESHOOTING.md - Sandboxed environments](TROUBLESHOOTING.md#sandboxed-environments-codex-claude-code-etc) for detailed sandbox troubleshooting
+- [DAEMON.md](DAEMON.md) for daemon mode details
 
----
+## Advanced Operations
 
-### bd close
+### Cleanup
-
-Close (complete) an issue.
 
 ```bash
-bd close issue-123
+# Clean up closed issues (bulk deletion)
-bd close issue-123 --reason "Implemented in PR #42"
+bd cleanup --force --json                                   # Delete ALL closed issues
-bd close issue-1 issue-2 issue-3 --reason "Bulk close"
+bd cleanup --older-than 30 --force --json                   # Delete closed >30 days ago
+bd cleanup --dry-run --json                                 # Preview what would be deleted
+bd cleanup --older-than 90 --cascade --force --json         # Delete old + dependents
 ```
 
-**Note**: Closed issues remain in database for history.
+### Duplicate Detection & Merging
-
----
-
-### bd show
-
-Show detailed information about a specific issue.
 
 ```bash
-bd show issue-123
+# Find and merge duplicate issues
-bd show issue-123 --json
+bd duplicates                                          # Show all duplicates
+bd duplicates --auto-merge                             # Automatically merge all
+bd duplicates --dry-run                                # Preview merge operations
+
+# Merge specific duplicate issues
+bd merge <source-id...> --into <target-id> --json      # Consolidate duplicates
+bd merge bd-42 bd-43 --into bd-41 --dry-run            # Preview merge
 ```
 
-Shows: all fields, dependencies, dependents, audit history.
+### Compaction (Memory Decay)
-
----
-
-### bd list
-
-List all issues with optional filters.
 
 ```bash
-bd list                          # All issues
+# Agent-driven compaction
-bd list --status open            # Only open
+bd compact --analyze --json                           # Get candidates for review
-bd list --priority 0             # Critical
+bd compact --analyze --tier 1 --limit 10 --json       # Limited batch
-bd list --type bug               # Only bugs
+bd compact --apply --id bd-42 --summary summary.txt   # Apply compaction
-bd list --assignee alice         # By assignee
+bd compact --apply --id bd-42 --summary - < summary.txt  # From stdin
-bd list --status closed --limit 10  # Recent completions
+bd compact --stats --json                             # Show statistics
+
+# Legacy AI-powered compaction (requires ANTHROPIC_API_KEY)
+bd compact --auto --dry-run --all                     # Preview
+bd compact --auto --all --tier 1                      # Auto-compact tier 1
+
+# Restore compacted issue from git history
+bd restore <id>  # View full history at time of compaction
 ```
 
----
+### Rename Prefix
-
-## Dependency Commands
-
-### bd dep add
-
-Add a dependency between issues.
 
 ```bash
-bd dep add from-issue to-issue                      # blocks (default)
+# Rename issue prefix (e.g., from 'knowledge-work-' to 'kw-')
-bd dep add from-issue to-issue --type blocks
+bd rename-prefix kw- --dry-run  # Preview changes
-bd dep add from-issue to-issue --type related
+bd rename-prefix kw- --json     # Apply rename
-bd dep add epic-id task-id --type parent-child
-bd dep add original-id found-id --type discovered-from
 ```
 
-**Dependency types**:
+## Database Management
-1. **blocks**: from-issue blocks to-issue (hard blocker)
-2. **related**: Soft link (no blocking)
-3. **parent-child**: Epic/subtask hierarchy
-4. **discovered-from**: Tracks origin of discovery
 
----
+### Import/Export
-
-### bd dep tree
-
-Visualize full dependency tree for an issue.
 
 ```bash
-bd dep tree issue-123
+# Import issues from JSONL
+bd import -i .beads/issues.jsonl --dry-run      # Preview changes
+bd import -i .beads/issues.jsonl                # Import and update issues
+bd import -i .beads/issues.jsonl --dedupe-after # Import + detect duplicates
+
+# Handle missing parents during import
+bd import -i issues.jsonl --orphan-handling allow      # Default: import orphans without validation
+bd import -i issues.jsonl --orphan-handling resurrect  # Auto-resurrect deleted parents as tombstones
+bd import -i issues.jsonl --orphan-handling skip       # Skip orphans with warning
+bd import -i issues.jsonl --orphan-handling strict     # Fail if parent is missing
+
+# Configure default orphan handling behavior
+bd config set import.orphan_handling "resurrect"
+bd sync  # Now uses resurrect mode by default
 ```
 
-Shows all dependencies and dependents in tree format.
+**Orphan handling modes:**
 
----
+- **`allow` (default)** - Import orphaned children without parent validation. Most permissive, ensures no data loss even if hierarchy is temporarily broken.
+- **`resurrect`** - Search JSONL history for deleted parents and recreate them as tombstones (Status=Closed, Priority=4). Preserves hierarchy with minimal data. Dependencies are also resurrected on best-effort basis.
+- **`skip`** - Skip orphaned children with warning. Partial import succeeds but some issues are excluded.
+- **`strict`** - Fail import immediately if a child's parent is missing. Use when database integrity is critical.
 
-### bd dep cycles
+**When to use:**
+- Use `allow` (default) for daily imports and auto-sync
+- Use `resurrect` when importing from databases with deleted parents
+- Use `strict` for controlled imports requiring guaranteed parent existence
+- Use `skip` rarely - only for selective imports
 
-Detect circular dependencies.
+See [CONFIG.md](CONFIG.md#example-import-orphan-handling) and [TROUBLESHOOTING.md](TROUBLESHOOTING.md#import-fails-with-missing-parent-errors) for more details.
+
+### Migration
 
 ```bash
-bd dep cycles
+# Migrate databases after version upgrade
+bd migrate                                             # Detect and migrate old databases
+bd migrate --dry-run                                   # Preview migration
+bd migrate --cleanup --yes                             # Migrate and remove old files
+
+# AI-supervised migration (check before running bd migrate)
+bd migrate --inspect --json                            # Show migration plan for AI agents
+bd info --schema --json                                # Get schema, tables, config, sample IDs
 ```
 
-Finds dependency cycles that would prevent work from being ready.
+**Migration workflow for AI agents:**
 
----
+1. Run `--inspect` to see pending migrations and warnings
+2. Check for `missing_config` (like issue_prefix)
+3. Review `invariants_to_check` for safety guarantees
+4. If warnings exist, fix config issues first
+5. Then run `bd migrate` safely
 
-## Monitoring Commands
+**Migration safety invariants:**
 
-### bd stats
+- **required_config_present**: Ensures issue_prefix and schema_version are set
+- **foreign_keys_valid**: No orphaned dependencies or labels
+- **issue_count_stable**: Issue count doesn't decrease unexpectedly
 
-Get project statistics.
+These invariants prevent data loss and would have caught issues like GH #201 (missing issue_prefix after migration).
+
+### Daemon Management
+
+See [docs/DAEMON.md](DAEMON.md) for complete daemon management reference.
 
 ```bash
-bd stats
+# List all running daemons
-bd stats --json
+bd daemons list --json
+
+# Check health (version mismatches, stale sockets)
+bd daemons health --json
+
+# Stop/restart specific daemon
+bd daemons stop /path/to/workspace --json
+bd daemons restart 12345 --json  # By PID
+
+# View daemon logs
+bd daemons logs /path/to/workspace -n 100
+bd daemons logs 12345 -f  # Follow mode
+
+# Stop all daemons
+bd daemons killall --json
+bd daemons killall --force --json  # Force kill if graceful fails
 ```
 
-Returns: total, open, in_progress, closed, blocked, ready, avg lead time.
+### Sync Operations
-
----
-
-### bd blocked
-
-Get blocked issues with blocker information.
 
 ```bash
-bd blocked
+# Manual sync (force immediate export/import/commit/push)
-bd blocked --json
+bd sync
+
+# What it does:
+# 1. Export pending changes to JSONL
+# 2. Commit to git
+# 3. Pull from remote
+# 4. Import any updates
+# 5. Push to remote
 ```
 
-Use to identify bottlenecks when ready list is empty.
+## Issue Types
 
----
+- `bug` - Something broken that needs fixing
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature composed of multiple issues (supports hierarchical children)
+- `chore` - Maintenance work (dependencies, tooling)
 
-## Data Management Commands
+**Hierarchical children:** Epics can have child issues with dotted IDs (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`). Children are auto-numbered sequentially. Up to 3 levels of nesting supported.
 
-### bd export
+## Priorities
 
-Export all issues to JSONL format.
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (nice-to-have features, minor bugs)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+## Dependency Types
+
+- `blocks` - Hard dependency (issue X blocks issue Y)
+- `related` - Soft relationship (issues are connected)
+- `parent-child` - Epic/subtask relationship
+- `discovered-from` - Track issues discovered during work
+
+Only `blocks` dependencies affect the ready work queue.
+
+**Note:** When creating an issue with a `discovered-from` dependency, the new issue automatically inherits the parent's `source_repo` field.
+
+## Output Formats
+
+### JSON Output (Recommended for Agents)
+
+Always use `--json` flag for programmatic use:
 
 ```bash
-bd export > issues.jsonl
+# Single issue
-bd export --json  # Same output, explicit flag
+bd show bd-42 --json
-```
 
-**Use cases:**
+# List of issues
-- Manual backup before risky operations
-- Sharing issues across databases
-- Version control / git tracking
-- Data migration or analysis
-
-**Note**: bd auto-exports to `.beads/*.jsonl` after each operation (5s debounce). Manual export is rarely needed.
-
----
-
-### bd import
-
-Import issues from JSONL format.
-
-```bash
-bd import < issues.jsonl
-bd import -i issues.jsonl --dry-run  # Preview changes
-```
-
-**Behavior with hash-based IDs (v0.20.1+):**
-- Same ID = update operation (hash IDs remain stable)
-- Different issues get different hash IDs (no collisions)
-- Import automatically applies updates to existing issues
-
-**Use `--dry-run` to preview:**
-```bash
-bd import -i issues.jsonl --dry-run
-# Shows: new issues, updates, exact matches
-```
-
-**Use cases:**
-- **Syncing after git pull** - daemon auto-imports, manual rarely needed
-- **Merging databases** - import issues from another database
-- **Restoring from backup** - reimport JSONL to restore state
-
----
-
-## Setup Commands
-
-### bd init
-
-Initialize bd in current directory.
-
-```bash
-bd init                    # Auto-detect prefix
-bd init --prefix api       # Custom prefix
-```
-
-Creates `.beads/` directory and database.
-
----
-
-### bd quickstart
-
-Show comprehensive quick start guide.
-
-```bash
-bd quickstart
-```
-
-Displays built-in reference for command syntax and workflows.
-
----
-
-## Common Workflows
-
-### Session Start
-
-```bash
 bd ready --json
-bd show issue-123
+
-bd update issue-123 --status in_progress
+# Operation result
+bd create "Issue" -p 1 --json
 ```
 
-### Discovery During Work
+### Human-Readable Output
 
-```bash
+Default output without `--json`:
-bd create "Found: bug in auth" -t bug
-bd dep add current-issue new-issue --type discovered-from
-```
 
-### Completing Work
-
-```bash
-bd close issue-123 --reason "Implemented with tests passing"
-bd ready  # See what unblocked
-```
-
-### Planning Epic
-
-```bash
-bd create "OAuth Integration" -t epic
-bd create "Set up credentials" -t task
-bd create "Implement flow" -t task
-
-bd dep add oauth-epic oauth-creds --type parent-child
-bd dep add oauth-epic oauth-flow --type parent-child
-bd dep add oauth-creds oauth-flow  # creds blocks flow
-
-bd dep tree oauth-epic
-```
-
----
-
-## JSON Output
-
-All commands support `--json` for structured output:
-
-```bash
-bd ready --json
-bd show issue-123 --json
-bd list --status open --json
-bd stats --json
-```
-
-Use when parsing programmatically or extracting specific fields.
-
----
-
-## Database Auto-Discovery
-
-bd finds database in this order:
-
-1. `--db` flag: `bd ready --db /path/to/db.db`
-2. `$BEADS_DIR` environment variable (points to .beads directory)
-3. `$BEADS_DB` environment variable (deprecated, points to database file)
-4. `.beads/*.db` in current directory or ancestors
-
-**Project-local** (`.beads/`): Project-specific work, git-tracked
-
-**Recommended**: Use `BEADS_DIR` to point to your `.beads` directory, especially when using `--no-db` mode
-
----
-
-## Git Integration
-
-bd automatically syncs with git:
-
-- **After each operation**: Exports to JSONL (5s debounce)
-- **After git pull**: Imports from JSONL if newer than DB
-
-**Files**:
-- `.beads/*.jsonl` - Source of truth (git-tracked)
-- `.beads/*.db` - Local cache (gitignored)
-
-### Git Integration Troubleshooting
-
-**Problem: `.gitignore` ignores entire `.beads/` directory**
-
-**Symptom**: JSONL file not tracked in git, can't commit beads
-
-**Cause**: Incorrect `.gitignore` pattern blocks everything
-
-**Fix**:
-```bash
-# Check .gitignore
-cat .gitignore | grep beads
-
-# ❌ WRONG (ignores everything including JSONL):
-.beads/
-
-# ✅ CORRECT (ignores only SQLite cache):
-.beads/*.db
-.beads/*.db-*
-```
-
-**After fixing**: Remove the `.beads/` line and add the specific patterns. Then `git add .beads/issues.jsonl`.
-
----
-
-### Permission Troubleshooting
-
-**Problem: bd commands prompt for permission despite whitelist**
-
-**Symptom**: `bd` commands ask for confirmation even with `Bash(bd:*)` in settings.local.json
-
-**Root Cause**: Wildcard patterns in settings.local.json don't actually work - not for bd, not for git, not for any Bash commands. This is a general Claude Code limitation, not bd-specific.
-
-**How It Actually Works**:
-- Individual command approvals (like `Bash(bd ready)`) DO persist across sessions
-- These are stored server-side by Claude Code, not in local config files
-- Commands like `git status` work without prompting because they've been individually approved many times, creating the illusion of a working wildcard pattern
-
-**Permanent Solution**:
-1. Trigger each bd subcommand you use frequently (see command list below)
-2. When prompted, click "Yes, and don't ask again" (NOT "Allow this time")
-3. That specific command will be permanently approved across all future sessions
-
-**Common bd Commands to Approve**:
 ```bash
 bd ready
-bd list
+# bd-42  Fix authentication bug  [P1, bug, in_progress]
-bd stats
+# bd-43  Add user settings page  [P2, feature, open]
-bd blocked
-bd export
-bd version
-bd quickstart
-bd dep cycles
-bd --help
-bd [command] --help  # For any subcommand help
 ```
 
-**Note**: Dynamic commands with arguments (like `bd show <issue-id>`, `bd create "title"`) must be approved per-use since arguments vary. Only static commands can be permanently whitelisted.
+## Common Patterns for AI Agents
 
----
+### Claim and Complete Work
 
-## Tips
-
-**Use JSON for parsing**:
 ```bash
-bd ready --json | jq '.[0].id'
+# 1. Find available work
+bd ready --json
+
+# 2. Claim issue
+bd update bd-42 --status in_progress --json
+
+# 3. Work on it...
+
+# 4. Close when done
+bd close bd-42 --reason "Implemented and tested" --json
 ```
 
-**Bulk operations**:
+### Discover and Link Work
+
 ```bash
-bd close issue-1 issue-2 issue-3 --reason "Sprint complete"
+# While working on bd-100, discover a bug
+
+# Old way (two commands):
+bd create "Found auth bug" -t bug -p 1 --json  # Returns bd-101
+bd dep add bd-101 bd-100 --type discovered-from
+
+# New way (one command):
+bd create "Found auth bug" -t bug -p 1 --deps discovered-from:bd-100 --json
 ```
 
-**Quick filtering**:
+### Batch Operations
+
 ```bash
-bd list --status open --priority 0 --type bug
+# Update multiple issues at once
+bd update bd-41 bd-42 bd-43 --priority 0 --json
+
+# Close multiple issues
+bd close bd-41 bd-42 bd-43 --reason "Batch completion" --json
+
+# Add label to multiple issues
+bd label add bd-41 bd-42 bd-43 urgent --json
 ```
 
-**Built-in help**:
+### Session Workflow
+
 ```bash
-bd quickstart       # Comprehensive guide
+# Start of session
-bd create --help    # Command-specific help
+bd ready --json  # Find work
+
+# During session
+bd create "..." -p 1 --json
+bd update bd-42 --status in_progress --json
+# ... work ...
+
+# End of session (IMPORTANT!)
+bd sync  # Force immediate sync, bypass debounce
 ```
+
+**ALWAYS run `bd sync` at end of agent sessions** to ensure changes are committed/pushed immediately.
+
+## See Also
+
+- [AGENTS.md](../AGENTS.md) - Main agent workflow guide
+- [DAEMON.md](DAEMON.md) - Daemon management and event-driven mode
+- [GIT_INTEGRATION.md](GIT_INTEGRATION.md) - Git workflows and merge strategies
+- [LABELS.md](../LABELS.md) - Label system guide
+- [README.md](../README.md) - User documentation