Feature: Custom Installation Directory & Post-Install Directory Migration (Velopack --installto & In-App Migration)

[undead2146]

Problem Statement & Context

GenHub currently installs by default to the user profile directory (%LOCALAPPDATA%\GenHub on Windows and ~/.local/share/GenHub on Linux) via Velopack's one-click setup.

Many players have limited storage capacity on their primary system partition (C: drive) and prefer to install games, mod organizers, and content launchers on secondary high-capacity drives (e.g. D:\Games\GenHub\).

Currently:

1. First-Install Limitation: While Velopack supports the --installto <path> CLI parameter (e.g. GenHub-Setup.exe --installto "D:\Games\GenHub"), this is neither documented for end-users nor surfaced in standard installation instructions.
2. Post-Install Migration: Once GenHub is installed to the default C: drive, there is no built-in option or UI workflow in GenHub to migrate the application and its installation directory to a different drive/folder without manual uninstall/reinstall and reconfiguring content/CAS locations.

---

User Stories & Use Cases

• UC-1 (First Install Custom Location): As a user with a small C: drive SSD, I want to install GenHub to a custom drive/directory (via installer parameter or guided setup) so that the application binaries and updates do not consume space on my primary OS partition.
• UC-2 (Post-Install Migration): As an existing GenHub user, I want a settings option to safely migrate my current GenHub installation to a different drive/folder without losing my game profiles, CAS pool, settings, or desktop shortcuts.
• UC-3 (Update Compatibility): When GenHub is installed in or migrated to a custom directory, subsequent automatic updates via VelopackUpdateManager must continue updating within the custom directory instead of falling back to %LOCALAPPDATA%\GenHub\.
• UC-4 (Shortcut & URI Scheme Re-registration): After migrating the installation directory, all Start Menu, Desktop shortcuts, and genhub:// protocol handlers should be updated to point to the new executable path.

---

Proposed Technical Scope

1. Documentation & Installer Support

• Document the --installto <path> command-line argument in docs/velopack-integration.md and release download notes.
• Verify Velopack installer behavior when custom target paths are provided on Windows and Linux.

2. In-App Migration Workflow (Settings > Storage / General)

• Add a "Migrate Installation Location" action in Settings.
• Workflow:
  1. User selects target folder via directory picker dialog.
  2. Perform pre-flight checks (disk space validation, write permissions, ensuring no game instances or locking processes are active).
  3. Invoke migration routine that stages files, moves application packages and binaries, and updates shortcut / URI scheme registrations.
  4. Relaunch GenHub from the new directory.

3. Integrated CAS Pool & Workspace Storage Prompt

• When relocating the application directory, offer the user an option to also relocate the local CAS pool and workspace directory to the new target drive to free up the C: drive.

---

Acceptance Criteria

• Document --installto argument in user and developer documentation (docs/velopack-integration.md).
• Verify VelopackUpdateManager update cycle functions seamlessly in custom install directories.
• Provide an in-app migration tool/flow to move GenHub installation directory to another drive.
• Ensure shortcuts and genhub:// URI scheme handler are updated upon migration.
• Test cross-drive migration and rollback on failure without data loss.

[coderabbitai]

Coding Plan

Summary

• Document the --installto first-install option in docs/velopack-integration.md and release notes, and record the verified custom-directory update behavior.
• Add a new IStorageMigrationService that runs pre-flight checks (disk space, write permission, active processes), moves GenHub data with copy-then-delete rollback safety, optionally relocates CAS and workspace storage by repointing settings, moves the whole Velopack root through the existing external helper scripts, and relaunches GenHub from the new path.
• Surface a "Migrate Installation" section in Settings that reuses the folder-picker, confirmation-dialog, progress, and notification patterns.
• Repair profile shortcuts after relaunch by recreating them, and rely on the existing self-healing UriSchemeRegistrar for the genhub:// handler on Windows.

File-Level Change Summary

