Surface the active TOML config file location in --help (and add a side-effect-free `config path` lookup)

[eabase]

Summary

all-smi --help does not reveal where the application's TOML config file lives. The only pointer is the --config <PATH> flag description, which defers to all-smi config init — a command that writes a file as a side effect. New users therefore cannot tell, from -h / --help alone, that a config file exists or where it should go.

This issue adds the resolved config-file location (with an existence marker) to the top-level help output, adds a read-only all-smi config path lookup for scripting/discovery, and fills the config-path gap in the man page FILES section.

Background

The TOML configuration system shipped in #202 (merged 2026-04-21): platform-canonical paths, a global --config flag, and config init / print / validate subcommands, all documented in the README and man page. This issue was filed afterward (2026-05-09) by an external user who — despite the feature being present — could not discover it from --help.

Current all-smi --help (verified on main @ d5b678d):

Options:
      --config <PATH>  Override the default TOML config file path. When omitted the loader
                       probes the platform-appropriate locations (see `all-smi config init`
                       for the canonical path). When given, a missing or malformed file
                       produces a hard error; no silent fallback

Gaps:

1. No literal path in --help. The resolved path (e.g. ~/Library/Application Support/all-smi/config.toml on macOS, $XDG_CONFIG_HOME/all-smi/config.toml on Linux, %APPDATA%\all-smi\config.toml on Windows) is never printed. The user is redirected to config init.
2. No side-effect-free discovery. config init writes a file; config print dumps the merged settings (not the source path); config validate echoes a path only when a file already exists. There is no "just tell me where it is / where it would go" command.
3. Man page FILES omits it. docs/man/all-smi.1's .SH FILES lists only hosts.csv; the config path appears only indirectly under the ENERGY ACCOUNTING section.

The path-resolution helpers already exist and are reusable in src/common/paths.rs: default_config_path(), candidate_config_paths(), discover_existing_config().

Note on the original report's "not showing any switches as what can be changed": per-subcommand switches are shown via all-smi <subcommand> --help, and the full set of configurable keys is shown by all-smi config print. The actionable part is discoverability — the help should point users to those.

Proposed Solution

1. Add a "Configuration file" block to --help (primary)

Append a runtime-resolved section to the top-level help, e.g.:

Configuration file:
  Optional TOML file. Precedence: CLI flags > env vars > config file > built-in defaults.
  Active path (this platform):
    /Users/you/Library/Application Support/all-smi/config.toml   (not found)
  Create:  all-smi config init        Inspect merged result:  all-smi config print
  Override path with --config <PATH>.

Because the path is runtime-dependent ($HOME / $XDG_CONFIG_HOME / platform), the current static #[command(after_help = ENERGY_HELP)] must be composed at runtime. With clap's derive API, build the command and inject the text before parsing:

let cmd = Cli::command().after_help(format!("{}\n\n{}", config_help_block(), ENERGY_HELP));
let cli = Cli::from_arg_matches(&cmd.get_matches())?;

config_help_block() uses paths::default_config_path() + paths::discover_existing_config() to print the path and an (active) / (not found) marker. Keep it in after_help (shown for both -h and --help) since the block is short.

2. Add all-smi config path (complementary, recommended)

A read-only command that prints the active path and the candidate search order, with no file writes:

$ all-smi config path
/Users/you/Library/Application Support/all-smi/config.toml   (not found)
search order:
  1. /Users/you/Library/Application Support/all-smi/config.toml
  2. /Users/you/.config/all-smi/config.toml

Optionally support --json for scripts. New ConfigAction::Path variant in src/cli_config.rs + run_path() in src/config_cmd/mod.rs.

3. Update man page FILES (complementary)

Add the per-platform config.toml paths to .SH FILES in docs/man/all-smi.1, mirroring the README configuration table.

4. Reword the --config flag help

So it no longer requires running another command to learn the default location — point at the new "Configuration file" block / config path instead of only config init.

Implementation Notes

• src/cli.rs — compose dynamic after_help; reword the --config doc comment. (Mind the 500-line soft limit noted in the file; the path helper can live in paths.rs or config_cmd.)
• src/main.rs (wherever Cli::parse() runs) — build the command, inject runtime help, then parse via Cli::from_arg_matches.
• src/cli_config.rs — add ConfigAction::Path (+ optional --json).
• src/config_cmd/mod.rs — run_path() reusing paths::*; wire into the run() dispatch.
• src/common/paths.rs — reuse existing helpers; optionally add one small (active)/(not found) formatter shared by the help block and config path.
• docs/man/all-smi.1 — add config paths to .SH FILES.
• README.md — add config path to the subcommands list (the config section already documents paths/precedence).
• Tests — assert --help contains the config-path block; unit-test the config path text + JSON output; keep cargo fmt / clippy clean.

Potential challenges:

• Verify clap derive + dynamic after_help still renders --version and per-subcommand help correctly.
• Avoid duplicating or detaching the existing energy block when composing after_help.
• The printed absolute path reveals the local username — acceptable (it is the user's own machine, consistent with other CLI tools); do not print secrets such as webhook_url.
• Handle the None case (no resolvable home dir) with a clear message instead of an empty/garbled path.

Acceptance Criteria

• all-smi --help and all-smi -h show a "Configuration file" section stating the resolved config path for the current platform plus an (active) / (not found) marker.
• The displayed path matches paths::default_config_path() and honors $XDG_CONFIG_HOME / $HOME (and %APPDATA% on Windows).
• The help block points to config init (create), config print (inspect what can be set), and --config <PATH> (override).
• A read-only way to print the path exists with no file writes (all-smi config path recommended); confirmed it does not create config.toml.
• docs/man/all-smi.1 .SH FILES documents the per-platform config.toml locations.
• The no-home-directory case degrades gracefully with a clear message rather than panicking or printing an empty path.
• Tests cover the help block and the new command; cargo fmt --check, cargo clippy, and cargo test pass.

---

Original Suggestion

Title: [UX] Clearly state the current config file location in the -h / --help switch

Its not at all clear that there is a config file for this app, especially since the --help option is not saying anything about that, and not showing any switches as what can be changed.