escribano 0.2.2 → 0.4.1

package/dist/config.js

@@ -0,0 +1,237 @@
+/**
+ * Configuration Management
+ *
+ * Loads configuration from multiple sources with priority (highest to lowest):
+ * 1. CLI arguments
+ * 2. Shell environment variables (export ESCRIBANO_*)
+ * 3. ~/.escribano/.env file
+ * 4. Default values
+ *
+ * Note: Project-level .env is NOT loaded by default (only for development).
+ */
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import path from 'node:path';
+import { config as dotenvConfig } from 'dotenv';
+import { z } from 'zod';
+// =============================================================================
+// CONFIG SCHEMA
+// =============================================================================
+const configSchema = z.object({
+    // === PERFORMANCE ===
+    frameWidth: z.number().int().min(320).max(3840).default(1024),
+    vlmBatchSize: z.number().int().min(1).max(8).default(2),
+    sampleInterval: z.number().int().min(1).max(60).default(10),
+    // === QUALITY ===
+    sceneThreshold: z.number().min(0).max(1).default(0.4),
+    vlmMaxTokens: z.number().int().min(500).max(8000).default(2000),
+    // === MODELS ===
+    llmModel: z.string().optional(),
+    vlmModel: z.string().default('mlx-community/Qwen3-VL-2B-Instruct-4bit'),
+    subjectGroupingModel: z.string().optional(),
+    // === DEBUGGING ===
+    verbose: z.boolean().default(false),
+    debugOllama: z.boolean().default(false),
+    debugVlm: z.boolean().default(false),
+    skipLlm: z.boolean().default(false),
+    // === ADVANCED ===
+    sceneMinInterval: z.number().int().min(1).max(10).default(2),
+    sampleGapThreshold: z.number().int().min(5).max(60).default(15),
+    sampleGapFill: z.number().int().min(1).max(10).default(3),
+    mlxSocketPath: z.string().default('/tmp/escribano-mlx.sock'),
+    mlxStartupTimeout: z.number().int().min(10000).default(60000),
+    pythonPath: z.string().optional(),
+    parallelTranscription: z.boolean().default(false),
+    artifactThink: z.boolean().default(false),
+    // === OPTIONAL (Outline publishing) ===
+    outlineUrl: z.string().optional(),
+    outlineToken: z.string().optional(),
+    outlineCollection: z.string().default('Escribano Sessions'),
+});
+// =============================================================================
+// DEFAULT CONFIG
+// =============================================================================
+const DEFAULT_CONFIG = {
+    frameWidth: 1024,
+    vlmBatchSize: 2,
+    sampleInterval: 10,
+    sceneThreshold: 0.4,
+    vlmMaxTokens: 2000,
+    vlmModel: 'mlx-community/Qwen3-VL-2B-Instruct-4bit',
+    verbose: false,
+    debugOllama: false,
+    debugVlm: false,
+    skipLlm: false,
+    sceneMinInterval: 2,
+    sampleGapThreshold: 15,
+    sampleGapFill: 3,
+    mlxSocketPath: '/tmp/escribano-mlx.sock',
+    mlxStartupTimeout: 60000,
+    parallelTranscription: false,
+    artifactThink: false,
+    outlineCollection: 'Escribano Sessions',
+};
+// =============================================================================
+// CONFIG FILE TEMPLATE
+// =============================================================================
+const CONFIG_TEMPLATE = `# Escribano Configuration - ~/.escribano/.env
+# Generated by escribano - edit as needed
+# Full reference: https://github.com/eduardosanzb/escribano#configuration
+
+# === PERFORMANCE ===
+ESCRIBANO_FRAME_WIDTH=1024          # Lower = faster (1920, 1280, 1024, 640)
+ESCRIBANO_VLM_BATCH_SIZE=2          # 1-4 frames (lower = more reliable)
+ESCRIBANO_SAMPLE_INTERVAL=10        # Base frame sampling (seconds)
+
+# === QUALITY ===
+ESCRIBANO_SCENE_THRESHOLD=0.4       # Scene detection sensitivity (0.0-1.0)
+ESCRIBANO_VLM_MAX_TOKENS=2000       # Token budget per batch
+
+# === MODELS ===
+# ESCRIBANO_LLM_MODEL=qwen3.5:27b   # Summary generation (auto-detected if not set)
+ESCRIBANO_VLM_MODEL=mlx-community/Qwen3-VL-2B-Instruct-4bit
+
+# === DEBUGGING ===
+ESCRIBANO_VERBOSE=false              # Enable verbose logging
+ESCRIBANO_DEBUG_VLM=false           # Debug VLM processing
+
+# === ADVANCED ===
+ESCRIBANO_SCENE_MIN_INTERVAL=2
+ESCRIBANO_SAMPLE_GAP_THRESHOLD=15
+ESCRIBANO_SAMPLE_GAP_FILL=3
+ESCRIBANO_MLX_SOCKET_PATH=/tmp/escribano-mlx.sock
+ESCRIBANO_MLX_STARTUP_TIMEOUT=60000
+# ESCRIBANO_PYTHON_PATH=             # Auto-detected if not set
+ESCRIBANO_ARTIFACT_THINK=false      # Enable thinking for artifacts (slower)
+
+# === OPTIONAL (Outline publishing) ===
+# ESCRIBANO_OUTLINE_URL=
+# ESCRIBANO_OUTLINE_TOKEN=
+# ESCRIBANO_OUTLINE_COLLECTION=Escribano Sessions
+`;
+// =============================================================================
+// CONFIG LOADER
+// =============================================================================
+let cachedConfig = null;
+export function getConfigPath() {
+    return path.join(homedir(), '.escribano', '.env');
+}
+export function createDefaultConfig() {
+    const configDir = path.join(homedir(), '.escribano');
+    const configPath = getConfigPath();
+    try {
+        if (!existsSync(configDir)) {
+            mkdirSync(configDir, { recursive: true });
+        }
+        if (!existsSync(configPath)) {
+            writeFileSync(configPath, CONFIG_TEMPLATE, 'utf-8');
+            console.log(`Created config file at ${configPath}`);
+            console.log('You can customize settings by editing this file.\n');
+        }
+    }
+    catch (error) {
+        console.error(`Failed to create config file at ${configPath}: ${error.message}`);
+    }
+}
+export function loadConfig() {
+    if (cachedConfig) {
+        return cachedConfig;
+    }
+    // 1. Load from config file (if exists)
+    const configPath = getConfigPath();
+    if (existsSync(configPath)) {
+        try {
+            const result = dotenvConfig({ path: configPath });
+            if (result.error) {
+                console.error(`Failed to parse config file ${configPath}: ${result.error.message}`);
+                console.error('Using default configuration.');
+            }
+            else if (result.parsed && Object.keys(result.parsed).length > 0) {
+                console.log(`Loaded config from ${configPath}`);
+            }
+        }
+        catch (error) {
+            console.error(`Error reading config file ${configPath}: ${error.message}`);
+            console.error('Using default configuration.');
+        }
+    }
+    // 2. Build config from environment variables
+    const config = {
+        // === PERFORMANCE ===
+        frameWidth: parseEnvNumber('ESCRIBANO_FRAME_WIDTH', DEFAULT_CONFIG.frameWidth),
+        vlmBatchSize: parseEnvNumber('ESCRIBANO_VLM_BATCH_SIZE', DEFAULT_CONFIG.vlmBatchSize),
+        sampleInterval: parseEnvNumber('ESCRIBANO_SAMPLE_INTERVAL', DEFAULT_CONFIG.sampleInterval),
+        // === QUALITY ===
+        sceneThreshold: parseEnvNumber('ESCRIBANO_SCENE_THRESHOLD', DEFAULT_CONFIG.sceneThreshold),
+        vlmMaxTokens: parseEnvNumber('ESCRIBANO_VLM_MAX_TOKENS', DEFAULT_CONFIG.vlmMaxTokens),
+        // === MODELS ===
+        llmModel: process.env.ESCRIBANO_LLM_MODEL,
+        vlmModel: process.env.ESCRIBANO_VLM_MODEL || DEFAULT_CONFIG.vlmModel,
+        subjectGroupingModel: process.env.ESCRIBANO_SUBJECT_GROUPING_MODEL,
+        // === DEBUGGING ===
+        verbose: parseEnvBoolean('ESCRIBANO_VERBOSE', DEFAULT_CONFIG.verbose),
+        debugOllama: parseEnvBoolean('ESCRIBANO_DEBUG_OLLAMA', DEFAULT_CONFIG.debugOllama),
+        debugVlm: parseEnvBoolean('ESCRIBANO_DEBUG_VLM', DEFAULT_CONFIG.debugVlm),
+        skipLlm: parseEnvBoolean('ESCRIBANO_SKIP_LLM', DEFAULT_CONFIG.skipLlm),
+        // === ADVANCED ===
+        sceneMinInterval: parseEnvNumber('ESCRIBANO_SCENE_MIN_INTERVAL', DEFAULT_CONFIG.sceneMinInterval),
+        sampleGapThreshold: parseEnvNumber('ESCRIBANO_SAMPLE_GAP_THRESHOLD', DEFAULT_CONFIG.sampleGapThreshold),
+        sampleGapFill: parseEnvNumber('ESCRIBANO_SAMPLE_GAP_FILL', DEFAULT_CONFIG.sampleGapFill),
+        mlxSocketPath: process.env.ESCRIBANO_MLX_SOCKET_PATH || DEFAULT_CONFIG.mlxSocketPath,
+        mlxStartupTimeout: parseEnvNumber('ESCRIBANO_MLX_STARTUP_TIMEOUT', DEFAULT_CONFIG.mlxStartupTimeout),
+        pythonPath: process.env.ESCRIBANO_PYTHON_PATH,
+        parallelTranscription: parseEnvBoolean('ESCRIBANO_PARALLEL_TRANSCRIPTION', DEFAULT_CONFIG.parallelTranscription),
+        artifactThink: parseEnvBoolean('ESCRIBANO_ARTIFACT_THINK', DEFAULT_CONFIG.artifactThink),
+        // === OPTIONAL ===
+        outlineUrl: process.env.ESCRIBANO_OUTLINE_URL,
+        outlineToken: process.env.ESCRIBANO_OUTLINE_TOKEN,
+        outlineCollection: process.env.ESCRIBANO_OUTLINE_COLLECTION ||
+            DEFAULT_CONFIG.outlineCollection,
+    };
+    // 3. Validate with Zod
+    const validated = configSchema.parse(config);
+    cachedConfig = validated;
+    return validated;
+}
+// =============================================================================
+// HELPERS
+// =============================================================================
+function parseEnvNumber(key, defaultValue) {
+    const value = process.env[key];
+    if (!value)
+        return defaultValue;
+    const parsed = Number(value);
+    if (Number.isNaN(parsed)) {
+        console.warn(`Invalid ${key}="${value}", using default: ${defaultValue}`);
+        return defaultValue;
+    }
+    return parsed;
+}
+function parseEnvBoolean(key, defaultValue) {
+    const value = process.env[key];
+    if (!value)
+        return defaultValue;
+    return value === 'true';
+}
+// =============================================================================
+// CLI UTILITIES
+// =============================================================================
+export function showConfig() {
+    const configPath = getConfigPath();
+    // Create config file if it doesn't exist
+    if (!existsSync(configPath)) {
+        createDefaultConfig();
+    }
+    const config = loadConfig();
+    console.log(`Config file: ${configPath}\n`);
+    console.log('Current configuration:');
+    console.log(JSON.stringify(config, null, 2));
+}
+export function showConfigPath() {
+    const configPath = getConfigPath();
+    // Create config file if it doesn't exist
+    if (!existsSync(configPath)) {
+        createDefaultConfig();
+    }
+    console.log(configPath);
+}

