Audit: fix GTA path onboarding and stale React query state after configuration changes

[rolling-codes]

Summary

The React UI can remain stale after setting GtaPath, and first-run users with no GTA path are not guided into setup. This matches the observed behavior: the database/API can contain records, but the UI still shows the same counts/state after configuring the GTA path because dependent queries are not invalidated and there is no first-run setup gate.

Findings

1. High: Saving GtaPath only updates the config query, leaving GTA-path-derived screens stale

Classification: High / product-blocking state refresh bug

SettingsPage.tsx saves settings via updateConfig. On success it only does:

queryClient.setQueryData(['config'], updated)
setPatch({})

It does not invalidate/refetch queries whose results depend on AppConfig.Instance.GtaPath, such as:

• ['compatibility'] used by Dashboard
• ['patrol-readiness']
• ['mods'] / Library state
• backups/logs/diagnostics/cleanup where applicable

Dashboard also uses staleTime: 60_000, so it can keep showing the previous no-GTA-path state for up to a minute even after a successful save.

Impact: user sets a valid GTA path, but Dashboard/Library/Readiness can continue showing stale values/counts. This makes the app appear broken immediately after onboarding/configuration.

Expected fix: when gtaPath changes successfully, invalidate all GTA-path-derived query keys, for example:

queryClient.setQueryData(['config'], updated)
queryClient.invalidateQueries({ queryKey: ['compatibility'] })
queryClient.invalidateQueries({ queryKey: ['patrol-readiness'] })
queryClient.invalidateQueries({ queryKey: ['mods'] })
queryClient.invalidateQueries({ queryKey: ['logs'] })
queryClient.invalidateQueries({ queryKey: ['diagnostics'] })
queryClient.invalidateQueries({ queryKey: ['cleanup'] })

Alternatively centralize this as invalidateEnvironmentQueries(queryClient).

---

2. High: First-run users are not routed to setup when no GTA path is configured

Classification: High / onboarding blocker

The React app always renders AppLayout and the normal route tree. SetupWizardPage.tsx is only a stub, and both Sidebar and the mobile route selector explicitly exclude /setup from navigation.

Impact: new users land on Dashboard with GTA path missing, but there is no functional setup wizard and no clear path to complete first-run configuration. This blocks the main use cases: install LSPDFR, configure RPH/LSPDFR files, and manage weapon/mod installs.

Expected fix: add an onboarding gate:

• fetch /api/v1/config at app/layout startup;
• if gtaPath is blank or invalid, route to /setup;
• implement the setup wizard or add a prominent CTA to Settings until the wizard is complete;
• after setup save, invalidate environment queries and navigate to Dashboard.

---

3. Medium-high: /setup exists as a route but is hidden and non-functional

Classification: Medium-high / dead route

routeConfig.ts marks Setup Wizard as status: 'stub'. SetupWizardPage.tsx renders only StubPage. Sidebar and AppLayout filter /setup out of navigation.

Impact: /setup is neither discoverable nor usable, but it is supposed to be the flow that resolves the no-GTA-path state.

Expected fix: implement the 3-step setup wizard or expose an interim page that can validate/save GTA path using the existing config endpoints.

Acceptance criteria

• Saving a new GtaPath invalidates/refetches compatibility, patrol readiness, library/mods, diagnostics, logs, and cleanup queries as appropriate.
• Dashboard updates immediately after saving a valid GTA path.
• First-run/no-GTA-path users are routed to a functional setup path or shown a clear setup CTA.
• /setup is functional before it is hidden from navigation.
• Tests cover Settings save invalidation behavior and first-run route behavior.

Related plan context

The implementation plan identifies Setup Wizard as Phase 1 and the top usability gap. This issue tracks the bug-level behavior behind that gap: stale UI state and no usable onboarding route.