@juspay/neurolink 9.44.1 → 9.48.1

package/dist/cli/commands/proxy.js

@@ -11,7 +11,7 @@
  */
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 import chalk from "chalk";
 import ora from "ora";
 import { buildProxyHealthResponse, createProxyReadinessState, markProxyReady, waitForProxyReadiness, } from "../../lib/proxy/proxyHealth.js";
@@ -1516,6 +1516,29 @@ function escapeXml(s) {
         .replace(/"/g, """)
         .replace(/'/g, "'");
 }
+/**
+ * Build a PATH for the launchd plist that includes the current Node/pnpm
+ * bin directories so the guard process can find npm/pnpm for update checks.
+ */
+function buildLaunchdPath() {
+    const fallback = "/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin";
+    const nodeDir = dirname(process.execPath);
+    const segments = new Set();
+    // Add the directory containing the Node binary that launched this process
+    if (nodeDir && nodeDir !== ".") {
+        segments.add(nodeDir);
+    }
+    // Add pnpm home if available (e.g., ~/.local/share/pnpm)
+    const pnpmHome = process.env.PNPM_HOME;
+    if (pnpmHome) {
+        segments.add(pnpmHome);
+    }
+    // Add the standard system paths
+    for (const p of fallback.split(":")) {
+        segments.add(p);
+    }
+    return [...segments].join(":");
+}
 function buildPlist(port, host, envFile, configFile) {
     const nodeExec = escapeXml(process.execPath);
     const entryScript = escapeXml(process.argv[1] ?? join(__dirname, "..", "index.js"));
@@ -1573,7 +1596,7 @@ ${configArgs}
   <key>EnvironmentVariables</key>
   <dict>
     <key>PATH</key>
-    <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+    <string>${buildLaunchdPath()}</string>
     <key>HOME</key>
     <string>${homedir()}</string>
   </dict>

package/dist/cli/factories/commandFactory.js

@@ -124,7 +124,10 @@ export class CLICommandFactory {
             type: "string",
             choices: ["raw", "markdown", "json"],
             default: "raw",
-            description: "CSV output format (raw recommended for large files)",
+            description: "CSV output format:\n" +
+                "  • raw: Plain CSV text (fastest, minimal tokens, best for large files)\n" +
+                "  • markdown: Formatted table (readable, best for small files <100 rows)\n" +
+                "  • json: Structured JSON array (best for programmatic use, higher tokens)",
         },
         model: {
             type: "string",
@@ -1081,6 +1084,9 @@ export class CLICommandFactory {
                     .example('$0 generate "Futuristic city" --model gemini-2.5-flash-image', "Generate an image")
                     .example('$0 generate "Mountain landscape" --model gemini-2.5-flash-image --imageOutput ./my-images/mountain.png', "Generate image with custom path")
                     .example('$0 generate "Describe this video" --video path/to/video.mp4', "Analyze video content")
+                    .example('$0 generate "Analyze sales" --csv data.csv --csv-format raw', "CSV with raw format (fast, minimal tokens)")
+                    .example('$0 generate "Summarize data" --csv small.csv --csv-format markdown', "CSV with markdown table (readable)")
+                    .example('$0 generate "Process data" --csv records.csv --csv-format json', "CSV with JSON format (structured)")
                     .example('$0 generate "Product showcase video" --image ./product.jpg --outputMode video --videoOutput ./output.mp4', "Generate video from image")
                     .example('$0 generate "Smooth camera movement" --image ./input.jpg --provider vertex --model veo-3.1-generate-001 --outputMode video --videoResolution 720p --videoLength 6 --videoAspectRatio 16:9 --videoOutput ./output.mp4', "Video generation with full options")
                     .example('$0 generate "AI in Healthcare" --pptPages 10', "Generate a PowerPoint presentation")

package/dist/lib/auth/tokenStore.js

@@ -148,7 +148,8 @@ export class TokenStore {
                 ? this.obfuscate(JSON.stringify(storageData))
                 : JSON.stringify(storageData, null, 2);
             // Write to temporary file first for atomic operation
-            const tempPath = `${this.storagePath}.tmp`;
+            // Use PID-scoped temp file to avoid cross-process race conditions
+            const tempPath = `${this.storagePath}.tmp.${process.pid}`;
             await writeFile(tempPath, content, "utf-8");
             // Set restrictive permissions before moving to final location
             await chmod(tempPath, TokenStore.FILE_PERMISSIONS);
@@ -681,7 +682,8 @@ export class TokenStore {
             const content = this.encryptionEnabled
                 ? this.obfuscate(JSON.stringify(data))
                 : JSON.stringify(data, null, 2);
-            const tmpPath = `${this.storagePath}.tmp`;
+            // Use PID-scoped temp file to avoid cross-process race conditions
+            const tmpPath = `${this.storagePath}.tmp.${process.pid}`;
             await writeFile(tmpPath, content, "utf-8");
             await chmod(tmpPath, TokenStore.FILE_PERMISSIONS);
             await rename(tmpPath, this.storagePath);

package/dist/lib/types/index.d.ts

@@ -16,7 +16,7 @@ export type { BatchProcessingSummary, ExcelWorksheet, FailedFileInfo, FileInfo,
 export { PROCESSOR_PRIORITIES } from "../processors/base/types.js";
 export type { ActionAWSConfig, ActionCommentResult, ActionEvaluation, ActionExecutionResult, ActionGoogleCloudConfig, ActionInputs, ActionInputValidation, ActionMultimodalInputs, ActionOutput, ActionProviderKeys, ActionThinkingConfig, ActionTokenUsage, CliAnalytics, CliEvaluation, CliResponse, CliTokenUsage, ProviderKeyMapping, } from "./actionTypes.js";
 export type { AnalyticsData, AnalyticsErrorInfo, PerformanceMetrics, StreamAnalyticsData, TokenUsage, } from "./analytics.js";
-export * from "./content.js";
+export * from "./multimodal.js";
 export type { DomainConfig, DomainConfigOptions, DomainEvaluationCriteria, DomainTemplate, DomainType, DomainValidationRule, } from "./domainTypes.js";
 export * from "./evaluation.js";
 export * from "./evaluationProviders.js";

package/dist/lib/types/index.js

@@ -14,8 +14,8 @@ export * from "./taskClassificationTypes.js";
 // Tool system types
 export * from "./tools.js";
 export { PROCESSOR_PRIORITIES } from "../processors/base/types.js";
-// Content types for multimodal support (includes multimodal re-exports for backward compatibility)
-export * from "./content.js";
+// Content types for multimodal support (direct export from canonical source)
+export * from "./multimodal.js";
 // Evaluation types - NEW
 export * from "./evaluation.js";
 // Evaluation provider types - NEW

package/dist/lib/utils/imageProcessor.d.ts

@@ -79,6 +79,11 @@ export declare class ImageProcessor {
      */
     static processImage(image: Buffer | string, provider: string, model?: string): ProcessedImage;
 }
+/**
+ * Whitelist of valid image file extensions (lowercase, no dots).
+ * Used to validate file extensions against a known set of image formats.
+ */
+export declare const VALID_IMAGE_EXTENSIONS: string[];
 /**
  * Utility functions for image handling
  */
@@ -96,9 +101,27 @@ export declare const imageUtils: {
      */
     isBase64: (str: string) => boolean;
     /**
-     * Extract file extension from filename or URL
+     * Extract file extension from filename or URL.
+     * Strips query strings and fragments before matching so that
+     * "image.jpg?v=1" correctly returns "jpg".
+     * Returns null if no extension is found or if the extension
+     * contains non-alphanumeric characters.
      */
     getFileExtension: (filename: string) => string | null;
+    /**
+     * Validate that an extension is a recognised image format.
+     * Case-insensitive; rejects extensions with special characters.
+     */
+    isValidImageExtension: (extension: string) => boolean;
+    /**
+     * Extract and validate image file extension from a filename or URL.
+     * Returns null if the extension is missing or not a recognised image format.
+     *
+     * Security note: the last extension is used, so "malware.exe.jpg" returns
+     * "jpg". Callers should apply additional checks (e.g. content inspection)
+     * where double-extension attacks are a concern.
+     */
+    getValidatedImageExtension: (filename: string) => string | null;
     /**
      * Convert file size to human readable format
      */

package/dist/lib/utils/imageProcessor.js

@@ -364,11 +364,58 @@ export class ImageProcessor {
                 const height = buffer.readUInt32BE(20);
                 return { width, height };
             }
-            // Basic JPEG dimension extraction (simplified)
+            // JPEG dimension extraction via SOF marker parsing
             if (buffer.length >= 4 && buffer[0] === 0xff && buffer[1] === 0xd8) {
-                // This is a very basic implementation
-                // For production, consider using a proper image library
-                return null;
+                // Search for SOF0 (0xFFC0) or SOF2 (0xFFC2) markers
+                let offset = 2;
+                while (offset < buffer.length - 1) {
+                    // Find next marker (0xFF followed by non-zero, non-0xFF byte)
+                    if (buffer[offset] !== 0xff) {
+                        offset++;
+                        continue;
+                    }
+                    // Skip any padding 0xFF bytes
+                    while (offset < buffer.length && buffer[offset] === 0xff) {
+                        offset++;
+                    }
+                    if (offset >= buffer.length) {
+                        break;
+                    }
+                    const marker = buffer[offset];
+                    offset++;
+                    // Check for SOF0 (0xC0 - baseline DCT) and SOF2 (0xC2 - progressive DCT)
+                    // These are the most common JPEG encoding modes
+                    if (marker === 0xc0 || marker === 0xc2) {
+                        // SOF marker found: length (2 bytes) + precision (1 byte) + height (2 bytes) + width (2 bytes)
+                        if (offset + 7 > buffer.length) {
+                            break; // Truncated file
+                        }
+                        const height = buffer.readUInt16BE(offset + 3);
+                        const width = buffer.readUInt16BE(offset + 5);
+                        return { width, height };
+                    }
+                    // Skip this marker's segment (except for markers without length)
+                    if (marker === 0xd0 ||
+                        marker === 0xd1 ||
+                        marker === 0xd2 ||
+                        marker === 0xd3 ||
+                        marker === 0xd4 ||
+                        marker === 0xd5 ||
+                        marker === 0xd6 ||
+                        marker === 0xd7 ||
+                        marker === 0xd8 ||
+                        marker === 0xd9 ||
+                        marker === 0x01) {
+                        // RST0-RST7, SOI, EOI, TEM - no length field
+                        continue;
+                    }
+                    if (offset + 2 > buffer.length) {
+                        break; // Truncated file
+                    }
+                    const segmentLength = buffer.readUInt16BE(offset);
+                    offset += segmentLength;
+                }
+                return null; // No SOF marker found
             }
             return null;
         }
@@ -437,6 +484,30 @@ export class ImageProcessor {
         }
     }
 }
+/**
+ * Whitelist of valid image file extensions (lowercase, no dots).
+ * Used to validate file extensions against a known set of image formats.
+ */
+export const VALID_IMAGE_EXTENSIONS = [
+    "jpg",
+    "jpeg",
+    "png",
+    "gif",
+    "webp",
+    "bmp",
+    "tiff",
+    "tif",
+    "svg",
+    "avif",
+    "ico",
+    "heic",
+    "heif",
+];
+/**
+ * Set of valid image extensions for O(1) lookup.
+ * @internal
+ */
+const VALID_IMAGE_EXTENSIONS_SET = new Set(VALID_IMAGE_EXTENSIONS);
 /**
  * Utility functions for image handling
  */
@@ -466,11 +537,52 @@ export const imageUtils = {
      */
     isBase64: (str) => imageUtils.isValidBase64(str),
     /**
-     * Extract file extension from filename or URL
+     * Extract file extension from filename or URL.
+     * Strips query strings and fragments before matching so that
+     * "image.jpg?v=1" correctly returns "jpg".
+     * Returns null if no extension is found or if the extension
+     * contains non-alphanumeric characters.
      */
     getFileExtension: (filename) => {
-        const match = filename.match(/\.([^.]+)$/);
-        return match ? match[1].toLowerCase() : null;
+        const sanitized = filename.split(/[?#]/)[0];
+        const match = sanitized.match(/\.([^.]+)$/);
+        if (!match) {
+            return null;
+        }
+        const extension = match[1].toLowerCase();
+        if (!/^[a-z0-9]+$/.test(extension)) {
+            return null;
+        }
+        return extension;
+    },
+    /**
+     * Validate that an extension is a recognised image format.
+     * Case-insensitive; rejects extensions with special characters.
+     */
+    isValidImageExtension: (extension) => {
+        if (!extension || typeof extension !== "string") {
+            return false;
+        }
+        const normalizedExt = extension.toLowerCase();
+        if (!/^[a-z0-9]+$/.test(normalizedExt)) {
+            return false;
+        }
+        return VALID_IMAGE_EXTENSIONS_SET.has(normalizedExt);
+    },
+    /**
+     * Extract and validate image file extension from a filename or URL.
+     * Returns null if the extension is missing or not a recognised image format.
+     *
+     * Security note: the last extension is used, so "malware.exe.jpg" returns
+     * "jpg". Callers should apply additional checks (e.g. content inspection)
+     * where double-extension attacks are a concern.
+     */
+    getValidatedImageExtension: (filename) => {
+        const extension = imageUtils.getFileExtension(filename);
+        if (!extension) {
+            return null;
+        }
+        return imageUtils.isValidImageExtension(extension) ? extension : null;
     },
     /**
      * Convert file size to human readable format
@@ -576,7 +688,11 @@ export const imageUtils = {
                 if (!/^image\//i.test(contentType)) {
                     throw new Error(`Unsupported content-type: ${contentType || "unknown"}`);
                 }
-                const len = Number(response.headers.get("content-length") || 0);
+                const contentLengthHeader = response.headers.get("content-length");
+                const len = Number(contentLengthHeader || 0);
+                if (contentLengthHeader !== null && len === 0) {
+                    throw new Error("Empty response: content-length is 0");
+                }
                 if (len && len > maxBytes) {
                     throw new Error(`Content too large: ${len} bytes`);
                 }

package/dist/lib/utils/messageBuilder.js

@@ -1127,15 +1127,27 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
 async function convertContentToProviderFormat(content, provider, _model) {
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
-    if (!textContent) {
-        throw new Error("Multimodal content must include at least one text element");
-    }
-    if (imageContent.length === 0) {
-        return textContent.text;
+    const pdfContent = content.filter((c) => c.type === "pdf");
+    // Allow empty text when multimodal content is present (enables image-only or PDF-only queries)
+    const text = textContent?.text || "";
+    const hasMultimodal = imageContent.length > 0 || pdfContent.length > 0;
+    // Validate that we have at least some content
+    if (!hasMultimodal && !text) {
+        throw new Error("Content must include either text or multimodal content");
+    }
+    // Text-only case
+    if (imageContent.length === 0 && pdfContent.length === 0) {
+        return text;
     }
     // Extract images as Buffer | string array
     const images = imageContent.map((img) => img.data);
-    return await convertSimpleImagesToProviderFormat(textContent.text, images, provider, _model);
+    // Extract PDFs in the expected format
+    const pdfFiles = pdfContent.map((pdf) => ({
+        buffer: typeof pdf.data === "string" ? Buffer.from(pdf.data, "base64") : pdf.data,
+        filename: pdf.metadata?.filename || "document.pdf",
+        pageCount: pdf.metadata?.pages ?? null,
+    }));
+    return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
 /**
  * Check if a string is an internet URL

package/dist/types/index.js

@@ -14,8 +14,8 @@ export * from "./taskClassificationTypes.js";
 // Tool system types
 export * from "./tools.js";
 export { PROCESSOR_PRIORITIES } from "../processors/base/types.js";
-// Content types for multimodal support (includes multimodal re-exports for backward compatibility)
-export * from "./content.js";
+// Content types for multimodal support (direct export from canonical source)
+export * from "./multimodal.js";
 // Evaluation types - NEW
 export * from "./evaluation.js";
 // Evaluation provider types - NEW

package/dist/utils/imageProcessor.js

@@ -364,11 +364,58 @@ export class ImageProcessor {
                 const height = buffer.readUInt32BE(20);
                 return { width, height };
             }
-            // Basic JPEG dimension extraction (simplified)
+            // JPEG dimension extraction via SOF marker parsing
             if (buffer.length >= 4 && buffer[0] === 0xff && buffer[1] === 0xd8) {
-                // This is a very basic implementation
-                // For production, consider using a proper image library
-                return null;
+                // Search for SOF0 (0xFFC0) or SOF2 (0xFFC2) markers
+                let offset = 2;
+                while (offset < buffer.length - 1) {
+                    // Find next marker (0xFF followed by non-zero, non-0xFF byte)
+                    if (buffer[offset] !== 0xff) {
+                        offset++;
+                        continue;
+                    }
+                    // Skip any padding 0xFF bytes
+                    while (offset < buffer.length && buffer[offset] === 0xff) {
+                        offset++;
+                    }
+                    if (offset >= buffer.length) {
+                        break;
+                    }
+                    const marker = buffer[offset];
+                    offset++;
+                    // Check for SOF0 (0xC0 - baseline DCT) and SOF2 (0xC2 - progressive DCT)
+                    // These are the most common JPEG encoding modes
+                    if (marker === 0xc0 || marker === 0xc2) {
+                        // SOF marker found: length (2 bytes) + precision (1 byte) + height (2 bytes) + width (2 bytes)
+                        if (offset + 7 > buffer.length) {
+                            break; // Truncated file
+                        }
+                        const height = buffer.readUInt16BE(offset + 3);
+                        const width = buffer.readUInt16BE(offset + 5);
+                        return { width, height };
+                    }
+                    // Skip this marker's segment (except for markers without length)
+                    if (marker === 0xd0 ||
+                        marker === 0xd1 ||
+                        marker === 0xd2 ||
+                        marker === 0xd3 ||
+                        marker === 0xd4 ||
+                        marker === 0xd5 ||
+                        marker === 0xd6 ||
+                        marker === 0xd7 ||
+                        marker === 0xd8 ||
+                        marker === 0xd9 ||
+                        marker === 0x01) {
+                        // RST0-RST7, SOI, EOI, TEM - no length field
+                        continue;
+                    }
+                    if (offset + 2 > buffer.length) {
+                        break; // Truncated file
+                    }
+                    const segmentLength = buffer.readUInt16BE(offset);
+                    offset += segmentLength;
+                }
+                return null; // No SOF marker found
             }
             return null;
         }
@@ -437,6 +484,30 @@ export class ImageProcessor {
         }
     }
 }
+/**
+ * Whitelist of valid image file extensions (lowercase, no dots).
+ * Used to validate file extensions against a known set of image formats.
+ */
+export const VALID_IMAGE_EXTENSIONS = [
+    "jpg",
+    "jpeg",
+    "png",
+    "gif",
+    "webp",
+    "bmp",
+    "tiff",
+    "tif",
+    "svg",
+    "avif",
+    "ico",
+    "heic",
+    "heif",
+];
+/**
+ * Set of valid image extensions for O(1) lookup.
+ * @internal
+ */
+const VALID_IMAGE_EXTENSIONS_SET = new Set(VALID_IMAGE_EXTENSIONS);
 /**
  * Utility functions for image handling
  */
@@ -466,11 +537,52 @@ export const imageUtils = {
      */
     isBase64: (str) => imageUtils.isValidBase64(str),
     /**
-     * Extract file extension from filename or URL
+     * Extract file extension from filename or URL.
+     * Strips query strings and fragments before matching so that
+     * "image.jpg?v=1" correctly returns "jpg".
+     * Returns null if no extension is found or if the extension
+     * contains non-alphanumeric characters.
      */
     getFileExtension: (filename) => {
-        const match = filename.match(/\.([^.]+)$/);
-        return match ? match[1].toLowerCase() : null;
+        const sanitized = filename.split(/[?#]/)[0];
+        const match = sanitized.match(/\.([^.]+)$/);
+        if (!match) {
+            return null;
+        }
+        const extension = match[1].toLowerCase();
+        if (!/^[a-z0-9]+$/.test(extension)) {
+            return null;
+        }
+        return extension;
+    },
+    /**
+     * Validate that an extension is a recognised image format.
+     * Case-insensitive; rejects extensions with special characters.
+     */
+    isValidImageExtension: (extension) => {
+        if (!extension || typeof extension !== "string") {
+            return false;
+        }
+        const normalizedExt = extension.toLowerCase();
+        if (!/^[a-z0-9]+$/.test(normalizedExt)) {
+            return false;
+        }
+        return VALID_IMAGE_EXTENSIONS_SET.has(normalizedExt);
+    },
+    /**
+     * Extract and validate image file extension from a filename or URL.
+     * Returns null if the extension is missing or not a recognised image format.
+     *
+     * Security note: the last extension is used, so "malware.exe.jpg" returns
+     * "jpg". Callers should apply additional checks (e.g. content inspection)
+     * where double-extension attacks are a concern.
+     */
+    getValidatedImageExtension: (filename) => {
+        const extension = imageUtils.getFileExtension(filename);
+        if (!extension) {
+            return null;
+        }
+        return imageUtils.isValidImageExtension(extension) ? extension : null;
     },
     /**
      * Convert file size to human readable format
@@ -576,7 +688,11 @@ export const imageUtils = {
                 if (!/^image\//i.test(contentType)) {
                     throw new Error(`Unsupported content-type: ${contentType || "unknown"}`);
                 }
-                const len = Number(response.headers.get("content-length") || 0);
+                const contentLengthHeader = response.headers.get("content-length");
+                const len = Number(contentLengthHeader || 0);
+                if (contentLengthHeader !== null && len === 0) {
+                    throw new Error("Empty response: content-length is 0");
+                }
                 if (len && len > maxBytes) {
                     throw new Error(`Content too large: ${len} bytes`);
                 }

package/dist/utils/messageBuilder.js

@@ -1127,15 +1127,27 @@ export async function buildMultimodalMessagesArray(options, provider, model) {
 async function convertContentToProviderFormat(content, provider, _model) {
     const textContent = content.find((c) => c.type === "text");
     const imageContent = content.filter((c) => c.type === "image");
-    if (!textContent) {
-        throw new Error("Multimodal content must include at least one text element");
-    }
-    if (imageContent.length === 0) {
-        return textContent.text;
+    const pdfContent = content.filter((c) => c.type === "pdf");
+    // Allow empty text when multimodal content is present (enables image-only or PDF-only queries)
+    const text = textContent?.text || "";
+    const hasMultimodal = imageContent.length > 0 || pdfContent.length > 0;
+    // Validate that we have at least some content
+    if (!hasMultimodal && !text) {
+        throw new Error("Content must include either text or multimodal content");
+    }
+    // Text-only case
+    if (imageContent.length === 0 && pdfContent.length === 0) {
+        return text;
     }
     // Extract images as Buffer | string array
     const images = imageContent.map((img) => img.data);
-    return await convertSimpleImagesToProviderFormat(textContent.text, images, provider, _model);
+    // Extract PDFs in the expected format
+    const pdfFiles = pdfContent.map((pdf) => ({
+        buffer: typeof pdf.data === "string" ? Buffer.from(pdf.data, "base64") : pdf.data,
+        filename: pdf.metadata?.filename || "document.pdf",
+        pageCount: pdf.metadata?.pages ?? null,
+    }));
+    return await convertMultimodalToProviderFormat(text, images, pdfFiles, provider, _model);
 }
 /**
  * Check if a string is an internet URL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.44.1",
+  "version": "9.48.1",
   "packageManager": "pnpm@10.15.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {

package/scripts/observability/manage-local-openobserve.sh

@@ -167,6 +167,33 @@ export NEUROLINK_OPENOBSERVE_OTLP_ENDPOINT
 
 select_compose
 
+# Write or update OTEL_EXPORTER_OTLP_ENDPOINT in ~/.neurolink/.env so the
+# proxy picks it up automatically without any manual export.
+upsert_neurolink_env() {
+  local neurolink_dir="${HOME}/.neurolink"
+  local env_file="${neurolink_dir}/.env"
+  local endpoint="http://localhost:${NEUROLINK_OTLP_HTTP_PORT}"
+  local key="OTEL_EXPORTER_OTLP_ENDPOINT"
+
+  mkdir -p "${neurolink_dir}"
+  chmod 700 "${neurolink_dir}" 2>/dev/null || true
+
+  if [[ -f "${env_file}" ]] && grep -Eq "^[[:space:]]*(export[[:space:]]+)?${key}=" "${env_file}"; then
+    # Replace existing line in-place (portable sed -i)
+    sed -i.bak -E "s|^[[:space:]]*(export[[:space:]]+)?${key}=.*|${key}=${endpoint}|" "${env_file}"
+    rm -f "${env_file}.bak"
+  else
+    # Ensure the new entry starts on its own line if the file lacks a trailing newline
+    if [[ -f "${env_file}" ]] && [[ -s "${env_file}" ]] && [[ "$(tail -c 1 "${env_file}")" != "" ]]; then
+      echo "" >> "${env_file}"
+    fi
+    echo "${key}=${endpoint}" >> "${env_file}"
+  fi
+  chmod 600 "${env_file}" 2>/dev/null || true
+
+  echo "  Wrote ${key}=${endpoint} to ${env_file}"
+}
+
 command="${1:-setup}"
 
 case "${command}" in
@@ -175,6 +202,7 @@ case "${command}" in
     wait_for_http "OpenObserve" "${NEUROLINK_OPENOBSERVE_URL}/healthz"
     wait_for_http "OTEL collector" "http://localhost:${NEUROLINK_OTEL_HEALTH_PORT}/"
     node "${IMPORT_SCRIPT}" --replace-by-title
+    upsert_neurolink_env
     cat <<EOF
 Local proxy observability is ready.
 
@@ -183,12 +211,12 @@ OpenObserve login user: ${NEUROLINK_OPENOBSERVE_USER}
 OpenObserve password source: ${ENV_FILE} (NEUROLINK_OPENOBSERVE_PASSWORD)
 OTLP HTTP endpoint: http://localhost:${NEUROLINK_OTLP_HTTP_PORT}
 
-Set this before starting the proxy:
-  export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:${NEUROLINK_OTLP_HTTP_PORT}
+OTEL endpoint written to ~/.neurolink/.env — the proxy will pick it up automatically on next start.
 EOF
     ;;
   up|start)
     compose up -d
+    upsert_neurolink_env
     ;;
   down|stop)
     compose down