docs: add Backup and Restore documentation for Configurator auto-backup

docs/Backup and Restore.md

@@ -0,0 +1,107 @@
+# Backup and Restore
+
+INAV Configurator can automatically back up your configuration before flashing firmware and offer to restore it afterwards. When upgrading across major versions (e.g. 7.x → 8.x → 9.x), settings are automatically migrated to the new firmware format.
+
+For manual CLI-based backup and restore, see the [CLI documentation](Cli.md#backup-via-cli).
+
+## Automatic Backup & Restore During Firmware Flash
+
+### What happens automatically
+
+1. **Before flashing** (with or without Full Chip Erase enabled): Your current CLI configuration (`diff all`) is automatically captured and saved to the backup directory.
+2. **After flashing**: Depending on the situation, the Configurator offers to restore your settings if Full Chip Erase was enabled:
+
+| Scenario | Behavior |
+|----------|----------|
+| **Patch update** (e.g. 8.0.0 → 8.0.1) | Auto-restore offered immediately |
+| **Minor update** (e.g. 8.0.0 → 8.1.0) | Auto-restore offered immediately |
+| **Major upgrade** (e.g. 7.x → 8.x) with migration profile available | Migration preview shown — confirm to restore with converted settings |
+| **Major upgrade** without migration profile | Warning shown — restore still possible but some settings may fail |
+| **Major downgrade** (e.g. 9.x → 7.x) | Auto-restore blocked — manual restore only (settings may be incompatible) |
+| **Local firmware file** (loaded from disk) | No auto-restore offered — backup is still saved |
+| **Flash without Full Chip Erase** | Backup taken, no restore offered |
+
+### Migration Preview
+
+When updating across major versions (e.g. 7.x → 9.x), the Configurator shows a **migration preview overlay** before restoring. This lists:
+
+- **Removed settings** — settings that no longer exist in the new firmware (will be skipped)
+- **Renamed settings** — settings whose name changed (automatically converted)
+- **Renamed commands** — CLI commands that were renamed (automatically converted)
+- **Value replacements** — setting values that changed meaning (automatically converted)
+- **Setting remappings** — numeric IDs that were renumbered (automatically converted)
+- **Warnings** — settings whose semantics changed and require manual review
+
+You can review all changes before confirming or cancelling the restore.
+
+Multi-step migrations are handled automatically. For example, a 7.x → 9.x upgrade applies migration profiles in sequence (7→8, then 8→9).
+
+## Manual Backup & Restore
+
+The Firmware Flasher tab provides three buttons:
+
+- **Backup Config** — saves your current CLI configuration to a file (opens save dialog)
+- **Restore Config** — loads a backup file and restores it to your flight controller
+  - If the backup is from a different major version, the migration preview is shown first
+  - If no migration profile exists for the version gap, a warning is shown but you can still proceed
+- **Open Backups Folder** — opens the backup directory in your file manager
+
+For CLI-based backup and restore procedures, see [Backup via CLI](Cli.md#backup-via-cli) and [Restore via CLI](Cli.md#restore-via-cli).
+
+## Backup File Location
+
+Backups are stored in your OS-specific application data directory:
+
+| OS | Path |
+|----|------|
+| **Windows** | `%APPDATA%/inav-configurator/backups/` |
+| **macOS** | `~/Library/Application Support/inav-configurator/backups/` |
+| **Linux** | `~/.config/inav-configurator/backups/` |
+
+Use the **Open Backups Folder** button in the Firmware Flasher tab to open this directory.
+
+## Backup File Naming
+
+| Type | Format |
+|------|--------|
+| Auto-backups | `UPDATE_inav_backup_{version}_{board}_{YYYY-MM-DD_HHMMSS}.txt` |
+| Manual backups | `inav_backup_{version}_{board}_{YYYY-MM-DD_HHMMSS}.txt` |
+
+Auto-backups are pruned automatically — only the 10 most recent are kept. Files you rename are never pruned.
+
+## Backup File Format
+
+Backup files are plain-text CLI dumps with a metadata header:
+
+```
+# INAV Backup
+# Version: 8.0.0
+# Board: SPEEDYBEEF405V4
+# Date: 2026-04-11T10:30:00.000Z
+# Craft: MyQuad
+#
+# INAV/SPEEDYBEEF405V4 8.0.0 Apr  1 2026 / 12:00:00 (abc1234)
+# GCC-13.2.1
+# ...
+set gyro_main_lpf_hz = 110
+set acc_hardware = AUTO
+...
+```
+
+You can open and edit these files with any text editor.
+
+## Restore Error Handling
+
+If errors occur during restore (e.g. unknown settings, invalid values):
+
+- An error dialog shows the affected lines
+- You can choose:
+  - **Save anyway** — saves the successfully applied settings and reboots
+  - **Abort** — discards all changes and exits CLI mode
+
+## Tips
+
+- **Always flash with Full Chip Erase** when upgrading to a new version. This ensures clean defaults and triggers automatic backup and restore.
+- **Review migration previews carefully** — especially the warnings section, which highlights settings whose meaning may have changed.
+- **Keep manual backups** before major upgrades. While auto-backup handles this, having an extra copy in a known location gives peace of mind.
+- **Use `diff` over `dump`** for backups. The `diff` format only stores settings that differ from defaults, which makes restoring safer across versions. The auto-backup feature already uses `diff all`.

docs/Cli.md

@@ -22,6 +22,8 @@ See the other documentation sections for details of the cli commands and setting
 
 ## Backup via CLI
 
+> **Note:** The INAV Configurator now performs automatic backups before flashing and can restore settings afterwards, including migration across major versions. See [Backup and Restore](Backup%20and%20Restore.md) for details. The CLI method below remains available for manual backup.
+
 Disconnect main power, connect to cli via USB/FTDI.
 
 dump using cli

docs/Configuration.md

@@ -10,7 +10,7 @@ See the Serial section for more information and see the Board specific sections
 The GUI cannot currently configure all aspects of the system, the CLI must be used to enable or configure
 some features and settings.
 
-__Due to ongoing development, the fact that the GUI cannot yet backup all your settings and automatic chrome updates of the GUI app it is highly advisable to backup your settings (using the CLI) so that when a new version of the configurator or firmware is released you can re-apply your settings.__
+__The INAV Configurator now (versions after 9.0.x) automatically backs up your settings before flashing firmware and can restore them afterwards (when Full Chip Erase is enabled), including automatic migration across major versions. For details, see [Backup and Restore](Backup%20and%20Restore.md). You can also manually backup and restore settings using the [CLI](Cli.md#backup-via-cli).__
 
 
 ## GUI

docs/Installation.md

@@ -27,4 +27,8 @@ When upgrading be sure to backup / dump your existing settings.  Some firmware r
 
 ## Backup/Restore process
 
-See the CLI section of the docs for details on how to backup and restore your configuration via the CLI.
+The INAV Configurator (after version 9.0.x) automatically backs up your configuration before flashing and offers to restore it afterwards (when Full Chip Erase is enabled) — including automatic settings migration when upgrading across major versions.
+
+For details on automatic and manual backup/restore, see [Backup and Restore](Backup%20and%20Restore.md).
+
+For CLI-based backup and restore, see the [CLI documentation](Cli.md#backup-via-cli).

docs/development/Backup Restore Architecture.md

@@ -0,0 +1,251 @@
+# Backup, Restore & Settings Migration — Architecture
+
+> **Note:** This document describes the internals of the INAV Configurator's backup/restore and settings migration system. It is intended for Configurator developers, not end users. For user-facing documentation, see the [INAV docs](https://github.com/iNavFlight/inav/blob/master/docs/Backup%20and%20Restore.md).
+
+## Architecture Overview
+
+```
+User → Firmware Flasher Tab → STM32.connect(onCliReady) → CLI mode
+                                                              ↓
+                                          BackupRestore.captureCliDiffAll()
+                                                              ↓
+                                           Save to file, prune old backups
+                                                              ↓
+                                               STM32 flash (DFU or serial)
+                                                              ↓
+                                              onFlashComplete() callback
+                                                              ↓
+                                      Version check → Migration check → UI overlay
+                                                              ↓
+                                      User confirms → Poll for FC reconnect
+                                                              ↓
+                        BackupRestore.performRestore() or performRestoreWithMigration()
+                                                              ↓
+                                    saveAndReboot() or abortRestore()
+```
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `js/backup_restore.js` | Core backup/restore module — CLI protocol, file I/O, auto-backup |
+| `js/migration/migration_handler.js` | Version migration engine — profile chaining, line transformation |
+| `js/migration/7_to_8.json` | Migration profile: INAV 7.x → 8.0 |
+| `js/migration/8_to_9.json` | Migration profile: INAV 8.0 → 9.0 |
+| `tabs/firmware_flasher.js` | Flash integration — auto-backup trigger, restore UI, version gating |
+| `tabs/firmware_flasher.html` | Overlays and buttons for backup/restore/migration UI |
+| `src/css/tabs/firmware_flasher.css` | Overlay styles |
+| `js/protocols/stm32.js` | STM32 flash protocol — `onCliReady` callback, DFU timeout fix |
+| `js/main/main.js` | Electron main process — IPC handlers for file operations |
+| `js/main/preload.js` | IPC bridge — exposes backup API to renderer |
+| `locale/en/messages.json` | All i18n translation keys |
+
+## Adding a New Migration Profile
+
+When a new major INAV version is released (e.g. 9.x → 10.x), create a migration profile:
+
+### Step 1: Create the JSON profile
+
+Create `js/migration/9_to_10.json`:
+
+```json
+{
+    "fromVersion": "9",
+    "toVersion": "10",
+    "description": "INAV 9.x → 10.0 migration profile",
+
+    "commandRenames": {
+        "old_command_name": "new_command_name"
+    },
+
+    "settingRenames": {
+        "old_setting_name": "new_setting_name"
+    },
+
+    "valueReplacements": {
+        "setting_name": {
+            "OLD_VALUE": "NEW_VALUE"
+        }
+    },
+
+    "removed": [
+        "deleted_setting_1",
+        "deleted_setting_2"
+    ],
+
+    "settingPatternMappings": [
+        {
+            "pattern": "^regex_matching_setting_names$",
+            "valueMap": { "old_numeric_id": "new_numeric_id" },
+            "description": "Human-readable description of remapping"
+        }
+    ],
+
+    "warnings": [
+        "Human-readable warning about settings whose semantics changed and need manual review."
+    ]
+}
+```
+
+### Step 2: Register the profile
+
+In `js/migration/migration_handler.js`, add the import and append to the array:
+
+```javascript
+import profile_9_to_10 from './9_to_10.json';
+
+const MIGRATION_PROFILES = [
+    profile_7_to_8,
+    profile_8_to_9,
+    profile_9_to_10,   // ← add here
+];
+```
+
+The migration engine automatically chains profiles. A 7.x → 10.x upgrade will apply all three profiles in sequence (7→8, 8→9, 9→10).
+
+### How to determine what goes into a migration profile
+
+Compare CLI settings between the old and new firmware version:
+
+1. **Removed settings**: Run `diff all` on old and new firmware with default settings. Settings present in old but not in new → add to `removed`
+2. **Renamed settings**: Check INAV release notes and source code for renamed settings → add to `settingRenames`
+3. **Renamed commands**: Check for CLI command name changes (e.g. `profile` → `control_profile`) → add to `commandRenames`
+4. **Value replacements**: Check for enum value name changes → add to `valueReplacements`
+5. **Pattern mappings**: Check for bulk ID renumbering (OSD elements, etc.) → add to `settingPatternMappings`
+6. **Warnings**: Check for settings where the meaning/units changed but name stayed the same → add to `warnings`
+
+Key INAV source files to check:
+- `src/main/fc/settings.yaml` — all CLI settings definitions
+- `src/main/fc/cli.c` — CLI command implementations
+- Release notes on GitHub
+
+## Migration Profile Schema Reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `fromVersion` | `string` | Yes | Source major version number (e.g. `"9"`) |
+| `toVersion` | `string` | Yes | Target major version number (e.g. `"10"`) |
+| `description` | `string` | Yes | Human-readable description |
+| `commandRenames` | `object` | Yes | Maps old CLI command names to new names. Applied to any token in the command line. E.g. `"profile" → "control_profile"` transforms `profile 2` to `control_profile 2` |
+| `settingRenames` | `object` | Yes | Maps old `set` setting names to new names. Only applies to `set <name> = <value>` lines |
+| `valueReplacements` | `object` | Yes | Maps setting names to value replacement objects `{ "oldval": "newval" }`. Only modifies the value portion after `=` |
+| `removed` | `string[]` | Yes | List of setting names to remove entirely. Lines with `set <name> = ...` matching these are dropped |
+| `settingPatternMappings` | `array` | Yes | Array of pattern-based value remappings for settings matching a regex. Each entry has `pattern` (regex), `valueMap` (object), `description` (string) |
+| `warnings` | `string[]` | Yes | Warning messages about semantic changes requiring manual review. Displayed in migration preview overlay |
+
+## Existing Migration Profile Details
+
+### 7_to_8.json (INAV 7.x → 8.0)
+
+| Category | Changes |
+|----------|---------|
+| **Command renames** | `profile` → `control_profile` |
+| **Value replacements** | `gps_provider`: `UBLOX7` → `UBLOX` |
+| **Removed settings** (18) | `control_deadband`, `cpu_underclock`, `disarm_kill_switch`, `dji_workarounds`, `fw_iterm_limit_stick_position`, `gyro_anti_aliasing_lpf_type`, `gyro_hardware_lpf`, `gyro_main_lpf_type`, `gyro_use_dyn_lpf`, `inav_use_gps_no_baro`, `inav_use_gps_velned`, `ledstrip_visual_beeper`, `max_throttle`, `nav_auto_climb_rate`, `nav_manual_climb_rate`, `osd_stats_min_voltage_unit`, `pidsum_limit`, `pidsum_limit_yaw` |
+| **Pattern mappings** | `osd_custom_element_N_type`: IDs remapped 4→9, 5→16, 6→7, 7→10 |
+| **Warnings** | `nav_fw_wp_tracking_accuracy` semantics changed: was arbitrary tracking response, now distance in meters |
+
+### 8_to_9.json (INAV 8.0 → 9.0)
+
+| Category | Changes |
+|----------|---------|
+| **Command renames** | `controlrate_profile` → `use_control_profile` |
+| **Setting renames** | `mixer_pid_profile_linking` → `mixer_control_profile_linking`, `osd_pan_servo_pwm2centideg` → `osd_pan_servo_range_decadegrees` |
+| **Value replacements** | None |
+| **Removed settings** | None |
+| **Pattern mappings** | None |
+| **Warnings** | Position estimator defaults changed (`w_z_baro_v`, `inav_w_z_gps_p`, `inav_w_z_gps_v`). `ahrs_acc_ignore_rate` default changed 20→15 |
+
+## Migration Engine Internals
+
+### Profile chaining
+
+`buildMigrationChain(fromVersion, toVersion)` selects all profiles where `profileFrom >= fromMajor` and `profileTo <= toMajor`, sorted by `fromVersion`. A 7.x → 9.x migration applies both 7→8 and 8→9 profiles in sequence.
+
+### Line processing
+
+Each non-comment, non-empty line passes through every profile in the chain. For each profile, transformations are applied in this order:
+
+1. Command renames (any token in the line)
+2. Removed settings (line dropped if `set <name>` matches)
+3. Setting renames (`set <name>` replacement)
+4. Value replacements (value after `=` replaced)
+5. Setting pattern mappings (regex-matched settings with value remapping)
+
+### Missing profile detection
+
+`hasMissingProfiles()` returns `true` when the number of profiles in the chain is fewer than the number of major version steps. The UI shows a warning but still allows restore — some settings may fail.
+
+## Edge Cases Handled
+
+1. **Stale FC version after flash**: Real FC version is queried via `MSP_FC_VERSION` after connect, not the cached value
+2. **DFU mode (no MSP)**: `FC.CONFIG` null checks prevent crashes when connected in DFU mode
+3. **DFU timeout**: UI unlock and progress label update on timeout (no permanent lock)
+4. **Local firmware files**: `localFirmwareLoaded` flag prevents stale dropdown version from triggering wrong migration
+5. **Backup pruning with mixed versions**: Sort by timestamp portion, not full filename
+6. **Multi-step migration**: 7.x → 9.x automatically chains 7→8 + 8→9 profiles
+7. **Missing migration profiles**: Warning shown but restore allowed — graceful degradation
+8. **Version detection from backup**: Parsed from backup header (`# Version: X.Y.Z`), not from FC state
+
+## i18n Keys
+
+All backup/restore/migration translation keys in `locale/en/messages.json`:
+
+### Backup status
+| Key | Text |
+|-----|------|
+| `backupRestoreStatusEnteringCli` | Entering CLI |
+| `backupRestoreStatusReadingConfig` | Reading configuration via CLI |
+| `backupRestoreStatusSavingFile` | Saving backup file... |
+| `backupRestoreStatusExitingCli` | Exiting CLI mode |
+| `backupRestoreBackupSaved` | Backup saved $1 |
+| `backupRestoreAutoBackupSaved` | Auto-backup saved to $1 |
+| `backupRestoreBackupComplete` | Backup complete |
+| `backupRestoreBackupCancelled` | Backup cancelled |
+| `backupRestoreBackupFailed` | Backup failed |
+
+### Restore status
+| Key | Text |
+|-----|------|
+| `backupRestoreStatusConnecting` | Connecting to flight controller |
+| `backupRestoreStatusRestoringConfig` | Restoring configuration |
+| `backupRestoreStatusRestoringProgress` | Restoring... $1 / $2 |
+| `backupRestoreStatusSaving` | Saving configuration |
+| `backupRestoreRestoreComplete` | Configuration restored. Flight controller is rebooting. |
+| `backupRestoreRestoreCancelled` | Restore cancelled. |
+| `backupRestoreRestoreFailed` | Restore failed. |
+
+### Auto-restore UI
+| Key | Text |
+|-----|------|
+| `backupRestoreAutoRestoreConfirm` | Restore confirmation prompt |
+| `backupRestoreAutoRestoreWaiting` | Waiting for FC to reboot after flash |
+| `backupRestoreAutoRestoreYes` | Yes, restore settings |
+| `backupRestoreAutoRestoreNo` | No, keep current settings |
+| `backupRestoreAutoRestoreWaitingPort` | Waiting for port $1 to reconnect |
+| `backupRestoreDowngradeNoAutoRestore` | Major downgrade warning |
+| `backupRestoreFlashCompleteBackupSaved` | Backup saved (local firmware, no restore offer) |
+| `backupRestoreMigrationApplied` | Migration applied: $1 → $2 ($3 changes) |
+| `backupRestoreMigrationWarningsHeader` | Migration Warnings: |
+
+### Migration preview
+| Key | Text |
+|-----|------|
+| `migrationPreviewTitle` | Settings Migration Required |
+| `migrationPreviewSubtitle` | Conversion explanation |
+| `migrationPreviewRemovedHeader` | Removed Settings: |
+| `migrationPreviewRenamedSettingsHeader` | Renamed Settings: |
+| `migrationPreviewRenamedCommandsHeader` | Renamed Commands: |
+| `migrationPreviewValueReplacementsHeader` | Value Replacements: |
+| `migrationPreviewSettingRemappingsHeader` | Setting Remappings: |
+| `migrationPreviewContinue` | Continue with migration |
+| `migrationPreviewCancel` | Cancel restore |
+| `migrationMissingProfileWarning` | Missing profile warning |
+
+### Error messages
+| Key | Text |
+|-----|------|
+| `backupRestoreErrorTitle` | Restore Errors Detected |
+| `backupRestoreErrorText` | Error explanation |
+| `backupRestoreErrorAbort` | Abort |
+| `backupRestoreErrorSave` | Save anyway |