refactor: polish providers cli status

docs/cli/index.md

@@ -211,7 +211,7 @@ Manage chat provider accounts (WhatsApp/Telegram/Discord/Slack/Signal/iMessage).
 
 Subcommands:
 - `providers list`: show configured chat providers and auth profiles (Claude CLI + Codex CLI sync included).
-- `providers status`: check gateway reachability and provider health (`--probe` to verify credentials).
+- `providers status`: check gateway reachability and provider health (`--probe` to verify credentials; use `status --deep` for local-only probes).
 - `providers add`: wizard-style setup when no flags are passed; flags switch to non-interactive mode.
 - `providers remove`: disable by default; pass `--delete` to remove config entries without prompts.
 
@@ -224,6 +224,15 @@ Common options:
 - `--no-usage`: skip provider usage/quota snapshots (OAuth/API-backed only).
 - `--json`: output JSON (includes usage unless `--no-usage` is set).
 
+Examples:
+```bash
+clawdbot providers add --provider telegram --account alerts --name "Alerts Bot" --token $TELEGRAM_BOT_TOKEN
+clawdbot providers add --provider discord --account work --name "Work Bot" --token $DISCORD_BOT_TOKEN
+clawdbot providers remove --provider discord --account work --delete
+clawdbot providers status --probe
+clawdbot status --deep
+```
+
 ### `pairing`
 Approve DM pairing requests across providers.
 

src/cli/command-options.ts

@@ -0,0 +1,11 @@
+import type { Command } from "commander";
+
+export function hasExplicitOptions(
+  command: Command,
+  names: readonly string[],
+): boolean {
+  if (typeof command.getOptionValueSource !== "function") {
+    return false;
+  }
+  return names.some((name) => command.getOptionValueSource(name) === "cli");
+}

src/cli/program.ts

@@ -662,7 +662,8 @@ Examples:
   clawdbot status --json            # machine-readable output
   clawdbot status --usage           # show provider usage/quota snapshots
   clawdbot status --deep            # run provider probes (WA + Telegram + Discord + Slack + Signal)
-  clawdbot status --deep --timeout 5000 # tighten probe timeout`,
+  clawdbot status --deep --timeout 5000 # tighten probe timeout
+  clawdbot providers status         # gateway provider runtime + probes`,
     )
     .action(async (opts) => {
       const verbose = Boolean(opts.verbose || opts.debug);

src/cli/providers-cli.ts

@@ -7,6 +7,7 @@ import {
   providersStatusCommand,
 } from "../commands/providers.js";
 import { defaultRuntime } from "../runtime.js";
+import { hasExplicitOptions } from "./command-options.js";
 
 const optionNamesAdd = [
   "provider",
@@ -30,18 +31,6 @@ const optionNamesAdd = [
 
 const optionNamesRemove = ["provider", "account", "delete"] as const;
 
-function hasExplicitOptions(
-  command: Command,
-  names: readonly string[],
-): boolean {
-  return names.some((name) => {
-    if (typeof command.getOptionValueSource !== "function") {
-      return false;
-    }
-    return command.getOptionValueSource(name) === "cli";
-  });
-}
-
 export function registerProvidersCli(program: Command) {
   const providers = program
     .command("providers")
@@ -64,7 +53,7 @@ export function registerProvidersCli(program: Command) {
 
   providers
     .command("status")
-    .description("Show gateway provider status")
+    .description("Show gateway provider status (use status --deep for local)")
     .option("--probe", "Probe provider credentials", false)
     .option("--timeout <ms>", "Timeout in ms", "10000")
     .option("--json", "Output JSON", false)

src/commands/providers.ts

@@ -59,6 +59,11 @@ const CHAT_PROVIDERS = [
 
 type ChatProvider = (typeof CHAT_PROVIDERS)[number];
 
+function docsLink(path: string, label?: string): string {
+  const url = `${DOCS_ROOT}${path}`;
+  return formatTerminalLink(url, label ?? url);
+}
+
 type ProvidersListOptions = {
   json?: boolean;
   usage?: boolean;
@@ -691,7 +696,12 @@ export async function providersStatusCommand(
         }
         const accountId =
           typeof account.accountId === "string" ? account.accountId : "default";
-        const labelText = `${label} ${accountId}`;
+        const name =
+          typeof account.name === "string" ? account.name.trim() : "";
+        const labelText = `${label} ${formatAccountLabel({
+          accountId,
+          name: name || undefined,
+        })}`;
         return `- ${labelText}: ${bits.join(", ")}`;
       });
 
@@ -744,6 +754,10 @@ export async function providersStatusCommand(
       );
     }
 
+    lines.push("");
+    lines.push(
+      `Tip: ${docsLink("/cli#status", "status --deep")} runs local probes without a gateway.`,
+    );
     runtime.log(lines.join("\n"));
   } catch (err) {
     runtime.error(`Gateway not reachable: ${String(err)}`);