@trillboards/edge-sdk 0.2.3 → 0.2.6

package/dist/cli.js

@@ -34,35 +34,166 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPermissionError = isPermissionError;
+exports.configWritePermissionMessage = configWritePermissionMessage;
+exports.writePairedConfig = writePairedConfig;
 const config_1 = require("./config");
-const EdgeAgent_1 = require("./EdgeAgent");
-const init_1 = require("./init");
-const status_1 = require("./status");
-const diagnose_1 = require("./diagnose");
-const demo_1 = require("./demo");
+const autoSense_1 = require("./autoSense");
+const sensingRunMode_1 = require("./sensingRunMode");
+const gemmaModelOta_1 = require("./gemmaModelOta");
+const keepAwake_1 = require("./keepAwake");
+const runtimePaths_1 = require("./runtimePaths");
+const modelIntegrity_1 = require("./modelIntegrity");
+const PairClient_1 = require("./PairClient");
+const pairVerify_1 = require("./pairVerify");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const https = __importStar(require("https"));
-const VERSION = '0.2.3';
+const os = __importStar(require("os"));
+const crypto_1 = require("crypto");
+// NOTE: the heavyweight command handlers (`start` → EdgeAgent → edge-sensing →
+// onnxruntime-node, plus init/status/diagnose/demo) are loaded LAZILY inside
+// their switch arms rather than as top-level imports. This keeps the
+// cloud-sensing + pair entrypoints (the macOS/edge "cloud-sense" connector
+// installer surface) free of the 200 MB+ ONNX runtime: a bundled-runtime build
+// that ships ONLY edge-core + edge-platform-rtsp + edge-sdk can run
+// `cloud-sense`, `pair`, `version`, and `help` without the local-inference
+// stack ever being required. `mcp` was already lazy-required for the same
+// reason.
+// Source the connector version from package.json (the single source of truth)
+// so `version`/`--version`/help and the pairing log can never drift from the
+// published package. dist/cli.js lives in dist/, so ../package.json resolves to
+// the edge-sdk package root both in-repo and in the shipped .pkg (where
+// build-macos-pkg.sh stages package.json next to dist/) — and npm always ships
+// package.json. Required at runtime (commonjs), like the lazy command handlers.
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const VERSION = require('../package.json').version;
 async function main() {
     const args = process.argv.slice(2);
     const command = args[0];
     switch (command) {
-        case 'demo':
-            await (0, demo_1.runDemo)();
+        case 'demo': {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runDemo } = require('./demo');
+            await runDemo();
             break;
-        case 'init':
-            await (0, init_1.runInit)();
+        }
+        case 'init': {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runInit } = require('./init');
+            await runInit();
             break;
+        }
         case 'start':
             await startAgent(args.slice(1));
             break;
