neo.mjs 11.14.0 → 11.16.0

package/.gemini/settings.json

@@ -18,6 +18,10 @@
         "neo.mjs-memory-core": {
             "command": "npm",
             "args"   : ["run", "ai:mcp-server-memory-core"]
+        },
+        "neo.mjs-neural-link": {
+            "command": "npm",
+            "args"   : ["run", "ai:mcp-server-neural-link"]
         }
     }
 }

package/.github/VISION.md

@@ -2,7 +2,7 @@
 
 Our vision is to build the platform for the next generation of web applications, **democratizing development** by making
 elite performance and architectural patterns accessible to all. We are building towards a future where the distinction
-between web and native applications disappears, and where the **interface for Humans and the interface for Agents are one and the same.**
+between web and native applications disappears, and where the **interface for Humans and the interface for Agents are one and the same.** This convergence empowers not just developers, but **every user** to reshape their software tools to fit their needs, simply by asking.
 
 This vision stands on four core pillars:
 
@@ -35,8 +35,7 @@ This principle radically reduces complexity and enables a cohesive ecosystem of
 We are building the first platform architected for true AI collaboration. Our goal is to use AI as the great equalizer,
 breaking down the barriers to contributing to and using a sophisticated framework. This is achieved through **Context Engineering**: building an AI-native ecosystem where the agent possesses **persistent memory** of past interactions and **deep semantic knowledge** of the codebase. This allows the AI to explain complex source code, guide new developers, and make meaningful contributions on its own. **Our architecture is inherently AI-native because it is built on a JSON Blueprint.** Instead of JSX, we use a clean, serializable structure for defining component trees and
 the VDOM itself. This makes the entire application legible and manipulable in the native language of Large Language Models
-(LLMs), allowing an AI to orchestrate complex, multi-window interfaces and turning it from a simple code-completer into a
-true architectural partner. **The end game is a development team where the AI is a proactive senior partner, mentoring
+(LLMs). This allows an AI to not just write code, but to **orchestrate the application at runtime**—injecting entire component trees or modifying state on the fly without a reload. **The end game is a development team where the AI is a proactive senior partner, mentoring
 developers and automating entire verticals of the workflow.**
 
 ### 4. The Agent Operating System (The Corporate HQ for AI)
@@ -49,6 +48,7 @@ a native Neo.mjs interface. This is our "Killer App":
 - **The "Headless" Workforce:** We are moving beyond black-box CLI wrappers. We provide a native **Headless Agent SDK** that spawns
   lightweight Node.js processes. These agents act as specialized employees—Strategic "CEOs" defining Epics, Tactical "PMs" breaking them down into tickets,
   and Execution "Drones" submitting PRs—communicating asynchronously via a **Ticket-Driven Protocol**.
+- **The "Neural Link" (Runtime Orchestration):** We are bridging the gap between the Agent (Node.js) and the App (Browser). Agents can connect to running applications to inspect state, **diagnose errors**, recover crashed components, or evolve the UI in real-time based on user voice commands ("Self-Evolving Apps").
 - **The Feedback Loop:** Because the Command Center is built with Neo.mjs, and the Agents write Neo.mjs, the platform
   is recursive. Agents can improve their own control interface, creating a self-reinforcing cycle of improvement.
 **The end game is a new paradigm where you are not just a coder, but the Architect and CEO of an intelligent, automated software organization, managing it through a powerful, spatial interface built on the very technology you are deploying.**

package/ROADMAP.md

@@ -48,15 +48,18 @@ We will build the **Neo Command Center** (`apps/agent-os`), a desktop-class UI t
 *   **Human-in-the-Loop:** A "Plan Verification" mode where Strategic Agents propose a plan in the UI, and the human Chairman approves it before execution proceeds.
 *   **Competitive Edge:** This leverages Neo.mjs's unique multi-window and shared-worker capabilities to provide an interface that single-tab competitors cannot match.
 
-### Phase 4: The Neural Link (Bidirectional Agent Integration) - **[RESEARCH]**
+### Phase 4: The Self-Evolving App Platform (Runtime Orchestration) - **[ACTIVE RESEARCH]**
 
-**Goal:** Move beyond "Pull-based" tool use to a real-time, event-driven "Push/Pull" architecture.
+**Goal:** Enable "Self-Healing" and "Self-Evolving" applications where AI Agents act as runtime operators.
 
