Source builders need the WebKitGTK 6 dev stack, which replaces the v2-era 4.x packages and is not preinstalled anywhere: give copy-paste distro commands (Arch/Debian-Ubuntu, names verified against the repos and the release workflow) plus the pinned wails3 CLI install. Same section records the version convention: 1.99.x is the v3-migration beta series (Wails v3 live, Svelte 4/Vite 4 refresh pending), 2.0.0 reserved for the finished article.
The release binary dynamically links libwebkitgtk-6.0 and libgtk-4, neither of which ships in the tarball or gets installed by install_linux.sh, and webkitgtk-6.0 is not preinstalled on most distros. Tell runners up front which runtime package to install (Arch/Debian-Ubuntu names verified) and what the missing-.so launch error looks like.
Add docs/V3_MIGRATION.md — a full write-up of the wailsv3 desktop migration (backend/frontend/build/CI changes, verification, branch map) and the planned follow-ups (toolchain majors + Android sideload). No behavior change.
Add a short notice to README.md: Migrating from v2 — v2 and v3 Secret Service collections coexist (AniTrack vs login) so both versions keep working after the first v3 re-login; the orphaned v2 entries are harmless. Details in docs/V3_MIGRATION.md. No cleanup instructions, by request.
Fixes the wails3 dev boot failure and removes remaining v2-isms so the tree matches a stock v3 project.
- frontend/package.json: add missing build:dev script (vite build --minify false --mode development). The dev taskflow runs npm run build:dev, which v2-era package.json never had - this was the wails3 dev boot failure.
- frontend/vite.config.ts: add the @wailsio/runtime vite plugin (typed custom events, as in every v3 template) and the server host/port/strictPort block (5173, matching the dev task).
- Remove stale v2 build dirs build/darwin + build/windows (v2 wails scaffolding; v3 generates its own via build-assets if ever needed).
- Delete untracked frontend/package.json.md5 (v2 change-detection artifact; v3 Taskfile uses content-hash sources) and drop its gitignore rule.
- go.mod: delete the leftover commented-out v2 replace directive.
- README.md: dev/build docs updated to make dev / make build (wails3), dropping the v2 :34115 browser-server paragraph; install link points at v3 docs.
Verified: production vite build green with the plugin, and wails3 dev boots end-to-end (bindings regen, build:dev, vite on :5173, asset server connected, AniTrack 1.6.8 window mapped).
John O'Keefe
john-okeefe