matlab-migrate-settings

# MATLAB Settings Migration

Diff MATLAB settings between two releases and automatically update any `.m` file that configures MATLAB settings (via `.PersonalValue` or `.TemporaryValue` assignments) so that setting paths point to the correct locations in the target release. Works with startup scripts, team preference files, test setup scripts, deployment configs, or any code that programmatically sets MATLAB settings.

## When To Use

- Upgrading MATLAB releases and existing `.m` scripts set `PersonalValue` or `TemporaryValue` on settings whose paths changed between releases
- Setting paths moved, were renamed, or had their value types changed between the source and target release
- Migrating startup scripts, team preference files, test setup, or deployment configs to a newer (or older) MATLAB release

## When Not To Use

- The `.m` file does not set any MATLAB settings (`s.PersonalValue` / `s.TemporaryValue` assignments)
- You want to change MATLAB preferences interactively (use the Preferences dialog instead)
- You need to migrate Simulink or toolbox-specific settings (this skill covers core MATLAB settings only)

## Arguments

- `<script-path>` — **(required)** Path to any `.m` file that sets PersonalValue/TemporaryValue on MATLAB settings
- `[from:R20XXy]` or `[from:/path/to/MATLAB/R20XXy]` — *(optional)* Source release the script was written for. Accepts either a release name (e.g., `R2025b`) which is resolved to the platform default install location, or a full path to a MATLAB installation root. If omitted, auto-detected from script content.
- `[to:R20XXy]` or `[to:/path/to/MATLAB/R20XXy]` — *(optional)* Target release to migrate to. Accepts either a release name or a full path to a MATLAB installation root. If omitted, defaults to the **latest** installed MATLAB release on this machine.

**Examples:**
```
/matlab-settings-migrate ~/startup.m
/matlab-settings-migrate ~/startup.m from:R2025b to:R2026a
/matlab-settings-migrate ~/startup.m to:R2025a
/matlab-settings-migrate ./test/setup_prefs.m from:/opt/matlab/R2025b to:/opt/matlab/R2026a
/matlab-settings-migrate ~/team_settings.m from:/network/apps/MATLAB/R2024b to:R2026a
```

**Default behavior (no from/to):** Detect the source release from the script, then migrate to the newest installed MATLAB release. If you want to migrate to an older release (downgrade), specify `to:` explicitly.

## Argument parsing

Parse the arguments string to extract:
1. The script path (first argument that looks like a file path)
2. Optional `from:` value — either a release name (`R20XXy`) or a full path (`/path/to/MATLAB/R20XXy`)
3. Optional `to:` value — either a release name (`R20XXy`) or a full path (`/path/to/MATLAB/R20XXy`)

**Path resolution:** If the value after `from:` or `to:` starts with `/`, `~`, or a drive letter (e.g., `C:\`), treat it as a full path to a MATLAB installation root. Otherwise, treat it as a release name and resolve it to a full path using the platform-specific default install location (determined in Phase 0).

If only the script path is provided, run Phase 0 (auto-discovery).

## Phase 0: Auto-detect MATLAB installations (skip if both roots provided)

If `from:` or `to:` are missing, auto-detect installed MATLAB releases. Read `references/auto-detect-installations.md` for the full procedure (platform detection, folder scanning, source/target resolution). Key behavior:
- Detect platform via `uname -s` → determines default install directory
- List installed releases by scanning the default directory for `R20*` folders
- Source release: detected from script content (filename hints, comments, or key matching against SO/DLLs)
- Target release: defaults to the latest installed release (unless `to:` was explicit)
- Downgrade requires explicit `to:` — default always goes to the latest

## How to execute

**Performance constraint:** Minimize tool calls. Target ≤6 total bash/read invocations for the entire migration. Batch aggressively — never check settings one-by-one in separate commands. Phase 1 setup (find libs, extract strings, diff) and Phase 2 (read startup script) are independent and MUST run in parallel.

### Phase 1: Build the settings change map

Produce the full change map (renamed, moved, removed, added) between releases.

#### Step 1: Validate paths and determine source format

Check for `.hpp` source files first (available on some Linux installs):
```
OLD_HPP=<old-matlab-root>/toolbox/matlab/settings/matlab_factory_settings
NEW_HPP=<new-matlab-root>/toolbox/matlab/settings/matlab_factory_settings
```

If `.hpp` files exist in both, use the **HPP path** (Step 2A).
If `.hpp` files do NOT exist (common on Windows where they are compiled to DLLs), use the **DLL path** (Step 2B).

To locate the shared library (extension depends on platform detected in Phase 0):
```bash
# Linux: .so | macOS: .dylib | Windows: .dll
find "<matlab-root>/bin" -path "*factory_settings*" -name "mwmatlab_factory_settings.*" 2>/dev/null
# Typical paths:
#   Linux:   <root>/bin/glnxa64/factory_settings/compute/settings/matlab/mwmatlab_factory_settings.so
#   macOS:   <root>/bin/maci64/factory_settings/compute/settings/matlab/mwmatlab_factory_settings.dylib
#   Windows: <root>/bin/win64/factory_settings/compute/settings/matlab/mwmatlab_factory_settings.dll
```

#### Step 2A: HPP path (plain-text source available)

##### File-level diff

Compare which `.hpp` files exist in each release:
```bash
ls "$OLD_HPP"/*.hpp | xargs -I{} basename {} | sort > /tmp/hpp_old.txt
ls "$NEW_HPP"/*.hpp | xargs -I{} basename {} | sort > /tmp/hpp_new.txt
comm -23 /tmp/hpp_old.txt /tmp/hpp_new.txt   # files only in OLD (removed)
comm -13 /tmp/hpp_old.txt /tmp/hpp_new.txt   # files only in NEW (added)
```

For any NEWLY added `.hpp` file, read it and list all settings it defines.
For any REMOVED `.hpp` file, read it from OLD and list all settings.

##### Extract all setting names with namespace context

For EACH `.hpp` file that exists in BOTH releases, extract `addSetting` an