feat: standardize logging with console + file separation

- Console: Compressed status workflow ([plan] ✓, [execute] ✓, [answer] ✓)
- Files: log/ folder with full LLM context and transcripts
- Update CLAUDE.md with logging standard
- Add log/ to .gitignore

Separates status updates (console) from debugging details (log/ files).

Co-Authored-By: Claude <noreply@anthropic.com>

.gitignore

@@ -37,6 +37,9 @@ input/*
 # Runtime cache (not in git, served via app download)
 _cache/
 
+# Runtime logs (not in git, for debugging and analysis)
+log/
+
 # Testing
 .pytest_cache/
 .coverage

CLAUDE.md

@@ -1,4 +1,29 @@
 # Project-Specific Instructions
 
-[Leave empty unless project requires special behavior]
 [Inherits all rules from ~/.claude/CLAUDE.md]
+
+## Logging Standard
+
+**Console Output (Status Workflow):**
+- **Compressed status updates:** `[node] ✓ result` or `[node] ✗ error`
+- **Progress indicators:** `[1/1] Processing task_id`, `[1/20]` for batch
+- **Key milestones only:** 3-4 statements vs verbose logs
+- **Node labels:** `[plan]`, `[execute]`, `[answer]` with success/failure
+
+**Log Files (log/ folder):**
+- **llm_context_TIMESTAMP.txt** - Full LLM prompts, evidence, answers for debugging
+- **{video_id}_transcript.txt** - Raw transcripts from YouTube/Whisper
+- **Purpose:** Post-run analysis, context preservation, audit trail
+- **Format:** Structured headers with timestamp, question, evidence items, full content
+
+**Log Format Examples:**
+```
+[plan] ✓ 660 chars
+[execute] 1 tool(s) selected
+[1/1] youtube_transcript ✓
+[execute] 1 tools, 1 evidence
+[answer] ✓ 3
+Context saved to: log/llm_context_20260113_022706.txt
+```
+
+**Note:** Explicit user request overrides global rule about "no logs/ folder"

src/agent/llm_client.py

@@ -1108,16 +1108,16 @@ Examples of bad answers (too verbose):
 Extract the factoid answer from the evidence above. Return only the factoid, nothing else."""
 
     # ============================================================================
-    # SAVE LLM CONTEXT TO CACHE - For debugging and comparison
+    # SAVE LLM CONTEXT TO LOG - For debugging and comparison
     # ============================================================================
     from pathlib import Path
     import datetime
 
-    cache_dir = Path("_cache")
-    cache_dir.mkdir(exist_ok=True)
+    log_dir = Path("log")
+    log_dir.mkdir(exist_ok=True)
 
     timestamp = datetime.datetime.now().strftime("%Y%m%d_%H%M%S")
-    context_file = cache_dir / f"llm_context_{timestamp}.txt"
+    context_file = log_dir / f"llm_context_{timestamp}.txt"
 
     with open(context_file, "w", encoding="utf-8") as f:
         f.write("=" * 80 + "\n")

src/tools/youtube.py

@@ -54,7 +54,7 @@ logger = logging.getLogger(__name__)
 
 def save_transcript_to_cache(video_id: str, text: str, source: str) -> None:
     """
-    Save transcript to _cache folder for debugging.
+    Save transcript to log/ folder for debugging.
 
     Args:
         video_id: YouTube video ID
@@ -62,10 +62,10 @@ def save_transcript_to_cache(video_id: str, text: str, source: str) -> None:
         source: "api" or "whisper"
     """
     try:
-        cache_dir = Path("_cache")
-        cache_dir.mkdir(exist_ok=True)
+        log_dir = Path("log")
+        log_dir.mkdir(exist_ok=True)
 
-        cache_file = cache_dir / f"{video_id}_transcript.txt"
+        cache_file = log_dir / f"{video_id}_transcript.txt"
         with open(cache_file, "w", encoding="utf-8") as f:
             f.write(f"# YouTube Transcript\n")
             f.write(f"# Video ID: {video_id}\n")
@@ -74,9 +74,9 @@ def save_transcript_to_cache(video_id: str, text: str, source: str) -> None:
             f.write(f"# Generated: {__import__('datetime').datetime.now().isoformat()}\n")
             f.write(f"\n{text}\n")
 
-        logger.info(f"Transcript saved to cache: {cache_file}")
+        logger.info(f"Transcript saved: {cache_file}")
     except Exception as e:
-        logger.warning(f"Failed to save transcript to cache: {e}")
+        logger.warning(f"Failed to save transcript: {e}")
 
 
 # ============================================================================