Fix SPEC.md and README.md for current codebase

- SPEC.md: Windows is now a fully supported platform (not secondary)
- SPEC.md: Remove outdated 'manual pane handling' claim for Windows
- SPEC.md: Update non-functional requirements (Linux/macOS/Windows)
- README.md: Remove duplicate 'This downloads...' paragraph
- README.md: Use --namespace instead of -n in k9s examples

.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)

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.

PLAN.md

@@ -14,7 +14,7 @@ is still open. For the full requirements, see [SPEC.md](SPEC.md).
       API is unreachable.
 - [x] `README.md`, `config.example.yaml`.
 
-## Phase 1 — Core logic + navigation (done, initial version)
+## Phase 1 — Core logic + navigation (done)
 
 - [x] `internal/kctl`: pure, unit-tested logic —
       template resolution (`ResolveTemplate`), namespace/label filtering
@@ -49,41 +49,101 @@ is still open. For the full requirements, see [SPEC.md](SPEC.md).
         **whole secret** (one ExternalSecret annotation).
       - `Esc` closes the whole tmux session (`tmux kill-session`).
 
-## Phase 2 — Hardening (open)
+## Phase 2 — Hardening (done)
 
-- [ ] Handle non-JSON AWS secrets and Kubernetes secrets with binary
-      (non-UTF8) values more gracefully in the diff table (currently
-      falls back to a single "value" key or may render oddly).
+- [x] Handle non-JSON AWS secrets and Kubernetes secrets with binary
+      (non-UTF8) values more gracefully in the diff table.
 - [ ] Add integration-style tests against a local `kind`/`k3d` cluster in
       CI for the `kubeexec` wrappers currently excluded from automated
-      testing.
-- [ ] Input validation for the free-text steps in "panel" mode (empty
-      region/secret name, invalid characters).
-- [ ] Graceful handling when `tmux`, `k9s`, or `aws` are not installed
-      (currently surfaces the raw exec error).
-- [ ] Structured logging / `--verbose` flag for troubleshooting failed
+      testing. *(Deferred — superseded by client-go in v0.3.0)*
+- [x] Input validation for the free-text steps in "panel" mode.
+- [x] Graceful handling when `tmux`, `k9s`, or `aws` are not installed.
+- [x] Structured logging / `--verbose` flag for troubleshooting failed
       `kubectl`/`aws` calls.
-- [ ] Paginate/scroll the secrets diff table for secrets with many fields
-      instead of relying on terminal wrapping.
+- [x] Paginate/scroll the secrets diff table for secrets with many fields.
 
 ## Phase 3 — Windows-native support (done)
 
