dashcam 0.8.3 → 1.0.1-beta.10

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/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/BACKWARD_COMPATIBILITY.md

@@ -0,0 +1,177 @@
+# Backward Compatibility Summary
+
+This document confirms that `dashcam-cli-minimal` now supports all commands and arguments documented in the README.md.
+
+## ✅ Implemented Commands
+
+### `auth <api-key>`
+Authenticate the dashcam desktop using a team's apiKey.
+```bash
+dashcam auth <api-key>
+```
+
+### `create [options]`
+Create a clip from current recording and output the resulting url or markdown. This stops the current recording and uploads it.
+```bash
+# Start instant replay in background
+dashcam start
+
+# Later, create a clip from the recording
+dashcam create
+dashcam create -t "My New Title"
+dashcam create --md
+dashcam create -k wef8we72h23012j
+dashcam create -d "Description text"
+cat README.md | dashcam create
+```
+
+Options:
+- `-t, --title <string>` - Title of the replay
+- `-d, --description [text]` - Replay markdown body (supports piped input)
+- `--md` - Returns rich markdown image link
+- `-k, --project <project>` - Project ID to publish to
+
+**Note:** `create` stops the current recording and creates a clip. It's similar to `stop` but focused on outputting URLs/markdown for integration with other tools.
+
+### `record [options]`
+Start a recording terminal to be included in your dashcam video recording.
+```bash
+dashcam record
+```
+
+Options:
+- `-t, --title <title>` - Title for the recording
+- `-d, --description <description>` - Description for the recording
+- `-p, --project <project>` - Project ID to upload to
+- `-a, --audio` - Include audio
+- `-f, --fps <fps>` - Frames per second
+
+### `pipe`
+Pipe command output to dashcam to be included in recorded video.
+```bash
+ping 1.1.1.1 | dashcam pipe
+cat /var/log/system.log | dashcam pipe
+```
+
+### `track [options]`
+Add a logs config to Dashcam.
+
+**New Syntax (matches README):**
+```bash
+dashcam track --name=social --type=web --pattern="*facebook.com*" --pattern="*twitter.com*"
+dashcam track --name=app-logs --type=application --pattern="/var/log/*.log"
+```
+
+**Old Syntax (still supported):**
+```bash
+dashcam track --web "*facebook.com*"
+dashcam track --app "/var/log/app.log"
+```
+
+Options:
+- `--name <name>` - Name for the tracking configuration (required with new syntax)
+- `--type <type>` - Type: "application" or "web" (required with new syntax)
+- `--pattern <pattern>` - Pattern to track (can use multiple times)
+- `--web <pattern>` - Web URL pattern (deprecated, use --type=web --pattern)
+- `--app <pattern>` - Application file pattern (deprecated, use --type=application --pattern)
+
+### `start`
+Start instant replay recording on dashcam.
+```bash
+dashcam start
+```
+
+### `stop`
+Stop the current recording and upload.
+```bash
+dashcam stop
+```
+
+### `status`
+Show current recording status.
+```bash
+dashcam status
+```
+
+## Examples from README
+
+All examples from the README should now work:
+
+### Basic usage
+```bash
+# Create a replay
+dashcam create
+# Returns: https://dashcam.io/replay/123?share=xyz
+
+# With markdown output
+dashcam create --md
+
+# With title
+dashcam create -t "My New Title"
+
+# With project
+dashcam create -k wef8we72h23012j
+
+# Attach last 20 CLI commands
+history -20 | dashcam create
+
+# Attach a logfile
+cat /var/log/system.log | dashcam create
+```
+
+### Tracking logs
+```bash
+# Track web URLs
+dashcam track --name=social --type=web --pattern="*facebook.com*" --pattern="*twitter.com*"
+
+# Track application files
+dashcam track --name=app-logs --type=application --pattern="/var/log/*.log"
+```
+
+### Recording
+```bash
+# Start recording
+dashcam record
+
+# Pipe output into recording
+ping 1.1.1.1 | dashcam pipe
+
+# Stop recording
+dashcam stop
+```
+
+### GitHub CLI integration
+```bash
+# Create GitHub issue with replay
+gh issue create -w -t "Title" -b "`dashcam create --md`"
+
+# With system logs
+gh issue create -w -t "Title" -b "`cat /var/log/system.log | dashcam create --md`"
+
+# Create PR with replay
+gh pr create -w -t "Title" -b "`dashcam create --md`"
+
+# Append to commit
+git commit -am "`dashcam create`"
+```
+
+## Key Changes for Backward Compatibility
+
+1. **Added `create` command** - Stops current recording and creates a clip with URL/markdown output
+2. **Added `pipe` command** - Allows piping command output into recordings
+3. **Added `start` command** - Simple way to start instant replay recording in background
+4. **Updated `track` command** - Now supports both old syntax (--web, --app) and new syntax (--name, --type, --pattern)
+5. **Updated descriptions** - Match README text exactly
+6. **Updated `auth` parameter** - Changed from `<apiKey>` to `<api-key>` to match README
+7. **Added `-k` alias** - For `--project` option in `create` command
+8. **Shared implementation** - `create`, `record`, and `start` share common code to avoid duplication
+
+## Migration Notes
+
+- **`start`** - Starts instant replay recording in background (like desktop app's always-on recording)
+- **`create`** - Stops the current recording and outputs URL/markdown (perfect for CI/CD, git hooks, GitHub CLI)
+- **`record`** - Full-featured recording command with all options (terminal recording mode)
+- **`stop`** - Similar to `create` but focused on stopping and uploading vs URL output
+- Old `track` syntax still works for backward compatibility but new syntax is preferred
+- All piped input examples from README are supported
+- Can run just `dashcam` with options (defaults to `create` command)

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.