Add CHANGELOG, CONTRIBUTING, and GitHub Issue/PR templates for v0.2.0

The / filter in the list component captured keystrokes after returning
from tmux, showing random text like 'cc' and blocking cursor navigation.
Filtering is not needed for the 3-level context/team/namespace flow.

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug Report
+about: Report a bug to help us improve kctl-tui
+title: ""
+labels: bug
+assignees: ""
+---
+
+## Describe the Bug
+
+A clear description of what the bug is.
+
+## Steps to Reproduce
+
+1. Run `kctl-tui ...`
+2. Select '...'
+3. See error
+
+## Expected Behavior
+
+What you expected to happen.
+
+## Actual Behavior
+
+What actually happened.
+
+## Environment
+
+- OS: [e.g. Windows 11, Ubuntu 24.04, macOS 15]
+- Go version: [e.g. 1.22.5]
+- kctl-tui version: [e.g. v0.2.0]
+- kubectl version: [e.g. v1.30.0]
+- tmux/psmux version: [e.g. tmux 3.4, psmux latest]
+- Terminal: [e.g. Windows Terminal, iTerm2, GNOME Terminal]
+
+## Additional Context
+
+Config file (without secrets), error logs, or screenshots.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,23 @@
+---
+name: Feature Request
+about: Suggest a new feature or improvement
+title: ""
+labels: enhancement
+assignees: ""
+---
+
+## Problem
+
+What problem does this feature solve?
+
+## Proposed Solution
+
+Describe the solution you'd like.
+
+## Alternatives Considered
+
+Any alternative solutions or workarounds you considered.
+
+## Additional Context
+
+Any mockups, examples, or references.

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+Brief description of what this PR does.
+
+## Changes
+
+- ...
+
+## Related Issues
+
+Closes #
+
+## Testing
+
+- [ ] `go vet ./...` passes
+- [ ] `go test ./...` passes
+- [ ] Manually tested on [OS]
+
+## Checklist
+
+- [ ] Code follows existing style
+- [ ] No new comments added (unless necessary)
+- [ ] CHANGELOG.md updated (if applicable)

.github/workflows/build.yml

@@ -60,7 +60,7 @@ jobs:
           ext=""
           if [ "${{ matrix.goos }}" = "windows" ]; then ext=".exe"; fi
           out="dist/kctl-tui-${{ matrix.goos }}-${{ matrix.goarch }}${ext}"
-          go build -o "$out" -ldflags "-s -w" ./cmd/kctl-tui
+          go build -o "$out" -ldflags "-s -w -X main.version=${GITHUB_REF_NAME}" ./cmd/kctl-tui
           echo "Built $out"
 
       - name: Upload artifact

CHANGELOG.md

