🎨 Palette: Add actionable instructions to checkpoint empty state

.Jules/palette.md

@@ -5,3 +5,7 @@
 ## 2024-05-24 - CLI Output Scannability and Human-Readability
 **Learning:** In text-based CLI menus, using internal identifiers (like `lesson-1`) and verbose status strings (like `pending` or `completed`) makes lists hard to scan and feels too technical.
 **Action:** When displaying lists of items with states, use familiar visual symbols (like `[x]` vs `[ ]`) and human-readable titles (like "Variables") to improve scannability and create a more friendly, intuitive interface.
+
+## 2025-03-26 - Actionable Empty States in CLI
+**Learning:** Empty states (e.g., "No checkpoints found.") can feel like dead-ends to users who don't know how to create the missing resource.
+**Action:** Always pair empty state messages with clear, actionable instructions or commands on how to create the missing resource to improve user experience and avoid dead-ends.

src/python_learning_orchestrated/cli.py

@@ -223,7 +223,10 @@ def main(
         if args.checkpoint_command == "list":
             checkpoints = checkpoint_store.list_checkpoints()
             if not checkpoints:
-                output_fn("No checkpoints found.")
+                output_fn(
+                    "No checkpoints found. "
+                    "Create one with: checkpoint create <name>"
+                )
                 return
             output_fn(f"Checkpoints ({len(checkpoints)}):")
             for checkpoint in checkpoints:

tests/test_cli_smoke.py

@@ -216,3 +216,19 @@ def test_cli_checkpoint_create_fails_on_existing_name(
         )
     else:
         raise AssertionError("Expected SystemExit for duplicate checkpoint name")
+
+def test_cli_checkpoint_list_empty_state_has_actionable_instructions(
+    tmp_path, capsys, monkeypatch
+) -> None:
+    checkpoint_dir = tmp_path / "checkpoints"
+
+    checkpoint_store_class = cli_module.CheckpointStore
+    monkeypatch.setattr(
+        cli_module,
+        "CheckpointStore",
+        lambda: checkpoint_store_class(checkpoint_dir),
+    )
+
+    main(["checkpoint", "list"])
+    list_output = capsys.readouterr().out
+    assert "No checkpoints found. Create one with: checkpoint create <name>" in list_output