---
name: lemana-vpn-operations
description: Use when working in the lemana-vpn repo on install, uninstall, status, CLI aliases, menu-bar app behavior, live VPN connection handling, update instructions, or user-facing answers.
---

# Lemana VPN Operations

## Overview

This repo is a macOS VPN packaging layer around `openconnect`, `openconnect-lite`, Keychain/Bitwarden credential sync, runtime SSO patches, DNS cleanup, and a Swift menu-bar app. Treat live VPN state as real user state, not as a disposable test fixture.

## System Map

- `install.sh` installs/updates the whole package and restarts `LemanaVPN.app` only if it is already running.
- `bin/vpn-lemanapro.sh` is the runtime source for `vpn`, `vpn-auto`, `vpn-manual`, `vpn-manual-full`, `vpn-debug`, `vpn-fix-dns`.
- `app/Sources/LemanaVPN/VPNManager.swift` shells out to `~/bin/vpn-lemanapro.sh --json`; app state must stay compatible with CLI JSON events.
- `templates/openconnect-lite-config.toml` holds Keycloak selectors and the VPN profile.
- `uninstall.sh` must stop the running menu-bar app when removing the app, not only delete the bundle.

## Live Connection Rules

Before any live connect, run:

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

Do not start another `vpn`, `vpn-auto`, `vpn-debug`, `vpn --manual`, `vpn --manual-full`, or app connect if status says connected/connecting/reconnecting or if the previous connect attempt is still active. Inspect logs instead:

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

Manual or interactive SSO checks require an explicit request in the current prompt. Within that authorization, use `vpn --manual` for SSO diagnosis before automatic mode. Use `vpn-lemanapro.sh --patch-only` when only runtime patches need to be applied.

## Update Commands

From a checkout:

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

From the remote installer:

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

If Bitwarden is disabled or unavailable and Keychain credentials are missing:

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

## Answer Format

For behavior or installation changes, include relevant run, check, and update commands, and state whether live VPN was tested. For skill-only or documentation-only changes, report the result and structural checks without unrelated installation steps.

## Common Mistakes

- Starting a second VPN session instead of reading `vpn --status` and logs.
- Testing only the Swift app while breaking CLI JSON events.
- Calling a Bitwarden master password an LDAP password.
- Treating the current 6-digit TOTP code as the TOTP seed.
- Forgetting that the menu-bar app may still be running after app files are changed or removed.