package/dist/domain/segment.js

@@ -5,9 +5,7 @@ import { TimeRange } from './time-range.js';
 import { Transcript } from './transcript.js';
 // Minimal Context logic previously in context.ts
 const Context = {
-    extractFromOCR: (text) => {
-        // This is a stub to keep V1 compiling.
-        // V2 uses signal-extraction.ts instead.
+    extractFromOCR: (_text) => {
         return [];
     },
     unique: (contexts) => contexts,

package/dist/index.js

@@ -5,18 +5,87 @@
  * Single command: process latest recording and generate summary
  * Refactored to use batch-context for shared initialization logic
  */
+import { access, constants, readdir, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import pkg from '../package.json' with { type: 'json' };
 import { createCapCaptureSource } from './adapters/capture.cap.adapter.js';
 import { createFilesystemCaptureSource } from './adapters/capture.filesystem.adapter.js';
 import { cleanupMlxBridge, initializeSystem, processVideo, } from './batch-context.js';
+import { loadConfig, showConfig, showConfigPath } from './config.js';
 import { getDbPath } from './db/index.js';
 import { checkPrerequisites, hasMissingPrerequisites, printDoctorResults, } from './prerequisites.js';
 import { logEnvironmentVariables } from './utils/env-logger.js';
 const MODELS_DIR = path.join(homedir(), '.escribano', 'models');
 const MODEL_FILE = 'ggml-large-v3.bin';
-const MODEL_PATH = path.join(MODELS_DIR, MODEL_FILE);
+const _MODEL_PATH = path.join(MODELS_DIR, MODEL_FILE);
+const VIDEO_EXTENSIONS = ['.mov', '.mp4', '.mkv', '.avi', '.webm'];
+function expandPath(inputPath) {
+    if (!inputPath.startsWith('~')) {
+        return inputPath;
+    }
+    const homeDir = homedir();
+    if (!homeDir) {
+        return inputPath;
+    }
+    if (inputPath === '~' || inputPath === '~/') {
+        return homeDir;
+    }
+    if (inputPath.startsWith('~/')) {
+        return path.join(homeDir, inputPath.slice(2));
+    }
+    return inputPath;
+}
+async function findLatestVideo(dirPath) {
+    const resolvedPath = expandPath(dirPath);
+    let entries;
+    try {
+        entries = await readdir(resolvedPath, { withFileTypes: true });
+    }
+    catch (error) {
+        const err = error;
+        if (err && typeof err === 'object') {
+            switch (err.code) {
+                case 'ENOENT':
+                    throw new Error(`Directory not found: ${resolvedPath}`);
+                case 'ENOTDIR':
+                    throw new Error(`Not a directory: ${resolvedPath}`);
+                case 'EACCES':
+                case 'EPERM':
+                    throw new Error(`Permission denied reading directory: ${resolvedPath}`);
+                default:
+                    break;
+            }
+        }
+        throw error;
+    }
+    const videoFiles = entries.filter((entry) => entry.isFile() &&
+        VIDEO_EXTENSIONS.some((ext) => entry.name.toLowerCase().endsWith(ext)));
+    if (videoFiles.length === 0) {
+        throw new Error(`No video files found in: ${resolvedPath}`);
+    }
+    let latestFilePath = null;
+    let latestMtime = -Infinity;
+    for (const entry of videoFiles) {
+        const fullPath = path.join(resolvedPath, entry.name);
+        try {
+            await access(fullPath, constants.R_OK);
+            const fileStat = await stat(fullPath);
+            const mtimeMs = fileStat.mtime.getTime();
+            if (mtimeMs > latestMtime) {
+                latestMtime = mtimeMs;
+                latestFilePath = fullPath;
+            }
+        }
+        catch {
+            // Skip files that are inaccessible (permission denied, broken symlink, etc.)
+        }
+    }
+    if (!latestFilePath) {
+        throw new Error(`No accessible video files found in: ${resolvedPath}`);
+    }
+    return latestFilePath;
+}
 function main() {
     const args = parseArgs(process.argv.slice(2));
     if (args.version) {
@@ -34,6 +103,17 @@ function main() {
         });
         return;
     }
+    if (args.config) {
+        if (args.configPath) {
+            showConfigPath();
+        }
+        else {
+            showConfig();
+        }
+        return;
+    }
+    // Load user config file before any adapter reads process.env
+    loadConfig();
     run(args).catch((error) => {
         console.error('Error:', error.message);
         console.error(error.stack);
@@ -50,6 +130,20 @@ async function runDoctor() {
 function parseArgs(argsArray) {
     const fileIndex = argsArray.indexOf('--file');
     const filePath = fileIndex !== -1 ? argsArray[fileIndex + 1] || null : null;
+    const latestIndex = argsArray.indexOf('--latest');
+    const latestPath = latestIndex !== -1 ? argsArray[latestIndex + 1] || null : null;
+    if (filePath && latestPath) {
+        console.error('Error: Cannot use both --latest and --file');
+        process.exit(1);
+    }
+    if (latestIndex !== -1 && !latestPath) {
+        console.error('Error: --latest requires a directory argument');
+        process.exit(1);
+    }
+    if (latestIndex !== -1 && latestPath?.startsWith('-')) {
+        console.error('Error: --latest requires a directory argument');
+        process.exit(1);
+    }
     const micIndex = argsArray.indexOf('--mic-audio');
     const micAudio = micIndex !== -1 ? argsArray[micIndex + 1] || null : null;
     const sysIndex = argsArray.indexOf('--system-audio');
@@ -61,7 +155,11 @@ function parseArgs(argsArray) {
         help: argsArray.includes('--help') || argsArray.includes('-h'),
         version: argsArray.includes('--version') || argsArray.includes('-v'),
         doctor: argsArray[0] === 'doctor',
+        config: argsArray[0] === 'config',
+        configShow: argsArray.includes('--show'),
+        configPath: argsArray.includes('--path'),
         file: filePath,
+        latest: latestPath,
         skipSummary: argsArray.includes('--skip-summary'),
         micAudio,
         systemAudio,
@@ -80,7 +178,10 @@ Escribano - Session Intelligence Tool
 Usage:
   npx escribano                           Process latest Cap recording
   npx escribano doctor                    Check prerequisites
+  npx escribano config                    Show current configuration
+  npx escribano config --path             Show config file path
   npx escribano --file <path>             Process video from filesystem
+  npx escribano --latest <dir>            Process latest video in directory
   npx escribano --file <path> --mic-audio <wav>   Use external mic audio
   npx escribano --file <path> --system-audio <wav>  Provide system audio
   npx escribano --force                   Reprocess from scratch
@@ -94,22 +195,35 @@ Usage:
 
 Examples:
   npx escribano --file "~/Desktop/Screen Recording.mov"
+  npx escribano --latest "~/Desktop"
   npx escribano --file "/path/to/video.mp4" --mic-audio "/path/to/mic.wav"
   npx escribano --file "/path/to/video.mp4" --system-audio "/path/to/system.wav"
   npx escribano --format standup --stdout
   npx escribano --format narrative --include-personal
 
+Configuration:
+  Config file: ~/.escribano/.env
+  View config: escribano config
+  Edit manually: vim ~/.escribano/.env
+
 Output: Markdown summary saved to ~/.escribano/artifacts/
 `);
 }
 async function run(args) {
-    const { force, file: filePath, skipSummary, micAudio, systemAudio, format, includePersonal, copyToClipboard, printToStdout, } = args;
+    const { force, file: filePath, latest, skipSummary, micAudio, systemAudio, format, includePersonal, copyToClipboard, printToStdout, } = args;
+    // Resolve --latest to a file path
+    let resolvedFilePath = filePath;
+    if (latest) {
+        resolvedFilePath = await findLatestVideo(latest);
+        console.log(`Found latest video: ${resolvedFilePath}`);
+    }
     // Log environment variables if verbose mode is enabled
     logEnvironmentVariables();
     // Initialize system (reuses batch-context for consistency)
     console.log('Initializing database...');
     const ctx = await initializeSystem();
-    const { repos } = ctx;
+    // Note: repos unused in CLI mode (only needed for batch processing)
+    void ctx;
     console.log(`Database ready: ${getDbPath()}`);
     console.log('');
     // SIGINT handler for graceful cancellation
@@ -121,14 +235,14 @@ async function run(args) {
     process.on('SIGINT', sigintHandler);
     // Create appropriate capture source
     let captureSource;
-    if (filePath) {
-        console.log(`Using filesystem source: ${filePath}`);
+    if (resolvedFilePath) {
+        console.log(`Using filesystem source: ${resolvedFilePath}`);
         if (micAudio)
             console.log(`  Mic audio: ${micAudio}`);
         if (systemAudio)
             console.log(`  System audio: ${systemAudio}`);
         captureSource = createFilesystemCaptureSource({
-            videoPath: filePath,
+            videoPath: resolvedFilePath,
             micAudioPath: micAudio ?? undefined,
             systemAudioPath: systemAudio ?? undefined,
         }, ctx.adapters.video);
@@ -140,8 +254,8 @@ async function run(args) {
     // Get recording
     const recording = await captureSource.getLatestRecording();
     if (!recording) {
-        if (filePath) {
-            console.log(`Failed to load video file: ${filePath}`);
+        if (resolvedFilePath) {
+            console.log(`Failed to load video file: ${resolvedFilePath}`);
         }
         else {
             console.log('No Cap recordings found.');

package/dist/prerequisites.js

@@ -5,8 +5,7 @@
  */
 import { execSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
-import { homedir } from 'node:os';
-import { resolve } from 'node:path';
+import { ESCRIBANO_VENV_PYTHON, getEffectivePythonPathSync, } from './python-utils.js';
 const LLM_MODEL_TIERS = [
     { model: 'qwen3.5:27b', tier: 4, minRamGB: 32, label: 'best' },
     { model: 'qwen3:14b', tier: 3, minRamGB: 20, label: 'very good' },
@@ -59,8 +58,8 @@ const PREREQUISITES = [
     {
         name: 'mlx-vlm',
         found: false,
-        installCommand: 'pip install mlx-vlm',
-        notes: 'VLM library for frame analysis (Apple Silicon)',
+        installCommand: 'pip install mlx-vlm torch torchvision',
+        notes: 'VLM library for frame analysis (Apple Silicon) — auto-installed by escribano on first run',
     },
 ];
 function checkCommand(command, args = ['--version']) {
@@ -128,21 +127,8 @@ function checkLLMModels() {
         installCommand: 'ollama pull qwen3:8b',
     };
 }
-function getPythonPath() {
-    if (process.env.ESCRIBANO_PYTHON_PATH) {
-        return process.env.ESCRIBANO_PYTHON_PATH;
-    }
-    if (process.env.VIRTUAL_ENV) {
-        return resolve(process.env.VIRTUAL_ENV, 'bin', 'python3');
-    }
-    const uvHomeVenv = resolve(homedir(), '.venv', 'bin', 'python3');
-    if (existsSync(uvHomeVenv)) {
-        return uvHomeVenv;
-    }
-    return 'python3';
-}
 function checkPythonPackage(packageName) {
-    const pythonPath = getPythonPath();
+    const pythonPath = getEffectivePythonPathSync();
     try {
         execSync(`"${pythonPath}" -c "import ${packageName}"`, {
             encoding: 'utf-8',
@@ -243,6 +229,10 @@ export function checkPrerequisites() {
                 if (check.found && check.pythonPath) {
                     result.notes = `via ${check.pythonPath}`;
                 }
+                else if (existsSync(ESCRIBANO_VENV_PYTHON)) {
+                    // Managed venv exists but mlx-vlm is missing — auto-install will fix it on next run
+                    result.installCommand = `${ESCRIBANO_VENV_PYTHON} -m pip install mlx-vlm torch torchvision`;
+                }
                 else {
                     result.installCommand = detectPipCommand();
                 }

package/dist/python-utils.js

@@ -0,0 +1,64 @@
+/**
+ * Shared Python path resolution utilities for Escribano.
+ *
+ * Used by both the MLX adapter (runtime) and the prerequisites checker (doctor).
+ */
+import { existsSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { resolve } from 'node:path';
+/** Escribano's managed Python environment — created automatically on first use. */
+export const ESCRIBANO_HOME = resolve(homedir(), '.escribano');
+export const ESCRIBANO_VENV = resolve(ESCRIBANO_HOME, 'venv');
+export const ESCRIBANO_VENV_PYTHON = resolve(ESCRIBANO_VENV, 'bin', 'python3');
+/**
+ * Get explicitly configured Python path.
+ * Returns null when nothing is explicitly configured or found via well-known
+ * conventions (active venv, uv project environment, local/home .venv directory).
+ * Callers receiving null should fall through to ensureEscribanoVenv() for
+ * zero-config auto-setup.
+ *
+ * Priority:
+ * 1. ESCRIBANO_PYTHON_PATH env var (explicit override)
+ * 2. Active virtual environment (VIRTUAL_ENV)
+ * 3. UV_PROJECT_ENVIRONMENT (uv project-synced venv)
+ * 4. Project-local .venv (created by `uv venv` in CWD)
+ * 5. ~/.venv/bin/python3 (home-level venv)
+ * 6. null — no environment detected; auto-venv will be created
+ */
+export function getPythonPath() {
+    if (process.env.ESCRIBANO_PYTHON_PATH) {
+        return process.env.ESCRIBANO_PYTHON_PATH;
+    }
+    if (process.env.VIRTUAL_ENV) {
+        return resolve(process.env.VIRTUAL_ENV, 'bin', 'python3');
+    }
+    // UV_PROJECT_ENVIRONMENT: set by uv when running inside a project with `uv sync`
+    if (process.env.UV_PROJECT_ENVIRONMENT) {
+        return resolve(process.env.UV_PROJECT_ENVIRONMENT, 'bin', 'python3');
+    }
+    // Check project-local .venv (created by `uv venv` in the current working directory)
+    const localVenv = resolve(process.cwd(), '.venv', 'bin', 'python3');
+    if (existsSync(localVenv)) {
+        return localVenv;
+    }
+    // Check common home-level venv (e.g., `uv venv ~/.venv`)
+    const uvHomeVenv = resolve(homedir(), '.venv', 'bin', 'python3');
+    if (existsSync(uvHomeVenv)) {
+        return uvHomeVenv;
+    }
+    return null;
+}
+/**
+ * Get the best Python path for synchronous prerequisite checks (e.g., `escribano doctor`).
+ * Checks the managed venv if it already exists. Does NOT create or install anything.
+ *
+ * Priority: explicit config → managed ~/.escribano/venv (if it exists) → system python3
+ */
+export function getEffectivePythonPathSync() {
+    const explicit = getPythonPath();
+    if (explicit)
+        return explicit;
+    if (existsSync(ESCRIBANO_VENV_PYTHON))
+        return ESCRIBANO_VENV_PYTHON;
+    return 'python3';
+}

package/dist/services/activity-segmentation.js

@@ -102,7 +102,7 @@ function extractActivityType(vlmDescription) {
  * Parse VLM description to extract apps and topics.
  * Expects format like: "Debugging Python error in VSCode, working on escribano project"
  */
-function extractContext(vlmDescription) {
+function _extractContext(vlmDescription) {
     if (!vlmDescription)
         return { apps: [], topics: [] };
     const apps = [];
@@ -120,7 +120,7 @@ function extractContext(vlmDescription) {
     ];
     for (const pattern of appPatterns) {
         const match = text.match(pattern);
-        if (match && match[1]) {
+        if (match?.[1]) {
             apps.push(match[1].toLowerCase().replace(' ', '_'));
         }
     }
@@ -132,7 +132,7 @@ function extractContext(vlmDescription) {
     ];
     for (const pattern of topicPatterns) {
         const match = text.match(pattern);
-        if (match && match[1]) {
+        if (match?.[1]) {
             topics.push(match[1].toLowerCase());
         }
     }

package/dist/services/signal-extraction.js

@@ -68,7 +68,7 @@ export function extractProjects(texts) {
     for (const text of texts) {
         for (const pattern of PROJECT_PATTERNS) {
             const match = text.match(pattern);
-            if (match && match[1]) {
+            if (match?.[1]) {
                 const name = match[1].toLowerCase();
                 // Filter out common non-project names
                 if (!['src', 'lib', 'dist', 'build', 'node_modules', 'packages'].includes(name)) {

package/dist/services/subject-grouping.js

@@ -217,7 +217,7 @@ function parseGroupingResponse(response, topicBlocks) {
     }
     return { groups };
 }
-function detectPersonalSubject(apps, activityBreakdown) {
+function detectPersonalSubject(apps, _activityBreakdown) {
     let personalAppCount = 0;
     let totalAppCount = 0;
     for (const app of apps) {
@@ -322,7 +322,7 @@ function formatDuration(seconds) {
     }
     return `${Math.floor(seconds)}s`;
 }
-export function saveSubjectsToDatabase(subjects, recordingId, repos) {
+export function saveSubjectsToDatabase(subjects, _recordingId, repos) {
     const subjectInserts = [];
     const links = [];
     for (const subject of subjects) {

package/dist/services/temporal-alignment.js

@@ -49,7 +49,7 @@ export function alignAudioToSegments(segments, audioObservations, config = {}) {
     const cfg = { ...DEFAULT_CONFIG, ...config };
     // Filter to audio observations with transcripts
     const audioTranscripts = audioObservations
-        .filter((o) => o.type === 'audio' && o.text && o.text.trim().length > 0)
+        .filter((o) => o.type === 'audio' && o.text !== null && o.text.trim().length > 0)
         .map((o) => ({
         source: o.audio_source,
         text: o.text,

package/dist/services/vlm-enrichment.js

@@ -68,13 +68,16 @@ export async function describeFrames(frames, intelligence) {
     const results = new Map();
     if (frames.length === 0)
         return results;
-    const images = frames.map((f) => ({
+    const validFrames = frames.filter((f) => f.observation.image_path !== null);
+    if (validFrames.length === 0)
+        return results;
+    const images = validFrames.map((f) => ({
         imagePath: f.observation.image_path,
         clusterId: 0, // Not used in our case
         timestamp: f.observation.timestamp,
     }));
     const descriptions = await intelligence.describeImages(images);
-    for (const [index, frame] of frames.entries()) {
+    for (const [index, frame] of validFrames.entries()) {
         const desc = descriptions[index];
         if (desc?.description) {
             results.set(frame.observation.id, desc.description);

package/dist/stats/observer.js

@@ -17,7 +17,7 @@ export function setupStatsObserver(repo) {
     pipelineEvents.on('run:end', (data) => {
         if (!currentRunId)
             return;
-        const startedAt = data.timestamp;
+        const _startedAt = data.timestamp;
         repo.updateRun(currentRunId, {
             status: data.status,
             completed_at: new Date(data.timestamp).toISOString(),