# User guide

## Profiles

A Proxy Profile contains proxy URLs and bypass rules. The Active Profile is the source applied to every Enabled Target.

Open Profile management with `m`:

- `n`: create a Profile
- `e` or Enter: edit the selected Profile
- `d`: safely delete the selected Profile
- Ctrl+S: save the editor
- Ctrl+T: switch between Single and Advanced modes

Single mode applies one URL to HTTP, HTTPS, and ALL/SOCKS. Advanced mode accepts separate values. A bare `host:port` is normalized to `http://`.

Bypass entries may be comma- or newline-delimited hostnames, domain suffixes, IPv4/IPv6 addresses, or CIDR ranges. The editor normalizes and deduplicates valid entries.

### Protocol Probe

Press Ctrl+D while editing the Single proxy URL to run an explicit handshake probe. It reports HTTP and SOCKS5 support without forwarding traffic or contacting another endpoint.

If both protocols are detected, the editor changes to Advanced mode and fills HTTP/HTTPS with `http://` and ALL/SOCKS with `socks5://`. GNOME cannot represent `socks5h` remote-DNS semantics; use Advanced mode with `socks5` when GNOME must use that endpoint.

## Dashboard

Press `p` to search and select the Active Profile. Select Targets with arrows or `j`/`k`; Space runs the contextual action:

- **Enable** a Disabled Target
- **Disable** an Enabled Target
- **Apply Profile** to an External Target
- **Resolve** a Drifted Target by reapplying the Active Profile or restoring the original configuration

Restoration refuses to overwrite configuration that changed after proxyctl applied it.

Other controls:

- `r`: refresh detection
- `u`: show unavailable Targets
- Tab: switch between Target list and details
- Page Up/Page Down: scroll details
- `e`: expand or collapse the current error
- `x`: acknowledge the current error
- `?`: contextual Help
- `q` or Esc: close the current page/dialog; `q` exits from the unobscured dashboard
- Ctrl+C: request exit

Conflicting actions are disabled while a mutation runs. Exit requests cancel cancellable work and wait for the operation to settle safely.

## Target states

- **Enabled:** managed configuration matches the Active Profile.
- **Disabled:** no managed or positively recognized external proxy configuration was detected.
- **External:** recognized proxy configuration exists outside proxyctl ownership.
- **Drifted:** managed configuration no longer matches the Active Profile, including partial failures.

External detection is best-effort. Disabled does not claim that every possible configuration source was exhaustively searched.

## What each Target affects

1. **Shell** — future commands in integrated Bash/Zsh sessions. It does not change existing processes or services.
2. **APT** — persistent Debian-family package operations through a tool-owned `apt.conf.d` overlay.
3. **Docker daemon** — registry and daemon traffic. Every change reloads systemd and restarts Docker.
4. **Docker containers/builds** — proxy defaults for future containers and builds in the owning user's Docker client configuration. It does not configure the daemon.
5. **GNOME** — compatible desktop applications using GNOME system proxy settings. It does not rewrite browser-specific profiles.

## Responsive and accessible TUI

At 100×28 and larger, Targets and details are side by side. At 60–99 columns they use one column. Below 60×16, proxyctl displays a minimum-size warning and restores interaction state after resize.

Focus and state never rely on color alone. States include symbols and words such as `● Enabled`, `○ Disabled`, `◇ External`, `! Drifted`, and `… Checking`. No Nerd Font is required. Set `NO_COLOR` to disable color.

Confirmation dialogs start on Cancel. The TUI uses the terminal alternate screen and restores the previous screen after exit.

Profiles are normally stored at `~/.config/proxyctl/profiles.json` with owner-only permissions.