docs: add chemistry commands documentation (bd-hhv3)

Document new molecular chemistry UX commands:
- bd pour (proto → persistent mol)
- bd wisp create (proto → ephemeral wisp)
- bd hook (inspect pinned work)
- bd pin --for/--start (work assignment)
- bd mol bond --pour/--wisp (phase control)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
2025-12-22 02:55:49 -08:00
parent 9102cdb825
commit 32181fd5a2

View File

@@ -303,6 +303,50 @@ bd monitor --port 3000 # Custom port
**AI agents**: Continue using CLI with `--json` flags. The monitor is for human supervision only.
### Chemistry Commands (Templates & Workflows)
bd uses a molecular chemistry metaphor for template instantiation:
| Phase | Storage | Synced | Use Case |
|-------|---------|--------|----------|
| **Proto** (solid) | Built-in | N/A | Reusable templates |
| **Mol** (liquid) | `.beads/` | Yes | Persistent work |
| **Wisp** (vapor) | `.beads-wisp/` | No | Ephemeral operations |
**Instantiation commands:**
```bash
# Pour: proto → persistent mol (liquid phase)
bd pour <proto> --var key=value # Create in .beads/
# Wisp: proto → ephemeral wisp (vapor phase)
bd wisp create <proto> --var key=value # Create in .beads-wisp/
# List available templates
bd mol list --json
```
**Work assignment:**
```bash
# Pin work to an agent's hook
bd pin <id> --for <agent> --start # Assign and start work
# Inspect what's on an agent's hook
bd hook --agent <agent> # Show pinned work
bd hook --json # JSON output
```
**Phase control with bond:**
```bash
# Attach proto to existing mol/wisp
bd mol bond <proto> <target> --pour # Force liquid (persistent)
bd mol bond <proto> <target> --wisp # Force vapor (ephemeral)
```
**Note:** Commands like `bd pour` require `--no-daemon` flag when daemon is running.
### Workflow
1. **Check your inbox**: Run `gt mail inbox` from your cwd to see handoffs and work assignments