001-migration-ui-redesign (#3)

Reviewed-on: #3

specs/001-migration-ui-redesign/quickstart.md

@@ -0,0 +1,39 @@
+# Quickstart: Migration Process and UI Redesign
+
+## Setup
+
+1. **Install Dependencies**:
+   ```bash
+   pip install rapidfuzz sqlalchemy
+   cd frontend && npm install
+   ```
+
+2. **Configure Environments**:
+   Ensure you have at least two Superset environments configured in the application settings.
+
+3. **Initialize Database**:
+   The system will automatically create the `mappings.db` SQLite file on the first run.
+
+## Usage
+
+### 1. Define Mappings
+1. Navigate to the **Database Mapping** tab.
+2. Select your **Source** and **Target** environments.
+3. Click **Fetch Databases**.
+4. Review the **Suggested Mappings** (highlighted in green).
+5. Manually adjust any mappings using the dropdowns.
+6. Click **Save Mappings**.
+
+### 2. Run Migration
+1. Go to the **Migration** dashboard.
+2. Select the **Source** and **Target** environments.
+3. Select the assets (Dashboards/Datasets) you want to migrate.
+4. Enable the **Replace Database** toggle.
+5. Click **Start Migration**.
+6. If a database is missing a mapping, a modal will appear prompting you to select a target database.
+
+## Troubleshooting
+
+- **Connection Error**: Ensure the backend can reach both Superset instances. Check credentials in settings.
+- **Mapping Not Applied**: Verify that the "Replace Database" toggle was enabled and that the mapping exists for the specific environment pair.
+- **Fuzzy Match Failure**: If names are too different, manual mapping is required. The system learns from manual overrides.