@danielblomma/cortex-mcp 0.4.2 → 0.4.5

package/README.md

@@ -30,6 +30,29 @@ Cortex can extract function-level chunks and build call graphs in experimental b
 
 These APIs are experimental and may not be exposed in every installation.
 
+## Chunking Strategy (Code)
+
+When semantic chunking is enabled, large function/method chunks are split into overlap windows during ingest.
+
+Defaults:
+
+- `CORTEX_CHUNK_WINDOW_LINES=80`
+- `CORTEX_CHUNK_OVERLAP_LINES=16`
+- `CORTEX_CHUNK_SPLIT_MIN_LINES=120`
+- `CORTEX_CHUNK_MAX_WINDOWS=8`
+
+Behavior:
+
+- Chunks are split only when the chunk body exceeds the split threshold.
+- Windows slide forward using configured overlap (`next_start = previous_end - overlap`).
+- The last allowed window always stretches to the end of the chunk body.
+- Window chunks inherit metadata (`status`, `source_of_truth`) from their parent chunk.
+- Window chunks inherit parent graph edges for `CALLS` and `IMPORTS` to keep traversal/ranking consistent.
+
+Verification:
+
+- Overlap and windowing regressions are covered in `tests/context-regressions.test.mjs`.
+
 ## Requirements
 
 - Node.js 18+
@@ -63,6 +86,14 @@ Disable watcher setup:
 cortex init --bootstrap --no-watch
 ```
 
+Check semantic search readiness:
+
+```bash
+cortex status
+```
+
+Look for `semantic_search=embedding+lexical (ready)` to confirm full semantic mode.
+
 ## Verify MCP Connection
 
 Claude:
@@ -189,6 +220,27 @@ cortex todo [text|list|done <id>|reopen <id>|remove <id>]
 cortex help
 ```
 
+## Automated Release
+
+This repository includes two GitHub Actions workflows:
+
+- `Release Bump` (`.github/workflows/release-bump.yml`)
+  - Manual `workflow_dispatch` from `main`
+  - Bumps semver (`patch`/`minor`/`major`)
+  - Syncs release metadata files (`package.json`, `server.json`, plugin manifests)
+  - Runs tests
+  - Commits and tags `vX.Y.Z`
+
+- `Release Publish` (`.github/workflows/release-publish.yml`)
+  - Triggers on tag push `v*.*.*`
+  - Verifies tag/version sync
+  - Runs root tests + MCP build/tests
+  - Publishes `@danielblomma/cortex-mcp` to npm
+
+Required GitHub secret:
+
+- `NPM_TOKEN` (npm automation token with publish rights for `@danielblomma/cortex-mcp`)
+
 ## Limitations
 
 - Requires repo initialization (`cortex init --bootstrap`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "0.4.2",
+  "version": "0.4.5",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -35,6 +35,8 @@
   ],
   "scripts": {
     "test": "node tests/plan-state.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'"
   },
   "engines": {

package/scaffold/mcp/package-lock.json

@@ -33,9 +33,9 @@
       }
     },
     "node_modules/@hono/node-server": {
-      "version": "1.19.9",
-      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.9.tgz",
-      "integrity": "sha512-vHL6w3ecZsky+8P5MD+eFfaGTyCeOHUIFYMGpQGbrBTSmNNoxv0if69rEZ5giu36weC5saFuznL411gRX7bJDw==",
+      "version": "1.19.10",
+      "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.10.tgz",
+      "integrity": "sha512-hZ7nOssGqRgyV3FVVQdfi+U4q02uB23bpnYpdvNXkYTRRyWx84b7yf1ans+dnJ/7h41sGL3CeQTfO+ZGxuO+Iw==",
       "license": "MIT",
       "engines": {
         "node": ">=18.14.1"
@@ -236,7 +236,6 @@
       "resolved": "https://registry.npmjs.org/@types/node/-/node-22.19.13.tgz",
       "integrity": "sha512-akNQMv0wW5uyRpD2v2IEyRSZiR+BeGuoB6L310EgGObO44HSMNT8z1xzio28V8qOrgYaopIDNA18YgdXd+qTiw==",
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "undici-types": "~6.21.0"
       }
@@ -1285,11 +1284,10 @@
       }
     },
     "node_modules/hono": {
-      "version": "4.12.3",
-      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.3.tgz",
-      "integrity": "sha512-SFsVSjp8sj5UumXOOFlkZOG6XS9SJDKw0TbwFeV+AJ8xlST8kxK5Z/5EYa111UY8732lK2S/xB653ceuaoGwpg==",
+      "version": "4.12.5",
+      "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.5.tgz",
+      "integrity": "sha512-3qq+FUBtlTHhtYxbxheZgY8NIFnkkC/MR8u5TTsr7YZ3wixryQ3cCwn3iZbg8p8B88iDBBAYSfZDS75t8MN7Vg==",
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=16.9.0"
       }
