@virsanghavi/axis-server 1.0.7 → 1.0.9

package/dist/mcp-server.mjs

@@ -1,10 +1,3 @@
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-
 // ../../src/local/mcp-server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -20,25 +13,47 @@ import dotenv2 from "dotenv";
 import fs from "fs/promises";
 import path from "path";
 import { Mutex } from "async-mutex";
+import * as fsSync from "fs";
 function getEffectiveInstructionsDir() {
   const cwd = process.cwd();
   const axisDir = path.resolve(cwd, ".axis");
   const instructionsDir = path.resolve(axisDir, "instructions");
   const legacyDir = path.resolve(cwd, "agent-instructions");
+  const sharedContextDir = path.resolve(cwd, "shared-context", "agent-instructions");
   try {
-    if (__require("fs").existsSync(instructionsDir)) return instructionsDir;
+    if (fsSync.existsSync(instructionsDir)) {
+      console.error(`[ContextManager] Using instructions dir: ${instructionsDir}`);
+      return instructionsDir;
+    }
   } catch {
   }
+  try {
+    if (fsSync.existsSync(legacyDir)) {
+      console.error(`[ContextManager] Using legacy dir: ${legacyDir}`);
+      return legacyDir;
+    }
+  } catch {
+  }
+  try {
+    if (fsSync.existsSync(sharedContextDir)) {
+      console.error(`[ContextManager] Using shared-context dir: ${sharedContextDir}`);
+      return sharedContextDir;
+    }
+  } catch {
+  }
+  console.error(`[ContextManager] Fallback to legacy dir: ${legacyDir}`);
   return legacyDir;
 }
 var ContextManager = class {
   mutex;
   apiUrl;
+  // Made public so NerveCenter can access it
   apiSecret;
-  constructor(apiUrl, apiSecret) {
+  // Made public so NerveCenter can access it
+  constructor(apiUrl2, apiSecret2) {
     this.mutex = new Mutex();
-    this.apiUrl = apiUrl;
-    this.apiSecret = apiSecret;
+    this.apiUrl = apiUrl2;
+    this.apiSecret = apiSecret2;
   }
   resolveFilePath(filename) {
     if (!filename || filename.includes("\0")) {
@@ -221,16 +236,27 @@ var NerveCenter = class {
     this.contextManager = contextManager;
     this.stateFilePath = options.stateFilePath || STATE_FILE;
     this.lockTimeout = options.lockTimeout || LOCK_TIMEOUT_DEFAULT;
-    this.projectName = options.projectName || process.env.PROJECT_NAME || "default";
-    const supabaseUrl = options.supabaseUrl || process.env.NEXT_PUBLIC_SUPABASE_URL;
-    const supabaseKey = options.supabaseServiceRoleKey || process.env.SUPABASE_SERVICE_ROLE_KEY;
-    if (!supabaseUrl || !supabaseKey) {
-      logger.warn("Supabase credentials missing. Running in local-only mode (state will be ephemeral or file-based).");
+    const hasRemoteApi = !!this.contextManager.apiUrl;
+    const supabaseUrl = options.supabaseUrl !== void 0 ? options.supabaseUrl : hasRemoteApi ? null : process.env.NEXT_PUBLIC_SUPABASE_URL;
+    const supabaseKey = options.supabaseServiceRoleKey !== void 0 ? options.supabaseServiceRoleKey : hasRemoteApi ? null : process.env.SUPABASE_SERVICE_ROLE_KEY;
+    if (supabaseUrl && supabaseKey) {
+      this.supabase = createClient(supabaseUrl, supabaseKey);
+      this.useSupabase = true;
+      logger.info("NerveCenter: Using direct Supabase persistence.");
+    } else if (this.contextManager.apiUrl) {
       this.supabase = void 0;
       this.useSupabase = false;
+      logger.info(`NerveCenter: Using Remote API persistence (${this.contextManager.apiUrl})`);
     } else {
-      this.supabase = createClient(supabaseUrl, supabaseKey);
-      this.useSupabase = true;
+      this.supabase = void 0;
+      this.useSupabase = false;
+      logger.warn("NerveCenter: Running in local-only mode. Coordination restricted to this machine.");
+    }
+    const explicitProjectName = options.projectName || process.env.PROJECT_NAME;
+    if (explicitProjectName) {
+      this.projectName = explicitProjectName;
+    } else {
+      this.projectName = "default";
     }
     this.state = {
       locks: {},
@@ -246,10 +272,27 @@ var NerveCenter = class {
   }
   async init() {
     await this.loadState();
-    await this.detectProjectName();
+    if (this.projectName === "default" && (this.useSupabase || !this.contextManager.apiUrl)) {
+      await this.detectProjectName();
+    }
     if (this.useSupabase) {
       await this.ensureProjectId();
     }
+    if (this.contextManager.apiUrl) {
+      try {
+        const { liveNotepad, projectId } = await this.callCoordination(`sessions/sync?projectName=${this.projectName}`);
+        if (projectId) {
+          this._projectId = projectId;
+          logger.info(`NerveCenter: Resolved projectId from cloud: ${this._projectId}`);
+        }
+        if (liveNotepad && (!this.state.liveNotepad || this.state.liveNotepad.startsWith("Session Start:"))) {
+          this.state.liveNotepad = liveNotepad;
+          logger.info(`NerveCenter: Recovered live notepad from cloud for project: ${this.projectName}`);
+        }
+      } catch (e) {
+        logger.warn("Failed to sync project/notepad with Remote API. Using local/fallback.", e);
+      }
+    }
   }
   async detectProjectName() {
     try {
@@ -259,12 +302,16 @@ var NerveCenter = class {
       if (config.project) {
         this.projectName = config.project;
         logger.info(`Detected project name from .axis/axis.json: ${this.projectName}`);
+        console.error(`[NerveCenter] Loaded project name '${this.projectName}' from ${axisConfigPath}`);
+      } else {
+        console.error(`[NerveCenter] .axis/axis.json found but no 'project' field.`);
       }
     } catch (e) {
+      console.error(`[NerveCenter] Could not load .axis/axis.json at ${path2.join(process.cwd(), ".axis", "axis.json")}: ${e}`);
     }
   }
   async ensureProjectId() {
-    if (!this.supabase) return;
+    if (!this.supabase || this._projectId) return;
     const { data: project, error } = await this.supabase.from("projects").select("id").eq("name", this.projectName).maybeSingle();
     if (error) {
       logger.error("Failed to load project", error);
@@ -281,6 +328,48 @@ var NerveCenter = class {
     }
     this._projectId = created.id;
   }
+  async callCoordination(endpoint, method = "GET", body) {
+    logger.info(`[callCoordination] Starting - endpoint: ${endpoint}, method: ${method}`);
+    logger.info(`[callCoordination] apiUrl: ${this.contextManager.apiUrl}, apiSecret: ${this.contextManager.apiSecret ? "SET (" + this.contextManager.apiSecret.substring(0, 10) + "...)" : "NOT SET"}`);
+    if (!this.contextManager.apiUrl) {
+      logger.error("[callCoordination] Remote API not configured - apiUrl is:", this.contextManager.apiUrl);
+      throw new Error("Remote API not configured");
+    }
+    const url = this.contextManager.apiUrl.endsWith("/v1") ? `${this.contextManager.apiUrl}/${endpoint}` : `${this.contextManager.apiUrl}/v1/${endpoint}`;
+    logger.info(`[callCoordination] Full URL: ${method} ${url}`);
+    logger.info(`[callCoordination] Request body: ${body ? JSON.stringify({ ...body, projectName: this.projectName }) : "none"}`);
+    try {
+      const response = await fetch(url, {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          "Authorization": `Bearer ${this.contextManager.apiSecret || ""}`
+        },
+        body: body ? JSON.stringify({ ...body, projectName: this.projectName }) : void 0
+      });
+      logger.info(`[callCoordination] Response status: ${response.status} ${response.statusText}`);
+      if (!response.ok) {
+        const text = await response.text();
+        logger.error(`[callCoordination] API Error Response (${response.status}): ${text}`);
+        if (response.status === 401) {
+          throw new Error(`Authentication failed (401): ${text}. Check if API key is valid and exists in api_keys table.`);
+        } else if (response.status === 500) {
+          throw new Error(`Server error (500): ${text}. Check Vercel logs for details.`);
+        } else {
+          throw new Error(`API Error (${response.status}): ${text}`);
+        }
+      }
+      const jsonResult = await response.json();
+      logger.info(`[callCoordination] Success - Response: ${JSON.stringify(jsonResult).substring(0, 200)}...`);
+      return jsonResult;
+    } catch (e) {
+      logger.error(`[callCoordination] Fetch failed: ${e.message}`, e);
+      if (e.message.includes("Authentication failed") || e.message.includes("401")) {
+        throw new Error(`API Authentication Error: ${e.message}. Verify AXIS_API_KEY in MCP config matches a key in the api_keys table.`);
+      }
+      throw e;
+    }
+  }
   jobFromRecord(record) {
     return {
       id: record.id,
@@ -290,69 +379,122 @@ var NerveCenter = class {
       status: record.status,
       assignedTo: record.assigned_to || void 0,
       dependencies: record.dependencies || void 0,
+      completionKey: record.completion_key || void 0,
       createdAt: Date.parse(record.created_at),
       updatedAt: Date.parse(record.updated_at)
     };
   }
   // --- Data Access Layers (Hybrid: Supabase > Local) ---
   async listJobs() {
-    if (!this.useSupabase || !this.supabase || !this._projectId) {
-      return Object.values(this.state.jobs);
+    if (this.useSupabase && this.supabase && this._projectId) {
+      const { data, error } = await this.supabase.from("jobs").select("id,title,description,priority,status,assigned_to,dependencies,created_at,updated_at").eq("project_id", this._projectId);
+      if (error || !data) {
+        logger.error("Failed to load jobs from Supabase", error);
+        return [];
+      }
+      return data.map((record) => this.jobFromRecord(record));
     }
-    const { data, error } = await this.supabase.from("jobs").select("id,title,description,priority,status,assigned_to,dependencies,created_at,updated_at").eq("project_id", this._projectId);
-    if (error || !data) {
-      logger.error("Failed to load jobs", error);
-      return [];
+    if (this.contextManager.apiUrl) {
+      try {
+        const url = `jobs?projectName=${this.projectName}`;
+        const res = await this.callCoordination(url);
+        return (res.jobs || []).map((record) => this.jobFromRecord(record));
+      } catch (e) {
+        logger.error("Failed to load jobs from API", e);
+        return Object.values(this.state.jobs);
+      }
     }
-    return data.map((record) => this.jobFromRecord(record));
+    return Object.values(this.state.jobs);
   }
   async getLocks() {
-    if (!this.useSupabase || !this.supabase || !this._projectId) {
-      return Object.values(this.state.locks);
+    logger.info(`[getLocks] Starting - projectName: ${this.projectName}`);
+    logger.info(`[getLocks] Config - apiUrl: ${this.contextManager.apiUrl}, useSupabase: ${this.useSupabase}, hasSupabase: ${!!this.supabase}`);
+    if (this.contextManager.apiUrl) {
+      if (!this.useSupabase || !this.supabase) {
+        try {
+          logger.info(`[getLocks] Fetching locks from API for project: ${this.projectName}`);
+          const res = await this.callCoordination(`locks?projectName=${this.projectName}`);
+          logger.info(`[getLocks] API returned ${res.locks?.length || 0} locks`);
+          return (res.locks || []).map((row) => ({
+            agentId: row.agent_id,
+            filePath: row.file_path,
+            intent: row.intent,
+            userPrompt: row.user_prompt,
+            timestamp: Date.parse(row.updated_at || row.timestamp)
+          }));
+        } catch (e) {
+          logger.error(`[getLocks] Failed to fetch locks from API: ${e.message}`, e);
+        }
+      }
     }
-    try {
-      await this.supabase.rpc("clean_stale_locks", {
-        p_project_id: this._projectId,
-        p_timeout_seconds: Math.floor(this.lockTimeout / 1e3)
-      });
-      const { data, error } = await this.supabase.from("locks").select("*").eq("project_id", this._projectId);
-      if (error) throw error;
-      return (data || []).map((row) => ({
-        agentId: row.agent_id,
-        filePath: row.file_path,
-        intent: row.intent,
-        userPrompt: row.user_prompt,
-        timestamp: Date.parse(row.updated_at)
-      }));
-    } catch (e) {
-      logger.warn("Failed to fetch locks from DB, falling back to local memory", e);
-      return Object.values(this.state.locks);
+    if (this.useSupabase && this.supabase && this._projectId) {
+      try {
+        await this.supabase.rpc("clean_stale_locks", {
+          p_project_id: this._projectId,
+          p_timeout_seconds: Math.floor(this.lockTimeout / 1e3)
+        });
+        const { data, error } = await this.supabase.from("locks").select("*").eq("project_id", this._projectId);
+        if (error) throw error;
+        return (data || []).map((row) => ({
+          agentId: row.agent_id,
+          filePath: row.file_path,
+          intent: row.intent,
+          userPrompt: row.user_prompt,
+          timestamp: Date.parse(row.updated_at)
+        }));
+      } catch (e) {
+        logger.warn("Failed to fetch locks from DB", e);
+      }
+    }
+    if (this.contextManager.apiUrl) {
+      try {
+        const res = await this.callCoordination(`locks?projectName=${this.projectName}`);
+        return (res.locks || []).map((row) => ({
+          agentId: row.agent_id,
+          filePath: row.file_path,
+          intent: row.intent,
+          userPrompt: row.user_prompt,
+          timestamp: Date.parse(row.updated_at || row.timestamp)
+        }));
+      } catch (e) {
+        logger.error("Failed to fetch locks from API in fallback", e);
+      }
     }
+    return Object.values(this.state.locks);
   }
   async getNotepad() {
-    if (!this.useSupabase || !this.supabase || !this._projectId) {
-      return this.state.liveNotepad;
+    if (this.useSupabase && this.supabase && this._projectId) {
+      const { data, error } = await this.supabase.from("projects").select("live_notepad").eq("id", this._projectId).single();
+      if (!error && data) return data.live_notepad || "";
     }
-    const { data, error } = await this.supabase.from("projects").select("live_notepad").eq("id", this._projectId).single();
-    if (error || !data) {
-      logger.error("Failed to fetch notepad", error);
-      return this.state.liveNotepad;
-    }
-    return data.live_notepad || "";
+    return this.state.liveNotepad;
   }
   async appendToNotepad(text) {
-    if (!this.useSupabase || !this.supabase || !this._projectId) {
-      this.state.liveNotepad += text;
-      await this.saveState();
-      return;
+    this.state.liveNotepad += text;
+    await this.saveState();
+    if (this.useSupabase && this.supabase && this._projectId) {
+      try {
+        await this.supabase.rpc("append_to_project_notepad", {
+          p_project_id: this._projectId,
+          p_text: text
+        });
+      } catch (e) {
+      }
     }
-    const { error } = await this.supabase.rpc("append_to_project_notepad", {
-      p_project_id: this._projectId,
-      p_text: text
-    });
-    if (error) {
-      const current = await this.getNotepad();
-      await this.supabase.from("projects").update({ live_notepad: current + text }).eq("id", this._projectId);
+    if (this.contextManager.apiUrl) {
+      try {
+        const res = await this.callCoordination("sessions/sync", "POST", {
+          title: `Current Session: ${this.projectName}`,
+          context: this.state.liveNotepad,
+          metadata: { source: "mcp-server-live" }
+        });
+        if (res.projectId && !this._projectId) {
+          this._projectId = res.projectId;
+          logger.info(`NerveCenter: Captured projectId from sync API: ${this._projectId}`);
+        }
+      } catch (e) {
+        logger.warn("Failed to sync notepad to remote API", e);
+      }
     }
   }
   async saveState() {
@@ -375,25 +517,35 @@ var NerveCenter = class {
   async postJob(title, description, priority = "medium", dependencies = []) {
     return await this.mutex.runExclusive(async () => {
       let id = `job-${Date.now()}-${Math.floor(Math.random() * 1e3)}`;
+      const completionKey = Math.random().toString(36).substring(2, 10).toUpperCase();
       if (this.useSupabase && this.supabase && this._projectId) {
-        const now = (/* @__PURE__ */ new Date()).toISOString();
         const { data, error } = await this.supabase.from("jobs").insert({
           project_id: this._projectId,
           title,
           description,
           priority,
           status: "todo",
-          assigned_to: null,
           dependencies,
-          created_at: now,
-          updated_at: now
+          completion_key: completionKey
         }).select("id").single();
-        if (error) {
-          logger.error("Failed to post job", error);
-        } else if (data?.id) {
-          id = data.id;
+        if (data?.id) id = data.id;
+        if (error) logger.error("Failed to post job to Supabase", error);
+      } else if (this.contextManager.apiUrl) {
+        try {
+          const data = await this.callCoordination("jobs", "POST", {
+            action: "post",
+            title,
+            description,
+            priority,
+            dependencies,
+            completion_key: completionKey
+          });
+          if (data?.id) id = data.id;
+        } catch (e) {
+          logger.error("Failed to post job to API", e);
         }
-      } else {
+      }
+      if (!this.useSupabase && !this.contextManager.apiUrl) {
         this.state.jobs[id] = {
           id,
           title,
@@ -402,21 +554,54 @@ var NerveCenter = class {
           dependencies,
           status: "todo",
           createdAt: Date.now(),
-          updatedAt: Date.now()
+          updatedAt: Date.now(),
+          completionKey
         };
       }
       const depText = dependencies.length ? ` (Depends on: ${dependencies.join(", ")})` : "";
       const logEntry = `
 - [JOB POSTED] [${priority.toUpperCase()}] ${title} (ID: ${id})${depText}`;
       await this.appendToNotepad(logEntry);
-      logger.info(`Job posted: ${title}`, { jobId: id, priority });
-      return { jobId: id, status: "POSTED" };
+      return { jobId: id, status: "POSTED", completionKey };
     });
   }
   async claimNextJob(agentId) {
     return await this.mutex.runExclusive(async () => {
+      if (this.useSupabase && this.supabase && this._projectId) {
+        const { data, error } = await this.supabase.rpc("claim_next_job", {
+          p_project_id: this._projectId,
+          p_agent_id: agentId
+        });
+        if (error) {
+          logger.error("Failed to claim job via RPC", error);
+        } else if (data && data.status === "CLAIMED") {
+          const job2 = this.jobFromRecord(data.job);
+          await this.appendToNotepad(`
+- [JOB CLAIMED] Agent '${agentId}' picked up: ${job2.title}`);
+          return { status: "CLAIMED", job: job2 };
+        }
+        return { status: "NO_JOBS_AVAILABLE", message: "Relax. No open tickets (or dependencies not met)." };
+      }
+      if (this.contextManager.apiUrl) {
+        try {
+          const data = await this.callCoordination("jobs", "POST", {
+            action: "claim",
+            agentId
+          });
+          if (data && data.status === "CLAIMED") {
+            const job2 = this.jobFromRecord(data.job);
+            await this.appendToNotepad(`
+- [JOB CLAIMED] Agent '${agentId}' picked up: ${job2.title}`);
+            return { status: "CLAIMED", job: job2 };
+          }
+          return { status: "NO_JOBS_AVAILABLE", message: "Relax. No open tickets (or dependencies not met)." };
+        } catch (e) {
+          logger.error("Failed to claim job via API", e);
+          return { status: "NO_JOBS_AVAILABLE", message: `Claim failed: ${e.message}` };
+        }
+      }
       const priorities = ["critical", "high", "medium", "low"];
-      const allJobs = await this.listJobs();
+      const allJobs = Object.values(this.state.jobs);
       const jobsById = new Map(allJobs.map((job2) => [job2.id, job2]));
       const availableJobs = allJobs.filter((job2) => job2.status === "todo").filter((job2) => {
         if (!job2.dependencies || job2.dependencies.length === 0) return true;
@@ -430,118 +615,110 @@ var NerveCenter = class {
       if (availableJobs.length === 0) {
         return { status: "NO_JOBS_AVAILABLE", message: "Relax. No open tickets (or dependencies not met)." };
       }
-      if (this.useSupabase && this.supabase) {
-        for (const candidate of availableJobs) {
-          const now = (/* @__PURE__ */ new Date()).toISOString();
-          const { data, error } = await this.supabase.from("jobs").update({
-            status: "in_progress",
-            assigned_to: agentId,
-            updated_at: now
-          }).eq("id", candidate.id).eq("status", "todo").select("id,title,description,priority,status,assigned_to,dependencies,created_at,updated_at");
-          if (error) {
-            logger.error("Failed to claim job", error);
-            continue;
-          }
-          if (data && data.length > 0) {
-            const job2 = this.jobFromRecord(data[0]);
-            await this.appendToNotepad(`
-- [JOB CLAIMED] Agent '${agentId}' picked up: ${job2.title}`);
-            logger.info(`Job claimed`, { jobId: job2.id, agentId });
-            return { status: "CLAIMED", job: job2 };
-          }
-        }
-        return { status: "NO_JOBS_AVAILABLE", message: "All available jobs were just claimed." };
-      }
       const job = availableJobs[0];
       job.status = "in_progress";
       job.assignedTo = agentId;
       job.updatedAt = Date.now();
-      this.state.liveNotepad += `
-- [JOB CLAIMED] Agent '${agentId}' picked up: ${job.title}`;
-      logger.info(`Job claimed`, { jobId: job.id, agentId });
-      await this.saveState();
+      await this.appendToNotepad(`
+- [JOB CLAIMED] Agent '${agentId}' picked up: ${job.title}`);
       return { status: "CLAIMED", job };
     });
   }
   async cancelJob(jobId, reason) {
     return await this.mutex.runExclusive(async () => {
-      if (this.useSupabase && this.supabase) {
-        const { data, error } = await this.supabase.from("jobs").update({ status: "cancelled", cancel_reason: reason, updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", jobId).select("id,title");
-        if (error || !data || data.length === 0) {
-          return { error: "Job not found" };
+      if (this.useSupabase && this.supabase && this._projectId) {
+        await this.supabase.from("jobs").update({ status: "cancelled", cancel_reason: reason, updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", jobId);
+      } else if (this.contextManager.apiUrl) {
+        try {
+          await this.callCoordination("jobs", "POST", { action: "update", jobId, status: "cancelled", cancel_reason: reason });
+        } catch (e) {
+          logger.error("Failed to cancel job via API", e);
         }
-        this.state.liveNotepad += `
-- [JOB CANCELLED] ${data[0].title} (ID: ${jobId}). Reason: ${reason}`;
-        await this.saveState();
-        return { status: "CANCELLED" };
       }
-      const job = this.state.jobs[jobId];
-      if (!job) return { error: "Job not found" };
-      job.status = "cancelled";
-      job.updatedAt = Date.now();
-      this.state.liveNotepad += `
-- [JOB CANCELLED] ${job.title} (ID: ${jobId}). Reason: ${reason}`;
-      await this.saveState();
-      return { status: "CANCELLED" };
-    });
-  }
-  async forceUnlock(filePath, adminReason) {
-    return await this.mutex.runExclusive(async () => {
-      if (this.useSupabase && this.supabase && this._projectId) {
-        const { error } = await this.supabase.from("locks").delete().eq("project_id", this._projectId).eq("file_path", filePath);
-        if (error) return { error: "DB Error" };
-        this.state.liveNotepad += `
-- [ADMIN] Force unlocked '${filePath}'. Reason: ${adminReason}`;
+      if (this.state.jobs[jobId]) {
+        this.state.jobs[jobId].status = "cancelled";
+        this.state.jobs[jobId].updatedAt = Date.now();
         await this.saveState();
-        return { status: "UNLOCKED" };
       }
-      const lock = this.state.locks[filePath];
-      if (!lock) return { message: "File was not locked." };
-      delete this.state.locks[filePath];
-      this.state.liveNotepad += `
-- [ADMIN] Force unlocked '${filePath}'. Reason: ${adminReason}`;
-      await this.saveState();
-      return { status: "UNLOCKED", previousOwner: lock.agentId };
+      await this.appendToNotepad(`
+- [JOB CANCELLED] ID: ${jobId}. Reason: ${reason}`);
+      return "Job cancelled.";
     });
   }
-  async completeJob(agentId, jobId, outcome) {
+  async completeJob(agentId, jobId, outcome, completionKey) {
     return await this.mutex.runExclusive(async () => {
       if (this.useSupabase && this.supabase) {
-        const { data, error } = await this.supabase.from("jobs").select("id,title,assigned_to").eq("id", jobId).single();
+        const { data, error } = await this.supabase.from("jobs").select("id,title,assigned_to,completion_key").eq("id", jobId).single();
         if (error || !data) return { error: "Job not found" };
-        if (data.assigned_to !== agentId) return { error: "You don't own this job." };
-        const { error: updateError } = await this.supabase.from("jobs").update({ status: "done", updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", jobId).eq("assigned_to", agentId);
+        const isOwner2 = data.assigned_to === agentId;
+        const isKeyValid2 = completionKey && data.completion_key === completionKey;
+        if (!isOwner2 && !isKeyValid2) {
+          return { error: "You don't own this job and provided no valid key." };
+        }
+        const { error: updateError } = await this.supabase.from("jobs").update({ status: "done", updated_at: (/* @__PURE__ */ new Date()).toISOString() }).eq("id", jobId);
         if (updateError) return { error: "Failed to complete job" };
         await this.appendToNotepad(`
-- [JOB DONE] ${data.title} by ${agentId}. Outcome: ${outcome}`);
-        logger.info(`Job completed`, { jobId, agentId });
+- [JOB DONE] Agent '${agentId}' finished: ${data.title}
+  Outcome: ${outcome}`);
         return { status: "COMPLETED" };
+      } else if (this.contextManager.apiUrl) {
+        try {
+          await this.callCoordination("jobs", "POST", {
+            action: "update",
+            jobId,
+            status: "done",
+            assigned_to: agentId,
+            completion_key: completionKey
+          });
+          await this.appendToNotepad(`
+- [JOB DONE] Agent '${agentId}' finished: ${jobId}
+  Outcome: ${outcome}`);
+          return { status: "COMPLETED" };
+        } catch (e) {
+          logger.error("Failed to complete job via API", e);
+        }
       }
       const job = this.state.jobs[jobId];
       if (!job) return { error: "Job not found" };
-      if (job.assignedTo !== agentId) return { error: "You don't own this job." };
+      const isOwner = job.assignedTo === agentId;
+      const isKeyValid = completionKey && job.completionKey === completionKey;
+      if (!isOwner && !isKeyValid) {
+        return { error: "You don't own this job and provided no valid key." };
+      }
       job.status = "done";
       job.updatedAt = Date.now();
-      this.state.liveNotepad += `
-- [JOB DONE] ${job.title} by ${agentId}. Outcome: ${outcome}`;
-      await this.saveState();
+      await this.appendToNotepad(`
+- [JOB DONE] Agent '${agentId}' finished: ${job.title}
+  Outcome: ${outcome}`);
       return { status: "COMPLETED" };
     });
   }
-  // --- Core State Management ---
-  async getLiveContext() {
-    const locks = await this.getLocks();
-    const lockSummary = locks.map(
-      (l) => `- [LOCKED] ${l.filePath} by ${l.agentId}
-  Intent: ${l.intent}
-  Prompt: "${l.userPrompt?.substring(0, 100)}..."`
-    ).join("\n");
+  async forceUnlock(filePath, reason) {
+    return await this.mutex.runExclusive(async () => {
+      if (this.useSupabase && this.supabase && this._projectId) {
+        await this.supabase.from("locks").delete().eq("project_id", this._projectId).eq("file_path", filePath);
+      } else if (this.contextManager.apiUrl) {
+        try {
+          await this.callCoordination("locks", "POST", { action: "unlock", filePath, reason });
+        } catch (e) {
+          logger.error("Failed to force unlock via API", e);
+        }
+      }
+      if (this.state.locks[filePath]) {
+        delete this.state.locks[filePath];
+        await this.saveState();
+      }
+      await this.appendToNotepad(`
+- [FORCE UNLOCK] ${filePath} unlocked by admin. Reason: ${reason}`);
+      return `File ${filePath} has been forcibly unlocked.`;
+    });
+  }
+  async getCoreContext() {
     const jobs = await this.listJobs();
-    const jobSummary = jobs.map(
-      (j) => `- [${j.status.toUpperCase()}] ${j.title} ${j.assignedTo ? "(" + j.assignedTo + ")" : "(Open)"}
-  ID: ${j.id}`
-    ).join("\n");
+    const locks = await this.getLocks();
     const notepad = await this.getNotepad();
+    const jobSummary = jobs.filter((j) => j.status !== "done" && j.status !== "cancelled").map((j) => `- [${j.status.toUpperCase()}] ${j.title} (ID: ${j.id}, Priority: ${j.priority}${j.assignedTo ? `, Assigned: ${j.assignedTo}` : ""})`).join("\n");
+    const lockSummary = locks.map((l) => `- ${l.filePath} (Locked by: ${l.agentId}, Intent: ${l.intent})`).join("\n");
     return `# Active Session Context
 
 ## Job Board (Active Orchestration)
@@ -556,40 +733,89 @@ ${notepad}`;
   // --- Decision & Orchestration ---
   async proposeFileAccess(agentId, filePath, intent, userPrompt) {
     return await this.mutex.runExclusive(async () => {
-      if (!this.supabase || !this._projectId) throw new Error("Database not connected");
-      const { data: existing } = await this.supabase.from("locks").select("*").eq("project_id", this._projectId).eq("file_path", filePath).maybeSingle();
+      logger.info(`[proposeFileAccess] Starting - agentId: ${agentId}, filePath: ${filePath}`);
+      if (this.contextManager.apiUrl) {
+        try {
+          const result = await this.callCoordination("locks", "POST", {
+            action: "lock",
+            filePath,
+            agentId,
+            intent,
+            userPrompt
+          });
+          if (result.status === "DENIED") {
+            logger.info(`[proposeFileAccess] DENIED by server: ${result.message}`);
+            return {
+              status: "REQUIRES_ORCHESTRATION",
+              message: result.message || `File '${filePath}' is locked by another agent`,
+              currentLock: result.current_lock
+            };
+          }
+          logger.info(`[proposeFileAccess] GRANTED by server`);
+          await this.appendToNotepad(`
+- [LOCK] ${agentId} locked ${filePath}
+  Intent: ${intent}`);
+          return { status: "GRANTED", message: `Access granted for ${filePath}` };
+        } catch (e) {
+          if (e.message && e.message.includes("409")) {
+            logger.info(`[proposeFileAccess] Lock conflict (409)`);
+            return {
+              status: "REQUIRES_ORCHESTRATION",
+              message: `File '${filePath}' is locked by another agent`
+            };
+          }
+          logger.error(`[proposeFileAccess] API lock failed: ${e.message}`, e);
+          return { error: `Failed to acquire lock via API: ${e.message}` };
+        }
+      }
+      if (this.useSupabase && this.supabase && this._projectId) {
+        try {
+          const { data, error } = await this.supabase.rpc("try_acquire_lock", {
+            p_project_id: this._projectId,
+            p_file_path: filePath,
+            p_agent_id: agentId,
+            p_intent: intent,
+            p_user_prompt: userPrompt,
+            p_timeout_seconds: Math.floor(this.lockTimeout / 1e3)
+          });
+          if (error) throw error;
+          const row = Array.isArray(data) ? data[0] : data;
+          if (row && row.status === "DENIED") {
+            return {
+              status: "REQUIRES_ORCHESTRATION",
+              message: `Conflict: File '${filePath}' is locked by '${row.owner_id}'`,
+              currentLock: {
+                agentId: row.owner_id,
+                filePath,
+                intent: row.intent,
+                timestamp: row.updated_at ? Date.parse(row.updated_at) : Date.now()
+              }
+            };
+          }
+          await this.appendToNotepad(`
+- [LOCK] ${agentId} locked ${filePath}
+  Intent: ${intent}`);
+          return { status: "GRANTED", message: `Access granted for ${filePath}` };
+        } catch (e) {
+          logger.warn("[NerveCenter] Lock RPC failed. Falling back to local.", e);
+        }
+      }
+      const existing = Object.values(this.state.locks).find((l) => l.filePath === filePath);
       if (existing) {
-        const updatedAt = new Date(existing.updated_at).getTime();
-        const isStale = Date.now() - updatedAt > this.lockTimeout;
-        if (!isStale && existing.agent_id !== agentId) {
+        const isStale = Date.now() - existing.timestamp > this.lockTimeout;
+        if (!isStale && existing.agentId !== agentId) {
           return {
             status: "REQUIRES_ORCHESTRATION",
-            message: `Conflict: File '${filePath}' is currently locked by agent '${existing.agent_id}'`,
-            currentLock: {
-              agentId: existing.agent_id,
-              intent: existing.intent,
-              timestamp: updatedAt
-            }
+            message: `Conflict: File '${filePath}' is currently locked by '${existing.agentId}'`,
+            currentLock: existing
           };
         }
       }
-      const { error } = await this.supabase.from("locks").upsert({
-        project_id: this._projectId,
-        file_path: filePath,
-        agent_id: agentId,
-        intent,
-        user_prompt: userPrompt,
-        updated_at: (/* @__PURE__ */ new Date()).toISOString()
-      }, { onConflict: "project_id,file_path" });
-      if (error) {
-        logger.error("Lock upsert failed", error);
-        return { status: "ERROR", message: "Database lock failed." };
-      }
+      this.state.locks[filePath] = { agentId, filePath, intent, userPrompt, timestamp: Date.now() };
+      await this.saveState();
       await this.appendToNotepad(`
-
-### [${agentId}] Locked '${filePath}'
-**Intent:** ${intent}
-**Prompt:** "${userPrompt}"`);
+- [LOCK] ${agentId} locked ${filePath}
+  Intent: ${intent}`);
       return { status: "GRANTED", message: `Access granted for ${filePath}` };
     });
   }
@@ -605,7 +831,12 @@ ${notepad}`;
       const content = await this.getNotepad();
       const filename = `session-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-")}.md`;
       const historyPath = path2.join(process.cwd(), "history", filename);
-      await fs2.writeFile(historyPath, content);
+      try {
+        await fs2.mkdir(path2.dirname(historyPath), { recursive: true });
+        await fs2.writeFile(historyPath, content);
+      } catch (e) {
+        logger.warn("Failed to write local session log", e);
+      }
       if (this.useSupabase && this.supabase && this._projectId) {
         await this.supabase.from("sessions").insert({
           project_id: this._projectId,
@@ -616,13 +847,18 @@ ${notepad}`;
         await this.supabase.from("projects").update({ live_notepad: "Session Start: " + (/* @__PURE__ */ new Date()).toISOString() + "\n" }).eq("id", this._projectId);
         await this.supabase.from("jobs").delete().eq("project_id", this._projectId).in("status", ["done", "cancelled"]);
         await this.supabase.from("locks").delete().eq("project_id", this._projectId);
-      } else {
-        this.state.liveNotepad = "Session Start: " + (/* @__PURE__ */ new Date()).toISOString() + "\n";
-        this.state.locks = {};
-        this.state.jobs = Object.fromEntries(
-          Object.entries(this.state.jobs).filter(([_, j]) => j.status !== "done" && j.status !== "cancelled")
-        );
+      } else if (this.contextManager.apiUrl) {
+        try {
+          await this.callCoordination("sessions/finalize", "POST", { content });
+        } catch (e) {
+          logger.error("Failed to finalize session via API", e);
+        }
       }
+      this.state.liveNotepad = "Session Start: " + (/* @__PURE__ */ new Date()).toISOString() + "\n";
+      this.state.locks = {};
+      this.state.jobs = Object.fromEntries(
+        Object.entries(this.state.jobs).filter(([_, j]) => j.status !== "done" && j.status !== "cancelled")
+      );
       await this.saveState();
       return {
         status: "SESSION_FINALIZED",
@@ -648,32 +884,55 @@ ${conventions}`;
   }
   // --- Billing & Usage ---
   async getSubscriptionStatus(email) {
-    if (!this.useSupabase || !this.supabase) {
-      return { error: "Supabase not configured." };
+    logger.info(`[getSubscriptionStatus] Starting - email: ${email}`);
+    logger.info(`[getSubscriptionStatus] Config - apiUrl: ${this.contextManager.apiUrl}, apiSecret: ${this.contextManager.apiSecret ? "SET" : "NOT SET"}, useSupabase: ${this.useSupabase}`);
+    if (this.contextManager.apiUrl) {
+      try {
+        logger.info(`[getSubscriptionStatus] Attempting API call to: usage?email=${encodeURIComponent(email)}`);
+        const result = await this.callCoordination(`usage?email=${encodeURIComponent(email)}`);
+        logger.info(`[getSubscriptionStatus] API call successful: ${JSON.stringify(result).substring(0, 200)}`);
+        return result;
+      } catch (e) {
+        logger.error(`[getSubscriptionStatus] API call failed: ${e.message}`, e);
+        return { error: `API call failed: ${e.message}` };
+      }
+    } else {
+      logger.warn("[getSubscriptionStatus] No API URL configured");
     }
-    const { data: profile, error } = await this.supabase.from("profiles").select("subscription_status, stripe_customer_id, current_period_end").eq("email", email).single();
-    if (error || !profile) {
-      return { status: "unknown", message: "Profile not found." };
+    if (this.useSupabase && this.supabase) {
+      const { data: profile, error } = await this.supabase.from("profiles").select("subscription_status, stripe_customer_id, current_period_end").eq("email", email).single();
+      if (error || !profile) {
+        return { status: "unknown", message: "Profile not found." };
+      }
+      const isActive = profile.subscription_status === "pro" || profile.current_period_end && new Date(profile.current_period_end) > /* @__PURE__ */ new Date();
+      return {
+        email,
+        plan: isActive ? "Pro" : "Free",
+        status: profile.subscription_status || "free",
+        validUntil: profile.current_period_end
+      };
     }
-    const isActive = profile.subscription_status === "pro" || profile.current_period_end && new Date(profile.current_period_end) > /* @__PURE__ */ new Date();
-    return {
-      email,
-      plan: isActive ? "Pro" : "Free",
-      status: profile.subscription_status || "free",
-      validUntil: profile.current_period_end
-    };
+    return { error: "Coordination not configured. API URL not set and Supabase not available." };
   }
   async getUsageStats(email) {
-    if (!this.useSupabase || !this.supabase) {
-      return { error: "Supabase not configured." };
+    logger.info(`[getUsageStats] Starting - email: ${email}`);
+    logger.info(`[getUsageStats] Config - apiUrl: ${this.contextManager.apiUrl}, apiSecret: ${this.contextManager.apiSecret ? "SET" : "NOT SET"}, useSupabase: ${this.useSupabase}`);
+    if (this.contextManager.apiUrl) {
+      try {
+        logger.info(`[getUsageStats] Attempting API call to: usage?email=${encodeURIComponent(email)}`);
+        const result = await this.callCoordination(`usage?email=${encodeURIComponent(email)}`);
+        logger.info(`[getUsageStats] API call successful: ${JSON.stringify(result).substring(0, 200)}`);
+        return { email, usageCount: result.usageCount || 0 };
+      } catch (e) {
+        logger.error(`[getUsageStats] API call failed: ${e.message}`, e);
+        return { error: `API call failed: ${e.message}` };
+      }
     }
-    const { data: profile } = await this.supabase.from("profiles").select("usage_count").eq("email", email).single();
-    return {
-      email,
-      usageCount: profile?.usage_count || 0,
-      limit: 1e3
-      // Hardcoded placeholder limit
-    };
+    if (this.useSupabase && this.supabase) {
+      const { data: profile } = await this.supabase.from("profiles").select("usage_count").eq("email", email).single();
+      return { email, usageCount: profile?.usage_count || 0 };
+    }
+    return { error: "Coordination not configured. API URL not set and Supabase not available." };
   }
 };
 
@@ -734,7 +993,7 @@ var RagEngine = class {
       const embedding = resp.data[0].embedding;
       const { data, error } = await this.supabase.rpc("match_embeddings", {
         query_embedding: embedding,
-        match_threshold: 0.5,
+        match_threshold: 0.1,
         match_count: limit,
         p_project_id: this.projectId
       });
@@ -751,44 +1010,101 @@ var RagEngine = class {
 };
 
 // ../../src/local/mcp-server.ts
-dotenv2.config({ path: ".env.local" });
-if (!process.env.NEXT_PUBLIC_SUPABASE_URL || !process.env.SUPABASE_SERVICE_ROLE_KEY) {
-  logger.warn("Supabase credentials missing. RAG & Persistence disabled. Running in local/ephemeral mode.");
+import path3 from "path";
+import fs3 from "fs";
+if (process.env.SHARED_CONTEXT_API_URL || process.env.AXIS_API_KEY) {
+  logger.info("Using configuration from MCP client (mcp.json)");
+} else {
+  const cwd = process.cwd();
+  const possiblePaths = [
+    path3.join(cwd, ".env.local"),
+    path3.join(cwd, "..", ".env.local"),
+    path3.join(cwd, "..", "..", ".env.local"),
+    path3.join(cwd, "shared-context", ".env.local"),
+    path3.join(cwd, "..", "shared-context", ".env.local")
+  ];
+  let envLoaded = false;
+  for (const envPath of possiblePaths) {
+    try {
+      if (fs3.existsSync(envPath)) {
+        logger.info(`[Fallback] Loading .env.local from: ${envPath}`);
+        dotenv2.config({ path: envPath });
+        envLoaded = true;
+        break;
+      }
+    } catch (e) {
+    }
+  }
+  if (!envLoaded) {
+    logger.warn("No configuration found from MCP client (mcp.json) or .env.local");
+    logger.warn("MCP server will use default API URL: https://aicontext.vercel.app/api/v1");
+  }
 }
-var manager = new ContextManager(
-  process.env.SHARED_CONTEXT_API_URL || "https://aicontext.vercel.app/api/v1",
-  process.env.AXIS_API_KEY || process.env.SHARED_CONTEXT_API_SECRET
-);
+logger.info("=== Axis MCP Server Starting ===");
+logger.info("Environment check:", {
+  hasSHARED_CONTEXT_API_URL: !!process.env.SHARED_CONTEXT_API_URL,
+  hasAXIS_API_KEY: !!process.env.AXIS_API_KEY,
+  hasSHARED_CONTEXT_API_SECRET: !!process.env.SHARED_CONTEXT_API_SECRET,
+  hasNEXT_PUBLIC_SUPABASE_URL: !!process.env.NEXT_PUBLIC_SUPABASE_URL,
+  hasSUPABASE_SERVICE_ROLE_KEY: !!process.env.SUPABASE_SERVICE_ROLE_KEY,
+  PROJECT_NAME: process.env.PROJECT_NAME || "default"
+});
+var apiUrl = process.env.SHARED_CONTEXT_API_URL || process.env.AXIS_API_URL || "https://aicontext.vercel.app/api/v1";
+var apiSecret = process.env.AXIS_API_KEY || process.env.SHARED_CONTEXT_API_SECRET || process.env.AXIS_API_SECRET;
+var useRemoteApiOnly = !!process.env.SHARED_CONTEXT_API_URL || !!process.env.AXIS_API_KEY;
+if (useRemoteApiOnly) {
+  logger.info("Running in REMOTE API mode - Supabase credentials not needed locally.");
+  logger.info(`Remote API: ${apiUrl}`);
+  logger.info(`API Key: ${apiSecret ? apiSecret.substring(0, 15) + "..." : "NOT SET"}`);
+} else if (!process.env.NEXT_PUBLIC_SUPABASE_URL || !process.env.SUPABASE_SERVICE_ROLE_KEY) {
+  logger.warn("No remote API configured and Supabase credentials missing. Running in local/ephemeral mode.");
+} else {
+  logger.info("Running in DIRECT SUPABASE mode (development).");
+}
+logger.info("ContextManager config:", {
+  apiUrl,
+  hasApiSecret: !!apiSecret,
+  source: useRemoteApiOnly ? "MCP config (mcp.json)" : "default/fallback"
+});
+var manager = new ContextManager(apiUrl, apiSecret);
+logger.info("NerveCenter config:", {
+  useRemoteApiOnly,
+  supabaseUrl: useRemoteApiOnly ? "DISABLED (using remote API)" : process.env.NEXT_PUBLIC_SUPABASE_URL ? "SET" : "NOT SET",
+  supabaseKey: useRemoteApiOnly ? "DISABLED (using remote API)" : process.env.SUPABASE_SERVICE_ROLE_KEY ? "SET" : "NOT SET",
+  projectName: process.env.PROJECT_NAME || "default"
+});
 var nerveCenter = new NerveCenter(manager, {
-  supabaseUrl: process.env.NEXT_PUBLIC_SUPABASE_URL,
-  supabaseServiceRoleKey: process.env.SUPABASE_SERVICE_ROLE_KEY,
+  supabaseUrl: useRemoteApiOnly ? null : process.env.NEXT_PUBLIC_SUPABASE_URL,
+  supabaseServiceRoleKey: useRemoteApiOnly ? null : process.env.SUPABASE_SERVICE_ROLE_KEY,
   projectName: process.env.PROJECT_NAME || "default"
 });
+logger.info("=== Axis MCP Server Initialized ===");
 var ragEngine;
-if (process.env.NEXT_PUBLIC_SUPABASE_URL && process.env.SUPABASE_SERVICE_ROLE_KEY) {
+if (!useRemoteApiOnly && process.env.NEXT_PUBLIC_SUPABASE_URL && process.env.SUPABASE_SERVICE_ROLE_KEY) {
   ragEngine = new RagEngine(
     process.env.NEXT_PUBLIC_SUPABASE_URL,
     process.env.SUPABASE_SERVICE_ROLE_KEY,
     process.env.OPENAI_API_KEY || ""
   );
+  logger.info("Local RAG Engine initialized.");
 }
 async function ensureFileSystem() {
   try {
-    const fs3 = await import("fs/promises");
-    const path3 = await import("path");
-    const fsSync = await import("fs");
+    const fs4 = await import("fs/promises");
+    const path4 = await import("path");
+    const fsSync2 = await import("fs");
     const cwd = process.cwd();
     logger.info(`Server CWD: ${cwd}`);
-    const historyDir = path3.join(cwd, "history");
-    await fs3.mkdir(historyDir, { recursive: true }).catch(() => {
+    const historyDir = path4.join(cwd, "history");
+    await fs4.mkdir(historyDir, { recursive: true }).catch(() => {
     });
-    const axisDir = path3.join(cwd, ".axis");
-    const axisInstructions = path3.join(axisDir, "instructions");
-    const legacyInstructions = path3.join(cwd, "agent-instructions");
-    if (fsSync.existsSync(legacyInstructions) && !fsSync.existsSync(axisDir)) {
+    const axisDir = path4.join(cwd, ".axis");
+    const axisInstructions = path4.join(axisDir, "instructions");
+    const legacyInstructions = path4.join(cwd, "agent-instructions");
+    if (fsSync2.existsSync(legacyInstructions) && !fsSync2.existsSync(axisDir)) {
       logger.info("Using legacy agent-instructions directory");
     } else {
-      await fs3.mkdir(axisInstructions, { recursive: true }).catch(() => {
+      await fs4.mkdir(axisInstructions, { recursive: true }).catch(() => {
       });
       const defaults = [
         ["context.md", "# Project Context\n\n"],
@@ -796,11 +1112,11 @@ async function ensureFileSystem() {
         ["activity.md", "# Activity Log\n\n"]
       ];
       for (const [file, content] of defaults) {
-        const p = path3.join(axisInstructions, file);
+        const p = path4.join(axisInstructions, file);
         try {
-          await fs3.access(p);
+          await fs4.access(p);
         } catch {
-          await fs3.writeFile(p, content);
+          await fs4.writeFile(p, content);
           logger.info(`Created default context file: ${file}`);
         }
       }
@@ -826,17 +1142,18 @@ var UPDATE_CONTEXT_TOOL = "update_context";
 var SEARCH_CONTEXT_TOOL = "search_codebase";
 server.setRequestHandler(ListResourcesRequestSchema, async () => {
   try {
-    return {
-      resources: [
-        {
-          uri: "mcp://context/current",
-          name: "Live Session Context",
-          mimeType: "text/markdown",
-          description: "The realtime state of the Nerve Center (Notepad + Locks)"
-        },
-        ...await manager.listFiles()
-      ]
-    };
+    const files = await manager.listFiles();
+    const resources = [
+      {
+        uri: "mcp://context/current",
+        name: "Live Session Context",
+        mimeType: "text/markdown",
+        description: "The realtime state of the Nerve Center (Notepad + Locks)"
+      },
+      ...files
+    ];
+    logger.info(`[ListResources] Returning ${resources.length} resources to MCP client`);
+    return { resources };
   } catch (error) {
     logger.error("Error listing resources", error);
     return { resources: [] };
@@ -850,7 +1167,7 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
         contents: [{
           uri,
           mimeType: "text/markdown",
-          text: await nerveCenter.getLiveContext()
+          text: await nerveCenter.getCoreContext()
         }]
       };
     }
@@ -873,192 +1190,193 @@ server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
   }
 });
 server.setRequestHandler(ListToolsRequestSchema, async () => {
-  return {
-    tools: [
-      {
-        name: READ_CONTEXT_TOOL,
-        description: "Read the shared context files (context.md, conventions.md, activity.md)",
-        inputSchema: {
-          type: "object",
-          properties: {
-            filename: { type: "string", description: "The name of the file to read (e.g., 'context.md')" }
-          },
-          required: ["filename"]
-        }
-      },
-      {
-        name: UPDATE_CONTEXT_TOOL,
-        description: "Update a shared context file",
-        inputSchema: {
-          type: "object",
-          properties: {
-            filename: { type: "string", description: "File to update" },
-            content: { type: "string", description: "New content" },
-            append: { type: "boolean", description: "Whether to append or overwrite (default: overwrite)" }
-          },
-          required: ["filename", "content"]
-        }
-      },
-      {
-        name: SEARCH_CONTEXT_TOOL,
-        description: "Search the codebase using vector similarity.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: { type: "string", description: "Search query" }
-          },
-          required: ["query"]
-        }
-      },
-      // --- Billing & Usage ---
-      {
-        name: "get_subscription_status",
-        description: "Check the subscription status of a user (Pro vs Free).",
-        inputSchema: {
-          type: "object",
-          properties: {
-            email: { type: "string", description: "User email to check." }
-          },
-          required: ["email"]
-        }
-      },
-      {
-        name: "get_usage_stats",
-        description: "Get API usage statistics for a user.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            email: { type: "string", description: "User email to check." }
-          },
-          required: ["email"]
-        }
-      },
-      {
-        name: "search_docs",
-        description: "Search the Axis documentation.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            query: { type: "string", description: "Search query." }
-          },
-          required: ["query"]
-        }
-      },
-      // --- Decision & Orchestration ---
-      {
-        name: "propose_file_access",
-        description: "Request a lock on a file. Checks for conflicts with other agents.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            agentId: { type: "string" },
-            filePath: { type: "string" },
-            intent: { type: "string" },
-            userPrompt: { type: "string", description: "The full prompt provided by the user that initiated this action." }
-          },
-          required: ["agentId", "filePath", "intent", "userPrompt"]
-        }
-      },
-      {
-        name: "update_shared_context",
-        description: "Write to the in-memory Live Notepad.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            agentId: { type: "string" },
-            text: { type: "string" }
-          },
-          required: ["agentId", "text"]
-        }
-      },
-      // --- Permanent Memory ---
-      {
-        name: "finalize_session",
-        description: "End the session, archive the notepad, and clear locks.",
-        inputSchema: { type: "object", properties: {}, required: [] }
-      },
-      {
-        name: "get_project_soul",
-        description: "Get high-level project goals and context.",
-        inputSchema: { type: "object", properties: {}, required: [] }
-      },
-      // --- Job Board (Task Orchestration) ---
-      {
-        name: "post_job",
-        description: "Post a new job/ticket. Supports priority and dependencies.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            title: { type: "string" },
-            description: { type: "string" },
-            priority: { type: "string", enum: ["low", "medium", "high", "critical"] },
-            dependencies: { type: "array", items: { type: "string" } }
-          },
-          required: ["title", "description"]
-        }
-      },
-      {
-        name: "cancel_job",
-        description: "Cancel a job that is no longer needed.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            jobId: { type: "string" },
-            reason: { type: "string" }
-          },
-          required: ["jobId", "reason"]
-        }
-      },
-      {
-        name: "force_unlock",
-        description: "Admin tool to forcibly remove a lock from a file.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            filePath: { type: "string" },
-            reason: { type: "string" }
-          },
-          required: ["filePath", "reason"]
-        }
-      },
-      {
-        name: "claim_next_job",
-        description: "Auto-assign the next available 'todo' job to yourself.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            agentId: { type: "string" }
-          },
-          required: ["agentId"]
-        }
-      },
-      {
-        name: "complete_job",
-        description: "Mark your assigned job as done.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            agentId: { type: "string" },
-            jobId: { type: "string" },
-            outcome: { type: "string" }
-          },
-          required: ["agentId", "jobId", "outcome"]
-        }
-      },
-      {
-        name: "index_file",
-        description: "Force re-index a file into the RAG vector database.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            filePath: { type: "string" },
-            content: { type: "string" }
-          },
-          required: ["filePath", "content"]
-        }
+  const tools = [
+    {
+      name: READ_CONTEXT_TOOL,
+      description: "**READ THIS FIRST** to understand the project's architecture, coding conventions, and active state.\n- Returns the content of core context files like `context.md` (Project Goals), `conventions.md` (Style Guide), or `activity.md`.\n- Usage: Call with `filename='context.md'` effectively.\n- Note: If you need the *current* runtime state (active locks, jobs), use the distinct resource `mcp://context/current` instead.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filename: { type: "string", description: "The name of the file to read (e.g., 'context.md', 'conventions.md')" }
+        },
+        required: ["filename"]
+      }
+    },
+    {
+      name: UPDATE_CONTEXT_TOOL,
+      description: "**APPEND OR OVERWRITE** shared context files.\n- Use this to update the project's long-term memory (e.g., adding a new convention, updating the architectural goal).\n- For short-term updates (like 'I just fixed bug X'), use `update_shared_context` (Notepad) instead.\n- Supports `append: true` (default: false) to add to the end of a file.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filename: { type: "string", description: "File to update (e.g. 'activity.md')" },
+          content: { type: "string", description: "The new content to write or append." },
+          append: { type: "boolean", description: "Whether to append to the end of the file (true) or overwrite it (false). Default: false." }
+        },
+        required: ["filename", "content"]
+      }
+    },
+    {
+      name: SEARCH_CONTEXT_TOOL,
+      description: "**SEMANTIC SEARCH** for the codebase.\n- Uses vector similarity to find relevant code snippets or documentation.\n- Best for: 'Where is the auth logic?', 'How do I handle billing?', 'Find the class that manages locks'.\n- Note: This searches *indexed* content only. For exact string matches, use `grep` (if available) or `warpgrep`.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Natural language search query." }
+        },
+        required: ["query"]
+      }
+    },
+    // --- Billing & Usage ---
+    {
+      name: "get_subscription_status",
+      description: "**BILLING CHECK**: specific to the Axis business logic.\n- Returns the user's subscription tier (Pro vs Free), Stripe customer ID, and current period end.\n- Critical for gating features behind paywalls.\n- Returns 'Profile not found' if the user doesn't exist in the database.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          email: { type: "string", description: "User email to check." }
+        },
+        required: ["email"]
       }
-    ]
-  };
+    },
+    {
+      name: "get_usage_stats",
+      description: "**API USAGE**: Returns a user's token usage and request counts.\n- Useful for debugging rate limits or explaining quota usage to users.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          email: { type: "string", description: "User email to check." }
+        },
+        required: ["email"]
+      }
+    },
+    {
+      name: "search_docs",
+      description: "**DOCUMENTATION SEARCH**: Searches the official Axis documentation (if indexed).\n- Use this when you need info on *how* to use Axis features, not just codebase structure.\n- Falls back to local RAG search if the remote API is unavailable.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Natural language search query." }
+        },
+        required: ["query"]
+      }
+    },
+    // --- Decision & Orchestration ---
+    {
+      name: "propose_file_access",
+      description: "**CRITICAL: REQUEST FILE LOCK**.\n- **MUST** be called *before* editing any file to prevent conflicts with other agents.\n- Checks if another agent currently holds a lock.\n- Returns `GRANTED` if safe to proceed, or `REQUIRES_ORCHESTRATION` if someone else is editing.\n- Usage: Provide your `agentId` (e.g., 'cursor-agent'), `filePath` (absolute), and `intent` (what you are doing).\n- Note: Locks expire after 30 minutes. Use `force_unlock` only if you are certain a lock is stale and blocking progress.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agentId: { type: "string" },
+          filePath: { type: "string" },
+          intent: { type: "string" },
+          userPrompt: { type: "string", description: "The full prompt provided by the user that initiated this action." }
+        },
+        required: ["agentId", "filePath", "intent", "userPrompt"]
+      }
+    },
+    {
+      name: "update_shared_context",
+      description: "**LIVE NOTEPAD**: The project's short-term working memory.\n- **ALWAYS** call this after completing a significant step (e.g., 'Fixed bug in auth.ts', 'Ran tests, all passed').\n- This content is visible to *all* other agents immediately.\n- Think of this as a team chat or 'standup' update.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agentId: { type: "string" },
+          text: { type: "string" }
+        },
+        required: ["agentId", "text"]
+      }
+    },
+    // --- Permanent Memory ---
+    {
+      name: "finalize_session",
+      description: "**END OF SESSION HOUSEKEEPING**.\n- Archives the current Live Notepad to a permanent session log.\n- Clears all active locks and completed jobs.\n- Resets the Live Notepad for the next session.\n- Call this when the user says 'we are done' or 'start fresh'.",
+      inputSchema: { type: "object", properties: {}, required: [] }
+    },
+    {
+      name: "get_project_soul",
+      description: "**HIGH-LEVEL INTENT**: Returns the 'Soul' of the project.\n- Combines `context.md`, `conventions.md`, and other core directives into a single prompt.\n- Use this at the *start* of a conversation to ground yourself in the project's reality.",
+      inputSchema: { type: "object", properties: {}, required: [] }
+    },
+    // --- Job Board (Task Orchestration) ---
+    {
+      name: "post_job",
+      description: "**CREATE TICKET**: Post a new task to the Job Board.\n- Use this when you identify work that needs to be done but *cannot* be done right now (e.g., refactoring, new feature).\n- Supports `dependencies` (list of other Job IDs that must be done first).\n- Priority: low, medium, high, critical.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          title: { type: "string" },
+          description: { type: "string" },
+          priority: { type: "string", enum: ["low", "medium", "high", "critical"] },
+          dependencies: { type: "array", items: { type: "string" }, description: "Array of Job IDs that must be completed before this job can be claimed." }
+        },
+        required: ["title", "description"]
+      }
+    },
+    {
+      name: "cancel_job",
+      description: "**KILL TICKET**: Cancel a job that is no longer needed.\n- Requires `jobId` and a `reason`.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          jobId: { type: "string" },
+          reason: { type: "string" }
+        },
+        required: ["jobId", "reason"]
+      }
+    },
+    {
+      name: "force_unlock",
+      description: "**ADMIN OVERRIDE**: Break a file lock.\n- **WARNING**: Only use this if a lock is clearly stale or the locking agent has crashed.\n- Will forcibly remove the lock from the database.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filePath: { type: "string" },
+          reason: { type: "string" }
+        },
+        required: ["filePath", "reason"]
+      }
+    },
+    {
+      name: "claim_next_job",
+      description: "**AUTO-ASSIGNMENT**: Ask the Job Board for the next most important task.\n- Respects priority (Critical > High > ...) and dependencies (won't assign a job if its deps aren't done).\n- Returns the Job object if successful, or 'NO_JOBS_AVAILABLE'.\n- Use this when you are idle and looking for work.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agentId: { type: "string" }
+        },
+        required: ["agentId"]
+      }
+    },
+    {
+      name: "complete_job",
+      description: "**CLOSE TICKET**: Mark a job as done.\n- Requires `outcome` (what was done).\n- If you are not the assigned agent, you must provide the `completionKey`.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          agentId: { type: "string" },
+          jobId: { type: "string" },
+          outcome: { type: "string" },
+          completionKey: { type: "string", description: "Optional key to authorize completion if not the assigned agent." }
+        },
+        required: ["agentId", "jobId", "outcome"]
+      }
+    },
+    {
+      name: "index_file",
+      description: "**UPDATE SEARCH INDEX**: Add a file's content to the RAG vector database.\n- Call this *immediately* after creating a new file or significantly refactoring an existing one.\n- Ensures future `search_codebase` calls return up-to-date results.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          filePath: { type: "string" },
+          content: { type: "string" }
+        },
+        required: ["filePath", "content"]
+      }
+    }
+  ];
+  logger.info(`[ListTools] Returning ${tools.length} tools to MCP client`);
+  return { tools };
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
@@ -1122,20 +1440,38 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
   if (name === "get_subscription_status") {
     const email = String(args?.email);
-    const result = await nerveCenter.getSubscriptionStatus(email);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    logger.info(`[get_subscription_status] Called with email: ${email}`);
+    try {
+      const result = await nerveCenter.getSubscriptionStatus(email);
+      logger.info(`[get_subscription_status] Result: ${JSON.stringify(result).substring(0, 200)}`);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (e) {
+      logger.error(`[get_subscription_status] Exception: ${e.message}`, e);
+      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }, null, 2) }], isError: true };
+    }
   }
   if (name === "get_usage_stats") {
     const email = String(args?.email);
-    const result = await nerveCenter.getUsageStats(email);
-    return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    logger.info(`[get_usage_stats] Called with email: ${email}`);
+    try {
+      const result = await nerveCenter.getUsageStats(email);
+      logger.info(`[get_usage_stats] Result: ${JSON.stringify(result).substring(0, 200)}`);
+      return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+    } catch (e) {
+      logger.error(`[get_usage_stats] Exception: ${e.message}`, e);
+      return { content: [{ type: "text", text: JSON.stringify({ error: e.message }, null, 2) }], isError: true };
+    }
   }
   if (name === "search_docs") {
     const query = String(args?.query);
     try {
-      const formatted = await manager.searchContext(query);
+      const formatted = await manager.searchContext(query, nerveCenter.currentProjectName);
       return { content: [{ type: "text", text: formatted }] };
     } catch (err) {
+      if (ragEngine) {
+        const results = await ragEngine.search(query);
+        return { content: [{ type: "text", text: results.join("\n---\n") }] };
+      }
       return {
         content: [{ type: "text", text: `Search Error: ${err}` }],
         isError: true
@@ -1181,8 +1517,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   }
   if (name === "complete_job") {
-    const { agentId, jobId, outcome } = args;
-    const result = await nerveCenter.completeJob(agentId, jobId, outcome);
+    const { agentId, jobId, outcome, completionKey } = args;
+    const result = await nerveCenter.completeJob(agentId, jobId, outcome, completionKey);
     return { content: [{ type: "text", text: JSON.stringify(result) }] };
   }
   throw new Error(`Tool not found: ${name}`);
@@ -1194,9 +1530,11 @@ async function main() {
     ragEngine.setProjectId(nerveCenter.projectId);
     logger.info(`Local RAG Engine linked to Project ID: ${nerveCenter.projectId}`);
   }
+  logger.info("MCP server ready - all tools and resources registered");
   const transport = new StdioServerTransport();
   await server.connect(transport);
   logger.info("Shared Context MCP Server running on stdio");
+  logger.info("Server is now accepting tool calls from MCP clients");
 }
 main().catch((error) => {
   logger.error("Server error", error);