@minhpnq1807/contextos 0.6.7 → 0.6.8

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.6.8
+
+- **Fallback context recovery:** Prompt-hook direct fallback now keeps ContextOS useful when `ctx-mcp` is unavailable by using indexed file text matches and lightweight evidence-based skill scoring instead of returning only workflows or an empty context.
+- **MCP bridge hardening:** Increased default bridge/connect timeouts, added `ctx health`, added bounded ctx-mcp daemon auto-start when the private socket is missing, and records retrieval mode in runtime telemetry/debug output.
+- **Agent-callable read-only MCP tools:** Added safe MCP tools for `ctx debug`, `ctx doctor`, `ctx skills doctor`, `ctx report`, `ctx evidence`, and `ctx stats` so agents can inspect ContextOS state without shelling out or exposing setup/install/sync write commands.
+
 ## 0.6.7
 
 - **MCP proxy test stability:** Fixed the MCP proxy telemetry smoke test so it waits for the telemetry file before reading it and uses a stable stdin/stdout echo child. This removes the CI race where `telemetry.jsonl` could be read before it existed.

package/README.md

@@ -391,6 +391,21 @@ Hook lightweight fallback: 0.69s
 MCP embedding hot startup: 477ms
 ```
 
+Agents can call read-only ContextOS MCP tools directly:
+
+```text
+ctx_health
+ctx_score_context
+ctx_debug_context
+ctx_doctor_repo
+ctx_skills_doctor
+ctx_report_last_task
+ctx_evidence_last_task
+ctx_stats_workspace
+```
+
+Write commands such as `ctx setup`, `ctx install`, `ctx refresh`, and `ctx sync` are not exposed as MCP tools by default.
+
 During install, ContextOS prints a 0-100 progress indicator. The longest stage is usually embedding warmup; if the model is already cached, install skips the download and only refreshes vectors.
 
 Verify the published package in any project:
@@ -591,6 +606,7 @@ This warning comes from a transitive dependency in the local embedding/WASM stac
 | `ctx setup --no-skills` | Skips skillshare sync during setup. | You do not want shared skills configured. | Does not run `ctx sync --skills`. |
 | `ctx setup --quiet` | Runs setup in measurement-only mode. | You want reports/stats without visible injected prompt context. | Installs hooks with prompt context injection disabled. |
 | `ctx debug -- "task"` | Runs the scheduler locally for a fake prompt. | You want to see which AGENTS.md rules and files ContextOS would inject before using Codex. | Prints rule scores, scoring reasons, suggested files, and final `additionalContext`. |
+| `ctx health` | Checks local ctx-mcp bridge/model/index readiness. | Hooks are falling back or suggestions look stale. | Prints bridge connection, model hot status, and whether local indexes exist. |
 | `ctx doctor` | Scores repository ContextOS readiness. | You want to add or verify a `ContextOS Ready` badge. | Prints Rules, Skills, Workflows, Overall tier, evidence, and next recommendations. |
 | `ctx doctor --fix` | Generates starter ContextOS project context. | `ctx doctor` says skills/workflows are missing and you want explicit local scaffolding. | Detects package/config evidence, creates up to three shared project skills plus `.agents/workflows/primary.md`, then prints the updated readiness score. |
 | `ctx report` | Shows the last Stop-hook compliance report for the current workspace. | An agent task has finished and you want the summary again. | Prints sectioned tables for summary, rule outcomes, suggested files, and runtime telemetry from `~/.ctx/contextos/workspaces/<workspace-id>/last-report.json`. |
@@ -696,6 +712,8 @@ Prompt-time file suggestions do not walk the repository. `ctx install` and `ctx
 
 If a prompt has no usable context candidates, the hook fails open without emitting an empty `hook context` block, records `emptyContextReason` in the workspace runtime file, and starts a detached `autowarm` rebuild with a cooldown. That background rebuild refreshes prepared indexes for the next prompt while keeping repository walking out of the current prompt path.
 
+If hooks fall back because `ctx-mcp` is unavailable or not hot yet, ContextOS still uses indexed text matches for files and lightweight evidence scoring for skills. It does not cold-load embeddings inside the prompt hook. Run `ctx debug -- "task"` to inspect retrieval mode, including bridge status, embedding status, file fallback, and skill fallback.
+
 Use `ctx --config` to choose which prompt sections ContextOS injects and how many suggestions each section may show. Interactive `ctx setup` includes the same section picker and limit prompts, while `ctx setup --yes` keeps the current saved config for automation. The panel supports multiple selection with `Space` and persists the global choice in `~/.ctx/contextos/output-config.json`. Defaults are five suggested files, five skills, and five workflows; caps are 20 files, 10 skills, and 5 workflows. Disabling rules hides both critical and additional relevant rule sections; compliance metadata remains available for reports.
 
 Injected prompt sections are intentionally compact: rules show only detected rule text, files show a comma-separated inline list of basenames without paths, skills show unique `$skill-name` activations as a comma-separated inline list without descriptions, and workflows show names with their agent chain. Stop hooks persist reports silently; run `ctx report` or `ctx evidence` when you want the detailed compliance output.
