Polish onboarding and CLI help

tests/test_cli.py

@@ -3,13 +3,59 @@ from __future__ import annotations
 import argparse
 import json
 import sys
-from typing import Any
+from typing import Any, cast
 
 import pytest
 
 import pyro_mcp.cli as cli
 
 
+def _subparser_choice(parser: argparse.ArgumentParser, name: str) -> argparse.ArgumentParser:
+    subparsers = getattr(parser, "_subparsers", None)
+    if subparsers is None:
+        raise AssertionError("parser does not define subparsers")
+    group_actions = cast(list[Any], subparsers._group_actions)  # noqa: SLF001
+    if not group_actions:
+        raise AssertionError("parser subparsers are empty")
+    choices = cast(dict[str, argparse.ArgumentParser], group_actions[0].choices)
+    return choices[name]
+
+
+def test_cli_help_guides_first_run() -> None:
+    parser = cli._build_parser()
+    help_text = parser.format_help()
+
+    assert "Suggested first run:" in help_text
+    assert "pyro doctor" in help_text
+    assert "pyro env pull debian:12" in help_text
+    assert "pyro run debian:12 -- git --version" in help_text
+    assert "Use `pyro mcp serve` only after the CLI validation path works." in help_text
+
+
+def test_cli_subcommand_help_includes_examples_and_guidance() -> None:
+    parser = cli._build_parser()
+
+    run_help = _subparser_choice(parser, "run").format_help()
+    assert "pyro run debian:12 -- git --version" in run_help
+    assert "Opt into host-side compatibility execution" in run_help
+    assert "Enable outbound guest networking" in run_help
+
+    env_help = _subparser_choice(_subparser_choice(parser, "env"), "pull").format_help()
+    assert "Environment name from `pyro env list`" in env_help
+    assert "pyro env pull debian:12" in env_help
+
+    doctor_help = _subparser_choice(parser, "doctor").format_help()
+    assert "Check host prerequisites and embedded runtime health" in doctor_help
+    assert "pyro doctor --json" in doctor_help
+
+    demo_help = _subparser_choice(parser, "demo").format_help()
+    assert "pyro demo ollama --verbose" in demo_help
+
+    mcp_help = _subparser_choice(_subparser_choice(parser, "mcp"), "serve").format_help()
+    assert "Expose pyro tools over stdio for an MCP client." in mcp_help
+    assert "Use this from an MCP client config after the CLI evaluation path works." in mcp_help
+
+
 def test_cli_run_prints_json(
     monkeypatch: pytest.MonkeyPatch,
     capsys: pytest.CaptureFixture[str],