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
165
website/docs/core-concepts/daemon.md
Normal file
165
website/docs/core-concepts/daemon.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
id: daemon
|
||||
title: Daemon Architecture
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Daemon Architecture
|
||||
|
||||
Beads runs a background daemon for auto-sync and performance.
|
||||
|
||||
## Overview
|
||||
|
||||
Each workspace gets its own daemon process:
|
||||
- Auto-starts on first `bd` command
|
||||
- Handles database ↔ JSONL synchronization
|
||||
- Listens on `.beads/bd.sock` (Unix) or `.beads/bd.pipe` (Windows)
|
||||
- Version checking prevents mismatches after upgrades
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
CLI Command
|
||||
↓
|
||||
RPC to Daemon
|
||||
↓
|
||||
Daemon executes
|
||||
↓
|
||||
Auto-sync to JSONL (5s debounce)
|
||||
```
|
||||
|
||||
Without daemon, commands access the database directly (slower, no auto-sync).
|
||||
|
||||
## Managing Daemons
|
||||
|
||||
```bash
|
||||
# List all running daemons
|
||||
bd daemons list
|
||||
bd daemons list --json
|
||||
|
||||
# Check health and version mismatches
|
||||
bd daemons health
|
||||
bd daemons health --json
|
||||
|
||||
# View daemon logs
|
||||
bd daemons logs . -n 100
|
||||
|
||||
# Restart all daemons
|
||||
bd daemons killall
|
||||
bd daemons killall --json
|
||||
```
|
||||
|
||||
## Daemon Info
|
||||
|
||||
```bash
|
||||
bd info
|
||||
```
|
||||
|
||||
Shows:
|
||||
- Daemon status (running/stopped)
|
||||
- Daemon version vs CLI version
|
||||
- Socket location
|
||||
- Auto-sync status
|
||||
|
||||
## Disabling Daemon
|
||||
|
||||
Use `--no-daemon` flag to bypass the daemon:
|
||||
|
||||
```bash
|
||||
bd --no-daemon ready
|
||||
bd --no-daemon list
|
||||
```
|
||||
|
||||
**When to disable:**
|
||||
- Git worktrees (required)
|
||||
- CI/CD pipelines
|
||||
- Resource-constrained environments
|
||||
- Debugging sync issues
|
||||
|
||||
## Event-Driven Mode (Experimental)
|
||||
|
||||
Event-driven mode replaces 5-second polling with instant reactivity:
|
||||
|
||||
```bash
|
||||
# Enable globally
|
||||
export BEADS_DAEMON_MODE=events
|
||||
bd daemons killall # Restart to apply
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- Less than 500ms latency (vs 5s polling)
|
||||
- ~60% less CPU usage
|
||||
- Instant sync after changes
|
||||
|
||||
**How to verify:**
|
||||
```bash
|
||||
bd info | grep "daemon mode"
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Daemon not starting
|
||||
|
||||
```bash
|
||||
# Check if socket exists
|
||||
ls -la .beads/bd.sock
|
||||
|
||||
# Try direct mode
|
||||
bd --no-daemon info
|
||||
|
||||
# Restart daemon
|
||||
bd daemons killall
|
||||
bd info
|
||||
```
|
||||
|
||||
### Version mismatch
|
||||
|
||||
After upgrading bd:
|
||||
|
||||
```bash
|
||||
bd daemons killall
|
||||
bd info # Should show matching versions
|
||||
```
|
||||
|
||||
### Sync not happening
|
||||
|
||||
```bash
|
||||
# Force sync
|
||||
bd sync
|
||||
|
||||
# Check daemon logs
|
||||
bd daemons logs . -n 50
|
||||
|
||||
# Verify git status
|
||||
git status .beads/
|
||||
```
|
||||
|
||||
### Port/socket conflicts
|
||||
|
||||
```bash
|
||||
# Kill all daemons
|
||||
bd daemons killall
|
||||
|
||||
# Remove stale socket
|
||||
rm -f .beads/bd.sock
|
||||
|
||||
# Restart
|
||||
bd info
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
Daemon behavior can be configured:
|
||||
|
||||
```bash
|
||||
# Set sync debounce interval
|
||||
bd config set daemon.sync_interval 10s
|
||||
|
||||
# Disable auto-start
|
||||
bd config set daemon.auto_start false
|
||||
|
||||
# Set log level
|
||||
bd config set daemon.log_level debug
|
||||
```
|
||||
|
||||
See [Configuration](/reference/configuration) for all options.
|
||||
129
website/docs/core-concepts/hash-ids.md
Normal file
129
website/docs/core-concepts/hash-ids.md
Normal file
@@ -0,0 +1,129 @@
|
||||
---
|
||||
id: hash-ids
|
||||
title: Hash-based IDs
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# Hash-based IDs
|
||||
|
||||
Understanding beads' collision-resistant ID system.
|
||||
|
||||
## The Problem
|
||||
|
||||
Traditional sequential IDs (`#1`, `#2`, `#3`) break when:
|
||||
- Multiple agents create issues simultaneously
|
||||
- Different branches have independent numbering
|
||||
- Forks diverge and later merge
|
||||
|
||||
## The Solution
|
||||
|
||||
Beads uses hash-based IDs:
|
||||
|
||||
```
|
||||
bd-a1b2c3 # Short hash
|
||||
bd-f14c # Even shorter
|
||||
bd-a3f8e9.1 # Hierarchical (child of bd-a3f8e9)
|
||||
```
|
||||
|
||||
**Properties:**
|
||||
- Globally unique (content-based hash)
|
||||
- No coordination needed between creators
|
||||
- Merge-friendly across branches
|
||||
- Predictable length (configurable)
|
||||
|
||||
## How Hashes Work
|
||||
|
||||
IDs are generated from:
|
||||
- Issue title
|
||||
- Creation timestamp
|
||||
- Random salt
|
||||
|
||||
```bash
|
||||
# Create issue - ID assigned automatically
|
||||
bd create "Fix authentication bug"
|
||||
# Returns: bd-7x2f
|
||||
|
||||
# The ID is deterministic for same content+timestamp
|
||||
```
|
||||
|
||||
## Hierarchical IDs
|
||||
|
||||
For epics and subtasks:
|
||||
|
||||
```bash
|
||||
# Parent epic
|
||||
bd create "Auth System" -t epic
|
||||
# Returns: bd-a3f8e9
|
||||
|
||||
# Children auto-increment
|
||||
bd create "Design UI" --parent bd-a3f8e9 # bd-a3f8e9.1
|
||||
bd create "Backend" --parent bd-a3f8e9 # bd-a3f8e9.2
|
||||
bd create "Tests" --parent bd-a3f8e9 # bd-a3f8e9.3
|
||||
```
|
||||
|
||||
Benefits:
|
||||
- Clear parent-child relationship
|
||||
- No namespace collision (parent hash is unique)
|
||||
- Up to 3 levels of nesting
|
||||
|
||||
## ID Configuration
|
||||
|
||||
Configure ID prefix and length:
|
||||
|
||||
```bash
|
||||
# Set prefix (default: bd)
|
||||
bd config set id.prefix myproject
|
||||
|
||||
# Set hash length (default: 4)
|
||||
bd config set id.hash_length 6
|
||||
|
||||
# New issues use new format
|
||||
bd create "Test"
|
||||
# Returns: myproject-a1b2c3
|
||||
```
|
||||
|
||||
## Collision Handling
|
||||
|
||||
While rare, collisions are handled automatically:
|
||||
|
||||
1. On import, if hash collision detected
|
||||
2. Beads appends disambiguator
|
||||
3. Both issues preserved
|
||||
|
||||
```bash
|
||||
# Check for collisions
|
||||
bd info --schema --json | jq '.collision_count'
|
||||
```
|
||||
|
||||
## Working with IDs
|
||||
|
||||
```bash
|
||||
# Partial ID matching
|
||||
bd show a1b2 # Finds bd-a1b2...
|
||||
bd show auth # Fuzzy match by title
|
||||
|
||||
# Full ID required for ambiguous cases
|
||||
bd show bd-a1b2c3d4
|
||||
|
||||
# List with full IDs
|
||||
bd list --full-ids
|
||||
```
|
||||
|
||||
## Migration from Sequential IDs
|
||||
|
||||
If migrating from a system with sequential IDs:
|
||||
|
||||
```bash
|
||||
# Import preserves original IDs in metadata
|
||||
bd import -i old-issues.json
|
||||
|
||||
# View original ID
|
||||
bd show bd-new --json | jq '.original_id'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Use short references** - `bd-a1b2` is usually unique enough
|
||||
2. **Use `--json` for scripts** - Parse full ID programmatically
|
||||
3. **Reference by hash in commits** - `Fixed bd-a1b2` in commit messages
|
||||
4. **Let hierarchies form naturally** - Create epics, add children as needed
|
||||
76
website/docs/core-concepts/index.md
Normal file
76
website/docs/core-concepts/index.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
id: index
|
||||
title: Core Concepts
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Core Concepts
|
||||
|
||||
Understanding the fundamental concepts behind beads.
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
Beads was built with these principles:
|
||||
|
||||
1. **Git as source of truth** - Issues sync via JSONL files, enabling collaboration across branches
|
||||
2. **AI-native workflows** - Hash-based IDs, JSON output, dependency-aware execution
|
||||
3. **Local-first operation** - SQLite database for fast queries, background sync
|
||||
4. **Declarative workflows** - Formulas define repeatable patterns
|
||||
|
||||
## Key Components
|
||||
|
||||
### Issues
|
||||
|
||||
Work items with:
|
||||
- **ID** - Hash-based (e.g., `bd-a1b2`) or hierarchical (e.g., `bd-a1b2.1`)
|
||||
- **Type** - `bug`, `feature`, `task`, `epic`, `chore`
|
||||
- **Priority** - 0 (critical) to 4 (backlog)
|
||||
- **Status** - `open`, `in_progress`, `closed`
|
||||
- **Labels** - Flexible tagging
|
||||
- **Dependencies** - Blocking relationships
|
||||
|
||||
### Dependencies
|
||||
|
||||
Four types of relationships:
|
||||
|
||||
| Type | Description | Affects Ready Queue |
|
||||
|------|-------------|---------------------|
|
||||
| `blocks` | Hard dependency (X blocks Y) | Yes |
|
||||
| `parent-child` | Epic/subtask relationship | No |
|
||||
| `discovered-from` | Track issues found during work | No |
|
||||
| `related` | Soft relationship | No |
|
||||
|
||||
### Daemon
|
||||
|
||||
Background process per workspace:
|
||||
- Auto-starts on first command
|
||||
- Handles auto-sync with 5s debounce
|
||||
- Socket at `.beads/bd.sock`
|
||||
- Manage with `bd daemons` commands
|
||||
|
||||
### JSONL Sync
|
||||
|
||||
The synchronization mechanism:
|
||||
|
||||
```
|
||||
SQLite DB (.beads/beads.db)
|
||||
↕ auto-sync
|
||||
JSONL (.beads/issues.jsonl)
|
||||
↕ git
|
||||
Remote repository
|
||||
```
|
||||
|
||||
### Formulas
|
||||
|
||||
Declarative workflow templates:
|
||||
- Define steps with dependencies
|
||||
- Variable substitution
|
||||
- Gates for async coordination
|
||||
- Aspect-oriented transformations
|
||||
|
||||
## Navigation
|
||||
|
||||
- [Issues & Dependencies](/core-concepts/issues)
|
||||
- [Daemon Architecture](/core-concepts/daemon)
|
||||
- [JSONL Sync](/core-concepts/jsonl-sync)
|
||||
- [Hash-based IDs](/core-concepts/hash-ids)
|
||||
183
website/docs/core-concepts/issues.md
Normal file
183
website/docs/core-concepts/issues.md
Normal file
@@ -0,0 +1,183 @@
|
||||
---
|
||||
id: issues
|
||||
title: Issues & Dependencies
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Issues & Dependencies
|
||||
|
||||
Understanding the issue model in beads.
|
||||
|
||||
## Issue Structure
|
||||
|
||||
Every issue has:
|
||||
|
||||
```bash
|
||||
bd show bd-42 --json
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "bd-42",
|
||||
"title": "Implement authentication",
|
||||
"description": "Add JWT-based auth",
|
||||
"type": "feature",
|
||||
"status": "open",
|
||||
"priority": 1,
|
||||
"labels": ["backend", "security"],
|
||||
"created_at": "2024-01-15T10:30:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## Issue Types
|
||||
|
||||
| Type | Use Case |
|
||||
|------|----------|
|
||||
| `bug` | Something broken that needs fixing |
|
||||
| `feature` | New functionality |
|
||||
| `task` | Work item (tests, docs, refactoring) |
|
||||
| `epic` | Large feature with subtasks |
|
||||
| `chore` | Maintenance (dependencies, tooling) |
|
||||
|
||||
## Priorities
|
||||
|
||||
| Priority | Level | Examples |
|
||||
|----------|-------|----------|
|
||||
| 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 |
|
||||
|
||||
## Creating Issues
|
||||
|
||||
```bash
|
||||
# Basic issue
|
||||
bd create "Fix login bug" -t bug -p 1
|
||||
|
||||
# With description
|
||||
bd create "Add password reset" \
|
||||
--description="Users need to reset forgotten passwords via email" \
|
||||
-t feature -p 2
|
||||
|
||||
# With labels
|
||||
bd create "Update dependencies" -t chore -l "maintenance,security"
|
||||
|
||||
# JSON output for agents
|
||||
bd create "Task" -t task --json
|
||||
```
|
||||
|
||||
## Dependencies
|
||||
|
||||
### Blocking Dependencies
|
||||
|
||||
The `blocks` relationship affects the ready queue:
|
||||
|
||||
```bash
|
||||
# Add dependency: bd-2 depends on bd-1
|
||||
bd dep add bd-2 bd-1
|
||||
|
||||
# View dependencies
|
||||
bd dep tree bd-2
|
||||
|
||||
# See blocked issues
|
||||
bd blocked
|
||||
|
||||
# See ready work (not blocked)
|
||||
bd ready
|
||||
```
|
||||
|
||||
### Structural Relationships
|
||||
|
||||
These don't affect the ready queue:
|
||||
|
||||
```bash
|
||||
# Parent-child (epic subtasks)
|
||||
bd create "Epic" -t epic
|
||||
bd create "Subtask" --parent bd-42
|
||||
|
||||
# Discovered-from (found during work)
|
||||
bd create "Found bug" --deps discovered-from:bd-42
|
||||
|
||||
# Related (soft link)
|
||||
bd relate bd-1 bd-2
|
||||
```
|
||||
|
||||
### Dependency Types
|
||||
|
||||
| Type | Description | Ready Queue Impact |
|
||||
|------|-------------|-------------------|
|
||||
| `blocks` | Hard dependency | Yes - blocked items not ready |
|
||||
| `parent-child` | Epic/subtask hierarchy | No |
|
||||
| `discovered-from` | Tracks origin of discovery | No |
|
||||
| `related` | Soft relationship | No |
|
||||
|
||||
## Hierarchical Issues
|
||||
|
||||
For large features, use hierarchical IDs:
|
||||
|
||||
```bash
|
||||
# Create epic
|
||||
bd create "Auth System" -t epic -p 1
|
||||
# Returns: bd-a3f8e9
|
||||
|
||||
# Child tasks auto-number
|
||||
bd create "Design login UI" --parent bd-a3f8e9 # bd-a3f8e9.1
|
||||
bd create "Backend validation" --parent bd-a3f8e9 # bd-a3f8e9.2
|
||||
|
||||
# View hierarchy
|
||||
bd dep tree bd-a3f8e9
|
||||
```
|
||||
|
||||
## Updating Issues
|
||||
|
||||
```bash
|
||||
# Change status
|
||||
bd update bd-42 --status in_progress
|
||||
|
||||
# Change priority
|
||||
bd update bd-42 --priority 0
|
||||
|
||||
# Add labels
|
||||
bd update bd-42 --add-label urgent
|
||||
|
||||
# Multiple changes
|
||||
bd update bd-42 --status in_progress --priority 1 --add-label "in-review"
|
||||
```
|
||||
|
||||
## Closing Issues
|
||||
|
||||
```bash
|
||||
# Simple close
|
||||
bd close bd-42
|
||||
|
||||
# With reason
|
||||
bd close bd-42 --reason "Implemented in PR #123"
|
||||
|
||||
# JSON output
|
||||
bd close bd-42 --json
|
||||
```
|
||||
|
||||
## Searching and Filtering
|
||||
|
||||
```bash
|
||||
# By status
|
||||
bd list --status open
|
||||
bd list --status in_progress
|
||||
|
||||
# By priority
|
||||
bd list --priority 1
|
||||
bd list --priority 0,1 # Multiple
|
||||
|
||||
# By type
|
||||
bd list --type bug
|
||||
bd list --type feature,task
|
||||
|
||||
# By label
|
||||
bd list --label-any urgent,critical
|
||||
bd list --label-all backend,security
|
||||
|
||||
# Combined filters
|
||||
bd list --status open --priority 1 --type bug --json
|
||||
```
|
||||
179
website/docs/core-concepts/jsonl-sync.md
Normal file
179
website/docs/core-concepts/jsonl-sync.md
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
id: jsonl-sync
|
||||
title: JSONL Sync
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# JSONL Sync
|
||||
|
||||
How beads synchronizes issues across git.
|
||||
|
||||
## The Magic
|
||||
|
||||
Beads uses a dual-storage architecture:
|
||||
|
||||
```
|
||||
SQLite DB (.beads/beads.db, gitignored)
|
||||
↕ auto-sync (5s debounce)
|
||||
JSONL (.beads/issues.jsonl, git-tracked)
|
||||
↕ git push/pull
|
||||
Remote JSONL (shared across machines)
|
||||
```
|
||||
|
||||
**Why this design?**
|
||||
- SQLite for fast local queries
|
||||
- JSONL for git-friendly versioning
|
||||
- Automatic sync keeps them aligned
|
||||
|
||||
## Auto-Sync Behavior
|
||||
|
||||
### Export (SQLite → JSONL)
|
||||
|
||||
Triggers:
|
||||
- Any database change
|
||||
- After 5 second debounce (batches multiple changes)
|
||||
- Manual `bd sync`
|
||||
|
||||
```bash
|
||||
# Force immediate export
|
||||
bd sync
|
||||
|
||||
# Check what would be exported
|
||||
bd export --dry-run
|
||||
```
|
||||
|
||||
### Import (JSONL → SQLite)
|
||||
|
||||
Triggers:
|
||||
- After `git pull` (via git hooks)
|
||||
- When JSONL is newer than database
|
||||
- Manual `bd import`
|
||||
|
||||
```bash
|
||||
# Force import
|
||||
bd import -i .beads/issues.jsonl
|
||||
|
||||
# Preview import
|
||||
bd import -i .beads/issues.jsonl --dry-run
|
||||
```
|
||||
|
||||
## Git Hooks
|
||||
|
||||
Install hooks for seamless sync:
|
||||
|
||||
```bash
|
||||
bd hooks install
|
||||
```
|
||||
|
||||
Hooks installed:
|
||||
- **pre-commit** - Exports to JSONL before commit
|
||||
- **post-merge** - Imports from JSONL after pull
|
||||
- **pre-push** - Ensures sync before push
|
||||
|
||||
## Manual Sync
|
||||
|
||||
```bash
|
||||
# Full sync cycle: export + commit + push
|
||||
bd sync
|
||||
|
||||
# Just export
|
||||
bd export
|
||||
|
||||
# Just import
|
||||
bd import -i .beads/issues.jsonl
|
||||
```
|
||||
|
||||
## Conflict Resolution
|
||||
|
||||
When JSONL conflicts occur during git merge:
|
||||
|
||||
### With Merge Driver (Recommended)
|
||||
|
||||
The beads merge driver handles JSONL conflicts automatically:
|
||||
|
||||
```bash
|
||||
# Install merge driver
|
||||
bd init # Prompts for merge driver setup
|
||||
```
|
||||
|
||||
The driver:
|
||||
- Merges non-conflicting changes
|
||||
- Preserves both sides for real conflicts
|
||||
- Uses latest timestamp for same-issue edits
|
||||
|
||||
### Without Merge Driver
|
||||
|
||||
Manual resolution:
|
||||
|
||||
```bash
|
||||
# After merge conflict
|
||||
git checkout --ours .beads/issues.jsonl # or --theirs
|
||||
bd import -i .beads/issues.jsonl
|
||||
bd sync
|
||||
```
|
||||
|
||||
## Orphan Handling
|
||||
|
||||
When importing issues with missing parents:
|
||||
|
||||
```bash
|
||||
# Configure orphan handling
|
||||
bd config set import.orphan_handling allow # Import anyway (default)
|
||||
bd config set import.orphan_handling resurrect # Restore deleted parents
|
||||
bd config set import.orphan_handling skip # Skip orphans
|
||||
bd config set import.orphan_handling strict # Fail on orphans
|
||||
```
|
||||
|
||||
Per-command override:
|
||||
|
||||
```bash
|
||||
bd import -i issues.jsonl --orphan-handling resurrect
|
||||
```
|
||||
|
||||
## Deletion Tracking
|
||||
|
||||
Deleted issues are tracked in `.beads/deletions.jsonl`:
|
||||
|
||||
```bash
|
||||
# Delete issue (records to manifest)
|
||||
bd delete bd-42
|
||||
|
||||
# View deletions
|
||||
bd deleted
|
||||
bd deleted --since=30d
|
||||
|
||||
# Deletions propagate via git
|
||||
git pull # Imports deletions from remote
|
||||
```
|
||||
|
||||
## Troubleshooting Sync
|
||||
|
||||
### JSONL out of sync
|
||||
|
||||
```bash
|
||||
# Force full sync
|
||||
bd sync
|
||||
|
||||
# Check sync status
|
||||
bd info
|
||||
```
|
||||
|
||||
### Import errors
|
||||
|
||||
```bash
|
||||
# Check import status
|
||||
bd import -i .beads/issues.jsonl --dry-run
|
||||
|
||||
# Allow orphans if needed
|
||||
bd import -i .beads/issues.jsonl --orphan-handling allow
|
||||
```
|
||||
|
||||
### Duplicate detection
|
||||
|
||||
```bash
|
||||
# Find duplicates after import
|
||||
bd duplicates
|
||||
|
||||
# Auto-merge duplicates
|
||||
bd duplicates --auto-merge
|
||||
```
|
||||
Reference in New Issue
Block a user