docs: QR phone login usage and verification

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

README.md

@@ -19,7 +19,9 @@
 
 ## 문제가 생기면
 
-- "다시 로그인하세요": 데스크탑 모드에서 2번 로그인을 다시 하세요.
+- "다시 로그인하세요": 패널의 **휴대폰으로 로그인 (QR)** 버튼을 누르고, 덱과 같은 와이파이에 있는 휴대폰으로 QR을 찍어 '로그인 기억하기'를 체크하고 로그인하세요. 로그인이 확인되면 팝업이 자동으로 닫힙니다.
+  - 이때 플러그인이 덱의 LAN 주소에 최대 5분 동안 임시 포트를 엽니다. QR에 일회용 값이 들어 있어, 처음 QR을 찍은 기기만 접속할 수 있습니다.
+  - 또는 데스크탑 모드에서 2번 로그인을 다시 해도 됩니다.
 - "노드 핑을 측정하는 중": 부팅 직후 1~2분 정도는 핑 측정이 끝나지 않았을 수 있습니다.
 - 로그: `~/homebrew/logs/mudfish-decky/`, `journalctl -u plugin_loader`
 - 미꾸라지 데몬: `systemctl status mudfish-decky`

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

@@ -176,6 +176,23 @@
   - 재검증(사용자 확인 + 로그 `resume detected; turning VPN off`): 깨어난 직후 인터넷이 정상이고 패널은 꺼짐이다.
 - **재부팅**(사용자 확인): 재부팅 후 패널은 꺼짐이고 코어는 미실행이다. 부팅 시 `prepare()`가 와이파이 연결 전에 실행되어 자동 로그인이 한 번 실패하지만, 노드 목록은 저장된 값을 쓰고 켜기를 누르면 그때 로그인한다.
 
+## 추가 기능: 휴대폰 QR 로그인 (2026-10-24, 사용자 요청)
+
+- **목적**: 저장된 로그인이 거부되면 데스크탑 모드로 가지 않고 게임모드에서 휴대폰으로 다시 로그인한다.
+- **사용자가 승인한 설계**:
+  - 패널에 "휴대폰으로 로그인 (QR)" 버튼을 띄운다. 플러그인 시작 시나 켜기를 누를 때 `SigninError`가 나면 `need_login`이 된다.
+  - 버튼을 누르면 QR 팝업이 뜨고, 그동안 덱의 LAN IP의 무작위 포트로 런처 UI를 중계한다.
+  - 중계는 일회용 토큰 `/_mfd/<token>`으로 보호한다. 이 경로를 처음 연 IP만 통과하고 나머지는 403이다.
+  - 최대 5분 동안 열고, 새 세션(jwt 변경)이 감지되거나 팝업을 닫거나 만료되거나 unload되면 닫는다.
+- **확인된 사실**:
+  - `api.mudfish.net`은 CORS로 요청 Origin을 그대로 허용한다.
+  - 런처 UI는 LAN 주소로 열어도 로그인 흐름이 동작한다.
+  - `/logout.html`을 열면 런처가 `autologin=False`, `token_v3="0"`이 된다. 이 상태를 "저장된 로그인 없음"으로 처리한다.
+- **실사용 검증**(사용자 확인 + 로그):
+  - 로그아웃 → 패널에 QR 버튼이 표시됐다.
+  - 휴대폰(192.168.1.60)이 인증됐고 10초 뒤 로그인이 감지되어 중계가 닫혔다.
+  - 이후 자동 로그인이 다시 켜졌고 켜기가 정상 동작했다. 닫힌 뒤 LAN에 남은 포트는 없다.
+
 ## 10. 끝나면 할 일
 
 - 스팀덱의 `/etc/sudoers.d/zz-dev-nopasswd`를 지운다(사용자가 직접 실행: `sudo rm /etc/sudoers.d/zz-dev-nopasswd`).