klypix-mcp 1.52.0 → 1.53.0

package/README.md

@@ -79,7 +79,7 @@ npx klypix-mcp conformance
 
 It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,
 truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.
-It verifies 12 required coordination behaviours — not the 18 tools, and not the retrieval engine.
+It verifies 12 required coordination behaviours — not the 19 tools, and not the retrieval engine.
 
 ---
 
@@ -383,7 +383,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 
 ---
 
-## The 18 verbs
+## The 19 verbs
 
 | Tool | What it does |
 |---|---|
@@ -398,6 +398,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_message` | Session-to-session coordination notes (24h TTL, never written into the brain) |
 | `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing |
 | `brain_connect` | Find and draw related-but-unlinked cards |
+| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context; Graphify artifacts are supported but never installed or run |
 | `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |
 | `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name and content |
@@ -406,7 +407,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `add_to_canvas` | Append cards/connections (positions preserved) |
 | `list_canvases` | List every `.klypix` in the vault |
 
-Exactly 18, machine-verifiable with `npx klypix-mcp doctor`.
+Exactly 19, machine-verifiable with `npx klypix-mcp doctor`.
 
 > **`canvas_view`:** no MCP Apps host has been observed rendering the UI resource yet — there is no
 > screenshot and no host-level test. Hosts without the extension get clean text, which is the path
@@ -598,7 +599,7 @@ Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or wi
 Issues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
 Questions or feedback: [hello@klypix.com](mailto:hello@klypix.com).
 
-The repository carries 38 test files, 34 of them in the `npm test` chain, covering the presence
+The repository carries 49 test files, 45 of them in the `npm test` chain, covering the presence
 lane and its cross-machine relay, the Context Gateway, supervisor hot-swap, auto-update, retrieval
 quality, decay, challenge, lenses, the format guard, the git tools (including a real `git merge`
 through the merge driver), uninstall, and conformance. Run them with `npm test` from a clone — they

package/bin/klypix-install.mjs

@@ -226,7 +226,7 @@ const flatten = (code) => code
     .replace(/\.\.\/src\/klypix-(core|format)\.mjs/g, './klypix-$1.mjs')
     // brain-doctor + agent-rules (the server's lazy `import('../src/brain-doctor.mjs')`
     // for the brain_doctor tool) → flat sibling refs in the runtime layout.
-    .replace(/\.\.\/src\/(brain-doctor|agent-rules|mcp-presence|mcp-supervisor|mcp-auto-update|semantic-memory|runtime-inspector)\.mjs/g, './$1.mjs')
+    .replace(/\.\.\/src\/(brain-doctor|agent-rules|mcp-presence|mcp-supervisor|mcp-auto-update|semantic-memory|runtime-inspector|project-graph)\.mjs/g, './$1.mjs')
     .replace(/klypix-worker\.mjs/g, 'klypix-mcp-worker.mjs')
     .replace(/const PKG_VERSION = \(\(\) => \{[\s\S]*?\}\)\(\);/, `const PKG_VERSION = '${VERSION}'; // baked at install (flat layout has no package.json)`);
 
@@ -293,7 +293,7 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [

package/bin/klypix-worker.mjs

@@ -30,6 +30,7 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
 } from '../src/klypix-core.mjs';
+import { projectGraphContextMarkdown, queryProjectGraph } from '../src/project-graph.mjs';
 import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
 import {
@@ -201,6 +202,7 @@ const toContent = (r) => {
     ? { type: 'image', data: b.data, mimeType: b.mime }
     : { type: 'text', text: b.text });
   const result = r.isError ? { content, isError: true } : { content };
+  if (r.structured && typeof r.structured === 'object') result.structuredContent = r.structured;
   return mcpPresence.decorateToolResult(result);
 };
 
@@ -242,6 +244,67 @@ server.registerTool('brain_ask', {
   },
 }, async ({ question, canvas, as_of, k }) => toContent(await opBrainAsk({ vault: mcpPresence.vault, canvas, question, as_of, k, log })));
 
