@skyhook-io/k8s-ui 1.18.2 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyhook-io/k8s-ui",
-  "version": "1.18.2",
+  "version": "1.19.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/skyhook-io/radar",

package/src/components/charts/AreaChart.test.tsx

@@ -2,7 +2,7 @@ import { describe, expect, it } from 'vitest'
 import { renderToStaticMarkup } from 'react-dom/server'
 import { AreaChart } from './AreaChart'
 import { layoutAnnotations, ANNOTATION_LABEL_ROWS } from './annotations'
-import { formatTimestamp } from './format'
+import { alignedTimeAxisTicks, formatTimestamp } from './format'
 import type { ChartAnnotation, TimeSeries } from './types'
 
 const t0 = 1_788_679_000
@@ -82,6 +82,29 @@ describe('AreaChart domain and axes', () => {
     expect(Math.max(...xs)).toBeCloseTo(960, 0)
   })
 
+  it('labels a multi-day X axis on local midnights', () => {
+    const week = 7 * 86_400
+    const html = render({ series: [series([[0, 1], [week, 2]])], domain: { start: t0, end: t0 + week } })
+    const ticks = alignedTimeAxisTicks(t0, t0 + week, 7)!
+    expect(ticks.length).toBeGreaterThanOrEqual(2)
+    for (const { label } of ticks) expect(html).toContain(`>${label}<`)
+    expect(html).not.toContain(`>${formatTimestamp(t0)}<`)
+  })
+
+  it('keeps every X label inside the viewBox on a multi-day axis', () => {
+    for (const days of [1.5, 2, 3, 7, 11, 270]) {
+      const span = days * 86_400
+      const html = render({ series: [series([[0, 1], [span, 2]])], domain: { start: t0, end: t0 + span } })
+      const xLabels = [...html.matchAll(/<text x="([^"]+)" y="296" text-anchor="middle"[^>]*>([^<]*)<\/text>/g)]
+      expect(xLabels.length).toBeGreaterThanOrEqual(2)
+      for (const [, x, label] of xLabels) {
+        const half = (label.length * 11 * 0.6) / 2
+        expect(Number(x) - half).toBeGreaterThanOrEqual(0)
+        expect(Number(x) + half).toBeLessThanOrEqual(1000)
+      }
+    }
+  })
+
   it('extends the Y axis below zero and draws a zero line for negative values', () => {
     const html = render({ series: [series([[0, -4], [600, 2], [1200, -1]])] })
     expect(html).toContain('data-chart-zero-line')
@@ -196,3 +219,18 @@ describe('AreaChart gaps and selection', () => {
     expect(html).toContain('cursor:crosshair')
   })
 })
+
+describe('AreaChart dashboard height', () => {
+  const data = [series([[0, 1], [600, 2]])]
+
+  it('renders the dashboard layout at the height asked for, and 240 by default', () => {
+    const short = render({ series: data, layout: 'dashboard', height: 140 })
+    expect(short).toContain('height:140px')
+    expect(attrs(short, 'svg', 'viewBox')[0]).toMatch(/ 140$/)
+    expect(render({ series: data, layout: 'dashboard' })).toContain('height:240px')
+  })
+
+  it('ignores the height outside the dashboard layout', () => {
+    expect(render({ series: data, layout: 'auto', height: 140 })).not.toContain('height:140px')
+  })
+})

package/src/components/charts/AreaChart.tsx

@@ -1,9 +1,9 @@
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from 'react'
 import type * as React from 'react'
 import { seriesColor, seriesFill, computeShortLabels, seriesDisplayLabels } from './colors'
-import { formatMetricValue, formatTimestamp } from './format'
+import { alignedTimeAxisTicks, datesNeedYear, formatFullTimestamp, formatMetricValue, formatTimeAxisLabels, labelWidthEm, type TimeAxisTick } from './format'
 import { layoutAnnotations } from './annotations'
-import { chartLayout, integerAxisTop, isCountUnit, yAxisValues } from './axis'
+import { chartLayout, integerAxisTop, isCountUnit, xLabelMaxWidthEm, yAxisValues } from './axis'
 import type { TimeSeries, ReferenceLine, ChartAnnotation } from './types'
 import { nearestSample } from './nearestSample'
 
@@ -19,7 +19,7 @@ export interface ChartTimeRange {
   end: number
 }
 
