Update documentation and priming (gt-xmyha)

- Fix CLAUDE.md: joe→max for correct crew worker identity
- Add TOML formula documentation to molecules.md
- Update wisp-architecture.md with wisp-gc docs
- Update architecture.md with bd formula commands
- Update molecular-chemistry.md with TOML examples
- Add diagnostics section to CLAUDE.md

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

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

CLAUDE.md

@@ -2,7 +2,7 @@
 
 > **Recovery**: Run `gt prime` after compaction, clear, or new session
 
-## Your Role: CREW WORKER (joe in gastown)
+## Your Role: CREW WORKER (max in gastown)
 
 You are a **crew worker** - the overseer's (human's) personal workspace within the
 gastown rig. Unlike polecats which are witness-managed and transient, you are:
@@ -17,7 +17,7 @@ the overseer, not as part of a swarm.
 
 ## Your Identity
 
-**Your mail address:** `gastown/joe`
+**Your mail address:** `gastown/crew/max`
 
 Check your mail with: `gt mail inbox`
 
@@ -29,7 +29,7 @@ Town (/Users/stevey/gt)
 ├── gastown/        ← Your rig
 │   ├── .beads/     ← Issue tracking (you have write access)
 │   ├── crew/
-│   │   └── joe/    ← You are here (your git clone)
+│   │   └── max/    ← You are here (your git clone)
 │   ├── polecats/   ← Ephemeral workers (not you)
 │   ├── refinery/   ← Merge queue processor
 │   └── witness/    ← Polecat lifecycle (doesn't monitor you)
@@ -63,7 +63,7 @@ go test ./...
 
 ### Communication
 - `gt mail send mayor/ -s "Subject" -m "Message"` - To Mayor
-- `gt mail send gastown/crew/joe -s "Subject" -m "Message"` - To yourself (handoff)
+- `gt mail send gastown/crew/max -s "Subject" -m "Message"` - To yourself (handoff)
 
 ## Git Workflow: Work Off Main
 
@@ -119,6 +119,30 @@ Issue prefix: `gt-`
 everything: sends handoff mail, respawns with fresh context, and your work
 continues from where you left off via your pinned molecule.
 
-Crew member: joe
+## Formulas
+
+Formulas are workflow templates stored in `.beads/formulas/`. They support both
+TOML (preferred) and JSON formats:
+
+```bash
+bd formula list              # List available formulas
+bd formula show shiny        # Show formula details
+bd formula convert --all     # Convert JSON to TOML
+bd cook shiny                # Compile formula to proto
+```
+
+TOML is preferred for human-edited formulas (multi-line strings, comments).
+
+## Key Diagnostics
+
+```bash
+gt doctor                    # Run all health checks
+gt doctor --fix              # Auto-fix common issues
+gt doctor -v                 # Verbose output
+gt status                    # Town-wide status
+bd doctor                    # Beads-specific checks
+```
+
+Crew member: max
 Rig: gastown
-Working directory: /Users/stevey/gt/gastown/crew/joe
+Working directory: /Users/stevey/gt/gastown/crew/max

docs/architecture.md

@@ -365,7 +365,7 @@ workflows that any worker can execute, with full auditability and the ability fo
 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`)
+- **Rig**: Compose workflow formulas (TOML/JSON 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)
 
@@ -375,7 +375,7 @@ See [molecular-chemistry.md](molecular-chemistry.md) for the full lifecycle spec
 
 | Concept | Name | Description |
 |---------|------|-------------|
-| Source | **Formula** | YAML workflow definition with composition rules (.formula.yaml) |
+| Source | **Formula** | TOML/JSON workflow definition with composition rules (.formula.toml preferred) |
 | 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") |
@@ -735,22 +735,25 @@ investigate → document
 ```
 Exploration workflow for understanding problems.
 
-Cook formula files into proto beads:
+Formula files support both TOML (preferred) and JSON formats:
 ```bash
-bd cook <formula-id>
+bd formula list              # List available formulas
+bd formula show shiny        # Show formula details
+bd formula convert --all     # Convert JSON to TOML
+bd cook <formula-id>         # Cook formula into proto bead
 ```
 
 ### Usage
 
 ```bash
-# List available molecules
+# List available molecules (cooked protos)
-gt molecule list
+bd mol list
 
 # Show molecule details
-gt molecule show mol-shiny
+bd mol show mol-shiny
 
-# Instantiate on an issue
+# Bond (instantiate) a molecule
-gt molecule instantiate mol-shiny --parent=gt-xyz
+bd mol bond mol-shiny --var feature_name="auth"
 
 # Spawn polecat with molecule
 gt spawn --issue gt-xyz --molecule mol-shiny

docs/molecular-chemistry.md

@@ -25,7 +25,7 @@ RIG ────→ COOK ────→ RUN
 | **Cook** | Instantiate artifacts | `cook`, `pour`, `wisp` | Proto, Mol, Wisp |
 | **Run** | Execute steps | (agent execution) | Work done |
 
-**Rig** is authoring time - writing and composing formula YAML files.
+**Rig** is authoring time - writing and composing formula files (TOML preferred, JSON supported).
 **Cook** is compile time - expanding macros, applying aspects, flattening to pure graphs.
 **Run** is execution time - agents provide cognition for each step.
 
@@ -73,10 +73,10 @@ Gas Town has **two** composition operators at different abstraction levels:
 
 | Operator | Level | Inputs | When to Use |
 |----------|-------|--------|-------------|
-| **Rig** | Source | Formula + Formula | Authoring time, in YAML |
+| **Rig** | Source | Formula + Formula | Authoring time, in TOML/JSON |
 | **Bond** | Artifact | Proto/Mol/Wisp + any | Runtime, on cooked artifacts |
 
-**Rig** composes formulas (YAML with `extends`, `compose`).
+**Rig** composes formulas (TOML/JSON with `extends`, `compose`).
 **Bond** composes artifacts (cooked protos, running mols/wisps).
 
 This separation is key: rig for design-time composition, bond for runtime composition.
@@ -102,41 +102,54 @@ In our chemistry:
 ## Formulas: The Source Layer
 
 **Formulas** sit above protos in the artifact hierarchy. They're the source code -
-YAML files that define workflows with composition operators.
+TOML or JSON files that define workflows with composition operators.
 
-```yaml
+TOML is preferred for human-edited formulas (multi-line strings, comments):
-# shiny.formula.yaml - a basic workflow
+
-formula: shiny
+```toml
-description: The canonical right way
+# shiny.formula.toml - a basic workflow
-version: 1
+formula = "shiny"
-steps:
+description = "The canonical right way"
-  - id: design
+version = 1
-    description: Think carefully about architecture
+
-  - id: implement
+[[steps]]
-    needs: [design]
+id = "design"
-  - id: review
+description = "Think carefully about architecture"
-    needs: [implement]
+
-  - id: test
+[[steps]]
-    needs: [review]
+id = "implement"
-  - id: submit
+needs = ["design"]
-    needs: [test]
+
+[[steps]]
+id = "review"
+needs = ["implement"]
+
+[[steps]]
+id = "test"
+needs = ["review"]
+
+[[steps]]
+id = "submit"
+needs = ["test"]
 ```
 
+Convert existing JSON formulas with `bd formula convert --all`.
+
 ### Formula Composition (Rigging)
 
 Formulas compose at the source level using `extends` and `compose`:
 
-```yaml
+```toml
-# shiny-enterprise.formula.yaml
+# shiny-enterprise.formula.toml
-formula: shiny-enterprise
+formula = "shiny-enterprise"
-extends: shiny                    # Inherit from base formula
+extends = ["shiny"]              # Inherit from base formula
-compose:
+
-  - expand:
+[compose]
-      target: implement
+aspects = ["security-audit"]      # Weave in cross-cutting concern
-      with: rule-of-five          # Apply macro expansion
+
-  - aspect:
+[[compose.expand]]
-      pointcut: "implement.*"
+target = "implement"
-      with: security-audit        # Weave in cross-cutting concern
+with = "rule-of-five"            # Apply macro expansion
 ```
 
 ### Cooking: Formula → Proto
@@ -178,7 +191,7 @@ encode reusable work structures. They're the "molds" from which instances are ca
 Protos are stored as beads issues with `labels: ["template"]` and structured step data:
 
 ```yaml
-# Example: shiny.formula.yaml (source) → cooked proto (beads)
+# Example: shiny.formula.toml (source) → cooked proto (beads)
 formula: shiny
 description: The canonical right way
 version: 1

docs/molecules.md

@@ -285,9 +285,62 @@ Gas Town work follows the **Rig → Cook → Run** lifecycle:
 ```
 
 **Full lifecycle:**
-- **Formula** (.formula.yaml) = Recipe (source code for workflows)
+- **Formula** (.formula.toml or .formula.json) = Recipe (source code for workflows)
 - **Proto** = Fuel (cooked template, ready to instantiate)
 - **Mol/Wisp** = Steam (active execution)
 - **Digest** = Distillate (crystallized work)
 
 See [molecular-chemistry.md](molecular-chemistry.md) for the complete specification.
+
+## Formula File Formats
+
+Formulas support both TOML (preferred) and JSON formats:
+
+```bash
+# List available formulas
+bd formula list
+
+# Show formula details
+bd formula show shiny
+
+# Convert JSON to TOML (better for human editing)
+bd formula convert shiny           # Single formula
+bd formula convert --all           # All formulas
+bd formula convert shiny --stdout  # Preview
+```
+
+**Why TOML?**
+- Multi-line strings without `\n` escaping
+- Comments allowed
+- Human-readable diffs
+- Same parsing semantics as JSON
+
+The loader tries `.formula.toml` first, falling back to `.formula.json`.
+
+### Example Formula (TOML)
+
+```toml
+formula = "shiny"
+type = "workflow"
+version = 1
+description = """
+Engineer in a Box - design before code, review before ship.
+"""
+
+[vars.feature]
+description = "The feature being implemented"
+required = true
+
+[[steps]]
+id = "design"
+title = "Design {{feature}}"
+description = """
+Think carefully about architecture before writing code.
+Consider edge cases and simpler approaches.
+"""
+
+[[steps]]
+id = "implement"
+title = "Implement {{feature}}"
+needs = ["design"]
+```

docs/wisp-architecture.md

@@ -79,6 +79,37 @@ Agent hook files (`hook-<agent>.json`) are stored in `.beads/` but are local-onl
 runtime state, not synced. These track what work is assigned to each agent for
 restart-and-resume.
 
+## Wisp Garbage Collection
+
+Wisps can accumulate over time. The `wisp-gc` doctor check cleans up stale wisps:
+
+```bash
+# Check for stale wisps
+gt doctor -v
+
+# Auto-cleanup stale wisps (>1h old by default)
+gt doctor --fix
+
+# Manual cleanup via bd
+bd wisp gc              # Preview what would be cleaned
+bd wisp gc --force      # Actually delete stale wisps
+bd wisp gc --age 2h     # Custom age threshold
+```
+
+The Deacon includes wisp-gc in its patrol cycle via `gt doctor --fix`.
+
+### What Gets Cleaned
+
+- Wisps older than the threshold (default 1 hour)
+- Wisps not associated with active sessions
+- Orphaned lifecycle mail
+
+### What's Preserved
+
+- Wisps with active sessions still running
+- Wisps younger than the threshold
+- Non-wisp issues (permanent records)
+
 ## Decision Matrix
 
 | Question | Answer | Use |