@skyhook-io/radar-app 1.14.6 → 1.16.0

package/src/api/usage-data.ts

@@ -0,0 +1,165 @@
+import { useCallback, useEffect } from 'react'
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query'
+import { fetchJSON } from './client'
+import { apiUrl, getApiBase, getAuthHeaders, getCredentialsMode } from './config'
+
+export type UsageDataState = 'undecided' | 'on' | 'off'
+export type UsageDataSource = 'default' | 'user' | 'env' | 'deployment'
+
+export interface ClusterShape {
+  kubernetesVersion: string
+  platform: string
+  nodes: string
+  integrations: string[]
+}
+
+export interface UsageReport {
+  schema: number
+  version: string
+  os: string
+  arch: string
+  installMethod: string
+  mode: string
+  periodStart: string
+  periodEnd: string
+  setup: {
+    authMode: string
+    timelineStorage: string
+    mcpEnabled: boolean
+    prometheus: string
+    costSource: string
+    browsers: string[]
+  }
+  engagement: { sessions: number; activeMinutes: string }
+  views: Record<string, number>
+  actions: Record<string, number>
+  mcpTools: Record<string, number>
+  uiEvents: Record<string, number>
+  errors: Record<string, number>
+  clusters: { contexts: string; used: number; shapes: ClusterShape[] }
+}
+
+export interface UsageDataStatus {
+  state: UsageDataState
+  source: UsageDataSource
+  canChange: boolean
+  developmentBuild: boolean
+  nextReportAt?: string
+  preview: UsageReport
+  firstRunPrompt: boolean
+  // What's New may ask: never asked, or asked and left unanswered long enough ago.
+  ask: boolean
+  // Several people use this Radar, so its configuration decides and nobody is asked.
+  shared: boolean
+}
+
+const usageDataKey = (apiBase: string) => ['usage-data', apiBase]
+
+// `fresh` is for the report preview: it must match what would be sent now, so
+// it refetches every time it is shown instead of reusing the app shell's copy.
+export function useUsageData(enabled = true, { fresh = false }: { fresh?: boolean } = {}) {
+  const apiBase = getApiBase()
+  return useQuery<UsageDataStatus>({
+    queryKey: usageDataKey(apiBase),
+    queryFn: () => fetchJSON<UsageDataStatus>('/usage-data'),
+    enabled,
+    staleTime: fresh ? 0 : 60_000,
+    refetchOnMount: fresh ? 'always' : true,
+    retry: false,
+  })
+}
+
+export function useSetUsageData() {
+  const queryClient = useQueryClient()
+  const apiBase = getApiBase()
+  return useMutation({
+    mutationFn: (enabled: boolean) =>
+      fetchJSON<UsageDataStatus>('/usage-data', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ enabled }),
+      }),
+    meta: { errorMessage: 'Failed to save usage data choice' },
+    // A status read still in flight predates the choice; it must not
+    // replace the answer the server just confirmed.
+    onSuccess: async (status) => {
+      const queryKey = usageDataKey(apiBase)
+      await queryClient.cancelQueries({ queryKey })
+      queryClient.setQueryData(queryKey, status)
+    },
+  })
+}
+
+// Records that the question was shown, answered or not, and stops this tab
+// offering it again from its cached status. Fire and forget: a failure only
+// means it might show once more.
+export function useMarkUsagePromptShown() {
+  const queryClient = useQueryClient()
+  const apiBase = getApiBase()
+  return useCallback(() => {
+    const queryKey = usageDataKey(apiBase)
+    void queryClient.cancelQueries({ queryKey })
+    queryClient.setQueryData<UsageDataStatus>(queryKey, (prev) => prev && { ...prev, firstRunPrompt: false, ask: false })
+    void fetch(apiUrl('/usage-data/prompt-shown'), {
+      method: 'POST',
+      headers: getAuthHeaders(),
+      credentials: getCredentialsMode(),
+    }).catch(() => {})
+  }, [queryClient, apiBase])
+}
+
+export function isRecording(status: UsageDataStatus | undefined): boolean {
+  return status?.state === 'on'
+}
+
+// Set from the status query so code without hook access (error boundaries,
+// event handlers) can skip the request entirely when usage data is off.
+let recording = false
+
+function setUsageRecording(on: boolean) {
+  recording = on
+}
+
+type UsageEvent =
+  | { type: 'view'; name: string }
+  | { type: 'ui'; name: string }
+  | { type: 'session' }
+  | { type: 'active'; minutes: number }
+
+// Fire and forget; the server drops anything outside its allow-list.
+export function recordUsageEvent(event: UsageEvent): void {
+  if (!recording) return
+  void fetch(apiUrl('/usage-data/event'), {
+    method: 'POST',
+    headers: { ...getAuthHeaders(), 'Content-Type': 'application/json' },
+    credentials: getCredentialsMode(),
+    body: JSON.stringify(event),
+    keepalive: true,
+  }).catch(() => {})
+}
+
+const ACTIVE_TICK_MINUTES = 5
+
+// Counts views, one session per page load, and visible time in five-minute
+// ticks. Nothing is sent unless usage data is on.
+export function useUsageRecording(view: string, status: UsageDataStatus | undefined) {
+  const on = isRecording(status)
+  useEffect(() => {
+    setUsageRecording(on)
+  }, [on])
+
+  useEffect(() => {
+    if (on) recordUsageEvent({ type: 'view', name: view })
+  }, [view, on])
+
+  useEffect(() => {
+    if (!on) return
+    recordUsageEvent({ type: 'session' })
+    const tick = window.setInterval(() => {
+      if (document.visibilityState === 'visible') {
+        recordUsageEvent({ type: 'active', minutes: ACTIVE_TICK_MINUTES })
+      }
+    }, ACTIVE_TICK_MINUTES * 60_000)
+    return () => window.clearInterval(tick)
+  }, [on])
+}

