Improve setup wizard onboarding

[touch2be]

Summary

• simplify the setup wizard to three steps and remove the appearance step
• clarify installed agent harness states and localize the inventory labels
• update Linux desktop integration metadata for packaged builds

Testing

• pnpm install
• pnpm exec vp build

[github-actions]

PR Review: Improve setup wizard onboarding

Confidence Score: 4/5

The PR cleanly simplifies the setup wizard from 4→3 steps, localizes the harness inventory display, and adds Linux desktop metadata. Builds and typechecks pass.

Issues

1. Redundant state updates in useEffect (src/components/SetupWizard.tsx:91-107)

refreshHarnessStatus() already calls setInventories() and setHarnessState() internally. The useEffect block immediately re-calls both setters with the same values:

// refreshHarnessStatus already did:
//   setInventories(result);
//   setHarnessState(...);

const result = await refreshHarnessStatus();
if (cancelled) return;
setInventories(result);                     // redundant
setHarnessState(                            // redundant
  hasModelReadyHarness(result) || hasInstalledHarness(result) ? "ready" : "none",
);

This causes two unnecessary renders on mount. The useEffect should just call refreshHarnessStatus() and use the cancellation guard — the state updates inside the function already handle it.

2. 18 orphaned i18n keys in all three locale files

After removing the appearance step and refactoring the wizard, the following keys are no longer referenced anywhere in src/:

appearanceTitle, privacyNote, backendStatusSubtitle, detectingBackends, detectedBackends, folderSubtitle, installed, notInstalled, requiredCommand, installCommand, installCli, reinstallCli, docs, folderTitle, folderHelp, folderEmptyHint, settingsGeneral, skipSetup, launch

These should be removed to avoid dead code and misleading translators.

3. Minor: stepNumber maps "opencode" to same dot as "harness"

function stepNumber(step: Step) {
  return ["harness", "folder", "finish"].indexOf(step === "opencode" ? "harness" : step);
}

When step === "opencode", the progress dots stay at index 0 (step 1/3). This is intentional but opaque — a comment or a {harness: 0, folder: 1, finish: 2, opencode: 0} lookup map would be clearer.

opencode session  |  github run

[github-actions]

PR Review: Improve setup wizard onboarding

Confidence Score: 5/5

Changes are well-structured, build passes, and the three-step wizard simplification is clean. The old wizard keys are properly removed from all locale files, and the new harness inventory localization is thorough.

Issues Detected

1. Orphaned i18n key setupWizard.title (src/i18n/locales/en.json:308, same in de.json/es.json)

The key "title": "Welcome to OpenGUI" exists in all three locale files but is never referenced by any component. After removing the old welcome/appearance step, this key became dead code. Should be removed alongside the other 19 keys that were correctly deleted.

2. Unmounted state update in copyOpenCodeInstallCommand (src/components/SetupWizard.tsx:113)

async function copyOpenCodeInstallCommand() {
  try {
    await navigator.clipboard.writeText(OPENCODE_INSTALL_COMMAND);
    setCopiedInstallCommand(true);
    window.setTimeout(() => setCopiedInstallCommand(false), 2000); // 🐛
  } catch {
    setCopiedInstallCommand(false);
  }
}

If the wizard unmounts within 2 seconds of copying, the timeout fires setCopiedInstallCommand(false) on an unmounted component. Store the timeout ID in a ref and clear it in the useEffect cleanup:

const copyTimeoutRef = useRef<ReturnType<typeof setTimeout>>();

async function copyOpenCodeInstallCommand() {
  try {
    await navigator.clipboard.writeText(OPENCODE_INSTALL_COMMAND);
    setCopiedInstallCommand(true);
    copyTimeoutRef.current = setTimeout(() => setCopiedInstallCommand(false), 2000);
  } catch {
    setCopiedInstallCommand(false);
  }
}

useEffect(() => {
  return () => clearTimeout(copyTimeoutRef.current);
}, []);

3. Scope creep in changes

Three changes are unrelated to the PR title/description:

• AppSidebar.tsx — removed SidebarRail import and usage
• AGENTS.md — bumped pnpm version from 11.1.2 → 11.5.2
• GeneralSettings.tsx — formatting-only change (wrapped a JSX attribute)

These should be split into separate PRs or called out in the description.

opencode session  |  github run