• docs/velopack-integration.md: add --installto subsection, correct the Linux AppImage claim, add a custom-directory troubleshooting entry, and note the URI-scheme self-heal behavior.
• .github/workflows/release.yml: mention --installto in the release notes body.
• GenHub.Core/Interfaces/.../IStorageMigrationService.cs: new interface.
• GenHub.Core/Models/Storage/: new pre-flight result and progress models.
• GenHub/Common/Services/StorageMigrationService.cs (or GenHub/Features/Storage/Services/): new service implementing pre-flight, data move, optional CAS/workspace relocation, Velopack root move, and relaunch.
• GenHub/Infrastructure/DependencyInjection/StorageMigrationModule.cs: new DI module; register it in AppServices.cs.
• GenHub.Windows/Resources/update_genhub.ps1, GenHub.Linux/Resources/update_genhub.sh: wire up extraction, placeholder substitution, and execution (no logic rewrite; these already implement the required pattern).
• GenHub.Core/Constants/SettingsConstants.cs: add SectionMigrateInstallation.
• GenHub/Features/Settings/ViewModels/SettingsViewModel.cs: add properties, BrowseMigrationTargetPath, and MigrateInstallationLocation commands; inject IStorageMigrationService.
• GenHub/Features/Settings/Views/SettingsView.axaml and SettingsView.axaml.cs: add the migration expander and section mapping.
• Shortcut-repair invocation near GenHub.Windows/Program.cs / GenHub.Linux/Program.cs startup, iterating profiles through IShortcutService.

Follow-up Agent Instructions

• Verify on Windows that moving the full Velopack root (with Update.exe, app-{version}, packages) keeps VelopackUpdateManager.CheckForUpdatesAsync and ApplyUpdatesAndRestart working from the new directory.
• Test cross-drive migration (different volume) and same-drive migration (rename path), and confirm rollback leaves the source intact on failure.
• Confirm the pre-flight active-process check blocks migration while a game runs.
• Confirm shortcuts and the genhub:// handler resolve to the new executable after relaunch.

Design Choices

Design Choice 1: How does the workflow move the Velopack-managed binary tree while GenHub runs from inside it?

Options Considered:

1. Use an external helper process/script that waits for GenHub to exit, moves the entire Velopack root, then relaunches GenHub from the new path. The repository already contains parameterized update_genhub.ps1/update_genhub.sh templates for this exact pattern.
2. Uninstall through Update.exe --uninstall, then run Setup.exe --installto <new path>, and restore data afterward.
3. Migrate only GenHub data directories (repoint CAS, workspace, and data paths) and leave the Velopack binaries in place.

Chosen Option: 1

Rationale: Option 1 satisfies the ticket requirement to move binaries and packages, reuses the existing helper-script scaffolding, and keeps the Velopack root intact so updates continue to work after relaunch. The running process cannot move its own executing binaries. Velopack exposes no documented "relocate installation" API. A separate mechanism must move the tree after GenHub exits.

Design Choice 2: Which directories does the migration move, and how does Velopack find the new root for future updates?

Options Considered:

1. Move the entire top-level GenHub root as one unit (Velopack binaries plus data), preserving internal structure, so Velopack's default locator resolves the new root automatically after relaunch.
2. Move Velopack binaries and data separately with independent settings repointing.

Chosen Option: 1

Rationale: Moving the whole root intact preserves Update.exe, app-{version}, and packages relative to the app, so Velopack updates continue in the custom directory without extra locator configuration (satisfies UC-3). The Velopack root and GenHub data root share the same parent. Future updates must resolve the new root.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Document and Verify Custom Install Support

This phase documents the --installto first-install path and records the verified update behavior in a custom directory. It requires no code changes.

Task 1: Document the `--installto` argument

Add end-user and developer documentation for custom first-install locations.

• Update docs/velopack-integration.md. Add a ### Custom Installation Path (--installto) subsection under the existing ## Installation Locations section.
• State the Windows usage: GenHub-win-Setup.exe --installto "D:\Games\GenHub". Note the short form -t, and that application arguments must follow --.
• State that Velopack installs per-user under %LOCALAPPDATA%\GenHub by default, and that --installto overrides this at install time.
• Describe the Linux situation accurately. Note that the repository CI (.github/workflows/release.yml) currently produces only .nupkg release-feed metadata for Linux and no AppImage or installer, so no Linux install-location picker exists. Correct the outdated AppImage claim in the same document.
• Add a ### Custom Installation Directory troubleshooting entry under ## Troubleshooting that confirms updates continue inside the custom directory because Velopack resolves the root from the running executable location.

