@danielblomma/cortex-mcp 2.0.19 → 2.1.1

package/README.md

@@ -87,6 +87,32 @@ The result is an assistant that behaves as if it already knows your codebase, be
 npm i -g @danielblomma/cortex-mcp
 ```
 
+## Upgrading
+
+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 bootstrap
+cortex update
+```
+
+`cortex init --force` preserves per-project files: `.context/config.yaml`,
+`.context/rules.yaml`, and your notes/decisions.
+
+Version-specific notes (see [CHANGELOG.md](CHANGELOG.md) for details):
+
+- **2.1.0**: the default embedding model changed, so the first
+  `cortex update` after upgrading triggers a full re-embed automatically
+  (~2 min per 1000 entities plus a one-time model download). The
+  `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.
+
 ## Quick Start
 
 From the repository you want to index:

package/bin/cortex.mjs

@@ -191,7 +191,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", "AGENTS.md"]);
+const PRESERVE_FILES = new Set(["config.yaml", "rules.yaml", "enterprise.yml", "enterprise.yaml", "CLAUDE.md", "AGENTS.md"]);
 const DEFAULT_SOURCE_PATHS = [
   "src",
   "docs",
@@ -410,9 +410,12 @@ function buildInitialConfig(targetDir) {
     "  - RULE",
     "  - CODE",
     "  - WIKI",
+    "# graph weight is low because graph degree mostly measures how many rules",
+    "# constrain an entity (docs are hubs, leaf code is not). Tuned as a pair with",
+    "# the midrank-percentile graph_score.",
     "ranking:",
-    "  semantic: 0.40",
-    "  graph: 0.25",
+    "  semantic: 0.55",
+    "  graph: 0.10",
     "  trust: 0.20",
     "  recency: 0.15",
     "runtime:",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.19",
+  "version": "2.1.1",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -50,7 +50,7 @@
   ],
   "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/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",
+    "test": "node tests/context-regressions.test.mjs && node --test tests/ingest-units.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",
     "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/.context/config.yaml

@@ -10,9 +10,12 @@ truth_order:
   - RULE
   - CODE
   - WIKI
+# graph weight is low because graph degree mostly measures how many rules
+# constrain an entity (docs are hubs, leaf code is not). Tuned as a pair with
+# the midrank-percentile graph_score.
 ranking:
-  semantic: 0.40
-  graph: 0.25
+  semantic: 0.55
+  graph: 0.10
   trust: 0.20
   recency: 0.15
 runtime:

package/scaffold/mcp/package-lock.json

@@ -1760,9 +1760,9 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.18",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.18.tgz",
-      "integrity": "sha512-RWzP96k/yv0PQfyXnWjs6zot20TqfpfsNXhOnev8d1InAxubW93L11/oNUc3tQqn2G0bSdAOBpX+2uDFHV7kdQ==",
+      "version": "4.12.25",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.25.tgz",
+      "integrity": "sha512-2NFaIyNVgJmBs/ecmtGzlmluTFs5cHEWGTdu0t1HBwYzoGXOL5nUQBRMXsXWla5i4KkG//QMzVP88m1+I3fdAQ==",
       "license": "MIT",
       "engines": {
         "node": ">=16.9.0"
@@ -2165,9 +2165,9 @@
       }
     },
     "node_modules/qs": {
-      "version": "6.15.0",
-      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.0.tgz",
-      "integrity": "sha512-mAZTtNCeetKMH+pSjrb76NAM8V9a05I9aBZOHztWy/UqcJdQYNsf59vrRKWnojAT9Y+GbIvoTBC++CPHqpDBhQ==",
+      "version": "6.15.2",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.2.tgz",
+      "integrity": "sha512-Rzq0KEyX/w/tEybncDgdkZrJgVUsUMk3xjh3t5bv3S1HTAtg+uOYt72+ZfwiQwKdysThkTBdL/rTi6HDmX9Ddw==",
       "license": "BSD-3-Clause",
       "dependencies": {
         "side-channel": "^1.1.0"

package/scaffold/mcp/package.json

@@ -24,7 +24,7 @@
   "overrides": {
     "cmake-js": "^8.0.0",
     "express-rate-limit": "^8.5.1",
-    "hono": "^4.12.18",
+    "hono": "^4.12.23",
     "@hono/node-server": "^1.19.13",
     "tar": "^7.5.11"
   },

package/scaffold/mcp/src/embed.ts

@@ -1,6 +1,7 @@
 import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
+import { pathToFileURL } from "node:url";
 import { env, pipeline } from "@huggingface/transformers";
 import { readJsonl, asString, asNumber, asBoolean } from "./jsonl.js";
 import { CACHE_DIR, PATHS } from "./paths.js";
@@ -11,9 +12,11 @@ const EMBEDDINGS_MANIFEST_PATH = PATHS.embeddingsManifest;
 const MODEL_CACHE_DIR = PATHS.embeddingsModelCache;
 const EMBEDDINGS_DIR = path.dirname(EMBEDDINGS_PATH);
 
-const DEFAULT_MODEL_ID = "Xenova/all-MiniLM-L6-v2";
-const DEFAULT_MAX_TEXT_CHARS = 7000;
-const CHUNK_BODY_PREVIEW_CHARS = 2000;
+export const DEFAULT_MODEL_ID = "jinaai/jina-embeddings-v2-base-code";
+
+export function resolveModelId(): string {
+  return (process.env.CORTEX_EMBED_MODEL ?? DEFAULT_MODEL_ID).trim() || DEFAULT_MODEL_ID;
+}
 
 type FileEntity = {
   id: string;
@@ -134,10 +137,6 @@ function normalizeText(value: string): string {
   return value.replace(/\s+/g, " ").trim();
 }
 
-function clampText(value: string, maxChars: number): string {
-  return value.slice(0, maxChars);
-}
-
 function writeJsonl(filePath: string, records: EmbeddingRecord[]): void {
   const body = records.map((record) => JSON.stringify(record)).join("\n");
   fs.writeFileSync(filePath, body ? `${body}\n` : "", "utf8");
@@ -157,7 +156,7 @@ function ensureRequiredFiles(): void {
   }
 }
 
-function parseFileEntities(raw: JsonObject[], maxChars: number): FileEntity[] {
+export function parseFileEntities(raw: JsonObject[]): FileEntity[] {
   return raw
     .map((item) => {
       const id = asString(item.id);
@@ -170,7 +169,7 @@ function parseFileEntities(raw: JsonObject[], maxChars: number): FileEntity[] {
       const excerpt = asString(item.excerpt);
       const updatedAt = asString(item.updated_at);
       const checksum = asString(item.checksum, hashText(content));
-      const text = clampText(`${filePath}\n${excerpt}\n${content}`, maxChars);
+      const text = `${filePath}\n${excerpt}\n${content}`;
 
       return {
         id,
@@ -189,7 +188,7 @@ function parseFileEntities(raw: JsonObject[], maxChars: number): FileEntity[] {
     .filter((value): value is FileEntity => value !== null);
 }
 
-function parseRuleEntities(raw: JsonObject[], maxChars: number): RuleEntity[] {
+function parseRuleEntities(raw: JsonObject[]): RuleEntity[] {
   return raw
     .map((item) => {
       const id = asString(item.id);
@@ -200,7 +199,7 @@ function parseRuleEntities(raw: JsonObject[], maxChars: number): RuleEntity[] {
       const title = asString(item.title, id);
       const body = asString(item.body);
       const updatedAt = asString(item.updated_at, "");
-      const text = clampText(`${title}\n${body}`, maxChars);
+      const text = `${title}\n${body}`;
 
       return {
         id,
@@ -219,7 +218,7 @@ function parseRuleEntities(raw: JsonObject[], maxChars: number): RuleEntity[] {
     .filter((value): value is RuleEntity => value !== null);
 }
 
-function parseAdrEntities(raw: JsonObject[], maxChars: number): AdrEntity[] {
+function parseAdrEntities(raw: JsonObject[]): AdrEntity[] {
   return raw
     .map((item) => {
       const id = asString(item.id);
@@ -231,7 +230,7 @@ function parseAdrEntities(raw: JsonObject[], maxChars: number): AdrEntity[] {
       const body = asString(item.body);
       const adrPath = asString(item.path);
       const decisionDate = asString(item.decision_date, "");
-      const text = clampText(`${adrPath}\n${title}\n${body}`, maxChars);
+      const text = `${adrPath}\n${title}\n${body}`;
 
       return {
         id,
@@ -250,7 +249,7 @@ function parseAdrEntities(raw: JsonObject[], maxChars: number): AdrEntity[] {
     .filter((value): value is AdrEntity => value !== null);
 }
 
-function parseModuleEntities(raw: JsonObject[], maxChars: number): ModuleEntity[] {
+function parseModuleEntities(raw: JsonObject[]): ModuleEntity[] {
   return raw
     .map((item) => {
       const id = asString(item.id);
@@ -263,7 +262,7 @@ function parseModuleEntities(raw: JsonObject[], maxChars: number): ModuleEntity[
       const summary = asString(item.summary);
       const exportedSymbols = asString(item.exported_symbols);
       const updatedAt = asString(item.updated_at);
-      const text = clampText(`${modulePath}\n${name}\n${summary}\n${exportedSymbols}`, maxChars);
+      const text = `${modulePath}\n${name}\n${summary}\n${exportedSymbols}`;
 
       return {
         id,
@@ -282,7 +281,7 @@ function parseModuleEntities(raw: JsonObject[], maxChars: number): ModuleEntity[
     .filter((value): value is ModuleEntity => value !== null);
 }
 
-function parseChunkEntities(raw: JsonObject[], filePathById: Map<string, string>, maxChars: number): ChunkEntity[] {
+export function parseChunkEntities(raw: JsonObject[], filePathById: Map<string, string>): ChunkEntity[] {
   return raw
     .map((item) => {
       const id = asString(item.id);
@@ -298,7 +297,7 @@ function parseChunkEntities(raw: JsonObject[], filePathById: Map<string, string>
       const body = asString(item.body);
       const updatedAt = asString(item.updated_at);
       const checksum = asString(item.checksum, hashText(body));
-      const text = clampText(`${filePath}\n${name}\n${sig}\n${description}\n${body.slice(0, CHUNK_BODY_PREVIEW_CHARS)}`, maxChars);
+      const text = `${filePath}\n${name}\n${sig}\n${description}\n${body}`;
 
       return {
         id,
@@ -317,7 +316,7 @@ function parseChunkEntities(raw: JsonObject[], filePathById: Map<string, string>
     .filter((value): value is ChunkEntity => value !== null);
 }
 
-function parseProjectEntities(raw: JsonObject[], maxChars: number): ProjectEntity[] {
+function parseProjectEntities(raw: JsonObject[]): ProjectEntity[] {
   return raw
     .map((item) => {
       const id = asString(item.id);
@@ -332,10 +331,7 @@ function parseProjectEntities(raw: JsonObject[], maxChars: number): ProjectEntit
       const targetFramework = asString(item.target_framework);
       const summary = asString(item.summary);
       const updatedAt = asString(item.updated_at);
-      const text = clampText(
-        `${projectPath}\n${name}\n${kind}\n${language}\n${targetFramework}\n${summary}`,
-        maxChars
-      );
+      const text = `${projectPath}\n${name}\n${kind}\n${language}\n${targetFramework}\n${summary}`;
 
       return {
         id,
@@ -416,29 +412,39 @@ async function main(): Promise<void> {
   fs.mkdirSync(EMBEDDINGS_DIR, { recursive: true });
   fs.mkdirSync(MODEL_CACHE_DIR, { recursive: true });
 
-  const modelId = (process.env.CORTEX_EMBED_MODEL ?? DEFAULT_MODEL_ID).trim() || DEFAULT_MODEL_ID;
-  const maxChars = Number(process.env.CORTEX_EMBED_MAX_CHARS ?? DEFAULT_MAX_TEXT_CHARS);
-  const maxTextChars = Number.isFinite(maxChars) && maxChars > 0 ? Math.floor(maxChars) : DEFAULT_MAX_TEXT_CHARS;
+  const modelId = resolveModelId();
 
-  const documents = parseFileEntities(readJsonl(path.join(CACHE_DIR, "documents.jsonl")), maxTextChars);
-  const rules = parseRuleEntities(readJsonl(path.join(CACHE_DIR, "entities.rule.jsonl")), maxTextChars);
-  const adrs = parseAdrEntities(readJsonl(path.join(CACHE_DIR, "entities.adr.jsonl")), maxTextChars);
-  const modules = parseModuleEntities(readJsonl(path.join(CACHE_DIR, "entities.module.jsonl")), maxTextChars);
-  const projects = parseProjectEntities(readJsonl(path.join(CACHE_DIR, "entities.project.jsonl")), maxTextChars);
+  const documents = parseFileEntities(readJsonl(path.join(CACHE_DIR, "documents.jsonl")));
+  const rules = parseRuleEntities(readJsonl(path.join(CACHE_DIR, "entities.rule.jsonl")));
+  const adrs = parseAdrEntities(readJsonl(path.join(CACHE_DIR, "entities.adr.jsonl")));
+  const modules = parseModuleEntities(readJsonl(path.join(CACHE_DIR, "entities.module.jsonl")));
+  const projects = parseProjectEntities(readJsonl(path.join(CACHE_DIR, "entities.project.jsonl")));
 
   // Build file path lookup for chunk embedding text (reuse already-parsed documents)
   const filePathById = new Map<string, string>();
   for (const doc of documents) {
     filePathById.set(doc.id, doc.path);
   }
-  const chunks = parseChunkEntities(readJsonl(path.join(CACHE_DIR, "entities.chunk.jsonl")), filePathById, maxTextChars);
+  const chunks = parseChunkEntities(readJsonl(path.join(CACHE_DIR, "entities.chunk.jsonl")), filePathById);
 
   const entities: SearchEntity[] = [...documents, ...rules, ...adrs, ...modules, ...projects, ...chunks].sort((a, b) => a.id.localeCompare(b.id));
 
   const existing = parseExistingEmbeddings(readJsonl(EMBEDDINGS_PATH), modelId);
 
   env.cacheDir = MODEL_CACHE_DIR;
-  const extractor = await pipeline("feature-extraction", modelId);
+  // Optional intra-op thread cap so co-located embedders (e.g. parallel CI
+  // jobs or eval containers) do not oversubscribe shared cores. Unset =
+  // library default (all cores), which is correct for a single instance.
+  const threadsRaw = Number(process.env.CORTEX_EMBED_THREADS);
+  const sessionOptions =
+    Number.isFinite(threadsRaw) && threadsRaw >= 1
+      ? { session_options: { intraOpNumThreads: Math.floor(threadsRaw), interOpNumThreads: 1 } }
+      : undefined;
+  const extractor = await pipeline(
+    "feature-extraction",
+    modelId,
+    sessionOptions as Parameters<typeof pipeline>[2]
+  );
 
   let reused = 0;
   let embedded = 0;
@@ -531,7 +537,10 @@ async function main(): Promise<void> {
   console.log(`[embed] manifest ${EMBEDDINGS_MANIFEST_PATH}`);
 }
 
-main().catch((error) => {
-  process.stderr.write(`${error instanceof Error ? error.message : "Embedding error"}\n`);
-  process.exit(1);
-});
+const isMain = process.argv[1] ? pathToFileURL(process.argv[1]).href === import.meta.url : false;
+if (isMain) {
+  main().catch((error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : "Embedding error"}\n`);
+    process.exit(1);
+  });
+}

