@infinitedusky/indusk-mcp 1.13.2 → 1.14.1

package/dist/bin/cli.js

@@ -290,6 +290,29 @@ eval_
     const { evalBaseline } = await import("./commands/eval.js");
     await evalBaseline(process.cwd(), opts);
 });
+program
+    .command("beam <file>")
+    .description("Get file-specific context from all sources")
+    .option("--trace", "Show query trace")
+    .option("--json", "Output as JSON")
+    .action(async (file, opts) => {
+    const { runBeam } = await import("../lib/beam/runner.js");
+    const { formatBeamMarkdown, formatBeamTrace } = await import("../lib/beam/format.js");
+    const result = await runBeam({
+        projectRoot: process.cwd(),
+        targetPath: file,
+        trace: opts.trace ?? false,
+    });
+    if (opts.json) {
+        console.info(JSON.stringify(result, null, 2));
+    }
+    else if (opts.trace) {
+        console.info(formatBeamTrace(result));
+    }
+    else {
+        console.info(formatBeamMarkdown(result));
+    }
+});
 program
     .command("serve")
     .description("Start the MCP server (used by Claude Code via .mcp.json)")

package/dist/bin/commands/extensions.js

@@ -115,7 +115,18 @@ export async function extensionsEnable(projectRoot, names) {
             printMcpSetup(projectRoot, name);
             continue;
         }