Task 2: Add custom-path notes to release download instructions

Surface the --installto option where users obtain the installer.

• Update the GitHub Release notes template in .github/workflows/release.yml (the create-release job body) to mention the --installto option next to the GenHub-win-Setup.exe download link.

🤖 Prompt for AI agents

Implement Phase 1: document custom install support for GenHub. This phase
requires no code changes, only documentation updates.

- In `docs/velopack-integration.md`, add a `### Custom Installation Path
(--installto)` subsection under the existing `## Installation Locations`
section.
- State the Windows usage: `GenHub-win-Setup.exe --installto "D:\Games\GenHub"`.
Note the short form `-t`, and note that application arguments must follow `--`.
- State that Velopack installs per-user under `%LOCALAPPDATA%\GenHub` by
default, and that `--installto` overrides this at install time.
- Describe the Linux situation accurately: the CI workflow
`.github/workflows/release.yml` currently produces only `.nupkg` release-feed
metadata for Linux, with no AppImage or installer, so no Linux install-location
picker exists. Correct the outdated AppImage claim in the same document.
- In the same document, add a `### Custom Installation Directory`
troubleshooting entry under `## Troubleshooting` confirming that updates
continue inside the custom directory because Velopack resolves the root from the
running executable location.
- In `.github/workflows/release.yml`, update the GitHub Release notes template
in the `create-release` job body to mention the `--installto` option next to the
`GenHub-win-Setup.exe` download link.

Phase 2: Migration Core Service and Relaunch Helper

This phase adds the backend that performs pre-flight validation, moves data directories, optionally relocates CAS and workspace storage, moves the Velopack root through an external helper, and relaunches GenHub. The service keeps all file operations out of the UI layer, consistent with existing architecture.

Task 1: Define the migration service contract and models

Create the interface and supporting models for the migration workflow.

• Add IStorageMigrationService in GenHub.Core/Interfaces/Common/ (or a new GenHub.Core/Interfaces/Storage/ entry alongside existing storage interfaces).
• Expose methods for pre-flight validation, for planning the migration, and for executing the migration with IProgress<T> progress reporting and a CancellationToken.
• Add result and progress models under GenHub.Core/Models/Storage/ (for example a pre-flight result carrying disk-space, write-permission, and active-process outcomes, and a progress model carrying stage name and percentage). Reuse existing OperationResult<T> for outcomes.
• Include an option flag in the migration request that indicates whether to also relocate the CAS pool and workspace directories.

Task 2: Implement pre-flight checks

Validate the target before any files move.

• Create StorageMigrationService in GenHub/Common/Services/ (or GenHub/Features/Storage/Services/).
• Check available disk space on the target volume against the measured size of the source root.
• Check write permission at the target using the existing IStorageWritabilityProbe.
• Check that no game or profile is running. Call ILaunchRegistry.GetAllActiveLaunchesAsync() and, as a secondary check, IGameProcessManager.GetActiveProcessesAsync(). Fail pre-flight if either returns active entries.
• Reject targets that resolve inside the current application directory, reusing the guard concept from CasPoolManager.IsInsideApplicationDirectory.

Task 3: Implement data and optional CAS/workspace migration

Move GenHub data with safe copy-and-verify semantics and support rollback.

• In StorageMigrationService, implement the move of GenHub data subdirectories using the move-with-copy-fallback pattern from ConfigurationProviderService.MigrateDirectory/MigrateFile and the primitives in FileOperationsService (AreSameVolume, lock-aware CopyFileAsync, DeleteDirectoryIfExists).
• Stage files first, verify the copy, then delete the source, so a failure at any point leaves the source intact for rollback (satisfies the rollback acceptance criterion).
• When the CAS/workspace relocation option is set, move the CAS pool and workspace directories, then repoint UserSettings.CasConfiguration paths and UserSettings.WorkspacePath through IUserSettingsService.TryUpdateAndSaveAsync. Call ICasPoolManager.ReinitializeInstallationPool() after the settings update so CAS resolves the new root.
• When the CAS/workspace relocation option is not set, leave those paths unchanged.
• Update UserSettings.ApplicationDataPath if the data root moves as part of the migration.

Task 4: Move the Velopack root and relaunch through an external helper

Move the running application binaries after GenHub exits, then relaunch.

