# Starminer Mod Manager Support Guide

This guide is for triaging player reports from the Windows manager.

## First Response Checklist

Ask for:

- the newest `%LOCALAPPDATA%\smmodmanager\support\support-report-*.json`;
- the exact action the player attempted;
- whether Starminer was running during the action;
- whether Steam updated Starminer recently;
- whether the selected path is the real Starminer install root.

Do not ask the player to install a random UE4SS release. Public installs should
come from the runtime profile published through the SMMODS catalog.

## Support Report Fields

Important top-level fields:

- `ok`: all collected checks succeeded.
- `gameRoot`: selected Starminer root.
- `catalogSource`: catalog path or URL.
- `managerReleaseSource`: manager release metadata path or URL.
- `catalog`: catalog metadata load result.
- `managerUpdate`: manager update metadata result.
- `catalogState`: runtime, bridge, mod, unknown, invalid, dependency, and
  update state.
- `launch`: launch readiness result.

Each check is a `SupportCheck`:

- `ok`: check succeeded.
- `value`: check result when successful.
- `error`: structured manager error report when failed.
- `skippedReason`: why a dependent check did not run.

## State Triage

Runtime:

- `catalogState.value.runtime.status == "installed"` means all profiled UE4SS
  required files exist.
- `missingRequiredFiles` lists profiled runtime files absent from `Win64`.
- Repair path: ask the player to run `Repair Runtime + Bridge`.

Bridge:

- `installed == true` and `enabled == true` is the expected ready state.
- `updateAvailable == true` means repair should update StarminerBridge.
- `targetGameBuildCompatible == false` means wait for a catalog/bridge update
  for the player's Starminer build.

Catalog mods:

- `status == "installed"` with `enabled == true` is active.
- `status == "not-installed"` means install is still needed.
- `status == "missing-dependency"` means an installed enabled mod is missing a
  required installed dependency, or the selected install cannot satisfy it.
- `status == "update-available"` means repair selected should update it.
- `status == "incompatible-game-build"` means do not force install; publish or
  wait for compatible metadata.

Unknown mods:

- Valid manifest, not present in the current catalog.
- The manager may enable/disable them if already installed.
- Install/repair actions are intentionally catalog-only.

Invalid installed mods:

- Manifest exists but fails validation or dependency policy.
- The manager reports them without aborting state collection.
- Ask for the folder and error from `invalidInstalledMods`.

## Error Codes

`missing-game-path`

The selected folder is not a Starminer root. Ask the player to select the folder
that contains `ILLSpace\Binaries\Win64`.

`download-failed`

Catalog or artifact URL could not be fetched. Check whether `smmods.com` is
reachable and whether the player has a proxy/firewall problem. No game files are
changed while downloads are failing.

`hash-mismatch`

Cached or downloaded artifact does not match catalog SHA256. Ask the player to
clear `%LOCALAPPDATA%\smmodmanager\downloads` and retry. If it persists, verify
the site artifact and catalog hash.

`missing-dependency`

The selected mod requires a catalog dependency that is not present. Fix the
catalog or publish the missing dependency.

`dependency-version-unsatisfied`

The dependency exists, but its catalog version does not satisfy the selected
mod's requirement. Publish a compatible version or adjust the requirement.

`dependency-cycle`

Catalog dependencies form a loop. Break the dependency graph before publishing
or recommending the mod.

`incompatible-game-build`

The runtime, bridge, or mod metadata targets a different Starminer build.
Do not tell the player to force it. Publish compatible metadata or wait for a
bridge/mod update.

`missing-artifact`

Catalog metadata lacks a package URL or SHA256. Fix the catalog entry before the
manager can install it.

`invalid-manifest`

The package or installed folder has a manifest that fails schema, path,
entrypoint, dependency, or load-order checks. Ask for the package source or
folder and reproduce with `smmodmanager.exe manifest <folder>`.

`unsafe-package-path`

The package contains an absolute path, traversal, symlink, drive prefix, or
unsafe path characters. Reject the package and rebuild it.

`install-conflict`

A local install would overwrite an existing folder without an explicit repair
path. Use catalog repair for managed updates, or manually back up/remove a local
folder only when the player understands the risk.

`install-rolled-back`

The staged install failed and the manager restored previous managed files where
possible. Review the `Cause` section in the report for the underlying file,
network, hash, manifest, or package error.

`rollback-failed`

Automatic rollback failed. Tell the player not to keep retrying. Inspect the
target folder and the error details first.

`permission-denied`

Close Starminer, UE4SS logs, editors, and archive tools. Retry from a Windows
account with write access to the selected install.

`file-locked`

Windows reported a sharing or lock violation while writing game files. Close
Starminer and any tools, terminals, editors, archive apps, or antivirus prompts
using the game folder, then retry.

## Install Failure Diagnostics

When catalog install, runtime/bridge install, or catalog repair fails, the
launcher appends an `Install failure diagnostics` block to the visible log and
the saved error report. Use it to check:

- whether the selected game root, Win64 folder, executable, and ue4ss Mods folder look
  valid;
- whether `ILLSpace-Win64-Shipping` is still running;
- whether the download cache is writable;
- whether the catalog, runtime package, bridge package, and selected mod
  package URLs can be reached from the player's machine.

## Recovery Flow

1. Confirm the selected game path.
2. Confirm the live manager version from `managerUpdate`.
3. Confirm catalog loaded successfully.
4. If runtime or bridge is missing, run `Repair Runtime + Bridge`.
5. If a selected catalog mod fails dependency checks, fix catalog metadata before
   asking the player to retry.
6. If hashes fail, clear cache and verify site artifacts.
7. If launch readiness blocks launch, resolve blocking issues before asking the
   player to start the game.
8. If only warnings remain, explain the warning and let the player decide
   whether to continue.

## Manual Commands

Run from the extracted manager folder:

```powershell
.\smmodmanager.exe support-report-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json" "https://smmods.com/api/v1/manager/latest.json"
.\smmodmanager.exe catalog-state-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json"
.\smmodmanager.exe launch-plan-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json"
.\smmodmanager.exe repair-catalog-url "E:\Path\To\Starminer" "https://smmods.com/api/v1/catalog.json" "%LOCALAPPDATA%\smmodmanager\downloads"
```

Use the URL-backed commands for public support so the manager consumes the same
contracts as the launcher.
