fix: friendlier first-run help text and no-arg fallback tip (#2)

src/first_commit_ai/cli.py

@@ -7,13 +7,31 @@
 
 from first_commit_ai.client import ChatClient
 
+CUSTOM_EPILOG = """
+Quick Start Flow:
+  1. clone   -> git clone https://github.com/primeodin/first-commit-ai.git
+  2. install -> pip install -e ".[dev]"
+  3. mock    -> python -m first_commit_ai --mock "hi"
+  4. real    -> export OPENAI_API_KEY=sk-... && python -m first_commit_ai "your prompt"
+"""
+
+NO_ARGS_TIP = """Tip: Run with --mock "your prompt" to test offline without an API key.
+See README.md for full usage instructions."""
+
 
 def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(
         prog="first-commit-ai",
-        description="Tiny OpenAI-compatible chat CLI. Use --mock to run without a key.",
+        description="Tiny OpenAI-compatible chat CLI.",
+        epilog=CUSTOM_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    p.add_argument(
+        "prompt",
+        nargs="?",
+        default=None,
+        help="What you want to ask",
     )
-    p.add_argument("prompt", help="What you want to ask")
     p.add_argument(
         "--mock",
         action="store_true",
@@ -24,6 +42,11 @@ def build_parser() -> argparse.ArgumentParser:
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
+
+    if not args.prompt:
+        print(NO_ARGS_TIP)
+        return 0
+
     client = ChatClient.from_env(mock=args.mock)
     try:
         print(client.chat(args.prompt))

tests/test_cli.py

@@ -32,3 +32,24 @@ def test_missing_key_without_mock_fails(monkeypatch):
         assert False, "expected RuntimeError"
     except RuntimeError as exc:
         assert "OPENAI_API_KEY" in str(exc)
+
+
+def test_no_args_prints_tip_and_exits_zero(capsys):
+    code = main([])
+    captured = capsys.readouterr()
+    assert code == 0
+    assert "Tip: Run with --mock" in captured.out
+    assert "README.md" in captured.out
+
+
+def test_help_epilog_shows_flow(capsys):
+    p = build_parser()
+    try:
+        p.parse_args(["--help"])
+    except SystemExit:
+        pass
+    captured = capsys.readouterr()
+    assert "clone   ->" in captured.out
+    assert "install ->" in captured.out
+    assert "mock    ->" in captured.out
+    assert "real    ->" in captured.out