• Wire up the existing embedded helper scripts GenHub.Windows/Resources/update_genhub.ps1 and GenHub.Linux/Resources/update_genhub.sh. Extract each with GetManifestResourceStream, substitute the {{SOURCE_DIR}}, {{TARGET_DIR}}, {{CURRENT_EXE}}, {{BACKUP_DIR}}, {{PROCESS_ID}}, and {{LOG_FILE}} placeholders, and write the script to a temporary location.
• Compute the Velopack root as the parent of AppContext.BaseDirectory. Pass the whole root as {{SOURCE_DIR}} and the chosen new root as {{TARGET_DIR}} so the entire tree (Update.exe, app-{version}, packages) moves intact.
• Set {{CURRENT_EXE}} to the executable path inside the new target so the helper relaunches GenHub from the new location.
• Start the helper as a detached process, then exit GenHub so the helper can move the locked binaries. The helper backs up the target, copies the source, relaunches GenHub, and self-deletes, with backup restore on failure.
• Keep the platform-specific helper selection behind the service so the UI stays platform-agnostic.

Task 5: Register the migration service in dependency injection

Add the service to the DI graph following existing module conventions.

• Add a new StorageMigrationModule.cs in GenHub/Infrastructure/DependencyInjection/ that registers IStorageMigrationService as a singleton, following the pattern in CasModule.cs.
• Register the module in AppServices.ConfigureApplicationServices after AddCasServices() and AddGameInstallation(), since the service depends on storage and installation services.

🤖 Prompt for AI agents

Implement Phase 2: build the backend migration service and relaunch helper
wiring, keeping all file operations out of the UI layer.

1. Contract and models:
- Add `IStorageMigrationService` in `GenHub.Core/Interfaces/Common/` (or a new
`GenHub.Core/Interfaces/Storage/` entry alongside existing storage interfaces).
- Expose methods for pre-flight validation, for planning the migration, and for
executing the migration with `IProgress<T>` progress reporting and a
`CancellationToken`.
- Add result and progress models under `GenHub.Core/Models/Storage/`: a
pre-flight result model carrying disk-space, write-permission, and
active-process outcomes, and a progress model carrying stage name and
percentage. Reuse the existing `OperationResult<T>` for outcomes.
- Include an option flag in the migration request that indicates whether to also
relocate the CAS pool and workspace directories.

2. Pre-flight checks:
- Create `StorageMigrationService` in `GenHub/Common/Services/` (or
`GenHub/Features/Storage/Services/`).
- Check available disk space on the target volume against the measured size of
the source root.
- Check write permission at the target using the existing
`IStorageWritabilityProbe`.
- Check that no game or profile is running by calling
`ILaunchRegistry.GetAllActiveLaunchesAsync()` and, as a secondary check,
`IGameProcessManager.GetActiveProcessesAsync()`. Fail pre-flight if either
returns active entries.
- Reject targets that resolve inside the current application directory, reusing
the guard concept from `CasPoolManager.IsInsideApplicationDirectory`.

3. Data and optional CAS/workspace migration:
- Implement the move of GenHub data subdirectories using the
move-with-copy-fallback pattern from
`ConfigurationProviderService.MigrateDirectory`/`MigrateFile` and the primitives
in `FileOperationsService` (`AreSameVolume`, lock-aware `CopyFileAsync`,
`DeleteDirectoryIfExists`).
- Stage files first, verify the copy, then delete the source, so a failure at
any point leaves the source intact for rollback.
- When the CAS/workspace relocation option is set, move the CAS pool and
workspace directories, then repoint `UserSettings.CasConfiguration` paths and
`UserSettings.WorkspacePath` through
`IUserSettingsService.TryUpdateAndSaveAsync`, and call
`ICasPoolManager.ReinitializeInstallationPool()` after the settings update.
- When the CAS/workspace relocation option is not set, leave those paths
unchanged.
- Update `UserSettings.ApplicationDataPath` if the data root moves as part of
the migration.

