docs(cli): clarify hermes -z version boundary and one-shot timeout behavior

[konsisumer]

What changed and why

Per the reporter's corrected findings on issue #25121 (comment on 2026-05-14), the original "hermes -z is rejected on some versions" claim was retracted — there was no raw evidence of the parser rejecting -z. The actual situation is a documentation gap:

• hermes -z / --oneshot was added in v0.12.0 (v2026.4.30); earlier releases only ship hermes chat -q.
• hermes chat -q is the portable cross-version one-shot entry point.
• Neither hermes -z nor hermes chat -q accepts a --timeout flag (verified against hermes_cli/_parser.py — --timeout only exists on the model/login/auth subparsers as a network timeout).

This PR adds a One-Shot / Non-Interactive Invocation section to website/docs/user-guide/cli.md that spells out the version boundary, recommends hermes chat -q for scripts targeting older installs, and shows how to bound run time with an external timeout wrapper. The single-query example in "Running the CLI" now also shows hermes -z alongside hermes chat -q.

Adding an actual --timeout flag to one-shot/chat invocations is a separate feature request and is intentionally not in scope here.

How to test

• Render the docs: cd website && npm install && npm run start, then open /docs/user-guide/cli and confirm the new "One-Shot / Non-Interactive Invocation" section renders, including the table and the :::info admonition.
• Or just review the Markdown diff in website/docs/user-guide/cli.md.
• Doc test suite: pytest tests/website/ -q --timeout=60 (7 passed locally).

What platforms tested on

macOS (Darwin 24.6.0). Change is documentation-only (a single Markdown file); no runtime code paths are touched, so it is platform-independent.

Fixes #25121

[Phantomthedog]

Thanks, this matches the corrected scope of #25121.

I reviewed the PR description and it accurately reflects my follow-up findings: hermes -z works on current main, the real compatibility boundary is v0.12.0+, hermes chat -q is the safer cross-version one-shot entry point, and --timeout support for one-shot/chat would be a separate feature request rather than part of this docs fix.

No objection from me. I'm happy for #25121 to be closed when this PR is merged.

[teknium1]

Thanks for narrowing the original report to the actual documentation gap. Current main has both parser entries (hermes_cli/_parser.py:102-112 and hermes_cli/_parser.py:263-270), while the user guide still shows only chat -q (website/docs/user-guide/cli.md:25-26), so the version-boundary guidance remains useful.

Problems

• The added bare timeout 300 hermes -z ... example in PR commit 393caee003d0337fe65259abb8f6d9d18d5eb1c3 relies on GNU coreutils' timeout, rather than a portable shell command. This conflicts with the PR's platform-independent framing and its macOS test claim.

Suggested changes

• Label that command GNU/Linux/coreutils-specific and add a portable Python subprocess timeout example, or give platform-specific alternatives.

Automated hermes-sweeper review.

[teknium1]

timeout is the GNU coreutils utility rather than a portable shell command. Please label this as GNU/Linux/coreutils-specific and add a portable Python subprocess example or platform-specific alternatives.

[konsisumer]

Closing — on reflection, platform-independent. conflicts with the GNU-only timeout example. If this still seems valuable, please reopen with feedback on what to change.