-        console.info(`  ${name}: not found — use 'extensions add ${name} --from <source>' for third-party`);
+        // Try npm as last resort
+        console.info(`  ${name}: not built-in, trying npm...`);
+        try {
+            await extensionsAdd(projectRoot, name, name);
+            if (isEnabled(projectRoot, name)) {
+                continue;
+            }
+        }
+        catch {
+            // npm lookup failed, fall through
+        }
+        console.info(`  ${name}: not found as built-in or npm package — use 'extensions add ${name} --from <source>' for third-party`);
     }
 }
 export async function extensionsDisable(projectRoot, names) {
@@ -190,13 +201,36 @@ export async function extensionsAdd(projectRoot, name, from) {
         }
     }
     else {
-        // Local path
+        // Local path — or fall back to npm if file doesn't exist
         if (existsSync(from)) {
             manifestContent = readFileSync(from, "utf-8");
         }
         else {
-            console.info(`  ${name}: file not found at ${from}`);
-            return;
+            // Try as npm package name
+            const pkg = from;
+            try {
+                const tmpDir = join(projectRoot, ".indusk/tmp");
+                mkdirSync(tmpDir, { recursive: true });
+                execSync(`npm pack ${pkg} --pack-destination "${tmpDir}"`, {
+                    encoding: "utf-8",
+                    timeout: 30000,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+                const tarballs = readdirSync(tmpDir).filter((f) => f.endsWith(".tgz"));
+                if (tarballs.length > 0) {
+                    try {
+                        manifestContent = execSync(`tar -xzf "${join(tmpDir, tarballs[tarballs.length - 1])}" -O package/indusk-extension.json`, { encoding: "utf-8", timeout: 10000 });
+                    }
+                    catch {
+                        console.info(`  ${name}: no indusk-extension.json found in npm package ${pkg}`);
+                    }
+                }
+                rmSync(tmpDir, { recursive: true, force: true });
+            }
+            catch {
+                console.info(`  ${name}: not found as local file or npm package: ${from}`);
+                return;
+            }
         }
     }
     if (!manifestContent)

package/dist/bin/commands/infra.js

@@ -99,7 +99,7 @@ export async function infraStart() {
     if (!hasImage) {
         console.error(`Docker image '${IMAGE_NAME}' not found.`);
         console.error("");
-        console.error("Build it from the infinitedusky repo:");
+        console.error("Build it from the dusk repo:");
         console.error("  docker build -f docker/Dockerfile.infra -t indusk-infra .");
         console.error("");
         console.error("Or pull from GHCR (when published):");

package/dist/lib/beam/format.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Format beam results as markdown for agent consumption.
+ */
+import type { BeamResult } from "./types.js";
+export declare function formatBeamMarkdown(result: BeamResult): string;
+export declare function formatBeamCompact(result: BeamResult): string;
+export declare function formatBeamTrace(result: BeamResult): string;

package/dist/lib/beam/format.js

@@ -0,0 +1,90 @@
+/**
+ * Format beam results as markdown for agent consumption.
+ */
+export function formatBeamMarkdown(result) {
+    const lines = [];
+    lines.push(`## Context for ${result.target}\n`);
+    // Distance 0 items
+    const d0 = result.items.filter((i) => i.distance === 0);
+    if (d0.length > 0) {
+        lines.push("### This file (distance 0)\n");
+        for (const item of d0) {
+            const prefix = item.source === "eval" ? "⚠" : "•";
+            lines.push(`${prefix} **${item.source}**: ${item.content}`);
+        }
+        lines.push("");
+    }
+    // Distance 1 items grouped by source
+    const d1 = result.items.filter((i) => i.distance === 1);
+    if (d1.length > 0) {
+        const structural = d1.filter((i) => i.source === "semantic-graph");
+        const facts = d1.filter((i) => i.source === "graphiti");
+        const cgc = d1.filter((i) => i.source === "cgc");
+        if (structural.length > 0) {
+            lines.push("### Structural neighbors (distance 1)\n");
+            for (const item of structural) {
+                lines.push(`- ${item.content}`);
+            }
+            lines.push("");
+        }
+        if (facts.length > 0) {
+            lines.push("### Neighbor facts\n");
+            for (const item of facts) {
+                lines.push(`- ${item.content}`);
+            }
+            lines.push("");
+        }
+        if (cgc.length > 0) {
+            lines.push("### Function dependencies\n");
+            for (const item of cgc) {
+                lines.push(`- ${item.content}`);
+            }
+            lines.push("");
+        }
+    }
+    // Distance 2 items
+    const d2 = result.items.filter((i) => i.distance === 2);
+    if (d2.length > 0) {
+        lines.push("### Extended context (distance 2)\n");
+        for (const item of d2) {
+            lines.push(`- ${item.content}`);
+        }
+        lines.push("");
+    }
+    lines.push(`*${result.items.length} items, ${result.durationMs}ms*`);
+    return lines.join("\n");
+}
+export function formatBeamCompact(result) {
+    const lines = [];
+    lines.push(`📡 [beam] ${result.target}`);
+    const d0 = result.items.filter((i) => i.distance === 0);
+    for (const item of d0) {
+        const prefix = item.source === "eval" ? "  ⚠" : "  •";
+        lines.push(`${prefix} ${item.content}`);
+    }
+    const neighbors = result.items
+        .filter((i) => i.distance === 1 && i.source === "semantic-graph")
+        .map((i) => i.metadata.path?.split("/").pop() ?? "")
+        .filter(Boolean);
+    if (neighbors.length > 0) {
+        lines.push(`  → neighbors: ${neighbors.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+export function formatBeamTrace(result) {
+    if (!result.trace)
+        return "(no trace data)";
+    const lines = [];
+    lines.push(`[beam] target: ${result.target}\n`);
+    for (const step of result.trace) {
+        lines.push(`[${step.query}] ${step.source} (${step.durationMs}ms)`);
+        lines.push(`  → ${step.resultCount} results`);
+        for (const r of step.results) {
+            lines.push(`    - ${r}`);
+        }
+        lines.push("");
+    }
+    lines.push(`[assembly] ${result.items.length} items total — ${result.items.filter((i) => i.distance === 0).length} high-signal (d0), ${result.items.filter((i) => i.distance === 1).length} awareness (d1)`);
+    lines.push(`[timing] ${result.durationMs}ms total`);
+    return lines.join("\n");
+}

package/dist/lib/beam/graph-client.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Lightweight FalkorDB client for beam queries.
+ *
+ * Wraps a connection to the semantic-{project} graph with a generic query
+ * method. The beam needs ad-hoc Cypher queries that don't fit the
+ * SemanticGraphClient's event-replay API.
+ */
+export declare class BeamGraphClient {
+    private readonly host;
+    private readonly port;
+    private db;
+    private graph;
+    private readonly graphName;
+    constructor(projectName: string, host?: string, port?: number);
+    connect(): Promise<void>;
+    query<T extends Record<string, unknown>>(cypher: string, params?: Record<string, unknown>): Promise<T[]>;
+    close(): Promise<void>;
+}

package/dist/lib/beam/graph-client.js

@@ -0,0 +1,41 @@
+/**
+ * Lightweight FalkorDB client for beam queries.
+ *
+ * Wraps a connection to the semantic-{project} graph with a generic query
+ * method. The beam needs ad-hoc Cypher queries that don't fit the
+ * SemanticGraphClient's event-replay API.
+ */
+import { FalkorDB } from "falkordb";
+const DEFAULT_HOST = "localhost";
+const DEFAULT_PORT = 6379;
+export class BeamGraphClient {
+    host;
+    port;
+    db;
+    graph;
+    graphName;
+    constructor(projectName, host = DEFAULT_HOST, port = DEFAULT_PORT) {
+        this.host = host;
+        this.port = port;
+        this.graphName = `semantic-${projectName}`;
+    }
+    async connect() {
+        if (this.db && this.graph)
+            return;
+        this.db = await FalkorDB.connect({ socket: { host: this.host, port: this.port } });
+        this.graph = this.db.selectGraph(this.graphName);
+    }
+    async query(cypher, params) {
+        if (!this.graph)
+            throw new Error("BeamGraphClient: call connect() first");
+        const result = await this.graph.query(cypher, params ? { params } : undefined);
+        return result.data ?? [];
+    }
+    async close() {
+        if (this.db) {
+            await this.db.close();
+            this.db = undefined;
+            this.graph = undefined;
+        }
+    }
+}

package/dist/lib/beam/pipeline.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Pipeline definition — the ordered list of query steps.
+ *
+ * This is the single place to add, remove, or reorder queries.
+ * The runner executes this list; it doesn't know about specific data sources.
+ */
+import type { QueryStep } from "./types.js";
+/**
+ * The beam pipeline. Each step is a discrete query.
+ *
+ * Execution groups (for parallelism):
+ * - Group A (independent): anchor-lookup, target-facts, eval-findings
+ * - Group B (depends on neighbors): structural-neighbors, then neighbor-facts, cgc-relationships
+ */
+export declare const BEAM_PIPELINE: QueryStep[];

package/dist/lib/beam/pipeline.js

@@ -0,0 +1,27 @@
+/**
+ * Pipeline definition — the ordered list of query steps.
+ *
+ * This is the single place to add, remove, or reorder queries.
+ * The runner executes this list; it doesn't know about specific data sources.
+ */
+import { anchorLookup } from "./queries/anchor-lookup.js";
+import { cgcRelationships } from "./queries/cgc-relationships.js";
+import { evalFindings } from "./queries/eval-findings.js";
+import { neighborFacts } from "./queries/neighbor-facts.js";
+import { structuralNeighbors } from "./queries/structural-neighbors.js";
+import { targetFacts } from "./queries/target-facts.js";
+/**
+ * The beam pipeline. Each step is a discrete query.
+ *
+ * Execution groups (for parallelism):
+ * - Group A (independent): anchor-lookup, target-facts, eval-findings
+ * - Group B (depends on neighbors): structural-neighbors, then neighbor-facts, cgc-relationships
+ */
+export const BEAM_PIPELINE = [
+    anchorLookup,
+    structuralNeighbors,
+    targetFacts,
+    neighborFacts,
+    evalFindings,
+    cgcRelationships,
+];

package/dist/lib/beam/queries/anchor-lookup.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Query 1: Find the target file's anchor in the semantic graph.
+ * Distance 0 — the starting point for the beam.
+ */
+import type { QueryStep } from "../types.js";
+export declare const anchorLookup: QueryStep;

package/dist/lib/beam/queries/anchor-lookup.js

@@ -0,0 +1,32 @@
+/**
+ * Query 1: Find the target file's anchor in the semantic graph.
+ * Distance 0 — the starting point for the beam.
+ */
+import { BeamGraphClient } from "../graph-client.js";
+export const anchorLookup = {
+    name: "anchor-lookup",
+    source: "semantic-graph",
+    distance: 0,
+    maxResults: 1,
+    detail: "full",
+    async execute(ctx) {
+        const client = new BeamGraphClient(ctx.projectName);
+        try {
+            await client.connect();
+            const rows = await client.query("MATCH (a:Anchor {path: $path, status: 'active'}) RETURN a.uuid AS uuid, a.kind AS kind, a.path AS path", { path: ctx.targetAbsolutePath });
+            return rows.map((row) => ({
+                source: "semantic-graph",
+                distance: 0,
+                detail: "full",
+                content: `Anchor: ${row.kind} at ${row.path}`,
+                metadata: { path: String(row.path) },
+            }));
+        }
+        catch {
+            return [];
+        }
+        finally {
+            await client.close();
+        }
+    },
+};

package/dist/lib/beam/queries/cgc-relationships.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Query 6: CGC callers/callees — function-level dependencies.
+ * Distance 1, summary detail.
+ */
+import type { QueryStep } from "../types.js";
+export declare const cgcRelationships: QueryStep;

package/dist/lib/beam/queries/cgc-relationships.js

@@ -0,0 +1,54 @@
+/**
+ * Query 6: CGC callers/callees — function-level dependencies.
+ * Distance 1, summary detail.
+ */
+import { FalkorDB } from "falkordb";
+export const cgcRelationships = {
+    name: "cgc-relationships",
+    source: "cgc",
+    distance: 1,
+    maxResults: 10,
+    detail: "summary",
+    async execute(ctx) {
+        const graphName = `cgc-${ctx.projectName}`;
+        let db;
+        try {
+            db = await FalkorDB.connect({ socket: { host: "localhost", port: 6379 } });
+            const graph = db.selectGraph(graphName);
+            // Find functions in the target file and their callers/callees
+            // CGC IMPORTS: File → Module. CONTAINS: File → Function/Class.
+            // Find what this file imports (modules) and what files contain functions that call into this file.
+            const rows = await graph.query(`MATCH (f:File {relative_path: $path})-[r:IMPORTS]->(m:Module)
+				 RETURN m.name AS name, 'imports' AS relationship, m.name AS path
+				 UNION
+				 MATCH (f:File {relative_path: $path})-[:CONTAINS]->(fn)-[:CALLS]->(callee)<-[:CONTAINS]-(other:File)
+				 WHERE other.relative_path <> $path AND other.is_dependency = false
+				 RETURN other.relative_path AS name, 'calls-into' AS relationship, other.relative_path AS path
+				 UNION
+				 MATCH (other:File)-[:CONTAINS]->(fn)-[:CALLS]->(callee)<-[:CONTAINS]-(f:File {relative_path: $path})
+				 WHERE other.relative_path <> $path AND other.is_dependency = false
+				 RETURN other.relative_path AS name, 'called-by' AS relationship, other.relative_path AS path`, { params: { path: ctx.targetRelativePath } });
+            const data = rows.data ?? [];
+            return data.map((row) => {
+                const neighborPath = String(row.path);
+                return {
+                    source: "cgc",
+                    distance: 1,
+                    detail: "summary",
+                    content: `${row.relationship}: ${neighborPath}`,
+                    metadata: {
+                        path: neighborPath,
+                        relationship: String(row.relationship),
+                    },
+                };
+            });
+        }
+        catch {
+            return [];
+        }
+        finally {
+            if (db)
+                await db.close();
+        }
+    },
+};

package/dist/lib/beam/queries/eval-findings.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Query 5: Unresolved eval findings referencing the target file.
+ * Distance 0, full detail. These are active warnings.
+ */
+import type { QueryStep } from "../types.js";
+export declare const evalFindings: QueryStep;

package/dist/lib/beam/queries/eval-findings.js

@@ -0,0 +1,32 @@
+/**
+ * Query 5: Unresolved eval findings referencing the target file.
+ * Distance 0, full detail. These are active warnings.
+ */
+import { getUnresolvedFindings } from "../../eval/findings.js";
+export const evalFindings = {
+    name: "eval-findings",
+    source: "eval",
+    distance: 0,
+    maxResults: 10,
+    detail: "full",
+    async execute(ctx) {
+        try {
+            const findings = getUnresolvedFindings(ctx.projectRoot);
+            const relevant = findings.filter((f) => f.finding.includes(ctx.targetPath) ||
+                f.finding.includes(ctx.targetPath.split("/").pop() ?? ""));
+            return relevant.map((f) => ({
+                source: "eval",
+                distance: 0,
+                detail: "full",
+                content: `[${f.severity}] ${f.questionId}: ${f.finding}`,
+                metadata: {
+                    path: ctx.targetPath,
+                    severity: f.severity,
+                },
+            }));
+        }
+        catch {
+            return [];
+        }
+    },
+};

package/dist/lib/beam/queries/neighbor-facts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Query 4: Graphiti facts for structural neighbors.
+ * Distance 1, summary detail.
+ */
+import type { QueryStep } from "../types.js";
+export declare const neighborFacts: QueryStep;

package/dist/lib/beam/queries/neighbor-facts.js

@@ -0,0 +1,31 @@
+/**
+ * Query 4: Graphiti facts for structural neighbors.
+ * Distance 1, summary detail.
+ */
+import { GraphitiClient } from "../../graphiti-client.js";
+export const neighborFacts = {
+    name: "neighbor-facts",
+    source: "graphiti",
+    distance: 1,
+    maxResults: 5,
+    detail: "summary",
+    async execute(ctx) {
+        if (ctx.neighbors.length === 0)
+            return [];
+        try {
+            const client = new GraphitiClient(ctx.projectRoot);
+            const query = ctx.neighbors.slice(0, 10).join(", ");
+            const facts = await client.searchFacts(query, { maxResults: 5 });
+            return facts.map((f) => ({
+                source: "graphiti",
+                distance: 1,
+                detail: "summary",
+                content: f.fact ?? "(no fact text)",
+                metadata: { factId: f.uuid },
+            }));
+        }
+        catch {
+            return [];
+        }
+    },
+};

package/dist/lib/beam/queries/structural-neighbors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Query 2: Structural neighbors — files that import or are imported by the target.
+ * Distance 1. Populates ctx.neighbors for downstream queries.
+ */
+import type { QueryStep } from "../types.js";
+export declare const structuralNeighbors: QueryStep;

package/dist/lib/beam/queries/structural-neighbors.js

@@ -0,0 +1,41 @@
+/**
+ * Query 2: Structural neighbors — files that import or are imported by the target.
+ * Distance 1. Populates ctx.neighbors for downstream queries.
+ */
+import { BeamGraphClient } from "../graph-client.js";
+export const structuralNeighbors = {
+    name: "structural-neighbors",
+    source: "semantic-graph",
+    distance: 1,
+    maxResults: 20,
+    detail: "summary",
+    async execute(ctx) {
+        const client = new BeamGraphClient(ctx.projectName);
+        try {
+            await client.connect();
+            const rows = await client.query(`MATCH (a:Anchor {path: $path})-[r]-(neighbor:Anchor)
+				 WHERE neighbor.status = 'active'
+				 RETURN neighbor.path AS path, neighbor.kind AS kind, type(r) AS relationship,
+				        COALESCE(neighbor.importance, 0) AS importance, COALESCE(r.weight, 1) AS weight
+				 ORDER BY weight DESC, importance DESC`, { path: ctx.targetAbsolutePath });
+            // Populate neighbors on context for downstream queries
+            ctx.neighbors = rows.map((r) => String(r.path));
+            return rows.map((row) => ({
+                source: "semantic-graph",
+                distance: 1,
+                detail: "summary",
+                content: `${row.relationship}: ${row.path}`,
+                metadata: {
+                    path: String(row.path),
+                    relationship: String(row.relationship),
+                },
+            }));
+        }
+        catch {
+            return [];
+        }
+        finally {
+            await client.close();
+        }
+    },
+};

package/dist/lib/beam/queries/target-facts.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Query 3: Graphiti facts for the target file.
+ * Distance 0, full detail.
+ */
+import type { QueryStep } from "../types.js";
+export declare const targetFacts: QueryStep;

package/dist/lib/beam/queries/target-facts.js

@@ -0,0 +1,32 @@
+/**
+ * Query 3: Graphiti facts for the target file.
+ * Distance 0, full detail.
+ */
+import { GraphitiClient } from "../../graphiti-client.js";
+export const targetFacts = {
+    name: "target-facts",
+    source: "graphiti",
+    distance: 0,
+    maxResults: 10,
+    detail: "full",
+    async execute(ctx) {
+        try {
+            const client = new GraphitiClient(ctx.projectRoot);
+            const facts = await client.searchFacts(ctx.targetPath, { maxResults: 10 });
+            return facts.map((f) => ({
+                source: "graphiti",
+                distance: 0,
+                detail: "full",
+                content: f.fact ?? "(no fact text)",
+                metadata: {
+                    path: ctx.targetPath,
+                    timestamp: f.valid_at ?? undefined,
+                    factId: f.uuid,
+                },
+            }));
+        }
+        catch {
+            return [];
+        }
+    },
+};

package/dist/lib/beam/runner.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Pipeline runner — executes beam query steps and assembles results.
+ *
+ * Queries run in two groups:
+ * - Group A (independent): anchor-lookup, target-facts, eval-findings
+ * - Group B (needs neighbors): structural-neighbors first, then neighbor-facts, cgc-relationships
+ */
+import type { BeamResult } from "./types.js";
+export interface BeamOptions {
+    projectRoot: string;
+    targetPath: string;
+    trace?: boolean;
+}
+export declare function runBeam(opts: BeamOptions): Promise<BeamResult>;

package/dist/lib/beam/runner.js

@@ -0,0 +1,145 @@
+/**
+ * Pipeline runner — executes beam query steps and assembles results.
+ *
+ * Queries run in two groups:
+ * - Group A (independent): anchor-lookup, target-facts, eval-findings
+ * - Group B (needs neighbors): structural-neighbors first, then neighbor-facts, cgc-relationships
+ */
+import { basename, isAbsolute, join, relative } from "node:path";
+import { BEAM_PIPELINE } from "./pipeline.js";
+export async function runBeam(opts) {
+    const start = Date.now();
+    const projectName = basename(opts.projectRoot);
+    // Resolve both absolute and relative forms of the target path
+    const absolutePath = isAbsolute(opts.targetPath)
+        ? opts.targetPath
+        : join(opts.projectRoot, opts.targetPath);
+    const relativePath = isAbsolute(opts.targetPath)
+        ? relative(opts.projectRoot, opts.targetPath)
+        : opts.targetPath;
+    const ctx = {
+        projectRoot: opts.projectRoot,
+        projectName,
+        targetPath: opts.targetPath,
+        targetAbsolutePath: absolutePath,
+        targetRelativePath: relativePath,
+        neighbors: [],
+        trace: opts.trace ?? false,
+    };
+    const allItems = [];
+    const traceSteps = [];
+    // Group A: independent queries (anchor-lookup, target-facts, eval-findings)
+    const groupA = BEAM_PIPELINE.filter((s) => s.name === "anchor-lookup" || s.name === "target-facts" || s.name === "eval-findings");
+    // Group B1: structural-neighbors (must run before neighbor-facts and cgc)
+    const structuralStep = BEAM_PIPELINE.find((s) => s.name === "structural-neighbors");
+    // Group B2: depends on neighbors
+    const groupB2 = BEAM_PIPELINE.filter((s) => s.name === "neighbor-facts" || s.name === "cgc-relationships");
+    // Run Group A in parallel
+    const groupAResults = await Promise.all(groupA.map(async (step) => {
+        const stepStart = Date.now();
+        try {
+            const items = await step.execute(ctx);
+            if (ctx.trace) {
+                traceSteps.push({
+                    query: step.name,
+                    source: step.source,
+                    durationMs: Date.now() - stepStart,
+                    resultCount: items.length,
+                    results: items.map((i) => i.content.slice(0, 100)),
+                });
+            }
+            return items;
+        }
+        catch {
+            if (ctx.trace) {
+                traceSteps.push({
+                    query: step.name,
+                    source: step.source,
+                    durationMs: Date.now() - stepStart,
+                    resultCount: 0,
+                    results: ["(query failed)"],
+                });
+            }
+            return [];
+        }
+    }));
+    for (const items of groupAResults)
+        allItems.push(...items);
+    // Run structural-neighbors (populates ctx.neighbors)
+    if (structuralStep) {
+        const stepStart = Date.now();
+        try {
+            const items = await structuralStep.execute(ctx);
+            allItems.push(...items);
+            if (ctx.trace) {
+                traceSteps.push({
+                    query: structuralStep.name,
+                    source: structuralStep.source,
+                    durationMs: Date.now() - stepStart,
+                    resultCount: items.length,
+                    results: items.map((i) => i.content.slice(0, 100)),
+                });
+            }
+        }
+        catch {
+            if (ctx.trace) {
+                traceSteps.push({
+                    query: structuralStep.name,
+                    source: structuralStep.source,
+                    durationMs: Date.now() - stepStart,
+                    resultCount: 0,
+                    results: ["(query failed)"],
+                });
+            }
+        }
+    }
+    // Run Group B2 in parallel (now that neighbors are populated)
+    const groupB2Results = await Promise.all(groupB2.map(async (step) => {
+        const stepStart = Date.now();
+        try {
+            const items = await step.execute(ctx);
+            if (ctx.trace) {
+                traceSteps.push({
+                    query: step.name,
+                    source: step.source,
+                    durationMs: Date.now() - stepStart,
+                    resultCount: items.length,
+                    results: items.map((i) => i.content.slice(0, 100)),
+                });
+            }
+            return items;
+        }
+        catch {
+            if (ctx.trace) {
+                traceSteps.push({
+                    query: step.name,
+                    source: step.source,
+                    durationMs: Date.now() - stepStart,
+                    resultCount: 0,
+                    results: ["(query failed)"],
+                });
+            }
+            return [];
+        }
+    }));
+    for (const items of groupB2Results)
+        allItems.push(...items);
+    // Assembly: sort by distance (0 first), then eval findings first, then by timestamp (recent first)
+    allItems.sort((a, b) => {
+        if (a.distance !== b.distance)
+            return a.distance - b.distance;
+        if (a.source === "eval" && b.source !== "eval")
+            return -1;
+        if (b.source === "eval" && a.source !== "eval")
+            return 1;
+        const aTime = a.metadata.timestamp ? new Date(a.metadata.timestamp).getTime() : 0;
+        const bTime = b.metadata.timestamp ? new Date(b.metadata.timestamp).getTime() : 0;
+        return bTime - aTime;
+    });
+    return {
+        target: opts.targetPath,
+        items: allItems,
+        trace: ctx.trace ? traceSteps : undefined,
+        durationMs: Date.now() - start,
+    };
+}

package/dist/lib/beam/types.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Types for the context beam query pipeline.
+ *
+ * The beam radiates outward from a target file, collecting context from
+ * multiple data sources with distance-based relevance decay.
+ */
+export interface BeamItem {
+    source: "semantic-graph" | "graphiti" | "eval" | "cgc";
+    distance: 0 | 1 | 2;
+    detail: "full" | "summary" | "name";
+    content: string;
+    metadata: {
+        path?: string;
+        relationship?: string;
+        timestamp?: string;
+        severity?: string;
+        factId?: string;
+    };
+}
+export interface BeamTraceStep {
+    query: string;
+    source: string;
+    durationMs: number;
+    resultCount: number;
+    results: string[];
+}
+export interface BeamResult {
+    target: string;
+    items: BeamItem[];
+    trace?: BeamTraceStep[];
+    durationMs: number;
+}
+export interface QueryContext {
+    projectRoot: string;
+    projectName: string;
+    targetPath: string;
+    targetAbsolutePath: string;
+    targetRelativePath: string;
+    neighbors: string[];
+    trace: boolean;
+}
+export interface QueryStep {
+    name: string;
+    source: "semantic-graph" | "graphiti" | "eval" | "cgc";
+    distance: 0 | 1 | 2;
+    maxResults: number;
+    detail: "full" | "summary" | "name";
+    execute: (ctx: QueryContext) => Promise<BeamItem[]>;
+}

package/dist/lib/beam/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the context beam query pipeline.
+ *
+ * The beam radiates outward from a target file, collecting context from
+ * multiple data sources with distance-based relevance decay.
+ */
+export {};

package/dist/lib/eval/prompt-builder.js

@@ -14,23 +14,27 @@ export function buildJudgePrompt(opts) {
         .join("\n\n");
     const graphitiInstructions = opts.mode === "eval"
         ? `
-## Step 5: Write findings to Graphiti
+## Step 5: Write findings to the knowledge graph
 
-For each finding with severity "warning" or "critical", write a derived insight to Graphiti:
+For each finding with severity "warning" or "critical", write it using \`mcp__indusk__graph_capture\`. This dual-writes to both Graphiti AND the semantic graph, connecting the finding to the existing file anchor — so the context beam can find it later.
+
+**Use \`graph_capture\`, NOT \`mcp__graphiti__add_memory\`.** graph_capture attaches the finding to the file's existing node in the graph. add_memory creates a disconnected episode.
+
+For each finding, identify the **primary file** it relates to and pass it as \`file_path\`. Include all relevant file paths in the body text too.
 
 \`\`\`
-mcp__graphiti__add_memory({
+mcp__indusk__graph_capture({
   name: "eval-finding-{question-id}-{short-slug}",
-  episode_body: "{finding text with evidence}",
-  group_id: "${opts.projectGroup}",
-  source: "text",
-  source_description: "eval judge finding"
+  body: "In {file1} and {file2}: {finding text with evidence}",
+  file_path: "{primary file path}",
+  relation: "eval-finding",
+  group_id: "${opts.projectGroup}"
 })
 \`\`\`
 
 Only write facts that would have changed the outcome. Be selective — quality over quantity.
-Count how many Graphiti writes you made for the scorecard.
-If Graphiti is unavailable, skip silently and set graphitiWrites to 0.`
+Count how many graph_capture calls you made for the scorecard.
+If the tool is unavailable, skip silently and set graphitiWrites to 0.`
         : `
 ## Step 5: Graphiti writes
 

package/dist/lib/eval/rubric.js

@@ -25,4 +25,9 @@ export const V1_RUBRIC = [
         question: "Is there information missing from the graph that would have helped? (context sufficiency)",
         guidance: "Consider what the agent struggled with or got wrong. Would a Graphiti fact, a lesson, or a CLAUDE.md entry have prevented the mistake?",
     },
+    {
+        id: "user-intent",
+        question: "Did the user express decisions, concerns, reasoning, or preferences that should be captured in the knowledge graph?",
+        guidance: "Read the transcript for user statements that reveal WHY something was done, not just what. Look for: design reasoning ('the reason we do X is...'), concerns ('I'm worried about...'), preferences ('I don't like this DX'), constraints ('we need this for promotion'), corrections ('no, do it this way'). These are the most valuable knowledge — they're only in the transcript and will be lost if not captured. Write each one to the graph via graph_capture with the relevant file_path.",
+    },
 ];

package/dist/tools/graph-tools.js

@@ -575,9 +575,7 @@ export function registerGraphTools(server, projectRoot) {
                             logExists: existsSync(logPath),
                             logSize: `${(logSize / 1024).toFixed(1)}KB`,
                             eventCount,
-                            lastSync: lastSyncTime
-                                ? { time: lastSyncTime, adapter: lastSyncAdapter }
-                                : null,
+                            lastSync: lastSyncTime ? { time: lastSyncTime, adapter: lastSyncAdapter } : null,
                             runtime: runtimeAvailable
                                 ? { anchors: anchorCount, edges: edgeCount }
                                 : { error: "FalkorDB not available" },
@@ -646,4 +644,41 @@ export function registerGraphTools(server, projectRoot) {
             };
         }
     });
+    server.registerTool("context_beam", {
+        description: "Get file-specific context from all sources (semantic graph, Graphiti, eval findings, CGC). Returns targeted, high-signal context for the file you're about to edit.",
+        inputSchema: {
+            path: z.string().describe("File path to get context for (relative to project root)"),
+            trace: z.boolean().default(false).describe("Show query trace"),
+            format: z.enum(["json", "markdown", "trace"]).default("markdown").describe("Output format"),
+        },
+    }, async ({ path: filePath, trace, format }) => {
+        try {
+            const { runBeam } = await import("../lib/beam/runner.js");
+            const { formatBeamMarkdown, formatBeamTrace } = await import("../lib/beam/format.js");
+            const result = await runBeam({
+                projectRoot,
+                targetPath: filePath,
+                trace: trace || format === "trace",
+            });
+            let text;
+            if (format === "json") {
+                text = JSON.stringify(result, null, 2);
+            }
+            else if (format === "trace") {
+                text = formatBeamTrace(result);
+            }
+            else {
+                text = formatBeamMarkdown(result);
+            }
+            return { content: [{ type: "text", text }] };
+        }
+        catch (err) {
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify({ error: err.message }) },
+                ],
+                isError: true,
+            };
+        }
+    });
 }

