beads/website/versioned_docs/version-1.0.0/reference/advanced.md
matt wilkie 57a4cab9f0
docs: fix broken xref to docs/EXTENDING.md in extension example (#3713)
* docs: fix broken xref to docs/EXTENDING.md in extension example

The extension example README referenced docs/EXTENDING.md in three
places, but that file was deliberately deleted in the SQLite -> Dolt
migration (see CHANGELOG entry "Deleted deprecated docs - removed
EXTENDING.md and MULTI_REPO_HYDRATION.md (SQLite-era, no longer
applicable)"). Anyone following the example hits a broken link.

Removed all three references. The example README is itself the
canonical reference for the extension pattern, so no redirect target
is needed.

Note: other docs in the repo still reference the deleted EXTENDING.md
(docs/ADVANCED.md, docs/CONFIG.md, examples/library-usage/README.md,
website/docs/reference/advanced.md). Those are out of scope for this
fix and should be addressed in follow-up issues.

Tracking bead: mybd-q71
GH: #3683
PR: builds on follow-up audit from PR #3706

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: fix remaining broken xrefs to deleted EXTENDING.md across repo

Round 1 (commit ddeff314c) only fixed the extension example README
because the original prompt scoped that PR narrowly. The bead
(mybd-q71) acceptance is repo-wide ("no broken xrefs anywhere"), so
this follow-up sweeps the rest in the same PR per the project's
"one issue per PR" rule.

Per-file treatment (EXTENDING.md was deleted in commit 508387377
before v1.0.0 was tagged, so even the v1.0.0 versioned snapshot has
been broken since release):

- docs/ADVANCED.md (3 refs):
  * Note in Extensible Database section: drop trailing "See
    EXTENDING.md for details" — the surrounding sentence about
    Dolt-era alternatives stands on its own.
  * Bold "See EXTENDING.md for complete documentation" line:
    redirect to the canonical working example
    (examples/bd-example-extension-go).
  * Next Steps bullet: same redirect.
- docs/CONFIG.md (2 refs):
  * Namespace doc for compact_*: replace "(see EXTENDING.md)" with
    "(used by `bd admin compact`)" — the doc itself describes the
    keys, no external reference needed.
  * See Also bullet: replace with link to docs/ADVANCED.md
    (Extensible Database section).
- examples/library-usage/README.md (1 ref):
  * See Also bullet: replace EXTENDING.md link with link to the
    sibling bd-example-extension-go example.
- website/docs/reference/advanced.md (1 ref):
  * Custom Tables section: replace EXTENDING.md link with link to
    the bd-example-extension-go README on GitHub.
- website/versioned_docs/version-1.0.0/reference/advanced.md (1 ref):
  * Same fix as the live docs. EXTENDING.md was deleted before
    v1.0.0 release (commit 508387377 is an ancestor of tag v1.0.0),
    so this versioned snapshot has been broken since cut and a fix
    here doesn't violate frozen-in-time correctness — the link was
    never valid in the v1.0.0 release.
- website/static/llms-full.txt (1 ref, auto-generated artifact):
  * Updated to match the corrected source so the on-disk artifact
    isn't broken until next regeneration.
- beads.go and internal/beads/beads.go (package doc comments):
  * Replaced "see docs/EXTENDING.md" / "see EXTENDING.md" with a
    pointer to examples/bd-example-extension-go. These were real
    broken pointers in published Go source comments.

CHANGELOG.md historical entries left untouched (intentional history).
cmd/bd/info.go:747 left untouched (it's a programmatic CHANGELOG
entry rendered by `bd info`, equivalent to a CHANGELOG line).

Verification:
  grep -rn 'EXTENDING\.md' --include='*.md' .
returns only CHANGELOG.md hits.

Tracking bead: mybd-q71
GH: #3683
PR: #3713 (round 2)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: CI Bot <ci@beads.test>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-05 13:18:43 -07:00

182 lines
3.2 KiB
Markdown

---
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 — requires dolt sql-server running)
bd dolt sql "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 the [bd-example-extension-go example](https://github.com/gastownhall/beads/blob/main/examples/bd-example-extension-go/README.md) for a working extension.
## 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
# Bootstrap a new database from JSONL
bd init --from-jsonl issues.jsonl
```
### 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/embeddeddolt"
store, _ := embeddeddolt.New(ctx, ".beads", "beads", "main")
defer store.Close()
issue, _ := store.GetIssue(ctx, "bd-a1b2")
```
## 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
Beads uses Dolt server mode to handle concurrent access from multiple agents.
The server manages transaction isolation automatically.
```bash
# Start the Dolt server
bd dolt start
# Check server health
bd doctor
```
### CI/CD Optimization
In CI/CD environments, beads uses embedded mode by default (no server required):
```bash
# Just run commands directly — no special flags needed
bd list
```