From a1dbb5115fb0a393ef2d4dc7c89c9ff30fb7329f Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 26 Mar 2026 19:03:44 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Add=20actionable=20in?=
 =?UTF-8?q?structions=20to=20checkpoint=20empty=20state?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: ivangegovdve-sudo <225339531+ivangegovdve-sudo@users.noreply.github.com>
---
 .Jules/palette.md                       |  4 ++++
 src/python_learning_orchestrated/cli.py |  5 ++++-
 tests/test_cli_smoke.py                 | 16 ++++++++++++++++
 3 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/.Jules/palette.md b/.Jules/palette.md
index 35ad244..bfbf281 100644
--- a/.Jules/palette.md
+++ b/.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.
diff --git a/src/python_learning_orchestrated/cli.py b/src/python_learning_orchestrated/cli.py
index 31751d2..b78eeed 100644
--- a/src/python_learning_orchestrated/cli.py
+++ b/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:
diff --git a/tests/test_cli_smoke.py b/tests/test_cli_smoke.py
index e54e34c..720eb4d 100644
--- a/tests/test_cli_smoke.py
+++ b/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