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:
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)
|
||||
Reference in New Issue
Block a user