enhancement: explain unit health and color inspect cron status

Author: ra0x3

docs/how-it-works/commands/inspect.mdx

@@ -94,6 +94,18 @@ runtime command lines and process/spawn descendants.
 - **Average duration** - For completed processes
 - **Success rate** - For cron jobs
 
+## Cron run history
+
+For cron units, inspect prints a `Cron Run History` table. The `STATUS` column is
+color-coded so outcomes are obvious at a glance:
+
+- `success` - light green
+- `running` - light blue (the run is still in progress)
+- `failed` / `failed: <reason>` - red
+- `overlap` - yellow (a run was skipped because the previous one was still going)
+
+Pass `--no-color` to disable the coloring.
+
 ## Snapshot detail
 
 The default `status.snapshot_mode: summary` is intended for production-scale

docs/how-it-works/commands/status.mdx

@@ -24,14 +24,50 @@ when you explicitly want the no-supervisor disk fallback for that config.
 ## Interactive Mode
 
 By default, `sysg status` displays an interactive table where you can:
-- **Tab** or **↓** (Down arrow) - Move to the next service
-- **Shift+Tab** or **↑** (Up arrow) - Move to the previous service
-- **Enter** or **I** - Open the inspect view for the selected service
+- **↓** / **Tab** (Down) - Move to the next service
+- **↑** / **Shift+Tab** (Up) - Move to the previous service
+- **→** / **←** (Right / Left) - Move the focused cell across columns in the
+  selected row
+- **I** or **Enter** - Open the inspect view for the selected service
+- **H** - Open the health report explaining why the selected unit is `Warn` or
+  `Failing` (see below)
 - **L** - Open a live log snapshot stream for the selected service
 - **R** - Restart the selected service
 - **q**, **ESC**, or **Ctrl+C** - Exit the status view
 
-The selected row is highlighted with a white background for easy visibility.
+The focused cell in the selected row is drawn in reverse video, so it stands
+out as lighter on a dark terminal and darker on a light terminal. This makes it
+obvious which cell you are on as you tab across the row.
+
+## Why is it `Warn` or `Failing`?
+
+The `HEALTH` column is a verdict, not an explanation. To see *why* a unit holds
+its health, select it and press **H**. systemg opens a full-screen, README-style
+health report in the same window:
+
+```
+# 'api' is stopped but should be serving
+
+Severity: 5/10 (Warn)
+
+TLDR: A long-running service is intentionally stopped.
+
+## Description
+
+'api' has intent 'Serve', meaning it is expected to stay available, but it is
+currently stopped. Nothing is serving requests for this unit right now.
+
+## Recommended Fix
+
+Start it again if it should be up:
+
+    sysg restart -s api --log-level debug
+
+If it is meant to stay down, this is expected and can be ignored.
+```
+
+The report wraps to at most 80 columns, narrowing to 80% of the terminal width
+on smaller terminals. Press any key to return to the status table.
 
 > **Info:** Press **L** while a UNIT row is selected to open that unit's logs
 > without leaving the status workflow. The shortcut runs
@@ -170,7 +206,9 @@ process and spawn-tree detail in status/inspect views.
   data is available.
 - **LAST_EXIT** - Last recorded exit code or signal when the unit has exited.
 - **HEALTH** - Operator action signal. `HEALTH` answers "does this unit need
-  attention?" Values are `Healthy`, `Idle`, `Warn`, and `Failing`.
+  attention?" Values are `Healthy`, `Idle`, `Warn`, and `Failing`. Press **H**
+  on a selected unit to open a health report explaining the verdict and how to
+  fix it.
 
 ### State values
 

src/bin/main.rs

@@ -45,7 +45,7 @@ use systemg::{
         CronUnitStatus, ExitMetadata, OverallHealth, ProcessState, ProjectRunMode,
         SpawnedProcessNode, StatusSnapshot, UnitHealth, UnitIntent, UnitKind,
         UnitMetricsSummary, UnitState, UnitStatus, UptimeInfo, collect_disk_snapshot,
-        compute_overall_health, format_elapsed,
+        compute_overall_health, explain_unit_health, format_elapsed,
     },
     supervisor::Supervisor,
 };
@@ -1190,7 +1190,7 @@ mod tests {
             runtime_command: None,
             spawned_children: vec![],
         };
-        let unit_row = format_unit_row(&unit, &columns, true);
+        let unit_row = format_unit_row_focus(&unit, &columns, true, None);
         assert!(unit_row.contains("srvc"));
         assert!(unit_row.contains("rashad"));
 
@@ -2248,6 +2248,71 @@ mod tests {
         assert!(widths[3] >= INSPECT_CRON_SOFT_MIN_WIDTHS[3]);
     }
 
+    #[test]
+    fn format_inspect_cron_status_colors_by_outcome() {
+        let success =
+            format_inspect_cron_status(Some(&CronExecutionStatus::Success), false);
+        assert!(success.contains("success"));
+        assert!(success.contains(BRIGHT_GREEN));
+
+        let running = format_inspect_cron_status(None, false);
+        assert!(running.contains("running"));
+        assert!(running.contains(LIGHT_BLUE));
+
+        let failed = format_inspect_cron_status(
+            Some(&CronExecutionStatus::Failed("boom".into())),
+            false,
+        );
+        assert!(failed.contains("failed: boom"));
+        assert!(failed.contains(RED_BOLD));
+    }
+
+    #[test]
+    fn format_inspect_cron_status_respects_no_color() {
+        let success =
+            format_inspect_cron_status(Some(&CronExecutionStatus::Success), true);
+        assert_eq!(success, "success");
+    }
+
+    #[test]
+    fn wrap_paragraph_respects_width_and_keeps_words_whole() {
+        let text = "the quick brown fox jumps over the lazy dog";
+        let lines = wrap_paragraph(text, 20);
+        assert!(lines.iter().all(|line| visible_length(line) <= 20));
+        let rejoined = lines.join(" ");
+        assert_eq!(rejoined, text);
+    }
+
+    #[test]
+    fn render_health_report_includes_required_sections() {
+        let mut unit = UnitStatus {
+            name: "api".into(),
+            hash: "hash".into(),
+            project: None,
+            kind: UnitKind::Service,
+            lifecycle: Some(ServiceLifecycleStatus::Stopped),
+            state: UnitState::Stopped,
+            intent: UnitIntent::Serve,
+            health: UnitHealth::Warn,
+            process: None,
+            uptime: None,
+            last_exit: None,
+            cron: None,
+            metrics: None,
+            command: None,
+            runtime_command: None,
+            spawned_children: Vec::new(),
+        };
+        unit.intent = UnitIntent::Serve;
+
+        let rendered = render_health_report(&unit, true).join("\n");
+        assert!(rendered.contains("# "));
+        assert!(rendered.contains("Severity:"));
+        assert!(rendered.contains("TLDR:"));
+        assert!(rendered.contains("## Description"));
+        assert!(rendered.contains("## Recommended Fix"));
+    }
+
     #[test]
     fn test_format_uptime_short() {
         assert_eq!(format_uptime_short("30 secs ago"), "< 1m");