Build this tool: Description-Free Video Scanner — Bulk Audit + Rewrite Tool
Product folder name: Description-Free Video Scanner
App version target: 2.0.0

PRODUCT BRIEF
Scan a YouTube playlist or whole channel with the YouTube Data API. Download
every video description, flag EMPTY or SHORT ones, export a CSV named
{channel}_{timestamp}.csv, and rewrite flagged descriptions with Gemini.
Optional custom rewrite prompt box — if empty, use the built-in default style.
No local / manual paste mode. YouTube API required to scan. Gemini required to rewrite.

CONTEXT
Difficulty: Easy–Medium
Category: Howto & Style

TREND HOOK
Majority of trending list has blank "Desc:" fields despite millions of views.

VIDEO ANGLE
Short: "I found 15 million-view videos with BLANK descriptions."
Long: build scanner → run on a real channel/playlist → export CSV → rewrite
empty/short ones with Gemini (optional custom prompt).

WHY THIS TOOL
Directly proven by the data — huge opportunity for a simple audit + rewrite tool.
Distinct from Description Link Rot Checker (that one checks links inside
descriptions). This one finds missing/short descriptions and helps rewrite them.

STACK (standalone desktop app)
- Python 3 + tkinter GUI — standalone desktop tool (not a website).
- Even if a brief says "web app", ship a Python desktop GUI for v1/v2.
- Include:
  - description_free_video_scanner.py (main)
  - casey_youtube_setup.py (shared YouTube Data API key helper)
  - casey_gemini.py (shared Gemini key/model helper + pack_gemini_settings_row)
  - YOUTUBE_SETUP.txt
  - requirements.txt
  - run_description_free_video_scanner.bat
  - build_exe.bat (PyInstaller)
  - exports/ folder for CSV + TXT output
- Smoke (offline synthetic, no live keys):
  python description_free_video_scanner.py --smoke

GUI RULES
- Clean dark UI (Casey Builds It palette: BG #0b0e1c, amber accents, teal brand).
- Hero: "Description-Free Video Scanner" + short lead + How to use line.
- How to use:
  Save YouTube key → paste playlist/channel → Scan YouTube →
  Export CSV ({channel}_{timestamp}.csv) → optional custom rewrite prompt →
  Rewrite flagged (Gemini) → Export rewrites.
- Inputs:
  - YouTube API key (shared) + Save + Help
  - Playlist / channel (URL, playlist ID, channel URL, or @handle)
  - Title filter (optional)
  - Short under (chars) — default 80
  - Max videos — default 100 (cap ~500)
  - Category hint (DarkSelect — for Gemini rewrites)
  - Gemini API key + Model + "Rewrite flagged with Gemini" checkbox
    (use casey_gemini.pack_gemini_settings_row — NOT mount_gemini_key_row)
  - Your rewrite prompt (optional ScrolledText) — leave blank for default
  - Buttons: Scan YouTube, Rewrite flagged descriptions,
    Copy report, Export CSV, Export report, Export descriptions, Export rewrites
- DarkSelect for category (NEVER ttk.Combobox; no grab_set).
- Handle window close with WM_DELETE_WINDOW.
- All network work in background threads; update UI with after(...).
- On Gemini failure: keep scan results, show error, do not wipe the report.

APIs & KEYS (required — no offline scan path in the product UI)
- YouTube Data API key
  Store: %%LOCALAPPDATA%%\CaseyBuilds\youtube_settings.json
  Shared across Casey tools via casey_youtube_setup.py
  Uses: playlistItems, channels (uploads playlist), videos.list (snippet/description)
  Resolve: playlist URL/ID OR channel URL / @handle / UC… → uploads playlist
- Gemini API key + model
  Store: %%LOCALAPPDATA%%\CaseyBuilds\gemini_settings.json
  Shared via casey_gemini.py
  Default model: gemini-2.5-flash-lite (accept typed model ids e.g. gemini-3.1-flash-lite)
  Used only for description rewrites
- Never hardcode keys or secrets into source / EXE.
- Label YouTube vs Gemini fields clearly.

CORE FLOW
1. Save YouTube Data API key (once).
2. Paste playlist URL OR channel / @handle.
3. Optional: title filter, short-char threshold, max videos, category hint.
4. Scan YouTube:
   - Resolve source → playlist id + friendly channel name
   - List video IDs (paginated)
   - Batch videos.list for titles + descriptions
   - Classify each: EMPTY (0 chars) / SHORT (< threshold) / OK
5. Auto-export after scan:
   - CSV → exports/{channel}_{YYYYMMDD_HHMMSS}.csv
   - Descriptions TXT → exports/{channel}_{timestamp}_descriptions.txt
6. Optional: paste a custom rewrite prompt (blank = default instructions).
7. Rewrite flagged (EMPTY + SHORT) with Gemini:
   - If custom prompt empty → DEFAULT_REWRITE_INSTRUCTIONS
   - If custom filled → use user's instructions
   - Always append: category, title, URL, current description
   - Return paste-ready description body only
8. Exports:
   - Export CSV (channel + timestamp filename, UTF-8-SIG)
     Columns: channel, status, title, url, video_id, desc_len, note,
     description, rewrite, scanned_at, source
   - Export report / descriptions / rewrites as TXT with same channel+timestamp stem

REWRITE PROMPT BEHAVIOR
- UI box: "Your rewrite prompt (optional — leave blank for default)"
- Empty → built-in default (plain text, no invented facts, brand-safe, CTA, ~400–900 chars)
- Filled → user instructions replace the default style block; video context still appended
- Status line should note "custom prompt" vs "default prompt" while rewriting

FILENAME RULES
- Prefer resolved channel title / customUrl / handle for the slug
- Sanitize to safe filename: slug_for_filename()
- Pattern: {channel}_{YYYYMMDD_HHMMSS}.csv
  Example: CaseyBuildsIt_20260806_141113.csv

OUT OF SCOPE
- No OAuth / uploading descriptions back to YouTube (API key is read-only)
- No local title/URL paste mode
- No link-rot checking (separate tool)

OUTPUT
- Runnable standalone Python app
- requirements.txt + run bat + optional EXE build script
- In-app how-to line matching the flow above
- Smoke path for offline logic checks (--smoke)