korjwl1 · korjwl1 · Aug 11, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 11, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,12 @@
 
 All notable changes to WireGuide will be documented in this file.
 
+## [Unreleased]
+
+### Fixed
+- **macOS "Update Now" (issue #38)** — the in-app update can no longer report success without actually installing: after `brew upgrade` exits, the installed bundle's version is verified against the release it claimed to install, progress phases ("refreshing" / "installing") are shown in the banner and About panel, and failures surface inline instead of vanishing behind a relaunch. Also survives Homebrew 6's tap-trust gate (`untrusted tap` errors trigger a `brew trust` + one retry) and skips the redundant `brew update` (`HOMEBREW_NO_AUTO_UPDATE=1` — the checker already knows the target version).
+- The Homebrew cask itself dropped `auto_updates` (korjwl1/homebrew-tap), so bulk `brew upgrade` no longer skips WireGuide — the root cause of months of silent non-updates.
+
 ## [0.5.0] - 2026-08-10
 
 Linux graduates to a supported platform, the CLI learns to start and stop the app, and the Windows helper's IPC surface is locked down to the launching user. Verified on all three OSes before release: a full runtime pass on Windows 11 against a real tunnel (helper IPC, multi-tunnel, kill-switch cycles, CLI lifecycle, tray), the Linux plan in `docs/linux-test-plan.md` on Debian 13 / Raspberry Pi OS ARM64, and the macOS DNS/lifecycle fixes below.

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -8,8 +8,9 @@ Thanks for your interest in contributing!
 
 - Go 1.25+
 - Node.js 20+
+- [Task](https://taskfile.dev/) (`go install github.com/go-task/task/v3/cmd/task@v3.45.4`)
 - [Wails v3](https://v3alpha.wails.io/) (`go install github.com/wailsapp/wails/v3/cmd/wails3@v3.0.0-alpha.74`)
-- macOS with Apple Silicon (for now)
+- macOS (Apple Silicon), Windows 11, or Linux — all three are supported build/dev hosts
 
 ### Build & Run
 
@@ -26,19 +27,23 @@ task build
 
 ### Project Structure
 
-- `internal/helper/` — Privileged daemon (runs as root)
+- `internal/helper/` — Privileged daemon (runs as root), Automation evaluation
 - `internal/tunnel/` — WireGuard engine and connection phases
 - `internal/gui/` — Wails app, tray, event bridge
+- `internal/app/` — GUI-side services bound to the frontend
 - `internal/network/` — Platform-specific network config
-- `internal/firewall/` — Kill switch (pf on macOS)
-- `internal/ipc/` — JSON-RPC 2.0 transport
+- `internal/firewall/` — Kill switch (macOS `pf` / Linux `nftables` / Windows WFP)
+- `internal/wifi/` — Automation rule model, network fingerprinting
+- `internal/ipc/` — JSON-RPC 2.0 transport (Unix socket / named pipe)
+- `internal/cli/` — `wireguide ctl` command-line interface
+- `internal/update/` — Update checker and Ed25519 release verification
 - `frontend/` — Svelte UI
 
 ## Pull Requests
 
 1. Fork the repo and create a branch from `main`
 2. Make your changes
-3. Test on macOS Apple Silicon
+3. Run `go vet ./...` and `go test ./...` locally (CI runs the same on a Linux/macOS/Windows matrix for every PR)
 4. Open a PR with a clear description of what and why
 
 Keep PRs focused — one fix or feature per PR.

diff --git a/README.ko.md b/README.ko.md
@@ -12,7 +12,7 @@
   <a href="https://github.com/korjwl1/wireguide/releases/latest"><img src="https://img.shields.io/github/v/release/korjwl1/wireguide?style=flat-square" alt="Release" /></a>
   <a href="https://github.com/korjwl1/wireguide/stargazers"><img src="https://img.shields.io/github/stars/korjwl1/wireguide?style=flat-square" alt="Stars" /></a>
   <a href="#설치"><img src="https://img.shields.io/badge/homebrew-tap-blue?style=flat-square" alt="Homebrew" /></a>
-  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey?style=flat-square" alt="Platform" />
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey?style=flat-square" alt="Platform" />
   <a href="LICENSE"><img src="https://img.shields.io/github/license/korjwl1/wireguide?style=flat-square" alt="License" /></a>
 </p>
 
@@ -37,7 +37,7 @@
 
 ## 설치
 
-**macOS 15+ (Apple Silicon)** 및 **Windows 11 (amd64)** 에서 테스트 완료.
+**macOS 15+ (Apple Silicon)**, **Windows 11 (amd64)**, **Linux (Debian 13 / Raspberry Pi OS, amd64/arm64)** 에서 테스트 완료 — 실제 검증 범위는 아래 [테스트 커버리지](#테스트-커버리지) 참조.
 
 ### macOS (Homebrew) — 권장
 
@@ -61,6 +61,18 @@ brew install --cask wireguide
 > Windows SmartScreen에서 "확인되지 않은 게시자" 경고가 뜰 수 있습니다 — 현재 코드 서명이
 > 없습니다. "추가 정보" → "실행"을 클릭하세요.
 
+### Linux (DEB)
+
+[Releases](https://github.com/korjwl1/wireguide/releases)에서 `WireGuide-linux-amd64.deb`
+(또는 `-arm64.deb`) 패키지를 다운로드 후 설치:
+
+```bash
+sudo apt install ./WireGuide-linux-amd64.deb
+```
+
+앱 메뉴 등록과 트레이 연동이 함께 설치되며, 특권 헬퍼는 상시 서비스가 아니라
+PolicyKit을 통해 필요할 때만 기동됩니다.
+
 ### 소스에서 빌드
 
 ```bash
@@ -72,14 +84,31 @@ task build
 ./bin/wireguide
 ```
 
+### 테스트 커버리지
+
+수동 QA는 실물 하드웨어에서 진행하지만, 모든 조합을 커버하지는 못합니다.
+실제로 검증된 범위:
+
+| 플랫폼 | 테스트 환경 | 유선랜 | Wi-Fi |
+|--------|------------|:------:|:-----:|
+| macOS | macOS 26.4 (Tahoe), Apple Silicon | ✅ | ✅ |
+| Windows | Windows 11 (amd64), 데스크탑 | ✅ | ⚠️ 제대로 테스트되지 못함 |
+| Linux | Raspberry Pi OS Lite (arm64) | ⚠️ 미테스트 | ✅ |
+
+미검증 칸은 Wi-Fi 의존 기능에서 특히 중요합니다 — Windows의 SSID 기반
+자동화 규칙과 Wi-Fi↔유선 전환, Linux의 유선 게이트웨이/서브넷 감지가
+해당됩니다. **이 빈 곳에서 오류를 만나면 꼭
+[이슈로 알려주세요](https://github.com/korjwl1/wireguide/issues/new/choose)** —
+저희에게 없는 하드웨어의 문제는 제보가 있어야만 고칠 수 있습니다.
+
 ---
 
 ## 기능
 
 | 기능 | 설명 |
 |------|------|
 | **자동화 (Automation)** | 터널별 조건→액션 규칙. 어느 네트워크에 있는지(Wi-Fi SSID / 서브넷 / 공유기 MAC 주소)에 따라 자동 연결·해제. 규칙은 우선순위 순서(드래그로 변경)이며 위에 있는 규칙이 우선. GUI 종료 시에도 헬퍼에서 독립 동작. |
-| **CLI** | `wireguide ctl` 명령줄 인터페이스 — 연결/해제/목록/가져오기/이름변경/삭제 및 자동화 규칙 설정. 실행 중인 헬퍼에 붙어 동작하므로 `wg-quick`과 달리 명령마다 sudo 불필요, 크로스플랫폼. |
+| **CLI** | `wireguide ctl` 명령줄 인터페이스 — 앱 시작/종료(`start`/`stop`), 연결/해제/목록(`--json` 지원)/가져오기/이름변경/삭제 및 자동화 규칙 설정. 실행 중인 헬퍼에 붙어 동작하므로 `wg-quick`과 달리 명령마다 sudo 불필요, 크로스플랫폼. |
 | **멀티 터널** | 여러 WireGuard 터널을 동시에 연결하고 터널별 독립 상태 관리 |
 | **터널 관리** | `.conf` 파일 가져오기, 생성, 편집, 내보내기. 드래그 앤 드롭 지원. |
 | **설정 에디터** | CodeMirror 6 기반 WireGuard 문법 강조 및 자동완성 |
@@ -98,7 +127,7 @@ task build
 | **다국어** | 영어, 한국어, 일본어 |
 | **테마** | 다크 / 라이트 / 시스템 자동 |
 
-[wireguard-go](https://git.zx2c4.com/wireguard-go) 2025년 5월 빌드 사용 (공식 앱 대비 57커밋 앞섬).
+[wireguard-go](https://git.zx2c4.com/wireguard-go) 2026년 5월 빌드 사용 (공식 macOS 앱의 엔진은 2023년 2월에서 멈춰 있음).
 
 ---
 

diff --git a/README.md b/README.md
@@ -12,7 +12,7 @@
   <a href="https://github.com/korjwl1/wireguide/releases/latest"><img src="https://img.shields.io/github/v/release/korjwl1/wireguide?style=flat-square" alt="Release" /></a>
   <a href="https://github.com/korjwl1/wireguide/stargazers"><img src="https://img.shields.io/github/stars/korjwl1/wireguide?style=flat-square" alt="Stars" /></a>
   <a href="#install"><img src="https://img.shields.io/badge/homebrew-tap-blue?style=flat-square" alt="Homebrew" /></a>
-  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows-lightgrey?style=flat-square" alt="Platform" />
+  <img src="https://img.shields.io/badge/platform-macOS%20%7C%20Windows%20%7C%20Linux-lightgrey?style=flat-square" alt="Platform" />
   <a href="LICENSE"><img src="https://img.shields.io/github/license/korjwl1/wireguide?style=flat-square" alt="License" /></a>
 </p>
 
@@ -99,16 +99,16 @@ WireGuide ships fewer knobs than most desktop VPN clients on purpose. The trade
 
 - **Privilege separation.** A single binary runs in two modes. The GUI runs unprivileged. A small helper runs as root / Administrator. They talk over a local Unix socket (macOS/Linux) or named pipe (Windows). Nothing is exposed over HTTP or the network.
 - **OS-native firewall.** The kill switch uses `pf` (macOS), WFP (Windows), or `nftables` (Linux) — not a userspace packet filter that fails open.
-- **Up-to-date crypto.** Built on [wireguard-go](https://git.zx2c4.com/wireguard-go) (May 2025) — 57 commits ahead of the engine inside the official macOS app, which hasn't been updated since Feb 2023.
-- **Manual QA per release.** Every tagged release is exercised on macOS (Apple Silicon) and Windows 11 (amd64) before it goes out.
+- **Up-to-date crypto.** Built on a May 2026 build of [wireguard-go](https://git.zx2c4.com/wireguard-go) — years ahead of the engine inside the official macOS app, which hasn't been updated since Feb 2023.
+- **Manual QA per release.** Every tagged release is exercised on macOS (Apple Silicon), Windows 11 (amd64), and Linux (Debian 13 / Raspberry Pi OS ARM64) before it goes out, on top of a 3-OS `go test` matrix that gates every PR.
 
 If something breaks, helper logs are plain text — not behind a paywall. Open an issue and attach them.
 
 ---
 
 ## Install
 
-Tested on **macOS 15+ (Apple Silicon)** and **Windows 11 (amd64)**.
+Tested on **macOS 15+ (Apple Silicon)**, **Windows 11 (amd64)**, and **Linux (Debian 13 / Raspberry Pi OS, amd64/arm64)** — see [what's actually been exercised](#tested-coverage) below.
 
 ### macOS (Homebrew) — recommended
 
@@ -132,6 +132,18 @@ installer registers the helper service and shortcut.
 > Windows SmartScreen may warn that the publisher is unknown — the binary is
 > currently unsigned. Click "More info" → "Run anyway".
 
+### Linux (DEB)
+
+Download the `WireGuide-linux-amd64.deb` (or `-arm64.deb`) package from
+[Releases](https://github.com/korjwl1/wireguide/releases) and install it:
+
+```bash
+sudo apt install ./WireGuide-linux-amd64.deb
+```
+
+The package registers the app menu entry and tray integration; the privileged
+helper is started on demand through PolicyKit (no always-on service).
+
 ### Build from Source
 
 ```bash
@@ -143,6 +155,23 @@ task build
 ./bin/wireguide
 ```
 
+### Tested coverage
+
+Manual QA runs on real hardware, but the hardware doesn't cover every
+combination. What has actually been exercised:
+
+| Platform | Tested on | Ethernet | Wi-Fi |
+|----------|-----------|:--------:|:-----:|
+| macOS | macOS 26.4 (Tahoe), Apple Silicon | ✅ | ✅ |
+| Windows | Windows 11 (amd64), desktop PC | ✅ | ⚠️ not properly tested |
+| Linux | Raspberry Pi OS Lite (arm64) | ⚠️ not tested | ✅ |
+
+The untested cells matter most for Wi-Fi-dependent features — SSID-based
+Automation rules and Wi-Fi↔Ethernet handover on Windows, and wired
+gateway/subnet detection on Linux. **If you hit an error in one of those
+gaps, please [open an issue](https://github.com/korjwl1/wireguide/issues/new/choose)**
+— reports from hardware we don't have are the only way those cells get fixed.
+
 ---
 
 ## Command line
@@ -153,8 +182,11 @@ helper over the local socket — so unlike `wg-quick` it needs no per-command
 `sudo`, works the same on macOS/Windows/Linux, and shares the GUI's tunnel store.
 
 ```
-wireguide ctl status                    # connection status
-wireguide ctl list                      # list tunnels (● = connected)
+wireguide ctl start                     # launch WireGuide (app + helper) and wait
+wireguide ctl stop                      # quit WireGuide (app + helper)
+
+wireguide ctl status [--json]           # connection status
+wireguide ctl list [--json]             # list tunnels (● = connected)
 wireguide ctl connect <name>            # connect a tunnel
 wireguide ctl disconnect [name]         # disconnect one (or all)
 wireguide ctl import <file> [name]      # import a .conf
@@ -177,13 +209,18 @@ wireguide ctl set loglevel <debug|info|warn|error>
 wireguide ctl dnsleak                        # check whether DNS leaks outside the tunnel
 wireguide ctl routes                         # OS routing table
 
+# Teach coding agents (Claude Code, Codex, ...) how to drive the CLI:
+wireguide ctl install-skills
+
 # e.g. turn the work VPN off on the office network, on everywhere else:
 wireguide ctl automation add work disconnect mac:b0:38:6c:54:8b:ab
 wireguide ctl automation add work connect else
 ```
 
-Connect/disconnect/status need the app (or its helper) running; list, import,
-rename, delete and automation edits work directly against the local files.
+Connect/disconnect/status need the app (or its helper) running — start it with
+`wireguide ctl start` (or by opening the app); nothing else starts a VPN stack
+behind your back. list, import, rename, delete and automation edits work
+directly against the local files.
 
 ---
 
@@ -237,6 +274,20 @@ Found a bug? [Open an issue](https://github.com/korjwl1/wireguide/issues/new/cho
 
 ---
 
+## Code signing
+
+Once the SignPath Foundation OSS approval completes, Windows installers will be
+code-signed via SignPath. The signing policy is documented in
+[SIGNING-POLICY.md](SIGNING-POLICY.md).
+
+> Free code signing provided by [SignPath.io](https://signpath.io),
+> certificate by [SignPath Foundation](https://signpath.org).
+
+Until then, releases ship unsigned and SmartScreen shows the "unknown
+publisher" warning on first run.
+
+---
+
 ## Sponsor
 
 <a href="https://github.com/sponsors/korjwl1">