package/extensions/graphiti/skill.md

@@ -34,7 +34,7 @@ Every episode belongs to a group. Groups isolate knowledge:
 
 | Group | Purpose | Example |
 |-------|---------|---------|
-| `{project-name}` | Project-specific knowledge | `infinitedusky`, `numero` |
+| `{project-name}` | Project-specific knowledge | `dusk`, `numero` |
 | `shared` | Cross-project conventions | Developer preferences, universal patterns |
 
 When searching, always include both the project group and `shared` to get the full picture. Use `getProjectGroupId(projectRoot)` (from `apps/indusk-mcp/src/lib/config.ts`) to get the project group consistently — it reads `.indusk/config.json` `graphiti.groupId` if set, otherwise falls back to the project directory basename.
@@ -112,7 +112,7 @@ After a plan retrospective surfaces a useful insight, the retrospective skill ca
 mcp__graphiti__add_memory({
   name: "retro-gate-enforcement-1",
   episode_body: "Plan gates need hook-based enforcement, not just instructions. The agent skipped gates when they were advisory only. PreToolUse hooks that block phase transitions are the fix.",
-  group_id: "infinitedusky",
+  group_id: "dusk",
   source: "text",
   source_description: "retrospective insight"
 })

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@infinitedusky/indusk-mcp",
-	"version": "1.13.2",
+	"version": "1.14.1",
 	"description": "InDusk development system — skills, MCP tools, and CLI for structured AI-assisted development",
 	"type": "module",
 	"files": [