From 7f77491080c7dfe2d73e1715cdf2ef3b50a8915d Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Sat, 27 Dec 2025 14:47:21 -0800
Subject: [PATCH] docs: Clarify gt mol vs bd mol command distinction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Update reference.md to explain the separation:
- bd mol: beads data operations (list, show, pour, wisp, bond)
- gt mol: agent operations (status, current, attach, burn, squash)

Key clarification: gt mol burn/squash operate on current agent's
attached molecule (auto-detected), while bd mol burn/squash take
explicit molecule IDs.

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 docs/reference.md | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/docs/reference.md b/docs/reference.md
index 207dc361..13057a09 100644
--- a/docs/reference.md
+++ b/docs/reference.md
@@ -121,22 +121,47 @@ persisted to JSONL. They exist only in memory during execution.
 
 ## Molecule Commands
 
+**Principle**: `bd` = beads data operations, `gt` = agent operations.
+
+### Beads Operations (bd)
+
 ```bash
 # Formulas
 bd formula list              # Available formulas
 bd formula show <name>       # Formula details
 bd cook <formula>            # Formula → Proto
 
-# Molecules
+# Molecules (data operations)
 bd mol list                  # Available protos
 bd mol show <id>             # Proto details
 bd mol pour <proto>          # Create mol
 bd mol wisp <proto>          # Create wisp
 bd mol bond <proto> <parent> # Attach to existing mol
-bd mol squash <id>           # Condense to digest
-bd mol burn <id>             # Discard wisp
+bd mol squash <id>           # Condense to digest (explicit ID)
+bd mol burn <id>             # Discard wisp (explicit ID)
 ```
 
+### Agent Operations (gt)
+
+```bash
+# Hook management (operates on current agent's hook)
+gt mol status                # What's on MY hook
+gt mol current               # What should I work on next
+gt mol progress <id>         # Execution progress of molecule
+gt mol attach <bead> <mol>   # Pin molecule to bead
+gt mol detach <bead>         # Unpin molecule from bead
+gt mol attach-from-mail <id> # Attach from mail message
+
+# Agent lifecycle (operates on agent's attached molecule)
+gt mol burn                  # Burn attached molecule (no ID needed)
+gt mol squash                # Squash attached molecule (no ID needed)
+gt mol step done <step>      # Complete a molecule step
+```
+
+**Key distinction**: `bd mol burn/squash <id>` take explicit molecule IDs.
+`gt mol burn/squash` operate on the current agent's attached molecule
+(auto-detected from working directory).
+
 ## Agent Lifecycle
 
 ### Polecat Shutdown