@polycode-projects/seonix 0.1.0

package/src/server.mjs

@@ -0,0 +1,389 @@
+// seonix MCP server — a local, query-only stdio server over the deterministic
+// typed code-graph artifact (<repo>/.seonix/graph.json). Adapted from the shipped
+// marginalia seon-mcp server, but the graph source
+// is a LOCAL file (src/source.mjs) and seonix_search is a LOCAL lexical lookup
+// (no remote API, no LLM, no model calls anywhere).
+//
+// Tools (all query-only, bounded output): seonix_search, seonix_describe, seonix_snippet,
+// seonix_impact, plus the §9 read-replacing tools seonix_members, seonix_subclasses,
+// seonix_architecture, seonix_tests_for, seonix_untested, seonix_history, seonix_callers,
+// seonix_callees. Each answers one question in ONE compact call so the agent need not
+// Read/Grep. Errors reach the caller as clean tool errors — message only, never a stack.
+
+import { readFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { loadConfig, ToolError } from "./config.mjs";
+import * as defaultSource from "./source.mjs";
+import {
+  parseEntities,
+  resolveSymbol,
+  renderDescribe,
+  renderImpact,
+  renderSearch,
+  siteOf,
+  renderMembers,
+  renderSubclasses,
+  renderArchitecture,
+  renderTestsFor,
+  renderUntested,
+  renderHistory,
+  renderCallers,
+  renderCallees,
+  renderCochanges,
+  renderExports,
+  renderSignature,
+  contextPlan,
+  sizeBundle,
+  bundleMask,
+  trimBundleMask,
+  renderContextMore,
+  renderCalls,
+  callHint,
+  renderFileHistory,
+  renderMethodHistory,
+  renderClassHistory,
+} from "./codegraph.mjs";
+
+const SNIPPET_MAX_LINES = 200;
+
+export const SERVER_INFO = { name: "seonix", version: "0.1.0" };
+
+// C4 tiered tool surface: only the TWO hot tools are registered as MCP tools, so the
+// agent's tool list stays tiny. Every COLD tool (describe/members/impact/history/…) is
+// still served by dispatchTool below and is reachable via the CLI `cli <tool>` route +
+// the generated <repo>/.seonix/TOOLS.md catalog (renderToolsCatalog).
+export const TOOLS = [
+  {
+    name: "seonix_context",
+    // Lean resident schema (re-billed every turn): the minimum that still steers the agent to
+    // ONE call → write, not Read.
+    description:
+      "START HERE to add/modify code: ONE call returns a sized edit bundle (exemplar source, sibling signatures, registration, insertion region) — then write directly, don't Read.",
+    inputSchema: {
+      type: "object",
+      required: ["symbol"],
+      properties: {
+        symbol: { type: "string", description: "Module path (django/utils/text.py) or a sibling function/class name in it (lower)." },
+        depth: { type: "string", enum: ["min", "auto", "full"], default: "auto", description: "auto (sized to the task) | min (leanest) | full (every section)." },
+      },
+    },
+  },
+  {
+    name: "seonix_snippet",
+    description: "EXACT source of one function/class/Class.method by name (its line span only) + a one-line in-repo call hint. Prefer over Read for a single symbol.",
+    inputSchema: {
+      type: "object",
+      required: ["symbol"],
+      properties: {
+        symbol: { type: "string", description: "function/class name (slugify, Truncator), Class.method, or fn:<path>#name." },
+      },
+    },
+  },
+];
+
+async function loadGraph(config, source) {
+  const payload = await source.fetchEntities(config);
+  const graph = parseEntities(payload);
+  if (!graph.individuals.length) {
+    throw new ToolError(
+      `the graph artifact at ${config.graphFile} has no entities — re-run ` +
+        "`seonix cli index_repository` for this repo (did the index step succeed?).",
+    );
+  }
+  return graph;
+}
+
+function resolveOrThrow(graph, symbol, what) {
+  const { match, candidates } = resolveSymbol(graph, symbol);
+  if (!match) {
+    throw new ToolError(
+      `no entity matching ${what} "${symbol}" in the code-map graph. ` +
+        "Try a repo-relative path (e.g. django/utils/text.py), a basename, or seonix_search for a fuzzy lookup.",
+    );
+  }
+  return { match, candidates };
+}
+
+/**
+ * Build the seonix_context "edit bundle" for a symbol and return { text, tier, topup }.
+ * Shared by the MCP seonix_context tool AND the no-MCP `cli digest` arm (cli.mjs), so both
+ * benefit from the size-adaptive sizing for free. `trim:true` (B2) renders a SECONDARY,
+ * signatures-only bundle (no bodies/tails) for related-but-not-primary digest modules.
+ *
+ * Section ORDER is cache-stable (B7): the content that is identical across runs (anchor /
+ * registration / exemplar / siblings / __all__ / insertion region) comes FIRST; the more
+ * variable, history-derived tails (covering tests, co-change) come LAST, so a stable prefix
+ * maximises prompt-cache reuse.
+ */
+export async function buildContextBundle(args, { config, source = defaultSource, trim = false } = {}) {
+  const symbol = String(args?.symbol || "").trim();
+  if (!symbol) throw new ToolError("symbol is required");
+  const depth = String(args?.depth || "auto").trim().toLowerCase();
+  // Tuning-flag contract: `min` forces the LEANEST bundle (TINY mask, no top-up) regardless of
+  // exemplar length; `untuned` reproduces the pre-B010 escalation (tuning #1 bypassed). Neither
+  // → the tuned default (sizeBundle's anchor-gated escalation).
+  const min = Boolean(args?.min);
+  const untuned = Boolean(args?.untuned);
+  const graph = await loadGraph(config, source);
+  const { match } = resolveOrThrow(graph, symbol, "symbol");
+  const plan = contextPlan(graph, match);
+  // #6/B1/B6: pick the section mask by depth — min forces TINY, full forces everything, auto
+  // runs the size classifier (lean TINY default + one-tier top-up when the edit needs it).
+  let tier;
+  let mask;
+  let topup = false;
+  if (min || depth === "min") { tier = "TINY"; mask = bundleMask("TINY"); }
+  else if (depth === "full") { tier = "FULL"; mask = bundleMask("FULL"); }
+  else ({ tier, mask, topup } = sizeBundle(plan, graph, { untuned }));
+  if (trim) mask = trimBundleMask(mask); // B2: secondary digest module → signatures + region only
+  const repoRoot = dirname(dirname(config.graphFile));
+  let lines = null;
+  if (plan.moduleLabel) {
+    try { lines = (await readFile(join(repoRoot, plan.moduleLabel), "utf8")).split("\n"); }
+    catch { lines = null; }
+  }
+  const lineAt = (n) => (lines && lines[n - 1] != null ? lines[n - 1].trim() : "");
+  const sliceBody = (start, end) => {
+    const e = Math.min(lines.length, Math.min(end, start + SNIPPET_MAX_LINES - 1));
+    return lines.slice(start - 1, e).map((l, i) => `${start + i}\t${l}`).join("\n");
+  };
+  const out = [
+    `Edit context for ${plan.moduleLabel} [${tier}${trim ? " secondary" : ""}] — assembled from the typed graph + that file. ` +
+      "You do NOT need to Read it; write the new code directly after reviewing this.",
+  ];
+  // ---- cache-stable prefix (B7): identical across runs ----
+  if (mask.anchor && plan.anchor?.site && lines) {
+    const { start, end } = plan.anchor.site;
+    out.push(`\n## anchor: ${plan.anchor.label} (${plan.anchor.class}) @ ${plan.moduleLabel}:${start}-${end}`);
+    out.push(sliceBody(start, end));
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.registration && plan.globals.length) {
+    out.push(`\n## registration / module globals (replicate this pattern):`);
+    for (const g of plan.globals) out.push(`  ${g.label} = ${g.value}${g.site ? `  [:${g.site.start}]` : ""}`);
+  }
+  if (mask.exemplar && plan.exemplar?.site && lines) {
+    const { start, end } = plan.exemplar.site;
+    const dec = plan.exemplar.decorators ? ` @${plan.exemplar.decorators}` : "";
+    out.push(`\n## closest example (full body) — copy this style: ${plan.exemplar.label} (${plan.exemplar.class})${dec} @ ${plan.moduleLabel}:${start}-${end}`);
+    out.push(sliceBody(start, end));
+    if (plan.callHint) out.push(plan.callHint);
+  }
+  if (mask.inlinedCallees && plan.calleeBodies.length && lines) {
+    let budget = 120; // INLINE_CALLEE_LOC
+    for (const cb of plan.calleeBodies) {
+      if (budget <= 0) break;
+      const start = cb.site.start;
+      const end = Math.min(cb.site.end, start + budget - 1);
+      const fromThisFile = cb.site.path === plan.moduleLabel;
+      const bodyLines = fromThisFile && lines
+        ? lines
+        : await readFile(join(repoRoot, cb.site.path), "utf8").then((t) => t.split("\n")).catch(() => null);
+      if (!bodyLines) continue;
+      const e = Math.min(bodyLines.length, end);
+      out.push(`\n## inlined callee body (depth-1 in-repo call): ${cb.label} @ ${cb.site.path}:${start}-${cb.site.end}`);
+      out.push(bodyLines.slice(start - 1, e).map((l, i) => `${start + i}\t${l}`).join("\n"));
+      budget -= (e - start + 1);
+    }
+  }
+  if (mask.classMembers && plan.classMembers && plan.classMembers.members.length) {
+    out.push(`\n## members of ${plan.classMembers.className} (the edit likely lives INSIDE this class — copy a member's shape, do not read the class body):`);
+    for (const m of plan.classMembers.members) {
+      const short = String(m.label).split(".").pop();
+      const sig = m.params != null && m.params !== "" ? `(${m.params})${m.returns ? ` -> ${m.returns}` : ""}` : "";
+      const dec = m.decorators ? `@${m.decorators} ` : "";
+      const r = m.raises ? `  raises=${m.raises}` : "";
+      out.push(`  ${m.class} ${short}${m.site ? ` :${m.site.start}` : ""}  ${dec}${short}${sig}${r}`);
+    }
+  }
+  if (mask.siblings && plan.siblings.length) {
+    out.push(`\n## sibling symbols to copy the style of (most relevant first; ${plan.siblings.length} total):`);
+    for (const s of plan.siblings.slice(0, plan.siblingCap)) {
+      const sig = s.site ? lineAt(s.site.start) : "";
+      const dec = s.decorators ? `@${s.decorators} ` : "";
+      const r = s.raises ? `  raises=${s.raises}` : "";
+      out.push(`  ${s.class} ${s.label}${s.site ? ` :${s.site.start}` : ""}  ${dec}${sig}${r}`);
+    }
+    if (plan.siblings.length > plan.siblingCap) {
+      out.push(`  …+${plan.siblings.length - plan.siblingCap} more (use seonix_search kind=function or seonix_snippet <name> for any of them)`);
+    }
+  }
+  if (mask.allExports && plan.allExports) {
+    out.push(`\n## module __all__ — this module curates its public API; ADD your new public symbol to this list so it is importable:\n  ${plan.allExports}`);
+  }
+  if (mask.reexports && plan.exports && plan.exports.length) out.push(`\n## re-exported symbols (resolved __all__ → defining module): ${plan.exports.join(", ")}`);
+  // #2 + B4: the contiguous insertion region is part of the STABLE prefix — always present
+  // (even at TINY) so the agent never needs to Read the file to place the edit.
+  if (mask.insertionRegion && plan.insertionRegion && lines) {
+    const start = plan.insertionRegion.start;
+    const end = Math.min(lines.length, start + 40 - 1); // INSERTION_REGION_CAP
+    out.push(`\n## insertion region (write your new sibling here) — ${plan.moduleLabel}:${start}-${end}`);
+    out.push(lines.slice(start - 1, end).map((l, i) => `${start + i}\t${l}`).join("\n"));
+  } else if (plan.insertion) {
+    out.push(`\n## insert the new sibling after line ~${plan.insertion} (end of the last top-level definition).`);
+  }
+  // ---- variable tail (B7): history-derived, kept LAST so the prefix stays cache-stable ----
+  if (mask.tests && plan.tests.length) out.push(`\n## covering tests: ${plan.tests.join(", ")}`);
+  if (mask.cochange && plan.cochange && plan.cochange.length) {
+    out.push(`\n## usually changed together (consider editing these too): ${plan.cochange.map((c) => `${c.label} (×${c.weight})`).join(", ")}`);
+  }
+  out.push(`\nYou now have the snippet, the sibling style, the registration anchor and the tests. ` +
+    `Write the new code with Edit/Write — do NOT Read ${plan.moduleLabel}.`);
+  if (tier !== "FULL") {
+    out.push(`(bundle tier ${tier}; for any omitted sections run seonix_context_more {"symbol":"${symbol}"}, or seonix_context with depth="full".)`);
+  }
+  return { text: out.join("\n"), tier, topup };
+}
+
+export async function dispatchTool(name, args, { config, source = defaultSource } = {}) {
+  if (name === "seonix_context") {
+    return (await buildContextBundle(args, { config, source })).text;
+  }
+  if (name === "seonix_context_more") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    return renderContextMore(contextPlan(graph, match));
+  }
+  if (name === "seonix_describe") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match, candidates } = resolveOrThrow(graph, symbol, "symbol");
+    return renderDescribe(graph, match, { candidates });
+  }
+  if (name === "seonix_snippet") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match, candidates } = resolveOrThrow(graph, symbol, "symbol");
+    const site = siteOf(match);
+    if (!site) {
+      throw new ToolError(
+        `"${match.label}" (${match.class || "Entity"}) has no source span in the graph — ` +
+          "it is likely a module. Use seonix_describe for its contents, then seonix_snippet one of the functions/classes it defines.",
+      );
+    }
+    // repo root = the dir containing .seonix/ (graphFile = <repo>/.seonix/graph.json)
+    const repoRoot = dirname(dirname(config.graphFile));
+    const abs = join(repoRoot, site.path);
+    let text;
+    try { text = await readFile(abs, "utf8"); }
+    catch (e) { throw new ToolError(`could not read ${site.path} (${e?.code || e?.message || e})`); }
+    const lines = text.split("\n");
+    const start = Math.max(1, site.start);
+    let end = Math.min(lines.length, site.end);
+    let truncated = false;
+    if (end - start + 1 > SNIPPET_MAX_LINES) { end = start + SNIPPET_MAX_LINES - 1; truncated = true; }
+    const body = lines.slice(start - 1, end).map((l, i) => `${start + i}\t${l}`).join("\n");
+    const span = site.end > site.start ? `${site.start}-${site.end}` : `${site.start}`;
+    const header = `${match.label} — ${match.class || "Entity"} @ ${site.path}:${span}`;
+    const note = truncated ? `\n… (truncated to ${SNIPPET_MAX_LINES} lines; full span ${span})` : "";
+    const cand = candidates.length ? `\n(other matches: ${candidates.map((c) => c.label).join(", ")})` : "";
+    const hint = callHint(graph, match); // #4: one-line "calls in-repo: …" so the agent sees in-repo deps inline
+    return `${header}\n${body}${note}${hint ? `\n${hint}` : ""}${cand}`;
+  }
+  if (name === "seonix_signature") {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    return renderSignature(graph, match);
+  }
+  if (name === "seonix_impact") {
+    const module = String(args?.module || "").trim();
+    if (!module) throw new ToolError("module is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, module, "module");
+    return renderImpact(graph, match);
+  }
+  if (name === "seonix_search") {
+    const query = String(args?.query || "").trim();
+    const kind = String(args?.kind || "").trim();
+    if (!query && !kind) throw new ToolError("query is required");
+    const graph = await loadGraph(config, source);
+    return renderSearch(graph, query, {
+      kind,
+      decorator: String(args?.decorator || "").trim(),
+      name: String(args?.name || "").trim(),
+    });
+  }
+  if (name === "seonix_members") {
+    const symbol = String(args?.class || "").trim();
+    if (!symbol) throw new ToolError("class is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "class");
+    return renderMembers(graph, match);
+  }
+  if (name === "seonix_subclasses") {
+    const symbol = String(args?.class || "").trim();
+    if (!symbol) throw new ToolError("class is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "class");
+    return renderSubclasses(graph, match);
+  }
+  if (name === "seonix_architecture") {
+    const graph = await loadGraph(config, source);
+    return renderArchitecture(graph, { pkg: String(args?.package || "").trim() });
+  }
+  if (name === "seonix_exports") {
+    const module = String(args?.module || "").trim();
+    if (!module) throw new ToolError("module is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, module, "module");
+    return renderExports(graph, match);
+  }
+  if (name === "seonix_untested") {
+    const graph = await loadGraph(config, source);
+    return renderUntested(graph);
+  }
+  if (
+    name === "seonix_tests_for" || name === "seonix_history" || name === "seonix_callers" ||
+    name === "seonix_callees" || name === "seonix_cochanges" || name === "seonix_calls" ||
+    name === "seonix_file_history" || name === "seonix_method_history" || name === "seonix_class_history"
+  ) {
+    const symbol = String(args?.symbol || "").trim();
+    if (!symbol) throw new ToolError("symbol is required");
+    const graph = await loadGraph(config, source);
+    const { match } = resolveOrThrow(graph, symbol, "symbol");
+    if (name === "seonix_tests_for") return renderTestsFor(graph, match);
+    if (name === "seonix_history") return renderHistory(graph, match);
+    if (name === "seonix_callers") return renderCallers(graph, match);
+    if (name === "seonix_cochanges") return renderCochanges(graph, match);
+    if (name === "seonix_calls") return renderCalls(graph, match);
+    if (name === "seonix_file_history") return renderFileHistory(graph, match);
+    if (name === "seonix_method_history") return renderMethodHistory(graph, match);
+    if (name === "seonix_class_history") return renderClassHistory(graph, match);
+    return renderCallees(graph, match);
+  }
+  throw new ToolError(`unknown tool: ${name}`);
+}
+
+/** Build the MCP server (transport-agnostic — tests connect it in-memory). */
+export function buildServer({ config = loadConfig(), source = defaultSource } = {}) {
+  const server = new Server(SERVER_INFO, { capabilities: { tools: {} } });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args } = req.params;
+    try {
+      const text = await dispatchTool(name, args || {}, { config, source });
+      return { content: [{ type: "text", text }] };
+    } catch (e) {
+      const text = e instanceof ToolError ? e.message : `unexpected error: ${e?.message || e}`;
+      return { content: [{ type: "text", text }], isError: true };
+    }
+  });
+  return server;
+}
+
+export async function startServer() {
+  const config = loadConfig();
+  const server = buildServer({ config });
+  await server.connect(new StdioServerTransport());
+  // stdout belongs to the MCP transport; sign on via stderr.
+  process.stderr.write(`seonix: serving ${TOOLS.length} tools over ${config.graphFile}\n`);
+}

