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 { if len(bondPoints) > 0 {
fmt.Printf(" Bond points: %s\n", strings.Join(bondPoints, ", ")) 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 // cookFormulaResult holds the result of cooking

8
cmd/bd/mol_catalog.go
View File

@@ -23,7 +23,7 @@ var molCatalogCmd = &cobra.Command{
Use: "catalog", Use: "catalog",
Aliases: []string{"list", "ls"}, Aliases: []string{"list", "ls"},
Short: "List available molecule formulas", 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. Formulas are ephemeral proto definitions stored as .formula.json files.
They are cooked inline when pouring, never stored as database beads. 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("\nOr distill from existing work:")
fmt.Println(" bd mol distill <epic-id> my-workflow") fmt.Println(" bd mol distill <epic-id> my-workflow")
fmt.Println("\nTo instantiate from formula:") fmt.Println("\nTo instantiate from formula:")
fmt.Println(" bd pour <formula-name> --var key=value # persistent mol") fmt.Println(" bd mol pour <formula-name> --var key=value # persistent mol")
fmt.Println(" bd ephemeral create <formula-name> --var key=value # ephemeral wisp") fmt.Println(" bd mol wisp <formula-name> --var key=value # ephemeral wisp")
return 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 // Group by type for display
byType := make(map[string][]CatalogEntry) 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(".")
fmt.Println("\nTo start work on a molecule:") 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") fmt.Println(" bd update <step-id> --status in_progress # Claim a step")
return 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(" Variables: %s\n", strings.Join(result.Variables, ", "))
} }
fmt.Printf("\nTo instantiate:\n") 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 { for _, v := range result.Variables {
fmt.Printf(" --var %s=<value>", v) 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) │ │ (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 | | Phase | State | Storage | Command |
|-------|-------|---------|---------| |-------|-------|---------|---------|
| Solid | Proto | `.beads/` | `bd mol catalog` | | Solid | Proto | `.beads/` | `bd mol catalog` |
| Liquid | Mol | `.beads/` | `bd pour` | | Liquid | Mol | `.beads/` | `bd mol pour` |
| Vapor | Wisp | `.beads/` (Wisp=true, not exported) | `bd ephemeral create` | | Vapor | Wisp | `.beads/` (Ephemeral=true, not exported) | `bd mol wisp` |
### Proto/Template Commands ### Proto/Template Commands
@@ -370,32 +370,32 @@ bd mol distill <epic-id> --json
```bash ```bash
# Instantiate proto as persistent mol (solid → liquid) # 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 # 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 # 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 # Attach additional protos during pour
bd pour <proto-id> --attach <other-proto> --json bd mol pour <proto-id> --attach <other-proto> --json
``` ```
### Wisp Commands ### Wisp Commands
```bash ```bash
# Instantiate proto as ephemeral issue (solid → vapor) # Instantiate proto as ephemeral wisp (solid → vapor)
bd ephemeral create <proto-id> --var key=value --json bd mol wisp <proto-id> --var key=value --json
# List all wisps # List all wisps
bd ephemeral list --json bd mol wisp list --json
bd ephemeral list --all --json # Include closed bd mol wisp list --all --json # Include closed
# Garbage collect orphaned wisps # Garbage collect orphaned wisps
bd ephemeral gc --json bd mol wisp gc --json
bd ephemeral gc --age 24h --json # Custom age threshold bd mol wisp gc --age 24h --json # Custom age threshold
bd ephemeral gc --dry-run # Preview what would be cleaned bd mol wisp gc --dry-run # Preview what would be cleaned
``` ```
### Bonding (Combining Work) ### 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: 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 ### 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 ### Phase Commands
```bash ```bash
bd pour <proto> # Proto → Mol (persistent instance) bd mol pour <proto> # Proto → Mol (persistent instance)
bd ephemeral create <proto> # Proto → Wisp (ephemeral instance) bd mol wisp <proto> # Proto → Wisp (ephemeral instance)
bd mol squash <id> # Mol/Wisp → Digest (permanent record) bd mol squash <id> # Mol/Wisp → Digest (permanent record)
bd mol burn <id> # Wisp → nothing (discard) bd mol burn <id> # Wisp → nothing (discard)
``` ```
@@ -227,10 +227,10 @@ bd close <id> --reason "Done"
Wisps accumulate if not squashed/burned: Wisps accumulate if not squashed/burned:
```bash ```bash
bd ephemeral list # Check for orphans bd mol wisp list # Check for orphans
bd mol squash <id> # Create digest bd mol squash <id> # Create digest
bd mol burn <id> # Or discard bd mol burn <id> # Or discard
bd ephemeral gc # Garbage collect old wisps bd mol wisp gc # Garbage collect old wisps
``` ```
## Layer Cake Architecture ## Layer Cake Architecture
@@ -272,8 +272,8 @@ bd dep tree <id> # Show dependency tree
### Molecules ### Molecules
```bash ```bash
bd pour <proto> --var k=v # Template → persistent mol bd mol pour <proto> --var k=v # Template → persistent mol
bd ephemeral create <proto> # Template → ephemeral wisp bd mol wisp <proto> # Template → ephemeral wisp
bd mol bond A B # Connect work graphs bd mol bond A B # Connect work graphs
bd mol squash <id> # Compress to digest bd mol squash <id> # Compress to digest
bd mol burn <id> # Discard without record 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:** **Chemistry shortcuts:**
```bash ```bash
bd pour mol-feature # Shortcut for spawn --pour bd mol pour mol-feature # Shortcut for spawn --pour
bd ephemeral create mol-patrol # Explicit wisp creation bd mol wisp mol-patrol # Explicit wisp creation
``` ```
### Spawn with Immediate Execution ### Spawn with Immediate Execution
@@ -164,7 +164,7 @@ bd mol bond mol-feature mol-deploy --as "Feature with Deploy"
### Creating Wisps ### Creating Wisps
```bash ```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-patrol # Same (spawn defaults to wisp)
bd mol spawn mol-check --var target=db # With variables 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 ### Listing Wisps
```bash ```bash
bd ephemeral list # List all wisps bd mol wisp list # List all wisps
bd ephemeral list --json # Machine-readable bd mol wisp list --json # Machine-readable
``` ```
### Ending Wisps ### Ending Wisps
@@ -198,7 +198,7 @@ Use burn for routine work with no archival value.
### Garbage Collection ### Garbage Collection
```bash ```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 ```bash
# Patrol proto exists # Patrol proto exists
bd ephemeral create mol-patrol bd mol wisp mol-patrol
# Execute patrol work... # 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 distill <epic>` | Extract proto from ad-hoc work |
| `bd mol squash <mol>` | Compress wisp children to digest | | `bd mol squash <mol>` | Compress wisp children to digest |
| `bd mol burn <wisp>` | Delete wisp without trace | | `bd mol burn <wisp>` | Delete wisp without trace |
| `bd pour <proto>` | Shortcut for `spawn --pour` | | `bd mol pour <proto>` | Shortcut for `spawn --pour` |
| `bd ephemeral create <proto>` | Create ephemeral wisp | | `bd mol wisp <proto>` | Create ephemeral wisp |
| `bd ephemeral list` | List all wisps | | `bd mol wisp list` | List all wisps |
| `bd ephemeral gc` | Garbage collect orphaned wisps | | `bd mol wisp gc` | Garbage collect orphaned wisps |
| `bd ship <capability>` | Publish capability for cross-project deps | | `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"** **"Wisp commands fail"**
- Wisps stored in `.beads-wisp/` (separate from `.beads/`) - 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"** **"External dependency not satisfied"**
- Target project must have closed issue with `provides:<capability>` label - Target project must have closed issue with `provides:<capability>` label