@danielblomma/cortex-mcp 2.1.4 → 2.2.0

package/README.md

@@ -15,7 +15,7 @@
 
 ## What Cortex is
 
-Cortex is a local, repository-scoped context engine for coding assistants. It parses your source code with tree-sitter, indexes it into a structured knowledge graph of entities (files, symbols, rules, ADRs) and their relationships (calls, defines, constrains, implements, supersedes), and serves that context to AI assistants over the Model Context Protocol (MCP).
+Cortex is a local, repository-scoped context engine for coding assistants. It parses your source code with tree-sitter, indexes it into a structured knowledge graph of entities (files, symbols, rules, ADRs) and their relationships (calls, defines, constrains, implements, supersedes), and exposes that context through CLI commands. MCP remains available as a compatibility and integration bridge for clients that support it.
 
 Where a general-purpose AI assistant sees your codebase as a pile of text files, Cortex gives it a precise map: what exists, how it is connected, which rules govern it, and which parts are source-of-truth versus deprecated.
 
@@ -40,7 +40,7 @@ Cortex is not a replacement for your editor, your version control, or your codin
 - **Architectural governance.** Rules and ADRs are surfaced with every answer, so assistants follow the team's established patterns rather than generic best practices.
 - **Multi-language coverage.** A single engine indexes multiple languages through tree-sitter grammars, giving polyglot teams consistent tooling.
 - **Privacy by design.** Your code and its derived index stay on your machine. No upload, no cloud dependency for the core product.
-- **Low friction.** One command (`cortex init --bootstrap`) scaffolds everything: indexing, git hooks, MCP registration for Claude Code, Claude Desktop, and Codex.
+- **Low friction.** One command (`cortex init --bootstrap`) scaffolds everything needed for local indexing, git hooks, CLI retrieval, and optional MCP compatibility.
 
 ## How it works
 
@@ -48,9 +48,9 @@ Cortex operates as a five-stage pipeline between your repository and your AI ass
 
 1. **Ingestion.** Source files are parsed with tree-sitter, producing structured entities (files, functions, classes, rules, ADRs) and relations (`CALLS`, `DEFINES`, `CONSTRAINS`, `IMPLEMENTS`, `IMPORTS`, `SUPERSEDES`).
 2. **Storage.** Entities and relations are persisted to a local graph database (RyuGraph). An optional vector index provides semantic search across entity content.
-3. **Retrieval.** MCP tools combine semantic search with graph traversal to assemble the smallest context package that answers the task.
+3. **Retrieval.** CLI commands combine semantic search with graph traversal to assemble the smallest context package that answers the task.
 4. **Policy.** Architectural rules and source-of-truth markers filter conflicting or deprecated content before it reaches the assistant.
-5. **Assembly.** Results are delivered to the assistant as a compact, ranked context package over MCP.
+5. **Assembly.** Results are delivered as compact, ranked context packages over `cortex ... --json`, with MCP exposing equivalent tool responses when enabled.
 
 Git hooks keep the index fresh on every checkout, pull, commit, and rewrite. A live TUI dashboard (`cortex dashboard`) shows what Cortex adds to the repository in real time.
 
@@ -74,13 +74,14 @@ The result is an assistant that behaves as if it already knows your codebase, be
 - Architectural rules and ADR enforcement at retrieval time.
 - Incremental index updates driven by git hooks.
 - Live TUI dashboard showing what Cortex adds to your repository.
-- First-class integrations with Claude Code, Claude Desktop, and Codex.
+- CLI-first retrieval commands for local agents and scripts.
+- Optional MCP integrations with Claude Code, Claude Desktop, and Codex.
 
 ## Requirements
 
-- Node.js 18+
+- Node.js 20+
 - Git repository
-- Optional for auto-connection: `claude` and/or `codex` CLI in `PATH`
+- Optional for MCP registration: `claude` and/or `codex` CLI in `PATH`
 
 ## Install
 