4. Velopack root move and relaunch:
- Wire up the existing embedded helper scripts
`GenHub.Windows/Resources/update_genhub.ps1` and
`GenHub.Linux/Resources/update_genhub.sh`. Extract each with
`GetManifestResourceStream`, substitute the `{{SOURCE_DIR}}`, `{{TARGET_DIR}}`,
`{{CURRENT_EXE}}`, `{{BACKUP_DIR}}`, `{{PROCESS_ID}}`, and `{{LOG_FILE}}`
placeholders, and write the script to a temporary location.
- Compute the Velopack root as the parent of `AppContext.BaseDirectory`. Pass
the whole root as `{{SOURCE_DIR}}` and the chosen new root as `{{TARGET_DIR}}`
so the entire tree (`Update.exe`, `app-{version}`, `packages`) moves intact.
- Set `{{CURRENT_EXE}}` to the executable path inside the new target so the
helper relaunches GenHub from the new location.
- Start the helper as a detached process, then exit GenHub so the helper can
move the locked binaries. The helper backs up the target, copies the source,
relaunches GenHub, and self-deletes, with backup restore on failure.
- Keep platform-specific helper selection behind the service so the UI stays
platform-agnostic.

5. Dependency injection:
- Add `StorageMigrationModule.cs` in
`GenHub/Infrastructure/DependencyInjection/` that registers
`IStorageMigrationService` as a singleton, following the pattern in
`CasModule.cs`.
- Register the module in `AppServices.ConfigureApplicationServices` after
`AddCasServices()` and `AddGameInstallation()`.

Phase 3: Settings Migration UI

This phase adds the user-facing migration action in Settings. It reuses the existing section, folder-picker, confirmation-dialog, and notification patterns.

Task 1: Add a "Migrate Installation" settings section

Surface the migration entry point in the Settings screen.

• Add a SectionMigrateInstallation constant to GenHub.Core/Constants/SettingsConstants.cs.
• Add a matching SettingsSectionItem to the Sections list in SettingsViewModel.cs.
• Add an Expander_MigrateInstallation mapping in the ScrollToSection switch in SettingsView.axaml.cs.
• Add the corresponding <Expander x:Name="Expander_MigrateInstallation"> block in SettingsView.axaml, following the layout of Expander_DataDirectories. Include a target-path TextBox, a browse button, a checkbox for the optional CAS/workspace relocation, and a migrate button using the danger-button style.

Task 2: Add migration view-model command and progress

Drive the workflow from SettingsViewModel and report progress.

• Add observable properties in SettingsViewModel.cs for the migration target path, the CAS/workspace relocation flag, and progress state.
• Add a BrowseMigrationTargetPath [RelayCommand] that reuses the OpenFolderPickerAsync pattern from BrowseCasRootPath.
• Add a MigrateInstallationLocation [RelayCommand] that runs pre-flight checks through IStorageMigrationService, shows a confirmation dialog through IDialogService.ShowConfirmationAsync (Danger-Zone style, stating that GenHub will move data and restart), then executes the migration with progress reporting.
• Report pre-flight failures and outcomes through INotificationService.
• Inject IStorageMigrationService into SettingsViewModel.

🤖 Prompt for AI agents

Implement Phase 3: add a user-facing "Migrate Installation" section in Settings,
reusing existing section, folder-picker, confirmation-dialog, and notification
patterns.

1. Section wiring:
- Add a `SectionMigrateInstallation` constant to
`GenHub.Core/Constants/SettingsConstants.cs`.
- Add a matching `SettingsSectionItem` to the `Sections` list in
`SettingsViewModel.cs`.
- Add an `Expander_MigrateInstallation` mapping in the `ScrollToSection` switch
in `SettingsView.axaml.cs`.
- Add the corresponding `<Expander x:Name="Expander_MigrateInstallation">` block
in `SettingsView.axaml`, following the layout of `Expander_DataDirectories`.
Include a target-path `TextBox`, a browse button, a checkbox for the optional
CAS/workspace relocation, and a migrate button using the `danger-button` style.

2. View-model command and progress:
- Add observable properties in `SettingsViewModel.cs` for the migration target
path, the CAS/workspace relocation flag, and progress state.
- Add a `BrowseMigrationTargetPath` `[RelayCommand]` that reuses the
`OpenFolderPickerAsync` pattern from `BrowseCasRootPath`.
- Add a `MigrateInstallationLocation` `[RelayCommand]` that runs pre-flight
checks through `IStorageMigrationService`, shows a confirmation dialog through
`IDialogService.ShowConfirmationAsync` (Danger-Zone style, stating GenHub will
move data and restart), and then executes the migration with progress reporting.
- Report pre-flight failures and outcomes through `INotificationService`.
- Inject `IStorageMigrationService` into `SettingsViewModel`.

