From 15cfef024748e9e473843724a0d63f7528a30edf Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Fri, 26 Dec 2025 23:52:50 -0800 Subject: [PATCH] Update documentation for bd mol pour/wisp command structure MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- cmd/bd/cook.go | 2 +- cmd/bd/mol_catalog.go | 8 ++++---- cmd/bd/mol_current.go | 2 +- cmd/bd/mol_distill.go | 2 +- docs/ARCHITECTURE.md | 2 +- docs/CLI_REFERENCE.md | 26 +++++++++++++------------- docs/DELETIONS.md | 2 +- docs/MOLECULES.md | 16 ++++++++-------- skills/beads/references/MOLECULES.md | 24 ++++++++++++------------ 9 files changed, 42 insertions(+), 42 deletions(-) diff --git a/cmd/bd/cook.go b/cmd/bd/cook.go index c2fa4652..3d19ef68 100644 --- a/cmd/bd/cook.go +++ b/cmd/bd/cook.go @@ -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 =\n", result.ProtoID) + fmt.Printf("\nTo use: bd mol pour %s --var =\n", result.ProtoID) } // cookFormulaResult holds the result of cooking diff --git a/cmd/bd/mol_catalog.go b/cmd/bd/mol_catalog.go index d2acdf36..1b5f4577 100644 --- a/cmd/bd/mol_catalog.go +++ b/cmd/bd/mol_catalog.go @@ -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 my-workflow") fmt.Println("\nTo instantiate from formula:") - fmt.Println(" bd pour --var key=value # persistent mol") - fmt.Println(" bd ephemeral create --var key=value # ephemeral wisp") + fmt.Println(" bd mol pour --var key=value # persistent mol") + fmt.Println(" bd mol wisp --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) diff --git a/cmd/bd/mol_current.go b/cmd/bd/mol_current.go index 95a6651f..75e2f07b 100644 --- a/cmd/bd/mol_current.go +++ b/cmd/bd/mol_current.go @@ -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 # Instantiate a molecule from template") + fmt.Println(" bd mol pour # Instantiate a molecule from template") fmt.Println(" bd update --status in_progress # Claim a step") return } diff --git a/cmd/bd/mol_distill.go b/cmd/bd/mol_distill.go index 49e5f834..e07fbd7d 100644 --- a/cmd/bd/mol_distill.go +++ b/cmd/bd/mol_distill.go @@ -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=", v) } diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 09ba38f1..ce2e4ff8 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -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) │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md index 3d4170da..f5b7513c 100644 --- a/docs/CLI_REFERENCE.md +++ b/docs/CLI_REFERENCE.md @@ -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 --json ```bash # Instantiate proto as persistent mol (solid → liquid) -bd pour --var key=value --json +bd mol pour --var key=value --json # Preview what would be created -bd pour --var key=value --dry-run +bd mol pour --var key=value --dry-run # Assign root issue -bd pour --var key=value --assignee alice --json +bd mol pour --var key=value --assignee alice --json # Attach additional protos during pour -bd pour --attach --json +bd mol pour --attach --json ``` ### Wisp Commands ```bash -# Instantiate proto as ephemeral issue (solid → vapor) -bd ephemeral create --var key=value --json +# Instantiate proto as ephemeral wisp (solid → vapor) +bd mol wisp --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) diff --git a/docs/DELETIONS.md b/docs/DELETIONS.md index ef4086e6..4fd55d97 100644 --- a/docs/DELETIONS.md +++ b/docs/DELETIONS.md @@ -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 diff --git a/docs/MOLECULES.md b/docs/MOLECULES.md index 132f33fb..172cb178 100644 --- a/docs/MOLECULES.md +++ b/docs/MOLECULES.md @@ -128,8 +128,8 @@ For reusable workflows, beads uses a chemistry metaphor: ### Phase Commands ```bash -bd pour # Proto → Mol (persistent instance) -bd ephemeral create # Proto → Wisp (ephemeral instance) +bd mol pour # Proto → Mol (persistent instance) +bd mol wisp # Proto → Wisp (ephemeral instance) bd mol squash # Mol/Wisp → Digest (permanent record) bd mol burn # Wisp → nothing (discard) ``` @@ -227,10 +227,10 @@ bd close --reason "Done" Wisps accumulate if not squashed/burned: ```bash -bd ephemeral list # Check for orphans -bd mol squash # Create digest -bd mol burn # Or discard -bd ephemeral gc # Garbage collect old wisps +bd mol wisp list # Check for orphans +bd mol squash # Create digest +bd mol burn # Or discard +bd mol wisp gc # Garbage collect old wisps ``` ## Layer Cake Architecture @@ -272,8 +272,8 @@ bd dep tree # Show dependency tree ### Molecules ```bash -bd pour --var k=v # Template → persistent mol -bd ephemeral create # Template → ephemeral wisp +bd mol pour --var k=v # Template → persistent mol +bd mol wisp # Template → ephemeral wisp bd mol bond A B # Connect work graphs bd mol squash # Compress to digest bd mol burn # Discard without record diff --git a/skills/beads/references/MOLECULES.md b/skills/beads/references/MOLECULES.md index 95d35314..4312511d 100644 --- a/skills/beads/references/MOLECULES.md +++ b/skills/beads/references/MOLECULES.md @@ -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 ` | Extract proto from ad-hoc work | | `bd mol squash ` | Compress wisp children to digest | | `bd mol burn ` | Delete wisp without trace | -| `bd pour ` | Shortcut for `spawn --pour` | -| `bd ephemeral create ` | Create ephemeral wisp | -| `bd ephemeral list` | List all wisps | -| `bd ephemeral gc` | Garbage collect orphaned wisps | +| `bd mol pour ` | Shortcut for `spawn --pour` | +| `bd mol wisp ` | Create ephemeral wisp | +| `bd mol wisp list` | List all wisps | +| `bd mol wisp gc` | Garbage collect orphaned wisps | | `bd ship ` | 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:` label