@@ -94,7 +95,7 @@ To upgrade an already-scaffolded project to a new Cortex version:
 
 ```bash
 npm i -g @danielblomma/cortex-mcp
-cortex init --force   # re-scaffolds .context/mcp + .context/scripts
+cortex init --force   # re-scaffolds .context runtime + .context/scripts
 cortex bootstrap
 cortex update
 ```
@@ -110,9 +111,9 @@ Version-specific notes (see [CHANGELOG.md](CHANGELOG.md) for details):
   `CORTEX_EMBED_MAX_CHARS` env var is removed and silently ignored.
   Existing projects keep their old ranking weights in `config.yaml`; the
   recommended block is now `semantic: 0.55, graph: 0.10, trust: 0.20,
-  recency: 0.15`. After re-embedding, restart the MCP server, and note
-  that the first search after a re-embed can hit a stale embeddings
-  cache — re-run the query.
+  recency: 0.15`. If you use MCP, restart the MCP server after
+  re-embedding. The first search after a re-embed can hit a stale
+  embeddings cache — re-run the query.
 
 ## Quick Start
 
@@ -124,10 +125,10 @@ cortex init --bootstrap
 
 This will:
 
-- scaffold `.context/`, `.context/scripts/`, `.context/mcp/`, `.githooks/`, and docs files
+- scaffold `.context/`, `.context/scripts/`, the local context runtime (`.context/mcp` compatibility path), `.githooks/`, and docs files
 - activate git hooks for checkout, pull/merge, commit, and rewrite events
-- build and prepare the local MCP server
-- try to auto-register MCP connections for Claude/Codex (if installed)
+- build and prepare the local context runtime
+- leave MCP client registration opt-in via `cortex connect` or `cortex init --connect`
 - start background sync unless disabled
 
 Disable watcher setup:
@@ -142,7 +143,29 @@ Check context status:
 cortex status
 ```
 
-## Verify MCP Connection
+## Query From The CLI
+
+Use the CLI as the default local agent interface:
+
+```bash
+cortex search "authentication flow" --json
+cortex related file:src/auth.ts --json
+cortex impact "payment service" --json
+cortex rules --json
+cortex explain "where retries are configured" --json
+```
+
+These commands read the same local graph, embeddings, and rules used by the MCP server, but they do not require an MCP client registration.
+
+## Optional MCP Connection
+
+MCP remains supported for clients that need it. Register MCP clients explicitly:
+
+```bash
+cortex connect
+```
+
+Then verify the client registration:
 
 Claude:
 
@@ -166,15 +189,16 @@ Install via Claude Code plugin marketplace:
 /plugin enable cortex
 ```
 
-Then initialize Cortex in your target repository:
+Then initialize Cortex in your target repository. If you want the plugin to call the local MCP server, also run `cortex connect` from that repository:
 
 ```bash
 cortex init --bootstrap
