@danielblomma/cortex-mcp 2.0.18 → 2.1.0

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:
@@ -97,7 +123,7 @@ cortex init --bootstrap
 
 This will:
 
-- scaffold `.context/`, `scripts/`, `mcp/`, `.githooks/`, and docs files
+- scaffold `.context/`, `.context/scripts/`, `.context/mcp/`, `.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)

package/bin/cortex.mjs

@@ -27,11 +27,14 @@ 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_SCRIPTS_REL = path.join(".context", "scripts");
 
+// `.context/*` (not `.context/`) so the !-negations below actually re-include
+// the config files — git can't re-include children of an excluded directory.
 const GITIGNORE_LINES = [
   "",
   "# Cortex local storage",
-  ".context/",
+  ".context/*",
   "!.context/config.yaml",
   "!.context/rules.yaml",
   "!.context/ontology.cypher",
@@ -188,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",
@@ -407,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:",
@@ -461,12 +467,73 @@ function migrateLegacyMcpLocation(targetDir) {
   );
 }
 
+const LEGACY_SCRIPT_ENTRIES = [
+  "bootstrap.sh",
+  "context.sh",
+  "dashboard.mjs",
+  "dashboard.sh",
+  "doctor.sh",
+  "embed.sh",
+  "ingest.mjs",
+  "ingest.sh",
+  "install-git-hooks.sh",
+  "load-kuzu.sh",
+  "load-ryu.sh",
+  "memory-compile.mjs",
+  "memory-compile.sh",
+  "memory-lint.mjs",
+  "memory-lint.sh",
+  "refresh.sh",
+  "status.sh",
+  "update-context.sh",
+  "watch.sh",
+  "lib",
+  "parsers"
+];
+
+function looksLikeLegacyCortexScriptsDir(scriptsDir) {
+  const contextScript = path.join(scriptsDir, "context.sh");
+  if (!fs.existsSync(contextScript)) {
+    return false;
+  }
+  try {
+    const contents = fs.readFileSync(contextScript, "utf8");
+    return contents.includes("bootstrap)") && contents.includes("graph-load)") && contents.includes("memory-lint)");
+  } catch {
+    return false;
+  }
+}
+
+function removeLegacyCortexScripts(targetDir) {
+  if (path.resolve(targetDir) === PACKAGE_ROOT) {
+    return;
+  }
+
+  const scriptsDir = path.join(targetDir, "scripts");
+  if (!looksLikeLegacyCortexScriptsDir(scriptsDir)) {
+    return;
+  }
+
+  for (const entry of LEGACY_SCRIPT_ENTRIES) {
+    fs.rmSync(path.join(scriptsDir, entry), { recursive: true, force: true });
+  }
+
+  try {
+    if (fs.existsSync(scriptsDir) && fs.readdirSync(scriptsDir).length === 0) {
+      fs.rmdirSync(scriptsDir);
+    }
+  } catch {
+    // Best effort. A user's own files in scripts/ must remain untouched.
+  }
+}
+
 function installScaffold(targetDir, force) {
   migrateLegacyMcpLocation(targetDir);
+  removeLegacyCortexScripts(targetDir);
 
   const copyMap = [
     [path.join(SCAFFOLD_ROOT, ".context"), path.join(targetDir, ".context")],
-    [path.join(SCAFFOLD_ROOT, "scripts"), path.join(targetDir, "scripts")],
+    [path.join(SCAFFOLD_ROOT, "scripts"), path.join(targetDir, CONTEXT_SCRIPTS_REL)],
     [path.join(SCAFFOLD_ROOT, "mcp"), path.join(targetDir, MCP_PROJECT_REL)],
     [path.join(SCAFFOLD_ROOT, ".githooks"), path.join(targetDir, ".githooks")]
   ];
@@ -720,7 +787,7 @@ async function connectMcpClients(targetDir, options = {}) {
 }
 
 async function maybeInstallGitHooks(targetDir) {
-  const installScript = path.join(targetDir, "scripts", "install-git-hooks.sh");
+  const installScript = path.join(targetDir, CONTEXT_SCRIPTS_REL, "install-git-hooks.sh");
   if (!fs.existsSync(installScript)) {
     return false;
   }
@@ -758,16 +825,17 @@ function isTruthyEnv(value) {
 function canAutoInitialize(targetDir) {
   // Legacy mcp/ at root no longer counted — pre-v2.0.5 projects are migrated
   // by installScaffold rather than blocking auto-init.
-  const scaffoldPaths = [".context", "scripts", ".githooks"].map((entry) => path.join(targetDir, entry));
+  const scaffoldPaths = [".context", ".githooks"].map((entry) => path.join(targetDir, entry));
   return scaffoldPaths.every((entryPath) => !fs.existsSync(entryPath));
 }
 
 function isScaffoldOutOfDate(targetDir) {
-  const contextScript = path.join(targetDir, "scripts", "context.sh");
+  const contextScript = path.join(targetDir, CONTEXT_SCRIPTS_REL, "context.sh");
+  const legacyContextScript = path.join(targetDir, "scripts", "context.sh");
   if (!fs.existsSync(contextScript)) {
-    return false;
+    return fs.existsSync(legacyContextScript);
   }
-  const doctorScript = path.join(targetDir, "scripts", "doctor.sh");
+  const doctorScript = path.join(targetDir, CONTEXT_SCRIPTS_REL, "doctor.sh");
   if (!fs.existsSync(doctorScript)) {
     return true;
   }
@@ -812,7 +880,7 @@ async function maybeMigrateScaffold(targetDir, command) {
 
   console.error(
     `[cortex] scaffold in ${targetDir} is out of date ` +
-      `(missing scripts/doctor.sh, .context/mcp/package.json, doctor subcommand in context.sh, ` +
+      `(missing .context/scripts/doctor.sh, .context/mcp/package.json, doctor subcommand in context.sh, ` +
       `or carries a legacy mcp/ directory at the project root).`
   );
 
@@ -881,7 +949,7 @@ async function ensureProjectInitializedForMcp(targetDir) {
 }
 
 async function runContextCommand(cwd, contextArgs) {
-  const contextScript = path.join(cwd, "scripts", "context.sh");
+  const contextScript = path.join(cwd, CONTEXT_SCRIPTS_REL, "context.sh");
   if (!fs.existsSync(contextScript)) {
     throw new Error(`Missing ${contextScript}. Run 'cortex init' first.`);
   }
@@ -915,7 +983,7 @@ async function run() {
     await maybeInstallGitHooks(target);
 
     console.log(`[cortex] initialized in ${target}`);
-    console.log("[cortex] scaffold copied: .context/, scripts/, mcp/, .githooks/, docs/");
+    console.log("[cortex] scaffold copied: .context/, .context/scripts/, .context/mcp/, .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");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@danielblomma/cortex-mcp",
   "mcpName": "io.github.DanielBlomma/cortex",
-  "version": "2.0.18",
+  "version": "2.1.0",
   "description": "Local, repo-scoped context platform for coding assistants. Semantic search, graph relationships, and architectural rule context.",
   "type": "module",
   "author": "Daniel Blomma",
@@ -49,7 +49,8 @@
     "docs/MCP_MARKETPLACE.md"
   ],
   "scripts": {
-    "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",
+    "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/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

@@ -1,19 +1,21 @@
 repo_id: cortex
 source_paths:
-  - src
+  - scripts
+  - mcp/src
   - docs
-  - design
   - .context/notes
   - .context/decisions
-  - README.md
 truth_order:
   - ADR
   - 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/.githooks/_cortex-update-runner.sh

@@ -6,12 +6,12 @@ if [[ -z "$REPO_ROOT" ]]; then
   exit 0
 fi
 
-CONTEXT_SCRIPT="$REPO_ROOT/scripts/context.sh"
+CONTEXT_SCRIPT="$REPO_ROOT/.context/scripts/context.sh"
 if [[ ! -x "$CONTEXT_SCRIPT" ]]; then
   exit 0
 fi
 
-PARSER_MODULES_DIR="$REPO_ROOT/scripts/parsers/node_modules"
+PARSER_MODULES_DIR="$REPO_ROOT/.context/scripts/parsers/node_modules"
 
 HOOK_DIR="$REPO_ROOT/.context/hooks"
 LOCK_DIR="$HOOK_DIR/update.lock"

package/scaffold/mcp/package-lock.json

@@ -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/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,22 +412,20 @@ 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));
 
@@ -531,7 +525,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/embeddings.ts

@@ -101,7 +101,7 @@ export function loadEmbeddingIndex(): EmbeddingIndex {
     embeddingsCache = {
       model: null,
       vectors: new Map(),
-      warning: "Embedding index missing (run: ./scripts/context.sh embed)"
+      warning: "Embedding index missing (run: cortex embed)"
     };
     return embeddingsCache;
   }

package/scaffold/mcp/src/graph.ts

@@ -419,8 +419,8 @@ function readGraphSignature(): string | null {
 
 function buildMissingDbMessage(): string {
   const dbDir = path.dirname(DB_PATH);
-  const loadCommand = "./scripts/context.sh graph-load";
-  const bootstrapCommand = "./scripts/context.sh bootstrap";
+  const loadCommand = "cortex graph-load";
+  const bootstrapCommand = "cortex bootstrap";
 
   if (!fs.existsSync(dbDir)) {
     return `RyuGraph directory missing at ${dbDir}. Run ${bootstrapCommand}.`;
@@ -430,7 +430,7 @@ function buildMissingDbMessage(): string {
 }
 
 function buildIncompatibleGraphMessage(missingKeys: string[]): string {
-  const loadCommand = "./scripts/context.sh graph-load";
+  const loadCommand = "cortex graph-load";
   const missing = missingKeys.join(", ");
   return `RyuGraph manifest is missing schema keys (${missing}). Run ${loadCommand} to rebuild the graph DB.`;
 }

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/bootstrap.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 MCP_DIR="$REPO_ROOT/.context/mcp"
 TOTAL_STEPS=6
 STEP_INDEX=0
@@ -25,24 +26,24 @@ mkdir -p "$MCP_DIR/.npm-cache"
 step "Installing MCP dependencies"
 info "note: upstream RyuGraph dependencies may print deprecation warnings during install"
 NPM_CONFIG_CACHE="$MCP_DIR/.npm-cache" npm --prefix "$MCP_DIR" install --no-fund --no-update-notifier --loglevel=warn
-NPM_CONFIG_CACHE="$REPO_ROOT/scripts/parsers/.npm-cache" npm --prefix "$REPO_ROOT/scripts/parsers" install --no-fund --no-update-notifier --loglevel=warn
+NPM_CONFIG_CACHE="$REPO_ROOT/.context/scripts/parsers/.npm-cache" npm --prefix "$REPO_ROOT/.context/scripts/parsers" install --no-fund --no-update-notifier --loglevel=warn
 
-source "$REPO_ROOT/scripts/lib/enterprise-check.sh"
+source "$SCRIPT_DIR/lib/enterprise-check.sh"
 
 step "Indexing repository context"
-"$REPO_ROOT/scripts/ingest.sh"
+"$SCRIPT_DIR/ingest.sh"
 
 step "Generating semantic embeddings"
-if ! "$REPO_ROOT/scripts/embed.sh"; then
+if ! "$SCRIPT_DIR/embed.sh"; then
   info "warning: embedding generation failed; continuing with lexical search fallback"
 fi
 
 step "Loading RyuGraph"
-"$REPO_ROOT/scripts/load-ryu.sh"
+"$SCRIPT_DIR/load-ryu.sh"
 
 step "Reading context status"
-"$REPO_ROOT/scripts/status.sh"
+"$SCRIPT_DIR/status.sh"
 
 echo ""
 info "bootstrap complete"
-info "next: run ./scripts/context.sh update while coding"
+info "next: run cortex update while coding"

package/scaffold/scripts/context.sh

@@ -5,7 +5,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 print_help() {
   cat <<'EOF'
-Usage: ./scripts/context.sh <command> [options]
+Usage: cortex <command> [options]
 
 Commands:
   bootstrap                        Install deps + full ingest + graph load

package/scaffold/scripts/dashboard.mjs

@@ -6,7 +6,9 @@ import { execSync } from "node:child_process";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const REPO_ROOT = path.resolve(__dirname, "..");
+const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
+  ? path.resolve(process.env.CORTEX_PROJECT_ROOT)
+  : path.resolve(__dirname, "..", "..");
 const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
 const CONFIG_PATH = path.join(CONTEXT_DIR, "config.yaml");

package/scaffold/scripts/dashboard.sh

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 MANIFEST="$REPO_ROOT/.context/cache/manifest.json"
 
 if [[ ! -f "$MANIFEST" ]]; then

package/scaffold/scripts/doctor.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 CONTEXT_DIR="$REPO_ROOT/.context"
 MCP_DIR="$CONTEXT_DIR/mcp"
 

package/scaffold/scripts/embed.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 MCP_DIR="$REPO_ROOT/.context/mcp"
 
 if ! command -v npm >/dev/null 2>&1; then

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;
     })
   ];
 
@@ -91,7 +95,9 @@ async function loadOptionalParsers() {
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const REPO_ROOT = path.resolve(__dirname, "..");
+const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
+  ? path.resolve(process.env.CORTEX_PROJECT_ROOT)
+  : path.resolve(__dirname, "..", "..");
 const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 const CACHE_DIR = path.join(CONTEXT_DIR, "cache");
 const DB_IMPORT_DIR = path.join(CONTEXT_DIR, "db", "import");
@@ -162,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",
@@ -296,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/ingest.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 CONTEXT_DIR="$REPO_ROOT/.context"
 
 printf "[ingest] repo: %s\n" "$REPO_ROOT"
@@ -17,4 +18,4 @@ if ! command -v node >/dev/null 2>&1; then
   exit 1
 fi
 
-node "$REPO_ROOT/scripts/ingest.mjs" "$@"
+node "$SCRIPT_DIR/ingest.mjs" "$@"

package/scaffold/scripts/install-git-hooks.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 HOOKS_DIR="$REPO_ROOT/.githooks"
 
 if [[ ! -d "$HOOKS_DIR" ]]; then

package/scaffold/scripts/load-kuzu.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 echo "[graph-load] warning: load-kuzu.sh is deprecated; using RyuGraph loader"
-"$REPO_ROOT/scripts/load-ryu.sh" "$@"
+"$SCRIPT_DIR/load-ryu.sh" "$@"

package/scaffold/scripts/load-ryu.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 MCP_DIR="$REPO_ROOT/.context/mcp"
 
 if [[ ! -f "$MCP_DIR/package.json" ]]; then

package/scaffold/scripts/memory-compile.mjs

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseFrontmatter, parseStringList } from "../.context/mcp/dist/frontmatter.js";
+import { parseFrontmatter, parseStringList } from "../mcp/dist/frontmatter.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -17,7 +17,7 @@ function normalizeForWsl(rawPath) {
 
 const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
   ? path.resolve(normalizeForWsl(process.env.CORTEX_PROJECT_ROOT))
-  : path.resolve(__dirname, "..");
+  : path.resolve(__dirname, "..", "..");
 const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 const MEMORY_DIR = path.join(CONTEXT_DIR, "memory");
 const RAW_DIR = path.join(MEMORY_DIR, "raw");

package/scaffold/scripts/memory-compile.sh

@@ -2,7 +2,8 @@
 # Keep in sync with scripts/memory-compile.sh
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 CONTEXT_DIR="$REPO_ROOT/.context"
 
 printf "[memory-compile] repo: %s\n" "$REPO_ROOT"
@@ -17,4 +18,4 @@ if ! command -v node >/dev/null 2>&1; then
   exit 1
 fi
 
-node "$REPO_ROOT/scripts/memory-compile.mjs" "$@"
+CORTEX_PROJECT_ROOT="$REPO_ROOT" node "$SCRIPT_DIR/memory-compile.mjs" "$@"

package/scaffold/scripts/memory-lint.mjs

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { parseFrontmatter, parseStringList } from "../.context/mcp/dist/frontmatter.js";
+import { parseFrontmatter, parseStringList } from "../mcp/dist/frontmatter.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -17,7 +17,7 @@ function normalizeForWsl(rawPath) {
 
 const REPO_ROOT = process.env.CORTEX_PROJECT_ROOT
   ? path.resolve(normalizeForWsl(process.env.CORTEX_PROJECT_ROOT))
-  : path.resolve(__dirname, "..");
+  : path.resolve(__dirname, "..", "..");
 const CONTEXT_DIR = path.join(REPO_ROOT, ".context");
 const MEMORY_DIR = path.join(CONTEXT_DIR, "memory");
 const COMPILED_DIR = path.join(MEMORY_DIR, "compiled");

package/scaffold/scripts/memory-lint.sh

@@ -2,7 +2,8 @@
 # Keep in sync with scripts/memory-lint.sh
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 CONTEXT_DIR="$REPO_ROOT/.context"
 
 printf "[memory-lint] repo: %s\n" "$REPO_ROOT"
@@ -17,4 +18,4 @@ if ! command -v node >/dev/null 2>&1; then
   exit 1
 fi
 
-node "$REPO_ROOT/scripts/memory-lint.mjs" "$@"
+CORTEX_PROJECT_ROOT="$REPO_ROOT" node "$SCRIPT_DIR/memory-lint.mjs" "$@"

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: [] };
+}

package/scaffold/scripts/parsers/package-lock.json

@@ -21,7 +21,6 @@
       "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.16.0.tgz",
       "integrity": "sha512-UVJyE9MttOsBQIDKw1skb9nAwQuR5wuGD3+82K6JgJlm/Y+KI92oNsMNGZCYdDsVtRHSak0pcV5Dno5+4jh9sw==",
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },

package/scaffold/scripts/refresh.sh

@@ -1,9 +1,9 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 echo "[refresh] running ingestion"
-"$REPO_ROOT/scripts/ingest.sh" "$@"
+"$SCRIPT_DIR/ingest.sh" "$@"
 
 echo "[refresh] done"

package/scaffold/scripts/status.sh

@@ -1,14 +1,15 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 MANIFEST="$REPO_ROOT/.context/cache/manifest.json"
 GRAPH_MANIFEST="$REPO_ROOT/.context/cache/graph-manifest.json"
 EMBED_MANIFEST="$REPO_ROOT/.context/embeddings/manifest.json"
 
 if [[ ! -f "$MANIFEST" ]]; then
   echo "[status] No ingest manifest found."
-  echo "[status] Run: ./scripts/context.sh ingest"
+  echo "[status] Run: cortex ingest"
   exit 0
 fi
 
@@ -47,7 +48,7 @@ console.log(`[status] graph files=${c.files ?? 0} rules=${c.rules ?? 0} adrs=${c
 console.log(`[status] graph rels constrains=${c.constrains ?? 0} implements=${c.implements ?? 0} supersedes=${c.supersedes ?? 0}`);
 ' "$GRAPH_MANIFEST"
 else
-  echo "[status] graph manifest missing (run: ./scripts/context.sh graph-load)"
+  echo "[status] graph manifest missing (run: cortex graph-load)"
 fi
 
 if [[ -f "$EMBED_MANIFEST" ]]; then
@@ -68,13 +69,13 @@ if (embedded > 0 && output > 0 && failed === 0) {
 } 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)");
+  console.log("[status] semantic_search=lexical-only (run: cortex 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] embeddings manifest missing (run: cortex embed)"
   echo "[status] semantic_search=lexical-only (embeddings manifest missing)"
 fi
 

package/scaffold/scripts/update-context.sh

@@ -1,18 +1,18 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 
 echo "[update] ingesting changed files"
-"$REPO_ROOT/scripts/ingest.sh" --changed
+"$SCRIPT_DIR/ingest.sh" --changed
 
 echo "[update] embedding changed entities"
-if ! "$REPO_ROOT/scripts/embed.sh" --changed; then
+if ! "$SCRIPT_DIR/embed.sh" --changed; then
   echo "[update] warning: embedding generation failed; continuing with lexical search fallback"
 fi
 
 echo "[update] rebuilding graph"
-"$REPO_ROOT/scripts/load-ryu.sh"
+"$SCRIPT_DIR/load-ryu.sh"
 
 echo "[update] status"
-"$REPO_ROOT/scripts/status.sh"
+"$SCRIPT_DIR/status.sh"

package/scaffold/scripts/watch.sh

@@ -1,7 +1,8 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 WATCH_DIR="$REPO_ROOT/.context/watch"
 PID_FILE="$WATCH_DIR/watch.pid"
 STAMP_FILE="$WATCH_DIR/last-stamp.sha1"
@@ -21,7 +22,7 @@ EVENT_BACKEND=""
 
 print_usage() {
   cat <<'USAGE'
-Usage: ./scripts/watch.sh [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
+Usage: cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
 
 Commands:
   start     Start background watch loop
@@ -149,8 +150,8 @@ status_digest() {
   # .context/ excludes the relocated .context/mcp/ tree as well.
   find "$REPO_ROOT" -type f \
     ! -path "$REPO_ROOT/.context/*" \
-    ! -path "$REPO_ROOT/scripts/parsers/node_modules/*" \
-    ! -path "$REPO_ROOT/scripts/parsers/.npm-cache/*" \
+    ! -path "$REPO_ROOT/.context/scripts/parsers/node_modules/*" \
+    ! -path "$REPO_ROOT/.context/scripts/parsers/.npm-cache/*" \
     -print \
     | LC_ALL=C sort \
     | shasum -a 1 \
@@ -162,7 +163,7 @@ run_update() {
   start_ts="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
   echo "[watch] update start at $start_ts"
 
-  if bash "$REPO_ROOT/scripts/context.sh" update; then
+  if bash "$SCRIPT_DIR/context.sh" update; then
     echo "[watch] update success"
     return 0
   fi
@@ -199,15 +200,13 @@ wait_for_change_event() {
     inotifywait)
       inotifywait -q -r \
         -e modify,create,delete,move \
-        --exclude '(^|/)\\.git(/|$)|(^|/)\\.context(/|$)|(^|/)scripts/parsers/(node_modules|\\.npm-cache)(/|$)' \
+        --exclude '(^|/)\\.git(/|$)|(^|/)\\.context(/|$)' \
         "$REPO_ROOT" >/dev/null 2>&1 || true
       ;;
     fswatch)
       fswatch -1 -r \
         --exclude '(^|/)\\.git(/|$)' \
         --exclude '(^|/)\\.context(/|$)' \
-        --exclude '(^|/)scripts/parsers/node_modules(/|$)' \
-        --exclude '(^|/)scripts/parsers/\\.npm-cache(/|$)' \
         "$REPO_ROOT" >/dev/null 2>&1 || true
       ;;
     *)