feat: add llms.txt standard support for AI agent discoverability (#784)
Cherry-picked website/, scripts/generate-llms-full.sh, and deploy-docs.yml from joyshmitz's PR. Fixed workflow to trigger on main branch instead of docs/docusaurus-site. Features: - Docusaurus documentation site with llms.txt support - Environment-variable driven config (defaults to steveyegge org) - Automated llms-full.txt generation from docs - GitHub Pages deployment workflow Co-authored-by: joyshmitz <joyshmitz@users.noreply.github.com> 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
This commit is contained in:
Steve Yegge
176
website/docs/reference/advanced.md
Normal file
176
website/docs/reference/advanced.md
Normal file
@@ -0,0 +1,176 @@
|
||||
---
|
||||
id: advanced
|
||||
title: Advanced Features
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Advanced Features
|
||||
|
||||
Advanced beads functionality.
|
||||
|
||||
## Issue Rename
|
||||
|
||||
Rename issues while preserving references:
|
||||
|
||||
```bash
|
||||
bd rename bd-42 bd-new-id
|
||||
bd rename bd-42 bd-new-id --dry-run # Preview
|
||||
```
|
||||
|
||||
Updates:
|
||||
- All dependencies pointing to old ID
|
||||
- All references in other issues
|
||||
- Comments and descriptions
|
||||
|
||||
## Issue Merge
|
||||
|
||||
Merge duplicate issues:
|
||||
|
||||
```bash
|
||||
bd merge bd-42 bd-43 --into bd-41
|
||||
bd merge bd-42 bd-43 --into bd-41 --dry-run
|
||||
```
|
||||
|
||||
What gets merged:
|
||||
- Dependencies → target
|
||||
- Text references updated across all issues
|
||||
- Source issues closed with merge reason
|
||||
|
||||
## Database Compaction
|
||||
|
||||
Reduce database size by compacting old issues:
|
||||
|
||||
```bash
|
||||
# View compaction statistics
|
||||
bd admin compact --stats
|
||||
|
||||
# Preview candidates (30+ days closed)
|
||||
bd admin compact --analyze --json
|
||||
|
||||
# Apply agent-generated summary
|
||||
bd admin compact --apply --id bd-42 --summary summary.txt
|
||||
|
||||
# Immediate deletion (CAUTION!)
|
||||
bd admin cleanup --force
|
||||
```
|
||||
|
||||
**When to compact:**
|
||||
- Database > 10MB with old closed issues
|
||||
- After major milestones
|
||||
- Before archiving project phase
|
||||
|
||||
## Restore from History
|
||||
|
||||
View deleted or compacted issues from git:
|
||||
|
||||
```bash
|
||||
bd restore bd-42 --show
|
||||
bd restore bd-42 --to-file issue.json
|
||||
```
|
||||
|
||||
## Database Inspection
|
||||
|
||||
```bash
|
||||
# Schema info
|
||||
bd info --schema --json
|
||||
|
||||
# Raw database query (advanced)
|
||||
sqlite3 .beads/beads.db "SELECT * FROM issues LIMIT 5"
|
||||
```
|
||||
|
||||
## Custom Tables
|
||||
|
||||
Extend the database with custom tables:
|
||||
|
||||
```go
|
||||
// In Go code using beads as library
|
||||
storage.UnderlyingDB().Exec(`
|
||||
CREATE TABLE IF NOT EXISTS custom_table (...)
|
||||
`)
|
||||
```
|
||||
|
||||
See [EXTENDING.md](https://github.com/steveyegge/beads/blob/main/docs/EXTENDING.md).
|
||||
|
||||
## Event System
|
||||
|
||||
Subscribe to beads events:
|
||||
|
||||
```bash
|
||||
# View recent events
|
||||
bd events list --since 1h
|
||||
|
||||
# Watch events in real-time
|
||||
bd events watch
|
||||
```
|
||||
|
||||
Events:
|
||||
- `issue.created`
|
||||
- `issue.updated`
|
||||
- `issue.closed`
|
||||
- `dependency.added`
|
||||
- `sync.completed`
|
||||
|
||||
## Batch Operations
|
||||
|
||||
### Create Multiple
|
||||
|
||||
```bash
|
||||
cat issues.jsonl | bd import -i -
|
||||
```
|
||||
|
||||
### Update Multiple
|
||||
|
||||
```bash
|
||||
bd list --status open --priority 4 --json | \
|
||||
jq -r '.[].id' | \
|
||||
xargs -I {} bd update {} --priority 3
|
||||
```
|
||||
|
||||
### Close Multiple
|
||||
|
||||
```bash
|
||||
bd list --label "sprint-1" --status open --json | \
|
||||
jq -r '.[].id' | \
|
||||
xargs -I {} bd close {} --reason "Sprint complete"
|
||||
```
|
||||
|
||||
## API Access
|
||||
|
||||
Use beads as a Go library:
|
||||
|
||||
```go
|
||||
import "github.com/steveyegge/beads/internal/storage"
|
||||
|
||||
db, _ := storage.NewSQLite(".beads/beads.db")
|
||||
issues, _ := db.ListIssues(storage.ListOptions{
|
||||
Status: "open",
|
||||
})
|
||||
```
|
||||
|
||||
## Performance Tuning
|
||||
|
||||
### Large Databases
|
||||
|
||||
```bash
|
||||
# Enable WAL mode
|
||||
bd config set database.wal_mode true
|
||||
|
||||
# Increase cache
|
||||
bd config set database.cache_size 10000
|
||||
```
|
||||
|
||||
### Many Concurrent Agents
|
||||
|
||||
```bash
|
||||
# Use event-driven daemon
|
||||
export BEADS_DAEMON_MODE=events
|
||||
bd daemons killall
|
||||
```
|
||||
|
||||
### CI/CD Optimization
|
||||
|
||||
```bash
|
||||
# Disable daemon in CI
|
||||
export BEADS_NO_DAEMON=true
|
||||
bd --no-daemon list
|
||||
```
|
||||
161
website/docs/reference/configuration.md
Normal file
161
website/docs/reference/configuration.md
Normal file
@@ -0,0 +1,161 @@
|
||||
---
|
||||
id: configuration
|
||||
title: Configuration
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
Complete configuration reference for beads.
|
||||
|
||||
## Configuration Locations
|
||||
|
||||
1. **Project config**: `.beads/config.toml` (highest priority)
|
||||
2. **User config**: `~/.beads/config.toml`
|
||||
3. **Environment variables**: `BEADS_*`
|
||||
4. **Command-line flags**: (highest priority)
|
||||
|
||||
## Managing Configuration
|
||||
|
||||
```bash
|
||||
# Get config value
|
||||
bd config get import.orphan_handling
|
||||
|
||||
# Set config value
|
||||
bd config set import.orphan_handling allow
|
||||
|
||||
# List all config
|
||||
bd config list
|
||||
|
||||
# Reset to default
|
||||
bd config reset import.orphan_handling
|
||||
```
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Database
|
||||
|
||||
```toml
|
||||
[database]
|
||||
path = ".beads/beads.db" # Database file location
|
||||
```
|
||||
|
||||
### ID Generation
|
||||
|
||||
```toml
|
||||
[id]
|
||||
prefix = "bd" # Issue ID prefix
|
||||
hash_length = 4 # Hash length in IDs
|
||||
```
|
||||
|
||||
### Import
|
||||
|
||||
```toml
|
||||
[import]
|
||||
orphan_handling = "allow" # allow|resurrect|skip|strict
|
||||
dedupe_on_import = false # Run duplicate detection after import
|
||||
```
|
||||
|
||||
| Mode | Behavior |
|
||||
|------|----------|
|
||||
| `allow` | Import orphans without validation (default) |
|
||||
| `resurrect` | Restore deleted parents as tombstones |
|
||||
| `skip` | Skip orphaned children with warning |
|
||||
| `strict` | Fail if parent missing |
|
||||
|
||||
### Export
|
||||
|
||||
```toml
|
||||
[export]
|
||||
path = ".beads/issues.jsonl" # Export file location
|
||||
auto_export = true # Auto-export on changes
|
||||
debounce_seconds = 5 # Debounce interval
|
||||
```
|
||||
|
||||
### Daemon
|
||||
|
||||
```toml
|
||||
[daemon]
|
||||
auto_start = true # Auto-start daemon
|
||||
sync_interval = "5s" # Sync check interval
|
||||
log_level = "info" # debug|info|warn|error
|
||||
mode = "poll" # poll|events (experimental)
|
||||
```
|
||||
|
||||
### Git
|
||||
|
||||
```toml
|
||||
[git]
|
||||
auto_commit = true # Auto-commit on sync
|
||||
auto_push = true # Auto-push on sync
|
||||
commit_message = "bd sync" # Default commit message
|
||||
```
|
||||
|
||||
### Hooks
|
||||
|
||||
```toml
|
||||
[hooks]
|
||||
pre_commit = true # Enable pre-commit hook
|
||||
post_merge = true # Enable post-merge hook
|
||||
pre_push = true # Enable pre-push hook
|
||||
```
|
||||
|
||||
### Deletions
|
||||
|
||||
```toml
|
||||
[deletions]
|
||||
retention_days = 30 # Keep deletion records for N days
|
||||
prune_on_sync = true # Auto-prune old records
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `BEADS_DB` | Database path |
|
||||
| `BEADS_NO_DAEMON` | Disable daemon |
|
||||
| `BEADS_DAEMON_MODE` | Daemon mode (poll/events) |
|
||||
| `BEADS_LOG_LEVEL` | Log level |
|
||||
| `BEADS_CONFIG` | Config file path |
|
||||
|
||||
## Per-Command Override
|
||||
|
||||
```bash
|
||||
# Override database
|
||||
bd --db /tmp/test.db list
|
||||
|
||||
# Disable daemon for single command
|
||||
bd --no-daemon create "Task"
|
||||
```
|
||||
|
||||
## Example Configuration
|
||||
|
||||
`.beads/config.toml`:
|
||||
|
||||
```toml
|
||||
[id]
|
||||
prefix = "myproject"
|
||||
hash_length = 6
|
||||
|
||||
[import]
|
||||
orphan_handling = "resurrect"
|
||||
dedupe_on_import = true
|
||||
|
||||
[daemon]
|
||||
auto_start = true
|
||||
sync_interval = "10s"
|
||||
mode = "events"
|
||||
|
||||
[git]
|
||||
auto_commit = true
|
||||
auto_push = true
|
||||
|
||||
[deletions]
|
||||
retention_days = 90
|
||||
```
|
||||
|
||||
## Viewing Active Configuration
|
||||
|
||||
```bash
|
||||
bd info --json | jq '.config'
|
||||
```
|
||||
163
website/docs/reference/faq.md
Normal file
163
website/docs/reference/faq.md
Normal file
@@ -0,0 +1,163 @@
|
||||
---
|
||||
id: faq
|
||||
title: FAQ
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Frequently Asked Questions
|
||||
|
||||
## General
|
||||
|
||||
### Why beads instead of GitHub Issues or Jira?
|
||||
|
||||
Beads was designed specifically for AI-supervised coding workflows:
|
||||
- **Hash-based IDs** prevent collisions with concurrent agents
|
||||
- **Git-backed storage** enables branch-based workflows
|
||||
- **Dependency-aware** ready queue for automated work selection
|
||||
- **Formula system** for declarative workflow templates
|
||||
|
||||
### What does "beads" stand for?
|
||||
|
||||
Nothing specific - it's a metaphor for linked work items (like beads on a string).
|
||||
|
||||
### Is beads production-ready?
|
||||
|
||||
Yes, beads is used in production for AI-assisted development. The API is stable with semantic versioning.
|
||||
|
||||
## Architecture
|
||||
|
||||
### Why SQLite + JSONL instead of just one?
|
||||
|
||||
- **SQLite** for fast local queries and complex filtering
|
||||
- **JSONL** for git-friendly versioning and sync
|
||||
- Auto-sync keeps them aligned
|
||||
|
||||
### Why hash-based IDs instead of sequential?
|
||||
|
||||
Sequential IDs (`#1`, `#2`) break when:
|
||||
- Multiple agents create issues simultaneously
|
||||
- Different branches have independent numbering
|
||||
- Forks diverge and merge
|
||||
|
||||
Hash-based IDs are globally unique without coordination.
|
||||
|
||||
### Why a daemon?
|
||||
|
||||
The daemon provides:
|
||||
- Auto-sync with 5-second debounce
|
||||
- Batched operations for performance
|
||||
- Background monitoring
|
||||
|
||||
Use `--no-daemon` when not needed (CI, worktrees).
|
||||
|
||||
## Usage
|
||||
|
||||
### How do I sync issues to git?
|
||||
|
||||
```bash
|
||||
# Auto-sync via daemon (default)
|
||||
# Or manual sync:
|
||||
bd sync
|
||||
```
|
||||
|
||||
### How do I handle merge conflicts?
|
||||
|
||||
Install the beads merge driver:
|
||||
```bash
|
||||
bd init # Prompts for merge driver
|
||||
```
|
||||
|
||||
Or manually resolve and reimport.
|
||||
|
||||
### Can multiple agents work on the same repo?
|
||||
|
||||
Yes! That's what beads was designed for:
|
||||
- Hash IDs prevent collisions
|
||||
- Pin work to specific agents
|
||||
- Track who's working on what
|
||||
|
||||
### How do I use beads in CI/CD?
|
||||
|
||||
```bash
|
||||
# Disable daemon in CI
|
||||
export BEADS_NO_DAEMON=true
|
||||
|
||||
# Or per-command
|
||||
bd --no-daemon list
|
||||
```
|
||||
|
||||
## Workflows
|
||||
|
||||
### What are formulas?
|
||||
|
||||
Declarative workflow templates in TOML or JSON. Pour them to create molecules (instances).
|
||||
|
||||
### What are gates?
|
||||
|
||||
Async coordination primitives:
|
||||
- Human gates wait for approval
|
||||
- Timer gates wait for duration
|
||||
- GitHub gates wait for CI/PR events
|
||||
|
||||
### What's the difference between molecules and wisps?
|
||||
|
||||
- **Molecules** persist in `.beads/` and sync with git
|
||||
- **Wisps** are ephemeral in `.beads-wisp/` and don't sync
|
||||
|
||||
## Integration
|
||||
|
||||
### Should I use CLI or MCP?
|
||||
|
||||
**Use CLI + hooks** when shell is available (Claude Code, Cursor, etc.):
|
||||
- Lower context overhead (~1-2k vs 10-50k tokens)
|
||||
- Faster execution
|
||||
- Universal across editors
|
||||
|
||||
**Use MCP** when CLI unavailable (Claude Desktop).
|
||||
|
||||
### How do I integrate with my editor?
|
||||
|
||||
```bash
|
||||
bd setup claude # Claude Code
|
||||
bd setup cursor # Cursor
|
||||
bd setup aider # Aider
|
||||
```
|
||||
|
||||
### Can beads import from GitHub Issues?
|
||||
|
||||
Yes:
|
||||
```bash
|
||||
bd import --from github --repo owner/repo
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Why is the daemon not starting?
|
||||
|
||||
```bash
|
||||
# Remove stale socket
|
||||
rm -f .beads/bd.sock
|
||||
|
||||
# Restart
|
||||
bd daemons killall
|
||||
bd info
|
||||
```
|
||||
|
||||
### Why aren't my changes syncing?
|
||||
|
||||
```bash
|
||||
# Check daemon status
|
||||
bd info
|
||||
|
||||
# Force sync
|
||||
bd sync
|
||||
|
||||
# Check hooks
|
||||
bd hooks status
|
||||
```
|
||||
|
||||
### How do I report a bug?
|
||||
|
||||
1. Check existing issues: https://github.com/steveyegge/beads/issues
|
||||
2. Include: `bd version`, `bd info --json`, reproduction steps
|
||||
3. File at: https://github.com/steveyegge/beads/issues/new
|
||||
170
website/docs/reference/git-integration.md
Normal file
170
website/docs/reference/git-integration.md
Normal file
@@ -0,0 +1,170 @@
|
||||
---
|
||||
id: git-integration
|
||||
title: Git Integration
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Git Integration
|
||||
|
||||
How beads integrates with git.
|
||||
|
||||
## Overview
|
||||
|
||||
Beads uses git for:
|
||||
- **JSONL sync** - Issues stored in `.beads/issues.jsonl`
|
||||
- **Deletion tracking** - `.beads/deletions.jsonl`
|
||||
- **Conflict resolution** - Custom merge driver
|
||||
- **Hooks** - Auto-sync on git operations
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
.beads/
|
||||
├── beads.db # SQLite database (gitignored)
|
||||
├── issues.jsonl # Issue data (git-tracked)
|
||||
├── deletions.jsonl # Deletion manifest (git-tracked)
|
||||
├── config.toml # Project config (git-tracked)
|
||||
└── bd.sock # Daemon socket (gitignored)
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
Installs:
|
||||
- **pre-commit** - Exports database to JSONL
|
||||
- **post-merge** - Imports from JSONL after pull
|
||||
- **pre-push** - Ensures sync before push
|
||||
|
||||
### Status
|
||||
|
||||
```bash
|
||||
bd hooks status
|
||||
```
|
||||
|
||||
### Uninstall
|
||||
|
||||
```bash
|
||||
bd hooks uninstall
|
||||
```
|
||||
|
||||
## Merge Driver
|
||||
|
||||
### Purpose
|
||||
|
||||
The beads merge driver handles JSONL conflicts automatically:
|
||||
- Merges non-conflicting changes
|
||||
- Uses latest timestamp for same-issue edits
|
||||
- Preserves both sides for real conflicts
|
||||
|
||||
### Installation
|
||||
|
||||
```bash
|
||||
bd init # Prompts for merge driver setup
|
||||
```
|
||||
|
||||
Or manually add to `.gitattributes`:
|
||||
|
||||
```gitattributes
|
||||
.beads/issues.jsonl merge=beads
|
||||
.beads/deletions.jsonl merge=beads
|
||||
```
|
||||
|
||||
And `.git/config`:
|
||||
|
||||
```ini
|
||||
[merge "beads"]
|
||||
name = Beads JSONL merge driver
|
||||
driver = bd merge-driver %O %A %B
|
||||
```
|
||||
|
||||
## Protected Branches
|
||||
|
||||
For protected main branches:
|
||||
|
||||
```bash
|
||||
bd init --branch beads-sync
|
||||
```
|
||||
|
||||
This:
|
||||
- Creates a separate `beads-sync` branch
|
||||
- Syncs issues to that branch
|
||||
- Avoids direct commits to main
|
||||
|
||||
## Git Worktrees
|
||||
|
||||
Beads requires `--no-daemon` in git worktrees:
|
||||
|
||||
```bash
|
||||
# In worktree
|
||||
bd --no-daemon create "Task"
|
||||
bd --no-daemon list
|
||||
```
|
||||
|
||||
Why: Daemon uses `.beads/bd.sock` which conflicts across worktrees.
|
||||
|
||||
## Branch Workflows
|
||||
|
||||
### Feature Branch
|
||||
|
||||
```bash
|
||||
git checkout -b feature-x
|
||||
bd create "Feature X" -t feature
|
||||
# Work...
|
||||
bd sync
|
||||
git push
|
||||
```
|
||||
|
||||
### Fork Workflow
|
||||
|
||||
```bash
|
||||
# In fork
|
||||
bd init --contributor
|
||||
# Work in separate planning repo...
|
||||
bd sync
|
||||
```
|
||||
|
||||
### Team Workflow
|
||||
|
||||
```bash
|
||||
bd init --team
|
||||
# All team members share issues.jsonl
|
||||
git pull # Auto-imports via hook
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
### With Merge Driver
|
||||
|
||||
Automatic - driver handles most conflicts.
|
||||
|
||||
### Manual Resolution
|
||||
|
||||
```bash
|
||||
# After conflict
|
||||
git checkout --ours .beads/issues.jsonl
|
||||
bd import -i .beads/issues.jsonl
|
||||
bd sync
|
||||
git add .beads/
|
||||
git commit
|
||||
```
|
||||
|
||||
### Duplicate Detection
|
||||
|
||||
After merge:
|
||||
|
||||
```bash
|
||||
bd duplicates --auto-merge
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Install hooks** - `bd hooks install`
|
||||
2. **Use merge driver** - Avoid manual conflict resolution
|
||||
3. **Sync regularly** - `bd sync` at session end
|
||||
4. **Pull before work** - Get latest issues
|
||||
5. **Use `--no-daemon` in worktrees**
|
||||
233
website/docs/reference/troubleshooting.md
Normal file
233
website/docs/reference/troubleshooting.md
Normal file
@@ -0,0 +1,233 @@
|
||||
---
|
||||
id: troubleshooting
|
||||
title: Troubleshooting
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Troubleshooting
|
||||
|
||||
Common issues and solutions.
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### `bd: command not found`
|
||||
|
||||
```bash
|
||||
# Check if installed
|
||||
which bd
|
||||
go list -f {{.Target}} github.com/steveyegge/beads/cmd/bd
|
||||
|
||||
# Add Go bin to PATH
|
||||
export PATH="$PATH:$(go env GOPATH)/bin"
|
||||
|
||||
# Or reinstall
|
||||
go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### `zsh: killed bd` on macOS
|
||||
|
||||
CGO/SQLite compatibility issue:
|
||||
|
||||
```bash
|
||||
CGO_ENABLED=1 go install github.com/steveyegge/beads/cmd/bd@latest
|
||||
```
|
||||
|
||||
### Permission denied
|
||||
|
||||
```bash
|
||||
chmod +x $(which bd)
|
||||
```
|
||||
|
||||
## Database Issues
|
||||
|
||||
### Database not found
|
||||
|
||||
```bash
|
||||
# Initialize beads
|
||||
bd init --quiet
|
||||
|
||||
# Or specify database
|
||||
bd --db .beads/beads.db list
|
||||
```
|
||||
|
||||
### Database locked
|
||||
|
||||
```bash
|
||||
# Stop daemon
|
||||
bd daemons killall
|
||||
|
||||
# Try again
|
||||
bd list
|
||||
```
|
||||
|
||||
### Corrupted database
|
||||
|
||||
```bash
|
||||
# Restore from JSONL
|
||||
rm .beads/beads.db
|
||||
bd import -i .beads/issues.jsonl
|
||||
```
|
||||
|
||||
## Daemon Issues
|
||||
|
||||
### Daemon not starting
|
||||
|
||||
```bash
|
||||
# Check status
|
||||
bd info
|
||||
|
||||
# Remove stale socket
|
||||
rm -f .beads/bd.sock
|
||||
|
||||
# Restart
|
||||
bd daemons killall
|
||||
bd info
|
||||
```
|
||||
|
||||
### Version mismatch
|
||||
|
||||
After upgrading bd:
|
||||
|
||||
```bash
|
||||
bd daemons killall
|
||||
bd info
|
||||
```
|
||||
|
||||
### High CPU usage
|
||||
|
||||
```bash
|
||||
# Switch to event-driven mode
|
||||
export BEADS_DAEMON_MODE=events
|
||||
bd daemons killall
|
||||
```
|
||||
|
||||
## Sync Issues
|
||||
|
||||
### Changes not syncing
|
||||
|
||||
```bash
|
||||
# Force sync
|
||||
bd sync
|
||||
|
||||
# Check daemon
|
||||
bd info | grep daemon
|
||||
|
||||
# Check hooks
|
||||
bd hooks status
|
||||
```
|
||||
|
||||
### Import errors
|
||||
|
||||
```bash
|
||||
# Allow orphans
|
||||
bd import -i .beads/issues.jsonl --orphan-handling allow
|
||||
|
||||
# Check for duplicates after
|
||||
bd duplicates
|
||||
```
|
||||
|
||||
### Merge conflicts
|
||||
|
||||
```bash
|
||||
# Use merge driver
|
||||
bd init # Setup merge driver
|
||||
|
||||
# Or manual resolution
|
||||
git checkout --ours .beads/issues.jsonl
|
||||
bd import -i .beads/issues.jsonl
|
||||
bd sync
|
||||
```
|
||||
|
||||
## Git Hook Issues
|
||||
|
||||
### Hooks not running
|
||||
|
||||
```bash
|
||||
# Check if installed
|
||||
ls -la .git/hooks/
|
||||
|
||||
# Reinstall
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
### Hook errors
|
||||
|
||||
```bash
|
||||
# Check hook script
|
||||
cat .git/hooks/pre-commit
|
||||
|
||||
# Run manually
|
||||
.git/hooks/pre-commit
|
||||
```
|
||||
|
||||
## Dependency Issues
|
||||
|
||||
### Circular dependencies
|
||||
|
||||
```bash
|
||||
# Detect cycles
|
||||
bd dep cycles
|
||||
|
||||
# Remove one dependency
|
||||
bd dep remove bd-A bd-B
|
||||
```
|
||||
|
||||
### Missing dependencies
|
||||
|
||||
```bash
|
||||
# Check orphan handling
|
||||
bd config get import.orphan_handling
|
||||
|
||||
# Allow orphans
|
||||
bd config set import.orphan_handling allow
|
||||
```
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Slow queries
|
||||
|
||||
```bash
|
||||
# Check database size
|
||||
ls -lh .beads/beads.db
|
||||
|
||||
# Compact if large
|
||||
bd admin compact --analyze
|
||||
```
|
||||
|
||||
### High memory usage
|
||||
|
||||
```bash
|
||||
# Reduce cache
|
||||
bd config set database.cache_size 1000
|
||||
```
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Debug output
|
||||
|
||||
```bash
|
||||
bd --verbose list
|
||||
```
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
bd daemons logs . -n 100
|
||||
```
|
||||
|
||||
### System info
|
||||
|
||||
```bash
|
||||
bd info --json
|
||||
```
|
||||
|
||||
### File an issue
|
||||
|
||||
```bash
|
||||
# Include this info
|
||||
bd version
|
||||
bd info --json
|
||||
uname -a
|
||||
```
|
||||
|
||||
Report at: https://github.com/steveyegge/beads/issues
|
||||
Reference in New Issue
Block a user