package/src/source.mjs

@@ -0,0 +1,35 @@
+// Local graph source — the offline replacement for marginalia's HTTP/A2A `api`
+// layer. The MCP server takes this as an injectable dependency (so tests can
+// stub it); in production it reads the JSON artifact the deterministic indexer
+// wrote to config.graphFile. No network, no model calls.
+
+import { readFile } from "node:fs/promises";
+import { ToolError } from "./config.mjs";
+
+let cache = null; // { file, payload } — one artifact per process; cheap re-reads.
+
+export function clearCache() {
+  cache = null;
+}
+
+/** Read + parse the local graph artifact. Cached per file for the process. */
+export async function fetchEntities(config) {
+  if (cache && cache.file === config.graphFile) return cache.payload;
+  let text;
+  try {
+    text = await readFile(config.graphFile, "utf8");
+  } catch (e) {
+    throw new ToolError(
+      `no graph artifact at ${config.graphFile} — run \`seonix cli index_repository '{"repo_path":"<abs>"}'\` ` +
+        `for this repo first (the indexer writes <repo>/.seonix/graph.json). (${e?.code || e?.message || e})`,
+    );
+  }
+  let payload;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    throw new ToolError(`graph artifact ${config.graphFile} is not valid JSON`);
+  }
+  cache = { file: config.graphFile, payload };
+  return payload;
+}

