release: prepare 0.2.0 for sing-box 1.14

docs/troubleshooting.md

@@ -9,54 +9,48 @@ vpn-egressctl status --json
 
 ## Unsupported sing-box version
 
-Установлена не `1.13.19`. Конфигурация не изменялась. Проверить:
+Установлена не exact `1.14.0` либо отсутствуют `with_quic`/`with_gvisor`.
+Конфигурация не изменялась. Не обходить version gate.
 
-```bash
-sing-box version
-apt-cache policy sing-box
-```
+## In-place upgrades are not supported
 
-Не использовать ручной обход version gate.
+Пакет 0.2.0 устанавливается поверх старого релиза. Старый package остаётся
+установленным; выполнить clean-install runbook из `docs/migration.md`.
+
+## State from another release / unmanaged configuration
+
+Обнаружены сохранённые файлы 0.1.0 или конфиг вне управления 0.2.0. Остановить
+sing-box, убедиться в наличии guard, переместить старые данные в защищённый архив
+и повторить `dpkg --configure vpn-egressctl`. Не редактировать старый state так,
+чтобы обойти проверку.
 
 ## sing-box rejected generated configuration
 
-Candidate удалён, production не менялся. Проверить package version, policy и
-логи oneshot. Секреты в отчёт не прикладывать.
+Candidate удалён, production не менялся. Проверить exact package version, URI и
+policy. Не прикладывать URI/config к отчёту без удаления secrets.
 
 ## Apply failed, previous configuration restored
 
-Автоматический rollback успешен. Проверить:
+Same-release rollback успешен. Проверить service/journal и выполнить doctor.
 
-```bash
-systemctl status sing-box --no-pager
-journalctl -u sing-box -u vpn-egress-sync.service -n 200 --no-pager
-vpn-egressctl doctor
-```
+## Automatic rollback also failed
 
-## Critical rollback failed
+Если это первое clean apply, предыдущего управляемого config нет — восстановить
+нечего. sing-box должен оставаться остановленным, а guard активным. При наличии
+last-good проверить его `.meta`; не запускать файл вручную при несовпадении
+версии или SHA.
 
-Не выполнять новый sync. Использовать `/var/lib/vpn-egress/last-good.json` или
-timestamped backup из консоли контейнера, затем `sing-box check` и restart.
+## Configuration metadata checksum does not match
+
+Backup и metadata рассогласованы или повреждены. Автоматический rollback
+правильно заблокирован. Использовать другой version-matched backup только через
+консоль и после `sing-box check`.
 
 ## Endpoint exclusion
 
-Если doctor сообщает, что A-запись endpoint находится в TUN exclusions, удалить
-публичный CIDR из policy и выполнить `check`, `diff`, `sync`. Не заменять его на
-новый IP.
+Удалить публичный endpoint CIDR из policy. Не заменять его новым A-адресом.
 
 ## Healthcheck request failed
 
-Проверить DNS, handshake Hysteria2, доступность health URL и nftables. Временно
-ставить `url: null` на production нельзя без отдельного решения: это скрывает
-неработающую локальную post-activation связность. Даже успешный healthcheck не
-заменяет отдельную проверку forwarded path с workload за `eth1`.
-
-## Watcher failed
-
-Некорректный файл URI не меняет рабочий config. Исправить его безопасным
-`vpn-egressctl import --stdin`, затем:
-
-```bash
-systemctl reset-failed vpn-egress-sync.service
-systemctl status vpn-egress-sync.path --no-pager
-```
+Проверить DNS, Gecko password, auth, SNI, certificate, UDP path и nftables.
+Успешный локальный healthcheck не заменяет forwarding E2E с `eth1`.