docs: add missing health command to CLI reference

[Copilot]

The health command was fully implemented and registered as an analysis command but absent from CLI documentation, making it undiscoverable to users.

Changes

• Added health command documentation in the Monitoring section of docs/src/content/docs/setup/cli.md
• Positioned after audit command for logical grouping of analysis tools
• Documented all options (--days, --threshold, --repo, --json) and metrics (success rates, trends, token usage, costs)

The command provides workflow health analytics including success rates over configurable time periods (7/30/90 days), trend indicators, and cost tracking - critical for maintaining workflow quality.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[cli-consistency] Missing Documentation: health Command</issue_title>
<issue_description>## Issue Description

Command: gh aw health
Type: Missing documentation
Priority: Medium

The health command exists in the codebase and is registered as an "analysis" command but is completely missing from the CLI documentation (docs/src/content/docs/setup/cli.md). Users cannot discover this analytical feature.

Evidence from Source Code

File: pkg/cli/health_command.go
Use: health [workflow]
Short description: "Display workflow health metrics and success rates"
Registration:

• cmd/gh-aw/main.go line 557: healthCmd := cli.NewHealthCommand()
• Line 593: healthCmd.GroupID = "analysis"
• Line 620: rootCmd.AddCommand(healthCmd)

Current State vs Expected State

Aspect	Current	Expected
Implementation	✅ Fully implemented	✅ Fully implemented
Registration	✅ Registered as "analysis" command	✅ Registered as "analysis" command
Documentation	❌ Missing entirely	✅ Should be in cli.md under "### Monitoring"

Impact

Users are missing out on workflow health metrics and success rate analysis features. This command provides valuable insights into:

• Workflow success rates
• Failure patterns
• Workflow reliability indicators

These metrics are crucial for maintaining and improving workflow quality.

Suggested Fix

Add documentation section in docs/src/content/docs/setup/cli.md under the "### Monitoring" section (after the status command documentation):

#### `health`

Display workflow health metrics and success rates for analyzing workflow reliability.

```bash wrap
gh aw health                  # Health metrics for all workflows
gh aw health my-workflow      # Health metrics for specific workflow
gh aw health --json           # Output in JSON format
```

**Options:** `--json`

Shows metrics such as:
- Success rates over time
- Failure patterns and common errors
- Workflow reliability indicators
- Historical performance trends

Use this command to identify problematic workflows and monitor overall workflow health in your repository.

Files to Modify

• docs/src/content/docs/setup/cli.md - Add health command documentation under "### Monitoring" section
  Related to [cli-consistency] CLI Consistency Issues - February 6, 2026 #14141

AI generated by CLI Consistency Checker

• expires on Feb 8, 2026, 1:35 PM UTC

Comments on the Issue (you are @copilot in this section)

• Fixes [cli-consistency] Missing Documentation: health Command #14144

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[Copilot]

Pull request overview

Adds missing CLI reference documentation for the existing gh aw health analysis command, improving discoverability for workflow health analytics.

Changes:

• Documented the health command under the Monitoring section, alongside other analysis/monitoring tools.
• Included usage examples, options list, and a summary of reported metrics.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

--days is restricted by the implementation to only 7, 30, or 90 (and defaults to 7). The docs currently show examples but don’t state the allowed values, which can lead to users trying unsupported values and hitting an error. Consider explicitly documenting the allowed set (and default) near the Options line.

Suggested change

	**Options:** `--days`, `--threshold`, `--repo`, `--json`
	**Options:** `--days` (allowed values: 7, 30, or 90; default: 7), `--threshold`, `--repo`, `--json`

[Copilot]

The metrics list says “Average and total cost”, but gh aw health (summary view) only renders average cost in the table; total cost is only shown in the per-workflow detailed view (and in JSON fields). Suggest rewording this bullet to avoid implying total cost is always displayed in the summary output.

Suggested change

	- Average and total cost
	- Average cost (with total cost available in detailed and JSON views)