@lenne.tech/cli 1.17.0 → 1.19.0

package/bin/lt

@@ -155,8 +155,12 @@ function runCLI() {
     require(`${__dirname}/../build/cli`).run(process.argv);
   } else {
     // this runs from the typescript source (for dev only)
-    // hook into ts-node so we can run typescript on the fly
-    require('ts-node').register({ project: `${__dirname}/../tsconfig.json` });
+    // hook into ts-node so we can run typescript on the fly. Use
+    // `transpileOnly` to skip ts-node's runtime type-checking pass —
+    // it triples startup time (~4 s → ~1.2 s) without catching
+    // anything new, since `npm run lint` (eslint) and `npm run
+    // compile` (tsc) already type-check the project before publish.
+    require('ts-node').register({ project: `${__dirname}/../tsconfig.json`, transpileOnly: true });
     // run the CLI with the current process arguments
     require(`${__dirname}/../src/cli`).run(process.argv);
   }

package/build/commands/tools/ocr.js

@@ -0,0 +1,166 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const fs_1 = require("fs");
+const path_1 = require("path");
+const marker_1 = require("../../lib/marker");
+/**
+ * OCR command: convert PDFs (or a directory of PDFs) to clean Markdown
+ * using marker-pdf with Apple Silicon MPS acceleration when available.
+ *
+ * Marker is kept in `~/.lt/marker/.venv/`; it is auto-installed on the
+ * first run (~3 GB model download). Subsequent runs reuse the cache.
+ *
+ * Examples:
+ *   lt tools ocr ./report.pdf
+ *   lt tools ocr ./pdfs --output-dir ./md --workers 4
+ *   lt tools ocr --install
+ *   lt tools ocr --status
+ */
+const NewCommand = {
+    alias: ['ocr', 'pdf2md'],
+    description: 'OCR PDFs to Markdown via marker-pdf (MPS-accelerated on Apple Silicon)',
+    hidden: false,
+    name: 'ocr',
+    run: (toolbox) => __awaiter(void 0, void 0, void 0, function* () {
+        var _a, _b, _c, _d, _e;
+        const { parameters, print: { error, info, spin, warning }, } = toolbox;
+        const showStatus = !!parameters.options.status;
+        const installOnly = !!parameters.options.install;
+        // Status mode
+        if (showStatus) {
+            const status = yield (0, marker_1.getMarkerStatus)();
+            const device = (0, marker_1.resolveDevice)('auto');
+            info('marker-pdf status:');
+            info(`  installed: ${status.installed ? 'yes' : 'no'}`);
+            info(`  python3:   ${status.pythonAvailable ? 'yes' : 'no'}`);
+            info(`  uv:        ${status.uvAvailable ? 'yes' : 'no'}`);
+            info(`  venv:      ${status.venvPath}`);
+            info(`  device:    ${device} (auto-detected)`);
+            if (!toolbox.parameters.options.fromGluegunMenu)
+                process.exit(0);
+            return 'ocr';
+        }
+        // Install-only mode
+        if (installOnly) {
+            const installSpinner = spin('Installing marker-pdf …');
+            try {
+                yield (0, marker_1.installMarker)({
+                    onProgress: (msg) => {
+                        installSpinner.text = msg;
+                    },
+                });
+                installSpinner.succeed('marker-pdf installed');
+            }
+            catch (err) {
+                installSpinner.fail('Installation failed');
+                error(String(err.message));
+                if (!toolbox.parameters.options.fromGluegunMenu)
+                    process.exit(1);
+                return 'ocr';
+            }
+            if (!toolbox.parameters.options.fromGluegunMenu)
+                process.exit(0);
+            return 'ocr';
+        }
+        // Normal run: need an input path
+        const inputArg = parameters.first;
+        if (!inputArg) {
+            error('Missing input path. Usage:');
+            info('  lt tools ocr <file.pdf|directory>           Convert PDFs to Markdown');
+            info('  lt tools ocr --install                       Install marker-pdf locally');
+            info('  lt tools ocr --status                        Show installation status');
+            info('');
+            info('Options:');
+            info('  --output-dir <dir>     Output directory (default: <input>-MD/)');
+            info('  --workers <n>          Parallel workers for batch mode (default: 3)');
+            info('  --device <auto|mps|cuda|cpu>   Override TORCH_DEVICE (default: auto)');
+            info('  --skip-existing        Skip already-converted files (batch mode)');
+            info('  --keep-images          Extract embedded images (default: off)');
+            info('  --format <markdown|json|html|chunks>   Output format (default: markdown)');
+            if (!toolbox.parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'ocr';
+        }
+        const inputPath = (0, path_1.resolve)(process.cwd(), inputArg);
+        if (!(0, fs_1.existsSync)(inputPath)) {
+            error(`Input not found: ${inputPath}`);
+            if (!toolbox.parameters.options.fromGluegunMenu)
+                process.exit(1);
+            return 'ocr';
+        }
+        // Auto-install if needed
+        let status = yield (0, marker_1.getMarkerStatus)();
+        if (!status.installed) {
+            warning('marker-pdf not yet installed — running first-time setup …');
+            const installSpinner = spin('Installing marker-pdf (one-time, ~3 GB model download) …');
+            try {
+                yield (0, marker_1.installMarker)({
+                    onProgress: (msg) => {
+                        installSpinner.text = msg;
+                    },
+                });
+                installSpinner.succeed('marker-pdf installed');
+                status = yield (0, marker_1.getMarkerStatus)();
+            }
+            catch (err) {
+                installSpinner.fail('Installation failed');
+                error(String(err.message));
+                if (!toolbox.parameters.options.fromGluegunMenu)
+                    process.exit(1);
+                return 'ocr';
+            }
+        }
+        // Resolve options
+        const isDir = (0, fs_1.statSync)(inputPath).isDirectory();
+        const defaultOutput = isDir ? `${inputPath}-MD` : `${inputPath}.md-out`;
+        const outputDir = (0, path_1.resolve)(process.cwd(), String((_b = (_a = parameters.options['output-dir']) !== null && _a !== void 0 ? _a : parameters.options.outputDir) !== null && _b !== void 0 ? _b : defaultOutput));
+        const workers = Number((_c = parameters.options.workers) !== null && _c !== void 0 ? _c : 3);
+        const skipExisting = parameters.options['skip-existing'] !== false; // default: true
+        const keepImages = !!parameters.options['keep-images'];
+        const format = String((_d = parameters.options.format) !== null && _d !== void 0 ? _d : 'markdown');
+        const device = ((_e = parameters.options.device) !== null && _e !== void 0 ? _e : 'auto');
+        info(`OCR ${isDir ? 'batch' : 'single'} → ${outputDir}`);
+        info(`  device: ${(0, marker_1.resolveDevice)(device)}`);
+        if (isDir)
+            info(`  workers: ${workers}, skip-existing: ${skipExisting}`);
+        info('');
+        const runSpinner = spin('Converting (may take a while on first run while models load)…');
+        let lastLine = '';
+        const result = yield (0, marker_1.runMarker)(inputPath, {
+            device,
+            disableImages: !keepImages,
+            onLine: (line) => {
+                // Forward marker output to spinner text (last line) so the user sees progress
+                if (line.trim()) {
+                    lastLine = line.replace(/\s+/g, ' ').trim().slice(-160);
+                    runSpinner.text = lastLine;
+                }
+            },
+            outputDir,
+            outputFormat: format,
+            skipExisting,
+            workers,
+        });
+        if (result.exitCode === 0) {
+            runSpinner.succeed(`Done — output in ${outputDir}`);
+        }
+        else {
+            runSpinner.fail(`marker exited with code ${result.exitCode}: ${lastLine}`);
+            if (!toolbox.parameters.options.fromGluegunMenu)
+                process.exit(result.exitCode);
+        }
+        if (!toolbox.parameters.options.fromGluegunMenu)
+            process.exit(0);
+        return 'ocr';
+    }),
+};
+exports.default = NewCommand;

package/build/extensions/frontend-helper.js

@@ -63,6 +63,70 @@ class FrontendHelper {
         content = content.replace(/^(NUXT_PUBLIC_STORAGE_PREFIX=).*$/m, `$1${projectName}-local`);
         filesystem.write(envPath, content);
     }
+    /**
+     * Flatten the cloned nuxt-base-starter wrapper layout so the project's
+     * `projects/app/` directory IS the Nuxt app.
+     *
+     * `lenneTech/nuxt-base-starter` ships a wrapper repo: the root
+     * `package.json` is the `create-nuxt-base` scaffolder (a separate npm
+     * package — `bin/create-nuxt-base` lives at `index.js`), and the
+     * actual Nuxt app lives one level deeper at `nuxt-base-template/`.
+     * Without this flatten, the generated monorepo's `pnpm-workspace.yaml`
+     * and the README's `cd projects/app && pnpm install && pnpm dev`
+     * point at the wrapper, not the app, so `pnpm install` resolves the
+     * wrong dependencies and `pnpm dev` has nothing to run
+     * (LLM-test 2026-05-03 friction #3 entry 20:30).
+     *
+     * Defense-in-depth: only mutate the layout if extraction succeeds.
+     * If `nuxt-base-template/` is missing or isn't a directory (corrupt
+     * clone, future repo reshape that drops the wrapper), we return
+     * `{ flattened: false, reason }` and leave the original tree alone.
+     * The pre-flatten layout is annoying but functional — better than
+     * wiping a user's clone over an unexpected layout.
+     *
+     * @param dest - The cloned `projects/app/` directory.
+     * @returns Whether the flatten ran, plus a reason if it didn't.
+     */
+    flattenNuxtBaseTemplate(dest) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { filesystem } = this.toolbox;
+            const subdir = filesystem.path(dest, 'nuxt-base-template');
+            if (!filesystem.exists(subdir)) {
+                return { flattened: false, reason: 'no nuxt-base-template subdirectory' };
+            }
+            if (!filesystem.isDirectory(subdir)) {
+                // Stray file at the path we'd flatten — abort to avoid clobbering
+                // the user's tree on a corrupt clone.
+                return { flattened: false, reason: 'nuxt-base-template path exists but is not a directory' };
+            }
+            // Stage the template into a sibling directory before touching `dest`,
+            // so a copy failure leaves the original layout intact.
+            const parent = filesystem.path(dest, '..');
+            const stage = filesystem.path(parent, `.nuxt-base-template-staging-${Date.now()}-${process.pid}`);
+            try {
+                filesystem.copy(subdir, stage, { overwrite: true });
+            }
+            catch (err) {
+                // Couldn't stage — leave `dest` untouched and bubble the reason up.
+                filesystem.remove(stage);
+                return { flattened: false, reason: `failed to stage template: ${err.message}` };
+            }
+            try {
+                // Wipe the cloned root (wrapper package.json, index.js, lock file,
+                // README, etc.) and replace it with the staged template contents.
+                // gluegun's `filesystem.remove(dest)` removes the directory, so
+                // we re-create it before copying back so dotfiles land at the
+                // right level.
+                filesystem.remove(dest);
+                filesystem.dir(dest);
+                filesystem.copy(stage, dest, { overwrite: true });
+            }
+            finally {
+                filesystem.remove(stage);
+            }
+            return { flattened: true };
+        });
+    }
     /**
      * Setup Nuxt frontend
      * Handles template setup (link/copy/clone) and optional npm install
@@ -87,6 +151,14 @@ class FrontendHelper {
                 if (!result.success) {
                     return { method: result.method, path: result.path, success: false };
                 }
+                // After a clone, flatten the wrapper layout so `projects/app/`
+                // IS the Nuxt app (the cloned root is the `create-nuxt-base`
+                // scaffolder, not the app — see flattenNuxtBaseTemplate).
+                // Skip on link mode: a symlink points at the user's local
+                // checkout and must not have its template subdir torn out.
+                if (result.method === 'clone') {
+                    yield this.flattenNuxtBaseTemplate(dest);
+                }
                 // Run install if not skipped and not a symlink
                 if (!skipInstall && result.method !== 'link') {
                     try {

package/build/lib/marker.js

@@ -0,0 +1,218 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getMarkerStatus = getMarkerStatus;
+exports.installMarker = installMarker;
+exports.resolveDevice = resolveDevice;
+exports.runMarker = runMarker;
+/**
+ * marker-pdf integration for the lt CLI.
+ *
+ * Marker (https://github.com/datalab-to/marker) is a PyTorch-based
+ * PDF → Markdown converter with first-class layout, table and equation
+ * support. On Apple Silicon it leverages Metal Performance Shaders
+ * (MPS) for GPU-accelerated inference.
+ *
+ * The CLI keeps marker in an isolated Python virtualenv under
+ * `~/.lt/marker/.venv/` so that:
+ *   - we do not pollute the user's global Python environment
+ *   - the ~3 GB of model weights are downloaded only once
+ *   - subsequent runs start instantly (cached models)
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const promises_1 = require("fs/promises");
+const os_1 = require("os");
+const path_1 = require("path");
+const util_1 = require("util");
+const execAsync = (0, util_1.promisify)(child_process_1.exec);
+const MARKER_HOME = (0, path_1.join)((0, os_1.homedir)(), '.lt', 'marker');
+const VENV_DIR = (0, path_1.join)(MARKER_HOME, '.venv');
+const VENV_BIN = (0, path_1.join)(VENV_DIR, 'bin');
+const VENV_PYTHON = (0, path_1.join)(VENV_BIN, 'python3');
+const VENV_MARKER_SINGLE = (0, path_1.join)(VENV_BIN, 'marker_single');
+const VENV_MARKER_BATCH = (0, path_1.join)(VENV_BIN, 'marker');
+/**
+ * Detect tool availability.
+ */
+function getMarkerStatus() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const status = {
+            installed: false,
+            pythonAvailable: false,
+            uvAvailable: false,
+            venvPath: VENV_DIR,
+        };
+        try {
+            yield execAsync('python3 --version');
+            status.pythonAvailable = true;
+        }
+        catch (_a) {
+            // python3 missing
+        }
+        try {
+            yield execAsync('uv --version');
+            status.uvAvailable = true;
+        }
+        catch (_b) {
+            // uv missing — we'll fall back to python -m venv + pip
+        }
+        status.installed = (0, fs_1.existsSync)(VENV_MARKER_SINGLE) && (0, fs_1.existsSync)(VENV_MARKER_BATCH);
+        return status;
+    });
+}
+/**
+ * Install marker-pdf into ~/.lt/marker/.venv.
+ *
+ * Preferred path: `uv venv --python 3.12` + `uv pip install marker-pdf psutil`.
+ * Fallback: `python3 -m venv` + `pip install`.
+ */
+function installMarker() {
+    return __awaiter(this, arguments, void 0, function* (opts = {}) {
+        var _a;
+        const log = (_a = opts.onProgress) !== null && _a !== void 0 ? _a : (() => { });
+        const status = yield getMarkerStatus();
+        if (status.installed) {
+            log('marker already installed');
+            return;
+        }
+        if (!status.pythonAvailable) {
+            throw new Error('python3 is required but not found in PATH. Install Python 3.10+ (e.g. via Homebrew: `brew install python@3.12`)');
+        }
+        yield (0, promises_1.mkdir)(MARKER_HOME, { recursive: true });
+        const useUv = status.uvAvailable;
+        // 1. Create virtualenv
+        if (useUv) {
+            log('Creating venv with uv (Python 3.12)…');
+            yield execAsync(`uv venv --python 3.12 "${VENV_DIR}"`, { cwd: MARKER_HOME });
+        }
+        else {
+            log('Creating venv with python3 (uv not found, falling back)…');
+            yield execAsync(`python3 -m venv "${VENV_DIR}"`, { cwd: MARKER_HOME });
+        }
+        // 2. Install marker-pdf + psutil
+        // psutil is needed by the marker batch CLI; it is a soft dep on some
+        // marker-pdf releases, so we install it explicitly.
+        // We use shell quoting to handle macOS "Library" / spaces in paths.
+        const cmd = useUv
+            ? `uv pip install --python "${VENV_PYTHON}" marker-pdf psutil`
+            : `"${VENV_BIN}/pip" install marker-pdf psutil`;
+        log('Installing marker-pdf + dependencies (~3 GB models will download on first run)…');
+        // Increase maxBuffer because pip output is large
+        yield execAsync(cmd, { cwd: MARKER_HOME, maxBuffer: 100 * 1024 * 1024 });
+        if (!(0, fs_1.existsSync)(VENV_MARKER_SINGLE)) {
+            throw new Error(`marker installation finished but ${VENV_MARKER_SINGLE} not found`);
+        }
+        log('marker installed successfully');
+    });
+}
+/**
+ * Decide the correct TORCH_DEVICE for this machine.
+ */
+function resolveDevice(requested = 'auto') {
+    if (requested !== 'auto')
+        return requested;
+    if (process.platform === 'darwin' && process.arch === 'arm64')
+        return 'mps';
+    // We don't probe nvidia-smi here — let PyTorch decide CUDA at runtime
+    return 'cpu';
+}
+/**
+ * Run marker on a single PDF or a directory of PDFs.
+ */
+function runMarker(inputPath, opts) {
+    return __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        const status = yield getMarkerStatus();
+        if (!status.installed) {
+            throw new Error('marker is not installed. Run `lt tools ocr --install` first.');
+        }
+        const isDir = (0, fs_1.existsSync)(inputPath) && (yield Promise.resolve().then(() => __importStar(require('fs')))).statSync(inputPath).isDirectory();
+        const bin = isDir ? VENV_MARKER_BATCH : VENV_MARKER_SINGLE;
+        const args = [];
+        if (isDir) {
+            args.push(inputPath);
+        }
+        else {
+            args.push(inputPath);
+        }
+        args.push('--output_dir', opts.outputDir);
+        args.push('--output_format', (_a = opts.outputFormat) !== null && _a !== void 0 ? _a : 'markdown');
+        if (opts.disableImages)
+            args.push('--disable_image_extraction');
+        if (isDir) {
+            if (opts.skipExisting)
+                args.push('--skip_existing');
+            if (opts.workers && opts.workers > 0)
+                args.push('--workers', String(opts.workers));
+        }
+        const device = resolveDevice(opts.device);
+        return new Promise((resolve, reject) => {
+            var _a;
+            const proc = (0, child_process_1.spawn)(bin, args, {
+                env: Object.assign(Object.assign({}, process.env), { TORCH_DEVICE: device }),
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const onLine = (_a = opts.onLine) !== null && _a !== void 0 ? _a : ((l) => process.stdout.write(`${l}\n`));
+            const handleStream = (stream) => {
+                let buf = '';
+                stream.on('data', (chunk) => {
+                    var _a;
+                    buf += chunk.toString();
+                    const lines = buf.split(/\r?\n/);
+                    buf = (_a = lines.pop()) !== null && _a !== void 0 ? _a : '';
+                    for (const line of lines)
+                        if (line)
+                            onLine(line);
+                });
+            };
+            handleStream(proc.stdout);
+            handleStream(proc.stderr);
+            proc.on('close', (code) => {
+                resolve({ exitCode: code !== null && code !== void 0 ? code : 0 });
+            });
+            proc.on('error', reject);
+        });
+    });
+}

