docs: Propagate Rig/Cook/Run lifecycle terminology

Updated the following docs to reference the Rig/Cook/Run lifecycle:
- propulsion-principle.md: Added lifecycle overview, updated steam metaphor table
- sling-design.md: Added see-also reference to molecular-chemistry.md
- molecules.md: Added lifecycle summary diagram, formula context
- architecture.md: Added Rig/Cook/Run overview, added Formula to concepts table

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

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

docs/architecture.md

@@ -364,11 +364,19 @@ composable, nondeterministic-idempotent workflow templates**. They encode struct
 workflows that any worker can execute, with full auditability and the ability for
 any worker to pick up where another left off.
 
+Work flows through the **Rig → Cook → Run** lifecycle:
+- **Rig**: Compose workflow formulas (YAML source files with `extends`, `compose`)
+- **Cook**: Transform formulas into executable protos (`bd cook` expands macros, applies aspects)
+- **Run**: Agents execute the cooked workflow (pour creates mols, wisp creates ephemeral traces)
+
+See [molecular-chemistry.md](molecular-chemistry.md) for the full lifecycle specification.
+
 ### Core Concepts
 
 | Concept | Name | Description |
 |---------|------|-------------|
-| Template | **Proto Molecule** | Read-only workflow pattern (the "fuel") |
+| Source | **Formula** | YAML workflow definition with composition rules (.formula.yaml) |
+| Template | **Proto Molecule** | Cooked workflow pattern (the "fuel") |
 | Running execution | **Wisp Molecule** | Transient execution trace (the "steam") |
 | Permanent record | **Digest** | Compressed summary of completed work (the "distillate") |
 | Individual step | **Atom/Step** | Smallest unit of work within a molecule |

docs/molecules.md