package/src/components/CloudFunnelButton.test.tsx

@@ -91,9 +91,9 @@ describe('Cloud dialog connection availability', () => {
     expect(requests).not.toContain('/api/cloud/install/discover')
     expect(requests).not.toContain('/api/cloud/install/prepare')
     await act(async () => { button('How it works and what it costs')!.click() })
-    expect(document.body.textContent).toContain('You approve the connection before anything is installed.')
+    expect(document.body.textContent).toContain('Radar runs in your cluster and tunnels outward to Radar Cloud')
     expect(document.body.textContent).not.toContain('Setup runs here in the app')
-    expect(document.body.textContent).not.toContain('Nothing installs on click')
+    expect(document.body.textContent).not.toContain('see what gets installed')
   })
 
   it('restores cluster discovery and Connect in the open dialog when the connection recovers', async () => {

package/src/components/CloudFunnelButton.tsx

@@ -1,13 +1,13 @@
 import { useEffect, useId, useState } from 'react'
 import { useMutation, useQueryClient } from '@tanstack/react-query'
-import { Bell, Check, Globe, History, Sparkles, Users, X } from 'lucide-react'
+import { Bell, Check, Cloud, Globe, History, Sparkles, Users, X } from 'lucide-react'
 import { Collapse, CollapseChevron } from '@skyhook-io/k8s-ui/components/ui/Collapse'
 import { DialogPortal } from '@skyhook-io/k8s-ui/components/ui/DialogPortal'
 import { Tooltip } from './ui/Tooltip'
 import { CloudConnectFlow } from './CloudConnectFlow'
+import { SelfManagedStart } from './SelfManagedStart'
 import {
   type Handoff,
-  SELF_HOSTED_DOCS_URL,
   exitFor,
   handoffForBlocked,
   handoffForPrepareError,
@@ -33,7 +33,9 @@ import {
 } from '../api/client'
 
 // OSS → Cloud funnel: a quiet globe button in the top bar that opens a modal
-// pitching Radar Cloud. Two lanes (capabilities.cloudConnect): "driver" runs
+// pitching Radar Cloud: Radar for you and your team, every cluster, around the
+// clock. Alerts and hosted investigations lead because they are the two things
+// the OSS binary cannot do at all. Two lanes (capabilities.cloudConnect): "driver" runs
 // the in-product connect flow against this server; "wizard" links to the Hub's
 // connect wizard.
 //
@@ -58,7 +60,7 @@ const FALLBACK_APP_URL = 'https://app.radarhq.io'
 const DEFAULT_ASSURANCES = [
   'Secure outbound-only tunnel',
   'Disconnect and delete your data anytime',
-  'SOC 2 Type II',
+  'SOC 2 Type II · SSO & SCIM on Enterprise',
   '3 clusters free, no card required',
 ]
 // Other OSS surfaces (a GitOps app that deploys to another cluster, say)
@@ -71,6 +73,7 @@ export function openCloudFunnel() {
   window.dispatchEvent(new Event(OPEN_EVENT))
 }
 const ABOUT_URL = 'https://radarhq.io/about'
+const BENCHMARK_URL = 'https://radarhq.io/benchmark'
 const PRICING_URL = 'https://radarhq.io/pricing'
 const SEEN_KEY = 'radar.cloudFunnel.seen'
 
@@ -99,6 +102,7 @@ export function CloudFunnelButton() {
   const [open, setOpen] = useState(false)
   const [seen, setSeen] = useState(readSeen)
   const [inFlowView, setInFlowView] = useState(false)
+  const [selfManaged, setSelfManaged] = useState(false)
   const [blocked, setBlocked] = useState<CloudInstallBlocked | null>(null)
   // Set once an in-app attempt has ended without connecting, naming what
   // happened (a flow failure kind, a blocked plan, a canceled plan, or the
@@ -191,6 +195,7 @@ export function CloudFunnelButton() {
 
   const openModal = () => {
     setOpen(true)
+    setSelfManaged(false)
     setSeen(true)
     markSeen()
     // Re-open lands on a live flow if one is running.
@@ -282,14 +287,24 @@ export function CloudFunnelButton() {
     <>
       {/* Tooltip is suppressed while the modal is open — it portals above the
           modal backdrop and would otherwise paint on top of the dialog. */}
-      <Tooltip content="Radar Cloud: all your clusters, one URL" delay={100} position="bottom" disabled={open}>
+      <Tooltip
+        content={
+          <>
+            <span className="block font-semibold">Meet Radar Cloud</span>
+            See all your clusters in one place, share with your team, and get alerts and automatic AI investigations.
+          </>
+        }
+        delay={100}
+        position="bottom"
+        disabled={open}
+      >
         <button
           onClick={openModal}
           aria-label="Radar Cloud"
           aria-haspopup="dialog"
           className="relative p-1.5 rounded-md bg-theme-elevated hover:bg-theme-hover text-theme-text-secondary hover:text-theme-text-primary transition-colors"
         >
-          <Globe className="w-4 h-4" />
+          <Cloud className="w-4 h-4" />
           {cloudInstallActive(flow?.state) ? (
             <span className="absolute top-0.5 right-0.5 w-[7px] h-[7px] rounded-full bg-emerald-500 animate-pulse motion-reduce:animate-none" />
           ) : (
@@ -305,6 +320,7 @@ export function CloudFunnelButton() {
       <DialogPortal
         open={open}
         onClose={() => setOpen(false)}
+        ariaLabel="Radar Cloud"
         className="w-[580px] max-w-full max-h-[calc(100vh-2rem)] overflow-hidden flex flex-col"
       >
         <button
@@ -332,6 +348,13 @@ export function CloudFunnelButton() {
               onExit={() => exitFlow(outcomeOf(flowForView))}
             />
           </div>
+        ) : selfManaged ? (
+          <>
+            <div className="shrink-0 px-8 pt-7">
+              <Eyebrow />
+            </div>
+            <SelfManagedStart appUrl={appUrl} onBack={() => setSelfManaged(false)} />
+          </>
         ) : (
           <>
             <div className="min-h-0 overflow-y-auto">
@@ -360,6 +383,7 @@ export function CloudFunnelButton() {
               // in-cluster, so the CTA would escape before classification.
               selfLoading={inCluster && self.isPending}
               onConnect={startConnect}
+              onSelfManaged={() => setSelfManaged(true)}
               onLater={() => setOpen(false)}
             />
           </>
@@ -395,7 +419,7 @@ function Eyebrow() {
   return (
     <div className="flex items-center gap-3 mb-5">
       <RadarSweep />
-      <span className="font-mono text-[10.5px] tracking-[0.16em] uppercase text-emerald-600 dark:text-emerald-400">Radar Cloud</span>
+      <span className="font-mono text-[16px] tracking-[0.12em] uppercase text-emerald-600 dark:text-emerald-400">Radar Cloud</span>
     </div>
   )
 }
@@ -417,6 +441,7 @@ function ModalFooter({
   discoverPending = false,
   clustersUrl,
   onConnect,
+  onSelfManaged,
   onLater,
 }: {
   lane: 'driver' | 'wizard'
@@ -449,6 +474,7 @@ function ModalFooter({
   // settings say it is connected but not where.
   clustersUrl?: string
   onConnect: () => void
+  onSelfManaged: () => void
   onLater: () => void
 }) {
   const gitops = self?.ownership === 'gitops'
@@ -463,7 +489,7 @@ function ModalFooter({
   // fast click would escape to signup before we could route this install.
   const selfPending = selfLoading === true
   return (
-    <div className="shrink-0 px-8 py-5 bg-theme-base border-t border-theme-border">
+    <div className="shrink-0 px-8 py-6 bg-theme-base border-t border-theme-border">
       {self && self.ownership !== 'unknown' && (
         <div className="mb-3.5 card-inner p-3 text-[12px] leading-relaxed text-theme-text-secondary">
           {ambiguous ? (
@@ -551,17 +577,6 @@ function ModalFooter({
                   inspect step and a plan the user approves in the browser. */}
               {prepareFailed ? 'Try again' : 'Connect this cluster…'}
             </button>
-            {/* Always visible: the browser wizard is a different workflow, not
-                a recovery path — install-averse operators need the door before
-                anything fails, or they close the modal instead. */}
-            <a
-              href={driverBrowserUrl}
-              target="_blank"
-              rel="noopener noreferrer"
-              className="whitespace-nowrap text-[12.5px] text-theme-text-secondary hover:text-theme-text-primary hover:underline underline-offset-2 transition-colors"
-            >
-              or set up in the browser
-            </a>
           </>
         ) : cliOnly ? null : (
           <a
@@ -575,6 +590,19 @@ function ModalFooter({
             {lane === 'driver' ? 'Continue in Radar Cloud' : self?.ownership === 'helm' || gitops ? 'Connect this cluster' : 'Try Cloud free'}
           </a>
         )}
+        {/* Self-Managed is a paid product with its own trial, so it gets a real
+            button beside the hosted CTA rather than a link near the exit, the
+            way GitLab and n8n show their self-managed tiers. Outlined, so the
+            hosted CTA stays the default. */}
+        {!(lane === 'driver' && alreadyConnected) && (
+          <button
+            type="button"
+            onClick={onSelfManaged}
+            className="whitespace-nowrap px-4 py-2 rounded-[10px] border border-theme-border bg-theme-surface hover:bg-theme-hover text-theme-text-primary text-[13px] font-medium transition-colors"
+          >
+            Run Radar Cloud yourself
+          </button>
+        )}
         <button onClick={onLater} className="ml-auto whitespace-nowrap text-[12px] text-theme-text-tertiary hover:text-theme-text-primary transition-colors">
           {lane === 'driver' && alreadyConnected ? 'Close' : 'Maybe later'}
         </button>
@@ -592,16 +620,27 @@ function ModalFooter({
           fulfills. Sits next to the button whose click it de-risks. */}
       {lane === 'driver' && clusterConnected && !alreadyConnected && (
         <p className="mt-2.5 text-[11px] leading-relaxed text-theme-text-tertiary">
-          Nothing installs on click. Radar inspects{' '}
-          {clusterName ? <span className="text-theme-text-secondary">{clusterName}</span> : 'the cluster'} and shows
-          you a plan; you approve it in the browser before anything changes.
+          Nothing installs on click. You&apos;ll see what gets installed in{' '}
+          {clusterName ? <span className="text-theme-text-secondary">{clusterName}</span> : 'this cluster'} and approve
+          it before anything changes.{' '}
+          {/* Always offered: the browser wizard is a different workflow, not a
+              recovery path. Install-averse operators need this door before
+              anything fails, or they close the dialog instead. */}
+          <a
+            href={driverBrowserUrl}
+            target="_blank"
+            rel="noopener noreferrer"
+            className="whitespace-nowrap text-theme-text-secondary underline underline-offset-2 hover:text-theme-text-primary"
+          >
+            Or set up in the browser →
+          </a>
         </p>
       )}
       {/* A 2-column grid, not flex-wrap: the long data-locality chip cannot
           share a single row with the other three at this width, and flex
           wrapping strands it as a 3+1 orphan. Two balanced columns read as a
           designed layout at any chip length the Hub sends. */}
-      <div className="mt-4 grid grid-cols-2 gap-x-3 gap-y-1.5 text-[11px] text-theme-text-tertiary">
+      <div className="mt-5 grid grid-cols-2 gap-x-3 gap-y-2 text-[11px] text-theme-text-tertiary">
         {assuranceItems(assurances).map((item) => (
           <span key={item} className="flex items-center gap-1">
             <Check className="w-3 h-3 shrink-0 text-emerald-600 dark:text-emerald-400" />
@@ -622,26 +661,31 @@ function PitchBody({ lane, freeTier }: { lane: 'driver' | 'wizard'; freeTier?: s
   // unreachable or predates the field).
   const freeLine = freeTier || 'free for 3 clusters'
   // lead is the scannable anchor (medium, primary); rest stays secondary.
+  // Each bullet is one line at the dialog's width, so the first screen stays
+  // skimmable. Alerts and investigations lead: they are the two things the
+  // OSS binary cannot do at all. Team, fleet and history follow.
   const highlights = [
-    { icon: Globe, lead: 'Your whole fleet in one URL', rest: ': issues, checks and search across every cluster' },
-    { icon: Users, lead: 'Bring the team', rest: ": SSO, invites and roles. Your cluster's RBAC has the final say" },
-    { icon: Bell, lead: 'Alerts', rest: ' that reach you the moment something breaks' },
-    { icon: History, lead: 'Long-term retention', rest: ': history that survives restarts and keeps growing' },
-    { icon: Sparkles, lead: 'An AI agent', rest: ' that digs into issues and pinpoints the root cause' },
+    { icon: Bell, lead: 'Alerts', rest: ' to Slack or any webhook. One per failure, not per crash-looping pod.' },
+    { icon: Sparkles, lead: 'AI investigations', rest: ': root cause with evidence, automatic on alerts or on demand' },
+    { icon: Users, lead: 'Your team', rest: ': share any view with just a link, scoped by your existing RBAC' },
+    { icon: Globe, lead: 'Every cluster', rest: ': the whole fleet in one view and one MCP endpoint' },
+    { icon: History, lead: 'History', rest: ': events and changes kept long after Kubernetes deletes them' },
   ]
   return (
-    <div className="px-8 pt-7 pb-2">
+    <div className="px-8 pt-7 pb-5">
       <Eyebrow />
-      <h3 className="text-[22px] font-semibold leading-tight tracking-tight text-theme-text-primary mb-3">
-        Meet Radar Cloud
+      <h3 className="text-[22px] font-semibold leading-tight tracking-tight text-theme-text-primary mb-3 text-balance">
+        Close the laptop. Radar keeps watching.
       </h3>
+      <p className="text-[14px] leading-relaxed text-theme-text-secondary mb-1.5">
+        Radar Cloud is the hosted side of Radar: alerts, AI root cause and every cluster in one place, for
+        you and your team.
+      </p>
       <p className="text-[14px] leading-relaxed text-theme-text-secondary mb-6">
-        The hosted side of Radar: your clusters in one place, run by us.
-        <br />
         The Radar you're running{' '}
         <b className="text-theme-text-primary font-semibold">stays free and open source, always.</b>
       </p>
-      <ul className="space-y-2.5 mb-4">
+      <ul className="space-y-2.5 mb-3">
         {highlights.map(({ icon: Icon, lead, rest }) => (
           <li key={lead} className="flex items-start gap-2.5 text-[13px] leading-relaxed text-theme-text-secondary">
             <Icon className="w-4 h-4 shrink-0 mt-[3px] text-emerald-600 dark:text-emerald-400" />
@@ -670,46 +714,46 @@ function PitchBody({ lane, freeTier }: { lane: 'driver' | 'wizard'; freeTier?: s
             {/* No heading: the disclosure's own label already names this one. */}
             <p className="text-[12px] leading-relaxed text-theme-text-secondary">
               {lane === 'driver'
-                ? 'Setup runs here in the app: Radar is installed in your cluster and connects outward to Radar Cloud. You review the plan and approve in your browser before anything is installed.'
-                : 'Radar runs in your cluster and connects outward to Radar Cloud. You approve the connection before anything is installed.'}
+                ? "Setup runs here in the app: Radar is installed in your cluster and tunnels outward to Radar Cloud, so there's no ingress to open."
+                : "Radar runs in your cluster and tunnels outward to Radar Cloud, so there's no ingress to open."}{' '}
+              Live views are fetched from your cluster when someone opens them, within their permissions. Radar
+              Cloud stores event history, changes and investigation results, so you can go back in time to
+              debug.
+            </p>
+          </section>
+          <section>
+            <h4 className="text-[12.5px] font-semibold text-theme-text-primary mb-0.5">Investigations</h4>
+            <p className="text-[12px] leading-relaxed text-theme-text-secondary">
+              In our public benchmark, the same agent diagnosed faults 3× faster on average with Radar than with
+              plain kubectl, and Radar answered 1.6–3.6× faster on average than the other AI SRE tools we tested.
+              Run it automatically on the alert rules you choose, or on demand from any issue, with no CLI or API
+              key.{' '}
+              <a href={BENCHMARK_URL} target="_blank" rel="noopener noreferrer" className="whitespace-nowrap text-theme-text-secondary underline underline-offset-2 hover:text-theme-text-primary">
+                See the benchmarks →
+              </a>
             </p>
           </section>
           <section>
             <h4 className="text-[12.5px] font-semibold text-theme-text-primary mb-0.5">What it costs</h4>
             <p className="text-[12px] leading-relaxed text-theme-text-secondary">
-              Radar Cloud is {freeLine}. The paid plans beyond that are what keep the lights on. The
-              Radar you're running stays
-              Apache&nbsp;2.0 either way: every feature, forever.{' '}
+              Radar Cloud is {freeLine}, including 100 investigations a month. Paid plans add investigations for
+              every cluster, with optional $1 overage, plus enterprise features like SSO, SCIM and audit logs.{' '}
               <a href={PRICING_URL} target="_blank" rel="noopener noreferrer" className="whitespace-nowrap text-theme-text-secondary underline underline-offset-2 hover:text-theme-text-primary">
                 See pricing →
               </a>
             </p>
           </section>
           <section>
-            <h4 className="text-[12.5px] font-semibold text-theme-text-primary mb-0.5">Who's behind it</h4>
+            {/* No heading: "built by Skyhook" already answers who is behind it. */}
             <p className="text-[12px] leading-relaxed text-theme-text-secondary">
-              Radar is built in the open and run by Skyhook, a CNCF Silver member and a small team of
-              humans, the kind you can actually talk to.{' '}
+              Built in the open by Skyhook, a CNCF Silver member and a small team you can actually talk to.{' '}
               <a href={ABOUT_URL} target="_blank" rel="noopener noreferrer" className="whitespace-nowrap text-theme-text-secondary underline underline-offset-2 hover:text-theme-text-primary">
                 Meet us →
               </a>
             </p>
           </section>
-          <p className="text-[12px] leading-relaxed text-theme-text-secondary">
-            Prefer your own VPC? You can run the Radar Cloud control plane yourself.{' '}
-            <a href={SELF_HOSTED_DOCS_URL} target="_blank" rel="noopener noreferrer" className="text-theme-text-secondary underline underline-offset-2 hover:text-theme-text-primary">
-              Read the docs
-            </a>
-            .
-          </p>
         </div>
       </Collapse>
-      <div className="mb-5 border-l-2 border-emerald-500/40 pl-3.5">
-        <p className="text-[12px] leading-relaxed text-theme-text-secondary">
-          Don't need Radar Cloud right now? That's fine. What you're running is already a full product,
-          not a demo. We're here if you ever do.
-        </p>
-      </div>
     </div>
   )
 }

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}
     />
   )
 })