dashcam 0.8.4 → 1.0.1-beta.2

package/.dashcam/cli-config.json

@@ -0,0 +1,3 @@
+{
+  "/tmp/test-cli-log.txt": true
+}

package/.dashcam/recording.log

@@ -0,0 +1,135 @@
+23:53:59.852 [info] Started tracking logs for /tmp/test-cli-log.txt
+23:53:59.940 [info] Generated temp file path
+23:53:59.941 [info] Wrote temp file info to disk
+23:53:59.941 [info] Starting recording with options:
+23:53:59.961 [info] FFmpeg process spawned
+Background recording started
+Background recording started
+23:53:59.987 [info] Started tracking logs for /tmp/test-cli-log.txt
+23:53:59.987 [info] Started new logs tracker instance
+23:53:59.988 [info] Recording process started successfully
+23:53:59.988 [info] Background recording signal handlers registered
+23:53:59.995 [info] FFmpeg output: ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
+  built with Apple clang version 13.1.6 (clang-1316.0.21.2.5)
+  configuration: --prefix=/Volumes/tempdisk/sw --extra-cflags=-fno-stack-check --arch=arm64 --cc=/usr/bin/clang --enable-gpl --enable-libvmaf --enable-libbluray --enable-libopenjpeg --enable-libopus --enable-libmp3lame --enable-libx264 --enable-libx265 --enable-libvpx --enable-libwebp --enable-libass --enable-libfreetype --enable-fontconfig --enable-libtheora --enable-libvorbis --enable-libsnappy --enable-libaom --enable-libvidstab --enable-libzimg --enable-libsvtav1 --enable-libkvazaar --enable-version3 --pkg-config-flags=--static --enable-ffplay --enable-postproc --enable-nonfree --enable-neon --enable-runtime-cpudetect --disable-indev=qtkit --disable-indev=x11grab_xcb
+  libavutil      58.  2.100 / 58.  2.100
+  libavcodec     60.  3.100 / 60.  3.100
+  libavformat    60.  3.100 / 60.  3.100
+  libavdevice    60.  1.100 / 60.  1.100
+  libavfilter     9.  3.100 /  9.  3.100
+  libswscale      7.  1.100 /  7.  1.100
+  libswresample   4. 10.100 /  4. 10.100
+  libpostproc    57.  1.100 / 57.  1.100
+23:54:00.583 [info] FFmpeg output: objc[43042]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+objc[43042]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+objc[43042]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+[AVFoundation indev @ 0x15bf04e90] Configuration of video device failed, falling back to default.
+23:54:00.584 [error] PERMISSION ISSUE DETECTED: Screen recording failed. This happens because the Node.js subprocess doesn't inherit VS Code's screen recording permissions.
+23:54:00.585 [error] SOLUTION: Add Node.js to screen recording permissions:
+23:54:00.585 [error] 1. Open System Preferences > Security & Privacy > Privacy > Screen Recording
+23:54:00.585 [error] 2. Click the lock to unlock
+23:54:00.585 [error] 3. Click the + button and add: /usr/local/bin/node (or your Node.js installation path)
+23:54:00.585 [error] 4. Alternatively, find node with: which node
+23:54:00.585 [error] 5. Restart the terminal after adding permissions
+23:54:02.962 [warn] Temp file not created yet
+23:54:05.323 [info] === STOP SIGNAL FILE DETECTED ===
+23:54:05.324 [info] === SHUTDOWN SIGNAL RECEIVED ===
+Stopping background recording...
+23:54:05.325 [info] Background recording shutdown initiated
+23:54:05.325 [info] Stopping recording
+23:54:11.594 [info] Looking for temp file
+DEBUG: Looking for temp file {
+  inMemory: '/Users/ianjennings/Development/dashcam-cli-minimal/tmp/recordings/temp-1761713639939.webm',
+  infoFileExists: true,
+  infoPath: '/Users/ianjennings/Development/dashcam-cli-minimal/.dashcam/temp-file.json'
+}
+23:54:11.601 [info] Debug: temp file check
+23:54:11.606 [info] Enhanced application tracking stopped
+23:54:11.608 [error] Error in background recording: Recording file is empty or missing
+Error in background recording: Recording file is empty or missing
+23:54:11.608 [info] Cleaning up background recording process
+23:54:36.456 [info] Started tracking logs for /tmp/test-cli-log.txt
+23:54:36.554 [info] Generated temp file path
+23:54:36.555 [info] Wrote temp file info to disk
+23:54:36.555 [info] Starting recording with options:
+23:54:36.578 [info] FFmpeg process spawned
+Background recording started
+Background recording started
+23:54:36.660 [info] Started tracking logs for /tmp/test-cli-log.txt
+23:54:36.661 [info] Started new logs tracker instance
+23:54:36.661 [info] Recording process started successfully
+23:54:36.661 [info] Background recording signal handlers registered
+23:54:36.673 [info] FFmpeg output: ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
+  built with Apple clang version 13.1.6 (clang-1316.0.21.2.5)
+  configuration: --prefix=/Volumes/tempdisk/sw --extra-cflags=-fno-stack-check --arch=arm64 --cc=/usr/bin/clang --enable-gpl --enable-libvmaf --enable-libbluray --enable-libopenjpeg --enable-libopus --enable-libmp3lame --enable-libx264 --enable-libx265 --enable-libvpx --enable-libwebp --enable-libass --enable-libfreetype --enable-fontconfig --enable-libtheora --enable-libvorbis --enable-libsnappy --enable-libaom --enable-libvidstab --enable-libzimg --enable-libsvtav1 --enable-libkvazaar --enable-version3 --pkg-config-flags=--static --enable-ffplay --enable-postproc --enable-nonfree --enable-neon --enable-runtime-cpudetect --disable-indev=qtkit --disable-indev=x11grab_xcb
+  libavutil      58.  2.100 / 58.  2.100
+  libavcodec     60.  3.100 / 60.  3.100
+  libavformat    60.  3.100 / 60.  3.100
+  libavdevice    60.  1.100 / 60.  1.100
+  libavfilter     9.  3.100 /  9.  3.100
+  libswscale      7.  1.100 /  7.  1.100
+  libswresample   4. 10.100 /  4. 10.100
+  libpostproc    57.  1.100 / 57.  1.100
+23:54:37.202 [info] FFmpeg output: objc[43240]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+objc[43240]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+objc[43240]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+[AVFoundation indev @ 0x150904880] Configuration of video device failed, falling back to default.
+23:54:37.203 [error] PERMISSION ISSUE DETECTED: Screen recording failed. This happens because the Node.js subprocess doesn't inherit VS Code's screen recording permissions.
+23:54:37.204 [error] SOLUTION: Add Node.js to screen recording permissions:
+23:54:37.205 [error] 1. Open System Preferences > Security & Privacy > Privacy > Screen Recording
+23:54:37.205 [error] 2. Click the lock to unlock
+23:54:37.205 [error] 3. Click the + button and add: /usr/local/bin/node (or your Node.js installation path)
+23:54:37.205 [error] 4. Alternatively, find node with: which node
+23:54:37.240 [error] 5. Restart the terminal after adding permissions
+23:54:39.580 [warn] Temp file not created yet
+23:55:03.729 [warn] Failed to get active window
+23:55:07.654 [info] Started tracking logs for /tmp/test-cli-log.txt
+23:55:07.783 [info] Generated temp file path
+23:55:07.783 [info] Wrote temp file info to disk
+23:55:07.784 [info] Starting recording with options:
+23:55:07.801 [info] FFmpeg process spawned
+Background recording started
+Background recording started
+23:55:07.825 [info] Started tracking logs for /tmp/test-cli-log.txt
+23:55:07.825 [info] Started new logs tracker instance
+23:55:07.825 [info] Recording process started successfully
+23:55:07.826 [info] Background recording signal handlers registered
+23:55:07.835 [info] FFmpeg output: ffmpeg version 6.0 Copyright (c) 2000-2023 the FFmpeg developers
+  built with Apple clang version 13.1.6 (clang-1316.0.21.2.5)
+  configuration: --prefix=/Volumes/tempdisk/sw --extra-cflags=-fno-stack-check --arch=arm64 --cc=/usr/bin/clang --enable-gpl --enable-libvmaf --enable-libbluray --enable-libopenjpeg --enable-libopus --enable-libmp3lame --enable-libx264 --enable-libx265 --enable-libvpx --enable-libwebp --enable-libass --enable-libfreetype --enable-fontconfig --enable-libtheora --enable-libvorbis --enable-libsnappy --enable-libaom --enable-libvidstab --enable-libzimg --enable-libsvtav1 --enable-libkvazaar --enable-version3 --pkg-config-flags=--static --enable-ffplay --enable-postproc --enable-nonfree --enable-neon --enable-runtime-cpudetect --disable-indev=qtkit --disable-indev=x11grab_xcb
+  libavutil      58.  2.100 / 58.  2.100
+  libavcodec     60.  3.100 / 60.  3.100
+  libavformat    60.  3.100 / 60.  3.100
+  libavdevice    60.  1.100 / 60.  1.100
+  libavfilter     9.  3.100 /  9.  3.100
+  libswscale      7.  1.100 /  7.  1.100
+  libswresample   4. 10.100 /  4. 10.100
+  libpostproc    57.  1.100 / 57.  1.100
+23:55:08.365 [info] FFmpeg output: objc[43507]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+23:55:08.367 [info] FFmpeg output: objc[43507]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+objc[43507]: class `NSKVONotifying_AVCaptureScreenInput' not linked into application
+[AVFoundation indev @ 0x1522047a0] Configuration of video device failed, falling back to default.
+23:55:08.367 [error] PERMISSION ISSUE DETECTED: Screen recording failed. This happens because the Node.js subprocess doesn't inherit VS Code's screen recording permissions.
+23:55:08.367 [error] SOLUTION: Add Node.js to screen recording permissions:
+23:55:08.367 [error] 1. Open System Preferences > Security & Privacy > Privacy > Screen Recording
+23:55:08.368 [error] 2. Click the lock to unlock
+23:55:08.368 [error] 3. Click the + button and add: /usr/local/bin/node (or your Node.js installation path)
+23:55:08.368 [error] 4. Alternatively, find node with: which node
+23:55:08.368 [error] 5. Restart the terminal after adding permissions
+23:55:10.803 [warn] Temp file not created yet
+23:55:17.645 [info] === STOP SIGNAL FILE DETECTED ===
+23:55:17.646 [info] === SHUTDOWN SIGNAL RECEIVED ===
+Stopping background recording...
+23:55:17.647 [info] Background recording shutdown initiated
+23:55:17.648 [info] Stopping recording
+23:55:23.673 [info] Looking for temp file
+DEBUG: Looking for temp file {
+  inMemory: '/Users/ianjennings/Development/dashcam-cli-minimal/tmp/recordings/temp-1761713707782.webm',
+  infoFileExists: true,
+  infoPath: '/Users/ianjennings/Development/dashcam-cli-minimal/.dashcam/temp-file.json'
+}
+23:55:23.676 [info] Debug: temp file check
+23:55:23.678 [info] Enhanced application tracking stopped
+23:55:23.679 [error] Error in background recording: Recording file is empty or missing
+Error in background recording: Recording file is empty or missing
+23:55:23.680 [info] Cleaning up background recording process

package/.dashcam/web-config.json

@@ -0,0 +1,11 @@
+{
+  "testdriver-tracking": {
+    "id": "testdriver-tracking",
+    "name": "testdriver-tracking",
+    "type": "web",
+    "enabled": true,
+    "patterns": [
+      "*testdriver.ai*"
+    ]
+  }
+}

package/.github/RELEASE.md

@@ -0,0 +1,59 @@
+# Release Workflow
+
+## How It Works
+
+### Pull Requests
+- When you create a PR, the build workflow runs automatically
+- Binaries are built for all platforms but **NOT released**
+- Artifacts are uploaded to the PR for testing
+
+### Pushes to Main
+- When code is pushed to `main`, the release workflow automatically:
+  1. **Bumps the version** (creates a git tag)
+  2. **Builds binaries** for all platforms
+  3. **Creates a GitHub release** with all binaries attached
+
+## Version Bumping
+
+The version is automatically bumped based on your commit messages:
+
+### Default: Patch Version (1.0.0 → 1.0.1)
+```bash
+git commit -m "fix: bug fix"
+git commit -m "docs: update documentation"
+```
+
+### Minor Version (1.0.0 → 1.1.0)
+Include `#minor` or `#feature` in your commit message:
+```bash
+git commit -m "feat: add new feature #minor"
+git commit -m "new feature #feature"
+```
+
+### Major Version (1.0.0 → 2.0.0)
+Include `#major` in your commit message:
+```bash
+git commit -m "breaking: major API change #major"
+git commit -m "refactor: complete rewrite #major"
+```
+
+### Skip Release
+Include `#none` or `[skip ci]` to skip the release:
+```bash
+git commit -m "chore: update README #none"
+git commit -m "docs: typo fix [skip ci]"
+```
+
+## Manual Release
+
+You can trigger a release manually from the GitHub Actions tab:
+1. Go to Actions → Release workflow
+2. Click "Run workflow"
+3. Select the branch and run
+
+## Supported Platforms
+
+Each release includes binaries for:
+- **macOS**: x64 (Intel) and ARM64 (Apple Silicon)
+- **Linux**: x64 and ARM64
+- **Windows**: x64 and ARM64

