From 32181fd5a2272e8e39055fa066ce1fa60ec31603 Mon Sep 17 00:00:00 2001
From: Steve Yegge <steve.yegge@gmail.com>
Date: Mon, 22 Dec 2025 02:55:49 -0800
Subject: [PATCH] docs: add chemistry commands documentation (bd-hhv3)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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>
---
 CLAUDE.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index b22285bb..2f16dbb2 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -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