# Инструкции для агентов

## Контекст проекта

ProxyWarden - standalone Windows desktop client в корне репозитория. Это Tauri 2 + React/TypeScript UI + Rust backend для маршрутизации выбранных Windows-приложений через внешний SOCKS5-прокси или опциональный Local sing-box.

Не возвращать старую идею `APP_MODE=windows` и не подключать Windows-клиент к отдельному Node gateway/server. Текущий рабочий путь - `src`, `src-tauri`, `scripts` в корне репозитория.

## Основные инварианты

- Три компонента должны оставаться разделенными: Control App, ProxiFyre, Local sing-box.
- ProxiFyre - обязательный слой для per-app routing; Local sing-box - необязательный runtime.
- Внешний SOCKS5 flow должен работать без установленного Local sing-box.
- Profile apply не должен скрыто устанавливать, удалять, запускать или чинить компоненты. Install/start/stop/uninstall - только явные действия пользователя.
- Source of truth - JSON под `C:\ProgramData\ProxyWarden\config` и `state`.
- `C:\ProgramData\ProxyWarden\generated\proxifyre-app-config.json` и `sing-box-config.json` - derived artifacts, их можно пересоздать.
- Subscription URL и другие секреты нельзя показывать полностью в UI, diagnostics или логах.
- Summary panel должен оставаться read-only: без apply/install/start/stop/delete/input/subscription mutations.

## Структура

- `src/app/App.tsx` - основная React-оркестрация, вкладки `Сводка`, `ProxiFyre`, `VPN / Прокси`, вызовы Tauri-команд и transient UI state.
- `src/app/readiness.ts` - gating применимости маршрута. Не обходить его локальными проверками в JSX.
- `src/app/viewModel.ts` - маленькие display/view-model helpers.
- `src/ui/*` - общие presentational-компоненты. Для новых кнопок, вкладок, service rows, pills, полей и лог-дока сначала расширять эти компоненты.
- `src/api/tauriCommands.ts` - единственная TypeScript-обертка над `invoke(...)`; держать DTO в синхронизации с Rust.
- `src/domain/types.ts` - TypeScript-зеркало доменных DTO.
- `src-tauri/src/models.rs` - Rust-модели и default values.
- `src-tauri/src/validation.rs` - нормализация входов.
- `src-tauri/src/storage.rs` и `activity.rs` - JSON storage, backup/tmp writes, activity cap/sort.
- `src-tauri/src/adapters/proxy_router.rs` - adapter boundary для proxy-router.
- `src-tauri/src/adapters/proxifyre.rs` - первый adapter, генерирует ProxiFyre `app-config.json`.
- `src-tauri/src/adapters/singbox.rs` - генерация локального `sing-box` конфига из subscription cache и выбранного сервера.
- `src-tauri/src/component_detection.rs` - detection ProxiFyre/Proxifier/Local sing-box.
- `src-tauri/src/commands.rs` - Tauri command handlers, installer/service orchestration, structured errors.
- `src-tauri/src/main.rs` - реальная Tauri entrypoint-регистрация команд.
- `src-tauri/src/lib.rs` сейчас scaffold/stale; не считать его источником регистрации команд без отдельной cleanup-задачи.
- `scripts/*.ps1` - явные installer entrypoints. `-PlanOnly` должен возвращать structured JSON без side effects.

## Правила изменений

- Не создавать второй источник правды для профилей, targets, components, subscription или activity.
- Не писать generated config напрямую из React.
- Не парсить raw PowerShell/stdout в UI. Backend/helper boundary должен возвращать structured JSON/error DTO.
- Не привязывать UI напрямую к деталям ProxiFyre, если изменение относится к общему proxy-router поведению.
- Не делать Local sing-box обязательным для external target.
- Для service/install операций сохранять UAC/admin boundary и человекочитаемые ошибки.
- При удалении install folders сохранять safe-path checks; не ослаблять рекурсивное удаление.
- В UI держать стиль компактной Windows-утилиты, а не landing/dashboard. Использовать existing `Button`, `Tabs`, `ServiceControlRow`, `StatusPill`, `Field`, `ActionMenu`, `LogDock`.
- Всплывающие подсказки при наведении делать быстрыми, кастомными и читаемыми: темная compact-плашка с мягкой рамкой/тенью, появление ~120ms, без нативного browser `title` как основного UI. Для иконок расширять общий `IconButton`/tooltip-паттерн, а не дублировать JSX/CSS локально.
- Apply actions должны быть disabled с объяснением, когда нет приложений, ProxiFyre отсутствует, proxy input неверный или local route не готов.
- Не оставлять dev-серверы (`npm run dev`, `npm run tauri -- dev`, preview-серверы) запущенными после проверки. Если сервер был поднят агентом, остановить его перед финальным ответом.

## Проверка

Минимум для frontend/UI:

```powershell
npm run build
```

Rust/backend:

```powershell
cd D:\repos\ProxyWarden\src-tauri
cargo test
```

Tauri/toolchain:

```powershell
npm run tauri -- info
npm run tauri -- dev
npm run tauri -- build
```

Installer boundaries:

```powershell
& .\scripts\install-control-app.ps1 -PlanOnly
& .\scripts\install-proxyfier.ps1 -PlanOnly
& .\scripts\install-singbox.ps1 -PlanOnly
```

Для UI-изменений проверять browser-preview на desktop и narrow viewport. Browser-preview не доказывает native Tauri commands или elevated service lane.

## Известные риски

- Реальные elevated install/start/stop/uninstall операции для ProxiFyre и Local sing-box считаются `implemented but unproven`, пока они не проверены на Windows с UAC/admin confirmation.
- Исторические planning/evidence файлы лежат в ignored `docs`-папках и не должны попадать в коммиты.
- Старые документы могут ссылаться на `apps/windows-client`; текущая структура репозитория - standalone client в корне.