From c82542f14b7c9cc6dc7875bd538573026d78cbd9 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Tue, 14 Jul 2026 14:23:50 +0000
Subject: [PATCH 1/3] feat(ux): add hint to missing zap-baseline.py error

---
 .Jules/palette.md           | 3 +++
 scanner/cli/appguardrail.py | 4 +++-
 2 files changed, 6 insertions(+), 1 deletion(-)

diff --git a/.Jules/palette.md b/.Jules/palette.md
index 1c4b835..699df7d 100644
--- a/.Jules/palette.md
+++ b/.Jules/palette.md
@@ -27,3 +27,6 @@
 ## 2024-07-13 - CLI 출력의 영문법적 복수형 및 에러 메시지 힌트 개선
 **Learning:** CLI 출력에서 `file(s)`, `issue(s)`, `rule(s) excluded`와 같이 괄호를 사용한 복수형 표기법은 가독성을 떨어뜨리고 투박한(developer-centric) 느낌을 줍니다. 또한, 에러 발생 시 단순 예외 내용만 출력하는 것보다 즉시 실행 가능한 해결책(Hint)을 함께 제공하는 것이 CLI 사용자 경험(DX) 향상에 매우 효과적입니다.
 **Action:** 조건부 f-string(예: `s_suffix = "s" if count != 1 else ""`)을 활용하여 동적으로 정확한 복수형 단어(file/files)를 출력하도록 개선하고, 예외 발생 로직에는 항상 `💡 Hint:`를 포함하여 후속 액션을 안내하도록 표준화해야 합니다. (단, Python 3.12 환경의 `black` 포매터 호환성을 위해 백슬래시가 포함된 중첩 f-string 사용을 피하고 변수 추출을 권장합니다.)
+## 2026-10-27 - CLI Error UX Insights
+**Learning:** Users encountering missing executables (like zap-baseline.py) need actionable hints. A simple file missing error doesn't explain what to install or configure.
+**Action:** Added a 💡 Hint to the RuntimeError to explicitly instruct users to install OWASP ZAP and ensure it is in their PATH, improving standard CLI DX.
diff --git a/scanner/cli/appguardrail.py b/scanner/cli/appguardrail.py
index 94e75ef..8ae4fe8 100644
--- a/scanner/cli/appguardrail.py
+++ b/scanner/cli/appguardrail.py
@@ -2714,7 +2714,9 @@ def _run_zap_baseline(target_url: str):
         raise RuntimeError("--zap-baseline requires an http(s) URL.")
     zap = shutil.which("zap-baseline.py")
     if not zap:
-        raise RuntimeError("zap-baseline.py executable not found.")
+        raise RuntimeError(
+            "zap-baseline.py executable not found.\n💡 Hint: Install OWASP ZAP and ensure zap-baseline.py is in your PATH."
+        )
 
     with tempfile.TemporaryDirectory() as tmpdir:
         report_path = Path(tmpdir) / "zap-baseline.json"

From 9c25b788a5fc5cc4c4403b02277ce30c0ce604fc Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Tue, 14 Jul 2026 14:29:38 +0000
Subject: [PATCH 2/3] feat(ux): add hint to missing zap-baseline.py error


From 73f4650517800f8ea5d52e26eecd5d4916047603 Mon Sep 17 00:00:00 2001
From: seonghobae <8172694+seonghobae@users.noreply.github.com>
Date: Tue, 14 Jul 2026 15:08:39 +0000
Subject: [PATCH 3/3] feat(ux): add hint to missing zap-baseline.py error