package/docs/commands.md

@@ -1463,6 +1463,53 @@ lt tools crawl https://lenne.tech --all --noConfirm
 lt tools crawl https://example.com --all --no-render --no-prune --noConfirm
 ```
 
+### `lt tools ocr`
+
+Converts PDFs to clean Markdown using [marker-pdf](https://github.com/datalab-to/marker) — a PyTorch-based, layout-aware OCR engine that produces real Markdown tables, headings and lists. On Apple Silicon (M-series) inference runs on the GPU via Metal Performance Shaders (MPS) and is typically 5–15× faster than CPU-only PDF text extractors. Marker is auto-installed into an isolated virtualenv at `~/.lt/marker/.venv/` on first use; subsequent runs reuse the cached environment and ~3 GB of model weights.
+
+**Aliases:** `ocr`, `pdf2md`
+
+**Usage:**
+```bash
+lt tools ocr <file.pdf|directory> [options]
+lt tools ocr --status              # Show installation status
+lt tools ocr --install             # Install marker-pdf without converting anything
+```
+
+**Options:**
+- `--output-dir <dir>` — Output directory (default: `<input>-MD/` for batch, `<input>.md-out/` for single).
+- `--workers <n>` — Parallel worker processes for batch mode (default `3`).
+- `--device <auto|mps|cuda|cpu>` — Override `TORCH_DEVICE`. Default `auto` picks `mps` on Apple Silicon, `cpu` elsewhere. Set `cuda` if running on a Linux machine with an NVIDIA GPU and the appropriate PyTorch CUDA build.
+- `--skip-existing` / `--no-skip-existing` — Skip already-converted files in batch mode (default **on**).
+- `--keep-images` — Extract embedded images alongside the Markdown (default **off** — Markdown only).
+- `--format <markdown|json|html|chunks>` — Output format (default `markdown`).
+
+**Setup notes:**
+- Requires `python3` (≥ 3.10) on PATH.
+- Uses `uv` if available (fastest install path); falls back to `python3 -m venv` + `pip` otherwise.
+- The first conversion is slower because the model weights download (~3 GB). Subsequent runs start instantly.
+- Apple Silicon: `device: mps` is auto-selected. Linux/CUDA: pass `--device cuda`.
+
+**Examples:**
+```bash
+# Inspect tooling status (python3, uv, venv path, auto-detected device)
+lt tools ocr --status
+
+# One-time install (skip if you just want to convert and let auto-install handle it)
+lt tools ocr --install
+
+# Convert a single PDF (creates ./report.pdf.md-out/report/report.md)
+lt tools ocr ./report.pdf
+
+# Batch a directory with 4 parallel workers
+lt tools ocr ./pdfs --output-dir ./md --workers 4
+
+# Force CPU mode (e.g. when MPS-related crashes occur on Sonoma)
+lt tools ocr ./report.pdf --device cpu
+```
+
+**When to reach for this command vs. the lt-knowledge ingest pipeline:** `lt tools ocr` is for **local developer workflows** — quick PDF → Markdown for research, demos, validation sets, sanity checks. For productive ingestion (Vector / Graph / Wiki layers, confidence-based fallback, Whisper for audio, archive-aware processing) use the lt-knowledge stack with its Docling + LightOnOCR sidecars. Marker is intentionally **not** added there because its MPS advantage doesn't apply in Linux containers and Docling already covers the same use cases with native confidence scoring (see `lt-knowledge/docs/OCR-COMPARISON-MARKER.md`).
+
 ---
 
 ## Configuration Priority

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lenne.tech/cli",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "description": "lenne.Tech CLI: lt",
   "keywords": [
     "lenne.Tech",