feat(cli): help text, daemon-health-rollup, project-status, E2E tests (closes #1)

crates/ao-fleet-cli/src/cli/command_router.rs

@@ -3,6 +3,7 @@ use anyhow::Result;
 use crate::cli::handlers::audit_list::audit_list;
 use crate::cli::handlers::config_snapshot_export::config_snapshot_export;
 use crate::cli::handlers::config_snapshot_import::config_snapshot_import;
+use crate::cli::handlers::daemon_health_rollup::daemon_health_rollup;
 use crate::cli::handlers::daemon_override_clear::daemon_override_clear;
 use crate::cli::handlers::daemon_override_list::daemon_override_list;
 use crate::cli::handlers::daemon_override_upsert::daemon_override_upsert;
@@ -41,6 +42,7 @@ use crate::cli::handlers::project_host_assign::project_host_assign;
 use crate::cli::handlers::project_host_clear::project_host_clear;
 use crate::cli::handlers::project_host_list::project_host_list;
 use crate::cli::handlers::project_list::project_list;
+use crate::cli::handlers::project_status::project_status;
 use crate::cli::handlers::project_update::project_update;
 use crate::cli::handlers::schedule_create::schedule_create;
 use crate::cli::handlers::schedule_delete::schedule_delete;
@@ -91,6 +93,7 @@ pub fn route_command(root: RootCommand) -> Result<()> {
         CommandGroup::ProjectHostClear(command) => project_host_clear(&root.db_path, command),
         CommandGroup::ProjectHostList(command) => project_host_list(&root.db_path, command),
         CommandGroup::ProjectList(command) => project_list(&root.db_path, command),
+        CommandGroup::ProjectStatus(command) => project_status(&root.db_path, command),
         CommandGroup::ProjectUpdate(command) => project_update(&root.db_path, command),
         CommandGroup::ProjectDelete(command) => project_delete(&root.db_path, command),
         CommandGroup::ScheduleCreate(command) => schedule_create(&root.db_path, command),
@@ -117,6 +120,7 @@ pub fn route_command(root: RootCommand) -> Result<()> {
         CommandGroup::DaemonOverrideList(command) => daemon_override_list(&root.db_path, command),
         CommandGroup::DaemonOverrideClear(command) => daemon_override_clear(&root.db_path, command),
         CommandGroup::DaemonStatus(command) => daemon_status(&root.db_path, command),
+        CommandGroup::DaemonHealthRollup(command) => daemon_health_rollup(&root.db_path, command),
         CommandGroup::DaemonReconcile(command) => daemon_reconcile(&root.db_path, command),
         CommandGroup::McpList(command) => mcp_list(command),
         CommandGroup::McpServe(command) => mcp_serve(&root.db_path, command),

crates/ao-fleet-cli/src/cli/handlers/audit_list_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "List recent audit log entries")]
 pub struct AuditListCommand {
     #[arg(long)]
     pub team_id: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/config_snapshot_export_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Export fleet config to a snapshot file")]
 pub struct ConfigSnapshotExportCommand {
     #[arg(long)]
     pub output: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/config_snapshot_import_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Import fleet config from a snapshot file")]
 pub struct ConfigSnapshotImportCommand {
     #[arg(long)]
     pub input: String,

crates/ao-fleet-cli/src/cli/handlers/daemon_health_rollup.rs

@@ -0,0 +1,43 @@
+use anyhow::Result;
+use ao_fleet_core::DaemonDesiredState;
+use ao_fleet_store::FleetStore;
+use serde::Serialize;
+
+use crate::cli::handlers::daemon_health_rollup_command::DaemonHealthRollupCommand;
+use crate::cli::handlers::json_printer::print_json;
+
+#[derive(Debug, Serialize)]
+pub struct DaemonHealthRollup {
+    pub total: usize,
+    pub desired_running: usize,
+    pub observed_running: usize,
+    pub aligned: usize,
+    pub degraded: usize,
+    pub unobserved: usize,
+}
+
+pub fn daemon_health_rollup(db_path: &str, command: DaemonHealthRollupCommand) -> Result<()> {
+    let store = FleetStore::open(db_path)?;
+    let statuses = store.fleet_daemon_statuses(command.team_id.as_deref())?;
+
+    let total = statuses.len();
+    let desired_running =
+        statuses.iter().filter(|s| s.desired_state == DaemonDesiredState::Running).count();
+    let observed_running =
+        statuses.iter().filter(|s| s.observed_state == Some(DaemonDesiredState::Running)).count();
+    let aligned = statuses
+        .iter()
+        .filter(|s| s.observed_state.as_ref().map_or(false, |obs| obs == &s.desired_state))
+        .count();
+    let unobserved = statuses.iter().filter(|s| s.observed_state.is_none()).count();
+    let degraded = total - aligned - unobserved;
+
+    print_json(&DaemonHealthRollup {
+        total,
+        desired_running,
+        observed_running,
+        aligned,
+        degraded,
+        unobserved,
+    })
+}

crates/ao-fleet-cli/src/cli/handlers/daemon_health_rollup_command.rs

@@ -0,0 +1,12 @@
+use clap::Args;
+
+#[derive(Debug, Args)]
+#[command(
+    about = "Show a health rollup summary across all fleet daemons",
+    long_about = "Aggregates observed vs desired daemon state for every project in the fleet. \
+Useful for a quick health check: how many daemons are aligned, degraded, or unobserved."
+)]
+pub struct DaemonHealthRollupCommand {
+    #[arg(long, help = "Filter to a specific team ID")]
+    pub team_id: Option<String>,
+}

crates/ao-fleet-cli/src/cli/handlers/daemon_override_clear_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Clear a daemon schedule override for a team")]
 pub struct DaemonOverrideClearCommand {
     #[arg(long)]
     pub team_id: String,

crates/ao-fleet-cli/src/cli/handlers/daemon_override_list_command.rs

@@ -1,4 +1,5 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "List active daemon schedule overrides")]
 pub struct DaemonOverrideListCommand;

crates/ao-fleet-cli/src/cli/handlers/daemon_override_upsert_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Create or update a daemon schedule override for a team")]
 pub struct DaemonOverrideUpsertCommand {
     #[arg(long)]
     pub team_id: String,

crates/ao-fleet-cli/src/cli/handlers/daemon_reconcile_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Preview or apply daemon reconciliation actions across the fleet")]
 pub struct DaemonReconcileCommand {
     #[arg(long)]
     pub at: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/daemon_status.rs

@@ -21,7 +21,7 @@ pub fn daemon_status(db_path: &str, command: DaemonStatusCommand) -> Result<()>
     print_json(&store.fleet_daemon_statuses(command.team_id.as_deref())?)
 }
 
-fn refresh_observed_statuses(store: &FleetStore, team_id: Option<&str>) -> Result<()> {
+pub fn refresh_observed_statuses(store: &FleetStore, team_id: Option<&str>) -> Result<()> {
     let placement_map = build_project_host_placement_map(store.list_project_host_placements()?);
     let host_map = build_host_map(store.list_hosts()?);
 

crates/ao-fleet-cli/src/cli/handlers/daemon_status_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Show current daemon desired and observed status for all projects")]
 pub struct DaemonStatusCommand {
     #[arg(long)]
     pub team_id: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/db_init_command.rs

@@ -1,4 +1,5 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Initialize or migrate the fleet SQLite database")]
 pub struct DbInitCommand;

crates/ao-fleet-cli/src/cli/handlers/fleet_overview_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Show a full overview of fleet health and daemon status")]
 pub struct FleetOverviewCommand {
     #[arg(long)]
     pub team_id: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/founder_overview_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Show a founder-level summary of team activity and project status")]
 pub struct FounderOverviewCommand {
     #[arg(long)]
     pub team_id: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/host_create_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Register a new execution host in the fleet")]
 pub struct HostCreateCommand {
     #[arg(long)]
     pub slug: String,

crates/ao-fleet-cli/src/cli/handlers/host_delete_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Remove a host from the fleet registry")]
 pub struct HostDeleteCommand {
     #[arg(long)]
     pub id: String,

crates/ao-fleet-cli/src/cli/handlers/host_get_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Get details for a specific host")]
 pub struct HostGetCommand {
     #[arg(long)]
     pub id: String,

crates/ao-fleet-cli/src/cli/handlers/host_import_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Import hosts and projects from a remote hostd instance")]
 pub struct HostImportCommand {
     #[arg(long)]
     pub base_url: String,

crates/ao-fleet-cli/src/cli/handlers/host_list_command.rs

@@ -1,4 +1,5 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "List all registered hosts")]
 pub struct HostListCommand;

crates/ao-fleet-cli/src/cli/handlers/host_log_stream_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Stream logs from a remote host in real time")]
 pub struct HostLogStreamCommand {
     #[arg(long)]
     pub base_url: String,

crates/ao-fleet-cli/src/cli/handlers/host_logs_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Fetch recent logs from a remote host")]
 pub struct HostLogsCommand {
     #[arg(long)]
     pub base_url: String,

crates/ao-fleet-cli/src/cli/handlers/host_sync_all_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Sync project registrations from all known hosts")]
 pub struct HostSyncAllCommand {
     #[arg(long)]
     pub auth_token: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/host_sync_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Sync project registrations from a specific remote host")]
 pub struct HostSyncCommand {
     #[arg(long)]
     pub base_url: String,

crates/ao-fleet-cli/src/cli/handlers/host_update_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Update fields on a registered host")]
 pub struct HostUpdateCommand {
     #[arg(long)]
     pub id: String,

crates/ao-fleet-cli/src/cli/handlers/knowledge_document_create_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Create a knowledge document in the fleet knowledge base")]
 pub struct KnowledgeDocumentCreateCommand {
     #[arg(long)]
     pub id: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/knowledge_document_list_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "List knowledge documents, optionally filtered by scope")]
 pub struct KnowledgeDocumentListCommand {
     #[arg(long)]
     pub scope: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/knowledge_fact_create_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Record a knowledge fact in the fleet knowledge base")]
 pub struct KnowledgeFactCreateCommand {
     #[arg(long)]
     pub id: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/knowledge_fact_list_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "List knowledge facts, optionally filtered by scope")]
 pub struct KnowledgeFactListCommand {
     #[arg(long)]
     pub scope: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/knowledge_search_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Search the fleet knowledge base for documents and facts")]
 pub struct KnowledgeSearchCommand {
     #[arg(long)]
     pub scope: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/knowledge_source_list_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "List knowledge sources, optionally filtered by scope")]
 pub struct KnowledgeSourceListCommand {
     #[arg(long)]
     pub scope: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/knowledge_source_upsert_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Create or update a knowledge source")]
 pub struct KnowledgeSourceUpsertCommand {
     #[arg(long)]
     pub id: Option<String>,

crates/ao-fleet-cli/src/cli/handlers/mcp_list_command.rs

@@ -1,4 +1,5 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "List available MCP tools exposed by this fleet server")]
 pub struct McpListCommand;

crates/ao-fleet-cli/src/cli/handlers/mod.rs

@@ -4,6 +4,8 @@ pub mod config_snapshot_export;
 pub mod config_snapshot_export_command;
 pub mod config_snapshot_import;
 pub mod config_snapshot_import_command;
+pub mod daemon_health_rollup;
+pub mod daemon_health_rollup_command;
 pub mod daemon_override_clear;
 pub mod daemon_override_clear_command;
 pub mod daemon_override_list;
@@ -87,6 +89,8 @@ pub mod project_host_list_command;
 pub mod project_list;
 pub mod project_list_command;
 pub mod project_ops_support;
+pub mod project_status;
+pub mod project_status_command;
 pub mod project_update;
 pub mod project_update_command;
 pub mod schedule_create;

crates/ao-fleet-cli/src/cli/handlers/project_ao_json_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Clone, Args)]
+#[command(about = "Run an ao-cli JSON command against a registered project")]
 pub struct ProjectAoJsonCommand {
     #[arg(long)]
     pub project_root: String,

crates/ao-fleet-cli/src/cli/handlers/project_config_get_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Clone, Args)]
+#[command(about = "Get the AO runtime config for a project")]
 pub struct ProjectConfigGetCommand {
     #[arg(long)]
     pub project_root: String,

crates/ao-fleet-cli/src/cli/handlers/project_create_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Register a new project in the fleet")]
 pub struct ProjectCreateCommand {
     #[arg(long)]
     pub team_id: String,

crates/ao-fleet-cli/src/cli/handlers/project_delete_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Remove a project from the fleet registry")]
 pub struct ProjectDeleteCommand {
     #[arg(long)]
     pub id: String,

crates/ao-fleet-cli/src/cli/handlers/project_discover_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Discover AO projects under one or more directory trees")]
 pub struct ProjectDiscoverCommand {
     #[arg(long = "search-root")]
     pub search_roots: Vec<String>,

crates/ao-fleet-cli/src/cli/handlers/project_events_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Clone, Args)]
+#[command(about = "Stream or tail workflow events for a project")]
 pub struct ProjectEventsCommand {
     #[arg(long)]
     pub project_root: String,

crates/ao-fleet-cli/src/cli/handlers/project_get_command.rs

@@ -1,6 +1,7 @@
 use clap::Args;
 
 #[derive(Debug, Args)]
+#[command(about = "Get details for a specific project")]
 pub struct ProjectGetCommand {
     #[arg(long)]
     pub id: String,