docs: install/update/remove usage and on-device verification

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -2,14 +2,21 @@
 
 스팀덱 게임모드의 데키 패널에서 **미꾸라지(Mudfish) Full VPN**을 켜고 끄는 플러그인입니다. 일본 지포스나우 계정으로 로그인할 때 쓰려고 만들었어요.
 
-## 처음 한 번만 (데스크탑 모드)
+## 처음 한 번만
 
-1. 미꾸라지를 설치합니다. 자세한 방법은 [공식 Steam Deck 가이드](https://docs.mudfish.net/v3/en/docs/mudfish-product/mudfish-cloud-vpn/platform/steamos/steamos-install)를 참고하세요. 설치 위치는 `/opt/mudfish/<버전>`입니다.
+1. 플러그인을 `~/homebrew/plugins/mudfish-decky/`에 설치합니다. 개발 환경에서는 `scripts/deploy.sh`를 씁니다.
-2. 미꾸라지를 실행하고 브라우저에서 `http://127.0.0.1:8282`에 접속해 **'로그인 기억하기'를 체크하고** 로그인합니다.
+2. 게임모드 패널에서 **미꾸라지 설치** 버튼을 누릅니다. `mudfish.net`에서 최신 리눅스 패키지를 받아 MD5를 확인한 뒤, 설치 스크립트를 실행하지 않고 직접 풀어서 `/opt/mudfish/<버전>`에 설치합니다.
-3. 플러그인을 `~/homebrew/plugins/mudfish-decky/`에 설치합니다. 개발 환경에서는 `scripts/deploy.sh`를 씁니다.
+3. **휴대폰으로 로그인 (QR)** 버튼으로 로그인합니다('로그인 기억하기' 체크).
 
 그다음부터는 플러그인이 알아서 미꾸라지를 대기 상태로 띄우고 자동 로그인합니다. **연결은 직접 켤 때만** 합니다.
 
+## 업데이트 / 제거
+
+- **업데이트**: 하루에 한 번 최신 버전을 확인합니다. 새 버전이 있으면 **고급 ▸**에 업데이트 버튼이 나타납니다. VPN을 끈 상태에서만 할 수 있습니다. 로그인 설정은 새 버전으로 옮겨지고, 바로 전 버전 하나는 남깁니다.
+- **제거**: **고급 ▸ → 미꾸라지 제거**를 누릅니다. 또는 데키에서 플러그인을 삭제해도 같이 정리됩니다. 정리 대상은 VPN 연결, 데몬, `/opt/mudfish` 전체, `mudfish-tap` 연결, 플러그인 설정입니다. 미꾸라지 계정에 저장된 Full VPN 노드 설정은 남습니다.
+  - 데키 3.3은 플러그인을 5초 만에 강제 종료하는 경우가 잦습니다. 그래서 별도의 systemd 감시(`mudfish-decky-cleanup.path`)가 플러그인 폴더를 지켜보다가, 폴더가 20초 동안 사라져 있으면 정리를 실행합니다.
+- 공식 설치 방법은 [Steam Deck 가이드](https://docs.mudfish.net/v3/en/docs/mudfish-product/mudfish-cloud-vpn/platform/steamos/steamos-install)를 참고하세요.
+
 ## 사용법 (게임모드)
 
 1. `...` → 데키 → **Mudfish VPN**에서 토글을 켭니다.

docs/superpowers/specs/2026-10-24-mudfish-decky-design.md

@@ -193,6 +193,26 @@
   - 휴대폰(192.168.1.60)이 인증됐고 10초 뒤 로그인이 감지되어 중계가 닫혔다.
   - 이후 자동 로그인이 다시 켜졌고 켜기가 정상 동작했다. 닫힌 뒤 LAN에 남은 포트는 없다.
 
+## 추가 기능: 미꾸라지 설치·업데이트·제거 (2026-10-24, 사용자 요청)
+
+이 기능으로 2절의 비목표 "미꾸라지 설치와 업데이트"를 철회한다.
+
+- **설치**:
+  - `mudfish.net/download`에서 최신 `mudfish-<ver>-linux-x86_64.sh`를 찾는다.
+  - 이 파일은 Makeself 형식(셸 헤더 `skip`줄 + bzip2 tar, 헤더에 MD5)이다. MD5를 검증한 뒤 tar를 직접 푼다. 이때 경로 조작과 링크를 거부하고 `filter="data"`를 쓴다.
+  - 결과는 `/opt/mudfish/<ver>/{bin,sbin,etc,share,var}`이다. **다운로드한 스크립트는 실행하지 않는다.**
+  - 실제 6.6.0을 이 방식으로 설치하면 데몬 바이너리가 공식 설치본과 동일하다. 공식 스크립트가 복사하지 않는 `mudstat`, `.desktop`, polkit 파일도 함께 들어간다.
+- **업데이트**:
+  - 최신 버전 확인은 하루 1회 백그라운드에서 한다. 실제 업데이트는 버튼으로만 하고, 터널이 있으면 거부한다.
+  - 새 버전을 설치한 뒤 `var/.conf`와 `var/.conf.db`를 복사하고, 데몬을 새 버전으로 재시작한다. 직전 버전 1개만 남긴다.
+  - **실측**: 6.5.5에서 QR 로그인 후 6.6.0으로 업데이트했다. 재로그인 없이 `isSignedIn=True`, `autologin=True`였다.
+- **제거**(사용자 결정: 버튼과 플러그인 삭제 시 모두):
+  - 순서: 터널 teardown → 데몬 중지(`--no-block`) → `mudfish-tap` 삭제 → `/opt/mudfish` 삭제 → 플러그인 설정 비우기.
+  - **데키 3.3.0 제약**: SIGTERM과 동시에 소켓이 닫히면 sandboxed plugin의 listener가 EOF에서 돌며 이벤트 루프를 굶긴다. 그러면 `_unload`/`_uninstall`이 실행되지 못하고 5초 뒤 SIGKILL된다. 이 덱에서 여러 플러그인이 이 상태로 수십 % 비율로 종료됐다.
+  - 대책 1: `_unload`/`_uninstall`은 동기로 실행한다.
+  - 대책 2: 일시적인 systemd path 유닛 `mudfish-decky-cleanup`이 plugins 폴더를 감시한다. 이 플러그인 폴더가 20초 동안 없으면 정리하고 스스로 멈춘다. 재설치나 업데이트처럼 폴더를 바로 다시 만드는 경우는 건드리지 않는다.
+  - **실측**: 데키에서 플러그인을 삭제하자 `_uninstall`과 감시가 모두 동작했다. `/opt/mudfish`, 설정, 데몬, 프로세스가 모두 없어졌다.
+
 ## 10. 끝나면 할 일
 
 - 스팀덱의 `/etc/sudoers.d/zz-dev-nopasswd`를 지운다(사용자가 직접 실행: `sudo rm /etc/sudoers.d/zz-dev-nopasswd`).