docs: Update docs to reflect molecule-first paradigm (gt-nam3)

- Add molecule-first paradigm note at top of architecture.md
- Update all spawn examples to include --molecule flag
- Add "Config vs Molecule" section with cognition principle
- Add policy-to-molecule escalation note in federation-design.md
- Update role templates (mayor, witness) with molecule usage

Key message: Gas Town spawns workers on molecules, not just issues.
The issue is seed data; the molecule defines the workflow.

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

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

docs/architecture.md

@@ -4,6 +4,8 @@ Gas Town is a multi-agent workspace manager that coordinates AI coding agents wo
 
 **Key insight**: Work is a stream, not discrete batches. The Refinery's merge queue is the coordination mechanism. Beads (issues) are the data plane. There are no "swarm IDs" - just epics with children, processed by workers, merged through the queue.
 
+**Molecule-first paradigm**: Gas Town is fundamentally a molecule execution engine. Workers don't just "work on issues" - they execute molecules. The issue is seed data; the molecule defines the workflow. This enables nondeterministic idempotence: any worker can pick up where another left off, surviving crashes, context compaction, and restarts. If a process requires cognition, it should be a molecule. See [Molecules](#molecules-composable-workflow-templates) for full details.
+
 ## System Overview
 
 ```mermaid
@@ -427,6 +429,43 @@ Both use similar structures but different semantics:
 - Templates focus on parameterization (`{{variable}}` substitution)
 - Molecules focus on execution (step states, nondeterministic dispatch)
 
+### Config vs Molecule: When to Use Which
+
+**The Key Principle: If it requires cognition, it's a molecule.**
+
+| Use Case | Config | Molecule |
+|----------|--------|----------|
+| Static policy (max workers, timeouts) | ✅ | ❌ |
+| Agent workflow (design → implement → test) | ❌ | ✅ |
+| Outpost routing preferences | ✅ | ❌ |
+| Error recovery with decisions | ❌ | ✅ |
+| Environment variables | ✅ | ❌ |
+| Multi-step processes that can fail | ❌ | ✅ |
+
+**Config** (`config.json`, `outposts.yaml`):
+- Declarative settings
+- No decision-making required
+- Read once at startup
+- Changes require restart
+
+**Molecules**:
+- Procedural workflows
+- Require agent cognition at each step
+- Survive agent restarts
+- Track progress through step states
+
+**Example: Outpost Assignment**
+
+Static policy in `outposts.yaml`:
+```yaml
+policy:
+  default_preference: [local, gce-burst, cloudrun-burst]
+```
+
+But if assignment requires cognition (analyzing work characteristics, checking outpost health, making tradeoffs), escalate to a molecule like `mol-outpost-assign`.
+
+**The insight**: Gas Town doesn't spawn workers on issues. It spawns workers on molecules. The issue is just the seed data for the molecule execution.
+
 ### Operational Molecules
 
 Molecules aren't just for implementing features. Any multi-step process that requires cognition, can fail partway through, or needs to survive agent restarts should be a molecule.
@@ -1591,7 +1630,7 @@ gt capture <polecat> "<cmd>"     # Run command in polecat session
 ### Session Management
 
 ```bash
-gt spawn --issue <id>  # Start polecat on issue (creates fresh worktree)
+gt spawn --issue <id> --molecule mol-engineer-in-box  # Spawn polecat with workflow
 gt handoff             # Polecat requests shutdown (run when done)
 gt session stop <p>    # Kill polecat session (Witness uses this)
 ```

docs/bootstrap.md

@@ -221,4 +221,4 @@ echo "Bootstrap complete!"
 After bootstrapping:
 1. Start a Mayor session: `gt mayor attach`
 2. Check for work: `bd ready`
-3. Spawn workers as needed: `gt spawn --issue <id>`
+3. Spawn workers with molecules: `gt spawn --issue <id> --molecule mol-engineer-in-box`

docs/federation-design.md

@@ -394,6 +394,8 @@ policy:
       prefer: gce-worker-1
 ```
 
+**When policy becomes a molecule**: Static policy handles simple preference-based routing. But when assignment requires cognition - analyzing work characteristics, checking outpost health in real-time, making cost/speed tradeoffs, or handling degraded outposts - escalate to `mol-outpost-assign`. The policy file declares preferences; the molecule executes intelligent assignment. See [Config vs Molecule](architecture.md#config-vs-molecule-when-to-use-which) for the general principle.
+
 ## Implementation Phases
 
 ### Phase 1: Outpost Abstraction (Local)

internal/templates/roles/mayor.md.tmpl

@@ -53,7 +53,7 @@ Town ({{ .TownRoot }})
 ### Work Management
 - `bd ready` - Issues ready to work (no blockers)
 - `bd list --status=open` - All open issues
-- `gt spawn --issue <id>` - Start polecat on issue
+- `gt spawn --issue <id> --molecule <mol>` - Spawn polecat with molecule workflow
 
 ### Delegation
 Prefer delegating to Refineries, not directly to polecats: