johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update documentation for bd mol pour/wisp command structure

Browse Source 
Updated all documentation and help text to reflect:
- bd pour → bd mol pour
- bd ephemeral → bd mol wisp
- bd ephemeral list → bd mol wisp list
- bd ephemeral gc → bd mol wisp gc

Files updated:
- docs/MOLECULES.md
- docs/CLI_REFERENCE.md
- docs/ARCHITECTURE.md
- docs/DELETIONS.md
- skills/beads/references/MOLECULES.md
- cmd/bd/mol_catalog.go
- cmd/bd/mol_current.go
- cmd/bd/mol_distill.go
- cmd/bd/cook.go
This commit is contained in:
Steve Yegge
2025-12-26 23:52:50 -08:00
parent a958c83422
commit 15cfef0247
9 changed files with 42 additions and 42 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
cmd/bd/cook.go
View File

@@ -353,7 +353,7 @@ func runCook(cmd *cobra.Command, args []string) {
if len(bondPoints) > 0 {
fmt.Printf(" Bond points: %s\n", strings.Join(bondPoints, ", "))
}
fmt.Printf("\nTo use: bd pour %s --var <name>=<value>\n", result.ProtoID)
fmt.Printf("\nTo use: bd mol pour %s --var <name>=<value>\n", result.ProtoID)
}
// cookFormulaResult holds the result of cooking

8
cmd/bd/mol_catalog.go
View File

@@ -23,7 +23,7 @@ var molCatalogCmd = &cobra.Command{
Use: "catalog",
Aliases: []string{"list", "ls"},
Short: "List available molecule formulas",
Long: `List formulas available for bd pour / bd ephemeral create.
Long: `List formulas available for bd mol pour / bd mol wisp.
Formulas are ephemeral proto definitions stored as .formula.json files.
They are cooked inline when pouring, never stored as database beads.
@@ -92,12 +92,12 @@ Search paths (in priority order):
fmt.Println("\nOr distill from existing work:")
fmt.Println(" bd mol distill <epic-id> my-workflow")
fmt.Println("\nTo instantiate from formula:")
fmt.Println(" bd pour <formula-name> --var key=value # persistent mol")
fmt.Println(" bd ephemeral create <formula-name> --var key=value # ephemeral wisp")
fmt.Println(" bd mol pour <formula-name> --var key=value # persistent mol")
fmt.Println(" bd mol wisp <formula-name> --var key=value # ephemeral wisp")
return
}
fmt.Printf("%s\n\n", ui.RenderPass("Formulas (for bd pour / bd ephemeral create):"))
fmt.Printf("%s\n\n", ui.RenderPass("Formulas (for bd mol pour / bd mol wisp):"))
// Group by type for display
byType := make(map[string][]CatalogEntry)

2
cmd/bd/mol_current.go
View File

@@ -100,7 +100,7 @@ The output shows all steps with status indicators:
}
fmt.Println(".")
fmt.Println("\nTo start work on a molecule:")
fmt.Println(" bd pour <proto-id> # Instantiate a molecule from template")
fmt.Println(" bd mol pour <proto-id> # Instantiate a molecule from template")
fmt.Println(" bd update <step-id> --status in_progress # Claim a step")
return
}

2
cmd/bd/mol_distill.go
View File

@@ -225,7 +225,7 @@ func runMolDistill(cmd *cobra.Command, args []string) {
fmt.Printf(" Variables: %s\n", strings.Join(result.Variables, ", "))
}
fmt.Printf("\nTo instantiate:\n")
fmt.Printf(" bd pour %s", result.FormulaName)
fmt.Printf(" bd mol pour %s", result.FormulaName)
for _, v := range result.Variables {
fmt.Printf(" --var %s=<value>", v)
}

2
docs/ARCHITECTURE.md
View File

