docs: polish public repo presentation

.env.example

@@ -1,59 +1,87 @@
-# Шаблон переменных окружения для deploy.sh, verify.sh и локальных CLI-скриптов.
-# Рекомендуемый путь:
+# GhostRoute environment example
+#
+# Recommended operator-local path:
 #   mkdir -p secrets
 #   cp .env.example secrets/router.env
 #
-# Директория secrets/ добавлена в .gitignore и никогда не попадёт в git.
-# Для обратной совместимости скрипты всё ещё читают .env, если secrets/router.env нет.
-
-# Профиль SSH-доступа к роутеру.
-# По умолчанию auto выбирает:
-# - home LAN/Wi-Fi: ROUTER_LAN:ROUTER_LAN_PORT, только если маршрут к LAN-адресу
-#   идет не через VPN-интерфейс;
-# - off-LAN/VPN: ROUTER:ROUTER_WAN_PORT, то есть выделенный WAN/remote SSH endpoint.
+# `secrets/` and real `.env*` files are gitignored. Keep real router/VPS hosts,
+# ports, users, keys and provider details out of git. Use placeholders in public
+# docs and commits.
+
+# -----------------------------------------------------------------------------
+# Router SSH access profile
+# -----------------------------------------------------------------------------
+
+# Default: auto chooses LAN when the control machine is really on the home LAN,
+# otherwise it keeps the dedicated remote/WAN SSH endpoint profile.
 # ROUTER_ACCESS_MODE=auto
 
-# LAN-адрес роутера для домашней сети. Используется только когда control machine
-# реально находится в home LAN/Wi-Fi; если маршрут идет через utun/tun/wg, auto
-# считает это VPN/off-LAN и выбирает WAN-профиль ниже.
+# LAN-only router access. Use only when the control machine is actually on the
+# home LAN/Wi-Fi; if the route goes through utun/tun/wg/Tailscale, auto mode
+# treats the machine as off-LAN.
 # ROUTER_LAN=<router_lan_ip>
 # ROUTER_LAN_PORT=22
 
-# WAN/remote SSH endpoint роутера. Для удаленной работы храните здесь DDNS или
-# текущий WAN fallback host и отдельный внешний порт.
+# Remote/off-LAN router SSH endpoint. Store only operator-local values here.
 # ROUTER=<remote-router-ssh-host>
 # ROUTER_WAN_PORT=<remote-router-ssh-port>
 # ROUTER_PORT=<legacy-remote-router-ssh-port>
 
-# auto выполняет короткий SSH-preflight. Если WAN endpoint принимает TCP, но не
-# отдает SSH banner, helper пробует direct LAN/Wi-Fi fallback перед ошибкой.
+# SSH preflight checks the banner before selecting a fallback path.
 # ROUTER_ACCESS_PREFLIGHT=ssh
 
-# SSH-пользователь на роутере (обычно admin).
+# SSH identity. Prefer a key under gitignored `secrets/router-remote-ssh/` or a
+# private workstation path; never commit the key.
 # ROUTER_USER=admin
-
-# Путь к SSH-ключу для подключения к роутеру.
 # SSH_IDENTITY_FILE=~/.ssh/id_rsa
-
-# Таймаут подключения в секундах.
 # CONNECT_TIMEOUT=5
 
-# Логирование DNS-запросов для автоматического обнаружения доменов.
-# Лог пишется в /opt/var/log/dnsmasq.log (требует Entware на USB).
-# Скрипт domain-auto-add.sh запускается каждые 4 часа через cron,
-# парсит DNS-лог и добавляет новые домены в VPN автоматически.
-#
-# Просмотр результатов:
-#   ./scripts/domain-report          # сводка + последний запуск
-#   ./scripts/domain-report --log    # подробный лог активности
-#   ./scripts/domain-report --all    # все авто-добавленные домены
-#   ./scripts/domain-report --reset  # удалить все авто-добавленные домены
-#
-# Отключить логирование: ENABLE_DNSMASQ_LOGGING=0
+# Optional override when a script should read another gitignored env file.
+# GHOSTROUTE_ROUTER_ENV_FILE=secrets/router.env
+
+# -----------------------------------------------------------------------------
+# DNS / catalog discovery
+# -----------------------------------------------------------------------------
+
+# Enables router-side dnsmasq query logging for domain discovery. Logs are stored
+# on router storage, not in git. See the module-native command paths below.
 # ENABLE_DNSMASQ_LOGGING=1
 
-# URL списка заблокированных доменов для фильтрации auto-discovery.
-# По умолчанию: community.antifilter.download (кураторский список ~500 доменов).
-# Скрипт update-blocked-list.sh скачивает его ежедневно через VPN.
-# Если список не скачан, domain-auto-add.sh работает в fallback-режиме (добавляет всё).
+# Public blocked-domain list used as an admission filter for auto-discovery.
+# If the list cannot be fetched, the discovery script documents its fallback
+# behavior in module reports.
 # BLOCKED_LIST_URL=https://community.antifilter.download/list/domains.lst