@@ -3,6 +3,7 @@
 This document covers the molecule system in depth.
 
 For an overview, see [architecture.md](architecture.md#molecules-composable-workflow-templates).
+For the full lifecycle (Rig → Cook → Run), see [molecular-chemistry.md](molecular-chemistry.md).
 
 ## Core Concepts
 
@@ -264,30 +265,29 @@ bd mol bond mol-code-review --var scope="src/"
 
 ## Lifecycle Summary
 
+Gas Town work follows the **Rig → Cook → Run** lifecycle:
+
 ```
-┌─────────────┐
+           RIG (source)              COOK (artifact)           RUN (execution)
-│   Proto     │  Template in molecules.jsonl
+      ┌─────────────────┐       ┌─────────────────┐       ┌─────────────────┐
-│  (frozen)   │  labels: ["template"]
+      │    Formula      │──────►│     Proto       │──────►│   Mol/Wisp      │
-└──────┬──────┘
+      │   (.yaml)       │ cook  │  (cooked/frozen)│ pour/ │   (flowing)     │
-       │
+      │                 │       │                 │ wisp  │                 │
-       ▼ bd mol bond [--wisp]
+      └─────────────────┘       └─────────────────┘       └────────┬────────┘
-┌─────────────┐
+                                                                   │
-│  Mol/Wisp   │  Active execution
+                                                              ┌────┴────┐
-│ (flowing)   │  Mol: .beads/ | Wisp: .beads-wisp/
+                                                              ▼         ▼
-└──────┬──────┘
+                                                            burn      squash
-       │
+                                                              │         │
-  ┌────┴────┐
+                                                              ▼         ▼
-  ▼         ▼
+                                                           (gone)   Digest
-burn      squash
+                                                                   (permanent)
-  │         │
-  ▼         ▼
-(gone)   Digest
-         (permanent)
 ```
 
-**Steam engine metaphor:**
+**Full lifecycle:**
-- Proto = Fuel (potential energy)
+- **Formula** (.formula.yaml) = Recipe (source code for workflows)
-- Mol/Wisp = Steam (kinetic energy)
+- **Proto** = Fuel (cooked template, ready to instantiate)
-- Digest = Distillate (crystallized work)
+- **Mol/Wisp** = Steam (active execution)
-- Burn = Steam dissipates
+- **Digest** = Distillate (crystallized work)
-- Squash = Steam condenses
+
+See [molecular-chemistry.md](molecular-chemistry.md) for the complete specification.

docs/propulsion-principle.md

@@ -2,6 +2,7 @@
 
 > **Status**: Design document (experimental)
 > **See also**: [sling-design.md](sling-design.md) for implementation details
+> **See also**: [molecular-chemistry.md](molecular-chemistry.md) for the full Rig/Cook/Run lifecycle
 
 ## The Core Idea
 
@@ -36,14 +37,19 @@ Stateless agents can:
 
 ### 2. Work Is Molecule-Driven
 
-All work in Gas Town is encoded in **molecules** - crystallized workflow patterns
+All work in Gas Town follows the **Rig → Cook → Run** lifecycle:
-stored as beads. A molecule defines:
+- **Rig**: Compose workflow formulas (YAML source files)
+- **Cook**: Transform formulas into executable protos (expand macros, apply aspects)
+- **Run**: Agents execute the cooked workflow
+
+A molecule (proto, mol, or wisp) defines:
 - What steps need to happen
 - What order they happen in (via dependencies)
 - What each step should accomplish
 
 The agent doesn't decide what to do. The molecule tells it. The agent's job is
-execution, not planning.
+execution, not planning. See [molecular-chemistry.md](molecular-chemistry.md)
+for the full lifecycle.
 
 ### 3. Hooks Deliver Work
 
@@ -60,7 +66,8 @@ it's your work. Run it.
 
 ## The Sling Lifecycle
 
-The **sling** operation puts work on an agent's hook. Here's the full lifecycle:
+The **sling** operation puts work on an agent's hook. This is the **Run** phase
+of the Rig → Cook → Run lifecycle (formulas have already been cooked into protos):
 
 ```
 ┌─────────────────────────────────────────────────────────┐
@@ -68,11 +75,11 @@ The **sling** operation puts work on an agent's hook. Here's the full lifecycle:
 ├─────────────────────────────────────────────────────────┤
 │                                                          │
 │  1. POUR (if proto)      2. ASSIGN           3. PIN     │
-│     proto → molecule        mol → agent         → hook  │
+│     proto → mol/wisp        mol → agent         → hook  │
 │                                                          │
 │  ┌─────────┐            ┌─────────┐        ┌─────────┐  │
-│  │  Proto  │ ────────►  │Molecule │ ─────► │  Hook   │  │
+│  │  Proto  │ ────────►  │Mol/Wisp │ ─────► │  Hook   │  │
-│  │(catalog)│   pour     │(instance)│ assign │(pinned) │  │
+│  │(cooked) │   pour     │(instance)│ assign │(pinned) │  │
 │  └─────────┘            └─────────┘        └─────────┘  │
 │                                                  │       │
 │                                            agent wakes   │
@@ -84,6 +91,9 @@ The **sling** operation puts work on an agent's hook. Here's the full lifecycle:
 └─────────────────────────────────────────────────────────┘
 ```
 
+**Pour** instantiates a proto into a running mol (persistent) or wisp (ephemeral).
+This is a phase transition from the Cook output to the Run phase.
+
 **Key insight**: The agent never decides *whether* to run. The molecule tells
 it *what* to do. It executes until complete, then checks the hook again.
 
@@ -125,15 +135,17 @@ situation and make decisions. The new way requires only execution.
 
 ## The Steam Engine Metaphor
 
-Gas Town uses steam engine vocabulary throughout:
+Gas Town uses steam engine vocabulary throughout. The full lifecycle is
+**Rig → Cook → Run**:
 
-| Metaphor | Gas Town | Description |
+| Metaphor | Gas Town | Lifecycle Phase | Description |
-|----------|----------|-------------|
+|----------|----------|-----------------|-------------|
-| **Fuel** | Proto molecules | Templates that define workflows |
+| **Recipe** | Formulas | Rig (source) | YAML files that compose workflows |
-| **Steam** | Wisps/Mols | Active execution traces |
+| **Fuel** | Proto molecules | Cook (artifact) | Cooked templates ready to instantiate |
-| **Distillate** | Digests | Condensed permanent records |
+| **Steam** | Wisps/Mols | Run (execution) | Active execution traces |
-| **Burn** | `bd mol burn` | Discard without record |
+| **Distillate** | Digests | (post-Run) | Condensed permanent records |
-| **Squash** | `bd mol squash` | Compress into digest |
+| **Burn** | `bd mol burn` | (post-Run) | Discard without record |
+| **Squash** | `bd mol squash` | (post-Run) | Compress into digest |
 
 Claude is fire. Claude Code is a Steam engine. Gas Town is a Steam Train, with
 Beads as the tracks. Wisps are steam vapors that dissipate after work is done.

docs/sling-design.md

@@ -2,6 +2,7 @@
 
 > **Status**: Implemented
 > **Updated**: 2024-12-24
+> **See also**: [molecular-chemistry.md](molecular-chemistry.md) for the full Rig → Cook → Run lifecycle
 
 ## The Propulsion Principle (GUPP)
 
@@ -187,5 +188,6 @@ gt mol status
 ## See Also
 
 - `docs/propulsion-principle.md` - GUPP design
+- `docs/molecular-chemistry.md` - Full Rig/Cook/Run lifecycle (formulas → protos → mols/wisps)
 - `docs/wisp-architecture.md` - Ephemeral wisps for patrol loops
 - `internal/wisp/` - Hook storage implementation