Update go.mod and go.sum (#89)

README.md

@@ -8,99 +8,51 @@
   <a href="https://goreportcard.com/report/github.com/lukaszraczylo/kportal"><img src="https://goreportcard.com/badge/github.com/lukaszraczylo/kportal" alt="Go Report Card"></a>
 </p>
 
-# kportal
+<p align="center">
+  <strong>Kubernetes port-forward manager with interactive terminal UI</strong>
+</p>
 
-kportal runs many Kubernetes port-forwards from one YAML file and shows their status in a terminal UI. It reconnects dropped forwards, reloads the file when it changes, and can run without the UI.
+kportal manages multiple Kubernetes port-forwards with an interactive terminal interface. It provides real-time status updates, automatic reconnection, hot-reload configuration, and mDNS hostname publishing.
 
 ![kportal Screenshot](docs/kportal-screenshot.png)
 
-Screenshot from kportal v0.2.17. The current key bar also lists `PgUp`/`PgDn`, `b` (Bench) and `l` (Logs).
+## ✨ Features
 
-Website: <https://lukaszraczylo.github.io/kportal>
+- **Interactive TUI** - Terminal interface with keyboard navigation
+- **Live management** - Add, edit, and delete port-forwards without restarting
+- **Auto-reconnect** - Exponential backoff retry on connection failures
+- **Hot-reload** - Configuration changes applied automatically
+- **Health monitoring** - Multiple check methods with stale connection detection
+- **Multi-context** - Support for multiple Kubernetes contexts and namespaces
+- **Pod restart handling** - Automatic reconnection when pods restart
+- **Label selectors** - Dynamic pod targeting using label selectors
+- **Port conflict detection** - Validates port availability with PID information
+- **mDNS hostnames** - Access forwards via `.local` hostnames
+- **HTTP traffic logging** - Real-time HTTP request/response logging for debugging
+- **Connection benchmarking** - Built-in HTTP benchmarking with latency statistics
+- **Headless mode** - Background operation for scripting and automation
 
-## Contents
+## 🔄 Comparison with Other Tools
 
-- [Features](#features)
-- [Comparison](#comparison-with-other-tools)
-- [Installation](#installation)
-- [Quick start](#quick-start)
-- [Configuration](#configuration)
-- [Usage](#usage)
-- [Status indicators](#status-indicators)
-- [Advanced features](#advanced-features)
-- [Migration from kftray](#migration-from-kftray)
-- [Signal handling](#signal-handling)
-- [Troubleshooting](#troubleshooting)
-- [Development](#development)
-- [Telemetry](#telemetry)
-- [License](#license)
+| Feature | kportal | [k9s](https://k9scli.io/) | [Kube Forwarder](https://kube-forwarder.pixelpoint.io/) | [kftray](https://kftray.app/) |
+|---------|---------|------|----------------|--------|
+| **Interface** | Terminal TUI | Terminal TUI | Desktop GUI (Electron) | Desktop GUI + TUI |
+| **Persistent Config** | ✅ YAML file | ❌ Session only | ✅ JSON bookmarks | ✅ JSON + Git sync |
+| **Auto-reconnect** | ✅ Exponential backoff | ❌ Manual | ✅ Basic | ✅ Watch API |
+| **Hot-reload Config** | ✅ File watch + SIGHUP | ❌ | ❌ | ❌ |
+| **Health Checks** | ✅ TCP + data-transfer | ❌ | ❌ | ❌ |
+| **Stale Connection Detection** | ✅ Age + idle tracking | ❌ | ❌ | ❌ |
+| **HTTP Traffic Logging** | ✅ Built-in viewer | ❌ | ❌ | ✅ |
+| **Connection Benchmarking** | ✅ Built-in | ✅ Via Hey | ❌ | ❌ |
+| **mDNS Hostnames** | ✅ `.local` domains | ❌ | ❌ | ❌ |
+| **Label Selectors** | ✅ | ✅ | ❌ | ✅ |
+| **Multi-context** | ✅ | ✅ | ✅ | ✅ |
+| **Headless Mode** | ✅ | ❌ | ❌ | ❌ |
+| **System Tray** | ❌ | ❌ | ❌ | ✅ |
+| **UDP Support** | ❌ | ❌ | ❌ | ✅ Proxy relay |
+| **Dependencies** | Single binary | Single binary | Electron | Tauri + kubectl |
 
-## Features
-
-| Area | What kportal does |
-|------|-------------------|
-| Forwards | Forwards to `service/<name>`, `pod/<name>` (exact name or name prefix), or `pod` with a label `selector`. Only TCP is supported. |
-| Terminal UI | Add (`n`), edit (`e`), delete (`d`) and toggle (`Space`) forwards without a restart. The add wizard writes the config file. |
-| Table columns | `tui.columns` sets which columns the forwards table shows, their order and their width. It applies to the UI and to the `-v` table. |
-| Add wizard | If the cluster does not allow listing namespaces, the wizard asks you to type the namespace. |
-| Reconnect | Retries with exponential backoff: 1s, 2s, 4s, 8s, then 10s, with 10% jitter. It does not stop retrying. |
-| Pod restarts | Forwards by pod prefix or selector connect to a new pod after a restart. |
-| Health checks | `tcp-dial` or `data-transfer` check every 3s by default. A connection is stale when it is older than `maxConnectionAge` and idle, or idle longer than `maxIdleTime`. |
-| Hot reload | The file watcher and `SIGHUP` reload the config. An invalid config is rejected and the previous one stays active. |
-| Contexts | Several Kubernetes contexts and namespaces in one file. `--context` selects which contexts run. |
-| Port conflicts | Startup and reload checks report a busy local port and the process that holds it. |
-| mDNS | With `mdns.enabled: true`, each forward is reachable as `<alias>.local`. Without an alias, the resource name is used. |
-| HTTP log | Per-forward request and response log in the UI, with detail view, filter, search, JSON formatting, gzip/deflate decoding and clipboard copy. |
-| Header redaction | With `includeHeaders: true`, values of sensitive headers such as `Authorization` and `Cookie` become `[REDACTED]`. You cannot turn this off. |
-| Benchmark | Press `b` to send HTTP requests through a forward. Reports success and failure counts, min/max/avg latency, P50/P95/P99, requests per second and status codes. |
-| Generate | `kportal generate` lists services in a cluster and appends the ones you pick to the config with consecutive local ports. |
-| Headless | `-headless` runs without the UI and logs to stderr. `-log-format json` switches the log format. |
-| Import | `-convert` turns a kftray JSON file into a kportal YAML file. |
-| Shell completion | `kportal completion` prints a bash, zsh or fish completion script, or installs it. |
-| Verified installer | `install.sh` checks the archive SHA-256 and, if `cosign` is on `PATH`, the keyless signature of the checksums file. |
-| Updates | `-update` checks for a newer release. `-version` prints the version. |
-
-## Comparison with other tools
-
-Compared on 2026-10-02 against each project's README and docs. Check their repositories for changes. The kportal column comes from this repository's code. "Not documented" means the project's README and docs do not say.
-
-| Feature | kportal | kubectl port-forward | k9s | kubefwd | kftray |
-|---------|---------|----------------------|-----|---------|--------|
-| Many forwards in one config file | Yes | No | Partial (annotations configure forwards; no forward list file) | Partial (`example.fwdconf.yml` exists) | Yes |
-| Automatic reconnect | Yes | Not documented | Not documented | Yes | Yes |
-| Follows pod restarts by label or name prefix | Yes | Not documented | Not documented | Yes (label filter) | Yes |
-| Terminal UI of all forwards | Yes | No | Yes (PortForward view, alias `pf`; forwards last for the session) | Yes | Yes |
-| GUI | No | No | No | No | Yes |
-| Config hot reload | Yes (file watcher, `SIGHUP`) | No | Partial (`benchmarks.yaml` only) | Not documented | Not documented |
-| HTTP request and response logging | Yes | No | Not documented | Not documented | Yes |
-| Health checks | Yes (`tcp-dial`, `data-transfer`) | Not documented | Not documented | Not documented | Partial (README says it tracks pod health) |
-| mDNS or friendly hostnames | Yes (mDNS) | No | No | Partial (edits `/etc/hosts`, not mDNS; needs root) | Not documented |
-| Built-in benchmark | Yes | No | Yes (`hey`, key `b`) | Not documented | Not documented |
-| Imports another tool's config | Yes (kftray JSON) | No | No | Not documented | Partial (JSON, GitHub repos, service annotations; not other tools' formats) |
-| Several contexts in one config | Yes | No | Partial | Partial | Not documented |
-| Local port conflict detection | Yes (reports the holding process) | Partial (`:remotePort` picks a free port) | Not documented | Yes | Not documented |
-| Platforms | Linux, macOS, Windows | Not documented | macOS, Linux, Windows | macOS, Linux, Windows | macOS, Linux, Windows |
-| Licence | MIT | Not documented | Apache-2.0 | Apache-2.0 | GPL-3.0 |
-| Language | Go | Not documented | Go | Go | Rust (Tauri, Ratatui) |
-| Latest release (2026-10-02) | [Releases](https://github.com/lukaszraczylo/kportal/releases) | Not documented | v0.51.0 (2026-06-06) | v1.25.16 (2026-06-20) | v0.29.2 (2026-09-29) |
-
-When another tool fits better:
-
-- kubectl port-forward for a one-off forward. It needs no config file and ships with kubectl.
-- k9s for general cluster browsing and its built-in benchmark.
-- kubefwd to forward every service in a namespace with local DNS names.
-- kftray for a tray GUI, shared JSON configs and UDP.
-
-Kube Forwarder is a GUI-only forwarder. Its last release was 2019-08-14.
-
-Sources:
-
-- kubectl: [Use Port Forwarding to Access Applications in a Cluster](https://kubernetes.io/docs/tasks/access-application-cluster/port-forward-access-application-cluster/)
-- k9s: <https://github.com/derailed/k9s> and <https://k9scli.io/topics/bench/>
-- kubefwd: <https://github.com/txn2/kubefwd>
-- kftray: <https://github.com/hcavarsan/kftray>
-
-## Installation
+## 📦 Installation
 
 ### Homebrew (macOS)
 
@@ -108,37 +60,29 @@ Sources:
 brew install --cask lukaszraczylo/taps/kportal
 ```
 
-If you installed the formula (`brew install lukaszraczylo/taps/kportal`) earlier, run `brew uninstall kportal` first.
+> **Note**: If you previously installed via `brew install lukaszraczylo/taps/kportal` (formula), uninstall first:
+> ```bash
+> brew uninstall kportal
+> ```
 
-### Quick install
+### Quick Install
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/lukaszraczylo/kportal/main/install.sh | bash
 ```
 
-The script downloads `kportal-<version>-checksums.txt` from the same release and verifies the archive SHA-256. If [`cosign`](https://github.com/sigstore/cosign) is on `PATH`, it also verifies the keyless signature of the checksums file.
+The installer downloads `kportal-<version>-checksums.txt` from the same release and verifies the archive's SHA-256 before installing. If [`cosign`](https://github.com/sigstore/cosign) is on your `PATH`, the checksums file's keyless cosign signature is also verified against the shared-actions reusable workflow identity.
 
 | Variable | Effect |
 |----------|--------|
-| `DRY_RUN=1` | Download and verify only. Do not install. |
-| `SKIP_COSIGN=1` | Skip the cosign check. The SHA-256 check still runs. |
-| `INSTALL_DIR` | Target directory. Default `/usr/local/bin`. |
-| `KPORTAL_VERSION` | Install a specific version, for example `1.2.3`, instead of the latest. |
-| `COSIGN_CERT_IDENTITY_REGEXP` | Certificate identity to accept. Set it if you fork the release pipeline. |
+| `DRY_RUN=1` | Download and verify only; do not install |
+| `SKIP_COSIGN=1` | Skip cosign signature verification (SHA-256 is still enforced) |
 
-Example:
+### Manual Download
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/lukaszraczylo/kportal/main/install.sh | DRY_RUN=1 bash
-```
+Download binaries from the [releases page](https://github.com/lukaszraczylo/kportal/releases).
 
-### Manual download
-
-The [releases page](https://github.com/lukaszraczylo/kportal/releases) has archives for Linux, macOS and Windows on amd64 and arm64. Archives are named `kportal-<version>-<os>-<arch>.tar.gz`, and `.zip` on Windows. Each release also has a `kportal-<version>-checksums.txt` file.
-
-### Build from source
-
-Go 1.26 or later is required (see `go.mod`).
+### Build from Source
 
 ```bash
 git clone https://github.com/lukaszraczylo/kportal.git
@@ -146,13 +90,12 @@ cd kportal
 make build && make install
 ```
 
-`make install` copies the binary to `/opt/homebrew/bin` if that directory exists, otherwise to `~/.local/bin` on macOS and Linux.
+### Verifying Release Signatures
 
-### Verifying release signatures
-
-Release checksums are signed with [cosign](https://github.com/sigstore/cosign) using keyless signing. Download the checksums file and its sigstore bundle from the release, then run:
+All release checksums are signed with [cosign](https://github.com/sigstore/cosign) using keyless signing. To verify:
 
 ```bash
+# Download the checksum file and its sigstore bundle from the release
 cosign verify-blob \
   --certificate-identity-regexp "^https://github\.com/lukaszraczylo/shared-actions/\.github/workflows/go-release\.yaml@refs/heads/main$" \
   --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
@@ -160,9 +103,7 @@ cosign verify-blob \
   kportal-<version>-checksums.txt
 ```
 
-Replace `<version>` with the release version, for example `1.2.3`. Then check the archive against the verified checksums file with `shasum -a 256` or `sha256sum`.
-
-## Quick start
+## 🚀 Quick Start
 
 Create `.kportal.yaml`:
 
@@ -183,40 +124,31 @@ contexts:
             port: 8080
             localPort: 8080
             alias: api
-            httpLog: true
+            httpLog: true  # Enable HTTP traffic logging
 ```
 
-Each `name` under `contexts` must exist in your kubeconfig. List them with `kubectl config get-contexts`.
-
 Run:
 
 ```bash
 kportal
 ```
 
-### Keyboard controls
-
-Forwards list:
+### Keyboard Controls
 
 | Key | Action |
 |-----|--------|
-| `Up` `Down` / `j` `k` | Move the selection |
-| `PgUp` `PgDn` / `Ctrl+u` `Ctrl+d` | Move by 10 rows |
-| `Space` / `Enter` | Toggle the forward |
-| `n` | Add a forward |
-| `e` | Edit the forward |
-| `d` | Delete the forward (asks to confirm) |
-| `b` | Benchmark the forward |
-| `l` | Open the HTTP log |
-| `q` / `Ctrl+c` | Quit |
+| `↑↓` / `j/k` | Navigate |
+| `Space` / `Enter` | Toggle forward |
+| `n` | Add new forward |
+| `e` | Edit forward |
+| `d` | Delete forward |
+| `b` | Benchmark connection |
+| `l` | View HTTP logs |
+| `q` | Quit |
 
-In the add and edit wizard, `h` on the confirmation step toggles `httpLog`. Advanced `httpLog` keys you set in YAML stay unchanged.
+## 📖 Configuration
 
-HTTP log keys are listed under [HTTP traffic logging](#http-traffic-logging).
-
-## Configuration
-
-### Basic structure
+### Basic Structure
 
 ```yaml
 contexts:
@@ -230,56 +162,56 @@ contexts:
             localPort: <local-port>
             alias: <display-name>      # optional
             selector: <label-selector> # optional
-            httpLog: true              # optional
+            httpLog: true              # optional - enable HTTP logging
 ```
 
-### Forward options
+### Forward Options
 
 | Field | Required | Description |
 |-------|----------|-------------|
-| `resource` | Yes | `service/<name>`, `pod/<name>`, or `pod` with `selector` |
-| `protocol` | No | `tcp`. No other value is accepted. |
+| `resource` | Yes | Resource type and name (e.g., `service/postgres`, `pod/my-app`) |
+| `protocol` | Yes | Protocol (`tcp`) |
 | `port` | Yes | Remote port |
 | `localPort` | Yes | Local port |
 | `alias` | No | Display name and mDNS hostname |
-| `selector` | With bare `pod` | Label selector. Not allowed with `pod/<name>`. |
-| `httpLog` | No | `true`, or a map of options (see [HTTP traffic logging](#http-traffic-logging)) |
+| `selector` | No | Label selector for pod resolution |
+| `httpLog` | No | Enable HTTP traffic logging (`true`/`false`) |
 
-### Resource formats
+### Resource Formats
 
 | Format | Description |
 |--------|-------------|
-| `service/name` | Forward to a service |
-| `pod/name` | Forward to a pod by exact name, or by name prefix |
-| `pod` with `selector` | Forward to a pod picked by label selector |
+| `service/name` | Service forwarding |
+| `pod/name` | Direct pod by name |
+| `pod/prefix` | Pod by prefix (matches `prefix-*`) |
+| `pod` + `selector` | Pod by label selector |
+| `deployment/name` | Deployment |
 
-Valid resource types are `pod` and `service`. To reach a deployment, use `pod` with a `selector`.
-
-### Health checks and reliability
+### Health Check Configuration
 
 ```yaml
 healthCheck:
-  interval: "3s"
-  timeout: "2s"
-  method: "data-transfer"  # or tcp-dial
-  maxConnectionAge: "25m"
-  maxIdleTime: "10m"
+  interval: "3s"           # Check frequency
+  timeout: "2s"            # Check timeout
+  method: "data-transfer"  # tcp-dial or data-transfer
+  maxConnectionAge: "25m"  # Reconnect before k8s timeout
+  maxIdleTime: "10m"       # Detect idle connections
 
 reliability:
   tcpKeepalive: "30s"
   dialTimeout: "30s"
   retryOnStale: true
-  watchdogPeriod: "30s"
 ```
 
-The values above are the defaults from `.kportal.yaml`.
+Health check methods:
+- `tcp-dial` - Fast TCP connection test
+- `data-transfer` - Verifies tunnel functionality by attempting data read
 
-- `tcp-dial` opens a TCP connection to the local port.
-- `data-transfer` also tries to read data through the tunnel. It is the default.
-- A connection past `maxConnectionAge` reconnects only when it is also idle, so a running transfer is not cut.
-- `watchdogPeriod` is the interval of the check for hung workers.
+Connection age reconnection only triggers when the connection is also idle, preventing interruption of active transfers like database dumps.
 
-### mDNS
+### mDNS Hostnames
+
+Enable mDNS to access forwards via `.local` hostnames:
 
 ```yaml
 mdns:
@@ -293,22 +225,22 @@ contexts:
           - resource: service/postgres
             port: 5432
             localPort: 5432
-            alias: prod-db   # reachable as prod-db.local:5432
+            alias: prod-db  # Accessible via prod-db.local:5432
 ```
 
-- `alias: prod-db` publishes `prod-db.local`.
-- Without an alias, `service/redis` publishes `redis.local`.
-- A bare `pod` with a selector and no alias is not published.
-- Services register as `_kportal._tcp`.
-
-Check registration:
+- Explicit `alias` becomes `<alias>.local`
+- Without alias, hostname is generated from resource name (`service/redis` → `redis.local`)
+- Works on macOS (Bonjour) and Linux (avahi-daemon)
 
+Verify registration:
 ```bash
 dns-sd -B _kportal._tcp local       # macOS
 avahi-browse -t _kportal._tcp       # Linux
 ```
 
-### Table columns
+### Table Columns
+
+Choose which columns the forwards table shows, and in what order. The setting applies to the interactive UI and the `-verbose` table:
 
 ```yaml
 tui:
@@ -320,83 +252,90 @@ tui:
     - name: status
 ```
 
-- Valid names: `context`, `namespace`, `alias`, `type`, `resource`, `remote`, `local`, `status`.
-- List order is render order. Unlisted columns are hidden.
-- `width` is the maximum text width, 1 to 200. Without it, the column keeps its default width.
-- Without `tui`, the table keeps its default columns and order.
-- The setting applies to the UI and to the `-v` table, and reloads with the file.
+- Valid names: `context`, `namespace`, `alias`, `type`, `resource`, `remote`, `local`, `status`
+- The list order is the render order, and unlisted columns are hidden
+- `width` is the maximum text width, from 1 to 200. If you omit it, the column keeps its default width
+- If you omit `tui`, the table keeps its default columns and order
+- Changes apply on hot-reload
 
 ## Usage
 
-### Command line
-
-| Command or flag | Effect |
-|-----------------|--------|
-| `kportal` | Start the terminal UI. |
-| `-c <file>` | Config file. Default `.kportal.yaml`. |
-| `-v` | Verbose logging. In headless mode it sets the log level only. |
-| `-headless` | No UI. Logs go to stderr. |
-| `-check` | Validate the config and exit. |
-| `-context <name>` | Forward only the named contexts. Repeatable and comma-separated. |
-| `-log-format text\|json` | Log format. Default `text`. |
-| `-convert <file>` | Convert a kftray JSON file to kportal YAML. |
-| `-convert-output <file>` | Output of `-convert`. Default `.kportal.yaml`. |
-| `-update` | Check for updates and exit. |
-| `-version` | Print the version and exit. |
-| `kportal generate` | Add forwards from a cluster. |
-| `kportal completion` | Print or install a shell completion script. |
-
-Each flag also accepts the double-dash form, for example `--check`.
-
-### Interactive mode
+### Interactive Mode
 
 ```bash
 kportal
 ```
 
-### Verbose mode
+### Verbose Mode
 
 ```bash
 kportal -v
 ```
 
-Without `-headless`, `-v` prints a plain-text table that redraws. The table uses the same status words as the UI. When stdout is not a terminal, it draws `✓ Active`, `⋯ Starting`, `↻ Reconnecting` and `✗ Error`.
+### Headless Mode
 
-### Headless mode
+Run without TUI for scripting and automation:
 
 ```bash
 kportal -headless
-kportal -headless -v 2>kportal.log &
-kportal -headless -log-format json
 ```
 
-Headless mode logs to stderr, so you can redirect it to a file or the systemd journal. `-v` sets the log level, not the destination.
+Headless mode emits both structured and standard-library logs to stderr by default
+(suitable for redirecting to a log file or systemd journal). The `-v` flag controls
+log level (debug vs info), not destination.
 
-### Validate configuration
+Combines well with verbose mode for background operation:
 
 ```bash
-kportal -check
+kportal -headless -v 2>kportal.log &
 ```
 
-### Custom config file
+### Validate Configuration
+
+```bash
+kportal --check
+```
+
+### Custom Config File
 
 ```bash
 kportal -c /path/to/config.yaml
 ```
 
-### Select contexts
+### Select Contexts
 
-By default kportal forwards every context in the file. `--context` limits the run to the contexts you name:
+By default every context in the config file is forwarded. `--context` limits the
+run to the contexts you name, which is useful when the file describes several
+clusters but you only work against one at a time:
 
 ```bash
 kportal --context development-team-a
+```
+
+The flag is repeatable and accepts comma-separated values, so these are
+equivalent:
+
+```bash
 kportal --context team-a --context team-b
 kportal --context team-a,team-b
 ```
 
-An unknown name is an error that lists the contexts in the file. Those are the `contexts[].name` values in `.kportal.yaml`, not every context in your kubeconfig.
+It composes with the other modes, and works well as a per-cluster shell alias:
 
-Local-port conflicts are only reported between forwards that can run together. With `--context`, contexts you never select together can reuse a `localPort`:
+```bash
+alias kp-a='kportal --context development-team-a'
+kportal --context development-team-a -headless
+```
+
+An unknown context name is an error that lists the contexts the file defines, so
+a typo fails loudly instead of silently forwarding nothing.
+
+#### Reusing local ports across contexts
+
+Local-port conflicts are only reported between forwards that could run at the
+same time. Contexts that are never selected together may therefore reuse the
+same `localPort`, so the same service keeps the same local port in every
+cluster and the app you are developing never needs reconfiguring:
 
 ```yaml
 contexts:
@@ -418,9 +357,15 @@ contexts:
           - <<: *rate-service   # same local port, no conflict
 ```
 
-Without `--context`, or with both contexts named, the duplicate port is an error.
+This requires passing `--context`. Without it every context is active, so the
+duplicate ports above would genuinely collide and are still reported as an
+error - as is naming both contexts at once (`--context team-a,team-b`).
 
-### Generate
+### Generate Forwards from a Cluster
+
+The `generate` subcommand discovers services in a Kubernetes context and lets you
+interactively pick which ones to forward. Selected entries are appended to the
+config file with consecutive local ports starting from a value you choose.
 
 ```bash
 kportal generate --context=my-cluster
@@ -430,51 +375,97 @@ kportal generate --context=my-cluster --dry-run
 
 | Flag | Description |
 |------|-------------|
-| `--context` | Required. Kubernetes context to scan. |
-| `--config` | Config file to append to. Default `.kportal.yaml`. |
-| `--dry-run` | Print the planned forwards. Do not change the config. |
+| `--context` | (required) Kubernetes context to scan |
+| `--config` | Path to kportal config file (default: `.kportal.yaml`) |
+| `--dry-run` | Print the planned forwards but do not modify the config |
 
-Steps:
+The interactive flow has three steps:
 
-1. Namespaces: select with `space`, toggle all with `a`, filter with `/`.
-2. Services: same keys. Services already in the config are locked. Non-TCP ports are skipped.
-3. Port assignment: choose a first local port (default `10000`, minimum `1024`). Ports are assigned in order and skip ports in use.
+1. **Namespaces** — multi-select with `space`, toggle-all with `a`, filter with `/`.
+2. **Services** — same controls; rows already present in the config are locked off, and non-TCP ports are skipped (UDP is not supported by kportal's forward layer).
+3. **Port assignment** — choose a starting local port (default `10000`, must be ≥ `1024`). Local ports are assigned consecutively in stable order, skipping any already in use.
 
-Press `enter` on the last step to save (or print, with `--dry-run`), `b` to go back, `esc` to cancel.
+Press `enter` on the final step to save (or to print and exit when `--dry-run` is set), `b` to go back, or `esc` to cancel.
 
-The `--dry-run` output has this form (example values):
+## Status Indicators
 
-```text
-[dry-run] Would add 2 forwards to .kportal.yaml
-  10000 → my-cluster/default/service/api:8080
-  10001 → my-cluster/default/service/postgres:5432
-```
-
-### Shell completion
-
-```bash
-kportal completion --shell zsh            # print the script
-kportal completion --shell zsh --install  # install it
-kportal completion --uninstall            # remove it
-```
-
-Without `--shell`, kportal detects the shell. Supported shells: bash, zsh, fish.
-
-## Status indicators
-
-| Indicator | Meaning |
-|-----------|---------|
+| Indicator | Description |
+|-----------|-------------|
 | `● Active` | Connection healthy |
-| `○ Starting` | First connection. Failed health checks show Starting for the first 10s. |
-| `◐ Reconnecting` | Reconnecting after a failure |
+| `○ Starting` | Initial connection (10s grace period) |
+| `◐ Reconnecting` | Reconnecting after failure |
 | `✗ Error` | Connection failed |
-| `○ Disabled` | Turned off in the UI |
+| `○ Disabled` | Manually disabled |
 
-## Advanced features
+## Advanced Features
 
-### HTTP traffic logging
+### HTTP Traffic Logging
 
-Press `l` on a forward that has `httpLog` set.
+Press `l` in the TUI to view real-time HTTP traffic for a selected forward. The log viewer shows:
+
+| Column | Description |
+|--------|-------------|
+| TIME | Request timestamp |
+| METHOD | HTTP method (GET, POST, etc.) |
+| STATUS | Response status code |
+| LATENCY | Request duration |
+| PATH | Request path |
+
+**List view shortcuts:**
+
+| Key | Action |
+|-----|--------|
+| `↑/↓` | Navigate entries |
+| `Enter` | View request details |
+| `g/G` | Jump to top/bottom |
+| `a` | Toggle auto-scroll |
+| `f` | Cycle filter mode (All → Non-2xx → Errors) |
+| `/` | Search by path or method |
+| `c` | Clear all filters |
+| `q` | Close log viewer |
+
+**Detail view:**
+
+Press `Enter` on any entry to see full request/response details including:
+- Request and response headers (alphabetically sorted)
+- Request and response bodies
+- Timing information and status codes
+
+| Key | Action |
+|-----|--------|
+| `↑/↓` | Scroll content |
+| `PgUp/PgDn` | Scroll by page |
+| `g` | Jump to top |
+| `c` | Copy response body to clipboard |
+| `Esc/q` | Return to list |
+
+**Body display features:**
+- **JSON formatting** - JSON bodies are pretty-printed with syntax highlighting
+- **Compression handling** - gzip/deflate content is automatically decompressed
+- **Binary detection** - Binary content shows a placeholder instead of garbled data
+
+**Filter modes:**
+- **All** - Show all entries
+- **Non-2xx** - Hide successful (2xx) responses
+- **Errors** - Show only 4xx and 5xx responses
+
+**Toggling per-forward logging:**
+
+In the add/edit wizard, press `h` on the confirmation step to toggle `httpLog` on or
+off for the current forward. The wizard preserves any advanced `httpLog` keys
+(`logFile`, `includeHeaders`, `maxBodySize`, `filterPath`) you set in YAML.
+
+**Header redaction:**
+
+When `httpLog.includeHeaders: true` is set, sensitive header values are
+automatically replaced with `[REDACTED]`. The header name is preserved so you can
+see that an `Authorization` header was present without exposing its value. Redacted
+headers include `Authorization`, `Cookie`, `Set-Cookie`, `X-Api-Key`,
+`X-Auth-Token`, `X-Csrf-Token`, `Proxy-Authorization`, `X-Access-Token`, and any
+header whose name contains `token`, `secret`, `password`, or `apikey`. This is
+always on and cannot be disabled.
+
+**Advanced configuration:**
 
 ```yaml
 forwards:
@@ -483,88 +474,48 @@ forwards:
     localPort: 8080
     httpLog:
       enabled: true
-      includeHeaders: true   # sensitive values are redacted
-      maxBodySize: 65536     # bytes
-      filterPath: "/api/"    # log only paths containing this text
-      logFile: "api.log"     # also append entries to this file
+      includeHeaders: true   # values of sensitive headers are redacted
+      maxBodySize: 65536     # bytes; 0 = unlimited
+      filterPath: "/api/"    # only log paths matching this substring
+      logFile: "api.log"     # append entries to a file in addition to the in-memory ring
 ```
 
-`maxBodySize` defaults to 1 MB (1048576 bytes) when you omit it or set a value of 0 or less.
+### Connection Benchmarking
 
-List view columns: TIME, METHOD, STATUS, LATENCY, PATH.
+Press `b` in the TUI to benchmark a selected forward. Configure:
 
-| Key | Action |
-|-----|--------|
-| `Up` `Down` | Move |
-| `Enter` | Open details |
-| `g` / `G` | Top / bottom |
-| `a` | Toggle auto-scroll |
-| `f` | Cycle filter: All, Non-2xx, Errors |
-| `/` | Search path or method |
-| `c` | Clear filters |
-| `q` | Close |
+- **URL Path** - Target endpoint (default: `/`)
+- **Method** - HTTP method (GET, POST, etc.)
+- **Concurrency** - Number of parallel workers
+- **Requests** - Total number of requests
 
-The detail view shows sorted request and response headers, bodies and timing. JSON bodies are pretty-printed, gzip and deflate bodies are decoded, and binary bodies show a placeholder.
+Results include:
+- Success/failure counts
+- Min/Max/Avg latency
+- P50/P95/P99 percentiles
+- Throughput (requests/sec)
+- Status code distribution
 
-| Key | Action |
-|-----|--------|
-| `Up` `Down` / `PgUp` `PgDn` | Scroll |
-| `g` | Top |
-| `c` | Copy the response body |
-| `Esc` / `q` / `Enter` | Back to the list |
+### Hot-Reload
 
-#### Sensitive header redaction
-
-With `includeHeaders: true`, kportal replaces these header values with `[REDACTED]` and keeps the name: `Authorization`, `Cookie`, `Set-Cookie`, `X-Api-Key`, `X-Auth-Token`, `X-Csrf-Token`, `Proxy-Authorization`, `X-Access-Token`, and any name containing `token`, `secret`, `password` or `apikey` (any case). You cannot turn this off. Source: `internal/httplog/proxy.go`.
-
-### Benchmarking
-
-Press `b` on a forward. Set the URL path (default `/`), the HTTP method, the concurrency and the request count. The wizard starts at 10 workers and 100 requests.
-
-The results screen has this layout (`x.xx` marks a measured value):
-
-```text
-Total Requests:  100
-Successful:      100 (100.0%)
-Failed:          0
-
-Latency (ms)
-  Min:    x.xx
-  Max:    x.xx
-  Avg:    x.xx
-  P50:    x.xx
-  P95:    x.xx
-  P99:    x.xx
-
-Throughput
-  Requests/sec:  x.xx
-  Bytes read:    n
-
-Status Codes
-  200: n
-```
-
-Only 2xx responses count as successful.
-
-### Hot reload
-
-kportal reloads when the config file changes. To reload by hand:
+Configuration changes are applied automatically. Manual reload:
 
 ```bash
 kill -HUP $(pgrep kportal)
 ```
 
-New forwards start, removed forwards stop and unchanged forwards keep running. An invalid config is rejected and the previous one stays active.
+### Port Conflict Detection
 
-### Port conflict detection
+kportal validates port availability at startup and during hot-reload, showing which process is using conflicting ports.
 
-kportal checks that local ports are free at startup and on reload. The report names the process that holds a busy port. kportal finds it with `lsof` on Linux and macOS and `tasklist` on Windows. A reload that would bind a busy port is rejected and the previous config stays active.
+Conflicts are only reported between forwards that could be running together.
+With `--context`, forwards in contexts outside the selection are ignored, which
+is what lets each context reuse the same `localPort` values - see
+[Reusing local ports across contexts](#reusing-local-ports-across-contexts).
 
-Conflicts are only reported between forwards that can run together. See [Select contexts](#select-contexts).
+### Retry Strategy
 
-### Retry strategy
-
-Exponential backoff with 10% jitter: 1s, 2s, 4s, 8s, then 10s (cap). Retries continue until the connection succeeds.
+Exponential backoff: 1s → 2s → 4s → 8s → 10s (max). Retries continue indefinitely until connection succeeds.
 
 ## Migration from kftray
 
@@ -572,63 +523,88 @@ Exponential backoff with 10% jitter: 1s, 2s, 4s, 8s, then 10s (cap). Retries con
 kportal --convert configs.json --convert-output .kportal.yaml
 ```
 
-`-convert-output` defaults to `.kportal.yaml`.
+## Signal Handling
 
-## Signal handling
+- `Ctrl+C` / `SIGTERM` - Graceful shutdown
+- `SIGHUP` - Reload configuration
 
-| Signal | Effect |
-|--------|--------|
-| `Ctrl+C`, `SIGTERM` | Graceful shutdown |
-| `SIGHUP` | Reload the configuration |
+## 🐛 Troubleshooting
 
-## Troubleshooting
-
-Port already in use:
+### Port Already in Use
 
 ```bash
 lsof -i :<port>
 kill <pid>
 ```
 
-Connection refused:
+### Connection Refused
 
-1. Check the pod: `kubectl get pods -n <namespace>`
-2. Check the port: `kubectl describe pod <pod>`
-3. Check the service endpoints: `kubectl get endpoints <service>`
+1. Verify pod is running: `kubectl get pods -n <namespace>`
+2. Verify port is correct: `kubectl describe pod <pod>`
+3. Check service endpoints: `kubectl get endpoints <service>`
 
-Context not found: list your contexts with `kubectl config get-contexts`. kportal reports `context <name> not found in kubeconfig` when a `contexts[].name` value is not in your kubeconfig. Names with `@`, `.`, `:` or `/` (for example `admin@home` or an EKS ARN) are valid. If `--context` reports `unknown context`, the name is missing from `contexts[].name` in the config file.
-
-The add wizard shows a namespace prompt instead of a list: the cluster refused or returned an empty namespace list. Type the namespace name.
-
-## Development
-
-Requires Go 1.26 or later, kubectl and access to a cluster.
+### Context Not Found
 
 ```bash
-make build    # build the binary
-make test     # run tests
-make all      # fmt, vet, staticcheck, test
-make install  # install locally
+kubectl config get-contexts
 ```
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Release history is in [CHANGELOG.md](CHANGELOG.md).
+Context names containing `@`, `.`, `:`, or `/` (e.g. `admin@home`,
+`[email protected]`, GKE dotted names, EKS ARNs) are accepted by the
+config validator.
+
+If `--context` reports `unknown context "..."`, the name does not match any
+`contexts[].name` in the config file. The error lists the names that are
+defined - note these are the contexts in your `.kportal.yaml`, which need not be
+every context in your kubeconfig.
+
+## 🔧 Development
+
+### Prerequisites
+
+- Go 1.23+
+- Kubernetes cluster access
+- kubectl configured
+
+### Build
+
+```bash
+make build    # Build binary
+make test     # Run tests
+make all      # fmt, vet, staticcheck, test
+make install  # Install locally
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## Telemetry
 
-On startup kportal sends one anonymous adoption ping: project name, version and timestamp. It has a 2-second timeout and cannot block startup.
+On startup this binary sends a single anonymous adoption ping — project name,
+version, timestamp; no identifiers, no command output, no payload contents.
+Fire-and-forget with a 2-second timeout; cannot block startup or panic.
 
-To opt out, set `DO_NOT_TRACK=1`, `OSS_TELEMETRY_DISABLED=1` or `KPORTAL_DISABLE_TELEMETRY=1`. See [oss-telemetry](https://github.com/lukaszraczylo/oss-telemetry#disabling-telemetry) for the wire format and source.
+See **[oss-telemetry — Disabling telemetry](https://github.com/lukaszraczylo/oss-telemetry#disabling-telemetry)**
+for the exact wire format, source, and full opt-out documentation.
+
+Quick opt-out: set any of `DO_NOT_TRACK=1`, `OSS_TELEMETRY_DISABLED=1`,
+or `KPORTAL_DISABLE_TELEMETRY=1`.
 
 ## License
 
-MIT. See [LICENSE](LICENSE).
+MIT License - see [LICENSE](LICENSE).
 
-## Credits
+## Acknowledgments
 
-[Bubble Tea](https://github.com/charmbracelet/bubbletea), [Lipgloss](https://github.com/charmbracelet/lipgloss), [client-go](https://github.com/kubernetes/client-go). [kftray](https://github.com/hcavarsan/kftray) was the inspiration.
+- [Bubble Tea](https://github.com/charmbracelet/bubbletea) - Terminal UI framework
+- [Lipgloss](https://github.com/charmbracelet/lipgloss) - Terminal styling
+- [client-go](https://github.com/kubernetes/client-go) - Kubernetes client
+- [kftray](https://github.com/hcavarsan/kftray) - Inspiration
 
 ## Links
 
 - [Website](https://lukaszraczylo.github.io/kportal)
 - [Issues](https://github.com/lukaszraczylo/kportal/issues)
 - [Releases](https://github.com/lukaszraczylo/kportal/releases)
+- [Changelog](CHANGELOG.md)

go.mod

@@ -9,11 +9,11 @@ require (
 	github.com/go-logr/logr v1.4.4
 	github.com/grandcat/zeroconf v1.0.0
 	github.com/lukaszraczylo/oss-telemetry v0.2.3
-	github.com/stretchr/testify v1.11.1
+	github.com/stretchr/testify v1.12.1
 	gopkg.in/yaml.v3 v3.0.1
-	k8s.io/api v0.37.0
-	k8s.io/apimachinery v0.37.0
-	k8s.io/client-go v0.37.0
+	k8s.io/api v0.37.1
+	k8s.io/apimachinery v0.37.1
+	k8s.io/client-go v0.37.1
 	k8s.io/klog/v2 v2.140.0
 )
 
@@ -60,7 +60,6 @@ require (
 	github.com/muesli/cancelreader v0.2.2 // indirect
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
-	github.com/pmezard/go-difflib v1.0.1-0.20181226105442-5d4384ee4fb2 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/spf13/pflag v1.0.10 // indirect
 	github.com/x448/float16 v0.8.4 // indirect
@@ -77,7 +76,7 @@ require (
 	gopkg.in/evanphx/json-patch.v4 v4.13.0 // indirect
 	gopkg.in/inf.v0 v0.9.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20260821135717-be32def86098 // indirect
-	k8s.io/streaming v0.37.0 // indirect
+	k8s.io/streaming v0.37.1 // indirect
 	k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3 // indirect
 	sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect

go.sum

@@ -133,8 +133,8 @@ github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+
 github.com/stretchr/objx v0.5.3 h1:jmXUvGomnU1o3W/V5h2VEradbpJDwGrzugQQvL0POH4=
 github.com/stretchr/objx v0.5.3/go.mod h1:rDQraq+vQZU7Fde9LOZLr8Tax6zZvy4kuNKF+QYS+U0=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
-github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
-github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
+github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
 github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
 github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
 github.com/xo/terminfo v1.0.0 h1:2ZpYzqWzyyytjk3TP6aJVDhkMAkc99/1xKQdA3TDTBY=
@@ -185,18 +185,18 @@ gopkg.in/inf.v0 v0.9.1 h1:73M5CoZyi3ZLMOyDlQh031Cx6N9NDJ2Vvfl76EDAgDc=
 gopkg.in/inf.v0 v0.9.1/go.mod h1:cWUDdTG/fYaXco+Dcufb5Vnc6Gp2YChqWtbxRZE0mXw=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
-k8s.io/api v0.37.0 h1:Z//Vj9N7RA/yS2sDmxyeo7h+RR4zbUrd2vrd3Z0TbB4=
-k8s.io/api v0.37.0/go.mod h1:LKXgcJWMc+f4OLbP5SFR8rulEg07zZhpi/zMULiBImk=
-k8s.io/apimachinery v0.37.0 h1:Np2AbDtf8x6RDHiD8T9LbKJ9gaegeVNa8yNm5FuGKm0=
-k8s.io/apimachinery v0.37.0/go.mod h1:RN3nhprFSCxOi5Selxd7oMTXOe/c+ZbcE7Im+TS2zkE=
-k8s.io/client-go v0.37.0 h1:nsN31fy8wBySuZ+QRnKmrjRSQLOG2rvoGN0tKd12zhQ=
-k8s.io/client-go v0.37.0/go.mod h1:FcGqw+Ll/gNQiq+nPGY1Oyt9y7SgDh1d3MW3RFDEbn0=
+k8s.io/api v0.37.1 h1:l6N77U7tjwB5L056bgrBTJIEdevac/naBZ3iSvDNfpM=
+k8s.io/api v0.37.1/go.mod h1:zSlbB1YpJ1YQlFVQy20UYll81UJSJJUMLhkhvg6Z78M=
+k8s.io/apimachinery v0.37.1 h1:hGCYyvKHCwtwMitj2vU4vYx0Z16N9GyZk9BBnz0wDAE=
+k8s.io/apimachinery v0.37.1/go.mod h1:jF84AyUi/IRIXRot5f+lm6MpxoWI+F1XgjaMmwCdTFw=
+k8s.io/client-go v0.37.1 h1:QTv/5ha4jAHtW9qxxVBkQVFBRDb4jHfFopQqqMdc+wM=
+k8s.io/client-go v0.37.1/go.mod h1:dnAPtTnCNY38Ho04D2KdY1F4IKausa9UbqaAZKl60SY=
 k8s.io/klog/v2 v2.140.0 h1:Tf+J3AH7xnUzZyVVXhTgGhEKnFqye14aadWv7bzXdzc=
 k8s.io/klog/v2 v2.140.0/go.mod h1:o+/RWfJ6PwpnFn7OyAG3QnO47BFsymfEfrz6XyYSSp0=
 k8s.io/kube-openapi v0.0.0-20260821135717-be32def86098 h1:z5+pcu1jTyKK5mNTe2/+x+U6Uuv9jRVOJQLaBJJMpeI=
 k8s.io/kube-openapi v0.0.0-20260821135717-be32def86098/go.mod h1:0/mqHCVhlumdJ3BhCfnjSZQE037nAhNodh1/hK0T8/I=
-k8s.io/streaming v0.37.0 h1:iPBUZLZiKt5bV+lxJurASMOV07VuBhNpiwJt2//AWrM=
-k8s.io/streaming v0.37.0/go.mod h1:APlJR26ZWRcVy5bIEj0QRrKUXROtBHPcxl2NT7EAzPU=
+k8s.io/streaming v0.37.1 h1:TpzVfQeFuVndn2g9mFqxy1UcUYPwDzqjUmwR/IzJCWc=
+k8s.io/streaming v0.37.1/go.mod h1:APlJR26ZWRcVy5bIEj0QRrKUXROtBHPcxl2NT7EAzPU=
 k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3 h1:jVkFFVfXdXP74B/zbO3hM3hpSFD0xvhQ5U686DPurkE=
 k8s.io/utils v0.0.0-20260707023825-cf1189d6abe3/go.mod h1:M2s5JB1lIYP3jzZdorPLHXIPJzt9vv2muW5a6L9DtNM=
 sigs.k8s.io/json v0.0.0-20250730193827-2d320260d730 h1:IpInykpT6ceI+QxKBbEflcR5EXP7sU1kvOlxwZh5txg=