From 192d2b63f2d02bbd0eed5629ae778d71a4efed73 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 21:23:25 -0700
Subject: [PATCH] docs: align videodb event directory handling

---
 skills/videodb/SKILL.md               | 13 ++++++++-----
 skills/videodb/scripts/ws_listener.py |  3 +++
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/skills/videodb/SKILL.md b/skills/videodb/SKILL.md
index 02c417d9..5742e59d 100644
--- a/skills/videodb/SKILL.md
+++ b/skills/videodb/SKILL.md
@@ -303,10 +303,11 @@ Use `ws_listener.py` to capture WebSocket events during recording sessions. Desk
 
 #### Quick Start
 
-1. **Start listener**: `python scripts/ws_listener.py --clear &`
-2. **Get WebSocket ID**: `cat "${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}/videodb_ws_id"`
-3. **Run capture code** (see reference/capture.md for the full workflow)
-4. **Events written to**: `${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}/videodb_events.jsonl`
+1. **Choose state dir**: `STATE_DIR="${VIDEODB_EVENTS_DIR:-$HOME/.local/state/videodb}"`
+2. **Start listener**: `VIDEODB_EVENTS_DIR="$STATE_DIR" python scripts/ws_listener.py --clear "$STATE_DIR" &`
+3. **Get WebSocket ID**: `cat "$STATE_DIR/videodb_ws_id"`
+4. **Run capture code** (see reference/capture.md for the full workflow)
+5. **Events written to**: `$STATE_DIR/videodb_events.jsonl`
 
 Use `--clear` whenever you start a fresh capture run so stale transcript and visual events do not leak into the new session.
 
@@ -314,10 +315,12 @@ Use `--clear` whenever you start a fresh capture run so stale transcript and vis
 
 ```python
 import json
+import os
 import time
 from pathlib import Path
 
-events_file = Path.home() / ".local" / "state" / "videodb" / "videodb_events.jsonl"
+events_dir = Path(os.environ.get("VIDEODB_EVENTS_DIR", Path.home() / ".local" / "state" / "videodb"))
+events_file = events_dir / "videodb_events.jsonl"
 events = []
 
 if events_file.exists():
diff --git a/skills/videodb/scripts/ws_listener.py b/skills/videodb/scripts/ws_listener.py
index 105aabc7..0ec20105 100644
--- a/skills/videodb/scripts/ws_listener.py
+++ b/skills/videodb/scripts/ws_listener.py
@@ -89,6 +89,9 @@ def parse_args() -> tuple[bool, Path]:
             output_dir = arg
     
     if output_dir is None:
+        events_dir = os.environ.get("VIDEODB_EVENTS_DIR")
+        if events_dir:
+            return clear, ensure_private_dir(Path(events_dir))
         return clear, ensure_private_dir(default_output_dir())
 
     return clear, ensure_private_dir(Path(output_dir))