@@ -275,7 +275,7 @@ open ──▶ in_progress ──▶ closed
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ bd ephemeral create │───▶│ Wisp Issues │───▶│ bd mol squash │
│ bd mol wisp │───▶│ Wisp Issues │───▶│ bd mol squash │
│ (from template) │ │ (local-only) │ │ (→ digest) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```

26
docs/CLI_REFERENCE.md
View File

@@ -350,8 +350,8 @@ Beads uses a chemistry metaphor for template-based workflows. See [MOLECULES.md]
| Phase | State | Storage | Command |
|-------|-------|---------|---------|
| Solid | Proto | `.beads/` | `bd mol catalog` |
| Liquid | Mol | `.beads/` | `bd pour` |
| Vapor | Wisp | `.beads/` (Wisp=true, not exported) | `bd ephemeral create` |
| Liquid | Mol | `.beads/` | `bd mol pour` |
| Vapor | Wisp | `.beads/` (Ephemeral=true, not exported) | `bd mol wisp` |
### Proto/Template Commands
@@ -370,32 +370,32 @@ bd mol distill <epic-id> --json
```bash
# Instantiate proto as persistent mol (solid → liquid)
bd pour <proto-id> --var key=value --json
bd mol pour <proto-id> --var key=value --json
# Preview what would be created
bd pour <proto-id> --var key=value --dry-run
bd mol pour <proto-id> --var key=value --dry-run
# Assign root issue
bd pour <proto-id> --var key=value --assignee alice --json
bd mol pour <proto-id> --var key=value --assignee alice --json
# Attach additional protos during pour
bd pour <proto-id> --attach <other-proto> --json
bd mol pour <proto-id> --attach <other-proto> --json
```
### Wisp Commands
```bash
# Instantiate proto as ephemeral issue (solid → vapor)
bd ephemeral create <proto-id> --var key=value --json
# Instantiate proto as ephemeral wisp (solid → vapor)
bd mol wisp <proto-id> --var key=value --json
# List all wisps
bd ephemeral list --json
bd ephemeral list --all --json # Include closed
bd mol wisp list --json
bd mol wisp list --all --json # Include closed
# Garbage collect orphaned wisps
bd ephemeral gc --json
bd ephemeral gc --age 24h --json # Custom age threshold
bd ephemeral gc --dry-run # Preview what would be cleaned
bd mol wisp gc --json
bd mol wisp gc --age 24h --json # Custom age threshold
bd mol wisp gc --dry-run # Preview what would be cleaned
```
### Bonding (Combining Work)

2
docs/DELETIONS.md
View File

@@ -202,7 +202,7 @@ The 1-hour grace period ensures tombstones propagate even with minor clock drift
## Wisps: Intentional Tombstone Bypass
**Wisps** (ephemeral issues created by `bd ephemeral create`) are intentionally excluded from tombstone tracking.
**Wisps** (ephemeral issues created by `bd mol wisp`) are intentionally excluded from tombstone tracking.
### Why Wisps Don't Need Tombstones

16
docs/MOLECULES.md
View File

@@ -128,8 +128,8 @@ For reusable workflows, beads uses a chemistry metaphor:
### Phase Commands
```bash
bd pour <proto> # Proto → Mol (persistent instance)
bd ephemeral create <proto> # Proto → Wisp (ephemeral instance)
bd mol pour <proto> # Proto → Mol (persistent instance)
bd mol wisp <proto> # Proto → Wisp (ephemeral instance)
bd mol squash <id> # Mol/Wisp → Digest (permanent record)
bd mol burn <id> # Wisp → nothing (discard)
```
@@ -227,10 +227,10 @@ bd close <id> --reason "Done"
Wisps accumulate if not squashed/burned:
```bash
bd ephemeral list # Check for orphans
bd mol squash <id> # Create digest
bd mol burn <id> # Or discard
bd ephemeral gc # Garbage collect old wisps
bd mol wisp list # Check for orphans
bd mol squash <id> # Create digest
bd mol burn <id> # Or discard
bd mol wisp gc # Garbage collect old wisps
```
## Layer Cake Architecture
@@ -272,8 +272,8 @@ bd dep tree <id> # Show dependency tree
### Molecules
```bash
bd pour <proto> --var k=v # Template → persistent mol
bd ephemeral create <proto> # Template → ephemeral wisp
bd mol pour <proto> --var k=v # Template → persistent mol
bd mol wisp <proto> # Template → ephemeral wisp
bd mol bond A B # Connect work graphs
bd mol squash <id> # Compress to digest
bd mol burn <id> # Discard without record

24
skills/beads/references/MOLECULES.md
View File

@@ -83,8 +83,8 @@ bd mol spawn mol-release --var version=2.0 # With variable substitution
**Chemistry shortcuts:**
```bash
bd pour mol-feature # Shortcut for spawn --pour
bd ephemeral create mol-patrol # Explicit wisp creation
bd mol pour mol-feature # Shortcut for spawn --pour
bd mol wisp mol-patrol # Explicit wisp creation
```
### Spawn with Immediate Execution
@@ -164,7 +164,7 @@ bd mol bond mol-feature mol-deploy --as "Feature with Deploy"
### Creating Wisps
```bash
bd ephemeral create mol-patrol # From proto
bd mol wisp mol-patrol # From proto
bd mol spawn mol-patrol # Same (spawn defaults to wisp)
bd mol spawn mol-check --var target=db # With variables
```
@@ -172,8 +172,8 @@ bd mol spawn mol-check --var target=db # With variables
### Listing Wisps
```bash
bd ephemeral list # List all wisps
bd ephemeral list --json # Machine-readable
bd mol wisp list # List all wisps
bd mol wisp list --json # Machine-readable
```
### Ending Wisps
@@ -198,7 +198,7 @@ Use burn for routine work with no archival value.
### Garbage Collection
```bash
bd ephemeral gc # Clean up orphaned wisps
bd mol wisp gc # Clean up orphaned wisps
```
---
@@ -289,7 +289,7 @@ bd mol spawn mol-weekly-review --pour
```bash
# Patrol proto exists
bd ephemeral create mol-patrol
bd mol wisp mol-patrol
# Execute patrol work...
@@ -327,10 +327,10 @@ bd mol distill bd-release-epic --as "Release Process" --var version=X.Y.Z
| `bd mol distill <epic>` | Extract proto from ad-hoc work |
| `bd mol squash <mol>` | Compress wisp children to digest |
| `bd mol burn <wisp>` | Delete wisp without trace |
| `bd pour <proto>` | Shortcut for `spawn --pour` |
| `bd ephemeral create <proto>` | Create ephemeral wisp |
| `bd ephemeral list` | List all wisps |
| `bd ephemeral gc` | Garbage collect orphaned wisps |
| `bd mol pour <proto>` | Shortcut for `spawn --pour` |
| `bd mol wisp <proto>` | Create ephemeral wisp |
| `bd mol wisp list` | List all wisps |
| `bd mol wisp gc` | Garbage collect orphaned wisps |
| `bd ship <capability>` | Publish capability for cross-project deps |
---
@@ -347,7 +347,7 @@ bd mol distill bd-release-epic --as "Release Process" --var version=X.Y.Z
**"Wisp commands fail"**
- Wisps stored in `.beads-wisp/` (separate from `.beads/`)
- Check `bd ephemeral list` for active wisps
- Check `bd mol wisp list` for active wisps
**"External dependency not satisfied"**
- Target project must have closed issue with `provides:<capability>` label