v0.18.0 — uaro-cli, third launcher, cold-read hardening, F1–F12 guidance (catch-up since v0.2.0)

Catch-up release: everything shipped since v0.2.0 that only ever landed in CHANGELOG.md, never got its own GitHub Release. This tag brings Releases back in sync with CHANGELOG.md/SKILL.md's version number (0.18.0); going forward each CHANGELOG.md version bump gets a matching Release.

Upgrading an existing install: re-run SKILL.md on a session pointed at your existing bottle — Step 2a will detect what's missing and offer to apply just the new fixes, no reinstall needed.

[0.18.0] - 2026-08-01

Fixed

• Found during the first full live run of this skill by an external user (fresh Apple Silicon Mac, macOS 26.5.2), at Step 12's first-run verification — not by a cold-read:
  • uaro-settings (Step 11) silently did nothing when double-clicked whenever setup.exe was already FCOM-patched — which is the normal healthy state after Step 8. Under set -e, _patch_setup_exe's final [[ "$b_cur" == "dcd8dfe0" ]] && ... Site-B check returns 1 when the file is already patched; that becomes the function's exit status, and errexit kills the script before the exec wine64 "setup.exe" line ever runs. This is the same set -e failure class as uaro-patcher's wait bug fixed in 0.16.0 — that sweep verified the patcher script end to end but didn't re-audit the settings script for siblings. The bug never fires while setup.exe still needs patching (the dd runs and returns 0), which is why the original field test — run right after a fresh unpatched state — missed it. Reproduced in isolation (zsh -c 'set -e; f() { [[ a == b ]] && echo x; }; f; echo reached' never prints "reached"), then confirmed live: adding return 0 as _patch_setup_exe's last line fixed the launcher immediately on the affected machine. uaro-patcher and uaro-game are confirmed unaffected (they define no shell functions at all).
  • Step 2a gained a healing check for it (grep -q 'return 0' against the installed uaro-settings), and the Common Gotchas table a Launcher/Signing row, so pre-0.18.0 installs get offered the fix without waiting for the symptom to be reported.
  • uaro-patcher's crash-retry loop misread the patcher's own Launch Game handoff as the known early crash, spawning a ghost second patcher window alongside the launching game. Probed live with an instrumented run: clicking Launch Game kills the patcher with exit 137 (SIGKILL) 44s after launch — a non-zero exit inside the sub-60s window, matching the retry heuristic's crash signature exactly (0.16.0's fix made the retry actually fire; this run was the first to see it fire on a successful handoff). The loop now checks whether uaRO.exe is running after the patcher exits — the script's own startup cleanup pkills any stale uaRO.exe, so a running one here was necessarily started by this session — and treats that as a successful handoff (exit 0, no retry). Step 2a gained a matching healing check and the gotchas table a row.

Added

