@cachly-dev/mcp-server 0.10.27 → 0.10.41

package/scripts/e2e-run.sh

@@ -0,0 +1,160 @@
+#!/usr/bin/env bash
+# ─────────────────────────────────────────────────────────────────────────────
+# cachly E2E test runner
+#
+# Usage:
+#   ./scripts/e2e-run.sh                 # run all e2e tests
+#   ./scripts/e2e-run.sh api             # only API health + auth tests
+#   ./scripts/e2e-run.sh tools           # only MCP tool tests (needs Redis creds)
+#   ./scripts/e2e-run.sh cli             # only CLI smoke tests
+#   ./scripts/e2e-run.sh funnel          # only funnel telemetry tests
+#   ./scripts/e2e-run.sh provisioning    # provisioning lifecycle (slow, ~5 min)
+#
+# Required env vars:
+#   E2E_API_URL       https://api.dev.cachly.dev   (or prod)
+#   E2E_JWT           <keycloak access token>
+#   E2E_INSTANCE_ID   <uuid of active test Brain>
+#   E2E_API_KEY       <redis password>
+#   E2E_REDIS_HOST    <redis host>
+#
+# Optional:
+#   E2E_REDIS_PORT    6380
+#   E2E_REDIS_TLS     true
+#   E2E_SKIP_SLOW     true   (skip provisioning + device flow)
+# ─────────────────────────────────────────────────────────────────────────────
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$ROOT"
+
+# ── Load .env.test if present (convenience for local dev) ─────────────────────
+if [[ -f "$ROOT/.env.test" ]]; then
+  set -a
+  # shellcheck source=/dev/null
+  source "$ROOT/.env.test"
+  set +a
+  echo -e "\033[90m[e2e] Loaded $ROOT/.env.test\033[0m"
+fi
+
+# ── Defaults ──────────────────────────────────────────────────────────────────
+export E2E_API_URL="${E2E_API_URL:-https://api.cachly.dev}"
+export E2E_REDIS_PORT="${E2E_REDIS_PORT:-6380}"
+export E2E_REDIS_TLS="${E2E_REDIS_TLS:-true}"
+export E2E_SKIP_SLOW="${E2E_SKIP_SLOW:-false}"
+
+# ── Color output ──────────────────────────────────────────────────────────────
+RED='\033[0;31m'; GREEN='\033[0;32m'; YELLOW='\033[1;33m'; NC='\033[0m'
+
+header() { echo -e "\n${YELLOW}━━━ $1 ━━━${NC}"; }
+ok()     { echo -e "${GREEN}✓ $1${NC}"; }
+fail()   { echo -e "${RED}✗ $1${NC}"; }
+
+# ── Pre-flight checks ─────────────────────────────────────────────────────────
+header "Pre-flight"
+
+if [[ -z "${E2E_JWT:-}" ]]; then
+  fail "E2E_JWT is not set. Export a valid Keycloak token."
+  echo "  Hint: copy your JWT from https://${E2E_API_URL}/api/v1/debug/me after login"
+  exit 1
+fi
+ok "E2E_JWT is set (length: ${#E2E_JWT})"
+
+if [[ -z "${E2E_INSTANCE_ID:-}" ]]; then
+  echo -e "${YELLOW}⚠  E2E_INSTANCE_ID not set — instance-specific tests will be skipped${NC}"
+else
+  ok "E2E_INSTANCE_ID: $E2E_INSTANCE_ID"
+fi
+
+# ── Build ─────────────────────────────────────────────────────────────────────
+header "Building"
+npm run build
+ok "Build complete"
+
+# ── Select test suite ─────────────────────────────────────────────────────────
+SUITE="${1:-all}"
+
+VITEST_BASE="npx vitest run --reporter=verbose"
+E2E_DIR="src/__tests__/e2e"
+
+run_suite() {
+  local name="$1"; local pattern="$2"
+  header "Running: $name"
+  $VITEST_BASE "$pattern" && ok "$name passed" || { fail "$name FAILED"; exit 1; }
+}
+
+case "$SUITE" in
+  api)
+    run_suite "API health + auth" "$E2E_DIR/api-health.test.ts $E2E_DIR/api-auth.test.ts"
+    ;;
+  tools)
+    if [[ -z "${E2E_API_KEY:-}" || -z "${E2E_REDIS_HOST:-}" ]]; then
+      fail "E2E_API_KEY and E2E_REDIS_HOST required for MCP tool tests"
+      exit 1
+    fi
+    run_suite "MCP tools" "$E2E_DIR/mcp-tools.test.ts"
+    ;;
+  cli)
+    run_suite "CLI smoke" "$E2E_DIR/cli.test.ts"
+    ;;
+  funnel)
+    run_suite "Funnel telemetry" "$E2E_DIR/funnel.test.ts"
+    ;;
+  provisioning)
+    export E2E_SKIP_SLOW=false
+    run_suite "Provisioning lifecycle" "$E2E_DIR/provisioning.test.ts"
+    ;;
+  all)
+    header "Running ALL e2e suites"
+
+    echo ""
+    echo "  API URL:      $E2E_API_URL"
+    echo "  Instance ID:  ${E2E_INSTANCE_ID:-(not set)}"
+    echo "  Redis host:   ${E2E_REDIS_HOST:-(not set — tool tests will fail)}"
+    echo "  Skip slow:    $E2E_SKIP_SLOW"
+    echo ""
+
+    FAILED=()
+
+    run_one() {
+      local name="$1"; local file="$2"
+      header "$name"
+      if $VITEST_BASE "$file"; then
+        ok "$name passed"
+      else
+        fail "$name FAILED"
+        FAILED+=("$name")
+      fi
+    }
+
+    run_one "API health (no auth)"  "$E2E_DIR/api-health.test.ts"
+    run_one "API auth + instances"  "$E2E_DIR/api-auth.test.ts"
+    run_one "Funnel telemetry"      "$E2E_DIR/funnel.test.ts"
+    run_one "CLI smoke tests"       "$E2E_DIR/cli.test.ts"
+
+    if [[ -n "${E2E_API_KEY:-}" && -n "${E2E_REDIS_HOST:-}" ]]; then
+      run_one "MCP tools (live Redis)" "$E2E_DIR/mcp-tools.test.ts"
+    else
+      echo -e "${YELLOW}⚠  Skipping MCP tool tests (E2E_API_KEY / E2E_REDIS_HOST not set)${NC}"
+    fi
+
+    if [[ "$E2E_SKIP_SLOW" != "true" ]]; then
+      run_one "Provisioning lifecycle" "$E2E_DIR/provisioning.test.ts"
+    else
+      echo -e "${YELLOW}⚠  Skipping provisioning tests (E2E_SKIP_SLOW=true)${NC}"
+    fi
+
+    echo ""
+    if [[ ${#FAILED[@]} -eq 0 ]]; then
+      echo -e "${GREEN}━━━ ALL E2E TESTS PASSED ━━━${NC}"
+    else
+      echo -e "${RED}━━━ FAILED SUITES: ${FAILED[*]} ━━━${NC}"
+      exit 1
+    fi
+    ;;
+  *)
+    echo "Unknown suite: $SUITE"
+    echo "Usage: $0 [all|api|tools|cli|funnel|provisioning]"
+    exit 1
+    ;;
+esac

package/scripts/postinstall.js

@@ -2,28 +2,28 @@
 // Shown once after: npm install @cachly-dev/mcp-server
 
 const c = {
-  reset: "\x1b[0m",
-  bold: "\x1b[1m",
+  reset:  "\x1b[0m",
+  bold:   "\x1b[1m",
   violet: "\x1b[35m",
-  green: "\x1b[32m",
-  cyan: "\x1b[36m",
+  green:  "\x1b[32m",
+  cyan:   "\x1b[36m",
+  dim:    "\x1b[2m",
   yellow: "\x1b[33m",
-  dim: "\x1b[2m",
 };
 
 const line = `${c.dim}─────────────────────────────────────────────────────${c.reset}`;
 
 console.log(`
 ${line}
-  ${c.bold}${c.violet}🧠 Cachly Brain MCP Server${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
+  ${c.bold}${c.violet}🧠 cachly AI Brain${c.reset} ${c.dim}v${process.env.npm_package_version ?? ""}${c.reset}
 
-  ${c.bold}Your AI forgets everything after each session. This fixes that.${c.reset}
+  ${c.bold}One command sets everything up:${c.reset}
 
-  ${c.green}Setup in 30 seconds (auto-detects all your editors):${c.reset}
-  ${c.cyan}npx @cachly-dev/init${c.reset}
+  ${c.cyan}npx @cachly-dev/mcp-server@latest setup${c.reset}
 
-  ${c.dim}Claude Code · Cursor · GitHub Copilot · Windsurf · Continue${c.reset}
-  ${c.dim}Free tier · GDPR · EU servers · No credit card${c.reset}
+  Signs you in → detects your editors → writes all MCP configs
+  automatically → adds Brain rules to CLAUDE.md.
 
+  ${c.green}No credentials. No credit card. Free forever.${c.reset}
+  ${c.dim}Other editors: https://cachly.dev/docs/mcp${c.reset}
 ${line}`);
-

package/server.json

@@ -1,27 +1,21 @@
 {
   "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.cachly-dev/cachly-mcp",
-  "description": "Give Claude a persistent memory that never forgets. cachly learns automatically from every session, bug fix, and git commit — no manual calls needed. Arrives pre-briefed. Predicts failures before they happen. One-click sign-in (OAuth Device Flow) · 63 tools · Free tier · EU servers · works with Claude Code, Cursor, Copilot, Windsurf.",
+  "description": "Your AI forgets everything between sessions. cachly fixes that permanently. A causal brain that learns WHY things break — built from every bug fix, git commit, and CI run, without any explicit calls. Arrives pre-briefed each session. Predicts failures before they happen. Never re-researches the same problem. 89 MCP tools · Free tier · EU servers · GDPR.",
   "repository": {
     "url": "https://github.com/cachly-dev/cachly-mcp",
     "source": "github"
   },
-  "version": "0.10.1",
+  "version": "0.10.23",
   "packages": [
     {
       "registryType": "npm",
       "name": "@cachly-dev/mcp-server",
       "identifier": "@cachly-dev/mcp-server",
-      "version": "0.10.1",
+      "version": "0.10.23",
       "transport": {
         "type": "stdio"
       }
     }
-  ],
-  "remotes": [
-    {
-      "transportType": "streamable-http",
-      "url": "https://mcp.cachly.dev/mcp"
-    }
   ]
 }

package/smithery.yaml

@@ -1,3 +1,12 @@
+name: cachly AI Brain
+description: >
+  Persistent AI memory for Claude Code, Cursor, Copilot, Windsurf, Cline & Zed.
+  Your AI remembers every lesson, fix, and architecture decision — forever.
+  Features: causal root-cause analysis (causal_trace), failure prediction (brain_predict),
+  git-ambient learning (brain_from_git), team knowledge sharing, Memory Crystals,
+  BM25+ search in 11 languages. 84 MCP tools. Free tier. GDPR. German servers.
+  Zero-config: sign in once via browser, auto-provisions your Brain instance.
+
 startCommand:
   type: stdio
   configSchema:
@@ -5,23 +14,21 @@ startCommand:
     properties:
       CACHLY_JWT:
         type: string
-        title: "API Key"
-        description: "Optional. Leave blank — on your first tool call the server starts a one-click browser sign-in (OAuth Device Flow) and auto-provisions your free Brain instance. No copy-paste, no dashboard visit required. Or pre-fill with your API key from cachly.dev/setup-ai."
-        default: ""
+        title: "API Key (optional — sign in via browser on first use)"
+        description: "Leave blank for zero-config: on your first tool call the server opens a browser sign-in (OAuth Device Flow) and auto-provisions your Brain instance. Or pre-fill with your API key from cachly.dev/setup-ai."
         examples:
           - "cky_live_abc123..."
       CACHLY_BRAIN_INSTANCE_ID:
         type: string
-        title: "Brain Instance ID"
-        description: "Optional. Leave blank — the server auto-detects your active instance. Only set this if you have multiple Brain instances."
-        default: ""
+        title: "Brain Instance ID (optional)"
+        description: "Only needed if you have multiple Brain instances. Leave blank — the server auto-detects your active instance from the API key."
         pattern: "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
         examples:
           - "9d4077aa-bfa2-468b-89cd-0a8d8f3ec483"
       CACHLY_API_URL:
         type: string
-        title: "API URL"
-        description: "Optional. Leave blank unless you self-host cachly."
+        title: "API URL (optional)"
+        description: "Leave blank unless you self-host Cachly."
         default: "https://api.cachly.dev"
     required: []
   commandFunction: |-

package/src/__tests__/auth.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from 'vitest';
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { jwtExpiryMs, checkJwt, handleApiError } from '../auth.js';
+
+function makeJwt(payload: Record<string, unknown>): string {
+  const header = Buffer.from(JSON.stringify({ alg: 'HS256', typ: 'JWT' })).toString('base64url');
+  const body   = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  return `${header}.${body}.fakesig`;
+}
+
+const nowSec = () => Math.floor(Date.now() / 1000);
+
+describe('jwtExpiryMs', () => {
+  it('returns null for an empty string', () => {
+    expect(jwtExpiryMs('')).toBeNull();
+  });
+
+  it('returns null for a plain (non-JWT) string', () => {
+    expect(jwtExpiryMs('not-a-token')).toBeNull();
+  });
+
+  it('returns null when the JWT has only two parts', () => {
+    expect(jwtExpiryMs('header.payload')).toBeNull();
+  });
+
+  it('returns null when the JWT has four parts', () => {
+    expect(jwtExpiryMs('a.b.c.d')).toBeNull();
+  });
+
+  it('returns null when the payload base64 is invalid', () => {
+    expect(jwtExpiryMs('header.!!!.sig')).toBeNull();
+  });
+
+  it('returns null when the payload has no exp field', () => {
+    expect(jwtExpiryMs(makeJwt({ sub: 'user-123', iat: nowSec() }))).toBeNull();
+  });
+
+  it('returns null when exp is 0', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: 0 }))).toBeNull();
+  });
+
+  it('converts exp (seconds) to milliseconds', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec }))).toBe(expSec * 1000);
+  });
+
+  it('returns a past timestamp for an expired token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() - 300 }))).toBeLessThan(Date.now());
+  });
+
+  it('returns a future timestamp for a valid token', () => {
+    expect(jwtExpiryMs(makeJwt({ exp: nowSec() + 86400 }))).toBeGreaterThan(Date.now());
+  });
+
+  it('handles a token expiring in less than 60 minutes', () => {
+    const expSec = nowSec() + 30 * 60;
+    const result = jwtExpiryMs(makeJwt({ exp: expSec }))!;
+    const minsLeft = Math.floor((result - Date.now()) / 60_000);
+    expect(minsLeft).toBeGreaterThanOrEqual(29);
+    expect(minsLeft).toBeLessThanOrEqual(30);
+  });
+
+  it('ignores extra claims', () => {
+    const expSec = nowSec() + 3600;
+    expect(jwtExpiryMs(makeJwt({ sub: 'u', iat: nowSec(), exp: expSec, plan: 'free' }))).toBe(expSec * 1000);
+  });
+
+  it('handles padding-free base64url payloads', () => {
+    // base64url (no =) — Buffer.from handles this natively
+    const expSec = nowSec() + 7200;
+    expect(jwtExpiryMs(makeJwt({ exp: expSec, x: 'a' }))).toBe(expSec * 1000);
+  });
+});
+
+describe('checkJwt', () => {
+  it('throws InvalidRequest when jwt is empty', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ code: ErrorCode.InvalidRequest, message: expect.stringContaining('CACHLY_JWT env var not set') }),
+    );
+  });
+
+  it('throws with setup URL when jwt is missing', () => {
+    expect(() => checkJwt('')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('throws InvalidRequest with expiry timestamp for an expired token', () => {
+    const expSec = nowSec() - 60;
+    const token  = makeJwt({ exp: expSec });
+    expect(() => checkJwt(token)).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('expired at'),
+      }),
+    );
+  });
+
+  it('does not throw for a valid non-expired token', () => {
+    expect(() => checkJwt(makeJwt({ exp: nowSec() + 3600 }))).not.toThrow();
+  });
+
+  it('does not throw for a token with no exp claim', () => {
+    expect(() => checkJwt(makeJwt({ sub: 'user' }))).not.toThrow();
+  });
+});
+
+describe('handleApiError', () => {
+  it('throws InvalidRequest for 401 with the detail message', () => {
+    expect(() => handleApiError(401, 'token expired')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Authentication failed (401): token expired'),
+      }),
+    );
+  });
+
+  it('throws InvalidRequest for 403 with the detail message', () => {
+    expect(() => handleApiError(403, 'plan limit reached')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InvalidRequest,
+        message: expect.stringContaining('Access denied (403): plan limit reached'),
+      }),
+    );
+  });
+
+  it('throws InternalError for other status codes', () => {
+    expect(() => handleApiError(500, 'server crash')).toThrowError(
+      expect.objectContaining({
+        code: ErrorCode.InternalError,
+        message: expect.stringContaining('cachly API error 500: server crash'),
+      }),
+    );
+  });
+
+  it('includes the cachly.dev/setup-ai link for 401 errors', () => {
+    expect(() => handleApiError(401, 'Unauthorized')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('cachly.dev/setup-ai') }),
+    );
+  });
+
+  it('includes account access hint for 403 errors', () => {
+    expect(() => handleApiError(403, 'Forbidden')).toThrowError(
+      expect.objectContaining({ message: expect.stringContaining('access to this resource') }),
+    );
+  });
+});