-- [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] Windows support via [psmux](https://github.com/marlocarlo/psmux).
 - [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)
+## Phase 4 — Nice-to-haves (done for v0.2.0)
 
 - [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.
-- [ ] Homebrew tap / `scoop` manifest as additional install options
-      alongside `install.sh`.
+- [x] `kctl-tui doctor` — health check for tools, config, and connectivity.
+- [x] `--help` flag with full usage documentation.
+- [x] CHANGELOG.md, CONTRIBUTING.md, GitHub Issue/PR templates.
+
+---
+
+## Bugfix Sprint — between v0.2.0 and v0.3.0
+
+- [ ] **Dead code** `cmd/kctl-tui/main.go:47-49` — empty
+      `if len(filtered) == 0` block with comment. Remove.
+- [ ] **Redundant logic** `internal/kctl/diff.go:60-63` —
+      `if lb || rb { match = l == r }` is identical to the line above.
+      Either dead or misunderstood.
+- [ ] **Diff-scroll is a no-op** `cmd/kctl-tui/panel.go:398-413` —
+      `renderDiffTable` is always called with `visibleHeight=0`, so
+      `end = len(entries)` is always true. j/k/arrows only change the
+      offset text but the table is always fully rendered. The CHANGELOG
+      promises "Diff table scroll support" but the feature is incomplete.
+- [ ] **README duplicate** `README.md:98-102` — "This downloads the latest
+      release binary..." appears twice (once "to your PATH", once
+      "to /usr/local/bin"). Edit leftover.
+- [ ] **go mod tidy in CI** `build.yml` — mutates `go.sum` during the
+      build instead of enforcing a tidy check. If someone forgets to tidy,
+      it's silently fixed instead of blocking the PR.
+- [ ] **Bubbles filter disabled** `full.go:53`, `panel.go:87` — workaround
+      for the stuck-filter bug (commit 7db58b6). Users can no longer
+      type-to-filter. Worth restoring with a proper fix later.
+- [ ] **Kleinkram:**
+  - `fmt.Errorf("%s", msg)` → `errors.New(msg)` in `kubeexec.go:41`
+  - `helpers.go` is a pointless 1:1 passthrough to the `kctl` package
+  - `IsBinary` also marks UTF-8 special chars (>0x7F) as "binary"
+
+- [ ] **SECURITY.md** — fehlt, besonders wichtig für ein Tool mit
+      Secret-Workflows.
+- [ ] **dependabot.yml** — automatische Dependency-Updates.
+- [ ] **Checksummen für Release-Assets** — CI erzeugt Binaries aber keine
+      `.sha256`-Dateien; für `curl | bash`-Install wichtig.
+- [ ] **Makefile / justfile** — Build/Test/Vet-Komfort.
+- [ ] **golangci-lint** — `go vet` allein ist dünn; optional aber empfohlen.
+- [ ] **PLAN.md aufräumen** — erledigte Phasen als „Done" markieren,
+      offene Items konsolidieren.
+
+---
+
+## Roadmap
+
+### v0.3.0 — client-go integration
+
+Replace kubectl shell-outs with direct API calls via `client-go`.
+
+- [ ] Add `internal/kubeclient` package using `client-go` for:
+      - Context/namespace/label queries (faster than kubectl JSON parsing)
+      - Deployment list and rollout restart/status
+      - Secret fetch (AWS Secrets Manager via SDK, K8s secrets via API)
+      - ExternalSecret annotation update
+- [ ] Keep `internal/kubeexec` as fallback for operations not yet
+      covered by `client-go`
+- [ ] Remove `kind`/`k3d` integration test plan (client-go has its own
+      test coverage)
+- [ ] Add unit tests with `fake.Clientset` for the new package
+
+### v1.0 — Stable release
+
+Production-ready with package manager support and documentation.
+
+- [ ] Homebrew tap (`skoelle/homebrew-tap`) with `kctl-tui` formula
+- [ ] Scoop manifest (`skoelle/scoop-bucket`) for Windows
+- [ ] Full test coverage for `internal/kubeclient`
+- [ ] Documentation: architecture diagram, config reference, troubleshooting
+- [ ] Semantic versioning policy documented
+- [ ] Deprecation policy for config schema changes
 
 ## Notes for contributors
 

README.md

@@ -42,9 +42,9 @@ See [SPEC.md](SPEC.md) for the full requirements and design rationale, and
 |  -> 1) Quit  2) beta  3) prod                     |
 |     each with: a) Secrets sync  b) Redeploy       |
 +--------------------------------------------------+
-|  k9s --context <resolved beta context>  -n <ns>   |
+|  k9s --context <resolved beta context> --namespace <ns> --command pods   |
 +--------------------------------------------------+
-|  k9s --context <resolved prod context>  -n <ns>   |
+|  k9s --context <resolved prod context> --namespace <ns> --command pods   |
 +--------------------------------------------------+
 ```
 
@@ -95,9 +95,6 @@ curl -fsSL https://raw.githubusercontent.com/skoelle/kctl-tui/main/install.sh |
 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`.
 

SPEC.md