Phase 4: Shortcut and URI Scheme Re-registration

This phase updates shortcuts and the genhub:// handler so they point to the new executable path after migration.

Task 1: Repair desktop shortcuts after migration

Recreate existing profile shortcuts to point to the new executable.

• Add a shortcut-repair step invoked as part of, or immediately after, the migration relaunch. Because shortcut targets embed Environment.ProcessPath at creation time, iterate stored GameProfile entries, check IShortcutService.ShortcutExistsAsync, and call IShortcutService.CreateDesktopShortcutAsync again for each so the target updates to the new path.
• Perform this step after relaunch, when Environment.ProcessPath already resolves to the new location. Model the invocation on the startup call pattern used by UriSchemeRegistrar.Register in GenHub.Windows/Program.cs.
• Note that MacOSShortcutService does not implement creation; skip shortcut repair on macOS.

Task 2: Re-register the `genhub://` URI scheme

Ensure the protocol handler points to the new executable.

• No new work is required on Windows. UriSchemeRegistrar.Register already runs on every primary-instance launch in GenHub.Windows/Program.cs and rewrites the handler when the stored command differs from Environment.ProcessPath. After relaunch from the new path, it self-heals.
• Confirm this behavior in a test and document it. Note in docs/velopack-integration.md that Linux and macOS have no genhub:// registration today, so no re-registration is needed there.

🤖 Prompt for AI agents

Implement Phase 4: update shortcuts and the `genhub://` handler so they point to
the new executable path after migration.

1. Shortcut repair:
- Add a shortcut-repair step invoked as part of, or immediately after, the
migration relaunch.
- Because shortcut targets embed `Environment.ProcessPath` at creation time,
iterate stored `GameProfile` entries, check
`IShortcutService.ShortcutExistsAsync`, and call
`IShortcutService.CreateDesktopShortcutAsync` again for each so the target
updates to the new path.
- Perform this step after relaunch, when `Environment.ProcessPath` already
resolves to the new location. Model the invocation on the startup call pattern
used by `UriSchemeRegistrar.Register` in `GenHub.Windows/Program.cs`.
- Skip shortcut repair on macOS because `MacOSShortcutService` does not
implement creation.

2. URI scheme re-registration:
- Do not add new work for Windows. `UriSchemeRegistrar.Register` already runs on
every primary-instance launch in `GenHub.Windows/Program.cs` and rewrites the
handler when the stored command differs from `Environment.ProcessPath`; it
self-heals after relaunch from the new path.
- Add a test that confirms this self-heal behavior and document it.
- In `docs/velopack-integration.md`, note that Linux and macOS have no
`genhub://` registration today, so no re-registration is needed there.

Research

GenHub is an Avalonia desktop application with per-platform startup projects (GenHub.Windows, GenHub.Linux, GenHub.MacOS) and a shared core (GenHub, GenHub.Core). Velopack drives install and update. VelopackUpdateManager delegates all install-location awareness to Velopack's default locator, which resolves the current root from AppContext.BaseDirectory. On Windows the Velopack root is %LOCALAPPDATA%\GenHub and contains Update.exe, versioned app-{version} folders, and a packages cache. GenHub's own data root (%LOCALAPPDATA%\GenHub via AppConfiguration.GetConfiguredDataPath) is the same parent that Velopack owns. CAS and workspace paths resolve through StorageLocationService and CasConfiguration; these services repoint paths but never move files. ConfigurationProviderService.MigrateDirectory/MigrateFile provide a reusable move-with-copy-fallback primitive. FileOperationsService provides AreSameVolume and lock-aware CopyFileAsync. Settings UI uses SettingsViewModel plus SettingsView.axaml, section metadata in SettingsConstants, folder pickers via OpenFolderPickerAsync, and confirmation dialogs via IDialogService. IShortcutService bakes Environment.ProcessPath at shortcut creation and has no repair routine. UriSchemeRegistrar (Windows only) self-heals the genhub:// handler on every startup. Orphaned parameterized helper scripts update_genhub.ps1/update_genhub.sh implement a "wait for process exit → back up → copy → relaunch → self-delete" pattern but are not wired to any code.

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement Phase 1: document custom install support for GenHub. This phase
requires no code changes, only documentation updates.