@@ -777,8 +795,10 @@ CONTEXTOS_GRAPH_RETRIEVAL=0       disable graph-backed file retrieval
 CONTEXTOS_GRAPH_TIMEOUT_MS=80     graph lookup timeout
 CONTEXTOS_CRG_PYTHON=/path/python Python with code_review_graph installed
 CONTEXTOS_EMBEDDINGS=0            disable embedding rule scoring
-CONTEXTOS_MCP_CONNECT_TIMEOUT_MS=100 stale ctx-mcp socket connect timeout
-CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS=2000 ctx-mcp hook bridge timeout
+CONTEXTOS_MCP_CONNECT_TIMEOUT_MS=500 stale ctx-mcp socket connect timeout
+CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS=5000 ctx-mcp hook bridge timeout
+CONTEXTOS_MCP_AUTOSTART=1        auto-start ctx-mcp daemon when the private bridge socket is missing
+CONTEXTOS_MCP_AUTOSTART_WAIT_MS=1500 max hook wait for auto-started ctx-mcp before fallback
 CONTEXTOS_HOOK_DEADLINE_MS=8500 hard fail-open deadline for prompt hooks
 CONTEXTOS_DIRECT_FALLBACK_TIMEOUT_MS=2500 direct scoring timeout when the bridge is unavailable
 CONTEXTOS_HOOK_EMBEDDING_TIMEOUT_MS=500 rule embedding timeout during hook direct fallback