+cortex connect
 ```
 
 ## Manual MCP Configuration
 
-If auto-registration is unavailable, configure MCP manually.
+If client registration is unavailable, configure MCP manually.
 
 Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
@@ -259,7 +283,7 @@ For projects on the WSL filesystem (e.g. `~/projects/myapp`), use the WSL path d
 - File watching on `/mnt/` paths (Windows filesystem) automatically uses poll mode since `inotify` is unreliable across filesystem boundaries.
 - For best performance, keep projects on the WSL filesystem (`~/...`) rather than `/mnt/c/...`.
 
-## MCP Tools
+## MCP Tool Compatibility
 
 ### `context.search`
 
@@ -352,6 +376,11 @@ cortex connect [path] [--skip-build]
 cortex mcp
 cortex bootstrap
 cortex update
+cortex search <query> [--json]
+cortex related <entity-id> [--json]
+cortex impact <query|entity-id> [--json]
+cortex rules [--json]
+cortex explain <query|entity-id> [--json]
 cortex status
 cortex dashboard [--interval <sec>]
 cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
@@ -372,7 +401,7 @@ This repository includes two GitHub Actions workflows:
 - `Release Publish` (`.github/workflows/release-publish.yml`)
   - Triggers on tag push `v*.*.*`
   - Verifies tag/version sync
-  - Runs root tests + MCP build/tests
+  - Runs root tests + context runtime/MCP build/tests
   - Publishes `@danielblomma/cortex-mcp` to npm via npm trusted publishing (GitHub OIDC)
 
 Required npm configuration:
@@ -404,12 +433,12 @@ to give each its fair share of cores.
 
 ## Troubleshooting
 
-- `mcp/dist/server.js` missing:
+- context runtime missing or `mcp/dist/server.js` missing:
   Run `cortex bootstrap` (or re-run `cortex init --bootstrap`).
-- `claude` or `codex` not found during init:
-  Auto-registration is skipped; use manual config above.
+- `claude` or `codex` not found during `cortex connect`:
+  MCP registration is skipped for that client; use manual config above if needed.
 - MCP tools return stale context:
-  Run `cortex update`, then reconnect MCP or call `context.reload` from your MCP client.
+  Run `cortex update`, then rerun the CLI query. If you use MCP, reconnect the client or call `context.reload`.
 
 ## Website and Benchmarks
 
@@ -422,7 +451,7 @@ to give each its fair share of cores.
 ## Support
 
 - Issues: https://github.com/DanielBlomma/cortex/issues
-- Marketplace prep notes: [docs/MCP_MARKETPLACE.md](docs/MCP_MARKETPLACE.md)
+- MCP registry submission draft: [mcp-registry-submission.json](mcp-registry-submission.json)
 
 ## License
 

package/bin/cortex.mjs

@@ -27,6 +27,7 @@ const PACKAGE_JSON_PATH = path.join(PACKAGE_ROOT, "package.json");
 // only the three editable config files". Generated artifacts (db,
 // embeddings, cache, hooks, mcp/, govern.local.json) never land in git.
 const MCP_PROJECT_REL = path.join(".context", "mcp");
+const CONTEXT_RUNTIME_REL = MCP_PROJECT_REL;
 const CONTEXT_SCRIPTS_REL = path.join(".context", "scripts");
 
 // `.context/*` (not `.context/`) so the !-negations below actually re-include
@@ -67,7 +68,7 @@ function printHelp() {
 
   console.log(helpSection("CONTEXT"));
   console.log(helpRow("init [path]", "Scaffold a project with --force/--bootstrap/--connect/--watch"));
-  console.log(helpRow("connect [path]", "Re-register MCP clients (Codex + Claude Code)"));
+  console.log(helpRow("connect [path]", "Register MCP clients (Codex + Claude Code)"));
   console.log(helpRow("bootstrap", "Install deps, ingest, embed, load graph"));
   console.log(helpRow("update", "Refresh context for changed files"));
   console.log(helpRow("status", "Project context status"));
@@ -75,6 +76,11 @@ function printHelp() {
   console.log(helpRow("ingest [--changed] [--verbose]", "Re-index source files"));
   console.log(helpRow("embed [--changed]", "Recompute embeddings"));
   console.log(helpRow("graph-load [--no-reset]", "Reload the dependency graph"));
+  console.log(helpRow("search <query> [--json]", "Search local graph+RAG context"));
+  console.log(helpRow("related <entity-id> [--json]", "Show related context entities"));
+  console.log(helpRow("impact <query|entity-id> [--json]", "Trace likely impact paths"));
+  console.log(helpRow("rules [--json]", "List active context rules"));
+  console.log(helpRow("explain <query|entity-id> [--json]", "Show search score evidence"));
   console.log(helpRow("dashboard [--interval <sec>]", "Live local dashboard"));
   console.log(helpRow("memory-compile [--dry-run] [--verbose]", "Compile memory artifacts"));
   console.log(helpRow("memory-lint [--verbose] [--json]", "Lint compiled memory"));
@@ -119,7 +125,7 @@ function parseInitArgs(args) {
   let target = process.cwd();
   let force = false;
   let bootstrap = false;
-  let connect = true;
+  let connect = false;
   let watch = true;
 
   for (const arg of args) {
@@ -810,9 +816,9 @@ async function maybeInstallGitHooks(targetDir) {
 }
 
 function ensureProjectInitialized(targetDir) {
-  const mcpPackageJson = path.join(targetDir, MCP_PROJECT_REL, "package.json");
-  if (!fs.existsSync(mcpPackageJson)) {
-    throw new Error(`Missing ${mcpPackageJson}. Run 'cortex init --bootstrap' first.`);
+  const runtimePackageJson = path.join(targetDir, CONTEXT_RUNTIME_REL, "package.json");
+  if (!fs.existsSync(runtimePackageJson)) {
+    throw new Error(`Missing ${runtimePackageJson}. Run 'cortex init --bootstrap' first.`);
   }
 }
 
@@ -882,7 +888,7 @@ async function maybeMigrateScaffold(targetDir, command) {
 
   console.error(
     `[cortex] scaffold in ${targetDir} is out of date ` +
-      `(missing .context/scripts/doctor.sh, .context/mcp/package.json, doctor subcommand in context.sh, ` +
+      `(missing .context/scripts/doctor.sh, context runtime package.json, doctor subcommand in context.sh, ` +
       `or carries a legacy mcp/ directory at the project root).`
   );
 
@@ -985,7 +991,7 @@ async function run() {
     await maybeInstallGitHooks(target);
 
     console.log(`[cortex] initialized in ${target}`);
-    console.log("[cortex] scaffold copied: .context/, .context/scripts/, .context/mcp/, .githooks/, docs/");
+    console.log("[cortex] scaffold copied: .context/, .context/scripts/, context runtime (.context/mcp compatibility path), .githooks/, docs/");
     console.log(`[cortex] Claude commands ready: /context-update (${helpers.claude.total} files)`);
     if (helpers.codex.changed) {
       console.log("[cortex] Codex workflow instructions added to AGENTS.md");
@@ -1002,7 +1008,7 @@ async function run() {
     if (connect) {
       console.log("[cortex] MCP connect: Codex + Claude Code (if CLIs are installed)");
     } else {
-      console.log("[cortex] MCP connect skipped (--no-connect)");
+      console.log("[cortex] MCP connect skipped (run 'cortex connect' or init with --connect)");
     }
 
     if (watch) {
@@ -1087,6 +1093,10 @@ async function run() {
     return runStageCommandShim(rest);
   }
 
+  if (QUERY_COMMANDS.has(command)) {
+    return runQueryCommandShim(command, rest);
+  }
+
   const passthrough = new Set([
     "bootstrap",
     "update",
@@ -1144,25 +1154,28 @@ function isPidAlive(pid) {
   }
 }
 
-function resolveProjectMcpDist() {
+function resolveProjectRuntimeDist() {
   // v2.0.5: project layout was moved from <cwd>/mcp/ to <cwd>/.context/mcp/.
-  // PACKAGE_ROOT/scaffold/mcp/ is still the source tree the scaffold is
-  // copied from; the actual built code lives in each project's
-  // <cwd>/.context/mcp/dist/ after bootstrap.
+  // The runtime still lives there for compatibility, but CLI commands now
+  // treat it as the local context runtime rather than an MCP-only surface.
   const target = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
-  return path.join(target, MCP_PROJECT_REL, "dist");
+  return path.join(target, CONTEXT_RUNTIME_REL, "dist");
+}
+
+function resolveProjectMcpDist() {
+  return resolveProjectRuntimeDist();
 }
 
 function resolveDaemonEntry() {
-  return path.join(resolveProjectMcpDist(), "daemon", "main.js");
+  return path.join(resolveProjectRuntimeDist(), "daemon", "main.js");
 }
 
 function resolveHookEntry(name) {
-  return path.join(resolveProjectMcpDist(), "hooks", `${name}.js`);
+  return path.join(resolveProjectRuntimeDist(), "hooks", `${name}.js`);
 }
 
 function resolveCliEntry(name) {
-  return path.join(resolveProjectMcpDist(), "cli", `${name}.js`);
+  return path.join(resolveProjectRuntimeDist(), "cli", `${name}.js`);
 }
 
 async function runDaemonCommand(args) {
@@ -1347,7 +1360,7 @@ function loadGovernModule() {
   const entry = resolveCliEntry("govern");
   if (!fs.existsSync(entry)) {
     throw new Error(
-      `Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`
+      `Build the project's context runtime first (missing ${entry}). Run 'cortex bootstrap' in the project root.`
     );
   }
   return import(pathToFileURL(entry).href);
@@ -1480,7 +1493,7 @@ async function runEnterpriseInstall(args) {
 
   const enterpriseEntry = resolveCliEntry("enterprise-setup");
   if (!fs.existsSync(enterpriseEntry)) {
-    printBullet("fail", `Build the project's MCP first (missing ${enterpriseEntry}). Run 'cortex bootstrap' in the project root.`);
+    printBullet("fail", `Build the project's context runtime first (missing ${enterpriseEntry}). Run 'cortex bootstrap' in the project root.`);
     process.exit(1);
   }
   const enterpriseMod = await import(pathToFileURL(enterpriseEntry).href);
@@ -1575,6 +1588,7 @@ async function runEnterpriseInstall(args) {
 }
 
 const RUN_CLIS = new Set(["claude", "codex", "copilot"]);
+const QUERY_COMMANDS = new Set(["search", "related", "impact", "rules", "explain"]);
 
 async function runRunCommand(args) {
   const sub = args[0];
@@ -1601,7 +1615,7 @@ async function runRunCommand(args) {
   const entry = resolveCliEntry("run");
   if (!fs.existsSync(entry)) {
     throw new Error(
-      `Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`
+      `Build the project's context runtime first (missing ${entry}). Run 'cortex bootstrap' in the project root.`
     );
   }
   const mod = await import(pathToFileURL(entry).href);
@@ -1615,19 +1629,32 @@ async function runStageCommandShim(args) {
   const entry = resolveCliEntry("stage");
   if (!fs.existsSync(entry)) {
     throw new Error(
-      `Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`,
+      `Build the project's context runtime first (missing ${entry}). Run 'cortex bootstrap' in the project root.`,
     );
   }
   const mod = await import(pathToFileURL(entry).href);
   await mod.runStageCommand(args);
 }
 
+async function runQueryCommandShim(command, args) {
+  const target = process.env.CORTEX_PROJECT_ROOT?.trim() || process.cwd();
+  process.env.CORTEX_PROJECT_ROOT = path.resolve(target);
+  const entry = resolveCliEntry("query");
+  if (!fs.existsSync(entry)) {
+    throw new Error(
+      `Build the project's context runtime first (missing ${entry}). Run 'cortex bootstrap' in the project root.`
+    );
+  }
+  const mod = await import(pathToFileURL(entry).href);
+  await mod.runQueryCommand([command, ...args]);
+}
+
 async function runTelemetryCommand(args) {
   const sub = args[0] || "help";
   if (sub === "test") {
     const entry = resolveCliEntry("telemetry-test");
     if (!fs.existsSync(entry)) {
-      throw new Error(`Build the project's MCP first (missing ${entry}). Run 'cortex bootstrap' in the project root.`);
+      throw new Error(`Build the project's context runtime first (missing ${entry}). Run 'cortex bootstrap' in the project root.`);
     }
     const mod = await import(pathToFileURL(entry).href);
     const code = await mod.runTelemetryTest();

package/mcp-registry-submission.json

@@ -0,0 +1,63 @@
+{
+  "name": "cortex",
+  "vendor": "danielblomma",
+  "sourceUrl": "https://github.com/DanielBlomma/cortex",
+  "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context for your codebase.",
+  "npmPackage": "@danielblomma/cortex-mcp",
+  "license": "MIT",
+  "homepage": "https://github.com/DanielBlomma/cortex",
+  "categories": [
+    "development-tools",
+    "code-analysis",
+    "search"
+  ],
+  "keywords": [
+    "mcp",
+    "context",
+    "code-search",
+    "semantic-search",
+    "refactoring"
+  ],
+  "installation": {
+    "npm": "npm i -g @danielblomma/cortex-mcp && cortex init --bootstrap"
+  },
+  "tools": [
+    {
+      "name": "context.search",
+      "description": "Semantic search across codebase entities (files, rules, ADRs)"
+    },
+    {
+      "name": "context.get_related",
+      "description": "Get related entities via graph relationships"
+    },
+    {
+      "name": "context.get_rules",
+      "description": "Get active architectural rules and decisions"
+    },
+    {
+      "name": "context.reload",
+      "description": "Reload context graph after code changes"
+    }
+  ],
+  "config": {
+    "command": "cortex",
+    "args": ["mcp"],
+    "env": {
+      "CORTEX_PROJECT_ROOT": "<project-path>"
+    }
+  },
+  "features": [
+    "Semantic codebase search with graph-aware ranking",
+    "Graph relationships between files, rules, and ADRs",
+    "Experimental call graph APIs for function-level tracing and impact analysis (JS/TS semantic chunking builds)",
+    "Architectural rules and ADR enforcement",
+    "Local & private (no cloud, your code stays on your machine)",
+    "Incremental background sync",
+    "Multi-language support (JS/TS today, Python/Go planned)"
+  ],
+  "requirements": {
+    "node": ">=18",
+    "git": "required for change tracking",
+    "disk": "~50MB per project"
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.1.4",
+  "version": "2.2.0",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -17,7 +17,9 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "cli",
     "context",
+    "knowledge-graph",
     "code-search",
     "semantic-search",
     "refactoring",
@@ -34,12 +36,23 @@
   "files": [
     "bin",
     "types.js",
-    "scaffold/.context",
+    "scaffold/.context/config.yaml",
+    "scaffold/.context/rules.yaml",
+    "scaffold/.context/ontology.cypher",
     "scaffold/.githooks",
     "scaffold/AGENTS.md",
     "scaffold/CLAUDE.md",
     "scaffold/docs",
-    "scaffold/scripts",
+    "scaffold/scripts/*.mjs",
+    "scaffold/scripts/*.sh",
+    "scaffold/scripts/lib",
+    "scaffold/scripts/parsers/*.mjs",
+    "scaffold/scripts/parsers/package.json",
+    "scaffold/scripts/parsers/package-lock.json",
+    "scaffold/scripts/parsers/javascript",
+    "scaffold/scripts/parsers/tree-sitter",
+    "scaffold/scripts/parsers/dotnet/*/*.csproj",
+    "scaffold/scripts/parsers/dotnet/*/Program.cs",
     "scaffold/mcp/src",
     "scaffold/mcp/tests",
     "scaffold/mcp/build.mjs",