package/scaffold/mcp/src/paths.ts

@@ -98,9 +98,12 @@ export const PATHS = {
   transformsConfigRelations: path.join(CACHE_DIR, "relations.transforms_config.jsonl")
 };
 
+// Graph degree mostly measures how many rules constrain an entity (docs are
+// hubs, leaf code is not), so it gets low weight. Tuned together with the
+// midrank-percentile graph_score in searchResults.ts.
 export const DEFAULT_RANKING: RankingWeights = {
-  semantic: 0.4,
-  graph: 0.25,
+  semantic: 0.55,
+  graph: 0.1,
   trust: 0.2,
   recency: 0.15
 };

package/scaffold/mcp/src/searchResults.ts

@@ -33,6 +33,38 @@ export function buildSearchResults(params: {
   recencyScorer: (isoDate: string) => number;
   legacyDataAccessBooster: (entity: SearchEntity, queryTokens: string[], queryPhrase: string) => number;
 }): Record<string, unknown>[] {
+  // Graph score = midrank percentile of relation degree within the entity's
+  // own type. The previous min(1, degree/4) saturated at degree >= 4, which
+  // nearly every entity exceeds, making the graph weight a constant. Per-type
+  // percentiles discriminate by connectivity while staying type-neutral
+  // (every type averages ~0.5), so hub-heavy types like rules cannot drown
+  // out leaf code files or doc sections.
+  const sortedDegreesByType = new Map<string, number[]>();
+  for (const entity of params.candidates) {
+    const degree = params.degreeByEntity.get(entity.id) ?? 0;
+    const list = sortedDegreesByType.get(entity.entity_type);
+    if (list) {
+      list.push(degree);
+    } else {
+      sortedDegreesByType.set(entity.entity_type, [degree]);
+    }
+  }
+  for (const list of sortedDegreesByType.values()) {
+    list.sort((a, b) => a - b);
+  }
+  const midrankPercentile = (sorted: number[], value: number): number => {
+    let lo = 0;
+    let hi = sorted.length;
+    while (lo < hi) {
+      const mid = (lo + hi) >> 1;
+      if (sorted[mid] < value) lo = mid + 1;
+      else hi = mid;
+    }
+    let upper = lo;
+    while (upper < sorted.length && sorted[upper] === value) upper += 1;
+    return sorted.length > 0 ? (lo + upper) / (2 * sorted.length) : 0;
+  };
+
   const rawResults = params.candidates
     .map((entity) => {
       const lexicalSemantic = params.semanticScorer(params.queryTokens, params.queryPhrase, entity.text);
@@ -49,7 +81,8 @@ export function buildSearchResults(params: {
 
       const semantic =
         vectorSemantic > 0 ? vectorSemantic * 0.75 + lexicalSemantic * 0.25 : lexicalSemantic;
-      const graphScore = Math.min(1, (params.degreeByEntity.get(entity.id) ?? 0) / 4);
+      const degree = params.degreeByEntity.get(entity.id) ?? 0;
+      const graphScore = midrankPercentile(sortedDegreesByType.get(entity.entity_type) ?? [], degree);
       const trustScore = Math.max(0, Math.min(1, entity.trust_level / 100));
       const dateScore = params.recencyScorer(entity.updated_at);
 

package/scaffold/mcp/tests/embed-entities.test.mjs

@@ -0,0 +1,72 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseFileEntities, parseChunkEntities, resolveModelId, DEFAULT_MODEL_ID } from "../dist/embed.js";
+
+function fileRecord(content) {
+  return {
+    id: "file-1",
+    path: "src/big.ts",
+    content,
+    excerpt: "excerpt",
+    updated_at: "2026-01-01T00:00:00Z",
+    checksum: "fixed-checksum"
+  };
+}
+
+function chunkRecord(body) {
+  return {
+    id: "chunk-1",
+    file_id: "file-1",
+    name: "bigFunction",
+    signature: "function bigFunction()",
+    description: "",
+    body,
+    updated_at: "2026-01-01T00:00:00Z",
+    checksum: "fixed-checksum"
+  };
+}
+
+test("file embedding text is uncapped beyond the old 7000-char limit", () => {
+  const base = "x".repeat(8000);
+  const variant = `${"x".repeat(7500)}CHANGED${"x".repeat(493)}`;
+
+  const [a] = parseFileEntities([fileRecord(base)]);
+  const [b] = parseFileEntities([fileRecord(variant)]);
+
+  assert.ok(a.text.length > 7000);
+  assert.ok(a.text.includes(base));
+  assert.notEqual(a.signature, b.signature);
+});
+
+test("chunk embedding text includes the full body beyond the old 2000-char preview", () => {
+  const filePathById = new Map([["file-1", "src/big.ts"]]);
+  const base = "y".repeat(3000);
+  const variant = `${"y".repeat(2500)}CHANGED${"y".repeat(493)}`;
+
+  const [a] = parseChunkEntities([chunkRecord(base)], filePathById);
+  const [b] = parseChunkEntities([chunkRecord(variant)], filePathById);
+
+  assert.ok(a.text.includes(base));
+  assert.notEqual(a.signature, b.signature);
+});
+
+test("default embedding model is jina code model and env override still works", () => {
+  const saved = process.env.CORTEX_EMBED_MODEL;
+  try {
+    delete process.env.CORTEX_EMBED_MODEL;
+    assert.equal(DEFAULT_MODEL_ID, "jinaai/jina-embeddings-v2-base-code");
+    assert.equal(resolveModelId(), DEFAULT_MODEL_ID);
+
+    process.env.CORTEX_EMBED_MODEL = "Xenova/all-MiniLM-L6-v2";
+    assert.equal(resolveModelId(), "Xenova/all-MiniLM-L6-v2");
+
+    process.env.CORTEX_EMBED_MODEL = "   ";
+    assert.equal(resolveModelId(), DEFAULT_MODEL_ID);
+  } finally {
+    if (saved === undefined) {
+      delete process.env.CORTEX_EMBED_MODEL;
+    } else {
+      process.env.CORTEX_EMBED_MODEL = saved;
+    }
+  }
+});

package/scaffold/mcp/tests/search-graph-score.test.mjs

@@ -0,0 +1,132 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { buildSearchResults } from "../dist/searchResults.js";
+
+function makeEntity(id, entityType, overrides = {}) {
+  return {
+    id,
+    entity_type: entityType,
+    kind: entityType === "Chunk" ? "function" : "DOC",
+    label: id,
+    path: `src/${id}.ts`,
+    text: `text for ${id}`,
+    status: "active",
+    source_of_truth: false,
+    trust_level: 50,
+    updated_at: "2026-01-01T00:00:00Z",
+    snippet: "",
+    matched_rules: [],
+    ...overrides
+  };
+}
+
+function runSearch(candidates, degrees) {
+  return buildSearchResults({
+    candidates,
+    degreeByEntity: new Map(degrees),
+    queryTokens: ["query"],
+    queryPhrase: "query",
+    ranking: { semantic: 0.55, graph: 0.1, trust: 0.2, recency: 0.15 },
+    includeScores: true,
+    includeMatchedRules: false,
+    includeContent: false,
+    queryVector: null,
+    embeddingVectors: new Map(),
+    topK: 100,
+    minLexicalRelevance: 0,
+    minVectorRelevance: 0,
+    semanticScorer: () => 0.5,
+    vectorScorer: () => 0,
+    recencyScorer: () => 0,
+    legacyDataAccessBooster: () => 0
+  });
+}
+
+function graphScoreById(results) {
+  return new Map(results.map((result) => [result.id, result.graph_score]));
+}
+
+test("graph score gives midrank to ties: a mass of degree-1 chunks lands at 0.5", () => {
+  const candidates = [1, 2, 3, 4].map((n) => makeEntity(`chunk-${n}`, "Chunk"));
+  const degrees = candidates.map((entity) => [entity.id, 1]);
+
+  const scores = graphScoreById(runSearch(candidates, degrees));
+
+  for (const entity of candidates) {
+    assert.equal(scores.get(entity.id), 0.5);
+  }
+});
+
+test("graph score for a single-entity type is 0.5", () => {
+  const candidates = [makeEntity("only-file", "File")];
+
+  const scores = graphScoreById(runSearch(candidates, [["only-file", 7]]));
+
+  assert.equal(scores.get("only-file"), 0.5);
+});
+
+test("graph score is monotonic in degree within a type", () => {
+  const candidates = [
+    makeEntity("low", "Chunk"),
+    makeEntity("mid", "Chunk"),
+    makeEntity("high", "Chunk"),
+    makeEntity("top", "Chunk")
+  ];
+  const degrees = [
+    ["low", 0],
+    ["mid", 2],
+    ["high", 5],
+    ["top", 9]
+  ];
+
+  const scores = graphScoreById(runSearch(candidates, degrees));
+
+  assert.ok(scores.get("low") < scores.get("mid"));
+  assert.ok(scores.get("mid") < scores.get("high"));
+  assert.ok(scores.get("high") < scores.get("top"));
+});
+
+test("graph score percentiles are isolated per type: hub types cannot drown out leaf code", () => {
+  const chunks = [
+    makeEntity("leaf-a", "Chunk"),
+    makeEntity("leaf-b", "Chunk")
+  ];
+  const hubRules = [
+    makeEntity("rule-hub-1", "Rule", { trust_level: 95 }),
+    makeEntity("rule-hub-2", "Rule", { trust_level: 95 })
+  ];
+  const degrees = [
+    ["leaf-a", 1],
+    ["leaf-b", 3],
+    ["rule-hub-1", 200],
+    ["rule-hub-2", 400]
+  ];
+
+  const scores = graphScoreById(runSearch([...chunks, ...hubRules], degrees));
+
+  // Chunk percentiles are computed against chunks only: degree 1 is the lower
+  // half and degree 3 the upper half, despite rule degrees being 100x larger.
+  assert.equal(scores.get("leaf-a"), 0.25);
+  assert.equal(scores.get("leaf-b"), 0.75);
+  assert.equal(scores.get("rule-hub-1"), 0.25);
+  assert.equal(scores.get("rule-hub-2"), 0.75);
+});
+
+test("graph score never saturates to a shared constant for common degrees", () => {
+  // The old min(1, degree/4) mapped every degree >= 4 to 1.0.
+  const candidates = [
+    makeEntity("deg-4", "Chunk"),
+    makeEntity("deg-8", "Chunk"),
+    makeEntity("deg-40", "Chunk")
+  ];
+  const degrees = [
+    ["deg-4", 4],
+    ["deg-8", 8],
+    ["deg-40", 40]
+  ];
+
+  const scores = graphScoreById(runSearch(candidates, degrees));
+  const unique = new Set(scores.values());
+
+  assert.equal(unique.size, 3);
+});

package/scaffold/scripts/ingest.mjs

@@ -21,6 +21,7 @@ let parseJavaCode = null;
 let parseRubyCode = null;
 let parseBashCode = null;
 let parseVb6Code = null;
+let parseMarkdownCode = null;
 let isVbNetParserAvailable = () => false;
 let isCSharpParserAvailable = () => false;
 let isCppParserAvailable = () => false;
@@ -83,6 +84,9 @@ async function loadOptionalParsers() {
     }),
     import("./parsers/vb6.mjs").then((module) => {
       parseVb6Code = module.parseCode;
+    }),
+    import("./parsers/markdown.mjs").then((module) => {
+      parseMarkdownCode = module.parseCode;
     })
   ];
 
@@ -164,7 +168,7 @@ const LEGACY_DOTNET_METADATA_EXTENSIONS = new Set([
 ]);
 
 const PROJECT_DEFINITION_EXTENSIONS = new Set([".sln", ".vbproj", ".csproj", ".fsproj", ".vcxproj"]);
-const STRUCTURED_NON_CODE_CHUNK_EXTENSIONS = new Set([".config", ".resx", ".settings"]);
+const STRUCTURED_NON_CODE_CHUNK_EXTENSIONS = new Set([".config", ".resx", ".settings", ".md", ".mdx"]);
 
 const CODE_FILE_EXTENSIONS = new Set([
   ".ts",
@@ -298,6 +302,22 @@ const CHUNK_PARSERS = new Map([
       isAvailable: () => typeof parseSqlCode === "function"
     }
   ],
+  [
+    ".md",
+    {
+      language: "markdown",
+      parse: (...args) => parseMarkdownCode(...args),
+      isAvailable: () => typeof parseMarkdownCode === "function"
+    }
+  ],
+  [
+    ".mdx",
+    {
+      language: "markdown",
+      parse: (...args) => parseMarkdownCode(...args),
+      isAvailable: () => typeof parseMarkdownCode === "function"
+    }
+  ],
   [
     ".config",
     {

package/scaffold/scripts/parsers/markdown.mjs

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+/**
+ * Markdown parser for Cortex.
+ * Chunks documents into heading-bounded sections (H1-H3). Headings inside
+ * fenced code blocks are ignored. Sections longer than the window threshold
+ * are split with overlap downstream by splitChunkIntoWindows in ingest.
+ */
+
+const HEADING_PATTERN = /^(#{1,3})\s+(.+?)\s*#*\s*$/;
+const FENCE_PATTERN = /^(```|~~~)/;
+
+export function parseCode(code, filePath, language = "markdown") {
+  const lines = code.split(/\r?\n/);
+  const sections = [];
+  let current = null;
+  let inFence = false;
+
+  const pushCurrent = (endIndex) => {
+    if (!current) {
+      return;
+    }
+    const body = lines.slice(current.startIndex, endIndex).join("\n").trimEnd();
+    const contentLines = lines.slice(current.startIndex + (current.heading ? 1 : 0), endIndex);
+    const hasContent = contentLines.some((line) => line.trim().length > 0);
+    if (body.trim().length > 0 && hasContent) {
+      sections.push({
+        name: current.name,
+        kind: "section",
+        signature: current.heading ?? current.name,
+        body,
+        startLine: current.startIndex + 1,
+        endLine: Math.max(current.startIndex + 1, endIndex),
+        language,
+        calls: [],
+        imports: []
+      });
+    }
+    current = null;
+  };
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (FENCE_PATTERN.test(line.trim())) {
+      inFence = !inFence;
+      continue;
+    }
+    if (inFence) {
+      continue;
+    }
+    const match = line.match(HEADING_PATTERN);
+    if (!match) {
+      if (!current) {
+        current = { name: "preamble", heading: null, startIndex: i };
+      }
+      continue;
+    }
+    pushCurrent(i);
+    current = { name: match[2].trim(), heading: line.trim(), startIndex: i };
+  }
+  pushCurrent(lines.length);
+
+  return { chunks: sections, errors: [] };
+}