docs: add documentation for beads, n8n, opencode packages

- Update AGENTS.md header with current commit (366af12) and date (2026-01-13) - Add beads, n8n, opencode to README.md Available Packages table - Update docs/README.md packages list - Create docs/packages/beads.md (220 lines) - Create docs/packages/n8n.md (310 lines) - Create docs/packages/opencode.md (346 lines) Documentation now reflects commit bc75505 which added these three packages.
2026-01-13 21:09:02 +01:00
parent 366af129bd
commit 42d94876d8
6 changed files with 884 additions and 2 deletions
--- a/docs/packages/beads.md
+++ b/docs/packages/beads.md
@@ -0,0 +1,220 @@
+# beads
+
+Lightweight memory system for AI coding agents with graph-based issue tracking.
+
+## Description
+
+beads is a command-line tool designed to provide persistent memory and issue tracking for AI coding agents. It features a graph-based system for managing issues, dependencies, and discovered work across development sessions.
+
+## Features
+
+- 🧠 **Persistent Memory**: Store and retrieve context across AI sessions
+- 📊 **Graph-Based Issue Tracking**: Manage issues with dependency relationships
+- 🔄 **Discovered Work**: Track work discovered during development
+- 🎯 **Multi-Session Continuity**: Resume work from previous sessions
+- 📝 **Git Integration**: Seamless integration with git workflows
+- 🐚 **Shell Completions**: Bash, Fish, and Zsh completions included
+
+## Installation
+
+### Via Overlay
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    beads
+  ];
+}
+```
+
+### Direct Reference
+
+```nix
+{pkgs, ...}: {
+  environment.systemPackages = with pkgs; [
+    inputs.m3ta-nixpkgs.packages.${pkgs.system}.beads
+  ];
+}
+```
+
+### Run Directly
+
+```bash
+nix run git+https://code.m3ta.dev/m3tam3re/nixpkgs#beads
+```
+
+## Usage
+
+### Basic Commands
+
+```bash
+# Show available issues ready to work on
+bd ready
+
+# Create a new issue
+bd create "Fix authentication bug" --type bug --priority 2
+
+# Show issue details
+bd show beads-123
+
+# Update issue status
+bd update beads-123 --status in_progress
+
+# Close completed issues
+bd close beads-123
+
+# Sync with git remote
+bd sync
+```
+
+### Issue Types
+
+- `task`: General tasks
+- `bug`: Bug fixes
+- `feature`: New features
+- `epic`: Large-scale initiatives
+
+### Priority Levels
+
+- `0` (P0): Critical
+- `1` (P1): High
+- `2` (P2): Medium
+- `3` (P3): Low
+- `4` (P4): Backlog
+
+### Dependency Management
+
+```bash
+# Add dependency (beads-123 depends on beads-456)
+bd dep add beads-123 beads-456
+
+# Show blocked issues
+bd blocked
+
+# Show what blocks an issue
+bd show beads-123 --blocked-by
+```
+
+## Advanced Usage
+
+### Finding Work
+
+```bash
+# Show ready tasks (no blockers)
+bd ready
+
+# Show all open issues
+bd list --status open
+
+# Show in-progress work
+bd list --status in_progress
+```
+
+### Assignment
+
+```bash
+# Assign issue to yourself
+bd update beads-123 --assignee username
+
+# Create assigned issue
+bd create "Review PR" --assignee reviewer
+```
+
+### Bulk Operations
+
+```bash
+# Close multiple issues at once
+bd close beads-123 beads-456 beads-789
+
+# Close with reason
+bd close beads-123 --reason "Completed in v1.2.0"
+```
+
+### Hooks
+
+```bash
+# Install git hooks for automatic sync
+bd hooks install
+
+# Remove hooks
+bd hooks uninstall
+```
+
+## Configuration
+
+### Environment Variables
+
+- `BEADS_DATA_DIR`: Custom directory for beads data (default: `.beads/`)
+- `BEADS_CONFIG`: Custom configuration file path
+- `BEADS_EDITOR`: Default editor for editing issues
+
+### Git Integration
+
+beads integrates with git for version-controlled issue tracking:
+
+- Automatic sync before commits (via hooks)
+- Issue references in commit messages
+- Branch name tracking
+- Git-aware issue states
+
+## Workflow Integration
+
+### Typical Development Workflow
+
+1. **Start session**: `bd prime` or check `bd ready`
+2. **Claim work**: `bd update beads-123 --status in_progress`
+3. **Work on task**: Implement changes
+4. **Discover new work**: `bd create "Discovered subtask"` as needed
+5. **Complete task**: `bd close beads-123`
+6. **Sync**: `bd sync` (automatic via hooks)
+
+### Team Collaboration
+
+```bash
+# Create issue and assign
+bd create "Implement feature X" --assignee dev1
+
+# Review assigned work
+bd list --assignee yourname
+
+# Close with review notes
+bd close beads-123 --reason "Reviewed and approved"
+```
+
+## Shell Completions
+
+beads provides shell completions for bash, fish, and zsh:
+
+```bash
+# Bash completions are auto-loaded
+source <(bd completion bash)
+
+# Fish completions
+bd completion fish | source
+
+# Zsh completions
+bd completion zsh > ~/.zfunc/_bd
+```
+
+## Build Information
+
+- **Version**: 0.47.1
+- **Language**: Go
+- **License**: MIT
+- **Source**: [GitHub](https://github.com/steveyegge/beads)
+
+## Platform Support
+
+- Linux
+- macOS
+
+## Notes
+
+- Tests are disabled in the Nix package due to git worktree operations that fail in the sandbox
+- Security tests on Darwin are skipped due to `/etc/passwd` unavailability in sandbox
+- Shell completions are installed for platforms that can execute the build target
+
+## Related
+
+- [Adding Packages](../guides/adding-packages.md) - How to add new packages
+- [Quick Start](../QUICKSTART.md) - Getting started guide