-export function AreaChart({ series, color, fillColor, unit, referenceLines, annotations, domain, seriesLabels, stepSeconds, layout = 'full', shadedRanges, selection, onSelectRange }: {
+export function AreaChart({ series, color, fillColor, unit, referenceLines, annotations, domain, seriesLabels, stepSeconds, layout = 'full', height: dashboardHeight = 240, shadedRanges, selection, onSelectRange }: {
   series: TimeSeries[]
   color: string
   fillColor: string
@@ -45,6 +45,8 @@ export function AreaChart({ series, color, fillColor, unit, referenceLines, anno
    * keeps text and plot height stable as its container resizes.
    */
   layout?: 'full' | 'auto' | 'compact' | 'dashboard'
+  /** Rendered height in px of the 'dashboard' layout; ignored by the others. */
+  height?: number
   /** Ranges drawn hatched, e.g. where no sample exists; `label` says why and shows on hover. */
   shadedRanges?: (ChartTimeRange & { label?: string })[]
   /** A selected range, drawn as a band. */
@@ -116,7 +118,8 @@ export function AreaChart({ series, color, fillColor, unit, referenceLines, anno
   // Layout constants. marginLeft sized for the widest expected Y-tick label
   // ("422.4 MiB" etc.) — narrow grid panels squeeze the X axis so labels
   // need extra viewBox-space to survive the down-scale.
-  const base = chartLayout(compact, layout === 'dashboard', renderedWidth)
+  const measured = chartLayout(compact, layout === 'dashboard', renderedWidth)
+  const base = layout === 'dashboard' ? { ...measured, height: dashboardHeight } : measured
   const { width, height, marginRight, marginTop, marginBottom, fontSize, yIntervals, xIntervals } = base
   const yValues = chartData ? yAxisValues(chartData.yMin, chartData.yMax, yIntervals, countAxis) : []
   const yLabels = yValues.map(val => formatMetricValue(val, unit))
@@ -149,14 +152,30 @@ export function AreaChart({ series, color, fillColor, unit, referenceLines, anno
   const xTicks = useMemo(() => {
     if (!chartData) return []
     const { minTs, maxTs } = chartData
-    return Array.from({ length: xIntervals + 1 }, (_, i) => {
-      const ts = minTs + ((maxTs - minTs) / xIntervals) * i
-      // In the compact layout the two labels sit at the plot edges and would
-      // otherwise spill past the viewBox.
-      const anchor: 'start' | 'middle' | 'end' = !(compact || layout === 'dashboard') ? 'middle' : i === 0 ? 'start' : i === xIntervals ? 'end' : 'middle'
-      return { ts, x: toX(ts), label: formatTimestamp(ts), anchor }
+    // A window longer than a day gets ticks on local midnights (and clock
+    // hours between) when at least two fit, positioned where they fall; the
+    // centred labels are nudged inside the viewBox so an end one isn't clipped.
+    const place = (ticks: TimeAxisTick[]) => ticks.map(({ ts, label }) => {
+      const halfWidth = (labelWidthEm(label) * fontSize) / 2
+      return { ts, x: Math.min(Math.max(toX(ts), halfWidth), width - halfWidth), halfWidth, label, anchor: 'middle' as const }
     })
-  }, [chartData, xIntervals, compact, layout, marginLeft, plotWidth])
+    const separated = (ticks: TimeAxisTick[]) => place(ticks).every((tick, i, all) =>
+      i === 0 || tick.x - tick.halfWidth - (all[i - 1].x + all[i - 1].halfWidth) >= fontSize)
+    const aligned = xIntervals >= 2 ? alignedTimeAxisTicks(minTs, maxTs, xIntervals + 1, separated) : null
+    if (aligned) return place(aligned)
+    // In the compact layout the two labels sit at the plot edges and would
+    // otherwise spill past the viewBox.
+    const edgeAnchored = compact || layout === 'dashboard'
+    const timestamps = Array.from({ length: xIntervals + 1 }, (_, i) => minTs + ((maxTs - minTs) / xIntervals) * i)
+    const labels = formatTimeAxisLabels(timestamps, xLabelMaxWidthEm(plotWidth, xIntervals, fontSize, edgeAnchored))
+    const multiDay = maxTs - minTs > 24 * 60 * 60
+    return timestamps.map((ts, i) => {
+      const anchor: 'start' | 'middle' | 'end' = !edgeAnchored ? 'middle' : i === 0 ? 'start' : i === xIntervals ? 'end' : 'middle'
+      const halfWidth = (labelWidthEm(labels[i]) * fontSize) / 2
+      const x = multiDay && !edgeAnchored ? Math.min(Math.max(toX(ts), halfWidth), width - halfWidth) : toX(ts)
+      return { ts, x, label: labels[i], anchor }
+    })
+  }, [chartData, xIntervals, compact, layout, marginLeft, plotWidth, fontSize, width])
 
   const paths = useMemo(() => {
     if (!chartData) return []
@@ -368,7 +387,7 @@ export function AreaChart({ series, color, fillColor, unit, referenceLines, anno
         ref={svgRef}
         viewBox={`0 0 ${width} ${height}`}
         className="w-full h-full"
-        style={layout === 'dashboard' ? { height: 240 } : undefined}
+        style={layout === 'dashboard' ? { height: dashboardHeight } : undefined}
         preserveAspectRatio="xMidYMid meet"
         data-chart-layout={compact ? 'compact' : 'full'}
       >
@@ -653,7 +672,7 @@ export function AreaChart({ series, color, fillColor, unit, referenceLines, anno
         >
           <div className="bg-theme-surface border border-theme-border rounded-lg shadow-lg px-3 py-2 text-xs whitespace-nowrap">
             <div className="text-theme-text-tertiary mb-1.5 font-mono">
-              {new Date(hoverData.ts * 1000).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' })}
+              {formatFullTimestamp(hoverData.ts, datesNeedYear(chartData.maxTs - chartData.minTs))}
             </div>
             {hoverData.nearbyAnnotations.map((placed, i) => (
               <div key={`annotation-${i}`} className="flex items-center gap-2 py-0.5">

package/src/components/charts/axis.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { chartLayout, integerAxisTop, yAxisValues } from './axis'
+import { chartLayout, integerAxisTop, xLabelMaxWidthEm, yAxisValues } from './axis'
 
 describe('integer axes', () => {
   it('ends a count axis on a whole step that reaches the maximum', () => {
@@ -46,3 +46,19 @@ describe('integer axes', () => {
     expect(chartLayout(false, false, 500)).toEqual(chartLayout(false))
   })
 })
+
+describe('xLabelMaxWidthEm', () => {
+  // "Oct 21 02:48 PM" is 15 characters, 9em.
+  const dateAndTime = 9
+  const room = (layout: ReturnType<typeof chartLayout>, edgeAnchored: boolean) =>
+    xLabelMaxWidthEm(layout.width - layout.marginLeft - layout.marginRight, layout.xIntervals, layout.fontSize, edgeAnchored)
+
+  it('fits a date-and-time label on the full layout and the compact edges', () => {
+    expect(room(chartLayout(false), false)).toBeGreaterThanOrEqual(dateAndTime)
+    expect(room(chartLayout(true), true)).toBeGreaterThanOrEqual(dateAndTime)
+  })
+
+  it('leaves too little room for a date and time with three ticks at 400px', () => {
+    expect(room(chartLayout(false, true, 400), true)).toBeLessThan(dateAndTime)
+  })
+})

package/src/components/charts/axis.ts

@@ -26,6 +26,19 @@ export function chartLayout(compact: boolean, dashboard = false, renderedWidth =
     : { width: 1000, height: 300, marginLeft: 84, marginRight: 40, marginTop: 10, marginBottom: 30, fontSize: 11, yIntervals: 4, xIntervals: 6 }
 }
 
+/**
+ * Widest X label, in ems, that leaves a gap of about two characters between
+ * neighbours. A centred label shares the spacing with half of each neighbour;
+ * an edge-anchored end label sits wholly on its side, so with two ticks both
+ * labels share the plot and with more the end label and half its neighbour
+ * share one spacing.
+ */
+export function xLabelMaxWidthEm(plotWidth: number, intervals: number, fontSize: number, edgeAnchored: boolean): number {
+  const spacing = plotWidth / Math.max(1, intervals) / fontSize
+  const share = !edgeAnchored ? 1 : intervals <= 1 ? 2 : 1.5
+  return (spacing - 1.2) / share
+}
+
 export function isCountUnit(unit: string): boolean {
   return unit === 'count' || unit === 'restarts'
 }

package/src/components/charts/format.test.ts

@@ -1,5 +1,5 @@
-import { describe, expect, it } from 'vitest'
-import { formatMetricValue } from './format'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { alignedTimeAxisTicks, datesNeedYear, formatFullTimestamp, formatMetricValue, formatTimeAxisLabels, formatTimestamp, labelWidthEm } from './format'
 
 describe('formatMetricValue', () => {
   it('scales unitless values with SI prefixes instead of a runaway k', () => {
@@ -17,3 +17,160 @@ describe('formatMetricValue', () => {
     expect(formatMetricValue(-2048, 'bytes')).toBe('-2.0 KiB')
   })
 })
+
+describe('time axis labels', () => {
+  // Day boundaries depend on the local zone; pin one with a DST change. The
+  // expected strings come from the same Intl calls, so any locale passes.
+  let previousTZ: string | undefined
+  beforeAll(() => {
+    previousTZ = process.env.TZ
+    process.env.TZ = 'America/New_York'
+  })
+  afterAll(() => {
+    if (previousTZ === undefined) delete process.env.TZ
+    else process.env.TZ = previousTZ
+  })
+
+  const at = (month: number, day: number, hour: number, minute = 0) => new Date(2026, month - 1, day, hour, minute).getTime() / 1000
+  const day = (unix: number) => new Date(unix * 1000).toLocaleDateString([], { month: 'short', day: 'numeric' })
+  const ticks = (start: number, end: number, intervals: number) =>
+    Array.from({ length: intervals + 1 }, (_, i) => start + ((end - start) / intervals) * i)
+
+  describe('formatTimeAxisLabels (evenly spaced ticks)', () => {
+    it('keeps time-only labels for a window of a day or less, even across midnight', () => {
+      const sameDay = ticks(at(10, 21, 8), at(10, 21, 14), 6)
+      expect(formatTimeAxisLabels(sameDay)).toEqual(sameDay.map(formatTimestamp))
+      const overMidnight = ticks(at(10, 21, 20), at(10, 22, 2), 6)
+      expect(formatTimeAxisLabels(overMidnight)).toEqual(overMidnight.map(formatTimestamp))
+      const fullDay = ticks(at(10, 21, 14, 48), at(10, 22, 14, 48), 6)
+      expect(formatTimeAxisLabels(fullDay, 1)).toEqual(fullDay.map(formatTimestamp))
+    })
+
+    it('names the day where a new one starts and the time elsewhere', () => {
+      const twoDays = ticks(at(10, 21, 14, 48), at(10, 23, 14, 48), 6)
+      const labels = formatTimeAxisLabels(twoDays)
+      expect(labels[0]).toBe(`${day(twoDays[0])} ${formatTimestamp(twoDays[0])}`)
+      expect(labels[1]).toBe(formatTimestamp(twoDays[1]))
+      expect(labels[2]).toBe(`${day(twoDays[2])} ${formatTimestamp(twoDays[2])}`)
+      expect(labels.filter((label) => label.includes(day(twoDays[0])))).toHaveLength(1)
+    })
+
+    it('keeps the time on two end ticks just over a day apart', () => {
+      const edges = [at(10, 21, 14, 48), at(10, 22, 14, 49)]
+      expect(formatTimeAxisLabels(edges)).toEqual(edges.map((ts) => `${day(ts)} ${formatTimestamp(ts)}`))
+    })
+
+    it('falls back to the day at day starts when date and time would not fit', () => {
+      const twoDays = ticks(at(10, 21, 14, 48), at(10, 23, 14, 48), 4)
+      expect(formatTimeAxisLabels(twoDays, 5)).toEqual([day(twoDays[0]), day(twoDays[1]), '', day(twoDays[3]), ''])
+    })
+
+    it('never repeats a bare day across a DST fall-back', () => {
+      // 24h steps from 00:30 land on 23:30 after clocks go back on Nov 1.
+      const window = ticks(at(10, 31, 0, 30), at(10, 31, 0, 30) + 3 * 86_400, 3)
+      expect(formatTimeAxisLabels(window)).toEqual([
+        `${day(window[0])} ${formatTimestamp(window[0])}`,
+        `${day(window[1])} ${formatTimestamp(window[1])}`,
+        formatTimestamp(window[2]),
+        `${day(window[3])} ${formatTimestamp(window[3])}`,
+      ])
+      expect(day(window[1])).toBe(day(window[2]))
+    })
+  })
+
+  describe('alignedTimeAxisTicks', () => {
+    const local = (ts: number) => {
+      const d = new Date(ts * 1000)
+      return [d.getMonth() + 1, d.getDate(), d.getHours(), d.getMinutes()]
+    }
+
+    it('leaves a window of a day or less to evenly spaced ticks', () => {
+      expect(alignedTimeAxisTicks(at(10, 21, 14, 48), at(10, 22, 14, 48), 7)).toBeNull()
+    })
+
+    it('puts a 7-day window on consecutive local midnights, labelled with the day', () => {
+      const result = alignedTimeAxisTicks(at(10, 21, 2, 48), at(10, 28, 2, 48), 7)!
+      expect(result.map(({ ts }) => local(ts))).toEqual([22, 23, 24, 25, 26, 27, 28].map((d) => [10, d, 0, 0]))
+      expect(result.map(({ label }) => label)).toEqual(result.map(({ ts }) => day(ts)))
+    })
+
+    it('steps by whole days when daily ticks would not fit, and keeps them as the window slides', () => {
+      const eleven = alignedTimeAxisTicks(at(10, 17, 1, 48), at(10, 28, 1, 48), 7)!
+      expect(eleven.length).toBeLessThanOrEqual(7)
+      expect(eleven.every(({ ts }) => local(ts)[2] === 0 && local(ts)[3] === 0)).toBe(true)
+      const slid = alignedTimeAxisTicks(at(10, 17, 7, 48), at(10, 28, 7, 48), 7)!
+      const shared = (list: { ts: number }[]) => list.map(({ ts }) => ts).filter((ts) => ts >= at(10, 17, 7, 48) && ts <= at(10, 28, 1, 48))
+      expect(shared(slid)).toEqual(shared(eleven))
+    })
+
+    it('adds clock-hour ticks with time labels on a short multi-day window', () => {
+      const result = alignedTimeAxisTicks(at(10, 21, 14, 48), at(10, 23, 2, 48), 7)!
+      expect(result.map(({ ts }) => local(ts))).toEqual([
+        [10, 21, 18, 0],
+        [10, 22, 0, 0],
+        [10, 22, 6, 0],
+        [10, 22, 12, 0],
+        [10, 22, 18, 0],
+        [10, 23, 0, 0],
+      ])
+      expect(result.map(({ label }) => label)).toEqual([
+        formatTimestamp(result[0].ts),
+        day(result[1].ts),
+        formatTimestamp(result[2].ts),
+        formatTimestamp(result[3].ts),
+        formatTimestamp(result[4].ts),
+        day(result[5].ts),
+      ])
+    })
+
+    it('keeps local midnights across a DST change', () => {
+      const result = alignedTimeAxisTicks(at(10, 30, 12), at(11, 3, 12), 7)!
+      expect(result.map(({ ts }) => local(ts))).toEqual([31, 1, 2, 3].map((d, i) => [i === 0 ? 10 : 11, d, 0, 0]))
+      expect(result[2].ts - result[1].ts).toBe(25 * 3600)
+    })
+
+    it('keeps later midnights where DST skips one', () => {
+      // Chile springs forward at midnight on Sep 6 2026; that day starts at 01:00.
+      process.env.TZ = 'America/Santiago'
+      try {
+        const result = alignedTimeAxisTicks(at(9, 4, 12), at(9, 11, 0, 30), 7)!
+        expect(result.map(({ ts }) => local(ts))).toEqual([
+          [9, 5, 0, 0], [9, 6, 1, 0], [9, 7, 0, 0], [9, 8, 0, 0], [9, 9, 0, 0], [9, 10, 0, 0], [9, 11, 0, 0],
+        ])
+        expect(result[1].label).toBe(day(result[1].ts))
+      } finally {
+        process.env.TZ = 'America/New_York'
+      }
+    })
+
+    it('takes a coarser step when the caller says labels collide, and gives up below two ticks', () => {
+      const daily = alignedTimeAxisTicks(at(10, 21, 2, 48), at(10, 28, 2, 48), 7, (ticks) => ticks.length <= 4)!
+      expect(daily.length).toBeLessThanOrEqual(4)
+      expect(alignedTimeAxisTicks(at(10, 21, 2, 48), at(10, 28, 2, 48), 7, () => false)).toBeNull()
+      expect(alignedTimeAxisTicks(at(10, 21, 2, 48), at(10, 22, 12), 1)).toBeNull()
+    })
+  })
+
+  it('names the year on axes and tooltips spanning most of a year or more', () => {
+    const twoYears = ticks(at(10, 21, 12), at(10, 21, 12) + 730 * 86_400, 6)
+    const withYear = (ts: number) => new Date(ts * 1000).toLocaleDateString([], { year: 'numeric', month: 'short', day: 'numeric' })
+    expect(formatTimeAxisLabels(twoYears, 6)).toEqual(twoYears.map(withYear))
+    expect(new Set(formatTimeAxisLabels(twoYears, 6)).size).toBe(twoYears.length)
+    expect(datesNeedYear(730 * 86_400)).toBe(true)
+    expect(datesNeedYear(30 * 86_400)).toBe(false)
+    expect(formatFullTimestamp(twoYears[0], true)).toContain(String(new Date(twoYears[0] * 1000).toLocaleDateString([], { year: 'numeric' })))
+    expect(formatTimeAxisLabels(ticks(at(10, 21, 2, 48), at(10, 28, 2, 48), 6), 6).some((label) => label.includes('2026'))).toBe(false)
+  })
+
+  it('estimates wide characters at a full em', () => {
+    expect(labelWidthEm('Oct 21')).toBeCloseTo(3.6)
+    expect(labelWidthEm('10月21日')).toBeCloseTo(4 * 0.6 + 2 * 1)
+  })
+
+  it('formats tooltips with the full date and time', () => {
+    const ts = at(10, 21, 14, 5)
+    const label = formatFullTimestamp(ts)
+    expect(label).toContain(day(ts))
+    expect(label).toContain(new Date(ts * 1000).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', second: '2-digit' }))
+  })
+})

package/src/components/charts/format.ts

@@ -59,3 +59,121 @@ export function formatTimestamp(unix: number): string {
   const d = new Date(unix * 1000)
   return d.toLocaleTimeString([], { hour: '2-digit', minute: '2-digit' })
 }
+
+const DAY_SECONDS = 24 * 60 * 60
+
+// Past this span two instants can share a month and day, so dates name the year.
+const YEAR_SPAN_SECONDS = 300 * DAY_SECONDS
+
+/** Whether dates on a chart spanning this many seconds should name the year. */
+export function datesNeedYear(spanSeconds: number): boolean {
+  return spanSeconds > YEAR_SPAN_SECONDS
+}
+
+function formatDay(unix: number, withYear = false): string {
+  return new Date(unix * 1000).toLocaleDateString([], { ...(withYear && { year: 'numeric' }), month: 'short', day: 'numeric' })
+}
+
+/** Full local date and time of one instant, for tooltips; `withYear` for charts spanning most of a year or more. */
+export function formatFullTimestamp(unix: number, withYear = false): string {
+  return new Date(unix * 1000).toLocaleString([], {
+    ...(withYear && { year: 'numeric' }),
+    month: 'short',
+    day: 'numeric',
+    hour: '2-digit',
+    minute: '2-digit',
+    second: '2-digit',
+  })
+}
+
+/**
+ * Labels for evenly spaced time-axis ticks given in ascending unix seconds.
+ * A span of a day or less shows the time only (`formatTimestamp`). A longer
+ * span names the day (and the year past about ten months): a tick that starts a new local day
+ * reads "Oct 21 02:00 PM" and the rest show the time; when that is wider than
+ * `maxWidth` (in ems, see `labelWidthEm`), ticks that start a day show the day
+ * alone and the rest stay blank, so neighbouring labels never collide.
+ */
+export function formatTimeAxisLabels(ticks: number[], maxWidth = Infinity): string[] {
+  if (ticks.length === 0) return []
+  const span = ticks[ticks.length - 1] - ticks[0]
+  if (span <= DAY_SECONDS) return ticks.map(formatTimestamp)
+
+  const withYear = datesNeedYear(span)
+  const days = ticks.map((ts) => formatDay(ts, withYear))
+  const startsDay = days.map((day, i) => i === 0 || day !== days[i - 1])
+  const mixed = ticks.map((ts, i) => (startsDay[i] ? `${days[i]} ${formatTimestamp(ts)}` : formatTimestamp(ts)))
+  if (Math.max(...mixed.map(labelWidthEm)) <= maxWidth) return mixed
+  return days.map((day, i) => (startsDay[i] ? day : ''))
+}
+
+/**
+ * Estimated rendered width of a monospace label in ems: about 0.6em per
+ * character, a full em for wide (CJK, fullwidth) characters.
+ */
+export function labelWidthEm(label: string): number {
+  let width = 0
+  for (const ch of label) width += /[\u1100-\u115F\u2E80-\uA4CF\uAC00-\uD7A3\uF900-\uFAFF\uFE30-\uFE4F\uFF00-\uFF60\uFFE0-\uFFE6]/.test(ch) ? 1 : 0.6
+  return width
+}
+
+export interface TimeAxisTick {
+  ts: number
+  label: string
+}
+
+const HOUR_SECONDS = 60 * 60
+// Sub-day steps align to local clock hours; day steps to local midnights.
+const ALIGNED_STEPS_HOURS = [6, 12, 24, 48, 72, 168, 336, 672]
+
+/**
+ * Calendar-aligned ticks for a window longer than a day: local midnights
+ * labelled with the day ("Oct 21"), and, when the window is short enough for
+ * 6- or 12-hour steps, the hours between labelled with the time. Uses the
+ * smallest step that keeps the tick count within `maxTicks` and passes `fits`
+ * (the caller's check that neighbouring labels don't collide). Returns null
+ * for a window of a day or less, or when fewer than two ticks would fit, so
+ * the caller keeps evenly spaced ticks.
+ */
+export function alignedTimeAxisTicks(
+  minTs: number,
+  maxTs: number,
+  maxTicks: number,
+  fits: (ticks: TimeAxisTick[]) => boolean = () => true,
+): TimeAxisTick[] | null {
+  if (maxTs - minTs <= DAY_SECONDS || maxTicks < 2) return null
+  for (const stepHours of ALIGNED_STEPS_HOURS) {
+    if ((maxTs - minTs) / HOUR_SECONDS / stepHours > maxTicks + 1) continue
+    const ticks = alignedTicks(minTs, maxTs, stepHours)
+    if (ticks.length > maxTicks) continue
+    if (ticks.length < 2) return null
+    const labelled = ticks.map(({ ts, startsDay }) => ({ ts, label: startsDay ? formatDay(ts) : formatTimestamp(ts) }))
+    if (fits(labelled)) return labelled
+  }
+  return null
+}
+
+function alignedTicks(minTs: number, maxTs: number, stepHours: number): { ts: number; startsDay: boolean }[] {
+  const out: { ts: number; startsDay: boolean }[] = []
+  const start = new Date(minTs * 1000)
+  const stepDays = stepHours / 24
+  // Each day's start is built from its date: where a DST change skips
+  // midnight the Date lands on 01:00, and stepping with setDate would carry
+  // that hour into every later day.
+  for (let offset = 0; ; offset++) {
+    const cursor = new Date(start.getFullYear(), start.getMonth(), start.getDate() + offset)
+    if (cursor.getTime() / 1000 > maxTs) break
+    if (stepHours < 24) {
+      for (let hour = 0; hour < 24; hour += stepHours) {
+        const ts = new Date(cursor.getFullYear(), cursor.getMonth(), cursor.getDate(), hour).getTime() / 1000
+        if (ts >= minTs && ts <= maxTs) out.push({ ts, startsDay: hour === 0 })
+      }
+    } else {
+      // Index days by calendar date so the chosen midnights stay put as the window slides.
+      const dayIndex = Math.round(Date.UTC(cursor.getFullYear(), cursor.getMonth(), cursor.getDate()) / (DAY_SECONDS * 1000))
+      const ts = cursor.getTime() / 1000
+      if (dayIndex % stepDays === 0 && ts >= minTs) out.push({ ts, startsDay: true })
+    }
+  }
+  return out
+}

package/src/components/gitops/insights/ArgoResourceDiff.test.tsx

@@ -113,6 +113,38 @@ describe('GitOpsChangesView expanded Argo row', () => {
     expect(html).not.toContain('Sync the application to create it')
   })
 
+  test.each([
+    ['ManualDrift', 'The render includes none of the resources this Application manages.', 'Manual'],
+    ['AutoSyncBlockedEmpty', 'A pruning sync could delete every listed resource.', 'Auto · prune'],
+    ['SharedResourceWarning', 'Resolve shared ownership before syncing.', 'Manual'],
+    ['SelfHealDisabled', 'Resolve shared ownership before syncing.', 'Auto'],
+    ['Failed', 'Fix the comparison error and refresh before syncing.', 'Manual'],
+  ])('defers resource sync/create advice to the %s hazard', (reason, hazard, autoSyncMode) => {
+    const data = insight(false)
+    data.summary.autoSyncMode = autoSyncMode
+    data.issues = [{ severity: 'warning', scope: 'operation', reason, message: 'Sync warning', hazard }]
+    data.changes = [
+      { ...change, drift: undefined },
+      { ...change, ref: { ...change.ref, name: 'missing' }, missing: true, hasLive: false, health: 'Missing', drift: undefined },
+      { ...change, ref: { ...change.ref, name: 'health-missing' }, sync: 'Unknown', health: 'Missing', drift: undefined },
+    ]
+    const html = renderToStaticMarkup(<GitOpsChangesView insight={data} />)
+    expect(count(html, 'See the sync warning above before syncing this Application.')).toBe(3)
+    expect(html).not.toContain('Click Sync')
+    expect(html).not.toContain('click Sync to force it')
+    expect(html).not.toContain('Auto-sync should reconcile')
+    expect(html).not.toContain('Sync the application to create it')
+    expect(html).not.toContain('Sync to create it')
+  })
+
+  test('keeps ordinary sync advice when there is no hazard', () => {
+    const data = insight(false)
+    data.summary.autoSyncMode = 'Manual'
+    const html = renderToStaticMarkup(<GitOpsChangesView insight={data} />)
+    expect(html).toContain('Click Sync to apply the desired state.')
+    expect(html).not.toContain('See the sync warning above')
+  })
+
   test("hands the last-applied list to the Argo diff instead of rendering it alongside", () => {
     let passed: GitOpsDrift | undefined
     const html = renderToStaticMarkup(

package/src/components/gitops/insights/GitOpsInsightViews.tsx

@@ -1,4 +1,5 @@
 import { AlertTriangle, ArrowUpDown, ChevronDown, ChevronRight, ChevronUp, CircleAlert, Clock3, GitBranch, GitCommit, Info, Loader2, Plus, RefreshCw, Trash2 } from 'lucide-react'
+import { IssueGuidance } from '../../issues/IssueGuidance'
 import { PaneLoader } from '../../ui/PaneLoader'
 import { clsx } from 'clsx'
 import { Fragment, useEffect, useRef, useState, type ReactNode } from 'react'
@@ -359,7 +360,7 @@ export function GitOpsIssuesBand({
         <GitOpsHistoricalIssuesDisclosure operationFailure={operationFailure} others={others} onSelectIssue={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />
       ) : (
         <>
-          {operationFailure && <GitOpsFailureCard issue={operationFailure} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
+          {operationFailure && <GitOpsFailureCard issue={operationFailure} emptyRenderGuardShown={others[0]?.reason === 'AutoSyncBlockedEmpty'} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
           {others.length > 0 && <GitOpsCompactIssueStack issues={others} onSelectIssue={onSelectIssue} />}
         </>
       )}
@@ -383,7 +384,7 @@ function GitOpsLifecycleBanner({ issue }: { issue: GitOpsIssue }) {
           </div>
           <p className="mt-1 text-[13px] text-theme-text-secondary">{issue.message}</p>
           {issue.cause && <p className="mt-1 text-[12px] text-orange-300/90">{issue.cause}</p>}
-          {issue.action && <p className="mt-1 text-[11px] text-theme-text-tertiary">{issue.action}</p>}
+          <IssueNextStep issue={issue} className="mt-1" />
         </div>
       </div>
     </div>
@@ -431,7 +432,7 @@ function GitOpsHistoricalIssuesDisclosure({
       </button>
       <Collapse open={expanded}>
         <div className="border-t border-theme-border">
-          {operationFailure && <GitOpsFailureCard issue={operationFailure} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
+          {operationFailure && <GitOpsFailureCard issue={operationFailure} emptyRenderGuardShown={others[0]?.reason === 'AutoSyncBlockedEmpty'} onSelect={onSelectIssue} onRemediate={onRemediate} remediationPending={remediationPending} />}
           {others.length > 0 && <GitOpsCompactIssueStack issues={others} onSelectIssue={onSelectIssue} />}
         </div>
       </Collapse>
@@ -440,15 +441,18 @@ function GitOpsHistoricalIssuesDisclosure({
 }
 
 // Structured failure card. One unit, owns the failure narrative end-to-end:
-// title (parsed cause when recognized, falls back to raw reason), affected
-// resource, retry posture, raw controller error in a collapsed details.
+// title (parsed cause when recognized, falls back to raw reason), sync
+// hazard, cause, next step, affected resource, retry posture, raw controller
+// error in a collapsed details.
 function GitOpsFailureCard({
   issue,
+  emptyRenderGuardShown,
   onSelect,
   onRemediate,
   remediationPending,
 }: {
   issue: GitOpsIssue
+  emptyRenderGuardShown: boolean
   onSelect?: (issue: GitOpsIssue) => void
   // onRemediate fires when the contextual fix button is clicked. The host
   // app (web/) dispatches on issue.remediation.kind to run the right
@@ -492,7 +496,16 @@ function GitOpsFailureCard({
               <span className="text-[11px] text-theme-text-tertiary">retried {issue.retryCount}×</span>
             )}
           </div>
+          {/* Ahead of the body: a cause can end in its own sync advice
+              ("so Argo creates it on sync"), which the hazard overrides. */}
+          {issue.hazard && (
+            <div className={clsx('mt-2 flex items-start gap-1.5 rounded border px-2 py-1.5 text-[12px] font-medium', SEVERITY_BADGE.warning)}>
+              <AlertTriangle className="mt-0.5 h-3.5 w-3.5 shrink-0" />
+              <p className="min-w-0">{emptyRenderGuardShown ? 'See the empty-render guard below before syncing.' : issue.hazard}</p>
+            </div>
+          )}
           {body && <p className="mt-1 text-[13px] text-theme-text-secondary">{body}</p>}
+          <IssueNextStep issue={issue} className="mt-1" />
           {ref && (
             <dl className="mt-2 flex flex-wrap gap-x-5 gap-y-1 text-[12px]">
               <div className="flex gap-1.5">
@@ -637,10 +650,13 @@ function GitOpsCompactIssueStack({ issues, onSelectIssue }: { issues: GitOpsIssu
           )}
           {canExpand && <CollapseChevron open={expanded} className="h-3.5 w-3.5" />}
         </div>
-        {headline.cause && (
-          <p className="truncate pl-[22px] text-[11px] text-theme-text-tertiary">{headline.cause}</p>
-        )}
       </button>
+      {(headline.cause || headline.action) && (
+        <div className="px-4 pb-2 pl-[38px]">
+          {headline.cause && <p className="text-[11px] text-theme-text-tertiary">{headline.cause}</p>}
+          <IssueNextStep issue={headline} />
+        </div>
+      )}
       {canExpand && (
         <Collapse open={expanded}>
         <div className="divide-y divide-theme-border border-t border-theme-border bg-theme-base/40">
@@ -650,33 +666,34 @@ function GitOpsCompactIssueStack({ issues, onSelectIssue }: { issues: GitOpsIssu
             const actionable = !!(onSelectIssue && ref)
             const rawMessage = issue.rawMessage && issue.rawMessage !== issue.message ? issue.rawMessage : ''
             return (
-              <button
-                key={`${issue.reason}-${index}`}
-                type="button"
-                onClick={() => actionable && onSelectIssue?.(issue)}
-                disabled={!actionable}
-                className={clsx(
-                  'group flex w-full items-start gap-2 px-4 py-2 text-left text-xs transition-colors',
-                  actionable ? 'hover:bg-theme-hover/50' : 'cursor-default',
-                )}
-              >
-                {t.icon}
-                <div className="min-w-0 flex-1">
-                  <div className="flex items-center gap-2">
-                    <span className={clsx('font-semibold', t.text)}>{issue.reason}</span>
-                    <span className="text-[10px] uppercase tracking-wide text-theme-text-tertiary">{issue.scope}</span>
+              <div key={`${issue.reason}-${index}`}>
+                <button
+                  type="button"
+                  onClick={() => actionable && onSelectIssue?.(issue)}
+                  disabled={!actionable}
+                  className={clsx(
+                    'group flex w-full items-start gap-2 px-4 py-2 text-left text-xs transition-colors',
+                    actionable ? 'hover:bg-theme-hover/50' : 'cursor-default',
+                  )}
+                >
+                  {t.icon}
+                  <div className="min-w-0 flex-1">
+                    <div className="flex items-center gap-2">
+                      <span className={clsx('font-semibold', t.text)}>{issue.reason}</span>
+                      <span className="text-[10px] uppercase tracking-wide text-theme-text-tertiary">{issue.scope}</span>
+                    </div>
+                    <p className="mt-0.5 text-theme-text-secondary">{issue.message}</p>
+                    {issue.cause && <p className="mt-0.5 text-[11px] text-theme-text-tertiary">{issue.cause}</p>}
+                    {rawMessage && <p className="mt-0.5 break-words font-mono text-[11px] text-theme-text-tertiary">{rawMessage}</p>}
                   </div>
-                  <p className="mt-0.5 text-theme-text-secondary">{issue.message}</p>
-                  {issue.cause && <p className="mt-0.5 text-[11px] text-theme-text-tertiary">{issue.cause}</p>}
-                  {rawMessage && <p className="mt-0.5 break-words font-mono text-[11px] text-theme-text-tertiary">{rawMessage}</p>}
-                  {issue.action && <p className="mt-0.5 text-[11px] text-theme-text-tertiary">{issue.action}</p>}
-                </div>
-                {actionable && ref && (
-                  <span className="shrink-0 self-center text-[11px] font-medium text-theme-text-secondary opacity-70 transition-opacity group-hover:opacity-100">
-                    Open {refText(ref)} →
-                  </span>
-                )}
-              </button>
+                  {actionable && ref && (
+                    <span className="shrink-0 self-center text-[11px] font-medium text-theme-text-secondary opacity-70 transition-opacity group-hover:opacity-100">
+                      Open {refText(ref)} →
+                    </span>
+                  )}
+                </button>
+                <IssueNextStep issue={issue} className="px-4 pb-2 pl-[38px]" />
+              </div>
             )
           })}
         </div>
@@ -686,6 +703,13 @@ function GitOpsCompactIssueStack({ issues, onSelectIssue }: { issues: GitOpsIssu
   )
 }
 
+// IssueNextStep is an issue's next step, styled alike on every surface of the
+// band. Wrapped, never truncated: a next step often ends in the caveat that
+// makes it safe (what not to sync), which truncation would cut.
+function IssueNextStep({ issue, className }: { issue: GitOpsIssue; className?: string }) {
+  return <IssueGuidance action={issue.action} primary={issue.actionPrimary} secondaryTitle={issue.actionSecondaryTitle} secondary={issue.actionSecondary} ordered={issue.reason === 'SharedResourceWarning'} className={clsx('text-[11px] text-theme-text-tertiary', className)} />
+}
+
 // firstSentence/remainderAfterFirstSentence split a string at the first
 // sentence boundary so the failure card can render "headline + body" from a
 // single source string. Falls back to the whole string when there's no
@@ -865,6 +889,7 @@ export function GitOpsChangesView({ insight, error, onOpenResource, onSyncResour
   // honest about what it's NOT checking. Neutral note, not an alarm.
   const ignoredDiffs = insight.summary.ignoredDifferences
   const isArgoRoot = insight.summary.tool === 'argocd' && insight.summary.kind === 'Application'
+  const syncHazard = insight.issues?.find((issue) => issue.hazard)?.hazard
   // Full-diff affordance is offered only when the backend reports the Argo CD
   // integration is connected for this app AND the host wired the loader.
   const argoDiffAvailable = isArgoRoot && !!insight.capabilities?.argoDiffAvailable && !!renderResourceDiff
@@ -1098,9 +1123,9 @@ export function GitOpsChangesView({ insight, error, onOpenResource, onSyncResour
                 const rowKey = refKey(change.ref)
                 const focused = focusKey === rowKey
                 const explanation = change.missing
-                  ? missingResourceMessage(change.sync)
+                  ? missingResourceMessage(change.sync, { hazard: syncHazard })
                   : !change.syncError && !change.message
-                    ? explainChangeStatus(change.sync, change.health, insight.summary)
+                    ? explainChangeStatus(change.sync, change.health, insight.summary, { hazard: syncHazard })
                     : ''
                 const hasInlineDetail = !!(
                   (change.drift && change.drift.entries.length > 0) ||
@@ -1275,7 +1300,12 @@ function explainChangeStatus(
   sync: string | undefined,
   health: string | undefined,
   summary: GitOpsInsight['summary'],
+  context?: { hazard?: string; rolledBack?: boolean },
 ): string {
+  if (context?.hazard && (sync === 'OutOfSync' || health === 'Missing')) {
+    return 'See the sync warning above before syncing this Application.'
+  }
+  if (context?.rolledBack && health === 'Missing') return missingResourceMessage(sync, context)
   const isAuto = (summary.autoSyncMode ?? '').toLowerCase().startsWith('auto')
   const phase = (summary.operationPhase ?? '').toLowerCase()
   const inFlight = phase === 'running'

package/src/components/gitops/insights/GitOpsIssuesBand.test.tsx

@@ -0,0 +1,108 @@
+import { describe, expect, it } from 'vitest'
+import { renderToString } from 'react-dom/server'
+import { GitOpsIssuesBand } from './GitOpsInsightViews'
+import type { GitOpsIssue } from '../../../types/gitops-insights'
+import { SEVERITY_BADGE } from '../../../utils/badge-colors'
+
+const guard: GitOpsIssue = {
+  severity: 'critical',
+  scope: 'condition',
+  reason: 'AutoSyncBlockedEmpty',
+  message: 'Auto-sync blocked: the render includes none of the managed resources',
+  rawMessage: 'Skipping sync attempt to [8088f4c]: auto-sync will wipe out all resources',
+  cause: 'Argo CD blocked auto-sync because the render includes none of the resources this Application manages.',
+  action: 'The render includes none of the resources this Application manages. A sync with Prune enabled could delete all of them. Prune=false blocks direct Argo pruning; Prune=confirm requires confirmation. Pruning a rendered Namespace deletes its contents, regardless of their Prune options.',
+}
+
+// The band's top row is the most severe issue. Its next step must be visible
+// without expanding, or a lower row's "click Sync" is the only advice on screen.
+describe('GitOpsIssuesBand headline', () => {
+  it('shows the top issue’s next step when it stands alone', () => {
+    const html = renderToString(<GitOpsIssuesBand issues={[guard]} />)
+    expect(html).toContain(guard.action)
+  })
+
+  it('shows the top issue’s next step above a collapsed stack', () => {
+    const drift: GitOpsIssue = {
+      severity: 'warning',
+      scope: 'operation',
+      reason: 'OutOfSync',
+      message: 'Application is OutOfSync.',
+      action: 'Review the drift.',
+    }
+    const html = renderToString(<GitOpsIssuesBand issues={[guard, drift]} />)
+    expect(html).toContain(guard.action)
+    expect(html.indexOf(guard.action!)).toBeLessThan(html.indexOf(drift.action!))
+  })
+
+  it('renders no next-step line when the top issue has none', () => {
+    const html = renderToString(
+      <GitOpsIssuesBand issues={[{ severity: 'warning', scope: 'condition', reason: 'X', message: 'only a message' }]} />,
+    )
+    expect(html).toContain('only a message')
+    expect(html.match(/pl-\[22px\]/g)).toBeNull()
+  })
+})
+
+// Argo's namespace-not-found cause ends in its own sync advice.
+const failedSync: GitOpsIssue = {
+  severity: 'critical',
+  scope: 'operation',
+  reason: 'Failed',
+  message: 'one or more objects failed to apply, reason: namespaces demo not found',
+  cause: 'The destination namespace does not exist. Create it, or enable CreateNamespace=true in the syncOptions so Argo creates it on sync.',
+  action: 'Open Activity for operation details.',
+}
+const causeAdvice = 'so Argo creates it on sync'
+const emptyRenderHazard = 'The render includes none of the resources this Application manages. A sync with Prune enabled could delete all of them. Prune=false blocks direct Argo pruning; Prune=confirm requires confirmation. Pruning a rendered Namespace deletes its contents, regardless of their Prune options. Check the source path, targetRevision, Helm values, and Kustomize or directory include/exclude settings first.'
+const emptyRenderReference = 'See the empty-render guard below before syncing.'
+
+describe('GitOpsIssuesBand failure card', () => {
+  it('shows the failure’s next step after its cause', () => {
+    const html = renderToString(<GitOpsIssuesBand issues={[failedSync]} />)
+    expect(html).toContain(failedSync.action)
+    expect(html.indexOf(causeAdvice)).toBeLessThan(html.indexOf(failedSync.action!))
+    expect(html).not.toContain(SEVERITY_BADGE.warning)
+  })
+
+  it('warns of a sync hazard before the cause’s own sync advice', () => {
+    const hazard = emptyRenderHazard
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard }]} />)
+    const at = html.indexOf(hazard)
+    expect(at).toBeGreaterThan(-1)
+    expect(at).toBeLessThan(html.indexOf(causeAdvice))
+    expect(html.lastIndexOf(SEVERITY_BADGE.warning, at)).toBeGreaterThan(-1)
+    expect(html).toContain(failedSync.action)
+    expect(html).not.toContain(emptyRenderReference)
+  })
+
+  it.each([false, true])('points to the empty-render guard in the issue band (terminating=%s)', (terminating) => {
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard: emptyRenderHazard }, guard]} terminating={terminating} />)
+    expect(html).toContain(emptyRenderReference)
+    expect(html).not.toContain(emptyRenderHazard)
+    expect(html).toContain(guard.message)
+    expect(html).toContain(guard.action)
+    expect(html.indexOf(emptyRenderReference)).toBeLessThan(html.indexOf(causeAdvice))
+  })
+
+  it('keeps the full hazard when the guard is behind a collapsed row', () => {
+    const comparisonError: GitOpsIssue = { severity: 'critical', scope: 'condition', reason: 'ComparisonError', message: 'Cannot render source.' }
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard: emptyRenderHazard }, comparisonError, guard]} />)
+    expect(html).toContain(emptyRenderHazard)
+    expect(html).not.toContain(emptyRenderReference)
+  })
+
+  it('keeps shared-ownership hazards unchanged', () => {
+    const hazard = 'Resolve shared ownership before syncing: some resources are also tracked by Application payments. A successful sync can take over their tracking unless it uses FailOnSharedResource=true. While Application payments still declares them, its next successful sync can take tracking back.'
+    const shared: GitOpsIssue = { severity: 'warning', scope: 'condition', reason: 'SharedResourceWarning', message: 'Shared resource' }
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, hazard }, shared]} />)
+    expect(html).toContain(hazard)
+    expect(html).not.toContain(emptyRenderReference)
+  })
+
+  it('shows a remote failure’s destination-cluster instruction', () => {
+    const action = 'Create namespace demo on the destination cluster, or add the CreateNamespace=true sync option.'
+    const html = renderToString(<GitOpsIssuesBand issues={[{ ...failedSync, action }]} />)
+    expect(html).toContain(action)
+  })
+})

package/src/components/gitops/insights/insights-helpers.test.ts

@@ -30,6 +30,34 @@ describe('confirmed missing resources', () => {
     expect(isArgoResourceSyncEligible(item, true)).toBe(true)
   })
 
+  it('defers creation advice to the sync hazard while preserving stale Synced refresh advice', () => {
+    for (const sync of ['OutOfSync', 'Unknown', undefined]) {
+      expect(missingResourceMessage(sync, { hazard: 'Resolve shared ownership before syncing.' })).toBe(
+        'Not present in the cluster. See the sync warning above before syncing this Application.',
+      )
+    }
+    expect(missingResourceMessage('Synced', { hazard: 'A pruning sync could delete everything.' })).toContain('Refresh')
+  })
+
+  it('warns that recreating a missing resource can undo a rollback', () => {
+    for (const sync of ['OutOfSync', 'Unknown', undefined]) {
+      expect(missingResourceMessage(sync, { rolledBack: true })).toBe(
+        'Declared in Git but not present in the cluster after a rollback. Sync can recreate it and undo the rollback.',
+      )
+    }
+  })
+
+  it('prioritizes the sync hazard over rollback advice', () => {
+    for (const sync of ['OutOfSync', 'Unknown', undefined]) {
+      expect(missingResourceMessage(sync, { hazard: 'Resolve shared tracking.', rolledBack: true })).toBe(
+        'Not present in the cluster. See the sync warning above before syncing this Application.',
+      )
+    }
+    // Argo calling it Synced means the cluster view is stale: refresh, whatever the context.
+    expect(missingResourceMessage('Synced', { hazard: 'Resolve shared tracking.', rolledBack: true })).toContain('Refresh the application')
+    expect(missingResourceMessage('OutOfSync', {})).toContain('Sync the application')
+  })
+
   it('asks for a refresh when Argo still reports Synced', () => {
     expect(missingResourceMessage('Synced')).toContain('Refresh')
     expect(missingResourceMessage('Synced')).not.toContain('Sync the application')

package/src/components/gitops/insights/insights-helpers.ts

@@ -47,9 +47,11 @@ export function changeHealth(change: GitOpsChange): GitOpsHealthStatus {
   return normalizeHealthStatus(change.health)
 }
 
-export function missingResourceMessage(sync?: string): string {
-  return sync === 'Synced'
-    ? 'Argo reports this resource as synced, but it is not present in the cluster. Refresh the application to check its status.'
+export function missingResourceMessage(sync?: string, context?: { hazard?: string; rolledBack?: boolean }): string {
+  if (sync === 'Synced') return 'Argo reports this resource as synced, but it is not present in the cluster. Refresh the application to check its status.'
+  if (context?.hazard) return 'Not present in the cluster. See the sync warning above before syncing this Application.'
+  return context?.rolledBack
+    ? 'Declared in Git but not present in the cluster after a rollback. Sync can recreate it and undo the rollback.'
     : 'Not present in the cluster. Sync the application to create it.'
 }
 

package/src/components/issues/IssueGuidance.test.tsx

@@ -0,0 +1,190 @@
+// @vitest-environment jsdom
+import { act } from 'react'
+import { createRoot, type Root } from 'react-dom/client'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { GitOpsIssuesBand } from '../gitops/insights/GitOpsInsightViews'
+import { IssueRow } from './IssuesView'
+import { ResourceIssuesSection } from './ResourceIssuesSection'
+import type { GitOpsIssue } from '../../types/gitops-insights'
+import type { Issue } from './types'
+
+Object.assign(globalThis, { IS_REACT_ACT_ENVIRONMENT: true })
+
+const primary = 'The render includes none of the resources this Application manages. A sync with Prune enabled could delete all of them. Prune=false blocks direct Argo pruning; Prune=confirm requires confirmation. Pruning a rendered Namespace deletes its contents, regardless of their Prune options. Check the source path, targetRevision, Helm values, and Kustomize or directory include/exclude settings first.'
+const secondary = [
+  'If this Application should go away: remove it from the ApplicationSet generator if generated; while the generator still emits it, the ApplicationSet recreates it. Check whether the generated Application survives; its ApplicationSet sync policy may keep it. If it survives, delete it explicitly with the intended cascade choice. For a plain Application, delete the Application. Cleanup follows the cascade/resources finalizer choice and Delete=false / Delete=confirm, not Prune options.',
+  'If it should render empty: set syncPolicy.automated.allowEmpty: true in the Application or its ApplicationSet template. This turns off the empty-render guard for all future syncs.',
+]
+const title = 'If removing all managed resources is intended'
+const cause = 'Argo CD blocked auto-sync because the render includes none of the resources this Application manages.'
+const guard: GitOpsIssue = {
+  severity: 'critical', scope: 'condition', reason: 'AutoSyncBlockedEmpty',
+  message: 'Auto-sync blocked: the render includes none of the managed resources', cause,
+  action: [primary, ...secondary].join(' '), actionPrimary: primary,
+  actionSecondaryTitle: title, actionSecondary: secondary,
+}
+const issue: Issue = {
+  id: 'guard', severity: 'critical', source: 'problem',
+  category: 'gitops_sync_failed', category_group: 'gitops', grouping_scope: 'unknown',
+  kind: 'Application', group: 'argoproj.io', namespace: 'argocd', name: 'empty',
+  reason: guard.reason, message: guard.message, cause,
+  action: guard.action, action_primary: primary,
+  action_secondary_title: title, action_secondary: secondary,
+}
+
+let root: Root
+let element: HTMLDivElement
+beforeEach(() => {
+  element = document.createElement('div')
+  document.body.appendChild(element)
+  root = createRoot(element)
+})
+afterEach(async () => {
+  await act(async () => root.unmount())
+  element.remove()
+})
+
+function disclosure() {
+  const button = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes(title))!
+  expect(button).toBeDefined()
+  return { button, panel: document.getElementById(button.getAttribute('aria-controls')!)! }
+}
+
+function checkPrimaryVisible() {
+  for (const text of [primary, cause]) {
+    const paragraph = [...element.querySelectorAll('p')].find((p) => p.textContent === text)!
+    expect(paragraph).toBeDefined()
+    expect(paragraph.closest('[inert]')).toBeNull()
+  }
+  expect(element.querySelector('button button')).toBeNull()
+}
+
+async function checkDisclosure() {
+  const { button, panel } = disclosure()
+  expect(button.getAttribute('aria-expanded')).toBe('false')
+  expect(panel.style.gridTemplateRows).toBe('0fr')
+  expect(panel.querySelector('[inert]')).not.toBeNull()
+  checkPrimaryVisible()
+  await act(async () => button.click())
+  expect(button.getAttribute('aria-expanded')).toBe('true')
+  expect(panel.style.gridTemplateRows).toBe('1fr')
+  expect(panel.querySelector('[inert]')).toBeNull()
+  for (const paragraph of secondary) expect(panel.textContent).toContain(paragraph)
+  await act(async () => button.click())
+  expect(button.getAttribute('aria-expanded')).toBe('false')
+  expect(panel.querySelector('[inert]')).not.toBeNull()
+}
+
+describe('empty-render guidance', () => {
+  it('shows primary guidance on the detail band and opens both intended-render paths', async () => {
+    await act(async () => root.render(<GitOpsIssuesBand issues={[guard]} />))
+    await checkDisclosure()
+  })
+
+  it('keeps the headline guidance independent of the collapsed detail stack', async () => {
+    const drift: GitOpsIssue = { severity: 'warning', scope: 'condition', reason: 'OtherWarning', message: 'Another condition' }
+    await act(async () => root.render(<GitOpsIssuesBand issues={[guard, drift]} />))
+    await checkDisclosure()
+    const stack = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes('AutoSyncBlockedEmpty'))!
+    expect(stack.getAttribute('aria-expanded')).toBe('false')
+  })
+
+  it('opens guidance on a lower detail row after expanding the stack', async () => {
+    const first: GitOpsIssue = { severity: 'critical', scope: 'condition', reason: 'ComparisonError', message: 'Cannot render' }
+    await act(async () => root.render(<GitOpsIssuesBand issues={[first, guard]} />))
+    const stack = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes('ComparisonError'))!
+    await act(async () => stack.click())
+    await checkDisclosure()
+  })
+
+  it.each([false, true])('shows split guidance on the cluster Issues row (open=%s)', async (open) => {
+    await act(async () => root.render(<IssueRow issue={issue} open={open} onToggle={() => {}} />))
+    await checkDisclosure()
+  })
+
+  it('shows primary guidance and disclosure in the resource drawer without expanding its issue', async () => {
+    await act(async () => root.render(<ResourceIssuesSection issues={[issue]} />))
+    await checkDisclosure()
+  })
+
+  it('shows complete action when presentation fields are absent', async () => {
+    const { actionPrimary: _primary, actionSecondaryTitle: _title, actionSecondary: _secondary, ...plain } = guard
+    await act(async () => root.render(<GitOpsIssuesBand issues={[plain]} />))
+    expect(element.textContent).toContain(guard.action)
+    expect(element.querySelectorAll('button[aria-controls]')).toHaveLength(0)
+  })
+})
+
+const moveSteps = [
+  "Check this Application's sync options for FailOnSharedResource=true. If set, the sync will refuse the takeover. Stop unless taking it over is intended and allowed.",
+  "Note the resource's live UID.",
+  'Sync this Application.',
+]
+const movePrimary = "To leave it with Application payments, remove it from this Application's source."
+const moveTitle = 'To move it to this Application'
+const move: GitOpsIssue = {
+  severity: 'warning', scope: 'condition', reason: 'SharedResourceWarning', message: 'Also tracked by payments',
+  action: `${movePrimary} ${moveTitle}: ${moveSteps.join(' ')}`, actionPrimary: movePrimary,
+  actionSecondaryTitle: moveTitle, actionSecondary: moveSteps,
+}
+
+describe('shared-resource move guidance', () => {
+  it.each(['detail', 'cluster'] as const)('renders numbered steps on the %s surface', async (surface) => {
+    const row: Issue = { ...issue, reason: move.reason, message: move.message, action: move.action,
+      action_primary: movePrimary, action_secondary_title: moveTitle, action_secondary: moveSteps }
+    await act(async () => root.render(surface === 'detail'
+      ? <GitOpsIssuesBand issues={[move]} />
+      : <IssueRow issue={row} open={true} onToggle={() => {}} />))
+    const button = [...element.querySelectorAll('button')].find((b) => b.textContent?.includes(moveTitle))!
+    expect(button).toBeDefined()
+    await act(async () => button.click())
+    const panel = document.getElementById(button.getAttribute('aria-controls')!)!
+    expect([...panel.querySelectorAll('ol > li')].map((li) => li.textContent)).toEqual(moveSteps)
+    expect(panel.querySelector('[inert]')).toBeNull()
+    expect(element.textContent).toContain(movePrimary)
+  })
+})
+
+describe('cluster sync hazards', () => {
+  const hazard = 'Resolve shared ownership before syncing: another Application can take tracking back.'
+  it.each([undefined, { nextStep: 'Host next step', cause: 'Host cause' }])('keeps a warning ahead of any next-step source (%j)', async (diagnosisSource) => {
+    await act(async () => root.render(<IssueRow
+      issue={{ ...issue, action_primary: undefined, action_secondary: undefined, action_secondary_title: undefined, hazard }}
+      open={true} onToggle={() => {}} diagnosisSource={diagnosisSource} />))
+    const warning = [...element.querySelectorAll('p')].find((p) => p.textContent === hazard)!
+    expect(warning).toBeDefined()
+    expect(warning.closest('.text-warning-text')).not.toBeNull()
+    expect(warning.closest('[inert]')).toBeNull()
+    expect(element.textContent!.indexOf(hazard)).toBeLessThan(element.textContent!.indexOf(diagnosisSource?.nextStep ?? primary))
+    if (diagnosisSource) expect(element.textContent).toContain(diagnosisSource.nextStep)
+  })
+
+  it('shows a hazard on a collapsed row with no split guidance or action', async () => {
+    await act(async () => root.render(<IssueRow
+      issue={{ ...issue, action: undefined, action_primary: undefined, action_secondary: undefined, action_secondary_title: undefined, hazard }}
+      open={false} onToggle={() => {}} diagnosisSource={{ nextStep: 'Host next step' }} />))
+    const warning = [...element.querySelectorAll('p')].find((p) => p.textContent === hazard)!
+    expect(warning).toBeDefined()
+    expect(warning.closest('[inert]')).toBeNull()
+    expect(warning.closest('.text-warning-text')).not.toBeNull()
+  })
+})
+
+describe('hazard text retained only once in presentation', () => {
+  it.each([false, true])('keeps empty-render guidance and one warning (open=%s)', async (open) => {
+    await act(async () => root.render(<IssueRow issue={{ ...issue, hazard: primary }} open={open} onToggle={() => {}} />))
+    expect([...element.querySelectorAll('p')].filter((p) => p.textContent === primary)).toHaveLength(1)
+    await checkDisclosure()
+  })
+
+  it.each(['hazard only', 'appended hazard'])('keeps one warning for %s actions', async (mode) => {
+    const hazard = 'Sync can take over shared tracking.'
+    const nextStep = "Open the application's sync operation details."
+    const action = mode === 'hazard only' ? hazard : `${nextStep} ${hazard}`
+    await act(async () => root.render(<IssueRow issue={{ ...issue, hazard, action,
+      action_primary: undefined, action_secondary: undefined, action_secondary_title: undefined }} open={true} onToggle={() => {}} />))
+    expect(element.textContent!.split(hazard)).toHaveLength(2)
+    if (mode === 'hazard only') expect(element.textContent).not.toContain('Next step')
+    else expect(element.textContent).toContain(nextStep)
+  })
+})

package/src/components/issues/IssueGuidance.tsx

@@ -0,0 +1,48 @@
+import { AlertTriangle } from 'lucide-react'
+import { Disclosure } from '../ui/Disclosure'
+
+export function issueGuidanceSummary(action?: string, primary?: string, hazard?: string) {
+  const summary = primary || action
+  if (!hazard || !summary) return summary
+  if (summary === hazard) return undefined
+  return summary.endsWith(` ${hazard}`) ? summary.slice(0, -hazard.length - 1) : summary
+}
+
+export function IssueGuidance({ action, primary, secondaryTitle, secondary, ordered, hazard, className }: {
+  action?: string
+  /** Replaces a supplied action; primary alone renders no action text. */
+  primary?: string
+  /** Paired with secondary; no disclosure is shown without both. */
+  secondaryTitle?: string
+  /** Paired with secondaryTitle; no disclosure is shown without both. */
+  secondary?: string[]
+  ordered?: boolean
+  hazard?: string
+  className?: string
+}) {
+  if (!action && !hazard && !(secondaryTitle && secondary?.length)) return null
+  return (
+    <div className={className}>
+      {hazard && (
+        <div className="mb-2 flex items-start gap-2 text-warning-text">
+          <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0" />
+          <p>{hazard}</p>
+        </div>
+      )}
+      {action && <p>{primary || action}</p>}
+      {secondaryTitle && secondary && (
+        <Disclosure summary={secondaryTitle} className="mt-2" summaryClassName="font-medium">
+          {ordered ? (
+            <ol className="list-decimal space-y-2 pl-5 pt-2">
+              {secondary.map((step) => <li key={step}>{step}</li>)}
+            </ol>
+          ) : (
+            <div className="space-y-2 pt-2">
+              {secondary.map((paragraph) => <p key={paragraph}>{paragraph}</p>)}
+            </div>
+          )}
+        </Disclosure>
+      )}
+    </div>
+  )
+}

package/src/components/issues/IssuesView.tsx

@@ -1,7 +1,8 @@
+import { IssueGuidance, issueGuidanceSummary } from './IssueGuidance'
 import { summarizeSchedulerMessage } from '../resources/resource-utils'
 import { useMemo, useState, type ComponentType, type ReactNode } from 'react';
 import { AlertOctagon, AlertTriangle, ArrowRight, CircleCheck, Clock, Eraser, ExternalLink, Layers, Terminal, Workflow } from 'lucide-react';
-import { CardBody, CardSection, ClusterName, Disclosure, EmptyState, KIND_CHIP_CLASS, TerminalBlock } from '../ui';
+import { CardSection, ClusterName, Disclosure, EmptyState, KIND_CHIP_CLASS, TerminalBlock } from '../ui';
 import { Collapse, CollapseChevron, useDisclosure } from '../ui/Collapse';
 import { Tooltip } from '../ui/Tooltip';
 import { formatCompactAge, formatRelativeAgeTime } from '../../utils/format';
@@ -368,6 +369,15 @@ export function IssueRow({
         </div>
       </div>
 
+      {(issue.action_primary || issue.hazard) && (
+        <Collapse open={!open} unmountOnExit>
+          <div className="px-4 pb-3 pl-6 text-xs">
+            {issue.cause && <p className="mb-1 text-theme-text-primary">{issue.cause}</p>}
+            <IssueGuidance hazard={issue.hazard} action={issue.action_primary ? issueGuidanceSummary(issue.action, issue.action_primary, issue.hazard) : undefined} secondaryTitle={issue.action_secondary_title} secondary={issue.action_secondary} ordered={issue.reason === 'SharedResourceWarning'} className="text-theme-text-tertiary" />
+          </div>
+        </Collapse>
+      )}
+
       {/* Details unmount after the close transition: a list can hold hundreds
           of rows and the body is the expensive part, so closed rows stay light. */}
       <Collapse open={open} unmountOnExit id={panelId}>
@@ -509,11 +519,13 @@ function Diagnosis({ issue, source }: { issue: Issue; source?: IssueDiagnosisSou
       </>
     ) : undefined;
 
+  const guidanceSummary = issueGuidanceSummary(issue.action, issue.action_primary, issue.hazard);
   const hasNextStep =
-    !!issue.action || !!sourceNextStep || (issue.remediation_kind === 'create-namespace' && !!issue.remediation_target);
+    !!guidanceSummary || !!issue.action_secondary?.length || !!sourceNextStep || (issue.remediation_kind === 'create-namespace' && !!issue.remediation_target);
 
   return (
     <div className="flex flex-col divide-y divide-theme-border/70 [&>*]:py-4 [&>*:first-child]:pt-0 [&>*:last-child]:pb-0">
+      <IssueGuidance hazard={issue.hazard} className="text-sm leading-relaxed" />
       {/* When a parsed cause replaces the detector text, the terse reason code
           (CrashLoopBackOff, FailedMount…) rides the eyebrow — it's the greppable
           identifier operators anchor on, and the collapsed header drops it while
@@ -547,7 +559,7 @@ function Diagnosis({ issue, source }: { issue: Issue; source?: IssueDiagnosisSou
           tone="fix"
           labelExtra={nextStepAttribution ?? undefined}
         >
-          {sourceNextStep ?? (issue.action ? <CardBody>{issue.action}</CardBody> : null)}
+          {sourceNextStep ?? <IssueGuidance action={guidanceSummary} secondaryTitle={issue.action_secondary_title} secondary={issue.action_secondary} ordered={issue.reason === 'SharedResourceWarning'} className="text-sm leading-relaxed text-theme-text-secondary" />}
           {/* Survives an override: this is a structured one-click fix with an
               apply path, not advice competing with the host's. */}
           {issue.remediation_kind === 'create-namespace' && issue.remediation_target ? (

package/src/components/issues/index.ts

@@ -15,6 +15,7 @@ export {
   memberRef,
   issueSortAnchor,
   compareIssueSortAnchors,
+  compareIssues,
 } from './types';
 export type { Issue, IssueConditionalCleanup, IssueFinalizerRemoval, IssueSeverity, IssueAffected, IssueResourceRef, IssueDiagnosticContext, IssueDiagnosticFact, IssueDiagnosticConfidence, IssueDiagnosticIssueRef, IssueDiagnosticRole, IssueIncidentParent, IssueChangeContext, IssueRecentChange, IssueRecentChangeField, IssueRunningPreviousValue, IssueWithheld } from './types';
 export {

package/src/components/issues/severity.ts

@@ -100,6 +100,7 @@ const CATEGORY_LABEL: Record<string, string> = {
   crossplane_reconcile_failed: 'Crossplane reconcile failed',
   termination_stuck: 'Stuck terminating',
   operator_condition_failed: 'Controller reports a problem',
+  gitops_resource_warning: 'GitOps resource warning',
   gitops_sync_failed: 'GitOps sync failed',
   gitops_render_failed: 'GitOps render failed',
   gitops_spec_invalid: 'GitOps spec invalid',

package/src/components/issues/types.ts

@@ -231,6 +231,16 @@ export interface Issue {
    *  Server-emitted (omitempty); empty for issues without a parser. */
   cause?: string;
   action?: string;
+  /** What the suggested or most obvious action could destroy or take over,
+   *  such as a GitOps sync that would prune every managed resource. Show it
+   *  even when replacing cause or action with other guidance; action also
+   *  contains it. Absence means no warning was supplied, not that the action
+   *  is safe; older producers omit it. */
+  hazard?: string;
+  /** Optional presentation split; action always retains the complete guidance. */
+  action_primary?: string;
+  action_secondary_title?: string;
+  action_secondary?: string[];
   remediation_kind?: string;
   remediation_target?: string;
   /** A cleanup that is right only when its condition holds — never part of

package/src/types/core.ts

@@ -176,6 +176,7 @@ export interface FeatureCapabilities {
   cnpgWorkspace?: boolean
   cnpgProtectionSetup?: boolean
   gitopsWriteEvidence?: boolean
+  agentSigninCheck?: boolean
   serviceEndpointSlices?: boolean
   trafficRecords?: boolean
   clusterScopedPlaceholder?: boolean

package/src/types/gitops-insights.ts

@@ -124,6 +124,14 @@ export interface GitOpsIssue {
   rawMessage?: string
   refs?: GitOpsInsightRef[]
   action?: string
+  /** Optional presentation split; action always retains the complete guidance. */
+  actionPrimary?: string
+  actionSecondaryTitle?: string
+  actionSecondary?: string[]
+  // Set when syncing would prune every managed
+  // resource or take resources over from another Application. Shown as a
+  // warning ahead of a failed operation's cause; resource rows defer sync advice to it.
+  hazard?: string
   // Plain-English root cause when the message matched a recognized error
   // pattern. Empty for unrecognized messages — UI falls back to the raw message.
   cause?: string