+
+# Module-native inspection commands:
+#   ./modules/dns-catalog-intelligence/bin/domain-report
+#   ./modules/dns-catalog-intelligence/bin/domain-report --log
+#   ./modules/dns-catalog-intelligence/bin/domain-report --all
+#   ./modules/dns-catalog-intelligence/bin/domain-report --reset
+#   ./modules/dns-catalog-intelligence/bin/catalog-review-report
+
+# -----------------------------------------------------------------------------
+# GhostRoute Console local development
+# -----------------------------------------------------------------------------
+
+# Local Console data directory. The default module path is gitignored.
+# GHOSTROUTE_CONSOLE_DATA_DIR=modules/ghostroute-console/data
+
+# Synthetic GUI test data and quota knobs. Safe placeholders only.
+# GHOSTROUTE_CONSOLE_VPS_QUOTA_GB=1024
+# GHOSTROUTE_CONSOLE_LTE_QUOTA_GB=50
+# GHOSTROUTE_CONSOLE_BILLING_RESET_DAY=1
+
+# Live UI refresh interval for server-sent events. Long default by design; the
+# Console reads prepared snapshots rather than becoming a real-time control loop.
+# GHOSTROUTE_LIVE_UI_REFRESH_MS=600000
+
+# Diagnostic rollback switch for Console prepared windows. Production should use
+# prepared windows; set to 0 only while debugging a read-model regression.
+# GHOSTROUTE_CONSOLE_USE_PREPARED_WINDOWS=1
+
+# Console public deployment values belong in Vault or gitignored operator files,
+# never in tracked docs:
+#   <console-host>
+#   <console-port>
+#   <console-user>
+#   <console-password>

.github/pull_request_template.md

@@ -0,0 +1,53 @@
+## Summary
+
+-
+-
+
+## Scope
+
+Touched areas:
+
+-
+
+Runtime impact:
+
+- [ ] Docs-only / no runtime behavior changed
+- [ ] Console read-only UI/API/read-model change
+- [ ] Router data plane / sing-box / dnsmasq / iptables
+- [ ] VPS edge / Caddy / Xray / Reality
+- [ ] Ansible / deploy / generated artifacts
+- [ ] Traffic Observatory / machine contract
+- [ ] Secrets / Vault / local operator files
+
+## Tests
+
+Run:
+
+```bash
+
+```
+
+Not run, and why:
+
+-
+
+## Risk and rollback
+
+Blast radius:
+
+-
+
+Rollback path:
+
+-
+
+Safety tag needed before deploy?
+
+- [ ] No
+- [ ] Yes: `pre-<change-name>-<YYYY-MM-DD>`
+
+## Secrets and public-safety check
+
+- [ ] No real endpoints, listener ports, credentials, UUIDs, Reality keys, short IDs, admin paths, QR payloads, VLESS URIs, provider details or personal device identifiers are included.
+- [ ] Generated artifacts under `ansible/out/`, local reports and private operator notes remain gitignored.
+- [ ] Public examples use placeholders only.

.gitignore

@@ -1,12 +1,16 @@
-# Персональные переменные окружения (IP роутера, SSH-ключ и т.п.)
+# Local environment and operator secrets
 .env
+.env.*
+!.env.example
+*.local.env
+/secrets/
 
-# Конфиги WireGuard с приватными ключами
+# WireGuard / VPN configs with private keys
 *.conf.wg
 wireguard/
 wg*.conf
 
-# Любые файлы с приватными/чувствительными данными
+# Keys, certificates and credential material
 *.key
 *.pem
 *.p12
@@ -16,23 +20,24 @@ id_ed25519
 id_ecdsa
 *.pub
 
-# Claude Code
+# AI assistant local state
 .claude/
 
-# VPN domain journal (local-only, не для репозитория)
+# Local reports, journals and private operator notes
+reports/
 docs/vpn-domain-journal.md
 docs/router-health-latest.md
 docs/catalog-review-latest.md
 docs/private/
 configs/private/
-reports/
+
+# Keep tracked Next.js route folders named reports/ inside the Console app
 !modules/ghostroute-console/app/src/app/reports/
 !modules/ghostroute-console/app/src/app/reports/**
 !modules/ghostroute-console/app/src/app/api/reports/
 !modules/ghostroute-console/app/src/app/api/reports/**
 
-# Локальные secrets / overrides с персональными IP, ключами и bypass-правилами
-/secrets/
+# Ansible Vault and generated client artifacts
 /ansible/secrets/*.yml
 !/ansible/secrets/*.yml.example
 /ansible/secrets/*.backup-*
@@ -61,19 +66,30 @@ reports/
 /ansible/out/clients-home-backup-*/
 ansible/*.retry
 
-# macOS
-.DS_Store
-__pycache__/
-
-# Node/Next module-local artifacts
+# Node / Next.js / Playwright artifacts
 node_modules/
 .next/
+out/
+coverage/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
 modules/ghostroute-console/app/node_modules/
 modules/ghostroute-console/app/.next/
+modules/ghostroute-console/app/out/
+modules/ghostroute-console/app/coverage/
 modules/ghostroute-console/app/test-results/
+modules/ghostroute-console/app/playwright-report/
 modules/ghostroute-console/data/
 
-# Редакторы
+# Python / shell local artifacts
+__pycache__/
+*.py[cod]
+.pytest_cache/
+
+# OS and editor noise
+.DS_Store
 *.swp
 *.swo
 *~

.nvmrc

@@ -0,0 +1 @@
+22