- In `docs/velopack-integration.md`, add a `### Custom Installation Path
(--installto)` subsection under the existing `## Installation Locations`
section.
- State the Windows usage: `GenHub-win-Setup.exe --installto "D:\Games\GenHub"`.
Note the short form `-t`, and note that application arguments must follow `--`.
- State that Velopack installs per-user under `%LOCALAPPDATA%\GenHub` by
default, and that `--installto` overrides this at install time.
- Describe the Linux situation accurately: the CI workflow
`.github/workflows/release.yml` currently produces only `.nupkg` release-feed
metadata for Linux, with no AppImage or installer, so no Linux install-location
picker exists. Correct the outdated AppImage claim in the same document.
- In the same document, add a `### Custom Installation Directory`
troubleshooting entry under `## Troubleshooting` confirming that updates
continue inside the custom directory because Velopack resolves the root from the
running executable location.
- In `.github/workflows/release.yml`, update the GitHub Release notes template
in the `create-release` job body to mention the `--installto` option next to the
`GenHub-win-Setup.exe` download link.
===============================================================================

Task: 2

Implement Phase 2: build the backend migration service and relaunch helper
wiring, keeping all file operations out of the UI layer.

1. Contract and models:
- Add `IStorageMigrationService` in `GenHub.Core/Interfaces/Common/` (or a new
`GenHub.Core/Interfaces/Storage/` entry alongside existing storage interfaces).
- Expose methods for pre-flight validation, for planning the migration, and for
executing the migration with `IProgress<T>` progress reporting and a
`CancellationToken`.
- Add result and progress models under `GenHub.Core/Models/Storage/`: a
pre-flight result model carrying disk-space, write-permission, and
active-process outcomes, and a progress model carrying stage name and
percentage. Reuse the existing `OperationResult<T>` for outcomes.
- Include an option flag in the migration request that indicates whether to also
relocate the CAS pool and workspace directories.

2. Pre-flight checks:
- Create `StorageMigrationService` in `GenHub/Common/Services/` (or
`GenHub/Features/Storage/Services/`).
- Check available disk space on the target volume against the measured size of
the source root.
- Check write permission at the target using the existing
`IStorageWritabilityProbe`.
- Check that no game or profile is running by calling
`ILaunchRegistry.GetAllActiveLaunchesAsync()` and, as a secondary check,
`IGameProcessManager.GetActiveProcessesAsync()`. Fail pre-flight if either
returns active entries.
- Reject targets that resolve inside the current application directory, reusing
the guard concept from `CasPoolManager.IsInsideApplicationDirectory`.

3. Data and optional CAS/workspace migration:
- Implement the move of GenHub data subdirectories using the
move-with-copy-fallback pattern from
`ConfigurationProviderService.MigrateDirectory`/`MigrateFile` and the primitives
in `FileOperationsService` (`AreSameVolume`, lock-aware `CopyFileAsync`,
`DeleteDirectoryIfExists`).
- Stage files first, verify the copy, then delete the source, so a failure at
any point leaves the source intact for rollback.
- When the CAS/workspace relocation option is set, move the CAS pool and
workspace directories, then repoint `UserSettings.CasConfiguration` paths and
`UserSettings.WorkspacePath` through
`IUserSettingsService.TryUpdateAndSaveAsync`, and call
`ICasPoolManager.ReinitializeInstallationPool()` after the settings update.
- When the CAS/workspace relocation option is not set, leave those paths
unchanged.
- Update `UserSettings.ApplicationDataPath` if the data root moves as part of
the migration.