@@ -7,9 +7,10 @@ work, bundling the most common workflows currently done via long
 `kubectl`/`k9s`/`aws-cli` commands, operable through a text UI (arrow keys,
 Esc) instead of long typed commands.
 
-Target platform: **Linux / WSL** (primary usage scenario, since split
-panes require a real terminal multiplexer). Native Windows (without WSL)
-is possible but with reduced split-view functionality (see 3.6).
+Target platform: **Linux / WSL / Windows** (primary usage scenario, since
+split panes require a real terminal multiplexer). On Windows, use
+[psmux](https://github.com/marlocarlo/psmux) as tmux-compatible
+multiplexer.
 
 **Technology decision: Go + Bubble Tea** (see section 5).
 
@@ -75,9 +76,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|
 +--------------------------------------------------+
 ```
 
@@ -94,8 +95,8 @@ 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
@@ -177,11 +178,11 @@ Alternatively, run kctl-tui inside WSL with standard `tmux`.
 
 ## 4. Non-functional requirements
 
-- **Primary platform Linux/WSL**, secondary native Windows (via psmux).
+- **Platforms**: Linux, macOS, Windows (via psmux or WSL).
 - **Single-binary distribution** without external runtime dependency (Go
   provides this natively).
-- **External dependencies**: `kubectl` mandatory; `tmux`, `k9s`, `aws-cli`
-  depending on the action used.
+- **External dependencies**: `kubectl` mandatory; `tmux`/`psmux`, `k9s`,
+  `aws-cli` depending on the action used.
 - **Low startup time**, noticeably faster than the current `kubens`
   experience.
 - **No destructive actions without confirmation** (redeploy, force-sync).
@@ -243,16 +244,14 @@ Rejected options (see discussion history):
 - These fixes are a prerequisite before the tool can be meaningfully
   tested, since it builds directly on `kubectl config`.
 
-## 8. Open items / out of scope (v1)
+## 8. Open items / out of scope
 
 - No automatic label setup for namespaces (migration is a separate,
   one-time task).
-- Split view v1 fixed at 2 status panes + 1 control pane (3 panes total).
+- Split view fixed at 2 status panes + 1 control pane (3 panes total).
 - No RBAC/permission checks before executing sensitive actions — the tool
   assumes existing kubectl permissions.
 - Configuration file format (`config.yaml`) is defined and implemented;
   concrete label keys, context names, and namespace names are
   project-specific and belong exclusively in the user's local, unversioned
   configuration, not in this document or the source code.
-- Native Windows (without WSL) remains a secondary platform with manual
-  pane handling instead of an automated tmux lifecycle.

cmd/kctl-tui/full.go

@@ -50,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}
 }
 
@@ -278,10 +279,11 @@ func (m *fullModel) startTmuxSession() tea.Cmd {
 
 	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)
 
-	fmt.Fprintf(os.Stderr, "[debug] selfPath=%s\n", selfPath)
-	fmt.Fprintf(os.Stderr, "[debug] panelCmd=%s\n", panelCmd)
+	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()
@@ -296,7 +298,8 @@ func (m *fullModel) startTmuxSession() tea.Cmd {
 	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)
+		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})
 	}
 	setup = append(setup,
@@ -306,13 +309,12 @@ func (m *fullModel) startTmuxSession() tea.Cmd {
 
 	for _, args := range setup {
 		if out, err := exec.Command("tmux", args...).CombinedOutput(); err != nil {
-			fmt.Fprintf(os.Stderr, "[debug] tmux %s failed: %v\n%s\n", args[0], err, out)
+			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.
-	fmt.Fprintf(os.Stderr, "[debug] tmux attach -t kctl\n")
 	c := exec.Command("tmux", "attach", "-t", "kctl")
 	return tea.ExecProcess(c, func(err error) tea.Msg {
 		return tmuxDoneMsg{err: err}

cmd/kctl-tui/panel.go

@@ -84,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 {

internal/kubeexec/log.go

@@ -29,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()