@@ -795,6 +815,7 @@ CONTEXTOS_FILE_EMBEDDING_TIMEOUT_MS=1000 file-path embedding retrieval timeout
 ```text
 Codex prompt
   -> UserPromptSubmit hook
+  -> auto-start ctx-mcp daemon if the private bridge socket is missing
   -> call ctx-mcp through private bridge
   -> ctx-mcp scores rules and relevant files
   -> write last-prompt-context.json

package/bin/ctx.js

@@ -41,10 +41,11 @@ import { configureOutputSections, enabledOutputSectionsLabel, loadOutputConfig,
 import { syncWorkflows, warmWorkflowEmbeddings } from "../plugins/ctx/lib/workflow-discoverer.js";
 import { checkForUpdate } from "../plugins/ctx/lib/update-notifier.js";
 import { fetchSkillsForAgents, printSkillRecommendations, getAllLibraries, getInstallCommands } from "../plugins/ctx/lib/skill-library.js";
-import { invalidateCtxMcpSocket } from "../plugins/ctx/lib/ctx-mcp-client.js";
+import { callCtxHealth, ctxMcpSocketPath, invalidateCtxMcpSocket } from "../plugins/ctx/lib/ctx-mcp-client.js";
 import { runPrefixedCommand } from "../plugins/ctx/lib/shell-runner.js";
 import { formatContextOSReady, inspectContextOSReady } from "../plugins/ctx/lib/certification.js";
 import { formatProjectContextGeneration, generateProjectContext } from "../plugins/ctx/lib/project-context-generator.js";
+import { retrievalMode } from "../plugins/ctx/lib/prompt-hook.js";
 
 /**
  * Run a shell command with all output lines prefixed by │  
@@ -195,6 +196,7 @@ Usage:
   ctx setup --no-skills                             Skip skill sync
   ctx setup --quiet                                 Quiet mode (minimal output)
   ctx debug -- "task"                               Debug a task with ContextOS tracing
+  ctx health                                        Show ctx-mcp bridge/model/index health
   ctx doctor                                       Score repository ContextOS readiness
   ctx doctor --fix                                 Generate starter project skills/workflow
   ctx doctor --fix --force                         Regenerate starter project context files
@@ -640,6 +642,7 @@ async function debug(task) {
   console.log(`workspace marker: ${workspaceMarkerPath(cwd)}`);
   console.log(`rules: ${rules.length}`);
   console.log(`mcp scorer: ${scored.telemetry.modelStatus}${scored.telemetry.model ? ` (${scored.telemetry.model})` : ""}`);
+  printRetrievalMode(retrievalMode(scored.telemetry || {}));
   console.log(`elapsed: ${scored.telemetry.elapsedMs}ms`);
   console.log("");
   for (const rule of rules.slice(0, 20)) {
@@ -677,6 +680,45 @@ async function debug(task) {
   console.log(scheduled.additionalContext || "(empty)");
 }
 
+async function health() {
+  const dataDir = contextOSDataDir();
+  const socketPath = ctxMcpSocketPath(dataDir);
+  const socketPresent = fs.existsSync(socketPath);
+  let bridgeConnected = false;
+  let bridgeHealth = {};
+  let bridgeError = null;
+  try {
+    bridgeHealth = await callCtxHealth({
+      dataDir,
+      timeoutMs: Number(process.env.CONTEXTOS_MCP_HEALTH_TIMEOUT_MS || 500),
+      connectTimeoutMs: Number(process.env.CONTEXTOS_MCP_CONNECT_TIMEOUT_MS || 500)
+    });
+    bridgeConnected = true;
+  } catch (error) {
+    bridgeError = error?.message || String(error);
+  }
+
+  const indexesReady = fs.existsSync(path.join(dataDir, "embeddings.db"));
+  const modelHot = Boolean(bridgeHealth.embedding_pipeline_loaded);
+  console.log("ContextOS health");
+  console.log(`ctx-mcp: ${socketPresent ? "running" : "not running"}`);
+  console.log(`bridge: ${bridgeConnected ? "connected" : "disconnected"}`);
+  console.log(`embedding_pipeline_loaded: ${Boolean(bridgeHealth.embedding_pipeline_loaded)}`);
+  console.log(`model_hot: ${modelHot}`);
+  console.log(`indexes_ready: ${indexesReady}`);
+  if (bridgeHealth.preload_status) console.log(`preload_status: ${bridgeHealth.preload_status}`);
+  if (bridgeHealth.loaded_at) console.log(`loaded_at: ${new Date(bridgeHealth.loaded_at).toISOString()}`);
+  if (bridgeHealth.error || bridgeError) console.log(`error: ${bridgeHealth.error || bridgeError}`);
+}
+
+function printRetrievalMode(mode = {}) {
+  console.log("retrieval mode:");
+  console.log(`- bridge: ${mode.bridge || "mcp"}${mode.bridgeError ? ` (${mode.bridgeError})` : ""}`);
+  console.log(`- embedding: ${mode.embedding || "enabled"}`);
+  console.log(`- file fallback: ${mode.fileFallback || "none"}`);
+  console.log(`- skill fallback: ${mode.skillFallback || "none"}`);
+}
+
 async function skillsDoctor(task) {
   if (!String(task || "").trim()) throw new Error('Usage: ctx skills doctor -- "task"');
   const result = await diagnoseSkills({
@@ -1048,6 +1090,8 @@ try {
     const task = marker >= 0 ? args.slice(marker + 1).join(" ") : args.slice(1).join(" ");
     if (!task.trim()) throw new Error('Usage: ctx debug -- "task"');
     await debug(task);
+  } else if (command === "health") {
+    await health();
   } else if (command === "doctor") {
     if (args.includes("--fix")) {
       const generated = generateProjectContext({ cwd: process.cwd(), force: args.includes("--force") });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minhpnq1807/contextos",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "Task-aware AGENTS.md context injection and compliance reporting for Codex, Claude Code, and Antigravity.",
   "type": "module",
   "bin": {

package/plugins/ctx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx",
-  "version": "0.6.7",
+  "version": "0.6.8",
   "description": "Inject task-relevant AGENTS.md rules into Codex through plugin hooks.",
   "author": {
     "name": "ContextOS"

package/plugins/ctx/lib/analyzer.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { findGraphRelevantFiles, mergeRelevantFiles } from "./graph-retriever.js";
 import { expandImportGraph } from "./import-graph.js";
-import { findEmbeddingRelevantFiles } from "./file-embedding-retriever.js";
+import { findEmbeddingRelevantFiles, findIndexedFileTextMatches } from "./file-embedding-retriever.js";
 import { workspacePackagePaths } from "./project-profiler.js";
 
 const STOP_WORDS = new Set([
@@ -280,7 +280,8 @@ export async function findRelevantFiles({
   limit = 3,
   embeddingFileFinder = findEmbeddingRelevantFiles,
   fileEmbeddingTimeoutMs,
-  fileEmbeddingOptions = {}
+  fileEmbeddingOptions = {},
+  indexedFileTextFinder = findIndexedFileTextMatches
 } = {}) {
   if (!String(task || "").trim()) return [];
 
@@ -295,13 +296,21 @@ export async function findRelevantFiles({
     embeddingOptions: fileEmbeddingOptions,
     limit: Math.max(limit * 2, 6)
   });
+  const indexedTextFiles = fileEmbeddingOptions?.enabled === false
+    ? await indexedFileTextFinder({
+      cwd,
+      task: retrievalTask,
+      dataDir,
+      limit: Math.max(limit * 2, 6)
+    })
+    : [];
   const importGraphFiles = expandImportGraph({
     cwd,
-    seedFiles: [...explicitFiles, ...manifestFiles, ...embeddingFiles].slice(0, limit),
+    seedFiles: [...explicitFiles, ...manifestFiles, ...embeddingFiles, ...indexedTextFiles].slice(0, limit),
     dataDir,
     limit: Math.max(limit * 2, 6)
   });
-  const seedFiles = mergeLocalFileCandidates([...explicitFiles, ...manifestFiles, ...embeddingFiles, ...importGraphFiles])
+  const seedFiles = mergeLocalFileCandidates([...explicitFiles, ...manifestFiles, ...embeddingFiles, ...indexedTextFiles, ...importGraphFiles])
     .slice(0, Math.max(limit * 3, 9));
 
   const graphFiles = findGraphRelevantFiles({

package/plugins/ctx/lib/ctx-mcp-client.js

@@ -1,11 +1,13 @@
 import fs from "node:fs";
 import net from "node:net";
 import path from "node:path";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 import { defaultDataRoot } from "./workspace-data.js";
 
-const DEFAULT_TIMEOUT_MS = 2000;
-const DEFAULT_CONNECT_TIMEOUT_MS = 100;
+const DEFAULT_TIMEOUT_MS = 5000;
+const DEFAULT_CONNECT_TIMEOUT_MS = 500;
 export const CTX_MCP_BRIDGE_REVISION = 2;
 
 export function ctxMcpSocketPath(dataDir = defaultDataDir()) {
@@ -42,6 +44,50 @@ export async function callCtxHealth({
   return response.health || {};
 }
 
+export async function ensureCtxMcpDaemon({
+  dataDir = defaultDataDir(),
+  waitMs = Number(process.env.CONTEXTOS_MCP_AUTOSTART_WAIT_MS || 1500),
+  enabled = process.env.CONTEXTOS_MCP_AUTOSTART !== "0",
+  socketPath = ctxMcpSocketPath(dataDir),
+  spawnProcess = spawn,
+  healthClient = callCtxHealth
+} = {}) {
+  if (!enabled) return { started: false, status: "disabled" };
+  if (fs.existsSync(socketPath)) return { started: false, status: "socket-present" };
+
+  const serverPath = fileURLToPath(new URL("../mcp/server.js", import.meta.url));
+  const child = spawnProcess(process.execPath, [serverPath], {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      CONTEXTOS_MCP_DAEMON: "1"
+    }
+  });
+  child.unref?.();
+
+  const deadline = Date.now() + Math.max(0, waitMs);
+  let lastError = null;
+  while (Date.now() <= deadline) {
+    try {
+      const health = await healthClient({
+        dataDir,
+        timeoutMs: Math.min(250, Math.max(50, waitMs)),
+        connectTimeoutMs: Math.min(DEFAULT_CONNECT_TIMEOUT_MS, Math.max(50, waitMs))
+      });
+      return { started: true, status: "ready", health };
+    } catch (error) {
+      lastError = error;
+      await sleep(100);
+    }
+  }
+  return {
+    started: true,
+    status: "timeout",
+    error: lastError?.message || String(lastError || "ctx-mcp daemon did not become ready")
+  };
+}
+
 async function callBridge(payload, {
   dataDir,
   timeoutMs,
@@ -121,3 +167,7 @@ function statIdentity(filePath) {
 function defaultDataDir() {
   return defaultDataRoot();
 }
+
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/plugins/ctx/lib/embedding-scorer.js

@@ -108,6 +108,29 @@ export async function searchIndexedEmbeddings({
   }
 }
 
+export async function listIndexedEmbeddingItems({
+  kind,
+  dataDir = defaultDataRoot()
+} = {}) {
+  if (!kind) return { items: [], status: "disabled" };
+  const cachePath = path.join(dataDir, "embeddings.db");
+  if (!fs.existsSync(cachePath)) return { items: [], status: "cold-cache", cachePath };
+  let cache;
+  try {
+    cache = await openEmbeddingCache(dataDir);
+    const items = cache.listIndexed(kind).map(({ id, text }) => ({ id, text }));
+    cache.close();
+    return { items, status: "enabled", cachePath };
+  } catch (error) {
+    try {
+      cache?.close();
+    } catch {
+      // best-effort close while reporting fallback status
+    }
+    return { items: [], status: "fallback", error: error?.message || String(error), cachePath };
+  }
+}
+
 export async function warmIndexedEmbeddings({
   kind,
   items = [],

package/plugins/ctx/lib/file-embedding-retriever.js

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
-import { isModelCacheReady, searchIndexedEmbeddings, warmIndexedEmbeddings } from "./embedding-scorer.js";
+import { isModelCacheReady, listIndexedEmbeddingItems, searchIndexedEmbeddings, warmIndexedEmbeddings } from "./embedding-scorer.js";
 import { rebuildImportGraphIndex } from "./import-graph.js";
 
 const SOURCE_EXTENSIONS = new Set([
@@ -49,6 +49,37 @@ export async function findEmbeddingRelevantFiles({
     }));
 }
 
+export async function findIndexedFileTextMatches({
+  cwd = process.cwd(),
+  task = "",
+  dataDir,
+  limit = 10,
+  indexedLister = listIndexedEmbeddingItems
+} = {}) {
+  if (!dataDir || !String(task || "").trim()) return [];
+  const result = await indexedLister({ kind: fileIndexKind(cwd), dataDir });
+  if (result.status !== "enabled" || !result.items.length) return [];
+  const queryTokens = meaningfulTokens(task);
+  if (!queryTokens.length) return [];
+  return result.items
+    .map((item) => {
+      const haystack = `${item.id || ""} ${item.text || ""}`.toLowerCase();
+      const matches = queryTokens.filter((token) => haystack.includes(token));
+      const basename = path.basename(String(item.id || "")).toLowerCase();
+      const basenameMatches = queryTokens.filter((token) => basename.includes(token));
+      const score = matches.length * 4 + basenameMatches.length * 3;
+      return {
+        path: item.id,
+        score,
+        source: "indexed-file-text",
+        reasons: matches.length ? [`indexed-file-text:${matches.slice(0, 5).join(",")}`] : []
+      };
+    })
+    .filter((item) => item.path && item.score > 0)
+    .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path))
+    .slice(0, limit);
+}
+
 export async function warmFileEmbeddings({
   cwd = process.cwd(),
   dataDir,
@@ -74,6 +105,17 @@ function fileIndexKind(cwd) {
   return `file:${path.resolve(cwd)}`;
 }
 
+function meaningfulTokens(value) {
+  const stop = new Set(["the", "and", "for", "with", "this", "that", "task", "implement", "create", "update", "fix", "can", "not", "see", "any", "why", "allways", "always", "app", "src", "page"]);
+  return [...new Set(String(value || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9/._-]+/g, " ")
+    .split(/\s+/)
+    .flatMap((token) => token.split(/[\\/._-]+/))
+    .map((token) => token.trim())
+    .filter((token) => token.length >= 3 && !stop.has(token)))];
+}
+
 function listSourceFiles(cwd, { maxFiles }) {
   const files = [];
   walkFiles(cwd, (filePath) => {

package/plugins/ctx/lib/prompt-hook.js

@@ -1,7 +1,7 @@
 import { scheduleContext } from "./scheduler.js";
 import { appendJsonLine, writeJsonFile } from "./fs-utils.js";
 import { maybeAutoWarmWorkspace } from "./auto-warm.js";
-import { callCtxHealth, callCtxScoreContext } from "./ctx-mcp-client.js";
+import { callCtxHealth, callCtxScoreContext, ensureCtxMcpDaemon } from "./ctx-mcp-client.js";
 import { resolveHookCwd } from "./hook-io.js";
 import { loadOutputConfig, outputConfigLimits } from "./output-config.js";
 import { scoreContext as scoreContextDirect } from "./score-context.js";
@@ -18,6 +18,7 @@ export async function handlePromptPayload(
     injectContext = process.env.CONTEXTOS_INJECT !== "0",
     scoreContextClient = callCtxScoreContext,
     healthContextClient = callCtxHealth,
+    ensureMcpDaemonClient = ensureCtxMcpDaemon,
     scoreContextDirectClient = scoreContextDirect,
     autoWarmWorkspace = maybeAutoWarmWorkspace,
     mcpDataDir,
@@ -35,8 +36,13 @@ export async function handlePromptPayload(
   const promptLimits = outputConfigLimits(effectiveOutputConfig);
 
   let scored;
+  let mcpDaemon = null;
   try {
     if (requireHotMcp) {
+      mcpDaemon = await ensureMcpDaemonClient({
+        dataDir: mcpDataDir || dataDir,
+        waitMs: Number(process.env.CONTEXTOS_MCP_AUTOSTART_WAIT_MS || 1500)
+      });
       const health = await healthContextClient({
         dataDir: mcpDataDir || dataDir,
         timeoutMs: Number(process.env.CONTEXTOS_MCP_HEALTH_TIMEOUT_MS || 250)
@@ -54,7 +60,7 @@ export async function handlePromptPayload(
       maxWorkflows: promptLimits.workflows
     }, {
       dataDir: mcpDataDir || dataDir,
-      timeoutMs: Number(process.env.CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS || 2000)
+      timeoutMs: Number(process.env.CONTEXTOS_MCP_BRIDGE_TIMEOUT_MS || 5000)
     });
   } catch (error) {
     try {
@@ -74,13 +80,15 @@ export async function handlePromptPayload(
       scored.telemetry = {
         ...(scored.telemetry || {}),
         bridgeStatus: "fallback",
-        bridgeError: error?.message || String(error)
+        bridgeError: error?.message || String(error),
+        mcpDaemon
       };
     } catch (directError) {
       scored = emptyScore({
         bridgeStatus: "fallback-failed",
         bridgeError: error?.message || String(error),
-        directFallbackError: directError?.message || String(directError)
+        directFallbackError: directError?.message || String(directError),
+        mcpDaemon
       });
     }
   }
@@ -114,6 +122,7 @@ export async function handlePromptPayload(
     suggestedWorkflows,
     telemetry: {
       ...(scored.telemetry || {}),
+      retrievalMode: retrievalMode(scored.telemetry || {}),
       rulesInjected: (scheduled.highRules?.length || 0) + (scheduled.midRules?.length || 0),
       filesSuggested: relevantFiles.length,
       skillsSuggested: suggestedSkills.length,
@@ -235,6 +244,19 @@ function emptyScore(telemetry = {}) {
   };
 }
 
+export function retrievalMode(telemetry = {}) {
+  const bridge = telemetry.bridgeStatus || "mcp";
+  const embedding = telemetry.modelStatus === "disabled" ? "disabled" : "enabled";
+  const fallback = bridge === "fallback" || bridge === "fallback-failed" || embedding === "disabled";
+  return {
+    bridge,
+    bridgeError: telemetry.bridgeError || null,
+    embedding,
+    fileFallback: fallback ? "indexed-text-match" : null,
+    skillFallback: fallback ? "lightweight-evidence-score" : null
+  };
+}
+
 function withTimeout(promise, timeoutMs, label) {
   if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) return promise;
   let timer;

package/plugins/ctx/lib/skill-discoverer.js

@@ -217,7 +217,12 @@ export async function suggestSkills({
   const byId = new Map(catalog.map((skill) => [skillIndexId(skill), skill]));
   const explicitSkills = explicitSkillSuggestions({ prompt, byId });
   const projectEvidence = detectProjectEvidence({ cwd });
-  if (!embeddingsEnabled) return finalizeSkillScores(explicitSkills, limit, { cwd, prompt, projectEvidence });
+  if (!embeddingsEnabled) {
+    return finalizeSkillScores([
+      ...explicitSkills,
+      ...lightweightSkillSuggestions({ catalog, prompt, projectEvidence })
+    ], limit, { cwd, prompt, projectEvidence });
+  }
 
   if (dataDir) {
     const indexed = await searchSkillIndexes({ cwd, query, dataDir, timeoutMs, indexedSearcher });
@@ -264,6 +269,63 @@ function explicitSkillSuggestions({ prompt = "", byId = new Map() } = {}) {
     .map(({ skill, index }) => skillScoreFromEmbedding(skill, 1 - index * 0.0001, ["explicit-skill"]));
 }
 
+function lightweightSkillSuggestions({ catalog = [], prompt = "", projectEvidence = {} } = {}) {
+  const promptTokens = new Set(meaningfulSkillTokens(prompt));
+  if (!promptTokens.size) return [];
+
+  return catalog
+    .map((skill) => {
+      const enriched = skill.searchTokens ? skill : enrichSkill(skill);
+      const metadata = enriched.metadata || inferSkillMetadata(enriched);
+      const promptMatch = matchTextTriggers(prompt, metadata.positivePrompts);
+      const dependencyEvidence = matchList(projectEvidence.dependencies, metadata.dependencies);
+      const fileEvidence = matchFiles(projectEvidence.files, metadata.files);
+      const negativeDependencies = matchList(projectEvidence.dependencies, metadata.negativeDependencies);
+      const negativeFiles = matchFiles(projectEvidence.files, metadata.negativeFiles);
+      const negativePrompts = matchTextTriggers(prompt, metadata.negativePrompts);
+      const negativePenalty = Math.max(negativeDependencies.score, negativeFiles.score, negativePrompts.score);
+      const nameMatches = meaningfulSkillTokens(enriched.name).filter((token) => promptTokens.has(token));
+      const tokenMatches = meaningfulSkillTokens(`${enriched.name} ${enriched.description}`).filter((token) => promptTokens.has(token));
+      const hasRouterEvidence = Boolean(
+        promptMatch.matches.length
+        || dependencyEvidence.matches.length
+        || fileEvidence.matches.length
+      );
+      const genericPromptOnly = promptMatch.matches.length > 0
+        && promptMatch.matches.every((item) => genericPromptTrigger(normalize(item)))
+        && !nameMatches.length
+        && !tokenMatches.length
+        && !dependencyEvidence.matches.length
+        && !fileEvidence.matches.length;
+      if (!hasRouterEvidence && !nameMatches.length && tokenMatches.length < 2) return null;
+      if (genericPromptOnly) return null;
+
+      const ecosystemPenalty = irrelevantEcosystemPenalty(enriched, { promptTokens, projectEvidence });
+      const lexicalScore = Math.min(1,
+        nameMatches.length * 0.20
+        + Math.min(tokenMatches.length, 5) * 0.08
+        + promptMatch.score * 0.45
+        + dependencyEvidence.score * 0.20
+        + fileEvidence.score * 0.12
+        + skillSourceBoostScore(enriched) * 0.03
+        - negativePenalty * 0.25
+        - ecosystemPenalty
+      );
+      if (lexicalScore < 0.35) return null;
+
+      const reasons = [
+        `lightweight:${lexicalScore.toFixed(2)}`,
+        ...nameMatches.slice(0, 3).map((item) => `name:${item}`),
+        ...tokenMatches.slice(0, 5).map((item) => `token:${item}`)
+      ];
+      return skillScoreFromEmbedding(enriched, lexicalScore, reasons);
+    })
+    .filter(Boolean)
+    .sort((a, b) => Number(b.embeddingScore || 0) - Number(a.embeddingScore || 0)
+      || scopePriority(b.scope) - scopePriority(a.scope)
+      || a.name.localeCompare(b.name));
+}
+
 function extractExplicitSkillNames(prompt = "") {
   const names = [];
   const seen = new Set();
@@ -557,7 +619,7 @@ function inferSkillMetadata(skill = {}) {
     metadata.dependencies.push("react");
     metadata.positivePrompts.push("frontend", "ui", "component", "page", "layout", "button", "modal");
   }
-  if (/\b(forum|topic|community|chat|message|realtime|websocket|socket|conversation)\b/.test(text)) {
+  if (/\b(forum|chat|realtime|websocket|socket)\b/.test(text)) {
     metadata.positivePrompts.push("forum", "topic", "new topic", "trending", "chat", "chatting", "message", "realtime", "websocket");
     metadata.files.push("package.json", "webapp/package.json", "services/*/package.json");
     metadata.dependencies.push("next", "react", "socket.io", "ws", "@nestjs/websockets");
@@ -710,6 +772,43 @@ function isAmbiguousPrompt(prompt = "") {
   return tokens.length <= 4 && tokens.every((token) => generic.has(token));
 }
 
+function meaningfulSkillTokens(value) {
+  const stop = new Set([
+    "the", "and", "for", "with", "this", "that", "from", "into", "using", "use",
+    "task", "create", "update", "implement", "build", "fix", "debug", "page",
+    "app", "src", "file", "files", "skill", "skills", "suggested", "suggest", "new"
+  ]);
+  return normalize(value)
+    .split(/\s+/)
+    .map((token) => token.trim())
+    .filter((token) => token.length > 2 && !stop.has(token));
+}
+
+function genericPromptTrigger(trigger) {
+  return new Set(["frontend", "ui", "component", "page", "layout", "button", "modal"]).has(trigger);
+}
+
+function irrelevantEcosystemPenalty(skill = {}, { promptTokens = new Set(), projectEvidence = {} } = {}) {
+  const text = normalize(`${skill.name || ""} ${skill.description || ""}`);
+  const dependencies = new Set((projectEvidence.dependencies || []).map(normalizeDependency));
+  const ecosystems = [
+    { token: "azure", deps: ["@azure", "azure"], prompts: ["azure"] },
+    { token: "aws", deps: ["aws-sdk", "@aws-sdk"], prompts: ["aws"] },
+    { token: "java", deps: ["java"], prompts: ["java"] },
+    { token: "dotnet", deps: ["dotnet", "aspnet"], prompts: ["dotnet", "csharp"] },
+    { token: "python", deps: ["python"], prompts: ["python"] },
+    { token: "angular", deps: ["@angular/core", "angular"], prompts: ["angular"] }
+  ];
+  let penalty = 0;
+  for (const ecosystem of ecosystems) {
+    if (!text.includes(ecosystem.token)) continue;
+    const promptHas = ecosystem.prompts.some((token) => promptTokens.has(token));
+    const projectHas = ecosystem.deps.some((dependency) => [...dependencies].some((value) => value.includes(dependency)));
+    if (!promptHas && !projectHas) penalty += 0.55;
+  }
+  return Math.min(0.7, penalty);
+}
+
 function detectProjectEvidence({ cwd = process.cwd() } = {}) {
   const dependencies = new Set();
   const scripts = new Set();

package/plugins/ctx/mcp/contextos-server.js

@@ -1,10 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 
 import { scoreContext } from "../lib/score-context.js";
 import { scheduleContext } from "../lib/scheduler.js";
 
-export function createContextOSMcpServer({ dataDir, getHealth = defaultHealth }) {
+const CTX_BIN = fileURLToPath(new URL("../../../bin/ctx.js", import.meta.url));
+
+export function createContextOSMcpServer({ dataDir, getHealth = defaultHealth, runCommand = runCliCommand } = {}) {
   const server = new McpServer({
     name: "ctx-mcp",
     version: "0.1.0"
@@ -107,9 +111,129 @@ export function createContextOSMcpServer({ dataDir, getHealth = defaultHealth })
     };
   });
 
+  registerCliTool(server, {
+    name: "ctx_debug_context",
+    title: "Debug ContextOS routing",
+    description: "Preview rules, files, skills, workflows, and final prompt context for a task.",
+    inputSchema: {
+      cwd: z.string().optional(),
+      prompt: z.string()
+    },
+    args: ({ prompt }) => ["debug", "--", prompt],
+    runCommand
+  });
+
+  registerCliTool(server, {
+    name: "ctx_doctor_repo",
+    title: "Inspect ContextOS repository readiness",
+    description: "Score repository ContextOS readiness without modifying files.",
+    inputSchema: {
+      cwd: z.string().optional()
+    },
+    args: () => ["doctor"],
+    runCommand
+  });
+
+  registerCliTool(server, {
+    name: "ctx_skills_doctor",
+    title: "Explain ContextOS skill routing",
+    description: "Explain which skills ContextOS would select for a prompt and why.",
+    inputSchema: {
+      cwd: z.string().optional(),
+      prompt: z.string()
+    },
+    args: ({ prompt }) => ["skills", "doctor", "--", prompt],
+    runCommand
+  });
+
+  registerCliTool(server, {
+    name: "ctx_report_last_task",
+    title: "Show last ContextOS task report",
+    description: "Read the latest local ContextOS compliance report for the workspace.",
+    inputSchema: {
+      cwd: z.string().optional()
+    },
+    args: () => ["report"],
+    runCommand
+  });
+
+  registerCliTool(server, {
+    name: "ctx_evidence_last_task",
+    title: "Show last ContextOS evidence",
+    description: "Read detailed evidence for the latest local ContextOS compliance report.",
+    inputSchema: {
+      cwd: z.string().optional()
+    },
+    args: () => ["evidence"],
+    runCommand
+  });
+
+  registerCliTool(server, {
+    name: "ctx_stats_workspace",
+    title: "Show ContextOS workspace stats",
+    description: "Summarize local ContextOS prompt, report, hook, and telemetry history.",
+    inputSchema: {
+      cwd: z.string().optional()
+    },
+    args: () => ["stats"],
+    runCommand
+  });
+
   return server;
 }
 
+function registerCliTool(server, { name, title, description, inputSchema, args, runCommand }) {
+  server.registerTool(name, {
+    title,
+    description,
+    inputSchema,
+    outputSchema: {
+      code: z.number(),
+      stdout: z.string(),
+      stderr: z.string()
+    }
+  }, async (toolArgs) => {
+    const result = await runCommand(args(toolArgs), {
+      cwd: toolArgs.cwd || process.cwd()
+    });
+    const text = result.stdout || result.stderr || `(ctx command exited with code ${result.code})`;
+    return {
+      content: [{ type: "text", text }],
+      structuredContent: result
+    };
+  });
+}
+
+function runCliCommand(args, { cwd = process.cwd(), timeoutMs = Number(process.env.CONTEXTOS_MCP_CLI_TOOL_TIMEOUT_MS || 10000) } = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(process.execPath, [CTX_BIN, ...args], {
+      cwd,
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      resolve({ code: 124, stdout, stderr: stderr || `ctx command timed out after ${timeoutMs}ms` });
+    }, timeoutMs);
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk.toString("utf8");
+    });
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      resolve({ code: 1, stdout, stderr: error?.message || String(error) });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ code: code ?? 0, stdout, stderr });
+    });
+  });
+}
+
 function defaultHealth() {
   return {
     model_cache_ready: false,

package/plugins/ctx/mcp/server.js

@@ -29,7 +29,11 @@ const keepAlive = setInterval(() => {}, 2 ** 31 - 1);
 
 const server = createContextOSMcpServer({ dataDir, getHealth: bridgeHealth });
 console.error("ctx-mcp ready");
-await server.connect(new StdioServerTransport());
+if (process.env.CONTEXTOS_MCP_DAEMON === "1") {
+  console.error("ctx-mcp daemon mode");
+} else {
+  await server.connect(new StdioServerTransport());
+}
 
 async function ensureModelReady() {
   const modelDir = modelCacheDir(dataDir);