-See [.github/AGENT_ARCHITECTURE.md](.github/AGENT_ARCHITECTURE.md) for the detailed technical specification.
+We will evolve the **Neural Link** into a bidirectional bridge that allows Agents to not just write code, but **drive** the application at runtime:
 
-*   **Bidirectional WebSocket RMA:** Enable Node.js Agents to invoke methods on Browser Apps (RPC) and vice-versa.
-*   **Telemetry Bridge:** Push Worker console logs and framework events to Agents in real-time, bypassing the need for Chrome DevTools polling.
-*   **Security Model:** A capability-based permission system for Agent-initiated browser actions.
+*   **Runtime Blueprints:** Agents can inject entire component trees (via JSON Blueprints) into running applications without a reload.
+*   **Automated Diagnostics (Dev):** Agents capture multi-thread error context to auto-generate bug reports or PRs.
+*   **State Recovery (User):** Agents detect crashes or silent failures (e.g., "dead clicks") and intervene to reset component state or guide the user.
+*   **Live Customization:** Non-technical users can verbally instruct Agents to modify the UI layout or behavior on the fly (e.g., "Move the chart to the right").
+*   **Persistence Layer:** Agent-driven changes are stored (e.g., in `localStorage` or a remote user profile), allowing runtime customizations to survive page reloads and become permanent user preferences.
+*   **Technical Spec:** See [.github/AGENT_ARCHITECTURE.md](.github/AGENT_ARCHITECTURE.md) for the detailed technical specification.
 
 ### Phase 5: Decoupling the Ecosystem (Future)
 

package/ServiceWorker.mjs

@@ -20,9 +20,9 @@ class ServiceWorker extends ServiceBase {
          */
         singleton: true,
         /**
-         * @member {String} version='11.14.0'
+         * @member {String} version='11.16.0'
          */
-        version: '11.14.0'
+        version: '11.16.0'
     }
 
     /**

package/ai/demo-agents/dev.mjs

@@ -11,15 +11,16 @@
  * node ai/agents/dev.mjs --issue <number>
  */
 