-        case 'status':
-            await (0, status_1.runStatus)(args.slice(1));
+        case 'cloud-sense':
+            (0, keepAwake_1.startKeepAwake)();
+            await startCloudSensing(args.slice(1));
+            break;
+        case 'local-sense':
+            (0, keepAwake_1.startKeepAwake)();
+            await startLocalSensing(args.slice(1));
+            break;
+        case 'auto-sense':
+            // Prefer on-device local sensing and wait for LiteRT-LM when it is still
+            // provisioning. Cloud inference is available only through explicit config;
+            // the supervisor starts local automatically with NO restart once ready.
+            // The supervisor owns the lifecycle + builds the SAME managers cloud-sense /
+            // local-sense use (see autoSense.ts + sensingRunMode.ts).
+            (0, keepAwake_1.startKeepAwake)();
+            await (0, autoSense_1.runAutoSense)(args.slice(1));
+            break;
+        case 'sense':
+        case 'combined-sense': {
+            (0, keepAwake_1.startKeepAwake)();
+            // APK parity: run the on-device ONNX ZOO (EdgeAgent) AND the VLM sensing
+            // manager (auto-detected local/cloud, like auto-sense) CONCURRENTLY in ONE
+            // process. Lazy-require like `start` so the cloud-sense/pair bundle stays
+            // free of the ONNX runtime (combinedSense → EdgeAgent → onnxruntime-node).
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runCombinedSense } = require('./combinedSense');
+            await runCombinedSense(args.slice(1));
+            break;
+        }
+        case 'pair':
+            await runPair(args.slice(1));
+            break;
+        case 'setup': {
+            // Validate-first onboarding (direction-inverted pairing): WE display a
+            // short code, the owner claims it in the portal, the portal drives
+            // discovery/validation through our setup session, and the finalized
+            // config lands here — no screens exist until streams are PROVEN. Exit
+            // codes: 0 config written (wrapper starts the service), 2 session
+            // expired/timeout (re-run for a fresh code), 1 hard error.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runSetupMode } = require('./setupMode');
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { createSetupProgressReporter } = require('./setupProgress');
+            const setupArgs = args.slice(1);
+            const statusFile = getArg(setupArgs, '--status-file');
+            const rc = await runSetupMode({
+                apiBaseUrl: getArg(setupArgs, '--api-base') || process.env.TRILLBOARDS_API_BASE || 'https://api.trillboards.com',
+                portalBaseUrl: getArg(setupArgs, '--portal-base') || process.env.TRILLBOARDS_PORTAL_BASE || 'https://trillboards.com',
+                configPath: getArg(setupArgs, '--config') || 'trillboards.config.json',
+                connectorVersion: VERSION,
+                ffmpegPath: (0, runtimePaths_1.resolveFfmpegBinaryPath)(getArg(setupArgs, '--ffmpeg')),
+                ...(statusFile ? { progress: createSetupProgressReporter(statusFile) } : {}),
+            });
+            process.exit(rc);
+            break;
+        }
+        case 'setup-status': {
+            // Internal platform-wrapper command. It advances the same credential-free
+            // progress file after setup mode hands off to model/service bootstrap.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { SETUP_PROGRESS_STAGES, writeSetupProgressFile } = require('./setupProgress');
+            const statusArgs = args.slice(1);
+            const statusFile = getArg(statusArgs, '--status-file');
+            const stage = getArg(statusArgs, '--stage');
+            if (!statusFile || !stage || !SETUP_PROGRESS_STAGES.includes(stage)) {
+                process.exit(2);
+            }
+            const cameraCountRaw = getArg(statusArgs, '--camera-count');
+            writeSetupProgressFile(statusFile, {
+                stage,
+                title: getArg(statusArgs, '--title') || 'Camera setup',
+                message: getArg(statusArgs, '--message') || '',
+                ...(cameraCountRaw ? { cameraCount: Number(cameraCountRaw) } : {}),
+                ...(stage === 'error' || stage === 'local_ai_error' ? { recoverable: true } : {}),
+            });
+            break;
+        }
+        case 'verify-connection': {
+            // One authenticated round-trip proving the SAVED pairing works from this
+            // machine (network + token). The install wrappers (trillboards-pair.cmd /
+            // pair.command) branch on its exit codes — see pairVerify.ts for the
+            // contract. Lazy-require to keep the pair hot path lean.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runVerifyConnection } = require('./pairVerify');
+            await runVerifyConnection(args.slice(1));
             break;
-        case 'diagnose':
-            await (0, diagnose_1.runDiagnose)(args.slice(1));
+        }
+        case 'discover': {
+            // Lazy-require: discovery (UDP WS-Discovery + NVR channel-range expansion)
+            // is a small, optional helper — keep it off the cloud-sense/pair hot path.
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runDiscover } = require('./discovery');
+            await runDiscover(args.slice(1));
+            break;
+        }
+        case 'status': {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runStatus } = require('./status');
+            await runStatus(args.slice(1));
+            break;
+        }
+        case 'diagnose': {
+            // eslint-disable-next-line @typescript-eslint/no-var-requires
+            const { runDiagnose } = require('./diagnose');
+            await runDiagnose(args.slice(1));
             break;
+        }
         case 'mcp':
             await startMcpServer();
             break;
