# Version Transition Guide: v2.3.x → v2.4.0
**Last Updated:** !`date -u +"%Y-%m-%d %H:%M:%S UTC"`
**Release Date:** 2025-10-18 (RC phase, not yet stable)
**Status:** Release Candidate (RC23+)
**Breaking Changes:** Yes (major architectural improvements)

---

## 📊 Executive Summary

Version 2.4.0 brings major architectural refinements focused on:
- **Token efficiency:** 98.8% reduction in session monitoring overhead
- **Cognitive architecture:** Clearer separation of agents/workflows
- **Performance:** Multi-agent orchestration improvements
- **Reliability:** Critical bug fixes for background agent launches

**Impact:** Fresh install recommended. Previous customizations (if any) are backed up.

---

## 🏗️ Architectural Changes

### 1. Enhanced Backup System ✅ NEW
**What changed:**
- Backup now includes root `AGENTS.md` and `CLAUDE.md` files
- Backup structure: `.genie/backups/{timestamp}/docs/`
- Rollback now restores root documentation files

**Why it matters:**
- Your framework customizations are now safely preserved
- No data loss during updates
- Can roll back both `.genie/` AND root docs

**User action:**
- None required (automatic)
- Future customizations to AGENTS.md/CLAUDE.md will be backed up

---

### 2. Token Efficiency Revolution
**What changed:**
- Session views use lightweight markdown instead of Ink rendering
- Output reduction: 36-48k tokens → <600 tokens (98.8% reduction)
- Removed ~1,200 lines of rendering overhead

**Why it matters:**
- 10+ concurrent agents without token budget explosion
- Faster AI-to-AI orchestration
- Lower costs for multi-agent workflows

**User action:**
- None required (automatic improvement)
- Enjoy faster, cheaper agent orchestration

---

### 3. Cognitive Architecture Refinement
**What changed:**
- Agent directories restructured: `core/` → `agents/` + `workflows/`
- Clearer separation of cognitive layers
- Custom overrides mirror cognitive architecture

**Why it matters:**
- Easier to understand agent organization
- Clearer delegation hierarchy
- Better maintainability

**User action:**
- None required (structure migrated automatically)
- If you had custom agents, check backup location

---

### 4. Critical Bug Fixes

#### 4a. Background Agent Launch Timeout (Issue #104)
**What was broken:**
- Background agents timed out with `executorPid=null`
- Caused by wrong working directory propagation

**What's fixed:**
- Increased timeout to 180 seconds
- Workspace root now correctly propagates MCP → CLI → executor
- Absolute path resolution for cross-process compatibility

**User impact:**
- Background agents now launch reliably
- No more mysterious timeouts

#### 4b. Session Lifecycle Bug (RC21)
**What was broken:**
- V1→V2 session format transition issues
- Session creation failing in background mode

**What's fixed:**
- Session format migrations handled correctly
- Background session creation stable

**User impact:**
- MCP sessions more reliable
- Fewer "session disappeared" errors

---

## 💾 Your Backup Location

Your previous configuration is at:
```
.genie/backups/{BACKUP_ID}/
├── genie/           # Entire .genie directory
└── docs/            # Root documentation files
    ├── AGENTS.md    (if existed)
    └── CLAUDE.md    (if existed)
```

---

## ✅ Migration Checklist

### For Most Users (No Customizations)
- [ ] Review this migration guide
- [ ] Test basic workflows: `genie run plan "test prompt"`
- [ ] Verify agents launch correctly
- [ ] Done! ✅

### If You Had Custom AGENTS.md
1. [ ] Check backup at `.genie/backups/{BACKUP_ID}/docs/AGENTS.md`
2. [ ] Review your custom learning entries or modifications
3. [ ] Decide what to preserve in new v2.4.0 AGENTS.md
4. [ ] Manually merge important customizations
5. [ ] Test: Verify framework still works as expected

### If You Had Custom CLAUDE.md
1. [ ] Check backup at `.genie/backups/{BACKUP_ID}/docs/CLAUDE.md`
2. [ ] Review your custom @ references or patterns
3. [ ] Decide what to preserve in new v2.4.0 CLAUDE.md
4. [ ] Manually merge project-specific patterns
5. [ ] Test: Verify project context loads correctly

### If You Had Custom Agents
1. [ ] Check backup at `.genie/backups/{BACKUP_ID}/genie/agents/`
2. [ ] Review your custom agent files
3. [ ] Note new structure: `agents/` and `workflows/` directories
4. [ ] Re-create custom agents in new structure if needed
5. [ ] Test: `genie run {your-custom-agent} "test prompt"`

---

## 🧪 Verification Steps

### 1. Test Basic Agent Launch
```bash
genie run plan "Create a simple hello world feature"
```
**Expected:** Plan agent launches, provides structured response

### 2. Test Background Agent
```bash
genie run genie "Analyze current project structure" --background
```
**Expected:** Session ID returned, no timeout errors

### 3. Check Version
```bash
cat .genie/state/version.json
```
**Expected:** `"version": "2.4.0"`

### 4. List Available Agents
```bash
genie list
```
**Expected:** All agents shown (plan, wish, forge, review, etc.)

---

## 🚨 Common Issues & Solutions

### Issue: "Agent not found" errors
**Cause:** Custom agents not migrated to new structure
**Solution:** Check backup, re-create in `agents/` or `workflows/`

### Issue: "Session timeout" errors
**Cause:** Background launch still unstable (rare)
**Solution:** Increase timeout in config or use foreground mode

### Issue: Lost customizations in AGENTS.md
**Cause:** Update overwrites root files (by design)
**Solution:** Check backup at `.genie/backups/{BACKUP_ID}/docs/`, manually merge

### Issue: MCP connection errors
**Cause:** Configuration mismatch after update
**Solution:** Re-run `genie init` to refresh MCP config

---

## 📚 Breaking Changes Reference

| Change | Impact | Action Required |
|--------|--------|-----------------|
| Backup expansion | None (improvement) | None |
| Token efficiency | None (automatic) | None |
| Agent restructure | Custom agents need migration | Check backup |
| Timeout fixes | None (improvement) | None |
| Session format | None (automatic) | None |

---

## 🔄 Rollback Instructions

If you encounter issues and need to revert:

```bash
# List available backups
ls -la .genie/backups/

# Rollback to previous version
genie rollback --id {BACKUP_ID}

# Or rollback to latest backup
genie rollback --latest
```

**Note:** Rollback restores both `.genie/` AND root docs (AGENTS.md, CLAUDE.md)

---

## 📖 Additional Resources

- **Changelog:** `CHANGELOG.md` (lines 11-47 for v2.4.0 details)
- **Issue #104:** Background launch timeout fix
- **Issue #109:** Session lifecycle fix (RC21)
- **GitHub Releases:** https://github.com/namastexlabs/automagik-genie/releases

---

## 🎯 Next Steps

1. ✅ Review this guide completely
2. ✅ Check backup if you had customizations
3. ✅ Run verification tests
4. ✅ Manually merge important customizations
5. ✅ Resume normal workflow

**Welcome to Genie v2.4.0! 🧞**