@@ -47,11 +60,11 @@
     "scaffold/mcp/package-lock.json",
     "scaffold/mcp/tsconfig.json",
     "README.md",
-    "docs/MCP_MARKETPLACE.md"
+    "mcp-registry-submission.json"
   ],
   "scripts": {
     "pretest": "test -d scaffold/scripts/parsers/node_modules || npm --prefix scaffold/scripts/parsers install --no-fund --no-update-notifier --silent",
-    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/ingest-parallel.test.mjs tests/ingest-worker-crash.test.mjs tests/javascript-parser.test.mjs tests/markdown-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 tests/bootstrapbench-stats.test.mjs tests/bootstrapbench-aggregate.test.mjs",
+    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.test.mjs tests/ingest-parallel.test.mjs tests/ingest-worker-crash.test.mjs tests/javascript-parser.test.mjs tests/markdown-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 tests/bootstrapbench-stats.test.mjs tests/bootstrapbench-aggregate.test.mjs tests/bootstrapbench-cleanup.test.mjs tests/query-cli-shim.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

@@ -2,17 +2,21 @@
 
 This project uses Cortex for AI-powered code context.
 
-## Required: Always use Cortex MCP tools
+## Required: Always use Cortex context
 
-When answering questions about this codebase, you MUST use Cortex tools instead of relying on memory or assumptions:
+When answering questions about this codebase, you MUST use Cortex context 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.
+Preferred CLI commands:
 
-Do NOT answer code questions from memory when these tools are available. Always search first.
+- `cortex search "<query>" --json` - Search before answering any code question. Never guess at implementations.
+- `cortex related <entity-id> --json` - Use when exploring dependencies or relationships between entities.
+- `cortex rules --json` - Check architectural rules before suggesting changes.
+- `cortex impact "<query-or-entity-id>" --json` - Use before refactoring or dependency analysis to understand blast radius and likely traversal paths.
+- `cortex update` - Refresh the index after making significant changes.
+
+If MCP tools are explicitly available in your client, the equivalent tools are `context.search`, `context.get_related`, `context.get_rules`, `context.impact`, and `context.reload`.
+
+Do NOT answer code questions from memory when Cortex CLI or MCP tools are available. Always search first.
 
 ## Enterprise tools (if available)
 
@@ -28,7 +32,7 @@ Do NOT answer code questions from memory when these tools are available. Always
 
 ## Diagnostics
 
-Run `cortex doctor` to verify your setup is healthy.
+Run `cortex doctor` to verify your setup is healthy. MCP client registration is optional; run `cortex connect` only when your local assistant needs MCP.
 
 <!-- cortex:auto:start -->
 ## Cortex Auto Workflow

package/scaffold/CLAUDE.md

@@ -2,17 +2,21 @@
 
 This project uses Cortex for AI-powered code context.
 
-## Required: Always use Cortex MCP tools
+## Required: Always use Cortex context
 
-When answering questions about this codebase, you MUST use Cortex tools instead of relying on memory or assumptions:
+When answering questions about this codebase, you MUST use Cortex context 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.
+Preferred CLI commands:
 
-Do NOT answer code questions from memory when these tools are available. Always search first.
+- `cortex search "<query>" --json` — Search before answering any code question. Never guess at implementations.
+- `cortex related <entity-id> --json` — Use when exploring dependencies or relationships between entities.
+- `cortex rules --json` — Check architectural rules before suggesting changes.
+- `cortex impact "<query-or-entity-id>" --json` — Use before refactoring or dependency analysis to understand blast radius and likely traversal paths.
+- `cortex update` — Refresh the index after making significant changes.
+
+If MCP tools are explicitly available in Claude, the equivalent tools are `context.search`, `context.get_related`, `context.get_rules`, `context.impact`, and `context.reload`.
+
+Do NOT answer code questions from memory when Cortex CLI or MCP tools are available. Always search first.
 
 ## Enterprise tools (if available)
 
@@ -28,4 +32,4 @@ Do NOT answer code questions from memory when these tools are available. Always
 
 ## Diagnostics
 
-Run `cortex doctor` to verify your setup is healthy.
+Run `cortex doctor` to verify your setup is healthy. MCP client registration is optional; run `cortex connect` only when Claude should use Cortex as an MCP server.

package/scaffold/docs/architecture.md

@@ -8,7 +8,7 @@ Provide high-signal, repo-local context to coding agents without bloating instru
 2. Storage: graph (RyuGraph) + optional vector index
 3. Retrieval: semantic + graph
 4. Policy: rules filter conflicts/deprecated/source-of-truth
-5. Assembly: runtime context package for MCP tool responses
+5. Assembly: runtime context package for CLI JSON and optional MCP tool responses
 
 ## Runtime Context Order
 1. Task