docs: clarify pinned molecule vs handoff mail distinction

Two mechanisms, different purposes:
- Pinned molecule (bd mol run) = What you are working on, tracked by beads
- Handoff mail = Optional context notes for session restarts

Updated templates, architecture.md, and builtin_molecules.go

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

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

docs/architecture.md

@@ -754,8 +754,8 @@ Submit to merge queue. Create PR if needed.
 Verify CI passes.
 Needs: rebase-main
 
-## Step: update-handoff
-Update handoff bead with final state.
+## Step: generate-summary
+Generate summary for molecule squash.
 File any remaining work as issues.
 Needs: submit-merge
 
@@ -817,8 +817,8 @@ Graceful shutdown with handoff preservation.
 Send shutdown notification to all agents.
 Record which agents acknowledged.
 
-## Step: wait-handoffs
-Wait for agents to update handoff beads.
+## Step: wait-squash
+Wait for agents to squash their molecules.
 Track completion status.
 Needs: notify-agents
 

internal/beads/builtin_molecules.go

@@ -375,11 +375,11 @@ gt done  # Signal work ready for merge queue
 If there are CI failures, fix them before proceeding.
 Needs: rebase-main
 
-## Step: update-handoff
-Update handoff bead with final state.
+## Step: generate-summary
+Generate a summary for molecule squash.
 File any remaining work as issues.
 
-Document any important context for the next session
+Document any important context for the squash digest
 or for anyone reviewing the work.
 Needs: submit-merge
 
@@ -389,7 +389,7 @@ Wait for termination.
 
 The polecat is now ready to be cleaned up.
 Do not exit directly - wait for Witness to kill the session.
-Needs: update-handoff`,
+Needs: generate-summary`,
 	}
 }
 

internal/templates/roles/crew.md.tmpl

@@ -105,24 +105,26 @@ If push fails (someone else pushed): `git pull --rebase && git push`
 
 ## Context Cycling (Handoff)
 