package/.github/workflows/build.yml

@@ -0,0 +1,103 @@
+name: Build Binaries
+
+on:
+  workflow_dispatch:
+  workflow_call:
+    inputs:
+      upload_artifacts:
+        description: 'Whether to upload artifacts'
+        required: false
+        type: boolean
+        default: true
+
+jobs:
+  build:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: 'npm'
+
+      - name: Setup Python (Windows)
+        if: matrix.os == 'windows-latest'
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build bundle
+        run: npm run bundle
+
+      - name: Verify bundle created
+        run: |
+          ls -la dist/ || dir dist\
+        shell: bash
+
+      - name: Build binaries (macOS)
+        if: matrix.os == 'macos-latest'
+        run: npm run build:macos
+
+      - name: Build binaries (Linux)
+        if: matrix.os == 'ubuntu-latest'
+        run: npm run build:linux
+
+      - name: Build binaries (Windows)
+        if: matrix.os == 'windows-latest'
+        run: npm run build:windows
+        continue-on-error: true
+        
+      - name: Check Windows build
+        if: matrix.os == 'windows-latest'
+        run: |
+          if (Test-Path dist/bundle-x64.exe) {
+            Write-Host "Windows build successful"
+            exit 0
+          } else {
+            Write-Host "Windows build failed, but continuing..."
+            exit 0
+          }
+        shell: pwsh
+
+      - name: List built files
+        run: |
+          ls -la dist/ || dir dist\
+        shell: bash
+
+      - name: Upload artifacts (macOS)
+        if: matrix.os == 'macos-latest' && (inputs.upload_artifacts || github.event_name == 'pull_request')
+        uses: actions/upload-artifact@v4
+        with:
+          name: dashcam-macos
+          path: |
+            dist/bundle-arm64
+            dist/bundle-x64
+
+      - name: Upload artifacts (Linux)
+        if: matrix.os == 'ubuntu-latest' && (inputs.upload_artifacts || github.event_name == 'pull_request')
+        uses: actions/upload-artifact@v4
+        with:
+          name: dashcam-linux
+          path: |
+            dist/bundle-arm64
+            dist/bundle-x64
+
+      - name: Upload artifacts (Windows)
+        if: (matrix.os == 'windows-latest' && hashFiles('dist/bundle-x64.exe') != '') && (inputs.upload_artifacts || github.event_name == 'pull_request')
+        uses: actions/upload-artifact@v4
+        with:
+          name: dashcam-windows
+          path: |
+            dist/bundle-x64.exe
+            dist/bundle-arm64.exe
+          if-no-files-found: warn