@@ -2277,9 +2275,9 @@
       }
     },
     "node_modules/tar": {
-      "version": "7.5.9",
-      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.9.tgz",
-      "integrity": "sha512-BTLcK0xsDh2+PUe9F6c2TlRp4zOOBMTkoQHQIWSIzI0R7KG46uEwq4OPk2W7bZcprBMsuaeFsqwYr7pjh6CuHg==",
+      "version": "7.5.10",
+      "resolved": "https://registry.npmjs.org/tar/-/tar-7.5.10.tgz",
+      "integrity": "sha512-8mOPs1//5q/rlkNSPcCegA6hiHJYDmSLEI8aMH/CdSQJNWztHC9WHNam5zdQlfpTwB9Xp7IBEsHfV5LKMJGVAw==",
       "license": "BlueOak-1.0.0",
       "dependencies": {
         "@isaacs/fs-minipass": "^4.0.0",
@@ -2446,7 +2444,6 @@
       "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
       "dev": true,
       "license": "Apache-2.0",
-      "peer": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -2605,7 +2602,6 @@
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
       "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
       "license": "MIT",
-      "peer": true,
       "funding": {
         "url": "https://github.com/sponsors/colinhacks"
       }

package/scaffold/mcp/src/graph.ts

@@ -4,6 +4,7 @@ import ryugraph, { type Connection, type Database, type QueryResult } from "ryug
 import { DB_PATH, DEFAULT_RANKING, PATHS } from "./paths.js";
 import type {
   AdrRecord,
+  ChunkRecord,
   ContextData,
   DocumentRecord,
   JsonObject,
@@ -148,6 +149,33 @@ function parseAdrs(raw: JsonObject[]): AdrRecord[] {
     .filter((item): item is AdrRecord => item !== null);
 }
 
+function parseChunkEntities(raw: JsonObject[]): ChunkRecord[] {
+  return raw
+    .map((item) => {
+      const id = asString(item.id);
+      if (!id) {
+        return null;
+      }
+
+      return {
+        id,
+        file_id: asString(item.file_id),
+        name: asString(item.name),
+        kind: asString(item.kind, "chunk"),
+        signature: asString(item.signature),
+        body: asString(item.body),
+        start_line: asNumber(item.start_line),
+        end_line: asNumber(item.end_line),
+        language: asString(item.language),
+        updated_at: asString(item.updated_at),
+        source_of_truth: asBoolean(item.source_of_truth, false),
+        trust_level: asNumber(item.trust_level, 60),
+        status: asString(item.status, "active")
+      };
+    })
+    .filter((item): item is ChunkRecord => item !== null);
+}
+
 function parseRuleEntities(raw: JsonObject[]): RuleRecord[] {
   return raw
     .map((item) => {
@@ -243,7 +271,11 @@ function parseRulesYaml(yamlText: string | null): RuleRecord[] {
   return rules;
 }
 
-function parseRelations(raw: JsonObject[], relation: RelationRecord["relation"]): RelationRecord[] {
+function parseRelations(
+  raw: JsonObject[],
+  relation: RelationRecord["relation"],
+  noteFields: string[] = ["note", "reason"]
+): RelationRecord[] {
   return raw
     .map((item) => {
       const from = asString(item.from);
@@ -252,11 +284,20 @@ function parseRelations(raw: JsonObject[], relation: RelationRecord["relation"])
         return null;
       }
 
+      let note = "";
+      for (const fieldName of noteFields) {
+        const candidate = asString(item[fieldName]);
+        if (candidate) {
+          note = candidate;
+          break;
+        }
+      }
+
       return {
         from,
         to,
         relation,
-        note: asString(item.note) || asString(item.reason)
+        note
       };
     })
     .filter((item): item is RelationRecord => item !== null);
@@ -483,6 +524,33 @@ function parseRyuGraphAdrs(rows: UnknownRow[]): AdrRecord[] {
     .filter((value): value is AdrRecord => value !== null);
 }
 
+function parseRyuGraphChunks(rows: UnknownRow[]): ChunkRecord[] {
+  return rows
+    .map((row) => {
+      const id = asStringUnknown(row.id);
+      if (!id) {
+        return null;
+      }
+
+      return {
+        id,
+        file_id: asStringUnknown(row.file_id),
+        name: asStringUnknown(row.name),
+        kind: asStringUnknown(row.kind, "chunk"),
+        signature: asStringUnknown(row.signature),
+        body: asStringUnknown(row.body),
+        start_line: asNumberUnknown(row.start_line),
+        end_line: asNumberUnknown(row.end_line),
+        language: asStringUnknown(row.language),
+        updated_at: asStringUnknown(row.updated_at),
+        source_of_truth: asBooleanUnknown(row.source_of_truth, false),
+        trust_level: asNumberUnknown(row.trust_level, 60),
+        status: asStringUnknown(row.status, "active")
+      };
+    })
+    .filter((value): value is ChunkRecord => value !== null);
+}
+
 function parseRyuGraphRelations(
   rows: UnknownRow[],
   relation: RelationRecord["relation"],
@@ -509,10 +577,16 @@ export async function loadContextData(): Promise<ContextData> {
   const ranking = parseRankingFromConfig(readFileIfExists(PATHS.config));
   const cachedDocuments = parseDocuments(readJsonl(PATHS.documents));
   const cachedAdrs = parseAdrs(readJsonl(PATHS.adrEntities));
+  const cachedChunks = parseChunkEntities(readJsonl(PATHS.chunkEntities));
+  const cachedChunkRelations = [
+    ...parseRelations(readJsonl(PATHS.callsRelations), "CALLS", ["call_type"]),
+    ...parseRelations(readJsonl(PATHS.importsRelations), "IMPORTS", ["import_name"])
+  ];
   const cachedRelations = [
     ...parseRelations(readJsonl(PATHS.constrainsRelations), "CONSTRAINS"),
     ...parseRelations(readJsonl(PATHS.implementsRelations), "IMPLEMENTS"),
-    ...parseRelations(readJsonl(PATHS.supersedesRelations), "SUPERSEDES")
+    ...parseRelations(readJsonl(PATHS.supersedesRelations), "SUPERSEDES"),
+    ...cachedChunkRelations
   ];
 
   const yamlRules = parseRulesYaml(readFileIfExists(PATHS.rulesYaml));
@@ -525,6 +599,7 @@ export async function loadContextData(): Promise<ContextData> {
       documents: cachedDocuments,
       adrs: cachedAdrs,
       rules: cachedRules,
+      chunks: cachedChunks,
       relations: cachedRelations,
       ranking,
       source: "cache",
@@ -533,7 +608,7 @@ export async function loadContextData(): Promise<ContextData> {
   }
 
   try {
-    const [fileRows, ruleRows, adrRows, constrainsRows, implementsRows, supersedesRows] =
+    const [fileRows, ruleRows, adrRows, chunkRows, constrainsRows, implementsRows, supersedesRows] =
       await Promise.all([
         queryRows(
           connection,
@@ -582,6 +657,26 @@ export async function loadContextData(): Promise<ContextData> {
             a.status AS status;
         `
         ),
+        queryRows(
+          connection,
+          `
+          MATCH (c:Chunk)
+          RETURN
+            c.id AS id,
+            c.file_id AS file_id,
+            c.name AS name,
+            c.kind AS kind,
+            c.signature AS signature,
+            c.body AS body,
+            c.start_line AS start_line,
+            c.end_line AS end_line,
+            c.language AS language,
+            c.updated_at AS updated_at,
+            c.source_of_truth AS source_of_truth,
+            c.trust_level AS trust_level,
+            c.status AS status;
+        `
+        ),
         queryRows(
           connection,
           `
@@ -610,6 +705,7 @@ export async function loadContextData(): Promise<ContextData> {
     const ryuDocuments = parseRyuGraphDocuments(fileRows, contentById);
     const ryuRules = parseRyuGraphRules(ruleRows);
     const ryuAdrs = parseRyuGraphAdrs(adrRows);
+    const ryuChunks = parseRyuGraphChunks(chunkRows);
     const ryuRelations = [
       ...parseRyuGraphRelations(constrainsRows, "CONSTRAINS", "note"),
       ...parseRyuGraphRelations(implementsRows, "IMPLEMENTS", "note"),
@@ -620,7 +716,8 @@ export async function loadContextData(): Promise<ContextData> {
       documents: ryuDocuments.length > 0 ? ryuDocuments : cachedDocuments,
       adrs: ryuAdrs.length > 0 ? ryuAdrs : cachedAdrs,
       rules: ryuRules.length > 0 ? ryuRules : cachedRules,
-      relations: ryuRelations.length > 0 ? ryuRelations : cachedRelations,
+      chunks: ryuChunks.length > 0 ? ryuChunks : cachedChunks,
+      relations: ryuRelations.length > 0 ? [...ryuRelations, ...cachedChunkRelations] : cachedRelations,
       ranking,
       source: "ryu"
     };
@@ -634,6 +731,7 @@ export async function loadContextData(): Promise<ContextData> {
       documents: cachedDocuments,
       adrs: cachedAdrs,
       rules: cachedRules,
+      chunks: cachedChunks,
       relations: cachedRelations,
       ranking,
       source: "cache",

package/scaffold/mcp/src/paths.ts

@@ -5,7 +5,10 @@ import type { RankingWeights } from "./types.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 
-export const REPO_ROOT = path.resolve(__dirname, "../..");
+const PROJECT_ROOT_OVERRIDE = process.env.CORTEX_PROJECT_ROOT?.trim();
+export const REPO_ROOT = PROJECT_ROOT_OVERRIDE
+  ? path.resolve(PROJECT_ROOT_OVERRIDE)
+  : path.resolve(__dirname, "../..");
 export const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 export const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
 export const DB_PATH = path.join(CONTEXT_DIR, "db", "graph.ryu");
@@ -20,9 +23,12 @@ export const PATHS = {
   documents: path.join(CACHE_DIR, "documents.jsonl"),
   adrEntities: path.join(CACHE_DIR, "entities.adr.jsonl"),
   ruleEntities: path.join(CACHE_DIR, "entities.rule.jsonl"),
+  chunkEntities: path.join(CACHE_DIR, "entities.chunk.jsonl"),
   constrainsRelations: path.join(CACHE_DIR, "relations.constrains.jsonl"),
   implementsRelations: path.join(CACHE_DIR, "relations.implements.jsonl"),
-  supersedesRelations: path.join(CACHE_DIR, "relations.supersedes.jsonl")
+  supersedesRelations: path.join(CACHE_DIR, "relations.supersedes.jsonl"),
+  callsRelations: path.join(CACHE_DIR, "relations.calls.jsonl"),
+  importsRelations: path.join(CACHE_DIR, "relations.imports.jsonl")
 };
 
 export const DEFAULT_RANKING: RankingWeights = {

package/scaffold/mcp/src/search.ts

@@ -11,14 +11,45 @@ import type {
   ToolPayload
 } from "./types.js";
 
+const MIN_LEXICAL_RELEVANCE = 0.05;
+const MIN_VECTOR_RELEVANCE = 0.2;
+
+const QUERY_TOKEN_EXPANSIONS: Record<string, string[]> = {
+  semantisk: ["semantic"],
+  sökning: ["search"],
+  sokning: ["search"],
+  regel: ["rule"],
+  regler: ["rules"],
+  relaterad: ["related"],
+  meddelande: ["message"],
+  avvikelse: ["deviation"]
+};
+
+function normalizeText(value: string): string {
+  return value.normalize("NFKC").toLowerCase();
+}
+
 function tokenize(value: string): string[] {
-  return value
-    .toLowerCase()
-    .split(/[^a-z0-9]+/g)
+  return normalizeText(value)
+    .split(/[^\p{L}\p{N}]+/gu)
     .map((part) => part.trim())
     .filter((part) => part.length >= 2);
 }
 
+function expandQueryTokens(tokens: string[]): string[] {
+  const expanded = new Set<string>(tokens);
+  for (const token of tokens) {
+    const aliases = QUERY_TOKEN_EXPANSIONS[token];
+    if (!aliases) {
+      continue;
+    }
+    for (const alias of aliases) {
+      expanded.add(alias);
+    }
+  }
+  return Array.from(expanded);
+}
+
 function daysSince(isoDate: string): number {
   const timestamp = Date.parse(isoDate);
   if (Number.isNaN(timestamp)) {
@@ -34,22 +65,30 @@ function recencyScore(isoDate: string): number {
   return 1 / (1 + days / 30);
 }
 
-function semanticScore(query: string, text: string): number {
-  const queryTokens = tokenize(query);
+function semanticScore(queryTokens: string[], queryPhrase: string, text: string): number {
   if (queryTokens.length === 0) {
     return 0;
   }
 
-  const haystack = text.toLowerCase();
+  const textTokenSet = new Set(tokenize(text));
+  if (textTokenSet.size === 0) {
+    return 0;
+  }
+
   let matched = 0;
   for (const token of queryTokens) {
-    if (haystack.includes(token)) {
+    if (textTokenSet.has(token)) {
       matched += 1;
     }
   }
 
   const overlap = matched / queryTokens.length;
-  const phraseBonus = haystack.includes(query.toLowerCase()) ? 0.25 : 0;
+  if (overlap <= 0) {
+    return 0;
+  }
+
+  const normalizedText = normalizeText(text);
+  const phraseBonus = queryPhrase && normalizedText.includes(queryPhrase) ? 0.15 : 0;
   return Math.min(1, overlap * 0.85 + phraseBonus);
 }
 
@@ -97,7 +136,7 @@ function groupRuleLinks(relations: RelationRecord[]): Map<string, string[]> {
 
 function buildSearchEntities(data: ContextData, includeContent: boolean): SearchEntity[] {
   const entities: SearchEntity[] = [];
-  const ruleLinks = groupRuleLinks(data.relations);
+  const fileRuleLinks = groupRuleLinks(data.relations);
   const adrPathSet = new Set(
     data.adrs
       .map((adr) => adr.path.trim().toLowerCase())
@@ -123,7 +162,7 @@ function buildSearchEntities(data: ContextData, includeContent: boolean): Search
       trust_level: document.trust_level,
       updated_at: document.updated_at,
       snippet: document.excerpt,
-      matched_rules: ruleLinks.get(document.id) ?? [],
+      matched_rules: fileRuleLinks.get(document.id) ?? [],
       content: includeContent ? document.content : undefined
     });
   }
@@ -164,6 +203,31 @@ function buildSearchEntities(data: ContextData, includeContent: boolean): Search
     });
   }
 
+  const filePathById = new Map(
+    data.documents
+      .filter((document) => document.kind === "CODE")
+      .map((document) => [document.id, document.path])
+  );
+
+  for (const chunk of data.chunks) {
+    const filePath = filePathById.get(chunk.file_id) ?? "";
+    entities.push({
+      id: chunk.id,
+      entity_type: "Chunk",
+      kind: chunk.kind || "chunk",
+      label: chunk.name || chunk.id,
+      path: filePath,
+      text: `${filePath}\n${chunk.name}\n${chunk.signature}\n${chunk.body}`,
+      status: chunk.status,
+      source_of_truth: chunk.source_of_truth,
+      trust_level: chunk.trust_level,
+      updated_at: chunk.updated_at,
+      snippet: chunk.body.slice(0, 500),
+      matched_rules: fileRuleLinks.get(chunk.file_id) ?? [],
+      content: includeContent ? chunk.body : undefined
+    });
+  }
+
   return entities;
 }
 
@@ -178,8 +242,26 @@ function relationDegree(relations: RelationRecord[]): Map<string, number> {
   return degrees;
 }
 
+function buildChunkPartOfRelations(data: ContextData): RelationRecord[] {
+  const relations: RelationRecord[] = [];
+  for (const chunk of data.chunks) {
+    if (!chunk.file_id) {
+      continue;
+    }
+
+    relations.push({
+      from: chunk.id,
+      to: chunk.file_id,
+      relation: "PART_OF",
+      note: "Chunk belongs to file"
+    });
+  }
+  return relations;
+}
+
 function entityCatalog(data: ContextData): Map<string, JsonObject> {
   const catalog = new Map<string, JsonObject>();
+  const fileById = new Map(data.documents.map((document) => [document.id, document]));
 
   for (const file of data.documents) {
     catalog.set(file.id, {
@@ -211,12 +293,29 @@ function entityCatalog(data: ContextData): Map<string, JsonObject> {
     });
   }
 
+  for (const chunk of data.chunks) {
+    const filePath = fileById.get(chunk.file_id)?.path ?? "";
+    const chunkEntity: JsonObject = {
+      id: chunk.id,
+      type: "Chunk",
+      label: chunk.name || chunk.id,
+      status: chunk.status,
+      source_of_truth: chunk.source_of_truth
+    };
+    if (filePath) {
+      chunkEntity.path = filePath;
+    }
+    catalog.set(chunk.id, chunkEntity);
+  }
+
   return catalog;
 }
 
 export async function runContextSearch(parsed: SearchParams): Promise<ToolPayload> {
   const data = await loadContextData();
   const degreeByEntity = relationDegree(data.relations);
+  const queryTokens = expandQueryTokens(Array.from(new Set(tokenize(parsed.query))));
+  const queryPhrase = normalizeText(parsed.query).trim();
   const candidates = buildSearchEntities(data, parsed.include_content).filter(
     (entity) => parsed.include_deprecated || entity.status.toLowerCase() !== "deprecated"
   );
@@ -228,12 +327,17 @@ export async function runContextSearch(parsed: SearchParams): Promise<ToolPayloa
 
   const results = candidates
     .map((entity) => {
-      const lexicalSemantic = semanticScore(parsed.query, entity.text);
+      const lexicalSemantic = semanticScore(queryTokens, queryPhrase, entity.text);
       const entityVector = embeddings.vectors.get(entity.id);
       const vectorSemantic =
         queryVector && entityVector
-          ? Math.max(0, Math.min(1, (cosineSimilarity(queryVector, entityVector) + 1) / 2))
+          ? Math.max(0, Math.min(1, cosineSimilarity(queryVector, entityVector)))
           : 0;
+      const hasRelevanceSignal =
+        lexicalSemantic >= MIN_LEXICAL_RELEVANCE || vectorSemantic >= MIN_VECTOR_RELEVANCE;
+      if (!hasRelevanceSignal) {
+        return null;
+      }
       const semantic =
         vectorSemantic > 0 ? vectorSemantic * 0.75 + lexicalSemantic * 0.25 : lexicalSemantic;
       const graphScore = Math.min(1, (degreeByEntity.get(entity.id) ?? 0) / 4);
@@ -247,7 +351,7 @@ export async function runContextSearch(parsed: SearchParams): Promise<ToolPayloa
       score += data.ranking.recency * dateScore;
 
       if (entity.source_of_truth) {
-        score += 0.1;
+        score += 0.1 * semantic;
       }
 
       return {
@@ -269,7 +373,7 @@ export async function runContextSearch(parsed: SearchParams): Promise<ToolPayloa
         content: parsed.include_content ? entity.content : undefined
       };
     })
-    .filter((result) => result.score > 0)
+    .filter((result): result is NonNullable<typeof result> => result !== null)
     .sort((a, b) => b.score - a.score)
     .slice(0, parsed.top_k);
 
@@ -291,6 +395,7 @@ export async function runContextSearch(parsed: SearchParams): Promise<ToolPayloa
 export async function runContextRelated(parsed: RelatedParams): Promise<ToolPayload> {
   const data = await loadContextData();
   const catalog = entityCatalog(data);
+  const relations = [...data.relations, ...buildChunkPartOfRelations(data)];
 
   if (!catalog.has(parsed.entity_id)) {
     return {
@@ -306,7 +411,7 @@ export async function runContextRelated(parsed: RelatedParams): Promise<ToolPayl
   const outgoing = new Map<string, RelationRecord[]>();
   const incoming = new Map<string, RelationRecord[]>();
 
-  for (const relation of data.relations) {
+  for (const relation of relations) {
     const outList = outgoing.get(relation.from) ?? [];
     outList.push(relation);
     outgoing.set(relation.from, outList);

package/scaffold/mcp/src/types.ts

@@ -41,10 +41,26 @@ export type AdrRecord = {
 export type RelationRecord = {
   from: string;
   to: string;
-  relation: "CONSTRAINS" | "IMPLEMENTS" | "SUPERSEDES";
+  relation: "CONSTRAINS" | "IMPLEMENTS" | "SUPERSEDES" | "CALLS" | "IMPORTS" | "PART_OF";
   note: string;
 };
 
+export type ChunkRecord = {
+  id: string;
+  file_id: string;
+  name: string;
+  kind: string;
+  signature: string;
+  body: string;
+  start_line: number;
+  end_line: number;
+  language: string;
+  updated_at: string;
+  source_of_truth: boolean;
+  trust_level: number;
+  status: string;
+};
+
 export type RankingWeights = {
   semantic: number;
   graph: number;
@@ -56,6 +72,7 @@ export type ContextData = {
   documents: DocumentRecord[];
   adrs: AdrRecord[];
   rules: RuleRecord[];
+  chunks: ChunkRecord[];
   relations: RelationRecord[];
   ranking: RankingWeights;
   source: "cache" | "ryu";
@@ -64,7 +81,7 @@ export type ContextData = {
 
 export type SearchEntity = {
   id: string;
-  entity_type: "File" | "Rule" | "ADR";
+  entity_type: "File" | "Rule" | "ADR" | "Chunk";
   kind: string;
   label: string;
   path: string;

package/scaffold/scripts/status.sh

@@ -49,12 +49,26 @@ const fs = require("node:fs");
 const embedManifestPath = process.argv[1];
 const data = JSON.parse(fs.readFileSync(embedManifestPath, "utf8"));
 const c = data.counts || {};
+const entities = Number(c.entities ?? 0);
+const output = Number(c.output ?? 0);
+const embedded = Number(c.embedded ?? 0);
+const failed = Number(c.failed ?? 0);
 console.log(`[status] embeddings generated_at=${data.generated_at}`);
 console.log(`[status] embeddings model=${data.model} dim=${data.dimensions ?? 0}`);
-console.log(`[status] embeddings entities=${c.entities ?? 0} output=${c.output ?? 0} embedded=${c.embedded ?? 0} reused=${c.reused ?? 0} failed=${c.failed ?? 0}`);
+console.log(`[status] embeddings entities=${entities} output=${output} embedded=${embedded} reused=${c.reused ?? 0} failed=${failed}`);
+if (embedded > 0 && output > 0 && failed === 0) {
+  console.log("[status] semantic_search=embedding+lexical (ready)");
+} else if (embedded > 0 && output > 0) {
+  console.log(`[status] semantic_search=embedding+lexical-partial (failed=${failed})`);
+} else if (entities > 0) {
+  console.log("[status] semantic_search=lexical-only (run: ./scripts/context.sh embed)");
+} else {
+  console.log("[status] semantic_search=lexical-only (no indexed entities)");
+}
 ' "$EMBED_MANIFEST"
 else
   echo "[status] embeddings manifest missing (run: ./scripts/context.sh embed)"
+  echo "[status] semantic_search=lexical-only (embeddings manifest missing)"
 fi
 
 node -e '