@@ -0,0 +1,59 @@
+# Changelog
+
+All notable changes to kctl-tui will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-08-09
+
+### Added
+- **Windows support** via [psmux](https://github.com/marlocarlo/psmux) as tmux-compatible multiplexer
+- `install.ps1` PowerShell install script for Windows
+- `--help` flag with full usage documentation
+- `--version` / `-v` flag (set via `-ldflags` at build time)
+- `kctl-tui doctor` command to verify tools, config and cluster connectivity
+- `kctl-tui config check` command to validate `~/.kctl-tui/config.yaml`
+- `--verbose` flag for debug logging of all kubectl/aws commands to stderr
+- Binary secret value detection (`IsBinary`) — base64 or non-UTF-8 content is flagged
+- ExternalSecret name validation before force-sync
+- `CheckTool()` and `CheckAWSAuth()` helpers for pre-flight checks
+- Diff table scroll support (j/k, up/down arrows)
+- `--command pods` flag for k9s to start directly in pod view
+- `--namespace` flag for k9s (Windows compatibility)
+
+### Fixed
+- Tmux session cleanup: stale sessions are killed before creating new ones
+- Panel path: uses `os.Executable()` instead of PATH lookup for correct binary
+- k9s on Windows: `--namespace` instead of `-n`, direct pods view
+- `--help` always shows usage and exits (no fallthrough to TUI)
+- Unknown subcommands show error message + usage (exit 1)
+- Panel quit: properly closes tmux session and exits
+- Bubbles list filter disabled to prevent stuck filter state after tmux return
+
+### Changed
+- Config uses `k8s_secret_name_template` for Kubernetes secret names (separate from AWS `secret_name_template`)
+- Contexts resolved via template (`context_template`) instead of live kubectl discovery
+- Panel redesigned: env-first menu (quit/beta/prod) with secrets sync + redeploy
+- Full-mode navigation starts at team selection with default context
+- `tea.ExecProcess` only used for `tmux attach` — setup commands run synchronously
+
+### Removed
+- Context-pair logic (superseded by env-template based context resolution)
+- Live kubectl discovery (superseded by config templates)
+
+## [0.1.0] - 2026-07-XX
+
+### Added
+- Initial release with Bubble Tea TUI
+- 3-pane tmux orchestration (control panel + 2x k9s)
+- Team/namespace navigation with kubectl context switching
+- Panel mode with redeploy and secrets diff/force-sync
+- AWS SSO integration with interactive login prompt
+- CI/CD pipeline with Go build and release
+- Linux/macOS install script
+
+[Unreleased]: https://github.com/skoelle/kctl-tui/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/skoelle/kctl-tui/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/skoelle/kctl-tui/releases/tag/v0.1.0

CONTRIBUTING.md

@@ -0,0 +1,95 @@
+# Contributing to kctl-tui
+
+Thanks for your interest in contributing! This document explains how to get
+started.
+
+## Development Setup
+
+```bash
+git clone https://github.com/skoelle/kctl-tui.git
+cd kctl-tui
+go mod download
+```
+
+### Prerequisites
+
+- Go 1.22+
+- kubectl, k9s, tmux (or psmux on Windows)
+- An active Kubernetes cluster for integration testing
+
+### Running Locally
+
+```bash
+go run ./cmd/kctl-tui
+```
+
+### Building
+
+```bash
+go build -o kctl-tui ./cmd/kctl-tui
+```
+
+### With Version Tag
+
+```bash
+go build -ldflags "-X main.version=v0.2.0" -o kctl-tui ./cmd/kctl-tui
+```
+
+## Project Structure
+
+```
+cmd/kctl-tui/          Entry points (main, full mode, panel mode)
+internal/config/       YAML config loading and template resolution
+internal/kctl/         Pure logic (secret diffing, template engine)
+internal/kubeexec/     kubectl/aws/tmux wrappers (side effects only)
+```
+
+### Architecture Rules
+
+- **Pure logic** goes into `internal/kctl` or `internal/config` — no exec, no I/O.
+- **Side effects** (running kubectl, aws, tmux) go into `internal/kubeexec`.
+- **UI** lives in `cmd/kctl-tui/` — Bubble Tea models, views, handlers.
+- Unit tests cover pure logic only. Side-effect packages are tested via
+  integration/manual tests.
+
+## Testing
+
+```bash
+go vet ./...       # static analysis
+go test ./...      # unit tests
+```
+
+There are no integration tests yet. Manual testing against a real cluster is
+expected for UI and kubeexec changes.
+
+## Code Style
+
+- Standard Go formatting (`gofmt`).
+- No comments unless the logic is non-obvious.
+- Error messages should be actionable — tell the user what to fix.
+- Log commands with `kubeexec.VerboseLog()` when `--verbose` is active.
+
+## Commits
+
+- One logical change per commit.
+- Imperative mood in commit messages ("Add ...", "Fix ...", "Remove ...").
+- No co-authors in commits.
+
+## Pull Requests
+
+1. Fork the repo and create a feature branch.
+2. Make your changes following the style guide above.
+3. Run `go vet` and `go test`.
+4. Open a PR against `main` with a clear description of what changed and why.
+5. Reference any related issues.
+
+## Issues
+
+- Use the provided issue templates.
+- Include your OS, Go version, and kctl-tui version.
+- For bugs: steps to reproduce, expected vs actual behavior.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the
+MIT License.

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Stefan Koelle
+Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

PLAN.md

@@ -66,21 +66,22 @@ is still open. For the full requirements, see [SPEC.md](SPEC.md).
 - [ ] Paginate/scroll the secrets diff table for secrets with many fields
       instead of relying on terminal wrapping.
 
-## Phase 3 — Windows-native support (open, secondary priority)
+## Phase 3 — Windows-native support (done)
 
-- [ ] Detect OS at runtime; on native Windows (no WSL), fall back to
-      `wt.exe split-pane` instead of `tmux` for the status panes.
-- [ ] Document/implement that `Esc`-triggered session close is **not**
-      available in the native Windows fallback — the panes must be closed
-      manually there.
+- [x] Windows support via [psmux](https://github.com/marlocarlo/psmux) —
+      a native, tmux-compatible terminal multiplexer. kctl-tui works
+      without code changes; `CheckTool("tmux")` error message includes
+      Windows-specific install hint.
+- [x] `install.ps1` — PowerShell install script for Windows.
+- [x] Updated README and SPEC with Windows + psmux setup instructions.
 
 ## Phase 4 — Nice-to-haves (open, not committed)
 
+- [x] `--version` flag — prints version, set via `-ldflags` at build time.
+- [x] Config validation command (`kctl-tui config check`) — validates
+      required fields and shows a resolved context example.
 - [ ] Optional direct use of `client-go` instead of shelling out to
       `kubectl`, for faster context/namespace/label queries.
-- [ ] Config validation command (`kctl-tui config check`) that reports
-      unknown label keys or context names not present in the current
-      kubeconfig.
 - [ ] Homebrew tap / `scoop` manifest as additional install options
       alongside `install.sh`.
 

README.md

@@ -68,12 +68,16 @@ See [SPEC.md](SPEC.md) for the full requirements and design rationale, and
   Configuration below - they must already exist in your kubeconfig, e.g.
   added via `aws eks update-kubeconfig`).
 - `k9s` (used for the two status panes).
-- `tmux` (used for the 3-pane layout). On Windows, this means running
-  kctl-tui inside **WSL** — `tmux` has no native Windows port. Native
-  Windows Terminal has its own split-pane feature, but it cannot be
-  scripted from inside a pane the way `tmux` can, so the automated 3-pane
-  layout and the `Esc` session handling described above are only fully
-  supported under Linux/WSL. See SPEC.md section 3.6 for details.
+- `tmux` (used for the 3-pane layout). On **Linux/macOS**, install
+  `tmux` via your package manager. On **Windows**, install
+  [psmux](https://github.com/marlocarlo/psmux) — a native,
+  tmux-compatible terminal multiplexer:
+  ```powershell
+  scoop install psmux
+  # or
+  cargo install psmux
+  ```
+  psmux provides a `tmux` command, so kctl-tui works without changes.
 - `aws` CLI, configured with credentials, only needed for the secrets
   workflow.
 
@@ -85,6 +89,15 @@ See [SPEC.md](SPEC.md) for the full requirements and design rationale, and
 curl -fsSL https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.sh | bash
 ```
 
+### Quick install (Windows)
+
+```powershell
+irm https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.ps1 | iex
+```
+
+This downloads the latest release binary for your architecture from
+GitHub Releases and installs it to your PATH.
+
 This downloads the latest release binary for your OS/architecture from
 GitHub Releases and installs it to `/usr/local/bin/kctl-tui`.
 
@@ -167,17 +180,37 @@ aws_sso_login_command: "aws sso login"
 that way — it typically contains your organization's internal account ID,
 context naming, and label names.
 
-## WSL setup notes
+## Windows notes
 
-If `kubectx`/`kubens` or `kctl-tui` report a missing kubeconfig inside WSL,
-your kubeconfig most likely only exists on the Windows side. Symlink it
-into WSL:
+On native Windows (without WSL), install [psmux](https://github.com/marlocarlo/psmux)
+for the 3-pane layout. psmux is a native Windows terminal multiplexer
+that is tmux-compatible — kctl-tui works without code changes:
+
+```powershell
+scoop install psmux
+# or
+cargo install psmux
+```
+
+If you prefer WSL, symlink your kubeconfig into WSL:
 
 ```bash
 mkdir -p ~/.kube
 ln -s /mnt/c/Users/<your-windows-username>/.kube/config ~/.kube/config
 ```
 
+## Usage
+
+```bash
+kctl-tui                    # start the TUI (full navigation mode)
+kctl-tui --help             # show all commands and flags
+kctl-tui --version          # print version
+kctl-tui --verbose          # enable debug logging to stderr
+kctl-tui doctor             # check if all tools, config and connections are OK
+kctl-tui config check       # validate ~/.kctl-tui/config.yaml
+kctl-tui panel --context=... --ns=... --team=...   # internal (called by tmux)
+```
+
 ## Development
 
 ```bash
@@ -194,4 +227,4 @@ and untested, since it has no meaningful behavior without a live cluster.
 
 ## License
 
-[MIT](LICENSE)
+Licensed under the [MIT License](LICENSE) - Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)

SPEC.md

@@ -75,9 +75,9 @@ Once start navigation is complete, the tool opens a tmux session with
 |  -> runs the kctl-tui binary in "panel" mode      |
 |  -> menu: Redeploy, secrets diff                  |
 +--------------------------------------------------+
-|  Pane 1 (middle): k9s --context <context-a> -n <ns>|
+|  Pane 1 (middle): k9s --context <context-a> --namespace <ns> --command pods|
 +--------------------------------------------------+
-|  Pane 2 (bottom): k9s --context <context-b> -n <ns>|
+|  Pane 2 (bottom): k9s --context <context-b> --namespace <ns> --command pods|
 +--------------------------------------------------+
 ```
 
@@ -89,11 +89,13 @@ not cover: **redeploy** and **secrets diff**.
 Example startup command (generic placeholders):
 
 ```
+# Kill stale session first (separate command — tmux aborts on kill-session error).
+tmux kill-session -t kctl
 tmux new-session -d -s kctl \
   "kctl-tui panel --context=$CTX_A --ns=$NS --team=$TEAM" \; \
   set-option -t kctl remain-on-exit on \; \
-  split-window -v -t kctl:0.0 "k9s --context $CTX_A -n $NS" \; \
-  split-window -v -t kctl:0.1 "k9s --context $CTX_B -n $NS" \; \
+  split-window -v -t kctl:0.0 "k9s --context $CTX_A --namespace $NS --command pods" \; \
+  split-window -v -t kctl:0.1 "k9s --context $CTX_B --namespace $NS --command pods" \; \
   select-layout -t kctl even-vertical \; \
   select-pane -t kctl:0.0 \; \
   attach -t kctl
@@ -167,18 +169,15 @@ The `context_template` replaces `{region}`, `{account_id}`, `{env}`, and
 selected environment/context. The resolved value must match an existing
 context in your kubeconfig (e.g. added via `aws eks update-kubeconfig`).
 
-**Platform limitation on Windows without WSL:** `kill-session` is
-tmux-specific. Windows Terminal (`wt.exe`) offers no equivalent scripting
-to end the session from inside a pane. On plain Windows (without WSL),
-only a simplified flow is possible: k9s panes are closed manually (`q`,
-then `Ctrl+Shift+W`); automatic session termination is unavailable there.
-This limitation is the main reason the primary target system is set to
-Linux/WSL.
+**Windows support:** On native Windows, install
+[psmux](https://github.com/marlocarlo/psmux) — a native, tmux-compatible
+terminal multiplexer. psmux provides a `tmux` command, so kctl-tui works
+without code changes (including `Esc`-triggered session termination).
+Alternatively, run kctl-tui inside WSL with standard `tmux`.
 
 ## 4. Non-functional requirements
 
-- **Primary platform Linux/WSL**, secondary native Windows with reduced
-  functionality.
+- **Primary platform Linux/WSL**, secondary native Windows (via psmux).
 - **Single-binary distribution** without external runtime dependency (Go
   provides this natively).
 - **External dependencies**: `kubectl` mandatory; `tmux`, `k9s`, `aws-cli`

cmd/kctl-tui/full.go

@@ -1,7 +1,11 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package main
 
 import (
 	"fmt"
+	"os"
 	"os/exec"
 	"sort"
 
@@ -46,6 +50,7 @@ func newFullModel() *fullModel {
 	l := list.New(nil, list.NewDefaultDelegate(), 0, 0)
 	l.Title = "kctl-tui"
 	l.SetShowStatusBar(false)
+	l.SetFilteringEnabled(false)
 	return &fullModel{list: l}
 }
 
@@ -192,6 +197,14 @@ func (m *fullModel) handleSelect() (tea.Model, tea.Cmd) {
 
 	case screenNamespace:
 		m.selectedNamespace = item.value
+		if err := kubeexec.CheckTool("tmux"); err != nil {
+			m.err = err
+			return m, nil
+		}
+		if err := kubeexec.CheckTool("k9s"); err != nil {
+			m.err = err
+			return m, nil
+		}
 		return m, m.startTmuxSession()
 	}
 	return m, nil
@@ -257,48 +270,52 @@ func (m *fullModel) loadNamespacesFor(teamValue string) tea.Cmd {
 // configured envs, resolved via the context template, so both are
 // visible side by side.
 func (m *fullModel) startTmuxSession() tea.Cmd {
-	return func() tea.Msg {
-		if err := kubeexec.CheckTool("tmux"); err != nil {
-			return errMsg{err}
-		}
-		if err := kubeexec.CheckTool("k9s"); err != nil {
-			return errMsg{err}
-		}
-		return m.buildAndRunTmux()
+	selfPath, err := os.Executable()
+	if err != nil {
+		selfPath = "kctl-tui" // fallback to PATH lookup
 	}
-}
-
-func (m *fullModel) buildAndRunTmux() tea.Msg {
-	selfPath := "kctl-tui" // resolved via PATH; see README for install instructions
 	panelCmd := fmt.Sprintf("%s panel --context=%s --ns=%s --team=%s",
 		selfPath, m.selectedContext, m.selectedNamespace, m.selectedTeam)
 
 	envA := m.cfg.Envs[0]
 	ctxA := m.cfg.ResolveContext(envA, m.selectedContext)
-	k9sCmdA := fmt.Sprintf("k9s --context %s -n %s", ctxA, m.selectedNamespace)
+	k9sCmdA := fmt.Sprintf("k9s --context %s --namespace %s --command pods", ctxA, m.selectedNamespace)
 
-	args := []string{
-		"new-session", "-d", "-s", "kctl",
-		panelCmd, ";",
-		"set-option", "-t", "kctl", "remain-on-exit", "on", ";",
-		"split-window", "-v", "-t", "kctl:0.0", k9sCmdA, ";",
+	kubeexec.VerboseLog("[debug] selfPath=%s\n", selfPath)
+	kubeexec.VerboseLog("[debug] panelCmd=%s\n", panelCmd)
+	kubeexec.VerboseLog("[debug] k9sCmdA=%s\n", k9sCmdA)
+
+	// Kill stale session first (ignore error if none exists).
+	exec.Command("tmux", "kill-session", "-t", "kctl").Run()
+
+	// Run setup commands individually — this avoids the ; separator
+	// issue on Windows where psmux doesn't handle chained args.
+	setup := [][]string{
+		{"new-session", "-d", "-s", "kctl", panelCmd},
+		{"set-option", "-t", "kctl", "remain-on-exit", "on"},
+		{"split-window", "-v", "-t", "kctl:0.0", k9sCmdA},
 	}
 	if len(m.cfg.Envs) > 1 {
 		envB := m.cfg.Envs[1]
 		ctxB := m.cfg.ResolveContext(envB, m.selectedContext)
-		k9sCmdB := fmt.Sprintf("k9s --context %s -n %s", ctxB, m.selectedNamespace)
-		args = append(args,
-			"split-window", "-v", "-t", "kctl:0.1", k9sCmdB, ";",
-		)
+		k9sCmdB := fmt.Sprintf("k9s --context %s --namespace %s --command pods", ctxB, m.selectedNamespace)
+		kubeexec.VerboseLog("[debug] k9sCmdB=%s\n", k9sCmdB)
+		setup = append(setup, []string{"split-window", "-v", "-t", "kctl:0.1", k9sCmdB})
 	}
-	args = append(args,
-		"select-layout", "-t", "kctl", "even-vertical", ";",
-		"select-pane", "-t", "kctl:0.0", ";",
-		"attach", "-t", "kctl",
+	setup = append(setup,
+		[]string{"select-layout", "-t", "kctl", "even-vertical"},
+		[]string{"select-pane", "-t", "kctl:0.0"},
 	)
 
-	c := exec.Command("tmux", args...)
+	for _, args := range setup {
+		if out, err := exec.Command("tmux", args...).CombinedOutput(); err != nil {
+			kubeexec.VerboseLog("[debug] tmux %s failed: %v\n%s\n", args[0], err, out)
+			return func() tea.Msg { return tmuxDoneMsg{err: fmt.Errorf("tmux %s: %w", args[0], err)} }
+		}
+	}
 
+	// Only attach uses tea.ExecProcess so it takes over the terminal.
+	c := exec.Command("tmux", "attach", "-t", "kctl")
 	return tea.ExecProcess(c, func(err error) tea.Msg {
 		return tmuxDoneMsg{err: err}
 	})

cmd/kctl-tui/helpers.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package main
 
 import "github.com/skoelle/kctl-tui/internal/kctl"

cmd/kctl-tui/list_item.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package main
 
 // simpleItem is a minimal implementation of list.Item used for all

cmd/kctl-tui/main.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package main
 
 import (
@@ -6,19 +9,30 @@ import (
 
 	tea "github.com/charmbracelet/bubbletea"
 
+	"github.com/skoelle/kctl-tui/internal/config"
 	"github.com/skoelle/kctl-tui/internal/kubeexec"
 )
 
+// version is set via -ldflags at build time.
+var version = "dev"
+
 func main() {
 	args := os.Args[1:]
 
-	// Extract --verbose before delegating to panel or full mode.
+	// Extract global flags before delegating to sub-commands.
 	verbose := false
+	showHelp := false
 	filtered := make([]string, 0, len(args))
 	for _, a := range args {
-		if a == "--verbose" {
+		switch a {
+		case "--verbose":
 			verbose = true
-		} else {
+		case "--version", "-v":
+			fmt.Printf("kctl-tui %s\n", version)
+			return
+		case "--help", "-h":
+			showHelp = true
+		default:
 			filtered = append(filtered, a)
 		}
 	}
@@ -26,12 +40,39 @@ func main() {
 		kubeexec.SetVerbose(true, os.Stderr)
 	}
 
-	if len(filtered) > 0 && filtered[0] == "panel" {
-		if err := runPanel(filtered[1:]); err != nil {
-			fmt.Fprintln(os.Stderr, "kctl-tui panel error:", err)
+	if showHelp {
+		printUsage()
+		return
+	}
+	if len(filtered) == 0 {
+		// No subcommand — start the full TUI.
+	}
+
+	if len(filtered) > 0 {
+		switch filtered[0] {
+		case "panel":
+			if err := runPanel(filtered[1:]); err != nil {
+				fmt.Fprintln(os.Stderr, "kctl-tui panel error:", err)
+				os.Exit(1)
+			}
+			return
+		case "config":
+			if err := runConfig(filtered[1:]); err != nil {
+				fmt.Fprintln(os.Stderr, "kctl-tui config error:", err)
+				os.Exit(1)
+			}
+			return
+		case "doctor":
+			if err := runDoctor(); err != nil {
+				fmt.Fprintln(os.Stderr, "kctl-tui doctor error:", err)
+				os.Exit(1)
+			}
+			return
+		default:
+			fmt.Fprintf(os.Stderr, "unknown command: %s\n\n", filtered[0])
+			printUsage()
 			os.Exit(1)
 		}
-		return
 	}
 
 	m := newFullModel()
@@ -41,3 +82,186 @@ func main() {
 		os.Exit(1)
 	}
 }
+
+func printUsage() {
+	fmt.Print(`kctl-tui — Kubernetes entry-point TUI
+
+Usage:
+  kctl-tui [flags]             start the TUI (full navigation mode)
+  kctl-tui doctor              check tools, config and connections
+  kctl-tui config check        validate ~/.kctl-tui/config.yaml
+  kctl-tui panel [options]     control pane (called internally by tmux)
+
+Flags:
+  --verbose    log all kubectl/aws commands to stderr
+  --version    print version
+  --help       show this help
+
+Examples:
+  kctl-tui                          # start the TUI
+  kctl-tui doctor                   # verify everything is installed
+  kctl-tui --verbose 2>debug.log    # log commands to a file
+  kctl-tui config check             # validate config
+`)
+}
+
+func runConfig(args []string) error {
+	if len(args) == 0 || args[0] != "check" {
+		return fmt.Errorf("usage: kctl-tui config check")
+	}
+	cfgPath, err := config.DefaultPath()
+	if err != nil {
+		return fmt.Errorf("cannot determine config path: %w", err)
+	}
+	cfg, err := config.Load(cfgPath)
+	if err != nil {
+		return fmt.Errorf("failed to load %s: %w", cfgPath, err)
+	}
+
+	ok := true
+	if len(cfg.Contexts) == 0 {
+		fmt.Fprintln(os.Stderr, "ERROR: no 'contexts' configured")
+		ok = false
+	}
+	if len(cfg.Envs) == 0 {
+		fmt.Fprintln(os.Stderr, "ERROR: no 'envs' configured")
+		ok = false
+	}
+	if cfg.ContextTemplate == "" {
+		fmt.Fprintln(os.Stderr, "ERROR: 'context_template' is empty")
+		ok = false
+	}
+	if cfg.SecretNameTemplate == "" {
+		fmt.Fprintln(os.Stderr, "ERROR: 'secret_name_template' is empty")
+		ok = false
+	}
+	if cfg.TeamLabelKey == "" {
+		fmt.Fprintln(os.Stderr, "WARNING: 'team_label_key' is empty — team selection will have no groups")
+	}
+	if cfg.AWSRegion == "" {
+		fmt.Fprintln(os.Stderr, "WARNING: 'aws_region' is empty — secrets workflow will fail")
+	}
+
+	// Try resolving one context to verify the template works.
+	if len(cfg.Contexts) > 0 && len(cfg.Envs) > 0 && cfg.ContextTemplate != "" {
+		ctx := cfg.ResolveContext(cfg.Envs[0], cfg.Contexts[0])
+		fmt.Printf("Resolved context example: %s\n", ctx)
+	}
+
+	if ok {
+		fmt.Println("Config OK")
+	} else {
+		fmt.Fprintln(os.Stderr, "Config has errors — see above")
+		os.Exit(1)
+	}
+	return nil
+}
+
+func runDoctor() error {
+	pass := "ok"
+	fail := "FAIL"
+	warn := "WARN"
+	status := pass
+	errs := 0
+
+	check := func(label string, err error) {
+		if err != nil {
+			fmt.Printf("  [%s] %s: %v\n", fail, label, err)
+			status = fail
+			errs++
+		} else {
+			fmt.Printf("  [%s] %s\n", pass, label)
+		}
+	}
+
+	warnCheck := func(label string, err error) {
+		if err != nil {
+			fmt.Printf("  [%s] %s: %v\n", warn, label, err)
+		} else {
+			fmt.Printf("  [%s] %s\n", pass, label)
+		}
+	}
+
+	// --- Tools ---
+	fmt.Println("\nTools:")
+	check("kubectl", kubeexec.CheckTool("kubectl"))
+	check("tmux/psmux", kubeexec.CheckTool("tmux"))
+	check("k9s", kubeexec.CheckTool("k9s"))
+	warnCheck("aws CLI (optional)", kubeexec.CheckTool("aws"))
+
+	// --- Config ---
+	fmt.Println("\nConfig:")
+	cfgPath, err := config.DefaultPath()
+	if err != nil {
+		fmt.Printf("  [%s] config path: %v\n", fail, err)
+		errs++
+		status = fail
+	} else {
+		cfg, err := config.Load(cfgPath)
+		if err != nil {
+			fmt.Printf("  [%s] load config: %v\n", fail, err)
+			errs++
+			status = fail
+		} else {
+			check("config file exists", nil)
+			if len(cfg.Contexts) == 0 {
+				fmt.Printf("  [%s] contexts configured\n", fail)
+				errs++
+				status = fail
+			} else {
+				fmt.Printf("  [%s] contexts configured (%d)\n", pass, len(cfg.Contexts))
+			}
+			if len(cfg.Envs) == 0 {
+				fmt.Printf("  [%s] envs configured\n", fail)
+				errs++
+				status = fail
+			} else {
+				fmt.Printf("  [%s] envs configured (%d)\n", pass, len(cfg.Envs))
+			}
+			if cfg.ContextTemplate != "" {
+				ctx := cfg.ResolveContext(cfg.Envs[0], cfg.Contexts[0])
+				fmt.Printf("  [%s] context_template resolves to: %s\n", pass, ctx)
+			} else {
+				fmt.Printf("  [%s] context_template is empty\n", fail)
+				errs++
+				status = fail
+			}
+			if cfg.SecretNameTemplate != "" && len(cfg.Envs) > 0 {
+				secret := cfg.ResolveSecretName("example-ns", cfg.Envs[0])
+				fmt.Printf("  [%s] secret_name_template resolves to: %s\n", pass, secret)
+			}
+		}
+	}
+
+	// --- Connections ---
+	fmt.Println("\nConnections:")
+	if kubeexec.CheckTool("kubectl") == nil {
+		err := kubeexec.CheckAWSAuth()
+		if err == nil {
+			fmt.Printf("  [%s] kubectl cluster reachable\n", pass)
+		} else {
+			// Not fatal — cluster might be unreachable from this machine
+			fmt.Printf("  [%s] kubectl cluster: %v\n", warn, err)
+		}
+	}
+	if kubeexec.CheckTool("aws") == nil {
+		err := kubeexec.CheckAWSAuth()
+		if err == nil {
+			fmt.Printf("  [%s] AWS credentials valid\n", pass)
+		} else {
+			fmt.Printf("  [%s] AWS credentials: %v\n", warn, err)
+		}
+	} else {
+		fmt.Printf("  [%s] AWS credentials (aws CLI not installed)\n", warn)
+	}
+
+	// --- Summary ---
+	fmt.Println()
+	if status == pass {
+		fmt.Println("All checks passed. kctl-tui is ready to use.")
+	} else {
+		fmt.Printf("%d error(s) found. Fix the issues above and re-run: kctl-tui doctor\n", errs)
+		os.Exit(1)
+	}
+	return nil
+}

cmd/kctl-tui/panel.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package main
 
 import (
@@ -81,6 +84,7 @@ func newPanelModel(context, ns, team string) *panelModel {
 
 	l := list.New(nil, list.NewDefaultDelegate(), 0, 0)
 	l.SetShowStatusBar(false)
+	l.SetFilteringEnabled(false)
 
 	m := &panelModel{context: context, ns: ns, team: team, cfg: cfg, step: stepEnvMenu, list: l, input: ti}
 	if loadErr != nil {

install.ps1

@@ -0,0 +1,74 @@
+# Install script for kctl-tui on Windows.
+# Downloads the latest GitHub release binary matching the current architecture
+# and installs it to your PATH.
+#
+# Usage (PowerShell):
+#   irm https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.ps1 | iex
+#
+# Or save and run locally:
+#   .\install.ps1
+#
+# Requires: PowerShell 5.1+, internet access.
+
+$ErrorActionPreference = "Stop"
+
+$Repo = "skoelle/kctl-tui"
+$BinName = "kctl-tui"
+
+# --- Detect architecture ---
+$arch = $env:PROCESSOR_ARCHITECTURE
+switch ($arch) {
+    "AMD64"   { $goarch = "amd64" }
+    "ARM64"   { $goarch = "arm64" }
+    default {
+        Write-Error "Unsupported architecture: $arch"
+        exit 1
+    }
+}
+
+# --- Determine install directory ---
+$installDir = "$env:USERPROFILE\bin"
+if (-not (Test-Path $installDir)) {
+    New-Item -ItemType Directory -Path $installDir | Out-Null
+}
+
+# Add to PATH if not already there
+$currentPath = [Environment]::GetEnvironmentVariable("Path", "User")
+if ($currentPath -notlike "*$installDir*") {
+    [Environment]::SetEnvironmentVariable("Path", "$currentPath;$installDir", "User")
+    $env:Path = "$env:Path;$installDir"
+    Write-Host "Added $installDir to your PATH."
+}
+
+# --- Query GitHub API for latest release ---
+Write-Host "Detecting latest release for $Repo ..."
+try {
+    $release = Invoke-RestMethod -Uri "https://api.github.com/repos/$Repo/releases/latest" -UseBasicParsing
+} catch {
+    Write-Error "Failed to reach the GitHub API (network error). Check your internet connection and try again."
+    exit 1
+}
+
+$tag = $release.tag_name
+if (-not $tag) {
+    Write-Error "Could not find a published release for $Repo. No release has been tagged yet."
+    exit 1
+}
+
+Write-Host "Latest release: $tag"
+
+# --- Download binary ---
+$asset = "kctl-tui-windows-${goarch}.exe"
+$url = "https://github.com/$Repo/releases/download/$tag/$asset"
+$outFile = "$installDir\$BinName.exe"
+
+Write-Host "Downloading $asset ($tag) ..."
+try {
+    Invoke-WebRequest -Uri $url -OutFile $outFile -UseBasicParsing
+} catch {
+    Write-Error "Download failed: $_"
+    exit 1
+}
+
+Write-Host "Installed $BinName to $outFile"
+Write-Host "Done. Run '$BinName' to get started."

install.sh

@@ -1,4 +1,6 @@
 #!/usr/bin/env bash
+# Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+# Licensed under the MIT License. See LICENSE file in project root for details.
 # Install script for kctl-tui.
 # Downloads the latest GitHub release binary matching the current OS/arch
 # and installs it to /usr/local/bin (or $INSTALL_DIR if set).

internal/config/config.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 // Package config loads the user-specific, non-versioned kctl-tui
 // configuration (contexts, envs, templates) from a YAML file.
 package config

internal/config/config_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package config
 
 import (

internal/kctl/diff.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package kctl
 
 import "sort"

internal/kctl/diff_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package kctl
 
 import "testing"

internal/kctl/labels.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package kctl
 
 import "sort"

internal/kctl/labels_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package kctl
 
 import (

internal/kctl/template.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package kctl
 
 import "strings"

internal/kctl/template_test.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package kctl
 
 import "testing"

internal/kubeexec/kubeexec.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 // Package kubeexec wraps kubectl/aws-cli invocations used by kctl-tui.
 // All functions here have side effects (they run external processes) and
 // are therefore not covered by unit tests; the pure logic they depend on
@@ -182,8 +185,11 @@ func RunAWSLogin(loginCommand string) *exec.Cmd {
 // Returns nil if found, or a descriptive error if not.
 func CheckTool(name string) error {
 	_, err := exec.LookPath(name)
-	if err != nil {
-		return fmt.Errorf("%q not found in PATH — please install it first", name)
+	if err == nil {
+		return nil
 	}
-	return nil
+	if name == "tmux" {
+		return fmt.Errorf("%q not found in PATH — install tmux (Linux/macOS) or psmux (Windows: scoop install psmux or cargo install psmux)", name)
+	}
+	return fmt.Errorf("%q not found in PATH — please install it first", name)
 }

internal/kubeexec/log.go

@@ -1,3 +1,6 @@
+// Copyright (c) 2026 Stefan Koelle (https://stefankoelle.de)
+// Licensed under the MIT License. See LICENSE file in project root for details.
+
 package kubeexec
 
 import (
@@ -26,6 +29,16 @@ func SetVerbose(enabled bool, w io.Writer) {
 	}
 }
 
+// VerboseLog writes a message to the verbose log if enabled.
+func VerboseLog(format string, args ...interface{}) {
+	mu.Lock()
+	defer mu.Unlock()
+	if !verbose {
+		return
+	}
+	fmt.Fprintf(logOut, format, args...)
+}
+
 func logCmd(name string, args ...string) {
 	mu.Lock()
 	defer mu.Unlock()