//! Error handling conventions for fyi CLI commands.
//!
//! # Error Handling Guidelines
//!
//! This module documents the standard error handling patterns used across all CLI commands.
//! Following these conventions ensures predictable behavior for scripts and consistent UX.
//!
//! ## Error Propagation
//!
//! Use [`anyhow::Context::context()`] to add context to errors. This produces clear,
//! hierarchical error messages that help users understand what went wrong:
//!
//! ```rust,ignore
//! // Preferred: use context() to wrap errors
//! storage.query(&query).context("failed to query events")?;
//!
//! // Avoid: map_err with anyhow! loses the original error's context
//! storage.query(&query).map_err(|e| anyhow::anyhow!("query failed: {}", e))?;
//! ```
//!
//! ## Creating New Errors
//!
//! - Use [`anyhow::bail!`] for validation failures and user-correctable errors:
//!   ```rust,ignore
//!   if !is_valid_framework(name) {
//!       bail!("unknown framework: {}", name);
//!   }
//!   ```
//!
//! - Use [`anyhow::anyhow!`] with `ok_or_else()` for Option → Result conversions:
//!   ```rust,ignore
//!   get_adapter(name).ok_or_else(|| anyhow::anyhow!("unknown framework: {}", name))?;
//!   ```
//!
//! ## Exit Codes
//!
//! Commands signal exit behavior via [`crate::RunResult`]:
//!
//! - **Normal commands**: Return `Err(e)` on failure, which exits with code 1
//! - **Hook commands** (e.g., `log`): Always exit 0 to avoid blocking workflows
//!   - Errors are printed to stderr but don't affect the exit code
//!   - Use `RunResult::ExitWithCode(0)` for this behavior
//!
//! ## Stderr Messages
//!
//! Use stderr for all non-data output:
//!
//! - **Errors**: Handled by main.rs with `eprintln!("error: {:#}", e)`
//! - **Warnings**: Prefix with "Warning: " (e.g., deprecation notices)
//! - **Info/Progress**: No prefix (e.g., "Hooks installed to: ...")
//!
//! For warnings during hook execution (where exit code is always 0), prefix with "fyi:":
//! ```rust,ignore
//! eprintln!("fyi: warning: multiple frameworks detected");
//! ```
//!
//! ## Stdout vs Stderr
//!
//! - **stdout**: Data output only (JSON, table output for `show`/`watch`)
//! - **stderr**: Everything else (errors, warnings, progress, informational messages)
//!
//! This allows scripts to parse stdout reliably while still showing user feedback.