package/src/__tests__/e2e/api-auth.test.ts

@@ -0,0 +1,182 @@
+/**
+ * E2E: Authenticated API endpoints
+ *
+ * Requires: E2E_JWT, E2E_INSTANCE_ID
+ * Run: npx vitest run src/__tests__/e2e/api-auth.test.ts
+ */
+
+import { describe, it, expect, beforeAll } from 'vitest';
+import { cfg, requireAuth, apiGet, apiPost } from './config.js';
+
+beforeAll(() => requireAuth());
+
+describe('Auth guard', () => {
+  it('GET /api/v1/instances without token returns 401', async () => {
+    const { status } = await apiGet('/api/v1/instances', '');
+    expect(status).toBe(401);
+  });
+
+  it('GET /api/v1/instances with invalid token returns 401', async () => {
+    const { status } = await apiGet('/api/v1/instances', 'not-a-real-token');
+    expect(status).toBe(401);
+  });
+
+  it('GET /api/v1/instances with valid token returns 200', async () => {
+    const { status } = await apiGet('/api/v1/instances');
+    expect(status).toBe(200);
+  });
+});
+
+describe('Instances API', () => {
+  // API returns { data: Instance[], count: number }
+  it('returns object with data array', async () => {
+    const { body } = await apiGet('/api/v1/instances');
+    const b = body as { data?: unknown[]; count?: number };
+    expect(Array.isArray(b.data)).toBe(true);
+    expect(typeof b.count).toBe('number');
+  });
+
+  it('each instance has required fields', async () => {
+    const { body } = await apiGet('/api/v1/instances');
+    const instances = ((body as { data?: Record<string, unknown>[] }).data) ?? [];
+    if (instances.length === 0) return; // fresh account — skip
+    for (const inst of instances) {
+      expect(typeof inst.id).toBe('string');
+      expect(typeof inst.name).toBe('string');
+      expect(typeof inst.status).toBe('string');
+      expect(typeof inst.tier).toBe('string');
+    }
+  });
+
+  it('test instance is present and running', async () => {
+    const { body } = await apiGet('/api/v1/instances');
+    const instances = ((body as { data?: Record<string, unknown>[] }).data) ?? [];
+    const found = instances.find((i) => i.id === cfg.instanceId);
+    expect(found).toBeDefined();
+    expect(found!.status).toBe('running');
+  });
+});
+
+describe('Single instance GET', () => {
+  it('returns 200 for test instance', async () => {
+    const { status } = await apiGet(`/api/v1/instances/${cfg.instanceId}`);
+    expect(status).toBe(200);
+  });
+
+  it('returns 404 for non-existent instance', async () => {
+    const { status } = await apiGet('/api/v1/instances/00000000-0000-0000-0000-000000000000');
+    expect([403, 404]).toContain(status);
+  });
+
+  it('instance body has id, status running, tier, name', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}`);
+    const inst = body as Record<string, unknown>;
+    expect(inst.id).toBe(cfg.instanceId);
+    expect(inst.status).toBe('running');
+    expect(typeof inst.tier).toBe('string');
+    expect(typeof inst.name).toBe('string');
+  });
+});
+
+describe('Connection endpoint', () => {
+  it('returns 200 with connection details for running instance', async () => {
+    const { status, body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+    expect(status).toBe(200);
+    const conn = body as Record<string, unknown>;
+    expect(typeof conn.host).toBe('string');
+    expect(typeof conn.port).toBe('number');
+    expect(typeof conn.password).toBe('string');
+    expect((conn.host as string).length).toBeGreaterThan(3);
+  });
+
+  it('connection host is not localhost (prod/dev has real host)', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+    const conn = body as Record<string, unknown>;
+    expect(String(conn.host)).not.toBe('localhost');
+    expect(String(conn.host)).not.toBe('127.0.0.1');
+  });
+
+  it('port is within valid Redis range', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/connection`);
+    const conn = body as Record<string, unknown>;
+    expect(Number(conn.port)).toBeGreaterThan(1023);
+    expect(Number(conn.port)).toBeLessThan(65536);
+  });
+});
+
+describe('API keys', () => {
+  // API returns { keys: APIKey[], count: number }
+  it('GET /api/v1/api-keys returns 200 with keys array', async () => {
+    const { status, body } = await apiGet('/api/v1/api-keys');
+    expect(status).toBe(200);
+    const b = body as { keys?: unknown[]; count?: number };
+    expect(Array.isArray(b.keys)).toBe(true);
+  });
+
+  it('api-keys have id and instance_id fields', async () => {
+    const { body } = await apiGet('/api/v1/api-keys');
+    const keys = ((body as { keys?: Record<string, unknown>[] }).keys) ?? [];
+    if (keys.length === 0) return;
+    for (const k of keys) {
+      expect(typeof k.id).toBe('string');
+      expect(typeof k.instance_id).toBe('string');
+    }
+  });
+});
+
+describe('Brain Stats endpoint', () => {
+  it('GET /api/v1/instances/:id/brain-stats returns 200', async () => {
+    const { status } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    expect(status).toBe(200);
+  });
+
+  it('brain-stats body has brain_level and brain_level_name', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    const stats = body as Record<string, unknown>;
+    expect(typeof stats.brain_level).toBe('number');
+    expect(stats.brain_level).toBeGreaterThanOrEqual(1);
+    expect(typeof stats.brain_level_name).toBe('string');
+    expect(['Apprentice', 'Explorer', 'Expert', 'Architect', 'Oracle']).toContain(stats.brain_level_name);
+  });
+
+  it('brain-stats has hours_saved and brain_recall_count', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    const stats = body as Record<string, unknown>;
+    expect(typeof stats.hours_saved).toBe('number');
+    expect(stats.hours_saved).toBeGreaterThanOrEqual(0);
+    expect(typeof stats.brain_recall_count).toBe('number');
+    expect(stats.brain_recall_count).toBeGreaterThanOrEqual(0);
+  });
+
+  it('brain-stats has standard search telemetry fields', async () => {
+    const { body } = await apiGet(`/api/v1/instances/${cfg.instanceId}/brain-stats`);
+    const stats = body as Record<string, unknown>;
+    expect(typeof stats.total_searches).toBe('number');
+    expect(typeof stats.avg_latency_ms).toBe('number');
+    expect(Array.isArray(stats.top_queries)).toBe(true);
+  });
+});
+
+describe('Provisioning status messages', () => {
+  it('non-existent instance connection returns 4xx, never 500', async () => {
+    const { status } = await apiGet('/api/v1/instances/00000000-0000-0000-0000-000000000001/connection');
+    expect([400, 403, 404, 422]).toContain(status);
+  });
+});
+
+describe('Auto-provision endpoint', () => {
+  it('POST /api/v1/instances/auto returns 200 or 201', async () => {
+    const { status } = await apiPost('/api/v1/instances/auto', {});
+    expect([200, 201]).toContain(status);
+  });
+
+  it('returns existing running instance without creating a new one', async () => {
+    const { body } = await apiPost('/api/v1/instances/auto', {});
+    const b = body as { instance?: { id: string; status: string }; created?: boolean };
+    if (b.instance) {
+      // Existing instance returned
+      expect(typeof b.instance.id).toBe('string');
+      expect(b.created).toBe(false);
+    }
+  });
+});