@@ -95,7 +226,13 @@ async function startAgent(args) {
     console.log(`Trillboards Edge AI SDK v${VERSION}`);
     console.log(`Loading config: ${configPath}`);
     const config = (0, config_1.loadConfig)(configPath);
-    const agent = new EdgeAgent_1.EdgeAgent(config);
+    // Lazy-require so the cloud-sense/pair connector bundle (which omits the
+    // local ONNX inference stack) never pays for EdgeAgent → edge-sensing →
+    // onnxruntime-node at module-load. `start` is the full-agent (local
+    // inference) entrypoint and needs it; cloud-sense does not.
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const { EdgeAgent } = require('./EdgeAgent');
+    const agent = new EdgeAgent(config);
     agent.on('started', ({ fingerprint, tier }) => {
         console.log(`\n  Device:      ${fingerprint}`);
         console.log(`  Tier:        TIER_${tier}`);
@@ -111,6 +248,314 @@ async function startAgent(args) {
     // Keep the process running
     await new Promise(() => { });
 }
+/**
+ * Fire a best-effort ONVIF LAN scan + report on connector startup so the portal's
+ * "Find my cameras" can surface the venue's real cameras. Non-blocking, never
+ * throws — returns a promise the caller can settle before a no-feeds exit. Uses
+ * any feed's device token (all share the owner). Lazy-requires the reporter so the
+ * light entrypoints don't pay for it unless cloud-sensing actually runs.
+ */
+function kickStartupDiscovery(config) {
+    try {
+        const deviceToken = (config.cameras || []).find((c) => c && c.deviceToken)?.deviceToken || config.deviceToken;
+        if (!config.apiBaseUrl || !deviceToken)
+            return Promise.resolve();
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const { discoverAndReport } = require('./DiscoveryReportClient');
+        return discoverAndReport({
+            apiBaseUrl: config.apiBaseUrl,
+            deviceToken,
+            log: (m) => console.log(m),
+        }).then(() => undefined);
+    }
+    catch {
+        return Promise.resolve();
+    }
+}
+/**
+ * Thin cloud-sensing run mode: RTSP frame → POST /v2/earner/audience-analyze.
+ * No local ONNX. Supports multi-channel via `cameras: [...]` (N loops, one
+ * token + one profile per channel).
+ */
+async function startCloudSensing(args) {
+    const configIdx = args.indexOf('--config');
+    const configPath = configIdx >= 0 && args[configIdx + 1] ? args[configIdx + 1] : 'trillboards.config.json';
+    console.log(`Trillboards Edge AI SDK v${VERSION} — cloud-sensing mode`);
+    console.log(`Loading config: ${configPath}`);
+    const config = (0, config_1.loadConfig)(configPath);
+    // Kick a best-effort ONVIF LAN scan on startup so the portal's "Find my
+    // cameras" surfaces the venue's real cameras — CRUCIALLY even when feeds were
+    // paired WITHOUT an rtspUrl (creds-local: the owner didn't know the DVR's IP),
+    // which yields zero sensable feeds below. Fire-and-forget; we only settle it
+    // before a no-feeds exit so the scan actually gets to POST.
+    const discoveryDone = kickStartupDiscovery(config);
+    // Build the manager (feed resolution + banner + event logging) via the shared
+    // helper — the SAME construction auto-sense uses. Null ⇒ no feeds configured.
+    const manager = (0, sensingRunMode_1.buildCloudSensingManager)(config, undefined, { configPath });
+    if (!manager) {
+        // No sensable feeds (e.g. all feeds are creds-local, no rtspUrl). Let the
+        // startup discovery finish + report so the owner still sees their cameras in
+        // the portal, then exit.
+        await discoveryDone;
+        process.exit(1);
+        return;
+    }
+    const shutdown = async () => {
+        console.log('\nStopping cloud-sensing…');
+        await manager.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await manager.start();
+    console.log('Cloud-sensing started. Press Ctrl+C to stop.');
+    // Keep the process running
+    await new Promise(() => { });
+}
+/**
+ * On-device LOCAL sensing: RTSP frame → LOCAL VLM (LiteRT-LM serving Gemma 4
+ * E2B, constrained structured output via tool-calling) → POST the STRUCTURED
+ * result as `preAnalyzed` to /v2/earner/audience-analyze (SKIPS the cloud VLM →
+ * no Vertex cost). For capable hosts running `litert-lm serve`. Multi-channel
+ * via `cameras: [...]`.
+ */
+async function startLocalSensing(args) {
+    const configIdx = args.indexOf('--config');
+    const configPath = configIdx >= 0 && args[configIdx + 1] ? args[configIdx + 1] : 'trillboards.config.json';
+    console.log(`Trillboards Edge AI SDK v${VERSION} — LOCAL-sensing mode (on-device VLM)`);
+    console.log(`Loading config: ${configPath}`);
+    const config = (0, config_1.loadConfig)(configPath);
+    // Build the manager (feed resolution + banner + event logging) via the shared
+    // helper — the SAME construction auto-sense uses. Null ⇒ no feeds configured.
+    const manager = (0, sensingRunMode_1.buildLocalSensingManager)(config, undefined, { configPath });
+    if (!manager) {
+        process.exit(1);
+        return;
+    }
+    // Keep the on-device VLM (Gemma) up to date over the air while local-sense runs
+    // (edge-core ModelManager + /v1/federated/models, S3 presigned). Non-fatal: a
+    // null handle (disabled / startup failure) never blocks sensing.
+    const gemmaOta = (0, gemmaModelOta_1.startGemmaModelOta)(config);
+    const shutdown = async () => {
+        console.log('\nStopping local-sensing…');
+        gemmaOta?.stop();
+        await manager.stop();
+        process.exit(0);
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+    await manager.start();
+    console.log('Local-sensing started (on-device VLM). Press Ctrl+C to stop.');
+    // Keep the process running
+    await new Promise(() => { });
+}
+/** Read a `--flag value` argument (returns undefined if absent). */
+function getArg(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 && args[i + 1] ? args[i + 1] : undefined;
+}
+/** Stable, non-PII connector fingerprint from this host (for pairing audit). */
+function hostFingerprint() {
+    const raw = `${os.hostname()}|${process.platform}|${os.arch()}`;
+    return 'conn_' + (0, crypto_1.createHash)('sha256').update(raw).digest('hex').slice(0, 24);
+}
+/**
+ * True if a filesystem error is a PERMISSION failure (EACCES/EPERM), or its
+ * message says so. This is the signature of the paired-config write failing
+ * because ~/Library/Application Support/Trillboards is owned by another account
+ * — which happens when the `.pkg` was installed with admin rights and its
+ * postinstall ran as root, creating that dir ROOT-OWNED. It is NOT a bad or
+ * expired claim code, so it must never be reported as one.
+ */
+function isPermissionError(err) {
+    const e = err;
+    if (!e)
+        return false;
+    if (e.code === 'EACCES' || e.code === 'EPERM')
+        return true;
+    return /permission denied/i.test(String(e.message ?? ''));
+}
+/**
+ * The operator-facing remediation when the paired config can't be written
+ * because its directory is owned by another account. Names the REAL cause and
+ * the exact one-line fix — deliberately NOT "double-check the code" (pairing
+ * already SUCCEEDED; only the local save failed). Mirrors the guidance in
+ * deploy/macos/pair.command so the GUI and headless paths say the same thing.
+ */
+function configWritePermissionMessage(resolvedConfigPath) {
+    const dir = path.dirname(resolvedConfigPath);
+    return (`\nPaired successfully, but Trillboards could not save its settings to:\n` +
+        `  ${resolvedConfigPath}\n\n` +
+        `That folder is owned by another account: the installer was run with admin\n` +
+        `rights, so it created the folder as root and this pairing (which runs as you)\n` +
+        `can't write there. This is NOT a bad code — pairing worked.\n\n` +
+        `Fix it once by pasting this in Terminal, then run pairing again:\n` +
+        `  sudo chown -R "$(whoami)" "${dir}"\n`);
+}
+/**
+ * Persist the paired config, translating a PERMISSION failure into the clear
+ * remediation above (and exiting non-zero) instead of letting a raw EACCES
+ * bubble up as an opaque "Fatal error" that the GUI then mislabels "check the
+ * code". Any OTHER write error is re-thrown unchanged (surfaced as "Fatal
+ * error: …"). The writer is injectable for tests (mirrors PairClient's poster).
+ */
+function writePairedConfig(resolvedConfigPath, serialized, writeFile = (p, data, opts) => fs.writeFileSync(p, data, opts)) {
+    try {
+        writeFile(resolvedConfigPath, serialized, { mode: 0o600 });
+    }
+    catch (err) {
+        if (isPermissionError(err)) {
+            console.error(configWritePermissionMessage(resolvedConfigPath));
+            process.exit(1);
+            return;
+        }
+        throw err;
+    }
+}
+/**
+ * First-run pairing: exchange a portal claim code for the connector config and
+ * write trillboards.config.json. The device token is delivered ONLY here (never
+ * baked into the installer), and RTSP credentials can be left local — feeds
+ * without an rtspUrl are flagged so the operator fills them in on this machine.
+ *
+ *   trillboards-edge pair --code XXXX-XXXX [--api-base URL] [--config PATH] [--start]
+ *   trillboards-edge pair --qr <image.png|.jpg>  (scan the portal QR instead of typing the code)
+ *
+ * Exit codes (the install wrappers branch on these — keep stable):
+ *   0  paired, config written, AND the post-pair connection check passed
+ *   1  pairing failed (classified: bad/expired code, network, rate-limit, server)
+ *   6  paired + config written, but the connection check hit a NETWORK/SERVER
+ *      failure — the code IS spent and the config IS saved; the operator fixes
+ *      connectivity and re-runs the helper WITHOUT needing a new code.
+ *   7  paired + config written, but the API REJECTED the fresh pairing
+ *      (verify kind 'auth', HTTP 401/403) — the saved config is unusable and
+ *      the operator DOES need a fresh code. Distinct from 6 so the wrappers
+ *      never promise "no new code needed" for an auth rejection.
+ */
+async function runPair(args) {
+    let code = getArg(args, '--code') || getArg(args, '-c');
+    const qrPath = getArg(args, '--qr');
+    const apiBase = getArg(args, '--api-base') ||
+        process.env.TRILLBOARDS_API_BASE ||
+        'https://api.trillboards.com';
+    const configPath = getArg(args, '--config') || 'trillboards.config.json';
+    const doStart = args.includes('--start');
+    // --qr: scan the claim code from an image of the portal's Install-step QR (a
+    // screenshot or phone photo) so the owner doesn't hand-type it. The decoder is
+    // lazy-required so the common `pair --code` path stays free of the image deps.
+    // An explicit --code always wins (no surprise when both are passed).
+    if (!code && qrPath) {
+        try {
+            const { decodeClaimCodeFromImageFile } = require('./qrScanner');
+            code = await decodeClaimCodeFromImageFile(qrPath);
+            console.log(`  Scanned claim code from ${qrPath}`);
+        }
+        catch (err) {
+            console.error(`\nCouldn't read a claim code from the QR image: ${err instanceof Error ? err.message : err}`);
+            console.error("Use a clear PNG/JPEG of the QR shown on the portal's Install step.");
+            process.exit(1);
+            return;
+        }
+    }
+    if (!code) {
+        console.error('Pairing requires a claim code:');
+        console.error('  trillboards-edge pair --code XXXX-XXXX');
+        console.error('  trillboards-edge pair --qr /path/to/qr.png   (scan the portal QR instead)');
+        console.error('Get one from the Trillboards portal → Add a camera → Install.');
+        process.exit(1);
+        return;
+    }
+    console.log(`Trillboards Edge AI SDK v${VERSION} — pairing`);
+    console.log(`  API:   ${apiBase}`);
+    console.log(`  Code:  ${(0, PairClient_1.normalizeClaimCode)(code)}`);
+    const logDir = (0, pairVerify_1.defaultLogDir)();
+    const client = new PairClient_1.PairClient({ apiBaseUrl: apiBase });
+    // Classify EVERY failure mode honestly. A transport throw (no response) and a
+    // non-2xx response get different, owner-grade copy — and only a SERVER
+    // rejection of the code may say "get a fresh code" (the historical failure was
+    // blaming valid codes for local EACCES/network problems — see pairVerify.ts).
+    let res;
+    try {
+        res = await client.pair({
+            claimCode: code,
+            connectorVersion: VERSION,
+            deviceFingerprint: hostFingerprint(),
+        });
+    }
+    catch (err) {
+        const failure = (0, pairVerify_1.classifyPairFailure)({ thrown: err });
+        const logFile = (0, pairVerify_1.appendPairLog)(logDir, [
+            `pair: transport failure (${failure.kind})`,
+            `pair: ${err instanceof Error ? err.message : String(err)}`,
+        ]);
+        console.error(`\nPairing did not complete.\n${failure.message}`);
+        if (logFile)
+            console.error(`\nDetails saved to: ${logFile}`);
+        process.exit(1);
+        return;
+    }
+    if (!res.ok || !res.config) {
+        const failure = (0, pairVerify_1.classifyPairFailure)({ statusCode: res.statusCode, error: res.error });
+        const logFile = (0, pairVerify_1.appendPairLog)(logDir, `pair: rejected (${failure.kind}, HTTP ${res.statusCode}): ${res.error ?? ''}`);
+        console.error(`\nPairing failed.\n${failure.message}`);
+        if (logFile)
+            console.error(`\nDetails saved to: ${logFile}`);
+        process.exit(1);
+        return;
+    }
+    const file = (0, PairClient_1.pairedConfigToFile)(res.config);
+    const resolved = path.resolve(configPath);
+    // Pairing succeeded — persist the config. A PERMISSION failure here (the
+    // config dir is root-owned from an admin/system install) is reported with the
+    // real cause + one-line chown fix, NOT as a bad code. See writePairedConfig.
+    writePairedConfig(resolved, JSON.stringify(file, null, 2) + '\n');
+    console.log(`\n  Paired ${res.config.cameras.length} camera feed(s):`);
+    for (const cam of res.config.cameras) {
+        console.log(`    - ${cam.name} → ${cam.screenId}${cam.rtspUrl ? '' : '  (add rtspUrl locally)'}`);
+    }
+    console.log(`  Config written: ${resolved}`);
+    const needRtsp = res.config.cameras.filter((c) => !c.rtspUrl);
+    if (needRtsp.length > 0) {
+        console.log(`\n  ${needRtsp.length} feed(s) need an RTSP URL added to ${configPath} ` +
+            '(camera credentials stay on this machine).');
+    }
+    // Post-pair verification: one authenticated round-trip with a freshly-minted
+    // device token, so "paired" is PROVEN to work from this machine (network path
+    // + token accepted), not assumed. On failure the code is already spent and the
+    // config already saved — exit 6 so the wrappers say "fix the connection and
+    // re-run, NO new code needed" instead of the failure path's "get a fresh code".
+    console.log('\n  Checking the connection to Trillboards…');
+    const verifiable = (0, pairVerify_1.readVerifiableConfig)(resolved);
+    const verify = verifiable
+        ? await (0, pairVerify_1.verifyApiConnection)(verifiable)
+        : { ok: false, kind: 'no_config', message: 'saved config has no device token' };
+    (0, pairVerify_1.appendPairLog)(logDir, [
+        `pair: ok (${res.config.cameras.length} feed(s), ${needRtsp.length} missing rtspUrl)`,
+        `pair: connection check ${verify.kind}`,
+    ]);
+    if (verify.ok) {
+        console.log('  Connected to Trillboards — this machine can reach the API and the pairing is valid.');
+    }
+    else {
+        // Never auto-start against an unverified connection (--start included).
+        // An AUTH rejection (the fresh token itself was refused) needs a NEW code —
+        // exit 7 so the wrappers don't give the connectivity-resume copy ("you will
+        // NOT need a new code"), which would be a lie for this case. Network/server
+        // failures exit 6: fix connectivity, re-run, same code stays unnecessary.
+        console.error(`\n${verify.message}`);
+        process.exit(verify.kind === 'auth' ? 7 : 6);
+        return;
+    }
+    if (doStart) {
+        if (needRtsp.length > 0) {
+            console.error('\nCannot auto-start: some feeds are missing rtspUrl. Edit the config, then run `auto-sense`.');
+            process.exit(1);
+            return;
+        }
+        console.log('\nStarting local-first sensing…\n');
+        await (0, autoSense_1.runAutoSense)(['--config', configPath]);
+    }
+}
 const MODEL_URLS = {
     'blazeface.onnx': 'https://models.trillboards.com/blazeface_128x128.onnx',
     'yamnet.onnx': 'https://models.trillboards.com/yamnet_classification.onnx',
@@ -124,6 +569,7 @@ async function downloadModels(args) {
     }
     console.log(`Downloading ONNX models to: ${resolved}`);
     console.log('');
+    const failed = [];
     for (const [filename, url] of Object.entries(MODEL_URLS)) {
         const dest = path.join(resolved, filename);
         if (fs.existsSync(dest)) {
@@ -133,17 +579,29 @@ async function downloadModels(args) {
         console.log(`  [GET]  ${filename}...`);
         try {
             await downloadFile(url, dest);
+            // A 200 is not a model. models.trillboards.com answers every path with the
+            // marketing SPA's index.html (2490 bytes, HTTP 200), so without this the
+            // command wrote a web page to blazeface.onnx and printed `[OK] (0.0 MB)`.
+            (0, modelIntegrity_1.assertOnnxModel)(dest, filename);
             const stats = fs.statSync(dest);
             const sizeMb = (stats.size / (1024 * 1024)).toFixed(1);
             console.log(`  [OK]   ${filename} (${sizeMb} MB)`);
         }
         catch (err) {
+            failed.push(filename);
             console.error(`  [FAIL] ${filename}: ${err instanceof Error ? err.message : err}`);
             // Remove partial download
             if (fs.existsSync(dest))
                 fs.unlinkSync(dest);
         }
     }
+    if (failed.length > 0) {
+        console.error(`\nFAILED to download ${failed.length} of ${Object.keys(MODEL_URLS).length} model(s): ${failed.join(', ')}.`);
+        console.error('No usable model was written. Sensing that needs these models will report the ' +
+            'camera/microphone subsystem as ERROR until a valid model is placed in this directory.');
+        process.exitCode = 1;
+        return;
+    }
     console.log('\nDone. Set models.dir in your config to point to this directory.');
 }
 function downloadFile(url, dest, maxRedirects = 5) {
@@ -200,6 +658,14 @@ Usage:
   trillboards-edge demo                            Try it instantly — no token, no camera, no setup
   trillboards-edge init                            Interactive setup wizard
   trillboards-edge start [--config <path>]         Start the edge agent
+  trillboards-edge cloud-sense [--config <path>]   Stream RTSP frame(s) to cloud VLM (no local ONNX)
+  trillboards-edge auto-sense [--config <path>]    Use on-device VLM; wait locally while its model prepares
+  trillboards-edge sense [--config <path>]         Run the ONNX zoo AND the VLM together (APK parity)
+  trillboards-edge setup [--config <path>]         Validate-first onboarding: opens the portal and keeps a code fallback
+  trillboards-edge pair --code <XXXX-XXXX>         Pair with a portal claim code (writes config)
+  trillboards-edge pair --qr <image.png>           Pair by scanning a screenshot/photo of the portal QR
+  trillboards-edge verify-connection [--config p]  Prove the saved pairing works (exit 0=ok 2=network 3=auth 4=no config)
+  trillboards-edge discover                         Find cameras on your network (ONVIF) or expand an NVR's channels
   trillboards-edge status [--host h] [--port p]    Show agent status dashboard
   trillboards-edge diagnose [--json]               Run system diagnostics
   trillboards-edge mcp                             Start MCP server (for AI agent integration)
@@ -217,6 +683,10 @@ Examples:
   # Quick start with default config
   trillboards-edge start --config trillboards.config.json
 
+  # Find cameras without typing a single RTSP URL
+  trillboards-edge discover                                  # scan the LAN for ONVIF cameras
+  trillboards-edge discover --nvr 192.168.1.10 --brand hikvision --channels 8 --user admin --pass ****
+
   # Check agent status (or watch in real-time)
   trillboards-edge status
   trillboards-edge status --watch
@@ -232,8 +702,8 @@ Examples:
   trillboards-edge mcp
 
   # Docker deployment
-  docker run -e DEVICE_TOKEN=xxx trillboards/edge-sdk:latest
-  docker run --gpus all -e DEVICE_TOKEN=xxx trillboards/edge-sdk:cuda
+  docker run -e DEVICE_TOKEN=xxx ghcr.io/trillboards/edge-sdk:latest
+  docker run --gpus all -e DEVICE_TOKEN=xxx ghcr.io/trillboards/edge-sdk:cuda
 
 Config file (trillboards.config.json):
   {
@@ -246,12 +716,25 @@ Config file (trillboards.config.json):
     "kiosk": { "enabled": true }
   }
 
+Cloud-sensing config (point any RTSP camera / NVR at Trillboards — no ONNX):
+  {
+    "apiBaseUrl": "https://api.trillboards.com",
+    "cloudSensing": { "enabled": true },
+    "cameras": [
+      { "name": "Parking lot", "screenId": "scr_lot",  "deviceToken": "tok1", "rtspUrl": "rtsp://user:pass@nvr:554/ch01" },
+      { "name": "Register",    "screenId": "scr_reg",  "deviceToken": "tok2", "rtspUrl": "rtsp://user:pass@nvr:554/ch02" }
+    ]
+  }
+  # Each feed = one screen = one device token = one sensing profile.
+  # Single feed: set "camera": { "rtspUrl": "..." } + top-level "deviceToken".
+
 Status endpoint (when agent is running):
   curl http://localhost:9090/status    Full JSON status
   curl http://localhost:9090/health    Health check (200/503)
   curl http://localhost:9090/metrics   Prometheus metrics
 
 Supported platforms:
+  - macOS 12+ (Apple Silicon + Intel) — one-click signed installer
   - Linux (Ubuntu 18.04+, Debian 10+, ARM64/x64)
   - Windows 10+ (x64)
 
@@ -262,8 +745,15 @@ Execution providers:
   - cuda      NVIDIA GPU (requires CUDA toolkit)
 `);
 }
-main().catch((err) => {
-    console.error(`Fatal error: ${err instanceof Error ? err.message : err}`);
-    process.exit(1);
-});
+// Auto-run ONLY when this file is the process entrypoint. The bundled
+// `trillboards-edge` launcher does `exec node …/dist/cli.js` and npm's bin shim
+// runs it directly — both make require.main === module true, so production
+// behavior is unchanged. Guarding here lets the unit tests import the exported
+// helpers (writePairedConfig, …) without dispatching a real CLI command.
+if (require.main === module) {
+    main().catch((err) => {
+        console.error(`Fatal error: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    });
+}
 //# sourceMappingURL=cli.js.map