@skyhook-io/radar-app 1.15.0 → 1.16.1

package/src/components/NamespaceSwitcher.test.tsx

@@ -0,0 +1,47 @@
+import { renderToStaticMarkup } from 'react-dom/server'
+import type { ReactNode } from 'react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+const state = vi.hoisted(() => ({
+  mode: 'local' as string | undefined,
+  authEnabled: false as boolean | undefined,
+}))
+
+vi.mock('@skyhook-io/k8s-ui', () => ({
+  NamespacePicker: ({ limitedListHelp }: { limitedListHelp?: ReactNode }) => <div>{limitedListHelp ?? 'no-help'}</div>,
+}))
+vi.mock('../api/client', () => ({
+  useNamespaceScope: () => ({ data: undefined, isLoading: false }),
+  useSetActiveNamespace: () => ({ isPending: false, mutate: vi.fn() }),
+  useCapabilities: () => ({ data: state.mode === undefined ? undefined : { deployment: { mode: state.mode } } }),
+  useAuthMe: () => ({ data: state.authEnabled === undefined ? undefined : { authEnabled: state.authEnabled } }),
+}))
+
+import { NamespaceSwitcher } from './NamespaceSwitcher'
+
+describe('NamespaceSwitcher namespace help', () => {
+  beforeEach(() => {
+    state.mode = 'local'
+    state.authEnabled = false
+  })
+
+  it('links to the namespace docs in local Radar without auth', () => {
+    const html = renderToStaticMarkup(<NamespaceSwitcher />)
+    expect(html).toContain('How to add namespaces')
+    expect(html).toContain('#namespaces-missing-from-the-picker')
+  })
+
+  // --namespaces and config.json belong to whoever runs the server; on a shared
+  // install the viewer can't use them.
+  it.each([
+    ['in-cluster Radar', 'in-cluster', false],
+    ['Radar Cloud', 'cloud', true],
+    ['auth-enabled local Radar', 'local', true],
+    ['capabilities still loading', undefined, false],
+    ['auth state still loading', 'local', undefined],
+  ] as const)('offers no help for %s', (_label, mode, authEnabled) => {
+    state.mode = mode
+    state.authEnabled = authEnabled
+    expect(renderToStaticMarkup(<NamespaceSwitcher />)).toContain('no-help')
+  })
+})

package/src/components/NamespaceSwitcher.tsx

@@ -1,9 +1,11 @@
 import { forwardRef } from 'react'
 import { NamespacePicker, type NamespacePickerHandle } from '@skyhook-io/k8s-ui'
-import { useNamespaceScope, useSetActiveNamespace } from '../api/client'
+import { useAuthMe, useCapabilities, useNamespaceScope, useSetActiveNamespace } from '../api/client'
 
 export type NamespaceSwitcherHandle = NamespacePickerHandle
 
+const NAMESPACES_HELP_URL = 'https://radarhq.io/docs/configuration/files#namespaces-missing-from-the-picker'
+
 interface NamespaceSwitcherProps {
   className?: string
   disabled?: boolean
@@ -24,6 +26,19 @@ export const NamespaceSwitcher = forwardRef<NamespaceSwitcherHandle, NamespaceSw
   const { data: scope, isLoading } = useNamespaceScope()
   const setActive = useSetActiveNamespace()
 
+  const { data: capabilities } = useCapabilities()
+  const { data: authMe } = useAuthMe()
+  // --namespaces and ~/.radar/config.json only reach a Radar the user launched
+  // themselves. With auth enabled, a non-authoritative list is also the
+  // per-user RBAC filter on a shared install, where neither applies.
+  const canConfigureNamespaces = capabilities?.deployment?.mode === 'local' && authMe?.authEnabled === false
+
+  const limitedListHelp = canConfigureNamespaces ? (
+    <a href={NAMESPACES_HELP_URL} target="_blank" rel="noreferrer" className="text-accent-text hover:underline">
+      How to add namespaces
+    </a>
+  ) : undefined
+
   return (
     <NamespacePicker
       ref={ref}
@@ -36,6 +51,7 @@ export const NamespaceSwitcher = forwardRef<NamespaceSwitcherHandle, NamespaceSw
       className={className}
       variant={variant}
       label={label}
+      limitedListHelp={limitedListHelp}
     />
   )
 })