4. Velopack root move and relaunch:
- Wire up the existing embedded helper scripts
`GenHub.Windows/Resources/update_genhub.ps1` and
`GenHub.Linux/Resources/update_genhub.sh`. Extract each with
`GetManifestResourceStream`, substitute the `{{SOURCE_DIR}}`, `{{TARGET_DIR}}`,
`{{CURRENT_EXE}}`, `{{BACKUP_DIR}}`, `{{PROCESS_ID}}`, and `{{LOG_FILE}}`
placeholders, and write the script to a temporary location.
- Compute the Velopack root as the parent of `AppContext.BaseDirectory`. Pass
the whole root as `{{SOURCE_DIR}}` and the chosen new root as `{{TARGET_DIR}}`
so the entire tree (`Update.exe`, `app-{version}`, `packages`) moves intact.
- Set `{{CURRENT_EXE}}` to the executable path inside the new target so the
helper relaunches GenHub from the new location.
- Start the helper as a detached process, then exit GenHub so the helper can
move the locked binaries. The helper backs up the target, copies the source,
relaunches GenHub, and self-deletes, with backup restore on failure.
- Keep platform-specific helper selection behind the service so the UI stays
platform-agnostic.

5. Dependency injection:
- Add `StorageMigrationModule.cs` in
`GenHub/Infrastructure/DependencyInjection/` that registers
`IStorageMigrationService` as a singleton, following the pattern in
`CasModule.cs`.
- Register the module in `AppServices.ConfigureApplicationServices` after
`AddCasServices()` and `AddGameInstallation()`.
===============================================================================

Task: 3

Implement Phase 3: add a user-facing "Migrate Installation" section in Settings,
reusing existing section, folder-picker, confirmation-dialog, and notification
patterns.

1. Section wiring:
- Add a `SectionMigrateInstallation` constant to
`GenHub.Core/Constants/SettingsConstants.cs`.
- Add a matching `SettingsSectionItem` to the `Sections` list in
`SettingsViewModel.cs`.
- Add an `Expander_MigrateInstallation` mapping in the `ScrollToSection` switch
in `SettingsView.axaml.cs`.
- Add the corresponding `<Expander x:Name="Expander_MigrateInstallation">` block
in `SettingsView.axaml`, following the layout of `Expander_DataDirectories`.
Include a target-path `TextBox`, a browse button, a checkbox for the optional
CAS/workspace relocation, and a migrate button using the `danger-button` style.

2. View-model command and progress:
- Add observable properties in `SettingsViewModel.cs` for the migration target
path, the CAS/workspace relocation flag, and progress state.
- Add a `BrowseMigrationTargetPath` `[RelayCommand]` that reuses the
`OpenFolderPickerAsync` pattern from `BrowseCasRootPath`.
- Add a `MigrateInstallationLocation` `[RelayCommand]` that runs pre-flight
checks through `IStorageMigrationService`, shows a confirmation dialog through
`IDialogService.ShowConfirmationAsync` (Danger-Zone style, stating GenHub will
move data and restart), and then executes the migration with progress reporting.
- Report pre-flight failures and outcomes through `INotificationService`.
- Inject `IStorageMigrationService` into `SettingsViewModel`.
===============================================================================

Task: 4

Implement Phase 4: update shortcuts and the `genhub://` handler so they point to
the new executable path after migration.

1. Shortcut repair:
- Add a shortcut-repair step invoked as part of, or immediately after, the
migration relaunch.
- Because shortcut targets embed `Environment.ProcessPath` at creation time,
iterate stored `GameProfile` entries, check
`IShortcutService.ShortcutExistsAsync`, and call
`IShortcutService.CreateDesktopShortcutAsync` again for each so the target
updates to the new path.
- Perform this step after relaunch, when `Environment.ProcessPath` already
resolves to the new location. Model the invocation on the startup call pattern
used by `UriSchemeRegistrar.Register` in `GenHub.Windows/Program.cs`.
- Skip shortcut repair on macOS because `MacOSShortcutService` does not
implement creation.

2. URI scheme re-registration:
- Do not add new work for Windows. `UriSchemeRegistrar.Register` already runs on
every primary-instance launch in `GenHub.Windows/Program.cs` and rewrites the
handler when the stored command differs from `Environment.ProcessPath`; it
self-heals after relaunch from the new path.
- Add a test that confirms this self-heal behavior and document it.
- In `docs/velopack-integration.md`, note that Linux and macOS have no
`genhub://` registration today, so no re-registration is needed there.

💡 Iterate on the plan with: `@coderabbitai` <feedback>

Example Feedback
- `@coderabbitai` You can skip phase 3. Add a simple unit test case for phase 2.
- `@coderabbitai` For design choice 1 go ahead with option 3 and replan.

---