-When your context fills up, cycle to a fresh session:
+When your context fills up, cycle to a fresh session.
+
+**Two mechanisms, different purposes:**
+- **Pinned molecule** = What you're working on (tracked by beads, survives restarts)
+- **Handoff mail** = Context notes for yourself (optional, for nuances the molecule doesn't capture)
+
+Your work state is in beads. Handoff mail is just for extra context:
 
 ```bash
-gt mail send {{ .RigName }}/crew/{{ .Polecat }} -s "🤝 HANDOFF: Work in progress" -m "
-## Current State
-Working on: <issue-id or description>
-Status: <what's done, what remains>
-
-## Next Steps
-1. <first thing to do>
-2. <second thing to do>
-
-## Notes
-<any important context>
+# Optional: send yourself context notes
+gt mail send {{ .RigName }}/crew/{{ .Polecat }} -s "🤝 HANDOFF: Context notes" -m "
+Was debugging the auth flow, found the issue is in token refresh.
+Check line 145 in auth.go first.
 "
 ```
 
-Then end your session. The next session will see this message in its inbox.
+When you restart, find your work:
+```bash
+bd list --pinned --assignee={{ .RigName }}/crew/{{ .Polecat }} --status=in_progress
+```
 
 ## Session End Checklist
 

internal/templates/roles/deacon.md.tmpl

@@ -47,18 +47,19 @@ You wake up when:
 
 When you wake, follow this protocol:
 
-### 1. Check for Attached Molecule
+### 1. Find Your Current Work
 ```bash
-gt mol status                # Shows current molecule attachment
-bd list --status=in_progress --assignee=deacon
+bd list --pinned --assignee=deacon --status=in_progress
 ```
 
-If you have an attached molecule, **resume from the current step**.
-If no molecule attached, **bond a new patrol molecule**:
+If you have a pinned molecule, **resume from the current step**.
+If no molecule (naked), **start a new patrol**:
 ```bash
-gt mol bond mol-deacon-patrol
+bd mol run mol-deacon-patrol
 ```
 
+This spawns the patrol molecule, assigns it to you, pins it, and sets status to in_progress.
+
 ### 2. Execute Current Step
 
 The `mol-deacon-patrol` steps are:
@@ -104,15 +105,15 @@ bd ready                     # Check for next step
 ### 4. Loop or Exit
 
 At the end of each patrol cycle:
-- **Low context**: `gt mol burn` → `gt mol bond mol-deacon-patrol` → repeat
-- **High context**: `gt mol burn` → exit cleanly (daemon respawns you)
+- **Low context**: `bd mol squash` → `bd mol run mol-deacon-patrol` → repeat
+- **High context**: `bd mol squash` → exit cleanly (daemon respawns you)
 
 ```bash
-# Burn the wisp (routine work, no audit needed)
-gt mol burn
+# Complete the patrol (squash generates summary, cleans up)
+bd mol squash <mol-id> --summary="Patrol complete: checked inbox, scanned health, no issues"
 
-# Option A: Loop
-gt mol bond mol-deacon-patrol
+# Option A: Loop (low context)
+bd mol run mol-deacon-patrol
 # Continue to inbox-check...
 
 # Option B: Exit (high context)
@@ -193,28 +194,28 @@ If you can't fix an issue after 3 attempts:
 
 ## Startup Protocol
 
-1. Check for attached molecule: `bd list --status=in_progress --assignee=deacon`
-2. If attached, **resume** from current step (you were mid-patrol)
-3. If not attached, **bond** a new patrol: `gt mol bond mol-deacon-patrol`
+1. Find your work: `bd list --pinned --assignee=deacon --status=in_progress`
+2. If you have a pinned molecule, **resume** from current step (you were mid-patrol)
+3. If naked (no pinned molecule), **start** a new patrol: `bd mol run mol-deacon-patrol`
 4. Execute patrol steps until loop-or-exit
-5. At loop-or-exit: burn molecule, then loop or exit based on context
+5. At loop-or-exit: squash molecule, then loop or exit based on context
 
 ## Handoff (Molecule-Based)
 
 The Deacon uses **nondeterministic idempotence** for handoff:
 
 1. Molecule state is in beads (survives session restarts)
-2. On respawn, check `bd list --status=in_progress` to find current step
-3. Resume from that step - no explicit handoff message needed
+2. On respawn, query `bd list --pinned --assignee=deacon` to find current work
+3. Resume from the next unclosed step - no explicit handoff message needed
 
 If you need to exit mid-patrol (high context):
 ```bash
-gt mol burn                  # Clean up wisp state
+bd mol squash <mol-id> --summary="Exiting mid-patrol due to context limit"
 # Just exit - daemon respawns with fresh context
-# New session will bond a fresh patrol molecule
+# New session will run a fresh patrol molecule
 ```
 
-The patrol molecule ensures continuity without handoff messages.
+The pinned molecule ensures continuity. Handoff mail is only for optional context notes.
 
 ---
 

internal/templates/roles/polecat.md.tmpl

@@ -77,23 +77,41 @@ Agent-friendly UX is critical. Your guesses reveal what's intuitive.
 
 When your session starts, follow this protocol:
 
-1. **Run `gt prime`** - This loads your context and checks for mail automatically
-2. **Check your inbox** - If `gt prime` shows mail, read it with `gt mail read <id>`
-3. **Look for work assignment** - Messages with "📋 Work Assignment" contain your task
-4. **If no mail** - Check `bd list --status=in_progress` for existing assignments
+1. **Run `gt prime`** - This loads your context and checks for mail
+2. **Find your work molecule**:
+   ```bash
+   bd list --pinned --assignee={{ .RigName }}/{{ .Polecat }} --status=in_progress
+   ```
+3. **If you have a pinned molecule** - Resume from the next unclosed step
+4. **If no molecule** - Check inbox for work assignment (`gt mail inbox`)
 5. **Otherwise** - Wait for instructions from the Witness or Mayor
 
-Work assignments are delivered to your inbox rather than injected into your session,
-ensuring persistence across session restarts and providing an audit trail.
+Your work is tracked as a **pinned molecule** (created by `bd mol run` when you were spawned).
+This survives session restarts - just query for your pinned work to continue.
 
 ## Work Protocol
 
-1. **Start**: Read your work assignment from mail, or `bd show <assigned-issue>`
-2. **Work**: Implement the solution in your clone
-3. **Commit**: Regular commits with clear messages
-4. **Test**: Verify your changes work
-5. **Close**: `bd close <issue>` when done
-6. **Signal**: `gt done` to submit to merge queue
+Your work follows the **mol-polecat-work** molecule steps:
+
+1. **load-context** - Run `gt prime`, read your assignment
+2. **implement** - Write the solution, make commits
+3. **self-review** - Check for bugs, style issues
+4. **verify-tests** - Run tests, fix any failures
+5. **rebase-main** - Rebase on origin/main
+6. **submit-merge** - Run `gt done` to submit to merge queue
+7. **generate-summary** - Write a summary of what you did
+8. **request-shutdown** - Signal done, Witness cleans you up
+
+As you complete each step, close it:
+```bash
+bd close <step-id>
+bd ready --parent=<mol-id>  # See next step
+```
+
+When finished, squash the molecule:
+```bash
+bd mol squash <mol-id> --summary="Implemented X, tests pass, ready for merge"
+```
 
 ## Before Signaling Done