package/src/components/SelfManagedStart.tsx

@@ -54,14 +54,13 @@ export function SelfManagedStart({ appUrl, onBack }: { appUrl: string; onBack: (
               </li>
             ))}
           </ol>
-          {/* What a platform engineer has to bring, split by stage: a trial
-              needs only an address clusters can reach (a cloud load balancer
-              is the install page's default; Postgres and a built-in admin come
-              bundled); production adds their own Postgres and IdP. */}
+          {/* Split by stage so a trial doesn't look like a production install:
+              the trial bundles Postgres and a built-in admin. */}
           <div className="mt-5 space-y-1 text-[12px] leading-relaxed text-theme-text-tertiary">
             <p>
-              <b className="font-medium text-theme-text-secondary">For a trial</b>, you just need a hostname your
-              clusters can reach the hub on.
+              <b className="font-medium text-theme-text-secondary">For a trial</b>, install it in one cluster and open
+              it with port-forward, no public address needed. To connect more clusters, give it an address they can
+              reach.
             </p>
             <p>
               <b className="font-medium text-theme-text-secondary">For production</b>, connect your own Postgres and

package/src/components/applications/ApplicationsView.tsx

@@ -4,7 +4,11 @@ import {
   ApplicationsList,
   ApplicationDetail,
   CenteredEmpty,
+  getRadarUpgradeRequirement,
   PageHeader,
+  RadarUpgradeAction,
+  radarUpgradeDetail,
+  radarUpgradeHeadline,
   FreshnessControl,
   IssueRow,
   ISSUE_SEVERITY_RANK,
@@ -166,6 +170,7 @@ export function ApplicationsView({
     );
   }
   if (query.error) {
+    const upgrade = getRadarUpgradeRequirement(query.error);
     return (
       <div className="flex min-h-0 flex-1 flex-col overflow-hidden">
         <div className="shrink-0 border-b border-theme-border px-4 py-4">
@@ -175,12 +180,21 @@ export function ApplicationsView({
             description="Deployable software in this cluster — your services, workers, and jobs, grouped by app/release evidence."
           />
         </div>
-        <CenteredEmpty
-          tone="filtered"
-          icon={Boxes}
-          headline="Failed to load applications"
-          body={(query.error as Error).message}
-        />
+        {upgrade ? (
+          <CenteredEmpty
+            icon={Boxes}
+            headline={radarUpgradeHeadline("Applications")}
+            body={radarUpgradeDetail(upgrade)}
+            action={<RadarUpgradeAction requirement={upgrade} />}
+          />
+        ) : (
+          <CenteredEmpty
+            tone="filtered"
+            icon={Boxes}
+            headline="Failed to load applications"
+            body={(query.error as Error).message}
+          />
+        )}
       </div>
     );
   }

package/src/components/audit/UpgradeReadinessView.test.ts

@@ -1,18 +1,26 @@
 import { describe, expect, it } from 'vitest'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { ApiError } from '../../api/client'
-import { UPGRADE_IMPACT_DOCS_URL, UPGRADE_IMPACT_MIN_RADAR_VERSION, UpgradeReadinessError, groupFindings, incompleteUpgradeCheckCount, issueSpecificReferences, summaryMeta, upgradeEvaluationSummary, upgradeEvidenceCoverageLabel, upgradeUnavailableKindsMessage } from './UpgradeReadinessView'
+import { RadarFeatureUnsupportedError } from '../../api/radarFeatures'
+import { UPGRADE_IMPACT_DOCS_URL, UpgradeReadinessError, groupFindings, incompleteUpgradeCheckCount, issueSpecificReferences, summaryMeta, upgradeEvaluationSummary, upgradeEvidenceCoverageLabel, upgradeUnavailableKindsMessage } from './UpgradeReadinessView'
 
 describe('UpgradeReadinessError', () => {
-  it('maps an unmatched endpoint 404 to the v1.9 upgrade message', () => {
-    const html = renderToStaticMarkup(UpgradeReadinessError({ error: new ApiError('Unknown error', 404) }))
+  it('maps an unsupported-feature error to the v1.9 upgrade message', () => {
+    const html = renderToStaticMarkup(UpgradeReadinessError({ error: new RadarFeatureUnsupportedError('upgradeReadiness', {}) }))
 
-    expect(html).toContain('Upgrade impact needs a newer Radar')
-    expect(html).toContain(UPGRADE_IMPACT_MIN_RADAR_VERSION)
-    expect(html).toContain('Upgrade the in-cluster Radar to enable it')
+    expect(html).toContain('Upgrade impact needs a newer Radar on this cluster')
+    expect(html).toContain('Available from Radar v1.9.')
     expect(html).not.toContain('Unable to analyze upgrade impact')
   })
 
+  it('keeps a non-JSON 404 that is not the router signature on the generic error state', () => {
+    // e.g. Radar Hub's plain-text "not found" for a cluster it can't resolve.
+    const html = renderToStaticMarkup(UpgradeReadinessError({ error: new ApiError('HTTP 404 (Not Found)', 404) }))
+
+    expect(html).toContain('Unable to analyze upgrade impact')
+    expect(html).not.toContain('needs a newer Radar')
+  })
+
   it('keeps a real resource 404 on the generic error state', () => {
     const html = renderToStaticMarkup(UpgradeReadinessError({ error: new ApiError('Cluster not found', 404) }))
 

package/src/components/audit/UpgradeReadinessView.tsx

@@ -19,8 +19,12 @@ import {
   CollapseChevron,
   EmptyState,
   FreshnessControl,
+  getRadarUpgradeRequirement,
   PageHeader,
   PaneLoader,
+  RadarUpgradeAction,
+  radarUpgradeDetail,
+  radarUpgradeHeadline,
   SelectMenu,
 } from '@skyhook-io/k8s-ui'
 import {
@@ -43,7 +47,6 @@ interface UpgradeReadinessViewProps {
 
 const FINDING_CAP = 8
 export const UPGRADE_IMPACT_DOCS_URL = 'https://radarhq.io/docs/features/upgrade-impact'
-export const UPGRADE_IMPACT_MIN_RADAR_VERSION = 'v1.9.0'
 
 const statusMeta: Record<UpgradeReadinessCheckStatus, {
   label: string
@@ -250,22 +253,15 @@ export function UpgradeReadinessView({ namespaces, onNavigateToResource }: Upgra
 }
 
 export function UpgradeReadinessError({ error, onResetTarget }: { error: unknown; onResetTarget?: () => void }) {
-  const missingEndpoint = error instanceof ApiError
-    && error.status === 404
-    && error.message === 'Unknown error'
-  if (missingEndpoint) {
+  const upgrade = getRadarUpgradeRequirement(error)
+  if (upgrade) {
     return (
       <EmptyState
         tone="neutral"
         icon={ShieldAlert}
-        headline="Upgrade impact needs a newer Radar"
-        body={
-          <>
-            This cluster&rsquo;s Radar predates Upgrade impact (added in Radar {UPGRADE_IMPACT_MIN_RADAR_VERSION}).
-            <br />
-            Upgrade the in-cluster Radar to enable it.
-          </>
-        }
+        headline={radarUpgradeHeadline('Upgrade impact')}
+        body={radarUpgradeDetail(upgrade)}
+        action={<RadarUpgradeAction requirement={upgrade} />}
       />
     )
   }

package/src/components/capacity/CapacityView.test.tsx

@@ -26,6 +26,7 @@ import { CapacityView } from "./CapacityView";
 import { updateDemandSearchParam } from "./CapacityDemand";
 import { integrationBlock } from "./shared";
 import { ApiError } from "../../api/client";
+import { RadarFeatureUnsupportedError } from "../../api/radarFeatures";
 
 vi.mock("../../context/ConnectionContext", () => ({
   useConnection: () => ({ connection: { state: "connected" } }),
@@ -2289,15 +2290,23 @@ describe("CapacityView activity", () => {
 });
 
 describe("integrationBlock version skew", () => {
-  it("maps a top-level 404 to the pre-v1.9.0 upgrade message, never 'Unknown error'", () => {
+  it("maps an unsupported-feature error to the upgrade message, never 'Unknown error'", () => {
     const html = renderToString(
-      <>{integrationBlock(undefined, new ApiError("404 page not found", 404), false, "Loading")}</>,
+      <>{integrationBlock(undefined, new RadarFeatureUnsupportedError("capacity", { currentVersion: "v1.7.2" }), false, "Loading")}</>,
     );
-    expect(html).toContain("Capacity needs a newer Radar");
-    expect(html).toContain("v1.9.0");
+    expect(html).toContain("Capacity needs a newer Radar on this cluster");
+    expect(html).toContain("Available from Radar v1.9. This cluster runs v1.7.2.");
     expect(html).not.toContain("Capacity unavailable");
   });
 
+  it("does not read a handler's JSON 404 as a missing route", () => {
+    const html = renderToString(
+      <>{integrationBlock(undefined, new ApiError("nodepool not found", 404, { error: "nodepool not found" }), false, "Loading")}</>,
+    );
+    expect(html).toContain("Capacity unavailable");
+    expect(html).not.toContain("needs a newer Radar");
+  });
+
   it("keeps ordinary failures on the generic error state", () => {
     const html = renderToString(
       <>{integrationBlock(undefined, new ApiError("boom", 500), false, "Loading")}</>,

package/src/components/capacity/shared.tsx

@@ -15,6 +15,10 @@ import {
 import {
   FreshnessControl,
   formatDuration,
+  getRadarUpgradeRequirement,
+  RadarUpgradeAction,
+  radarUpgradeDetail,
+  radarUpgradeHeadline,
   memberRef,
   PaneLoader,
   ResourceBar,
@@ -51,7 +55,6 @@ import {
 import {
   isCapacityCursorInvalidError,
   isForbiddenError,
-  isNotFoundError,
   useCapacityPools,
 } from "../../api/client";
 import type { SelectedResource } from "../../types";
@@ -1520,21 +1523,19 @@ export function integrationBlock(
   if (!response && error) {
     if (isForbiddenError(error))
       return <DeniedCapacityState detail={errorMessage(error)} />;
-    // A 404 on the top-level capacity routes means the route doesn't exist on
-    // this Radar — a pre-v1.9.0 binary behind a version-skewed host (Radar
-    // Cloud), not a failure. The embedded OSS binary can never hit this.
-    if (isNotFoundError(error))
+    // Only reachable behind a version-skewed host (Radar Cloud): the OSS
+    // binary always serves the routes its own frontend calls.
+    const upgrade = getRadarUpgradeRequirement(error);
+    if (upgrade)
       return (
         <EmptyState
           icon={Gauge}
-          title="Capacity needs a newer Radar"
-          detail={
-            <>
-              This cluster&rsquo;s Radar predates the Capacity view (added in
-              Radar v1.9.0).
-              <br />
-              Upgrade the in-cluster Radar to enable it.
-            </>
+          title={radarUpgradeHeadline("Capacity")}
+          detail={radarUpgradeDetail(upgrade)}
+          action={
+            <div className="mt-3 text-sm">
+              <RadarUpgradeAction requirement={upgrade} />
+            </div>
           }
         />
       );

package/src/components/cost/ApplicationCostTab.tsx

@@ -33,6 +33,7 @@ import {
   isCostDiscoveryPending,
 } from './source'
 import { useNavCustomization } from '../../context/NavCustomization'
+import { CostConnectionAction } from './CostConnectionAction'
 
 type ApplicationCostState =
   | 'loading'
@@ -130,6 +131,8 @@ export function ApplicationCostTab({
     state === 'authentication_error' ||
     state === 'configuration_mismatch' ||
     state === 'deployment_configuration_error' ||
+    state === 'metrics_settings_error' ||
+    state === 'cost_settings_error' ||
     state === 'history_unsupported' ||
     state === 'load_error'
   ) {
@@ -398,7 +401,9 @@ export function getApplicationCostState(
     reason === 'source_unavailable' ||
     reason === 'authentication_error' ||
     reason === 'configuration_mismatch' ||
-    reason === 'deployment_configuration_error'
+    reason === 'deployment_configuration_error' ||
+    reason === 'metrics_settings_error' ||
+    reason === 'cost_settings_error'
   )
     return reason
   if (queryError) return 'load_error'
@@ -512,6 +517,8 @@ function reasonLabel(reason?: CostUnavailableReason) {
   if (reason === 'not_found') return 'Workload not found'
   if (reason === 'configuration_mismatch') return 'Kubecost settings are not valid for this cluster'
   if (reason === 'deployment_configuration_error') return 'Radar cost deployment is misconfigured'
+  if (reason === 'metrics_settings_error') return 'Saved metrics settings need review'
+  if (reason === 'cost_settings_error') return 'Saved cost settings need review'
   return 'No workload cost metrics'
 }
 
@@ -577,6 +584,7 @@ function ApplicationCostUnavailable({
       <div className="flex max-w-md flex-col items-center gap-3 text-center text-theme-text-secondary">
         <Coins className="h-8 w-8 text-theme-text-tertiary/50" />
         <div className="text-sm">{text}</div>
+        <CostConnectionAction reason={state} />
       </div>
     </div>
   )

package/src/components/cost/CostConnectionAction.tsx

@@ -0,0 +1,30 @@
+import type { CostUnavailableReason } from '../../api/client'
+import type { ReactNode } from 'react'
+import { useNavCustomization } from '../../context/NavCustomization'
+import { useCapabilitiesContext } from '../../contexts/CapabilitiesContext'
+import { usePreviousIntegrationSettings } from '../../hooks/usePreviousIntegrationSettings'
+import { costConfigurationAction, isCostConfigurable } from './source'
+
+export function CostConnectionAction({ reason, children }: { reason?: CostUnavailableReason | 'load_error'; children?: ReactNode }) {
+  const { embedded } = useNavCustomization()
+  const { configManagement } = useCapabilitiesContext()
+  const available = !embedded && isCostConfigurable(reason)
+  const offers = usePreviousIntegrationSettings(available)
+  if (!available) return <>{children}</>
+  const action = costConfigurationAction(reason as CostUnavailableReason, offers)
+  return (
+    <div className="flex flex-col items-center gap-2 text-center">
+      {action.note && <p className="text-xs text-theme-text-secondary">{action.note}</p>}
+      <div className="flex flex-wrap items-center justify-center gap-2">
+        <button
+          type="button"
+          onClick={() => window.dispatchEvent(new CustomEvent('radar:open-settings', { detail: { section: action.section } }))}
+          className="btn-brand px-3 py-1.5 text-xs font-medium"
+        >
+          {configManagement === 'operator' || configManagement === 'cloud' ? 'View connection settings' : action.label}
+        </button>
+        {children}
+      </div>
+    </div>
+  )
+}

package/src/components/cost/CostTrendChart.tsx

@@ -513,6 +513,8 @@ export function kubecostTrendUnavailableMessage(
       return 'Radar could not reach Kubecost. Check Settings → Cost.'
     case 'configuration_mismatch':
       return 'Kubecost returned data for a different cluster. Check the cluster ID in Settings → Cost.'
+    case 'cost_settings_error':
+      return 'This cluster’s saved cost settings need review. Check Settings → Cost.'
     default:
       return 'Kubecost history could not be loaded.'
   }

package/src/components/cost/CostView.tsx

@@ -41,8 +41,8 @@ import { clusterCloudConsoleLink, nodeCloudConsoleLink } from './cloud-console'
 import { RightsizingScanView } from '../rightsizing/RightsizingScanView'
 import { CostViewTabs } from './CostViewTabs'
 import { useNavCustomization } from '../../context/NavCustomization'
+import { CostConnectionAction } from './CostConnectionAction'
 import {
-  costConfigurationAction,
   costFreshnessLabel,
   costIntegrationUnavailableMessage,
   costRateLabels,
@@ -57,13 +57,6 @@ interface CostViewProps {
 }
 
 const SYSTEM_COST_NAMESPACES = new Set(['kube-system', 'kube-public', 'kube-node-lease'])
-const CONFIGURABLE_COST_REASONS = new Set<CostUnavailableReason>([
-  'no_prometheus',
-  'no_cost_source',
-  'source_unavailable',
-  'authentication_error',
-  'configuration_mismatch',
-])
 
 export function CostView(props: CostViewProps) {
   const { pathname } = useLocation()
@@ -137,8 +130,6 @@ function CostOverview({ onBack, onOpenResource }: CostViewProps) {
       settingsAvailable,
       namespaceScoped: namespaceScopeCount > 0,
     })
-    const canConfigure = settingsAvailable && reason != null && CONFIGURABLE_COST_REASONS.has(reason)
-    const configureAction = costConfigurationAction(reason)
 
     return (
       <CostOverviewState>
@@ -146,18 +137,7 @@ function CostOverview({ onBack, onOpenResource }: CostViewProps) {
           <div className="flex flex-col items-center gap-3 text-theme-text-secondary">
             <Coins className="w-8 h-8 text-theme-text-tertiary/40" />
             <p className="text-sm">{message}</p>
-            <div className="flex flex-wrap items-center justify-center gap-2">
-              {canConfigure && (
-                <button
-                  type="button"
-                  onClick={() => window.dispatchEvent(
-                    new CustomEvent('radar:open-settings', { detail: { section: configureAction.section } }),
-                  )}
-                  className="btn-brand px-3 py-1.5 text-xs font-medium"
-                >
-                  {configureAction.label}
-                </button>
-              )}
+            <CostConnectionAction reason={reason}>
             {(reason === 'no_prometheus' || reason === 'no_cost_source' || reason === 'source_unavailable') && (
               <button
                 onClick={() => {
@@ -170,7 +150,7 @@ function CostOverview({ onBack, onOpenResource }: CostViewProps) {
                 {isFetching ? 'Checking…' : 'Check again'}
               </button>
             )}
-            </div>
+            </CostConnectionAction>
             <button
               onClick={onBack}
               className="text-xs text-accent-text hover:text-theme-text-primary transition-colors"
@@ -893,7 +873,7 @@ function CostHelpDialog({ currency, source, window, onClose }: { currency: strin
               Which currency is shown?
             </h3>
             <p>
-              Radar labels these values <strong>{currency}</strong> and does not convert them. Auto
+              Radar labels these values <strong>{currency}</strong> and does not convert them. Automatic
               reads <code>currencyCode</code> or <code>DISPLAY_CURRENCY</code> from a
               cluster-discovered OpenCost installation or any active Kubecost installation, then
               falls back to USD. A manually configured Prometheus URL disables OpenCost currency

package/src/components/cost/WorkloadCostTab.tsx

@@ -28,6 +28,7 @@ import {
   isCostDiscoveryPending,
 } from './source'
 import { useNavCustomization } from '../../context/NavCustomization'
+import { CostConnectionAction } from './CostConnectionAction'
 
 type WorkloadCostState =
   | 'loading'
@@ -98,6 +99,8 @@ export function WorkloadCostTab({ kind, namespace, name }: WorkloadCostTabProps)
     state === 'authentication_error' ||
     state === 'configuration_mismatch' ||
     state === 'deployment_configuration_error' ||
+    state === 'metrics_settings_error' ||
+    state === 'cost_settings_error' ||
     state === 'history_unsupported' ||
     state === 'load_error'
   ) {
@@ -306,7 +309,9 @@ export function getWorkloadCostState(
     reason === 'source_unavailable' ||
     reason === 'authentication_error' ||
     reason === 'configuration_mismatch' ||
-    reason === 'deployment_configuration_error'
+    reason === 'deployment_configuration_error' ||
+    reason === 'metrics_settings_error' ||
+    reason === 'cost_settings_error'
   )
     return reason
   if (queryError) return 'load_error'
@@ -375,6 +380,7 @@ function WorkloadCostUnavailable({
       <div className="flex max-w-md flex-col items-center gap-3 text-center text-theme-text-secondary">
         <Coins className="h-8 w-8 text-theme-text-tertiary/50" />
         <div className="text-sm">{message}</div>
+        <CostConnectionAction reason={state} />
       </div>
     </div>
   )

package/src/components/cost/source.test.ts

@@ -1,10 +1,30 @@
 import { describe, expect, it } from 'vitest'
-import { costDataThroughLabel, costFreshnessLabel, costIntegrationUnavailableMessage, costRateLabels, costSourceLabel, isCostDiscoveryPending } from './source'
+import { COST_SOURCE_OPTIONS, costSourcePreferenceLabel, costConfigurationAction, isCostConfigurable, costDataThroughLabel, costFreshnessLabel, costIntegrationUnavailableMessage, costRateLabels, costSourceLabel, isCostDiscoveryPending } from './source'
 
 describe('cost source presentation', () => {
+  it('routes missing sources to one applicable previous connection', () => {
+    const both = { metrics: 'previous', cost: 'previous', explicitCostBackend: true } as const
+    expect(costConfigurationAction('no_prometheus', both).section).toBe('prometheus')
+    expect(costConfigurationAction('no_cost_source', both).section).toBe('cost')
+    expect(costConfigurationAction('no_prometheus', { ...both, metrics: undefined }).section).toBe('cost')
+    expect(costConfigurationAction('no_cost_source', { ...both, explicitCostBackend: false }).section).toBe('prometheus')
+    expect(costConfigurationAction('no_prometheus', { ...both, metrics: undefined, explicitCostBackend: false }).label).toBe('Configure metrics')
+    expect(costConfigurationAction('authentication_error', { ...both, cost: undefined }).label).toBe('Configure cost source')
+    expect(costConfigurationAction('configuration_mismatch', both).section).toBe('cost')
+  })
+  it('keeps the neutral action and explains reuse in the note', () => {
+    const copy = { metrics: 'copy', explicitCostBackend: false } as const
+    expect(costConfigurationAction('no_prometheus', copy)).toMatchObject({ section: 'prometheus', label: 'Configure metrics' })
+    expect(costConfigurationAction('no_prometheus', copy).note).toContain('if that backend also serves this cluster')
+    expect(costConfigurationAction('no_prometheus', { ...copy, metrics: 'previous' })).toMatchObject({ label: 'Configure metrics' })
+    expect(costConfigurationAction('no_prometheus', { ...copy, metrics: 'previous' }).note).toContain('now saved per cluster')
+  })
+  it.each(['access_denied', 'not_found', 'history_unsupported', 'no_workload_data', 'no_metrics', 'query_error', 'load_error', undefined])('does not offer connection edits for %s', reason => {
+    expect(isCostConfigurable(reason)).toBe(false)
+  })
   it('distinguishes Prometheus windows from Kubecost ETL freshness', () => {
-    expect(costSourceLabel('prometheus')).toBe('OpenCost via Prometheus')
-    expect(costSourceLabel('kubecost')).toBe('Kubecost Aggregator')
+    expect(costSourceLabel('prometheus')).toBe('OpenCost metrics')
+    expect(costSourceLabel('kubecost')).toBe('Kubecost')
     expect(costFreshnessLabel('prometheus', '1h')).toBe('last 1h average')
     expect(costFreshnessLabel('kubecost', '1h', '2026-08-26T13:58:00Z')).toContain('1-hour allocation average')
     expect(costFreshnessLabel('kubecost', '1d', '2026-08-26T13:58:00Z')).toContain('1-day allocation average')
@@ -12,6 +32,13 @@ describe('cost source presentation', () => {
     expect(costDataThroughLabel('invalid')).toBe('')
   })
 
+  it('names cost-source preferences the same way in every install type', () => {
+    expect(COST_SOURCE_OPTIONS.map(option => option.label)).toEqual(['Automatic', 'OpenCost metrics', 'Kubecost'])
+    expect(costSourcePreferenceLabel(undefined)).toBe('Automatic')
+    expect(costSourcePreferenceLabel('')).toBe('Automatic')
+    expect(costSourcePreferenceLabel('prometheus')).toBe('OpenCost metrics')
+  })
+
   it('labels fallback allocation windows without calling a daily average current', () => {
     expect(costRateLabels('1h').hourly).toBe('Hourly (1-hour average)')
     expect(costRateLabels('1d').rate).toBe('1-day average hourly rate')

package/src/components/cost/source.ts

@@ -1,17 +1,48 @@
 import type { CostDataSource, CostUnavailableReason } from '../../api/client'
+import { previousSettingsNote, type PreviousIntegrationSettings } from '../../hooks/usePreviousIntegrationSettings'
+
+export function isCostConfigurable(reason?: string): boolean {
+  return reason === 'no_prometheus' || reason === 'no_cost_source' || reason === 'source_unavailable'
+    || reason === 'authentication_error' || reason === 'configuration_mismatch'
+    || reason === 'metrics_settings_error' || reason === 'cost_settings_error'
+}
+
+export type CostSourcePreference = 'auto' | CostDataSource
+
+export const COST_SOURCE_OPTIONS: { value: CostSourcePreference; label: string; description: string }[] = [
+  { value: 'auto', label: 'Automatic', description: 'OpenCost metrics when available, otherwise Kubecost' },
+  { value: 'prometheus', label: 'OpenCost metrics', description: 'From the metrics connection' },
+  { value: 'kubecost', label: 'Kubecost', description: 'From a Kubecost Aggregator' },
+]
+
+export function costSourcePreferenceLabel(preference?: string): string {
+  return COST_SOURCE_OPTIONS.find(option => option.value === (preference || 'auto'))?.label ?? preference ?? 'Automatic'
+}
 
 export function costSourceLabel(source?: CostDataSource): string {
-  return source === 'kubecost' ? 'Kubecost Aggregator' : 'OpenCost via Prometheus'
+  return costSourcePreferenceLabel(source === 'kubecost' ? 'kubecost' : 'prometheus')
 }
 
 export function isCostDiscoveryPending(reason?: string): boolean {
   return reason === 'no_prometheus' || reason === 'no_cost_source'
 }
 
-export function costConfigurationAction(reason?: CostUnavailableReason): {
+export function costConfigurationAction(reason?: CostUnavailableReason, offers?: PreviousIntegrationSettings): {
   section: 'prometheus' | 'cost'
   label: string
+  note?: string
 } {
+  if (reason === 'metrics_settings_error') return { section: 'prometheus', label: 'Review metrics settings' }
+  if (reason === 'cost_settings_error') return { section: 'cost', label: 'Review cost settings' }
+  const previousKind = reason === 'no_prometheus'
+    ? offers?.metrics ? 'metrics' : offers?.explicitCostBackend ? 'cost' : undefined
+    : reason === 'no_cost_source'
+      ? offers?.explicitCostBackend ? 'cost' : offers?.metrics ? 'metrics' : undefined
+      : isCostConfigurable(reason) && offers?.cost ? 'cost' : undefined
+  const offer = previousKind && offers?.[previousKind]
+  if (previousKind && offer) return previousKind === 'metrics'
+    ? { section: 'prometheus', label: 'Configure metrics', note: previousSettingsNote('metrics', offer) }
+    : { section: 'cost', label: 'Configure cost source', note: previousSettingsNote('cost', offer) }
   return reason === 'no_prometheus'
     ? { section: 'prometheus', label: 'Configure metrics' }
     : { section: 'cost', label: 'Configure cost source' }
@@ -84,6 +115,10 @@ export function costIntegrationUnavailableMessage(
       return settingsAvailable
         ? 'Kubecost Aggregator is unavailable. Check the URL, network path, and cluster ID in Settings → Cost.'
         : 'Kubecost Aggregator is unavailable. Update this cluster’s cost-source configuration in the host application or Radar deployment.'
+    case 'metrics_settings_error':
+      return 'This cluster’s saved metrics settings need review before cost data can load. Review them in Settings → Metrics.'
+    case 'cost_settings_error':
+      return 'This cluster’s saved cost settings need review before cost data can load. Review them in Settings → Cost.'
     case 'deployment_configuration_error':
       return 'Cost collection is misconfigured by this Radar deployment. Update its environment variables or Helm cost values, then restart Radar.'
     case 'authentication_error':