feat(help): dedup usage --format, tg help format topic-help, voice-setup status glyph

[alex-mextner]

Why

The ROADMAP heading "tg help specifics" (CTO 2026-06-16) queued three help-UX fixes to land with the tg-cli help work (the --tag + colorize landed in #36; this is the follow-up increment). None of the three were done on main.

What

1. Usage no longer repeats [--format plain|html] on every line. It was duplicated 8× across the usage examples. --format is a global modifier — shown ONCE in Options: now, with a one-line note that the global options apply to any send form.

2. tg help format — standard topic-help, replacing the bespoke --format-help flag.

• tg help format → the formatting reference (byte-identical to the old --format-help).
• tg help (no topic) → the main help (which now lists the available topics).
• tg help <unknown> → a 3-part WHAT/WHY/HOW error on stderr, exit 1.
• --format-help is kept as a back-compat alias (an agent-facing tool — older scripts/skills that learned the flag don't break). tg --help advertises the canonical tg help format form.

3. tg voice setup shows actual STATUS — green ✓ when configured, yellow ○ when pending (the install-* state principle). The glyph is plain unicode so the SAME onboardingMessage string is meaningful on BOTH surfaces: colorizeVoiceStatus colors it for the terminal (CLI path only), while the daemon's Telegram onboarding reply stays ANSI-free (no escape-code garbage in chat).

Docs synced to the tg help format form (AGENTS.md, install-skill SKILL.md). Version 1.13.0 → 1.14.0 + CHANGELOG; AGENTS test count 1066 → 1074.

Tests

bun test: 1074 pass / 0 fail (+8 new across cli-subprocess, voice, help-color):

• tg help format prints the reference; --format-help alias is byte-identical; bare tg help prints main help; tg help bogus errors 3-part non-zero; --help advertises tg help format.
• onboardingMessage leads with ✓/○; is ANSI-free; colorizeVoiceStatus colors only the glyph (green ✓ / yellow ○) and is a no-op when disabled.

Visual proof

$ tg --help        # usage block — NO repeated [--format] lines
  tg "text message"
  tg --photo screen.png "caption"
  tg --file doc.pdf "caption"
  ...
Help topics (`tg help <topic>`):
  format   what Telegram message formatting supports (HTML tags / entities)

$ tg help bogus
Error: unknown help topic 'bogus'. Available topics: format. See `tg help`.   (exit 1)

tg help format and tg --format-help diff = IDENTICAL. The colorized tg voice setup status (green ✓ configured / yellow ○ pending) is attached below as a terminal render.

Note

The prescribed pre-commit review --staged multi-model gate could not run: the installed review binary is broken on this host (ModuleNotFoundError: reviewlib; the review-cli repo is absent at ~/.files/repos/review-cli). The CI review-threads gate covers this PR; I self-reviewed the staged diff. Flagging the tooling breakage explicitly.

🤖 Generated with Claude Code

[alex-mextner]

Visual proof — tg voice setup status glyph (terminal render)

Green ✓ when voice transcription is configured, yellow ○ when pending — the install-* state principle applied to voice setup. The glyph is plain unicode (NOT ANSI) so the daemon's Telegram onboarding reply carries the SAME ✓/○ without escape codes; only the CLI terminal path is colorized.

(Rendered from the real colorizeVoiceStatus(onboardingMessage(verdict), true) output via headless Chrome — the actual production strings.)