package/src/viz.mjs

@@ -0,0 +1,218 @@
+// viz.mjs — render a FOCUSED sub-graph of the typed code-map to a single, portable
+// HTML file driven by Cytoscape.js. Deliberately NOT a whole-graph dump (that hangs
+// the browser): we BFS an ego-network around a focus node to a small depth, stop
+// expanding through high-degree hubs, and cap the node count. The HTML embeds the
+// sub-graph + an inlined copy of Cytoscape, and offers controls to navigate
+// (depth/hub sliders), change label verbosity, switch layout, and inspect nodes.
+//
+// `buildSubgraph` is pure and unit-tested; the CLI adds graph loading + file I/O.
+
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { parseEntities, resolveSymbol, relationKind, siteOf } from "./codegraph.mjs";
+import { loadConfig } from "./config.mjs";
+import * as source from "./source.mjs";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+const CLASS_COLOR = {
+  Module: "#5b9bd5",
+  Class: "#ffc000",
+  Function: "#70ad47",
+  Method: "#9ece6a",
+  Attribute: "#bb9af7",
+  GlobalVariable: "#e0af68",
+  Commit: "#8a8f98",
+};
+
+/** Build the adjacency + degree of every node across all typed relations. */
+function adjacency(graph) {
+  const adj = new Map(); // id -> [{id, rel}]
+  const degree = new Map();
+  const bump = (a, b, rel) => {
+    if (!adj.has(a)) adj.set(a, []);
+    adj.get(a).push({ id: b, rel });
+    degree.set(a, (degree.get(a) || 0) + 1);
+  };
+  for (const g of graph.relations) {
+    const rel = relationKind(g) || g.predicate || "rel";
+    for (const e of g.edges) {
+      if (!e.subject || !e.object) continue;
+      bump(e.subject, e.object, rel);
+      bump(e.object, e.subject, rel);
+    }
+  }
+  return { adj, degree };
+}
+
+/**
+ * Focused ego-network around `focusId`: BFS to `depth`, not expanding through nodes
+ * whose total degree exceeds `hubDegree` (so hubs appear but don't drag in the world),
+ * capped at `maxNodes`. Pure — returns {nodes, edges, focusId, truncated}.
+ */
+export function buildSubgraph(graph, { focusId, depth = 2, hubDegree = 40, maxNodes = 200 } = {}) {
+  if (!graph.byId.has(focusId)) return { nodes: [], edges: [], focusId, truncated: false };
+  const { adj, degree } = adjacency(graph);
+  const depthOf = new Map([[focusId, 0]]);
+  let frontier = [focusId];
+  let truncated = false;
+  for (let d = 1; d <= depth && frontier.length; d += 1) {
+    const next = [];
+    for (const id of frontier) {
+      // Stop expanding through a hub (but the hub itself is already included).
+      if (id !== focusId && (degree.get(id) || 0) > hubDegree) continue;
+      for (const { id: nb } of adj.get(id) || []) {
+        if (depthOf.has(nb)) continue;
+        if (depthOf.size >= maxNodes) { truncated = true; break; }
+        depthOf.set(nb, d);
+        next.push(nb);
+      }
+      if (depthOf.size >= maxNodes) { truncated = true; break; }
+    }
+    frontier = next;
+  }
+  const inSet = (id) => depthOf.has(id);
+  const nodes = [];
+  for (const [id, d] of depthOf) {
+    const ind = graph.byId.get(id);
+    const site = ind ? siteOf(ind) : null;
+    nodes.push({
+      id,
+      label: ind?.label || id,
+      cls: ind?.class || "Entity",
+      site: site ? `${site.path}:${site.end > site.start ? `${site.start}-${site.end}` : site.start}` : "",
+      depth: d,
+      degree: degree.get(id) || 0,
+    });
+  }
+  const seenEdge = new Set();
+  const edges = [];
+  for (const g of graph.relations) {
+    const rel = relationKind(g) || g.predicate || "rel";
+    for (const e of g.edges) {
+      if (!inSet(e.subject) || !inSet(e.object)) continue;
+      const key = `${e.subject}|${e.object}|${rel}`;
+      if (seenEdge.has(key)) continue;
+      seenEdge.add(key);
+      edges.push({ source: e.subject, target: e.object, rel });
+    }
+  }
+  return { nodes, edges, focusId, truncated };
+}
+
+/** Inline the Cytoscape dist so the HTML is one portable file (no sidecar, no CDN). */
+async function cytoscapeSource() {
+  const candidates = [
+    join(here, "..", "node_modules", "cytoscape", "dist", "cytoscape.min.js"),
+    join(here, "..", "..", "..", "node_modules", "cytoscape", "dist", "cytoscape.min.js"),
+  ];
+  for (const p of candidates) {
+    try { return await readFile(p, "utf8"); } catch { /* try next */ }
+  }
+  throw new Error("cytoscape not installed — run `npm install` in packages/seonix");
+}
+
+export function renderHtml({ subgraph, focusLabel, cytoscape, colors = CLASS_COLOR }) {
+  const data = {
+    nodes: subgraph.nodes.map((n) => ({ data: { ...n, color: colors[n.cls] || "#8a8f98" } })),
+    edges: subgraph.edges.map((e, i) => ({ data: { id: `e${i}`, ...e } })),
+    focusId: subgraph.focusId,
+    maxDepth: subgraph.nodes.reduce((m, n) => Math.max(m, n.depth), 0),
+  };
+  const legend = Object.entries(colors)
+    .map(([k, v]) => `<span class="lg"><i style="background:${v}"></i>${k}</span>`)
+    .join(" ");
+  return `<!doctype html><html><head><meta charset="utf-8"><title>seon code-map — ${focusLabel}</title>
+<style>
+  html,body{margin:0;height:100%;font:13px system-ui,sans-serif;background:#1a1b26;color:#c0caf5}
+  #bar{padding:8px 12px;background:#16161e;border-bottom:1px solid #2a2e42;display:flex;gap:14px;align-items:center;flex-wrap:wrap}
+  #bar label{color:#a9b1d6} #bar b{color:#7aa2f7}
+  #cy{position:absolute;top:auto;left:0;right:300px;bottom:0;height:calc(100% - 44px)}
+  #side{position:absolute;right:0;width:300px;bottom:0;height:calc(100% - 44px);background:#16161e;border-left:1px solid #2a2e42;padding:12px;overflow:auto}
+  .lg{margin-right:8px;white-space:nowrap}.lg i{display:inline-block;width:10px;height:10px;border-radius:2px;margin-right:4px;vertical-align:middle}
+  input[type=range]{vertical-align:middle} select{background:#1a1b26;color:#c0caf5;border:1px solid #2a2e42;border-radius:4px}
+  h3{margin:4px 0;color:#7aa2f7} code{color:#9ece6a;word-break:break-all}
+</style></head><body>
+<div id="bar">
+  <span><b>seon</b> focus: <b id="focuslabel">${focusLabel}</b></span>
+  <label>depth <input id="depth" type="range" min="1" max="9" value="9"> <span id="depthv"></span></label>
+  <label>hide deg&gt; <input id="hub" type="range" min="2" max="200" value="200"> <span id="hubv"></span></label>
+  <label>labels <select id="verb"><option value="1">name</option><option value="0">none</option><option value="2">name+site</option></select></label>
+  <label>layout <select id="layout"><option value="cose">cose</option><option value="breadthfirst">tree</option><option value="concentric">concentric</option></select></label>
+  <button id="fit">fit</button>
+  <span style="margin-left:auto">${legend}</span>
+</div>
+<div id="cy"></div>
+<div id="side"><h3>click a node</h3><div id="detail">Nodes: ${data.nodes.length}, edges: ${data.edges.length}${subgraph.truncated ? " (capped)" : ""}.</div></div>
+<script>${cytoscape}</script>
+<script>
+const G=${JSON.stringify(data)};
+const cy=cytoscape({container:document.getElementById('cy'),elements:[...G.nodes,...G.edges],
+  style:[
+    {selector:'node',style:{'background-color':'data(color)','label':'data(label)','color':'#c0caf5','font-size':10,'text-wrap':'wrap','text-max-width':120,'width':18,'height':18}},
+    {selector:'node[id = "'+G.focusId+'"]',style:{'width':30,'height':30,'border-width':3,'border-color':'#f7768e'}},
+    {selector:'edge',style:{'label':'data(rel)','width':1,'line-color':'#3b4261','target-arrow-color':'#3b4261','target-arrow-shape':'triangle','curve-style':'bezier','font-size':8,'color':'#7a88cf','text-rotation':'autorotate'}}
+  ],
+  layout:{name:'cose',animate:false}});
+const $=id=>document.getElementById(id);
+function applyFilters(){
+  const d=+$('depth').value, h=+$('hub').value;
+  $('depthv').textContent=d; $('hubv').textContent=h;
+  cy.batch(()=>cy.nodes().forEach(n=>{
+    const vis = n.data('depth')<=d && (n.id()===G.focusId || n.data('degree')<=h);
+    n.style('display', vis?'element':'none');
+  }));
+}
+function applyLabels(){const v=$('verb').value;cy.nodes().forEach(n=>{
+  n.style('label', v==='0'?'':v==='2'?(n.data('label')+(n.data('site')?'\\n'+n.data('site'):'')):n.data('label'));});}
+['depth','hub'].forEach(id=>$(id).addEventListener('input',applyFilters));
+$('verb').addEventListener('change',applyLabels);
+$('layout').addEventListener('change',()=>cy.layout({name:$('layout').value,animate:false}).run());
+$('fit').addEventListener('click',()=>cy.fit());
+cy.on('tap','node',e=>{const d=e.target.data();
+  $('detail').innerHTML='<h3>'+d.label+'</h3>class: '+d.cls+'<br>depth: '+d.depth+' · degree: '+d.degree+
+    (d.site?'<br>site: <code>'+d.site+'</code>':'')+'<br>id: <code>'+d.id+'</code>';});
+applyFilters();applyLabels();
+</script></body></html>`;
+}
+
+export async function runVizCli(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      focus: { type: "string" },
+      depth: { type: "string", default: "2" },
+      hub: { type: "string", default: "40" },
+      max: { type: "string", default: "200" },
+      out: { type: "string", default: "seon-graph.html" },
+      graph: { type: "string" },
+    },
+    allowPositionals: false,
+  });
+  if (!values.focus) {
+    process.stderr.write('seonix viz: --focus <symbol> is required (e.g. --focus Truncator --depth 2)\n');
+    process.exit(2);
+  }
+  const config = loadConfig(values.graph ? { ...process.env, SEONIX_GRAPH_FILE: resolve(values.graph) } : process.env);
+  const graph = parseEntities(await source.fetchEntities(config));
+  const { match } = resolveSymbol(graph, values.focus);
+  if (!match) {
+    process.stderr.write(`seonix viz: no entity matching "${values.focus}" in ${config.graphFile}\n`);
+    process.exit(1);
+  }
+  const subgraph = buildSubgraph(graph, {
+    focusId: match.id,
+    depth: Math.max(1, parseInt(values.depth, 10) || 2),
+    hubDegree: Math.max(2, parseInt(values.hub, 10) || 40),
+    maxNodes: Math.max(2, parseInt(values.max, 10) || 200),
+  });
+  const html = renderHtml({ subgraph, focusLabel: match.label, cytoscape: await cytoscapeSource() });
+  const out = resolve(values.out);
+  await writeFile(out, html);
+  process.stderr.write(
+    `seonix viz: ${subgraph.nodes.length} nodes, ${subgraph.edges.length} edges around "${match.label}" ` +
+      `(depth ${values.depth})${subgraph.truncated ? " [capped]" : ""} → ${out}\n`,
+  );
+}