docs: enhance integration guide with detailed step-by-step commands and troubleshooting tips

README-CUSTOM-INTEGRATION.md

@@ -68,7 +68,357 @@ ls -la backups/
 - `src/ipc/utils/smart_context_store.ts` - Context storage and management
 - `src/hooks/useSmartContext.ts` - React hooks for smart context
 
-## Integration Workflow
+## Complete Step-by-Step Integration Guide
+
+This section provides detailed, copy-paste ready commands for every step of the integration process. Follow these commands exactly as written.
+
+### 📋 Pre-Update Checklist (5 minutes)
+
+**Step 1: Verify Current Working Directory**
+```bash
+# Make sure you're in the correct directory
+pwd
+# Expected output: /Users/kunthawatgreethong/Gitea/moreminimore-vibe
+
+# If not, navigate to the correct directory
+cd /Users/kunthawatgreethong/Gitea/moreminimore-vibe
+```
+
+**Step 2: Check Git Status**
+```bash
+# Check if you have any uncommitted changes
+git status
+# Expected: "working tree clean" or list your changes
+
+# If you have changes, commit them first
+git add .
+git commit -m "Save current state before upstream update"
+```
+
+**Step 3: Verify Custom Features Are Working**
+```bash
+# Validate current integration
+./scripts/integrate-custom-features.sh validate
+# Expected: [SUCCESS] Integration validation passed
+
+# If validation fails, fix issues before proceeding
+./scripts/integrate-custom-features.sh help
+```
+
+**Step 4: Check Current Git Branch**
+```bash
+# Make sure you're on your main branch
+git branch
+# Expected: * main or * master (with * indicating current branch)
+
+# If not on main branch, switch to it
+git checkout main
+```
+
+### 🔄 Upstream Update Process (10-15 minutes)
+
+**Step 5: Fetch Latest Changes from Upstream**
+```bash
+# Fetch all changes from upstream repository
+git fetch upstream
+# Expected: No output (or shows what was fetched)
+
+# Check what new commits are available
+git log main..upstream/main --oneline
+# Expected: List of new commits from upstream
+```
+
+**Step 6: Stash Your Local Changes (Optional but Recommended)**
+```bash
+# If you have any local changes not committed
+git stash push -m "Temporary stash before upstream merge"
+# Expected: Saved working directory and index state
+
+# To see your stashes
+git stash list
+```
+
+**Step 7: Merge Upstream Changes**
+```bash
+# Merge upstream changes into your main branch
+git merge upstream/main
+# Expected: Shows merge summary or conflicts
+
+# If there are conflicts, you'll see:
+# CONFLICT (content): Merge conflict in file-name
+```
+
+**Step 8: Handle Merge Conflicts (If Any)**
+```bash
+# If conflicts exist, check which files have conflicts
+git status
+# Look for files marked as "both modified"
+
+# Open conflicted files and resolve them manually
+# Look for these markers in files:
+# <<<<<<< HEAD
+# Your changes
+# =======
+# Upstream changes
+# >>>>>>> upstream/main
+
+# After resolving conflicts in each file:
+git add path/to/resolved/file.ts
+
+# Continue with merge when all conflicts resolved
+git merge --continue
+```
+
+**Step 9: Restore Stashed Changes (If You Stashed)**
+```bash
+# Restore your stashed changes
+git stash pop
+# Expected: Shows what was restored
+
+# If there are new conflicts, resolve them
+git status
+git add . (resolve conflicts first)
+git commit -m "Merge upstream changes and resolve conflicts"
+```
+
+### 🔧 Integration Process (5-10 minutes)
+
+**Step 10: Run the Integration Script**
+```bash
+# Execute the integration script
+./scripts/integrate-custom-features.sh integrate
+# Expected output:
+# [2025-12-18 HH:MM:SS] Starting custom features integration...
+# [2025-12-18 HH:MM:SS] Creating backup: backup-YYYYMMDD-HHMMSS
+# [SUCCESS] Backup created at: /Users/kunthawatgreethong/Gitea/moreminimore-vibe/backups/backup-YYYYMMDD-HHMMSS
+# [2025-12-18 HH:MM:SS] Creating missing custom files...
+# [SUCCESS] Missing custom files created
+# [2025-12-18 HH:MM:SS] Validating integration...
+# [SUCCESS] Integration validation passed
+# [SUCCESS] Custom features integration completed successfully!
+```
+
+**Step 11: Verify Integration Success**
+```bash
+# Check that all expected files exist
+ls -la src/ipc/handlers/smart_context_handlers.ts
+ls -la src/ipc/utils/smart_context_store.ts
+ls -la src/hooks/useSmartContext.ts
+
+# Expected: All three files should exist and show file info
+```
+
+### ✅ Validation and Testing (10-15 minutes)
+
+**Step 12: Run Validation Script**
+```bash
+# Validate the integration
+./scripts/integrate-custom-features.sh validate
+# Expected:
+# [2025-12-18 HH:MM:SS] Validating integration...
+# [SUCCESS] Integration validation passed
+
+# If you see warnings, note them but continue
+# Warnings about missing custom modifications are usually OK
+```
+
+**Step 13: Check TypeScript Compilation**
+```bash
+# Check for TypeScript errors (may have some MCP-related warnings)
+npm run ts
+# Expected: May show some MCP-related errors but should complete
+# If many new errors appear, investigate before proceeding
+```
+
+**Step 14: Test Application Startup**
+```bash
+# Install any new dependencies if needed
+npm install
+
+# Start the application in development mode
+npm start
+# Expected: Application should start without critical errors
+# Let it run for 30-60 seconds to ensure stability
+# Press Ctrl+C to stop when confirmed working
+```
+
+**Step 15: Test Custom Features Manually**
+```bash
+# Start the application again
+npm start
+
+# Test these features in the UI:
+# 1. Create a new chat
+# 2. Send a message
+# 3. Check if smart context is working (no obvious errors)
+# 4. Verify help dialog opens correctly
+# 5. Check that promo messages display properly
+
+# If everything works, integration is successful!
+# If issues occur, proceed to troubleshooting section
+```
+
+### 🚨 If Something Goes Wrong
+
+**Step 16: Identify the Problem**
+```bash
+# Check what went wrong
+./scripts/integrate-custom-features.sh validate
+# Note any errors or warnings
+
+# Check application logs if it won't start
+npm start 2>&1 | tee startup-errors.log
+# Review startup-errors.log for clues
+```
+
+**Step 17: Restore from Backup (If Needed)**
+```bash
+# List available backups
+ls -la backups/
+# Expected: List of backup directories with timestamps
+
+# Find your most recent backup (look for the latest timestamp)
+# Example: backup-20231218-154512
+
+# Restore from the most recent working backup
+./scripts/integrate-custom-features.sh restore backup-20231218-154512
+# Expected:
+# [2025-12-18 HH:MM:SS] Restoring from backup: backup-20231218-154512
+# [SUCCESS] Restore completed
+```
+
+**Step 18: Verify Restoration**
+```bash
+# Check that custom features are back
+./scripts/integrate-custom-features.sh validate
+# Expected: [SUCCESS] Integration validation passed
+
+# Test application startup
+npm start
+# Should work as it did before the update
+```
+
+**Step 19: Manual Investigation (If Restoration Doesn't Work)**
+```bash
+# Check Git state
+git status
+git log --oneline -10
+
+# Check specific files for issues
+git diff HEAD~1 src/ipc/ipc_types.ts
+git diff HEAD~1 src/ipc/ipc_client.ts
+
+# Look for specific error patterns
+grep -r "SmartContext" src/ --include="*.ts" --include="*.tsx"
+```
+
+### 🔍 Troubleshooting Commands
+
+**Check Integration Script Health**
+```bash
+# Make script executable (if permission issues)
+chmod +x scripts/integrate-custom-features.sh
+
+# Test script help
+./scripts/integrate-custom-features.sh help
+# Should show usage instructions
+```
+
+**Verify File Permissions**
+```bash
+# Check script permissions
+ls -la scripts/integrate-custom-features.sh
+# Should show -rwxr-xr-x (executable)
+
+# Fix permissions if needed
+chmod 755 scripts/integrate-custom-features.sh
+```
+
+**Check Node.js and npm**
+```bash
+# Verify Node.js version
+node --version
+# Expected: v18.x.x or higher
+
+# Verify npm version
+npm --version
+# Expected: 9.x.x or higher
+
+# Clear npm cache if needed
+npm cache clean --force
+```
+
+**Check Git Configuration**
+```bash
+# Verify upstream remote is configured
+git remote -v
+# Should show upstream remote pointing to dyad-sh/dyad
+
+# If upstream is missing, add it
+git remote add upstream https://github.com/dyad-sh/dyad.git
+```
+
+### 📝 Quick Reference Commands
+
+**Emergency Restore (One-liner)**
+```bash
+# Restore latest backup (replace with actual backup name)
+./scripts/integrate-custom-features.sh restore $(ls -t backups/ | head -1)
+```
+
+**Check All Backups**
+```bash
+# List all backups with details
+ls -la backups/ | grep backup
+```
+
+**Force Clean Integration**
+```bash
+# For problematic integrations, start fresh
+git clean -fd
+git reset --hard HEAD
+./scripts/integrate-custom-features.sh integrate
+```
+
+**Verify All Custom Files**
+```bash
+# Quick check that all custom files exist
+files=("src/ipc/handlers/smart_context_handlers.ts" "src/ipc/utils/smart_context_store.ts" "src/hooks/useSmartContext.ts")
+for file in "${files[@]}"; do
+  if [[ -f "$file" ]]; then
+    echo "✅ $file exists"
+  else
+    echo "❌ $file missing"
+  fi
+done
+```
+
+### ⏱️ Time Estimates
+
+- **Pre-Update Checklist**: 5 minutes
+- **Upstream Update**: 10-15 minutes (longer if many conflicts)
+- **Integration Process**: 5-10 minutes
+- **Validation and Testing**: 10-15 minutes
+- **Troubleshooting**: 15-30 minutes (if needed)
+
+**Total Time**: 30-60 minutes for smooth integration, up to 2 hours if problems occur.
+
+### 🎯 Success Indicators
+
+You'll know the integration was successful when:
+
+1. ✅ Integration script runs without errors
+2. ✅ Validation script shows "[SUCCESS] Integration validation passed"
+3. ✅ Application starts with `npm start`
+4. ✅ No critical errors in console
+5. ✅ Custom features work in the UI
+6. ✅ TypeScript compilation completes (may have warnings)
+
+If all these are true, your custom features have been successfully integrated with the latest upstream changes!
+
+---
+
+## Integration Workflow Summary
 
 ### Before Upstream Update
 1. **Current State**: Your custom features are integrated