+server.registerTool('project_map_context', {
+  title: 'Project Map context - current code structure plus brain decisions',
+  description: 'Read-only combined context for a coding question. It queries a provider-neutral, bounded view of the generated project graph (Graphify graphify-out/graph.json is supported first) and places that CURRENT CODE evidence beside fast, correction-aware KLYPIX brain cards (decisions and rationale). KLYPIX never installs or runs Graphify and never copies graph nodes into brain.klypix. Missing graph artifacts degrade cleanly to brain-only context. Source-file anchors are accepted only when they stay inside the declared project root. Set deep_history:true only when superseded history is genuinely needed; the default never loads the local embedding model.',
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  inputSchema: {
+    question: z.string().min(1).describe('Question or code concept to ground in both current structure and project memory.'),
+    project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
+    graph_path: z.string().optional().describe('Optional project-relative graph JSON path. Defaults to graphify-out/graph.json and may not escape the project root.'),
+    depth: z.number().optional().describe('Relationship hops around the best code matches (0-3, default 1).'),
+    max_nodes: z.number().optional().describe('Maximum code nodes returned (default 60, capped 200).'),
+    k: z.number().optional().describe('Maximum brain cards returned (default 8; fast mode caps 8, deep history caps 20).'),
+    deep_history: z.boolean().optional().describe('false (default) uses the sub-second lexical-fast correction-aware path; true opts into whole-brain semantic/history retrieval, which may cold-load the local model.'),
+  },
+}, async ({ question, project, graph_path, depth, max_nodes, k, deep_history }) => {
+  let graphResult;
+  let graphMarkdown;
+  try {
+    graphResult = queryProjectGraph({
+      project: project || mcpPresence.vault,
+      graphPath: graph_path,
+      query: question,
+      depth,
+      maxNodes: max_nodes,
+    });
+    graphMarkdown = projectGraphContextMarkdown(graphResult);
+  } catch (error) {
+    graphResult = { schemaVersion: 1, status: 'invalid', error: error?.message || String(error) };
+    graphMarkdown = `# Project Map\n\nThe generated graph could not be read safely: ${graphResult.error}`;
+  }
+  const graphFiles = Array.isArray(graphResult?.nodes)
+    ? [...new Set(graphResult.nodes.map(node => node.sourceFile).filter(Boolean))].slice(0, 20)
+    : [];
+  const brainResult = deep_history
+    ? await opBrainAsk({
+      vault: mcpPresence.vault,
+      question,
+      k: Math.max(1, Math.min(20, Number(k) || 8)),
+      log,
+    })
+    : await opBrainTaskContext({
+      vault: mcpPresence.vault,
+      intent: question,
+      files: graphFiles,
+      k: Math.max(1, Math.min(8, Number(k) || 8)),
+      budgetChars: 4_500,
+    });
+  const brainMarkdown = brainResult.blocks
+    .filter(block => block.kind === 'text')
+    .map(block => block.text)
+    .join('\n\n');
+  return toContent({
+    blocks: [{ kind: 'text', text: `${graphMarkdown}\n\n---\n\n# Project Brain - ${deep_history ? 'decisions and history' : 'current decisions and corrections'}\n\n${brainMarkdown}` }],
+    isError: brainResult.isError,
+    structured: { projectGraph: graphResult, brainContext: brainResult.context || null, deepHistory: deep_history === true },
+  });
+});
+
 server.registerTool('brain_challenge', {
   title: 'Challenge a decision against the brain (argue back with receipts)',
   description: 'BEFORE committing to a significant decision, ask the brain to ARGUE BACK: prior decisions that deterministically contradict the claim (correction-cue / opposite-polarity evidence — never mere topical similarity), 🛠 standing rules that dispute it, approaches tried before and REVERSED (with the correction/successor as the receipt), and open questions it collides with. Candidates, not verdicts — silence means "no deterministic contradiction signal", not verified consistency. Cards captured by a DIFFERENT agent are flagged so you coordinate instead of overriding. Dismiss a confirmed-false pair (after capturing the claim) with brain_connect pairs + relationship:"not_contradiction". Defaults to the project brain ("brain").',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.52.0",
+  "version": "1.53.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -56,6 +56,7 @@
     "./supervisor": "./src/mcp-supervisor.mjs",
     "./runtime-inspector": "./src/runtime-inspector.mjs",
     "./runtime": "./src/runtime-inspector.mjs",
+    "./project-graph": "./src/project-graph.mjs",
     "./auto-update": "./src/mcp-auto-update.mjs"
   },
   "files": [
@@ -73,19 +74,20 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test:project-graph": "node test/project-graph.mjs",
+    "test": "node test/project-graph.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/ext-apps": "^1.7.4",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "fractional-indexing": "^3.2.0",
     "jszip": "^3.10.1",
     "zod": "^4.3.6"
   },
-  "optionalDependencies": {
+  "devDependencies": {
     "@huggingface/transformers": "^4.2.0"
   }
 }

package/src/project-graph.mjs

@@ -0,0 +1,340 @@
+// Provider-neutral, read-only project-graph adapter.
+//
+// Graphify is the first supported producer, but callers only see the stable
+// KLYPIX shape below. Generated graph artifacts remain disposable local cache:
+// this module never runs Graphify, edits source, or writes into brain.klypix.
+
+import fs from 'fs';
+import path from 'path';
+
+export const PROJECT_GRAPH_SCHEMA_VERSION = 1;
+export const DEFAULT_PROJECT_GRAPH = 'graphify-out/graph.json';
+export const DEFAULT_PROJECT_GRAPH_HTML = 'graphify-out/graph.html';
+export const DEFAULT_PROJECT_GRAPH_REPORT = 'graphify-out/GRAPH_REPORT.md';
+
+const MAX_GRAPH_BYTES = 64 * 1024 * 1024;
+const MAX_GRAPH_NODES = 100_000;
+const MAX_GRAPH_EDGES = 500_000;
+const MAX_QUERY_NODES = 200;
+const MAX_QUERY_EDGES = 600;
+const CACHE_TTL_MS = 60_000;
+
+let cache = null;
+
+const clamp = (value, min, max, fallback) => {
+  const n = Number(value);
+  return Number.isFinite(n) ? Math.max(min, Math.min(max, Math.floor(n))) : fallback;
+};
+
+const normalizedCase = (value) => process.platform === 'win32'
+  ? value.toLocaleLowerCase('en-US')
+  : value;
+
+function isInside(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!relative.startsWith(`..${path.sep}`) && relative !== '..' && !path.isAbsolute(relative));
+}
+
+function realRoot(project) {
+  const resolved = path.resolve(String(project || process.cwd()));
+  const real = fs.realpathSync(resolved);
+  const stat = fs.statSync(real);
+  if (!stat.isDirectory()) throw new Error(`Project root is not a directory: ${resolved}`);
+  return real;
+}
+
+function resolveInsideProject(projectRoot, requested, fallback) {
+  const candidate = path.resolve(projectRoot, String(requested || fallback));
+  if (!isInside(normalizedCase(projectRoot), normalizedCase(candidate))) {
+    throw new Error('Project graph path must stay inside the project root.');
+  }
+  if (!fs.existsSync(candidate)) return candidate;
+  const real = fs.realpathSync(candidate);
+  if (!isInside(normalizedCase(projectRoot), normalizedCase(real))) {
+    throw new Error('Project graph path resolves outside the project root.');
+  }
+  return real;
+}
+
+function relativePortable(root, file) {
+  return path.relative(root, file).split(path.sep).join('/');
+}
+
+function safeSourceFile(root, value) {
+  if (typeof value !== 'string' || !value.trim()) return null;
+  const original = value.trim().replace(/\\/g, '/');
+  const foreignAbsolute = /^[A-Za-z]:[\\/]/.test(value) || /^\\\\/.test(value);
+  if (foreignAbsolute && !path.isAbsolute(value)) return null;
+  const candidate = path.isAbsolute(value)
+    ? path.resolve(value)
+    : path.resolve(root, ...original.split('/'));
+  if (!isInside(normalizedCase(root), normalizedCase(candidate))) return null;
+  const relative = relativePortable(root, candidate);
+  return relative && relative !== '.' ? relative : null;
+}
+
+function shortString(value, max = 1_000) {
+  if (value == null) return '';
+  return String(value).replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g, '').slice(0, max);
+}
+
+function normalizeConfidence(edge) {
+  const raw = shortString(edge?.confidence, 32).toUpperCase();
+  if (raw === 'EXTRACTED' || raw === 'INFERRED' || raw === 'AMBIGUOUS') return raw;
+  return edge?.confidence_score == null ? 'EXTRACTED' : 'INFERRED';
+}
+
+function normalizeGraph(raw, projectRoot, artifact) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+    throw new Error('graph.json must contain a JSON object.');
+  }
+  const rawNodes = Array.isArray(raw.nodes) ? raw.nodes : null;
+  const rawEdges = Array.isArray(raw.edges) ? raw.edges : Array.isArray(raw.links) ? raw.links : null;
+  if (!rawNodes || !rawEdges) {
+    throw new Error('Unsupported project graph: expected NetworkX node-link arrays named nodes and edges (or links).');
+  }
+  if (rawNodes.length > MAX_GRAPH_NODES || rawEdges.length > MAX_GRAPH_EDGES) {
+    throw new Error(`Project graph exceeds the safe in-process limit (${MAX_GRAPH_NODES.toLocaleString()} nodes / ${MAX_GRAPH_EDGES.toLocaleString()} edges).`);
+  }
+
+  const nodes = [];
+  const byId = new Map();
+  let unsafeSourcePaths = 0;
+  let duplicateNodes = 0;
+  for (const input of rawNodes) {
+    if (!input || typeof input !== 'object') continue;
+    const id = shortString(input.id, 512);
+    if (!id) continue;
+    if (byId.has(id)) { duplicateNodes++; continue; }
+    const originalSource = input.source_file ?? input.path;
+    const sourceFile = safeSourceFile(projectRoot, originalSource);
+    if (originalSource && !sourceFile) unsafeSourcePaths++;
+    const node = {
+      id,
+      label: shortString(input.label ?? input.name ?? id, 1_000),
+      kind: shortString(input.kind ?? input.type ?? input.file_type ?? 'symbol', 120),
+      sourceFile,
+      sourceLocation: shortString(input.source_location ?? input.location, 240) || null,
+      community: shortString(input.community, 160) || null,
+      origin: shortString(input._origin ?? input.origin, 160) || null,
+    };
+    byId.set(id, node);
+    nodes.push(node);
+  }
+
+  const edges = [];
+  const adjacency = new Map(nodes.map(node => [node.id, []]));
+  let danglingEdges = 0;
+  for (const input of rawEdges) {
+    if (!input || typeof input !== 'object') continue;
+    const source = shortString(input.source, 512);
+    const target = shortString(input.target, 512);
+    if (!source || !target || !byId.has(source) || !byId.has(target)) {
+      danglingEdges++;
+      continue;
+    }
+    const edge = {
+      source,
+      target,
+      relation: shortString(input.relation ?? input.type ?? 'related_to', 160),
+      confidence: normalizeConfidence(input),
+    };
+    const index = edges.length;
+    edges.push(edge);
+    adjacency.get(source).push({ nodeId: target, edgeIndex: index });
+    if (source !== target) adjacency.get(target).push({ nodeId: source, edgeIndex: index });
+  }
+
+  return {
+    schemaVersion: PROJECT_GRAPH_SCHEMA_VERSION,
+    provider: 'graphify',
+    artifact,
+    nodes,
+    edges,
+    byId,
+    adjacency,
+    diagnostics: {
+      unsafeSourcePaths,
+      duplicateNodes,
+      danglingEdges,
+      inputNodes: rawNodes.length,
+      inputEdges: rawEdges.length,
+      acceptedNodes: nodes.length,
+      acceptedEdges: edges.length,
+    },
+  };
+}
+
+function cacheLimitBytes() {
+  const configured = Number(process.env.KLYPIX_PROJECT_GRAPH_CACHE_MB);
+  const mb = Number.isFinite(configured) ? Math.max(0, Math.min(64, configured)) : 12;
+  return Math.floor(mb * 1024 * 1024);
+}
+
+export function discoverProjectGraph({ project, graphPath } = {}) {
+  const projectRoot = realRoot(project);
+  const filePath = resolveInsideProject(projectRoot, graphPath, DEFAULT_PROJECT_GRAPH);
+  const artifactDir = path.dirname(filePath);
+  const htmlPath = resolveInsideProject(projectRoot, path.join(artifactDir, 'graph.html'), DEFAULT_PROJECT_GRAPH_HTML);
+  const reportPath = resolveInsideProject(projectRoot, path.join(artifactDir, 'GRAPH_REPORT.md'), DEFAULT_PROJECT_GRAPH_REPORT);
+  const provider = path.basename(artifactDir).toLocaleLowerCase('en-US') === 'graphify-out' ? 'graphify' : 'project-graph';
+  if (!fs.existsSync(filePath)) {
+    return {
+      schemaVersion: PROJECT_GRAPH_SCHEMA_VERSION,
+      provider,
+      status: 'missing',
+      projectRoot,
+      filePath,
+      artifact: {
+        graphJson: relativePortable(projectRoot, filePath),
+        graphHtml: fs.existsSync(htmlPath) ? relativePortable(projectRoot, htmlPath) : null,
+        report: fs.existsSync(reportPath) ? relativePortable(projectRoot, reportPath) : null,
+      },
+    };
+  }
+  const stat = fs.statSync(filePath);
+  if (!stat.isFile()) throw new Error('Project graph path is not a file.');
+  if (stat.size > MAX_GRAPH_BYTES) {
+    throw new Error(`Project graph is ${(stat.size / 1024 / 1024).toFixed(1)} MB; the safe read limit is ${MAX_GRAPH_BYTES / 1024 / 1024} MB.`);
+  }
+  return {
+    schemaVersion: PROJECT_GRAPH_SCHEMA_VERSION,
+    provider,
+    status: 'ready',
+    projectRoot,
+    filePath,
+    artifact: {
+      graphJson: relativePortable(projectRoot, filePath),
+      graphHtml: fs.existsSync(htmlPath) ? relativePortable(projectRoot, htmlPath) : null,
+      report: fs.existsSync(reportPath) ? relativePortable(projectRoot, reportPath) : null,
+      sizeBytes: stat.size,
+      modifiedAt: stat.mtime.toISOString(),
+    },
+    stat,
+  };
+}
+
+export function loadProjectGraph(options = {}) {
+  const found = discoverProjectGraph(options);
+  if (found.status !== 'ready') return { ...found, graph: null };
+  const key = `${found.filePath}:${found.stat.size}:${found.stat.mtimeMs}`;
+  if (cache?.key === key && Date.now() - cache.loadedAt < CACHE_TTL_MS) {
+    return { ...found, graph: cache.graph, cache: 'hit' };
+  }
+  const json = fs.readFileSync(found.filePath, 'utf8');
+  let raw;
+  try { raw = JSON.parse(json); }
+  catch (error) { throw new Error(`Project graph is not valid JSON: ${error?.message || error}`); }
+  const graph = normalizeGraph(raw, found.projectRoot, found.artifact);
+  graph.provider = found.provider;
+  if (found.stat.size <= cacheLimitBytes()) cache = { key, graph, loadedAt: Date.now() };
+  else cache = null;
+  return { ...found, graph, cache: 'miss' };
+}
+
+function queryTokens(value) {
+  return [...new Set(String(value || '').toLocaleLowerCase('en-US').match(/[\p{L}\p{N}_./:@#$-]+/gu) || [])]
+    .filter(token => token.length > 1)
+    .slice(0, 32);
+}
+
+function scoreNode(node, query, tokens, degree) {
+  const label = node.label.toLocaleLowerCase('en-US');
+  const source = (node.sourceFile || '').toLocaleLowerCase('en-US');
+  const haystack = `${label} ${source} ${node.kind} ${node.community || ''}`.toLocaleLowerCase('en-US');
+  let score = Math.min(3, Math.log2(1 + degree));
+  if (query && label === query) score += 60;
+  else if (query && source === query) score += 55;
+  else if (query && label.includes(query)) score += 28;
+  else if (query && source.includes(query)) score += 24;
+  for (const token of tokens) {
+    if (label === token) score += 14;
+    else if (label.includes(token)) score += 8;
+    if (source.includes(token)) score += 7;
+    if (haystack.includes(token)) score += 2;
+  }
+  return score;
+}
+
+export function queryProjectGraph({ project, graphPath, query = '', depth = 1, maxNodes = 60 } = {}) {
+  const loaded = loadProjectGraph({ project, graphPath });
+  if (!loaded.graph) return { ...loaded, query: String(query || ''), nodes: [], edges: [] };
+  const graph = loaded.graph;
+  const normalizedQuery = String(query || '').trim().toLocaleLowerCase('en-US');
+  const tokens = queryTokens(query);
+  const cap = clamp(maxNodes, 1, MAX_QUERY_NODES, 60);
+  const hopLimit = clamp(depth, 0, 3, 1);
+  const ranked = graph.nodes
+    .map(node => ({ node, score: scoreNode(node, normalizedQuery, tokens, graph.adjacency.get(node.id)?.length || 0) }))
+    .filter(hit => !tokens.length || hit.score > 0)
+    .sort((a, b) => b.score - a.score || a.node.label.localeCompare(b.node.label));
+  const seeds = ranked.slice(0, Math.min(tokens.length ? 12 : cap, cap));
+  const selected = new Set();
+  const queue = seeds.map(hit => ({ id: hit.node.id, depth: 0 }));
+  while (queue.length && selected.size < cap) {
+    const current = queue.shift();
+    if (selected.has(current.id)) continue;
+    selected.add(current.id);
+    if (current.depth >= hopLimit) continue;
+    const neighbors = graph.adjacency.get(current.id) || [];
+    for (const neighbor of neighbors) {
+      if (!selected.has(neighbor.nodeId) && selected.size + queue.length < cap * 3) {
+        queue.push({ id: neighbor.nodeId, depth: current.depth + 1 });
+      }
+    }
+  }
+  const nodeScore = new Map(ranked.map(hit => [hit.node.id, hit.score]));
+  const nodes = [...selected]
+    .map(id => graph.byId.get(id))
+    .filter(Boolean)
+    .sort((a, b) => (nodeScore.get(b.id) || 0) - (nodeScore.get(a.id) || 0));
+  const edges = graph.edges
+    .filter(edge => selected.has(edge.source) && selected.has(edge.target))
+    .slice(0, MAX_QUERY_EDGES);
+  return {
+    schemaVersion: PROJECT_GRAPH_SCHEMA_VERSION,
+    provider: graph.provider,
+    status: 'ready',
+    query: String(query || ''),
+    depth: hopLimit,
+    artifact: graph.artifact,
+    counts: {
+      graphNodes: graph.nodes.length,
+      graphEdges: graph.edges.length,
+      returnedNodes: nodes.length,
+      returnedEdges: edges.length,
+    },
+    diagnostics: graph.diagnostics,
+    nodes,
+    edges,
+    cache: loaded.cache,
+  };
+}
+
+export function projectGraphContextMarkdown(result) {
+  if (result.status === 'missing') {
+    return `# Project Map\n\nNo supported project graph was found at \`${result.artifact.graphJson}\`. KLYPIX did not install or run a provider. Generate the artifact with Graphify, then retry.`;
+  }
+  const lines = result.nodes.map(node => {
+    const where = node.sourceFile ? ` — \`${node.sourceFile}${node.sourceLocation ? `:${node.sourceLocation}` : ''}\`` : '';
+    return `- **${node.label || node.id}** (${node.kind || 'symbol'})${where} · id \`${node.id}\``;
+  });
+  const edgeLines = result.edges.slice(0, 80).map(edge =>
+    `- \`${edge.source}\` —${edge.relation}→ \`${edge.target}\` [${edge.confidence}]`);
+  const warnings = [];
+  if (result.diagnostics?.unsafeSourcePaths) warnings.push(`${result.diagnostics.unsafeSourcePaths} unsafe/out-of-root source path(s) were withheld`);
+  if (result.diagnostics?.danglingEdges) warnings.push(`${result.diagnostics.danglingEdges} dangling edge(s) were ignored`);
+  return [
+    '# Project Map — code evidence',
+    `Provider artifact: \`${result.artifact.graphJson}\` · ${result.counts.graphNodes.toLocaleString()} nodes · ${result.counts.graphEdges.toLocaleString()} edges · query \`${result.query || '(overview)'}\`.`,
+    warnings.length ? `Safety note: ${warnings.join('; ')}.` : '',
+    '## Relevant code nodes',
+    lines.join('\n') || '_No matching code nodes._',
+    edgeLines.length ? '## Relationships\n' + edgeLines.join('\n') : '',
+    '_Graph evidence describes the current generated artifact; brain cards below remain the source for decisions, corrections, and project history._',
+  ].filter(Boolean).join('\n\n');
+}
+
+export function clearProjectGraphCache() {
+  cache = null;
+}