Work on Luxury Yacht kubeconfig selection, multi-cluster client lifecycle, auth failure/recovery, selected/background clusters, cluster tabs, refresh subsystem rebuilds, and object catalog lifecycle
Cluster Auth Lifecycle
Use this when touching kubeconfig selection, cluster client setup, auth failure
overlays, retry/recovery, selected/background cluster state, cluster tabs,
refresh subsystem rebuilds, object catalog start/stop, or tests for cluster
add/remove behavior.
Read First
AGENTS.md
backend/AGENTS.md for backend lifecycle/client changes
frontend/AGENTS.md for frontend cluster state or UI changes
docs/architecture/multi-cluster.md
docs/architecture/data-freshness.md
docs/architecture/auth.md
docs/architecture/refresh-system.md
docs/architecture/catalog.md when object catalog lifecycle is involved
Backend Entry Points
backend/cluster_runtime_manager.go
backend/cluster_workspace_projection.go
backend/refresh_coordinator.go
backend/workspace_coordinator.go
backend/cluster_runtime_intent.go
backend/cluster_runtime_clients.go
backend/cluster_runtime_auth.go
backend/workspace_auth.go
backend/workspace_cluster_clients.go
backend/workspace_kubeconfigs.go
backend/workspace_state.go
backend/refresh_setup.go
backend/refresh_update.go
backend/refresh_subsystems.go
backend/refresh_recovery.go
backend/refresh_object_catalog.go
backend/internal/authstate
Frontend Entry Points
frontend/src/modules/kubernetes/config
frontend/src/modules/cluster
frontend/src/ui/layout/ClusterTabs.tsx
frontend/src/ui/overlays/AuthFailureOverlay.tsx
frontend/src/core/refresh
frontend/src/core/data-access
Checklist
Every cluster-data path carries clusterId; never infer the active
cluster in a backend/API/cache/action path.
Selected and background cluster sets stay distinct and refresh scopes are
rebuilt or cleared when cluster selection changes.
Refresh domains stay single-cluster. Cross-cluster displays fan out only
for clusters they display; retained inactive tabs stay passive.
Cluster add/remove updates aggregate refresh handlers and object catalog
services through the live update path, not only initial setup.
Watcher, auth, and transport callbacks publish non-blocking typed
ClusterRuntimeIntent values; Workspace is the single consumer and routes
accepted generations through the serialized selection mutation.
Auth-failed clusters do not block healthy clusters.
Retry/recovery rebuilds transport, refresh, object catalog, and frontend
diagnostics consistently.
Closing/removing a cluster cleans up streams, sessions, stale scopes, and
catalog state for that cluster.
Every frontend cluster-tab open/close affordance routes through
KubeconfigContext's unified selection transition (openKubeconfig,
closeKubeconfig, or setSelectedKubeconfigs); do not splice selected
clusters locally or call generated backend selection/close commands from
UI surfaces.
Tests cover at least one multi-cluster or auth-failure transition.
Validation
Use focused checks while iterating:
mise exec -- go test ./backend ./backend/internal/authstate
mise exec -- npm run typecheck --prefix frontend
mise exec -- npm run test --prefix frontend -- cluster kubeconfig auth refresh
