docs: add migration docs (#2580)

<!--
Please read and fill out this form before submitting your PR.

Please make sure you have reviewed our contributors guide before
submitting your
first PR.

NOTE: PR titles should follow semantic commits:
https://www.conventionalcommits.org/en/v1.0.0/
-->

## Overview

<!-- 
Please provide an explanation of the PR, including the appropriate
context,
background, goal, and rationale. If there is an issue with this
information,
please provide a tl;dr and link the issue. 

Ex: Closes #<issue number>
-->

Author: auricom

docs/guides/evm/migration.md

@@ -52,16 +52,24 @@ All network participants must agree on:
 
 ### 3. Stop the Node at Target Height
 
-Configure your node to stop at the agreed-upon migration height:
+Configure your node to stop at the agreed-upon migration height. Both the Evolve node and ev-reth must be stopped to properly export the genesis state:
 
 ```bash
 # Stop the Evolve node gracefully
-docker stop evolve-node
+docker stop ev-node
 
 # Or if running as a service
-systemctl stop evolve-node
+systemctl stop ev-node
+
+# Stop ev-reth
+docker stop ev-reth
+
+# Or if running as a service
+systemctl stop ev-reth
 ```
 
+**Important**: ev-reth must be completely shutdown before running `dump-genesis` as the export process requires exclusive access to the database.
+
 ### 4. Export Current State Using reth dump-genesis
 
 reth dump-genesis exports the current head state in the node’s local database into a genesis file.
@@ -70,49 +78,57 @@ It does not accept a --block flag, so to capture a specific migration height you
 ⸻
 
 Option 1 — Stop at the target height before dumping
+
 - Sync your Evolve/reth node to the agreed migration height.
 - Disable block production or stop the sequencer so no new blocks are added.
 - Run dump-genesis while the DB is exactly at the migration height.
 
+```bash
 # Stop node at migration height
+
 systemctl stop evolve-node
 
 # Export state at current head (must be migration height)
-reth dump-genesis \
+
+ev-reth dump-genesis \
   --datadir /path/to/reth/datadir \
   --output genesis-export.json
-
+```
 
 ⸻
 
 Option 2 — Rewind DB to migration height
 
 If your node has already synced past the migration block:
 
+```bash
 reth db revert-to-block <MIGRATION_BLOCK_HEIGHT> --datadir /path/to/reth/datadir
 
 # Then dump the state
 reth dump-genesis \
   --datadir /path/to/reth/datadir \
   --output genesis-export.json
-
+```
 
 ⸻
 
 Verification after export:
 
+```bash
 # Number of accounts in alloc
+
 jq '.alloc | length' genesis-export.json
 
 # Review chain configuration
 jq '.config' genesis-export.json
+```
 
 The exported genesis will contain:
+
 - All account balances and nonces
 - Contract bytecode and storage
 - Current chain configuration
 
-
 ### 5. Prepare New Genesis Configuration
 
 Once you have genesis-export.json, update it for the new chain parameters.
@@ -143,7 +159,6 @@ jq '.config.chainId = <NEW_CHAIN_ID> |
     genesis-export.json > genesis-new.json
 ```
 
-
 ### 6. Initialize New Chain with reth init
 
 Initialize the new chain using the modified genesis:
@@ -161,29 +176,44 @@ reth init \
 reth db stats --datadir /path/to/new/reth/datadir
 ```
 
-### 7. Update Node Configuration
+### 7. Update Node Configuration and Purge Data
+
+Update your Evolve node configuration for the new chain and purge the data directory:
 
-Update your Evolve node configuration for the new chain:
+**CRITICAL**: Always preserve the `$HOME_DIR/config` directory as it contains essential sequencer node ID and private keys.
 
-```yaml
-# evolve.yml
-chain_id: <NEW_CHAIN_ID>
-genesis_file: /path/to/genesis-new.json
-reth:
-  datadir: /path/to/new/reth/datadir
-  network_id: <NEW_NETWORK_ID>
+```bash
+# Update the configuration file with new chain ID
+# Edit $HOME_DIR/config/evolve.yaml
+sed -i 's/chain_id: .*/chain_id: <NEW_CHAIN_ID>/' $HOME_DIR/config/evolve.yaml
+
+# Purge the data directory
+rm -rf $HOME_DIR/data
 ```
 
+**Important Notes**:
+
+- The `$HOME_DIR/config` directory contains critical sequencer node identity and private keys
+- **Never delete the config directory** - this would result in loss of node identity
+- Only the `data` directory should be purged to start fresh with the new chain
+- Backup your config directory before migration as an additional safety measure
+
 ### 8. Start the New Chain
 
 Start your node with the new configuration:
 
 ```bash
 # Start Evolve node with new configuration
-evolve start --config evolve.yml
+docker start ev-reth
+
+# Or if running as a service
+systemctl start ev-reth
 
 # Monitor logs for successful startup
-tail -f /var/log/evolve/node.log
+docker logs ev-reth
+
+# Or if running as a service
+journalctl -xeu ev-reth
 ```
 
 ## External Services Coordination
@@ -198,6 +228,7 @@ Bridge operators must be notified well in advance to:
 - **Map balances**: Ensure locked tokens match bridged tokens on new chain
 
 Coordination checklist:
+
 ```markdown
 - [ ] Notify bridge operators 2 weeks before migration
 - [ ] Pause bridge operations at block height - 100
@@ -217,6 +248,7 @@ Explorer operators need to:
 - **Redirect users**: Implement proper redirects and notifications
 
 Explorer coordination:
+
 ```bash
 # Provide explorer operators with:
 - New genesis file
@@ -238,6 +270,7 @@ Exchange integration requires careful coordination:
 - **Resume operations**: Gradual reopening after validation
 
 Exchange checklist:
+
 ```markdown
 - [ ] 30-day advance notice to exchanges
 - [ ] Provide technical migration guide
@@ -354,26 +387,31 @@ Here's a recommended timeline for chain migration:
 
 ```markdown
 ### T-30 days
+
 - [ ] Initial migration announcement
 - [ ] Technical documentation published
 - [ ] Begin coordination with service providers
 
 ### T-14 days
+
 - [ ] Finalize migration block height
 - [ ] Confirm participation from all validators
 - [ ] Service providers confirm readiness
 
 ### T-7 days
+
 - [ ] Final migration parameters locked
 - [ ] Test migration on testnet
 - [ ] Public reminder announcements
 
 ### T-24 hours
+
 - [ ] Final coordination call
 - [ ] Service suspension notifications
 - [ ] Last-chance backups
 
 ### T-0 (Migration)
+
 - [ ] Stop nodes at target height
 - [ ] Export state
 - [ ] Generate new genesis
@@ -382,11 +420,13 @@ Here's a recommended timeline for chain migration:
 - [ ] Initial validation
 
 ### T+6 hours
+
 - [ ] Service providers begin reconnection
 - [ ] Initial functionality tests
 - [ ] Public progress updates
 
 ### T+24 hours
+
 - [ ] Full service restoration
 - [ ] Post-migration report
 - [ ] Address any issues
@@ -397,13 +437,15 @@ Here's a recommended timeline for chain migration:
 ### Common Issues and Solutions
 
 **State Export Failures**:
+
 ```bash
 # If export fails due to memory, increase heap size
 export RETH_HEAP_SIZE=8g
 reth dump-genesis --datadir /path/to/datadir
 ```
 
 **Genesis Initialization Errors**:
+
 ```bash
 # Verify genesis file format
 jq empty genesis-new.json  # Should return nothing if valid
@@ -413,6 +455,7 @@ jq '.config.chainId, .alloc, .timestamp' genesis-new.json
 ```
 
 **Node Sync Issues**:
+
 ```bash
 # Clear peer database and reconnect
 rm -rf /path/to/datadir/nodes