# Lemana VPN Agent Instructions

## Scope

This repository builds a macOS Lemana VPN installer, CLI, DNS cleanup wrapper, and Swift menu-bar app. Work in Russian by default, unless the user asks otherwise.

Before changing behavior, read the relevant repo-local skills:

- `.agents/skills/lemana-vpn-operations/SKILL.md` for install/update/connect/status/user-answer rules.
- `.agents/skills/lemana-vpn-testing/SKILL.md` for verification strategy and live VPN safety.
- `.agents/skills/lemana-vpn-sso-autofill/SKILL.md` for Bitwarden, Keychain, TOTP, SSO, and runtime autofill patches.

## System Model

- `install.sh` installs Homebrew/pipx dependencies, `openconnect-lite`, CLI scripts, config, DNS wrapper, sudoers rules, optional Touch ID helper, and optional `~/Applications/LemanaVPN.app`.
- `bin/vpn-lemanapro.sh` is the main runtime path. It reports module status, syncs Bitwarden credentials into macOS Keychain, verifies Keychain credentials, applies `openconnect-lite` runtime patches, starts SSO/openconnect, writes status JSON, and cleans VPN DNS on exit.
- `templates/openconnect-lite-config.toml` defines the SSO profile and Keycloak auto-fill selectors.
- `libexec/lemana-vpn-dns-cleanup` is the narrow root-owned DNS cleanup wrapper.
- `app/Sources/LemanaVPN/*` is a menu-bar wrapper over `~/bin/vpn-lemanapro.sh --json`; it does not implement a separate VPN client.
- `uninstall.sh` restores patch backups when possible, removes installed files, stops a running `LemanaVPN` process when the app is removed, and optionally removes Keychain/Touch ID/openconnect-lite state.

## Live VPN Safety

Always check current state before starting a live connection:

```sh
vpn --status
vpn --status --json
```

Use `~/bin/vpn-lemanapro.sh` if aliases are not loaded. For repo-local code checks, `bin/vpn-lemanapro.sh --status` validates the source script, but it may not be the installed version used by the menu-bar app.

Do not run `vpn`, `vpn-auto`, `vpn-debug`, `vpn --manual`, `vpn --manual-full`, or the Swift app connect action repeatedly when a connection is already connected, connecting, reconnecting, or when a live connect attempt is still running. Inspect status and logs instead:

```sh
tail -f ~/Library/Logs/LemanaVPN-openconnect-lite.log
tail -f ~/Library/Logs/LemanaVPN.log
```

Use `vpn --manual` before `vpn`/`vpn-auto` when debugging SSO/autofill, because manual mode shows the browser, fills fields, and does not press submit. Use `vpn --manual-full` when the form itself must be filled entirely by hand with no auto-fill. Use `vpn-debug` only when raw logs and a visible browser are needed.

`vpn-lemanapro.sh --patch-only` is safe for applying runtime patches without starting a VPN session.

## Testing

Prefer the non-live ladder first:

```sh
sh -n install.sh
sh -n uninstall.sh
bash -n bin/vpn-lemanapro.sh
sh -n tests/smoke.sh
tests/smoke.sh
swift build -c release --package-path app
git diff --check
```

Run a live VPN check only when the change affects real connection behavior, credential flow, SSO/autofill, status reporting, reconnect, or DNS cleanup, and only after checking current status. If VPN is already connected, do not start a second session; report that live reconnect was intentionally skipped unless the user explicitly asks for it.

## Answer Contract

Every final answer for this repository must include:

- What changed, with file references when useful.
- How to run it.
- How to check it.
- How to update the installed local setup.
- What verification was run, and what was intentionally not run.

For update instructions, prefer the exact current path:

```sh
sh install.sh
vpn --status
open ~/Applications/LemanaVPN.app
```

For remote user-facing update instructions, use:

```sh
curl -fsSL https://git.dokops.ru/dokril/lemana-vpn/raw/branch/main/install.sh | sh
```

If credentials are missing and Bitwarden is disabled or unavailable from the menu-bar app, point the user to:

```sh
vpn --configure-keychain
```