docs: add project specification and implementation plan for kubectl-gui

Co-authored-by: aider (openrouter/nvidia/nemotron-3-ultra-550b-a55b:free) <aider@aider.chat>

README.md

@@ -1,3 +1,85 @@
 # kubectl-gui
 
-Web gui for kubectl.
+## Project Overview
+A local web-based GUI for kubectl that runs on your machine and provides a user-friendly interface to manage Kubernetes clusters. Built with Go backend and React frontend.
+
+## Key Features
+
+### Cluster & Context Management
+- **Context Selector**: Switch between Kubernetes contexts from kubeconfig
+- **Namespace Selector**: Filter resources by namespace with "All Namespaces" option
+- **Cluster Info**: Display current cluster version and status
+
+### Resource Browser
+- **Multi-Resource Support**: Pods, Nodes, PVCs, Services, Deployments, ConfigMaps, Secrets, and more
+- **Search & Filter**: Real-time search by name, labels, status
+- **Sortable Tables**: Sort by name, namespace, status, age, etc.
+- **Custom Columns**: Show/hide columns like labels, resource requests/limits
+
+### Resource Actions
+| Resource | Actions |
+|----------|---------|
+| **Pods** | Logs (tail/follow), Exec, Describe, Delete, Port-forward, View YAML |
+| **Nodes** | Describe, Cordon/Uncordon, Drain, View YAML, Taints |
+| **PVCs** | Describe, Delete, View YAML, View bound PV |
+| **Deployments** | Scale, Rollout restart/undo, Describe, Delete, View YAML |
+| **Services** | Describe, Delete, View endpoints, View YAML |
+| **ConfigMaps/Secrets** | View data, Edit, Describe, Delete, View YAML |
+
+### Real-time Updates
+- WebSocket-based live updates for resource changes
+- Configurable auto-refresh interval
+- Visual indicators for state changes
+
+## Technical Architecture
+
+### Backend (Go)
+- **Language**: Go 1.21+
+- **Router**: Chi
+- **Kubernetes Client**: client-go with dynamic client
+- **WebSocket**: Gorilla WebSocket
+- **Auth**: Uses local kubeconfig (no separate auth)
+- **Port**: localhost:8080 (configurable)
+
+### Frontend (React + TypeScript)
+- **Framework**: React 18 with TypeScript
+- **State**: TanStack Query for server state
+- **UI**: Headless UI + Tailwind CSS
+- **Real-time**: WebSocket with reconnection
+- **Build**: Vite
+
+## Implementation Plan
+
+### Phase 1: Core Infrastructure
+- [ ] Go backend with kubeconfig loading
+- [ ] Context/namespace switching API
+- [ ] Basic React frontend with routing
+- [ ] WebSocket connection for resource watches
+- [ ] Shared TypeScript/Go types for resources
+
+### Phase 2: Resource Browser
+- [ ] Generic resource list component
+- [ ] Resource-specific columns and actions
+- [ ] Search/filter/sort implementation
+- [ ] YAML/JSON modal viewer
+- [ ] Describe output formatter
+
+### Phase 3: Pod Operations
+- [ ] Log streaming with follow/tail
+- [ ] Exec terminal (xterm.js integration)
+- [ ] Port-forward management UI
+- [ ] Pod detail view with containers/events
+
+### Phase 4: Advanced Resources
+- [ ] Node management (cordon/drain/taints)
+- [ ] PVC/PV binding visualization
+- [ ] Deployment rollout controls
+- [ ] ConfigMap/Secret editors with validation
+
+### Phase 5: Polish & Extras
+- [ ] Theme system
+- [ ] Keyboard shortcuts
+- [ ] Command palette
+- [ ] Settings persistence (localStorage)
+- [ ] Error boundaries and loading states
+- [ ] Comprehensive test coverage