-import { Command }           from 'commander';
-import fs                    from 'fs-extra';
-import path                  from 'path';
-import { fileURLToPath }     from 'url';
-import yaml                  from 'js-yaml';
-import dotenv                from 'dotenv';
-import { exec }              from 'child_process';
-import { promisify }         from 'util';
-import { GoogleGenerativeAI, SchemaType } from '@google/generative-ai';
+import {Command}                        from 'commander';
+import fs                               from 'fs-extra';
+import path                             from 'path';
+import {fileURLToPath}                  from 'url';
+import yaml                             from 'js-yaml';
+import dotenv                           from 'dotenv';
+import {exec}                           from 'child_process';
+import {promisify}                      from 'util';
+import {GoogleGenerativeAI, SchemaType} from '@google/generative-ai';
+import {sanitizeInput}                  from '../../buildScripts/util/Sanitizer.mjs';
 
 import {
     GH_LocalFileService,
@@ -56,7 +57,7 @@ const program = new Command();
 program
     .name('dev-agent')
     .description('Autonomous Developer Agent -> Ticket to PR')
-    .requiredOption('-i, --issue <number>', 'Issue Number to process')
+    .requiredOption('-i, --issue <number>', 'Issue Number to process', sanitizeInput)
     .option('-d, --dry-run', 'Simulate execution without pushing/PR')
     .parse(process.argv);
 
@@ -76,14 +77,14 @@ async function runGit(command) {
 function parseIssueContent(rawContent) {
     const parts = rawContent.split('---');
     if (parts.length < 3) return { title: 'Unknown', body: rawContent };
-    
+
     const frontmatter = parts[1];
     const body = parts.slice(2).join('---').trim();
-    
+
     let title = 'Unknown';
     const titleMatch = frontmatter.match(/^title:\s*(.*)$/m);
     if (titleMatch) title = titleMatch[1].trim().replace(/^['"](.*)['"]$/, '$1');
-    
+
     return { title, body };
 }
 
@@ -107,7 +108,7 @@ async function parseYamlBody(body) {
 
 async function generateCode(rawIssueContent, task, contextFiles, kbContext) {
     console.log('🧠 Dev Agent is thinking...');
-    
+
     const genAI = new GoogleGenerativeAI(process.env.GEMINI_API_KEY);
     const model = genAI.getGenerativeModel({
         model: MODEL_NAME,
@@ -169,7 +170,7 @@ async function run() {
         // 2. Fetch Issue (Local)
         const issueId = String(options.issue);
         console.log(`📥 Fetching Issue #${issueId}...`);
-        
+
         const issueFile = await GH_LocalFileService.getIssueById(issueId);
         if (issueFile.error) throw new Error(`Issue #${issueId} not found locally.`);
 
@@ -240,17 +241,17 @@ async function run() {
             console.log('📦 Committing changes...');
             await runGit('git add .');
             await runGit(`git commit -m "feat: ${title}"`);
-            
+
             console.log('⬆️  Pushing branch...');
             // Construct authenticated URL for push
             // Format: https://x-access-token:<TOKEN>@github.com/owner/repo.git
             let remoteUrl = await runGit('git remote get-url origin');
-            
+
             // Strip existing auth if present (e.g. https://user:pass@...) and ensure .git suffix
             remoteUrl = remoteUrl.replace(/^https?:\/\/([^@]*@)?/, 'https://');
-            
+
             const authenticatedUrl = remoteUrl.replace('https://', `https://x-access-token:${process.env.GH_TOKEN}@`);
-            
+
             await runGit(`git push -u "${authenticatedUrl}" ${branchName}`);
 
             console.log('🔀 Creating Pull Request...');

package/ai/demo-agents/pm.mjs

@@ -11,11 +11,12 @@
  * node ai/agents/pm.mjs --epic <issue_number>
  */
 
-import { Command } from 'commander';
-import yaml from 'js-yaml';
-import dotenv from 'dotenv';
-import path from 'path';
-import { fileURLToPath } from 'url';
+import {Command}       from 'commander';
+import yaml            from 'js-yaml';
+import dotenv          from 'dotenv';
+import path            from 'path';
+import {fileURLToPath} from 'url';
+import {sanitizeInput} from '../../buildScripts/util/Sanitizer.mjs';
 import {
     GH_IssueService,
     GH_HealthService,
@@ -32,7 +33,7 @@ const program = new Command();
 program
     .name('pm-agent')
     .description('Autonomous PM Agent for breaking down Epics into Tickets')
-    .requiredOption('-e, --epic <number>', 'Epic Issue Number to process')
+    .requiredOption('-e, --epic <number>', 'Epic Issue Number to process', sanitizeInput)
     .option('-d, --dry-run', 'Simulate execution without creating issues')
     .parse(process.argv);
 

package/ai/examples/test-app-worker.mjs

@@ -0,0 +1,74 @@
+import { AppWorker_BridgeService } from '../services.mjs';
+
+/**
+ * Test script for the App Worker MCP Server.
+ * Verifies that the Node.js agent can talk to the browser app.
+ */
+async function main() {
+    console.log('🧪 Testing App Worker Neural Link...');
+
+    // 1. Start the Bridge
+    console.log('[1] Starting Bridge Service...');
+    // Accessing the singleton instance starts the server
+    const bridge = AppWorker_BridgeService;
+
+    // Wait a moment for server to bind
+    await new Promise(resolve => setTimeout(resolve, 1000));
+
+    const status = bridge.getStatus();
+    console.log(`   ✅ Bridge listening on port ${bridge.port}`);
+    console.log(`   Clients connected: ${status.connectedClients}`);
+
+    if (status.connectedClients === 0) {
+        console.log('   ⚠️  No App Worker connected yet. Please reload the browser window.');
+        console.log('   Waiting for connection...');
+
+        // Poll for connection
+        let retries = 30;
+        while (retries > 0) {
+            await new Promise(resolve => setTimeout(resolve, 1000));
+            if (bridge.getStatus().connectedClients > 0) break;
+            process.stdout.write('.');
+            retries--;
+        }
+        console.log('');
+    }
+
+    if (bridge.getStatus().connectedClients === 0) {
+        console.error('❌ Timeout: App Worker did not connect.');
+        process.exit(1);
+    }
+
+    console.log('   ✅ App Worker Connected!');
+
+    // 2. Send Remote Command
+    console.log('[2] Sending Remote Command (createNeoInstance)...');
+
+    try {
+        const result = await bridge.evaluate({
+            method: 'Neo.worker.App.createNeoInstance',
+            params: [{
+                ntype: 'button',
+                text: 'Hello from Node.js!',
+                iconCls: 'fa fa-robot',
+                style: {
+                    position: 'absolute',
+                    top: '20px',
+                    right: '20px',
+                    zIndex: 1000
+                }
+            }]
+        });
+
+        console.log('   ✅ Command Sent. Result:', result);
+        console.log('   (Check browser to see the new button!)');
+
+    } catch (error) {
+        console.error('   ❌ Command Failed:', error);
+    }
+
+    // Keep process alive briefly to ensure message flush
+    setTimeout(() => process.exit(0), 1000);
+}
+
+main();

package/ai/mcp/client/mcp-cli.mjs

@@ -16,17 +16,18 @@ import * as core         from '../../../src/core/_export.mjs'; // For Neo.core.B
 import InstanceManager   from '../../../src/manager/Instance.mjs'; // For Neo.core.Base setup
 import Client            from './Client.mjs';
 import aiConfig          from './config.mjs';
+import {sanitizeInput}   from '../../../buildScripts/util/Sanitizer.mjs';
 
 const program = new Command();
 
 program
     .name('mcp-client')
     .description('CLI for interacting with MCP servers')
-    .option('-s, --server <name>', 'Logical name of the MCP server to connect to (e.g., github-workflow)')
+    .option('-s, --server <name>', 'Logical name of the MCP server to connect to (e.g., github-workflow)', sanitizeInput)
     .option('-l, --list-tools', 'List available tools on the specified server')
-    .option('-c, --config <path>', 'Path to an external client configuration file')
-    .option('-t, --call-tool <toolName>', 'Name of the tool to call')
-    .option('-a, --args <json>', 'JSON string of arguments for --call-tool', '{}')
+    .option('-c, --config <path>', 'Path to an external client configuration file', sanitizeInput)
+    .option('-t, --call-tool <toolName>', 'Name of the tool to call', sanitizeInput)
+    .option('-a, --args <json>', 'JSON string of arguments for --call-tool', '{}', sanitizeInput)
     .option('-d, --debug', 'Enable debug logging');
 
 program.parse(process.argv);

package/ai/mcp/server/github-workflow/config.mjs

@@ -1,7 +1,13 @@
-import fs   from 'fs/promises';
+import fs from 'fs/promises';
 import path from 'path';
+import { fileURLToPath } from 'url';
 import Base from '../../../../src/core/Base.mjs';
 
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const packageRoot = path.resolve(__dirname, '../../../../');
+const projectRoot = process.cwd() === '/' ? packageRoot : process.cwd();
+
 /**
  * Default configuration object.
  * Defines the structure and default values for the server configuration.
@@ -48,17 +54,17 @@ const defaultConfig = {
          * The path to the directory for active issues.
          * @type {string}
          */
-        issuesDir: path.resolve(process.cwd(), '.github', 'ISSUE'),
+        issuesDir: path.resolve(projectRoot, '.github', 'ISSUE'),
         /**
          * The path to the directory for archived issues.
          * @type {string}
          */
-        archiveDir: path.resolve(process.cwd(), '.github', 'ISSUE_ARCHIVE'),
+        archiveDir: path.resolve(projectRoot, '.github', 'ISSUE_ARCHIVE'),
         /**
          * The path to the synchronization metadata file.
          * @type {string}
          */
-        metadataFile: path.resolve(process.cwd(), '.github', '.sync-metadata.json'),
+        metadataFile: path.resolve(projectRoot, '.github', '.sync-metadata.json'),
         /**
          * Labels that, when present on an issue, will cause it to be ignored and deleted locally.
          * @type {string[]}
@@ -73,7 +79,7 @@ const defaultConfig = {
          * The path to the directory for release notes.
          * @type {string}
          */
-        releaseNotesDir: path.resolve(process.cwd(), '.github', 'RELEASE_NOTES'),
+        releaseNotesDir: path.resolve(projectRoot, '.github', 'RELEASE_NOTES'),
         /**
          * The default version directory to use for archiving issues when no release is found.
          * @type {string}
@@ -233,15 +239,15 @@ class Config extends Base {
 
         try {
             const absolutePath = path.resolve(filePath);
-            const ext          = path.extname(absolutePath);
-            let   customConfig;
+            const ext = path.extname(absolutePath);
+            let customConfig;
 
             if (ext === '.mjs' || ext === '.js') {
                 const module = await import(absolutePath);
                 customConfig = module.default;
             } else {
                 const content = await fs.readFile(absolutePath, 'utf-8');
-                customConfig  = JSON.parse(content);
+                customConfig = JSON.parse(content);
             }
 
             // Deep merge custom config into the data object

package/ai/mcp/server/github-workflow/mcp-stdio.mjs

@@ -5,13 +5,14 @@ import InstanceManager from '../../../../src/manager/Instance.mjs';
 import aiConfig        from './config.mjs';
 import logger          from './logger.mjs';
 import Server          from './Server.mjs';
+import {sanitizeInput} from '../../../../buildScripts/util/Sanitizer.mjs';
 
 const program = new Command();
 
 program
     .name('neo-github-workflow-mcp')
     .description('Neo.mjs GitHub Workflow MCP Server')
-    .option('-c, --config <path>', 'Path to the configuration file')
+    .option('-c, --config <path>', 'Path to the configuration file', sanitizeInput)
     .option('-d, --debug', 'Enable debug logging')
     .parse(process.argv);
 

package/ai/mcp/server/knowledge-base/config.mjs

@@ -1,10 +1,8 @@
-import fs              from 'fs/promises';
-import path            from 'path';
-import {fileURLToPath} from 'url';
-import Base            from '../../../../src/core/Base.mjs';
+import fs   from 'fs/promises';
+import path from 'path';
+import Base from '../../../../src/core/Base.mjs';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname  = path.dirname(__filename);
+const cwd = process.cwd();
 
 /**
  * Default configuration object.
@@ -28,13 +26,13 @@ const defaultConfig = {
      * @returns {Object} The dummy embedding function satisfying IEmbeddingFunction
      */
     dummyEmbeddingFunction: {
-        generate: () => null,
-        name: 'dummy_embedding_function',
-        getConfig: () => ({}),
+        generate   : () => null,
+        name       : 'dummy_embedding_function',
+        getConfig  : () => ({}),
         constructor: {
             buildFromConfig: () => ({
-                generate: () => null,
-                name: 'dummy_embedding_function',
+                generate : () => null,
+                name     : 'dummy_embedding_function',
                 getConfig: () => ({})
             })
         }
@@ -53,12 +51,12 @@ const defaultConfig = {
      * The local persistence path for the agent knowledge-base server.
      * @type {string}
      */
-    path: path.resolve(__dirname, '../../../../chroma-neo-knowledge-base'),
+    path: path.resolve(cwd, 'chroma-neo-knowledge-base'),
     /**
      * The path to the generated knowledge base JSONL file.
      * @type {string}
      */
-    dataPath: path.resolve(__dirname, '../../../../dist/ai-knowledge-base.jsonl'),
+    dataPath: path.resolve(cwd, 'dist/ai-knowledge-base.jsonl'),
     /**
      * The name of the ChromaDB collection for the knowledge base.
      * @type {string}

package/ai/mcp/server/knowledge-base/mcp-stdio.mjs

@@ -5,13 +5,14 @@ import InstanceManager from '../../../../src/manager/Instance.mjs';
 import aiConfig        from './config.mjs';
 import logger          from './logger.mjs';
 import Server          from './Server.mjs';
+import {sanitizeInput} from '../../../../buildScripts/util/Sanitizer.mjs';
 
 const program = new Command();
 
 program
     .name('neo-knowledge-base-mcp')
     .description('Neo.mjs Knowledge Base MCP Server')
-    .option('-c, --config <path>', 'Path to the configuration file')
+    .option('-c, --config <path>', 'Path to the configuration file', sanitizeInput)
     .option('-d, --debug', 'Enable debug logging')
     .parse(process.argv);
 

package/ai/mcp/server/memory-core/Server.mjs

@@ -45,7 +45,6 @@ class Server extends Base {
 
     /**
      * Async initialization sequence.
-     * Replaces the main() function of the previous procedural implementation.
      * @returns {Promise<void>}
      */
     async initAsync() {

package/ai/mcp/server/memory-core/config.mjs

@@ -1,10 +1,8 @@
-import fs              from 'fs/promises';
-import path            from 'path';
-import {fileURLToPath} from 'url';
-import Base            from '../../../../src/core/Base.mjs';
+import fs   from 'fs/promises';
+import path from 'path';
+import Base from '../../../../src/core/Base.mjs';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname  = path.dirname(__filename);
+const cwd = process.cwd();
 
 /**
  * Default configuration object.
@@ -28,13 +26,13 @@ const defaultConfig = {
      * @returns {Object} The dummy embedding function satisfying IEmbeddingFunction
      */
     dummyEmbeddingFunction: {
-        generate: () => null,
-        name: 'dummy_embedding_function',
-        getConfig: () => ({}),
+        generate   : () => null,
+        name       : 'dummy_embedding_function',
+        getConfig  : () => ({}),
         constructor: {
             buildFromConfig: () => ({
-                generate: () => null,
-                name: 'dummy_embedding_function',
+                generate : () => null,
+                name     : 'dummy_embedding_function',
                 getConfig: () => ({})
             })
         }
@@ -78,12 +76,12 @@ const defaultConfig = {
          * The local persistence path for the agent memory server.
          * @type {string}
          */
-        path: path.resolve(__dirname, '../../../../chroma-neo-memory-core'),
+        path: path.resolve(cwd, 'chroma-neo-memory-core'),
         /**
          * The path to store memory backups.
          * @type {string}
          */
-        backupPath: path.resolve(__dirname, '../../../../../dist/memory-backups')
+        backupPath: path.resolve(cwd, 'dist/memory-backups')
     },
     /**
      * Configuration for the AI agent's session summary database.
@@ -108,7 +106,7 @@ const defaultConfig = {
          * The path to store session summary backups.
          * @type {string}
          */
-        backupPath: path.resolve(__dirname, '../../../../../dist/session-backups')
+        backupPath: path.resolve(cwd, 'dist/session-backups')
     }
 };
 

package/ai/mcp/server/memory-core/mcp-stdio.mjs

@@ -5,13 +5,14 @@ import InstanceManager from '../../../../src/manager/Instance.mjs';
 import aiConfig        from './config.mjs';
 import logger          from './logger.mjs';
 import Server          from './Server.mjs';
+import {sanitizeInput} from '../../../../buildScripts/util/Sanitizer.mjs';
 
 const program = new Command();
 
 program
     .name('neo-memory-core-mcp')
     .description('Neo.mjs Memory Core MCP Server')
-    .option('-c, --config <path>', 'Path to the configuration file')
+    .option('-c, --config <path>', 'Path to the configuration file', sanitizeInput)
     .option('-d, --debug', 'Enable debug logging')
     .parse(process.argv);
 

package/ai/mcp/server/memory-core/services/HealthService.mjs

@@ -2,7 +2,6 @@ import aiConfig                 from '../config.mjs';
 import Base                     from '../../../../../src/core/Base.mjs';
 import ChromaManager            from './ChromaManager.mjs';
 import DatabaseLifecycleService from './DatabaseLifecycleService.mjs';
-import SessionService           from './SessionService.mjs';
 import logger                   from '../logger.mjs';
 
 /**
@@ -208,7 +207,7 @@ class HealthService extends Base {
             status   : 'healthy',
             timestamp: new Date().toISOString(),
             session  : {
-                currentId: SessionService.currentSessionId
+                currentId: Neo.ns('Neo.ai.mcp.server.memory-core.services.SessionService', false)?.currentSessionId
             },
             database : {
                 process: DatabaseLifecycleService.getDatabaseStatus(),

package/ai/mcp/server/memory-core/services/TextEmbeddingService.mjs

@@ -1,6 +1,7 @@
 import {GoogleGenerativeAI} from '@google/generative-ai';
 import aiConfig             from '../config.mjs';
 import Base                 from '../../../../../src/core/Base.mjs';
+import logger               from '../logger.mjs';
 
 /**
  * @summary Service for creating embedding vectors for text.
@@ -42,10 +43,8 @@ class TextEmbeddingService extends Base {
         const apiKey = process.env.GEMINI_API_KEY;
 
         if (!apiKey) {
-            const error = new Error('The GEMINI_API_KEY environment variable must be set to use semantic search endpoints.');
-            error.status = 503;
-            error.code   = 'missing_gemini_api_key';
-            throw error;
+            logger.warn('⚠️  [TextEmbeddingService] GEMINI_API_KEY not set. Semantic search features will be unavailable.');
+            return;
         }
 
         const genAI = new GoogleGenerativeAI(apiKey);
@@ -58,6 +57,10 @@ class TextEmbeddingService extends Base {
      * @returns {Promise<number[]>}
      */
     async embedText(text) {
+        if (!process.env.GEMINI_API_KEY) {
+             throw  new Error('Semantic search unavailable: GEMINI_API_KEY is missing.');
+        }
+
         const result = await this.embeddingModel.embedContent(text);
         return result.embedding.values;
     }