package/.github/workflows/publish.yml

@@ -0,0 +1,43 @@
+name: Publish to npm
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Configure Git
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Bump version
+        run: |
+          npm version prerelease --preid=beta -m "chore: bump version to %s [skip ci]"
+
+      - name: Push changes
+        run: |
+          git push --follow-tags
+
+      - name: Publish to npm
+        run: npm publish --access public --tag beta
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/.github/workflows/release.yml

@@ -0,0 +1,107 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  bump-version:
+    runs-on: ubuntu-latest
+    # Skip if commit message contains [skip ci] or [skip release]
+    if: ${{ !contains(github.event.head_commit.message, '[skip ci]') && !contains(github.event.head_commit.message, '[skip release]') }}
+    outputs:
+      new_tag: ${{ steps.bump.outputs.new_tag }}
+      version: ${{ steps.bump.outputs.tag }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Bump version and create tag
+        id: bump
+        uses: anothrNick/github-tag-action@1.67.0
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          WITH_V: true
+          DEFAULT_BUMP: patch
+          INITIAL_VERSION: 1.0.0
+          RELEASE_BRANCHES: main,master
+
+  build:
+    needs: bump-version
+    uses: ./.github/workflows/build.yml
+    with:
+      upload_artifacts: true
+
+  release:
+    needs: [bump-version, build]
+    runs-on: ubuntu-latest
+    if: needs.bump-version.outputs.new_tag != ''
+    
+    steps:
+      - name: Download all artifacts
+        uses: actions/download-artifact@v4
+        continue-on-error: true
+
+      - name: List downloaded artifacts
+        run: |
+          echo "Downloaded artifacts:"
+          ls -R
+
+      - name: Prepare release files
+        run: |
+          mkdir -p release
+          # macOS binaries
+          if [ -f dashcam-macos/bundle-arm64 ]; then
+            cp dashcam-macos/bundle-arm64 release/dashcam-macos-arm64
+            chmod +x release/dashcam-macos-arm64
+          fi
+          if [ -f dashcam-macos/bundle-x64 ]; then
+            cp dashcam-macos/bundle-x64 release/dashcam-macos-x64
+            chmod +x release/dashcam-macos-x64
+          fi
+          # Linux binaries
+          if [ -f dashcam-linux/bundle-arm64 ]; then
+            cp dashcam-linux/bundle-arm64 release/dashcam-linux-arm64
+            chmod +x release/dashcam-linux-arm64
+          fi
+          if [ -f dashcam-linux/bundle-x64 ]; then
+            cp dashcam-linux/bundle-x64 release/dashcam-linux-x64
+            chmod +x release/dashcam-linux-x64
+          fi
+          # Windows binaries
+          if [ -f dashcam-windows/bundle-x64.exe ]; then
+            cp dashcam-windows/bundle-x64.exe release/dashcam-windows-x64.exe
+          fi
+          if [ -f dashcam-windows/bundle-arm64.exe ]; then
+            cp dashcam-windows/bundle-arm64.exe release/dashcam-windows-arm64.exe
+          fi
+          ls -la release/
+
+      - name: Create Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: ${{ needs.bump-version.outputs.new_tag }}
+          name: Release ${{ needs.bump-version.outputs.new_tag }}
+          body: |
+            ## Dashcam CLI Release ${{ needs.bump-version.outputs.new_tag }}
+            
+            Automated release with binaries for macOS (x64, ARM64), Linux (x64, ARM64), and Windows (x64, ARM64).
+            
+            ### Download Instructions
+            - **macOS Intel**: `dashcam-macos-x64`
+            - **macOS Apple Silicon**: `dashcam-macos-arm64`
+            - **Linux x64**: `dashcam-linux-x64`
+            - **Linux ARM64**: `dashcam-linux-arm64`
+            - **Windows x64**: `dashcam-windows-x64.exe`
+            - **Windows ARM64**: `dashcam-windows-arm64.exe`
+          files: release/*
+          draft: false
+          prerelease: false
+          fail_on_unmatched_files: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

package/LOG_TRACKING_GUIDE.md

@@ -0,0 +1,225 @@
+# Dashcam CLI - Log Tracking Guide
+
+The Dashcam CLI can track both **file-based logs** (from CLI applications) and **web browser logs** (from browser extensions). This guide explains how to use the log tracking features.
+
+## File Log Tracking (CLI Applications)
+
+### Adding Log Files to Track
+
+Track log files during recordings:
+
+```bash
+# Add a single log file
+dashcam logs --add /var/log/myapp.log
+
+# Add multiple log files
+dashcam logs --add /tmp/debug.log
+dashcam logs --add ~/.npm/_logs/npm.log
+dashcam logs --add /var/log/nginx/access.log
+```
+
+### Removing Log Files
+
+```bash
+# Remove a log file from tracking
+dashcam logs --remove /var/log/myapp.log
+```
+
+### Viewing Tracked Files
+
+```bash
+# List all currently tracked log files
+dashcam logs --list
+
+# Show detailed tracking status
+dashcam logs --status
+```
+
+## Web Browser Log Tracking
+
+### Setting Up Web App Tracking
+
+Web log tracking requires configuring patterns for URLs you want to monitor:
+
+```bash
+# Create a config file for web apps (web-logs.json)
+cat > web-logs.json << 'EOF'
+[
+  {
+    "id": "my-web-app",
+    "type": "web",
+    "name": "My Web Application",
+    "enabled": true,
+    "patterns": [
+      "*localhost:3000*",
+      "*myapp.com*",
+      "*staging.myapp.com*"
+    ]
+  },
+  {
+    "id": "github",
+    "type": "web", 
+    "name": "GitHub",
+    "enabled": true,
+    "patterns": [
+      "*github.com*"
+    ]
+  }
+]
+EOF
+```
+
+### Updating Web Log Configuration
+
+```javascript
+// In your Node.js script or through the API
+import { logsTrackerManager } from './lib/logs/index.js';
+
+const webConfig = [
+  {
+    id: 'my-app',
+    type: 'web',
+    name: 'My Application',
+    enabled: true,
+    patterns: ['*localhost:3000*', '*myapp.com*']
+  }
+];
+
+logsTrackerManager.updateLogsConfig(webConfig);
+```
+
+## Recording with Log Tracking
+
+### Start a Recording with Logs
+
+```bash
+# Start recording (logs are automatically included if configured)
+dashcam record --duration 30
+
+# The recording will include:
+# - All tracked log files (--add files above)
+# - Web browser events (if browser extension is installed)
+```
+
+### Browser Extension Setup
+
+1. **Install the Dashcam browser extension** (Chrome/Firefox)
+2. **The CLI automatically starts a WebSocket server** on ports: 10368, 16240, 21855, 24301, or 25928
+3. **Extension connects automatically** when CLI is running
+4. **Web events are captured** based on your URL patterns
+
+## Log Event Types
+
+### File Logs
+- **Line events**: Each new line written to tracked files
+- **Timestamps**: Precise timing for synchronization with video
+- **Error detection**: Automatic highlighting of error lines
+
+### Web Logs  
+- **Console logs**: `console.log()`, `console.error()`, etc.
+- **Network requests**: HTTP requests and responses
+- **Navigation events**: Page loads and URL changes
+- **Tab management**: Tab switches and window focus
+
+## Example Workflow
+
+```bash
+# 1. Add log files to track
+dashcam logs --add /var/log/myapp.log
+dashcam logs --add /tmp/debug.log
+
+# 2. Check status
+dashcam logs --status
+# Output:
+# Log tracking status:
+#   Active recording instances: 0
+#   Configured CLI log files: 2
+#   Total recent events: 15
+#   File tracker details:
+#     /var/log/myapp.log: 8 events (last minute)
+#     /tmp/debug.log: 7 events (last minute)
+
+# 3. Start recording
+dashcam record --duration 60
+
+# 4. During recording:
+# - CLI monitors all tracked log files in real-time
+# - Browser extension sends web events via WebSocket
+# - All events are timestamped and synchronized
+
+# 5. After recording:
+# - Logs are automatically trimmed to match video duration
+# - Events are saved in JSONL format alongside video
+# - Logs can be replayed in sync with video
+```
+
+## Advanced Configuration
+
+### Custom WebSocket Port
+
+```javascript
+// If you need to use specific ports
+import { server } from './lib/websocket/server.js';
+await server.start(); // Uses predefined port list
+```
+
+### Pattern Matching for Web Apps
+
+Patterns support wildcards:
+- `*example.com*` - Matches any URL containing "example.com"
+- `*localhost:3000*` - Matches local development server
+- `*github.com/myuser/*` - Matches specific GitHub paths
+
+### Log File Requirements
+
+- **Files must exist** before adding to tracking
+- **Files must be readable** by the CLI process  
+- **Real-time writes** are monitored (uses `tail` library)
+- **Log rotation** is automatically handled
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Log file does not exist"**
+   ```bash
+   # Ensure file exists first
+   touch /var/log/myapp.log
+   dashcam logs --add /var/log/myapp.log
+   ```
+
+2. **"WebSocket connection failed"** 
+   - Check that browser extension is installed
+   - Verify no firewall blocking local ports
+   - Ensure CLI is running when opening browser
+
+3. **"No events captured"**
+   ```bash
+   # Check if files are being written to
+   tail -f /var/log/myapp.log
+   
+   # Verify tracking status
+   dashcam logs --status
+   ```
+
+### Getting Help
+
+```bash
+# Show all log tracking options
+dashcam logs --help
+
+# Show general CLI help
+dashcam --help
+```
+
+## Integration with Recordings
+
+When you create a recording, all configured logs are:
+
+1. **Automatically included** in the recording
+2. **Synchronized** with video timestamps  
+3. **Trimmed** to match video start/end times
+4. **Saved** in JSON Lines format for replay
+5. **Uploaded** along with video files
+
+The result is a complete recording with both visual and log context, making debugging and analysis much more effective.