vz: add SPICE connection documentation

vz/pve-spice-connect.md

+# Подключение к VM Proxmox через SPICE из CLI
+
+## Обзор
+
+Для подключения к VM на Proxmox (gefest) через SPICE из командной строки нужно:
+1. Получить одноразовые credentials через API
+2. Сформировать .vv файл в правильном формате
+3. Запустить remote-viewer с этим файлом
+
+## 1. Получение данных для подключения
+
+```bash
+ssh root@gefest "pvesh create /nodes/gefest/qemu/VMID/spiceproxy --proxy gefest.office.etersoft.ru --output-format=json"
+```
+
+Возвращает JSON:
+```json
+{
+  "password": "одноразовый_пароль",
+  "host": "pvespiceproxy:TICKET:VMID:NODE::HASH",
+  "tls-port": 61007,
+  "ca": "-----BEGIN CERTIFICATE-----\\n...\\n-----END CERTIFICATE-----\\n",
+  "title": "VM VMID - имя",
+  "host-subject": "OU=PVE Cluster Node,O=Proxmox Virtual Environment,CN=gefest.office.etersoft.ru",
+  "proxy": "http://gefest.office.etersoft.ru:3128"
+}
+```
+
+## 2. Формат .vv файла
+
+Порядок полей соответствует тому, что генерирует веб-интерфейс Proxmox:
+
+```ini
+[virt-viewer]
+password=be3bcd8c390050b6e5ffa9b1385a154b1152c36b
+host=pvespiceproxy:69505df5:228:gefest::e80b5a4bdde6e651a940b5c5b037c3aba9972401
+toggle-fullscreen=Shift+F11
+secure-attention=Ctrl+Alt+Ins
+release-cursor=Ctrl+Alt+R
+title=VM 228 - lav-altp11-gnome
+delete-this-file=1
+host-subject=OU=PVE Cluster Node,O=Proxmox Virtual Environment,CN=gefest.office.etersoft.ru
+ca=-----BEGIN CERTIFICATE-----\nMIIF...\n-----END CERTIFICATE-----\n
+proxy=http://gefest:3128
+tls-port=61007
+type=spice
+```
+
+## 3. Критически важные моменты
+
+### proxy — короткое имя хоста!
+```
+proxy=http://gefest:3128        # ПРАВИЛЬНО
+proxy=http://gefest.office.etersoft.ru:3128  # НЕ РАБОТАЕТ
+```
+
+### host-subject — обязателен
+Без этого поля TLS соединение не установится.
+
+### password и host — одноразовые
+Генерировать непосредственно перед подключением. Повторно использовать нельзя.
+
+### Клиент — remote-viewer
+```bash
+remote-viewer файл.vv   # ПРАВИЛЬНО
+virt-viewer файл.vv     # Пытается подключиться к libvirt, не работает
+```
+
+## 4. Полный скрипт для Claude Code
+
+```bash
+ssh lav@lav 'DATA=$(ssh root@gefest "pvesh create /nodes/gefest/qemu/VMID/spiceproxy --proxy gefest.office.etersoft.ru --output-format=json")
+
+cat > ~/tmp/claude/vm.vv << EOF
+[virt-viewer]
+password=$(echo "$DATA" | jq -r ".password")
+host=$(echo "$DATA" | jq -r ".host")
+toggle-fullscreen=Shift+F11
+secure-attention=Ctrl+Alt+Ins
+release-cursor=Ctrl+Alt+R
+title=$(echo "$DATA" | jq -r ".title")
+delete-this-file=0
+host-subject=$(echo "$DATA" | jq -r ".\"host-subject\"")
+ca=$(echo "$DATA" | jq -r ".ca")
+proxy=http://gefest:3128
+tls-port=$(echo "$DATA" | jq -r ".\"tls-port\"")
+type=spice
+EOF
+
+DISPLAY=:0.0 remote-viewer ~/tmp/claude/vm.vv'
+```
+
+Заменить:
+- `VMID` — номер виртуальной машины
+- `lav@lav` — пользователь и хост с графической сессией
+
+## 5. Запуск из Claude Code
+
+### Найти DISPLAY пользователя
+```bash
+ssh lav@HOST "for pid in \$(pgrep -u lav); do d=\$(grep -z '^DISPLAY=' /proc/\$pid/environ 2>/dev/null | tr '\0' '\n'); [ -n \"\$d\" ] && echo \"\$d\" && break; done"
+```
+Обычно возвращает `:0.0`
+
+### Запуск команды
+- Использовать параметр `run_in_background: true` в Bash tool
+- НЕ использовать `&` в конце команды
+
+## 6. Отладка
+
+### Проверить доступность прокси
+```bash
+nc -zv gefest 3128
+```
+
+### Проверить что VM запущена
+```bash
+ssh root@gefest "qm status VMID"
+```
+
+### Посмотреть ошибки remote-viewer
+Вывод сохраняется в файл задачи при использовании `run_in_background: true`