• Fullscreen Cmd+Tab focus-bounce gotcha (new Config/Graphics row), also from the same live run: with ISFULLSCREENMODE=1, tabbing away from the game then back in bounces focus straight back out every time — the game becomes unplayable until quit and relaunched. Second confirmed symptom of the fullscreen setting this skill already configures away (the black-screen row); the new row also warns that the client rewrites OptionInfo.lua on exit, so the flip back to 0 must happen with the game fully closed or it gets clobbered.
• F1-F12 skill-key guidance (new walkthrough item 9 in Installation complete, plus an Input/Keyboard gotcha row), from the same live run: RO leans on the F-row, but Mac keyboards default it to brightness/volume/media. Apple keyboards: the System Settings "Use F1, F2, etc. keys as standard function keys" toggle, or per-app via the optional Fluor menu-bar app (brew install --cask fluor) — with two live-verified wrinkles: Fluor rules must be created while the game is running and frontmost (the frontmost app presents as the launcher's own bundle name, UaRO Game/UaRO Patcher, not a Wine process name), and one live test on macOS 26.5.2 saw a Fluor rule never engage (fnState never flipped), so the gotcha row includes a defaults read -g com.apple.keyboard.fnState verification probe. Third-party keyboards (Keychron etc.) decide F-row behavior in their own firmware — neither the macOS toggle nor Fluor can affect them; documented the keyboard-side fixes instead (Keychron fn+X+L held ~4s in Mac mode, or the Mac/Windows hardware switch — the latter verified live as working, with the Cmd/Option swap trade-off noted).

[0.17.0] - 2026-07-30

Fixed

• Prompted by Discord feedback ("Rhya"): Steps 3, 4, and 9 ran their install/download commands unconditionally instead of checking first whether the target already existed, causing noisy errors (Step 3), a hanging fallback mirror (Step 4), and a false "failure" read on an already-installed Gecko (Step 9).
  • Added check-first guards to all three steps, plus a general "check real end-state before installing" principle to Section 0.
  • Step 4: the archive.org fallback mirror is confirmed unreliable now (hangs on live test) — this repo's own mirror is tried first instead.

[0.16.1] - 2026-07-29

Changed

• README.md: Option A now lists per-app choices (Claude, ChatGPT, GitHub Copilot) in the same layout as Option B, adding GitHub Copilot (macOS desktop app, free tier included) as a third choice, plus a long chain of cold-read-driven wording/UX fixes across README.md's AI-picker section (free-tier figures corrected against GitHub's own docs, Option A/B reformatted for scannability, "Terminal" and "pick any folder" explained for non-technical readers, a no-preference tiebreaker added). Full detail in CHANGELOG.md.
• README.md: "The problem this solves" now links uaRO to uaro.net instead of Wikipedia's Ragnarok Online article.
• Prompted by Discord feedback (uaRO player "Defectivve") on unclear prerequisites, Git/Xcode confusion, and a request for a gentler pace: README.md now offers desktop-app and Terminal/CLI paths side by side, SKILL.md Step 1 explains the Command Line Developer Tools popup before it appears, and per-step approval prompts were softened.
• Prompted by Discord feedback ("Rhya"): README.md Option B now also lists GitHub Copilot CLI (free tier, no paid plan required), installed via GitHub's own dependency-free curl script.

[0.16.0] - 2026-07-28

Fixed

• Prompted by an eighth fresh, zero-context cold-read of the public repo:
  • uaro-patcher's crash-retry loop (Step 11) never actually retried, because set -e + a bare wait $pid interact badly — errexit killed the script inside the retry loop before the second launch attempt ever ran, silently indistinguishable from a successful retry. Fixed by bracketing the wait/code=$? pair in set +e/set -e.
  • Step 6's URL-download branch (curl -fL ... "$INSTALLER_SOURCE") had no caffeinate -i, unlike every other unattended multi-minute operation in this file. Wrapped it the same way.

[0.15.0] - 2026-07-28

Fixed

• Prompted by a seventh cold-read: the Common Gotchas table's "Inno Setup installs into the bottle" row had the one surviving bare, unquoted whisky call in the whole file; Step 9's primary Gecko install wasn't wrapped in caffeinate -i; $SETUP was reused bare across two later fenced code blocks with no re-derivation. All three fixed to match this file's established patterns.

[0.14.0] - 2026-07-28

Fixed

• Prompted by a sixth cold-read: four more bare whisky calls survived 0.13.0's sweep — Section 2a's existing-bottle detection, the Uninstall section's own re-derivation TIP (added in 0.13.0, and reintroduced the bug it was fixing), and Uninstall Level 2's bottle deletion + verification line. All resolved via the standard command -v whisky || echo .../WhiskyCmd fallback, verified with whisky removed from PATH.

[0.13.0] - 2026-07-28

Fixed

• Prompted by a fifth cold-read run against actual pushed main: seven eval "$(whisky shellenv ...)" calls across Section 2a and Steps 5/7/9/9b called bare whisky instead of the documented fallback pattern — same bug class 0.4.0 fixed only in the launcher scripts. Also: Uninstall never re-derived $GAME_DIR/$BOTTLE_NAME despite being documented as a standalone entry point; a Parameters-table TIP pointed at the wrong numbered section; a placeholder comment was under-explained relative to this file's other placeholders.

[0.12.0] - 2026-07-28

Fixed

• Remaining findings from the same fourth cold-read as 0.11.0: Step 8's Python fallback had no write-to-disk wrapper (unlike Step 10's identical pattern); reused variables ($BOTTLE_NAME/$GAME_DIR/$WHISKY) needed a standing "always re-derive" instruction instead of a judgment call; the Parameters-table TIP could silently point back at the wrong $GAME_DIR after Step 7's redirect; Info.plist generation for two of three launcher bundles required manual mirroring instead of a shared loop.

