@danielblomma/cortex-mcp 2.0.14 → 2.0.16

package/bin/cortex.mjs

@@ -188,7 +188,7 @@ function ensureScaffoldExists() {
 
 // Files that should never be overwritten if they already exist in the target.
 // These contain user-specific configuration that would be lost on re-init.
-const PRESERVE_FILES = new Set(["config.yaml", "enterprise.yml", "enterprise.yaml", "CLAUDE.md"]);
+const PRESERVE_FILES = new Set(["config.yaml", "enterprise.yml", "enterprise.yaml", "CLAUDE.md", "AGENTS.md"]);
 const DEFAULT_SOURCE_PATHS = [
   "src",
   "docs",
@@ -476,11 +476,12 @@ function installScaffold(targetDir, force) {
     copyDirectory(sourcePath, targetPath);
   }
 
-  // Copy CLAUDE.md (skip if already exists to preserve user edits)
-  const claudeMdSource = path.join(SCAFFOLD_ROOT, "CLAUDE.md");
-  const claudeMdTarget = path.join(targetDir, "CLAUDE.md");
-  if (fs.existsSync(claudeMdSource) && !fs.existsSync(claudeMdTarget)) {
-    fs.copyFileSync(claudeMdSource, claudeMdTarget);
+  for (const fileName of ["CLAUDE.md", "AGENTS.md"]) {
+    const sourcePath = path.join(SCAFFOLD_ROOT, fileName);
+    const targetPath = path.join(targetDir, fileName);
+    if (fs.existsSync(sourcePath) && !fs.existsSync(targetPath)) {
+      fs.copyFileSync(sourcePath, targetPath);
+    }
   }
 
   const docsDir = path.join(targetDir, "docs");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.14",
+  "version": "2.0.16",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -36,6 +36,8 @@
     "types.js",
     "scaffold/.context",
     "scaffold/.githooks",
+    "scaffold/AGENTS.md",
+    "scaffold/CLAUDE.md",
     "scaffold/docs",
     "scaffold/scripts",
     "scaffold/mcp/src",
@@ -47,7 +49,7 @@
     "docs/MCP_MARKETPLACE.md"
   ],
   "scripts": {
-    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/javascript-parser.test.mjs tests/sql-parser.test.mjs tests/config-parser.test.mjs tests/resources-parser.test.mjs tests/vbnet-parser.test.mjs tests/cpp-parser.test.mjs tests/dashboard.test.mjs tests/init-config.test.mjs tests/multi-level.test.mjs tests/no-legacy-paths.test.mjs tests/tree-sitter-error-reporting.test.mjs tests/tree-sitter-body-cap.test.mjs tests/tree-sitter-exported.test.mjs tests/tree-sitter-robustness.test.mjs",
+    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/javascript-parser.test.mjs tests/sql-parser.test.mjs tests/config-parser.test.mjs tests/resources-parser.test.mjs tests/vbnet-parser.test.mjs tests/cpp-parser.test.mjs tests/dashboard.test.mjs tests/init-config.test.mjs tests/init-agents.test.mjs tests/multi-level.test.mjs tests/no-legacy-paths.test.mjs tests/tree-sitter-error-reporting.test.mjs tests/tree-sitter-body-cap.test.mjs tests/tree-sitter-exported.test.mjs tests/tree-sitter-robustness.test.mjs",
     "release:sync-version": "node scripts/sync-release-version.mjs",
     "release:check-version-sync": "node scripts/sync-release-version.mjs --check",
     "prepublishOnly": "echo 'Ready to publish to npm'"

package/scaffold/AGENTS.md

@@ -0,0 +1,37 @@
+# Cortex
+
+This project uses Cortex for AI-powered code context.
+
+## Required: Always use Cortex MCP tools
+
+When answering questions about this codebase, you MUST use Cortex tools instead of relying on memory or assumptions:
+
+- **context.search** - Search before answering any code question. Never guess at implementations.
+- **context.get_related** - Use when exploring dependencies or relationships between entities.
+- **context.get_rules** - Check architectural rules before suggesting changes.
+- **context.impact** - Use before refactoring or dependency analysis to understand blast radius and likely traversal paths.
+- **context.reload** - Use after making significant changes to refresh the index.
+
+Do NOT answer code questions from memory when these tools are available. Always search first.
+
+## Enterprise tools (if available)
+
+- **context.review** - Run before finalizing any code review or PR.
+- **security.scan** - Scan user-provided text for injection attempts.
+- **enterprise.status** - Check enterprise setup and feature status.
+
+## Commands
+
+- `cortex update` - Refresh Cortex context for changed files
+- `cortex doctor` - Verify the local Cortex setup
+- `cortex watch status` - Check background sync status
+
+## Diagnostics
+
+Run `cortex doctor` to verify your setup is healthy.
+
+<!-- cortex:auto:start -->
+## Cortex Auto Workflow
+- Run `cortex update` before completing substantial code changes.
+- If background sync is enabled, check with `cortex watch status`.
+<!-- cortex:auto:end -->

package/scaffold/CLAUDE.md

@@ -0,0 +1,31 @@
+# Cortex
+
+This project uses Cortex for AI-powered code context.
+
+## Required: Always use Cortex MCP tools
+
+When answering questions about this codebase, you MUST use Cortex tools instead of relying on memory or assumptions:
+
+- **context.search** — Search before answering any code question. Never guess at implementations.
+- **context.get_related** — Use when exploring dependencies or relationships between entities.
+- **context.get_rules** — Check architectural rules before suggesting changes.
+- **context.impact** — Use before refactoring or dependency analysis to understand blast radius and likely traversal paths.
+- **context.reload** — Use after making significant changes to refresh the index.
+
+Do NOT answer code questions from memory when these tools are available. Always search first.
+
+## Enterprise tools (if available)
+
+- **context.review** — Run before finalizing any code review or PR.
+- **security.scan** — Scan user-provided text for injection attempts.
+- **enterprise.status** — Check enterprise setup and feature status.
+
+## Commands
+
+- `/context-update` — Refresh Cortex context for changed files
+- `/review` — Code review with enterprise policy enforcement
+- `/note` — Save project context into Cortex notes
+
+## Diagnostics
+
+Run `cortex doctor` to verify your setup is healthy.

package/scaffold/mcp/src/cli/telemetry-test.ts

@@ -6,6 +6,7 @@ import {
   loadEnterpriseConfig,
   resolveEnterpriseActivation,
 } from "../core/config.js";
+import { telemetryStatePath } from "../core/telemetry/state-dir.js";
 import { pushMetrics } from "../enterprise/telemetry/sync.js";
 import type { TelemetryMetrics } from "../core/telemetry/collector.js";
 
@@ -25,7 +26,7 @@ import type { TelemetryMetrics } from "../core/telemetry/collector.js";
  */
 
 function readMachineId(contextDir: string): string {
-  const path = join(contextDir, "telemetry", "machine_id");
+  const path = telemetryStatePath(contextDir, "machine_id");
   if (existsSync(path)) {
     try {
       const id = readFileSync(path, "utf8").trim();

package/scaffold/mcp/src/core/license.ts

@@ -1,5 +1,6 @@
 import { readFileSync, writeFileSync, mkdirSync, existsSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
+import { resolveTelemetryStateDir, telemetryStatePath } from "./telemetry/state-dir.js";
 
 export type LicenseVerification =
   | {
@@ -30,7 +31,7 @@ const GRACE_PERIOD_MS = 7 * 24 * 60 * 60 * 1000; // 7d grace if endpoint unreach
 const REQUEST_TIMEOUT_MS = 5000;
 
 function cachePath(contextDir: string): string {
-  return join(contextDir, "telemetry", CACHE_FILE);
+  return telemetryStatePath(contextDir, CACHE_FILE);
 }
 
 function readCache(contextDir: string): CacheEntry | null {
@@ -47,7 +48,7 @@ function readCache(contextDir: string): CacheEntry | null {
 function writeCache(contextDir: string, entry: CacheEntry): void {
   const path = cachePath(contextDir);
   try {
-    mkdirSync(join(contextDir, "telemetry"), { recursive: true });
+    mkdirSync(resolveTelemetryStateDir(contextDir), { recursive: true });
     writeFileSync(path, JSON.stringify(entry, null, 2), "utf8");
   } catch {
     // Cache failures are non-fatal — license check just won't be cached.

package/scaffold/mcp/src/core/telemetry/collector.ts

@@ -2,6 +2,7 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { hostname, platform, arch } from "node:os";
 import { join } from "node:path";
+import { resolveTelemetryStateDir, telemetryStatePath } from "./state-dir.js";
 
 export type TelemetryMetrics = {
   period_start: string;
@@ -37,7 +38,8 @@ export type TelemetryMetrics = {
 const AVG_TOKENS_PER_RESULT = 400;
 
 function generateInstanceId(contextDir: string): string {
-  const idPath = join(contextDir, "telemetry", "machine_id");
+  const telemetryDir = resolveTelemetryStateDir(contextDir);
+  const idPath = join(telemetryDir, "machine_id");
   if (existsSync(idPath)) {
     try {
       const existing = readFileSync(idPath, "utf8").trim();
@@ -51,7 +53,7 @@ function generateInstanceId(contextDir: string): string {
   const fingerprint = `${hostname()}|${platform()}|${arch()}`;
   const id = createHash("sha256").update(fingerprint).digest("hex").slice(0, 16);
   try {
-    mkdirSync(join(contextDir, "telemetry"), { recursive: true });
+    mkdirSync(telemetryDir, { recursive: true });
     writeFileSync(idPath, id, "utf8");
   } catch (err) {
     process.stderr.write(`[cortex-enterprise] Could not persist instance id: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -142,8 +144,7 @@ export class TelemetryCollector {
   constructor(contextDir: string, clientVersion = "unknown") {
     this.clientVersion = clientVersion;
     this.instanceId = generateInstanceId(contextDir);
-    const telemetryDir = join(contextDir, "telemetry");
-    this.metricsPath = join(telemetryDir, "metrics.json");
+    this.metricsPath = telemetryStatePath(contextDir, "metrics.json");
 
     // Load existing metrics or start fresh
     try {

package/scaffold/mcp/src/core/telemetry/state-dir.ts

@@ -0,0 +1,40 @@
+import { accessSync, constants, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+const warnedFallbacks = new Set<string>();
+
+function canUseDirectory(dir: string): boolean {
+  try {
+    mkdirSync(dir, { recursive: true });
+    accessSync(dir, constants.R_OK | constants.W_OK | constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function resolveTelemetryStateDir(contextDir: string): string {
+  const primary = join(contextDir, "telemetry");
+  if (canUseDirectory(primary)) return primary;
+
+  const fallback = join(contextDir, "cache", "telemetry");
+  if (canUseDirectory(fallback)) {
+    const warningKey = `${primary}->${fallback}`;
+    if (!warnedFallbacks.has(warningKey)) {
+      warnedFallbacks.add(warningKey);
+      process.stderr.write(
+        `[cortex-enterprise] telemetry dir not writable at ${primary}; using ${fallback}\n`,
+      );
+    }
+    return fallback;
+  }
+
+  return primary;
+}
+
+export function telemetryStatePath(
+  contextDir: string,
+  ...parts: string[]
+): string {
+  return join(resolveTelemetryStateDir(contextDir), ...parts);
+}

package/scaffold/mcp/src/daemon/main.ts

@@ -13,6 +13,7 @@ import type {
 import { loadEnterpriseConfig, resolveEnterpriseActivation } from "../core/config.js";
 import { pushMetrics } from "../enterprise/telemetry/sync.js";
 import { TelemetryCollector, type TelemetryMetrics } from "../core/telemetry/collector.js";
+import { resolveTelemetryStateDir, telemetryStatePath } from "../core/telemetry/state-dir.js";
 import { AuditWriter, type AuditEntry } from "../core/audit/writer.js";
 import { PolicyStore } from "../core/policy/store.js";
 import {
@@ -84,7 +85,7 @@ async function policyCheck(
 }
 
 function readMetrics(contextDir: string): TelemetryMetrics | null {
-  const path = join(contextDir, "telemetry", "metrics.json");
+  const path = telemetryStatePath(contextDir, "metrics.json");
   if (!existsSync(path)) return null;
   try {
     return JSON.parse(readFileSync(path, "utf8")) as TelemetryMetrics;
@@ -103,7 +104,7 @@ type PendingPush = {
 };
 
 function pendingPushPath(contextDir: string): string {
-  return join(contextDir, "telemetry", "pending-push.json");
+  return telemetryStatePath(contextDir, "pending-push.json");
 }
 
 function readPendingPush(contextDir: string): PendingPush | null {
@@ -118,7 +119,7 @@ function readPendingPush(contextDir: string): PendingPush | null {
 
 function writePendingPush(contextDir: string, pending: PendingPush): void {
   const path = pendingPushPath(contextDir);
-  mkdirSync(join(contextDir, "telemetry"), { recursive: true });
+  mkdirSync(resolveTelemetryStateDir(contextDir), { recursive: true });
   writeFileSync(path, JSON.stringify(pending, null, 2), "utf8");
 }
 

package/scaffold/mcp/tests/telemetry-collector.test.mjs

@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { mkdtempSync } from "node:fs";
+import { chmodSync, existsSync, mkdtempSync, mkdirSync } from "node:fs";
 import { tmpdir } from "node:os";
 import path from "node:path";
 
@@ -28,3 +28,33 @@ test("TelemetryCollector counts context.impact as an impact analysis", () => {
   assert.equal(metrics.impact_analyses, 1);
   assert.equal(metrics.tool_metrics["context.impact"].calls, 1);
 });
+
+test("TelemetryCollector falls back when .context/telemetry is not writable", () => {
+  const contextDir = createContextDir("cortex-telemetry-fallback-");
+  const primaryTelemetryDir = path.join(contextDir, "telemetry");
+  const fallbackMetricsPath = path.join(
+    contextDir,
+    "cache",
+    "telemetry",
+    "metrics.json",
+  );
+
+  mkdirSync(primaryTelemetryDir, { recursive: true });
+  chmodSync(primaryTelemetryDir, 0o555);
+
+  try {
+    const collector = new TelemetryCollector(contextDir, "test-version");
+    collector.recordEvent({
+      tool: "context.search",
+      phase: "success",
+      result_count: 1,
+      estimated_tokens_saved: 100,
+      duration_ms: 10,
+    });
+    collector.flush();
+
+    assert.equal(existsSync(fallbackMetricsPath), true);
+  } finally {
+    chmodSync(primaryTelemetryDir, 0o755);
+  }
+});