moreminimore-vibe/UPDATE_GUIDE.md

# Dyad Update Management Guide

This guide explains how to update your forked Dyad application while preserving your custom modifications.

## 🎯 Overview

Your setup uses a **selective update strategy** that:
- Keeps your custom code separate from the main codebase
- Automatically preserves custom modifications during updates
- Provides backup and rollback capabilities
- Minimizes merge conflicts

## 📁 Custom Code Structure

Your custom modifications are organized in `src/custom/`:

```
src/custom/
├── index.ts                    # Main entry point for custom features
├── hooks/
│   └── useSmartContext.ts     # Custom smart context hook
├── ipc/
│   └── smart_context_handlers.ts  # Custom IPC handlers
└── utils/
    └── smart_context_store.ts     # Custom utilities
```

## 🚀 Update Process

### Method 1: Automated Update (Recommended)

Use the provided update script:

```bash
./update-dyad-v2.sh
```

**What the script does:**
1. Creates a timestamped backup
2. Backs up your custom code
3. Fetches latest changes from upstream
4. Resets to the latest upstream version
5. Restores your custom code
6. Pushes updates to your fork

### Method 2: Manual Update

If you prefer manual control:

```bash
# 1. Create backup
cp -r src/custom/ dyad-backup-$(date +%Y%m%d-%H%M%S)/

# 2. Fetch latest changes
git fetch upstream

# 3. Reset to latest upstream
git reset --hard upstream/main

# 4. Restore custom code
cp -r dyad-backup-*/src/custom/ src/

# 5. Commit and push
git add src/custom/
git commit -m "Restore custom code after update"
git push origin main
```

## 🔄 Update Workflow

### Before Updating
1. **Test current state** - Ensure your app works properly
2. **Commit any changes** - Don't have uncommitted work
3. **Check custom code** - Note any modifications that might need updates

### After Updating
1. **Run npm install** - Update dependencies if needed
2. **Test the application** - Ensure everything works
3. **Check custom integrations** - Verify custom features still work
4. **Update custom code** if needed - Adapt to any API changes

## 🛠️ Adding New Custom Features

When adding new custom features:

1. **Place in src/custom/** - Keep custom code organized
2. **Update imports** - Use relative imports within custom directory
3. **Document changes** - Note what each custom feature does
4. **Test integration** - Ensure custom features work with main app

Example:
```typescript
// src/custom/components/MyCustomComponent.tsx
import { useSmartContext } from '../hooks/useSmartContext';

export const MyCustomComponent = () => {
  // Your custom logic
};
```

## 🚨 Troubleshooting

### Merge Conflicts
If you encounter merge conflicts during manual updates:

```bash
# Abort the merge
git merge --abort

# Use the automated script instead
./update-dyad-v2.sh
```

### Custom Code Not Working
After an update, if custom features don't work:

1. **Check API changes** - The upstream may have changed interfaces
2. **Update imports** - File paths might have changed
3. **Review breaking changes** - Check upstream release notes
4. **Test incrementally** - Isolate the problematic code

### Backup Restoration
If you need to restore from backup:

```bash
# Find your backup directory
ls dyad-backup-*

# Restore specific files
cp -r dyad-backup-YYYYMMDD-HHMMSS/src/custom/ src/

# Or restore entire project (last resort)
rm -rf * .gitignore
cp -r dyad-backup-YYYYMMDD-HHMMSS/* .
cp dyad-backup-YYYYMMDD-HHMMSS/.gitignore .
```

## 📋 Best Practices

### Regular Maintenance
- **Update frequently** - Smaller updates are easier to manage
- **Test after each update** - Catch issues early
- **Keep custom code minimal** - Only customize what's necessary
- **Document customizations** - Future you will thank you

### Code Organization
- **Separate concerns** - Keep UI, logic, and utilities separate
- **Use TypeScript** - Catch integration issues early
- **Follow existing patterns** - Match the upstream code style
- **Avoid modifying core files** - Use extension patterns when possible

### Backup Strategy
- **Multiple backups** - Keep several backup versions
- **Offsite backup** - Consider cloud storage for critical backups
- **Test backups** - Ensure you can restore from backup
- **Label clearly** - Use descriptive backup names

## 🔧 Advanced Configuration

### Custom Update Script
You can modify `update-dyad-v2.sh` to:
- Skip certain files from backup
- Add custom post-update steps
- Include additional validation
- Send notifications on completion

### Selective File Restoration
To restore only specific custom files:

```bash
# Restore specific directory
cp -r dyad-backup-*/src/custom/hooks/ src/custom/

# Restore specific file
cp dyad-backup-*/src/custom/index.ts src/custom/
```

## 📞 Getting Help

If you encounter issues:

1. **Check this guide first** - Most common issues are covered
2. **Review the script output** - Error messages are informative
3. **Test with a clean state** - Start fresh if needed
4. **Document the issue** - Note what you were trying to do

## 🎉 Success Indicators

You'll know the update was successful when:
- ✅ Script completes without errors
- ✅ Custom code is present in `src/custom/`
- ✅ Application starts and runs normally
- ✅ Custom features work as expected
- ✅ No merge conflicts in git status

---

**Remember**: The goal is to make updates painless and predictable. When in doubt, use the automated script and keep good backups!