[0.11.0] - 2026-07-28

Fixed

• Prompted by a fourth cold-read run after pushing, against real main — two genuinely new regressions from 0.10.0's own $APPS refactor: an unset $APPS silently iterates zero times in bash (success by omission, launchers never actually built); typeset -A EXE=(...) is zsh/bash-4+ syntax that macOS's real /bin/bash 3.2 rejects outright, replaced with a portable case statement. Also: $GUID required an error-prone manual retype into a quoted heredoc, fixed by passing it through the environment instead.

[0.10.0] - 2026-07-28

Fixed

• Prompted by a third cold-read: declining UaRO Game.app in Step 11 required manually omitting it from ~8 separate hardcoded three-item...

v0.2.0 - Option=Alt keybind fix, crash-dialog mitigation

Fixed

• In-game menu shortcuts (Cmd+A, Cmd+Z, etc.) not registering — game shortcuts now go through Option (mapped to Alt via Wine's LeftOptionIsAlt/RightOptionIsAlt), matching how uaRO already behaves in a Windows VM. This replaces an earlier approach (disabling Wine's hidden macOS Edit menu) that fixed the same symptom but broke native Cmd+V paste as a side effect — the new approach has no such trade-off.
• "Program Error" crash dialog appearing after the post-Gecko patcher launch — mitigated (not root-caused) by suppressing Wine's crash dialog (ShowCrashDialog=0) combined with a bounded single-retry watchdog in the launcher script.

Added

• Step 2a now also detects bottles still running the old Edit-menu-disable fix (and migrates them) or missing the new Option/Alt fix entirely, and separately detects launchers missing the crash-dialog mitigation.
• Step 12 first-run checklist now tells the user the game's Alt key is macOS's Option key.
• "Known open issues" documents the precise trigger sequence found for the post-Gecko patcher crash, for anyone who wants to dig into the real root cause later.

Upgrading an existing install: re-run SKILL.md on a session pointed at your existing bottle — Step 2a will detect what's missing and offer to apply just the new fixes, no reinstall needed.

Full diff: v0.1.0...v0.2.0

v0.1.0 - Initial public release

Initial public release. A single self-contained SKILL.md that installs uaRO on Apple Silicon Macs via Whisky, end to end, meant to be handed to a fresh Claude Code/Codex session with no other context.

Added

• Steps 1-12: Homebrew → Rosetta 2 → Whisky.app → WhiskyWine runtime → bottle creation/config → download & run the uaRO installer → FCOM byte-patch for Rosetta compatibility → Wine Gecko pre-install → game config files → two launcher .app bundles (with icon extraction) → first-run verification.
• Pre-flight checks: Apple Silicon gate, macOS version gate, disk space check.
• Environment-adaptive detection/self-heal: existing-state scan (Step 2a), proactive installer-download handling (Step 2b) with iCloud-relocation avoidance and size-stability recheck.
• Mandatory verification after every risky step (byte-diff after binary patches, decode-testing config files, lsregister -dump after building launchers) instead of trusting exit codes alone.
• Per-step progress table with explicit user approval gate before advancing to the next step.
• Uninstall/rollback section with tiered levels and backup-dependency warnings.
• caffeinate -i wrapping around long unattended waits so macOS idle sleep doesn't stall the install.
• README: project story, how-to-run instructions, Credits & Disclaimer, MIT LICENSE.

Full diff: https://github.com/jirukouya/auRO-whisky-macOS-setup/commits/v0.1.0

Whisky install backup (2026-07-25)

Archived copy of the now-dead Whisky ecosystem, since upstream (Homebrew cask + GPTK download endpoint) is gone:

• Whisky-app-2.3.5.zip — Whisky.app installer (matches installed version)
• WhiskyWine-Libraries-2.5.0.zip — WhiskyWine runtime: Wine 7.7 + Apple GPTK + DXVK
• whisky-cask-metadata.json — original Homebrew cask metadata/download URLs
• WhiskyWineVersion.plist / GPTKVersion.plist — installed version snapshots

Whisky development was discontinued in April 2025 by its creator; this preserves what's needed to reproduce the install after upstream disappears.