@atolis-hq/corum 0.1.35 → 0.1.37

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -301,10 +301,10 @@ Or if installed globally:
301
301
  | `list_nodes` | List graph nodes using a `filter` object with `templates`, `exclude_templates`, `component`, `state`, and `stability` |
302
302
  | `list_templates` | List loaded templates with summary metadata |
303
303
  | `get_template` | Return full details for a template |
304
- | `get_cluster` | Return a root node, its descendants, included external nodes, and edges |
304
+ | `get_cluster` | Return a root node, its descendants, included external nodes, and edges for one node's full structural detail |
305
305
  | `get_graph` | Return the semantic graph as `{ nodes, edges }`, excluding structural templates and structural edges by default |
306
306
  | `get_graph_metadata` | Return discoverable metadata: template names, node templates in use, edge types, and valid enum values |
307
- | `get_lineage` | Traverse lineage from one or more start nodes with depth, direction, and edge/node-type filters |
307
+ | `get_lineage` | Traverse lineage from one or more start nodes. Lean nodes and no `edges` by default; opt in to fuller payloads when needed |
308
308
  | `get_graph_summary` | Return high-level graph statistics: node count, component count, orphan breakdown, edge counts, diagnostics |
309
309
  | `search_nodes` | Fuzzy-search root-level nodes by ID, with optional template filters and property search |
310
310
  | `get_linked_fields` | Return `maps-to` edges touching fields owned by a root node |
@@ -313,12 +313,18 @@ Or if installed globally:
313
313
 
314
314
  All tools accept an optional `format` argument: `yaml` (default), `json`, or `toon`. All tools also accept `compact_keys: true` to shorten common keys before serialization, reducing token usage.
315
315
 
316
+ All node-returning MCP tools accept `include_provenance: true` to include `extractedFrom`, `lastModifiedAt`, `derivation`, and `derivedBy`. These fields are omitted by default. `schemaVersion` is never returned by MCP.
317
+
316
318
  Common notes:
317
319
  - `branch` is supported on graph-query tools when Corum is running against a source-backed graph.
318
320
  - `list_nodes` is a breaking-change surface from older builds: use `filter.templates` instead of top-level `template`.
319
321
  - `search_nodes` accepts `queries: string[]`.
320
- - `get_graph_metadata` is the quickest way to discover valid template names, edge types, lifecycle states, stabilities, lineage directions, and output formats before constructing other calls.
321
- - `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, and `reads_outbound_only`.
322
+ - `get_graph_metadata` should usually be your first call. Use `edge_types_in_use` to avoid traversing edge types that do not exist in the current graph.
323
+ - Prefer `search_nodes` over `list_nodes` for discovery. Use `list_nodes` when you need a full inventory under explicit filters.
324
+ - `get_lineage` accepts `node_ids: string[]`, `depth`, `direction`, `edge_types`, `node_types`, `exclude_node_types`, `include_dangling_edges`, `reads_outbound_only`, `lean`, and `include_edges`.
325
+ - `get_lineage` defaults to `lean: true` and `include_edges: false`. Lean lineage nodes contain only `id`, `origin_id`, `depth`, `via_edge_type`, and `via_node_id`.
326
+ - Pass multiple `node_ids` to `get_lineage` in one call instead of making separate traversal calls.
327
+ - Use `get_cluster` only when you need full structural contents for one node such as schemas and fields. Use `get_lineage` for relationship traversal.
322
328
  - The graph reflects modeled relationships, not guaranteed complete truth. Missing edges do not prove no relationship exists; agents should treat naming and schema similarity as hypotheses and then verify via cluster inspection or source material.
323
329
 
324
330
  ## MCP Prompts
@@ -181,9 +181,18 @@ export function computeClusterOverlay(multi, viewingRef, overlayRefs, clusterRoo
181
181
  }
182
182
  export function getGraphSummary(graph) {
183
183
  const components = new Set();
184
+ const nodesByComponent = {};
185
+ const nodesByTemplate = {};
186
+ const nodesByState = {};
187
+ const nodesByStability = {};
184
188
  for (const node of graph.nodesById.values()) {
185
- if (node.component)
189
+ if (node.component) {
186
190
  components.add(node.component);
191
+ nodesByComponent[node.component] = (nodesByComponent[node.component] ?? 0) + 1;
192
+ }
193
+ nodesByTemplate[node.template] = (nodesByTemplate[node.template] ?? 0) + 1;
194
+ nodesByState[node.state] = (nodesByState[node.state] ?? 0) + 1;
195
+ nodesByStability[node.stability] = (nodesByStability[node.stability] ?? 0) + 1;
187
196
  }
188
197
  const nodesWithEdges = new Set();
189
198
  const edgesByType = {};
@@ -207,6 +216,10 @@ export function getGraphSummary(graph) {
207
216
  return {
208
217
  nodeCount: graph.nodesById.size,
209
218
  componentCount: components.size,
219
+ nodesByComponent,
220
+ nodesByTemplate,
221
+ nodesByState,
222
+ nodesByStability,
210
223
  orphanNodeCount: Object.values(orphansByTemplate).reduce((sum, count) => sum + count, 0),
211
224
  orphansByTemplate,
212
225
  edgesByType,
@@ -56,19 +56,92 @@ function parseListNodesFilter(value) {
56
56
  : toStringArray(filterArg.stability),
57
57
  };
58
58
  }
59
+ function includesProvenance(args) {
60
+ return args.include_provenance === true || args.includeProvenance === true;
61
+ }
62
+ function summarizeNode(node, includeProvenance) {
63
+ return {
64
+ id: node.id,
65
+ template: node.template,
66
+ component: node.component,
67
+ state: node.state,
68
+ stability: node.stability,
69
+ ...(includeProvenance ? withProvenance(node) : {}),
70
+ };
71
+ }
72
+ function withProvenance(node) {
73
+ return {
74
+ ...(node.extractedFrom !== undefined ? { extractedFrom: node.extractedFrom } : {}),
75
+ ...(node.lastModifiedAt !== undefined ? { lastModifiedAt: node.lastModifiedAt } : {}),
76
+ ...(node.derivation !== undefined ? { derivation: node.derivation } : {}),
77
+ ...(node.derivedBy !== undefined ? { derivedBy: node.derivedBy } : {}),
78
+ };
79
+ }
80
+ function fullNode(node, includeProvenance) {
81
+ return {
82
+ id: node.id,
83
+ template: node.template,
84
+ component: node.component,
85
+ state: node.state,
86
+ stability: node.stability,
87
+ properties: node.properties,
88
+ ...(includeProvenance ? withProvenance(node) : {}),
89
+ };
90
+ }
91
+ function mapEdge(edge, includeProvenance) {
92
+ const out = {
93
+ id: edge.id,
94
+ from: edge.from,
95
+ to: edge.to,
96
+ type: edge.type,
97
+ state: edge.state,
98
+ stability: edge.stability,
99
+ };
100
+ if (edge.notes !== undefined)
101
+ out.notes = edge.notes;
102
+ if (includeProvenance) {
103
+ if (edge.derivation !== undefined)
104
+ out.derivation = edge.derivation;
105
+ if (edge.derivedBy !== undefined)
106
+ out.derivedBy = edge.derivedBy;
107
+ }
108
+ return out;
109
+ }
110
+ function mapLineageNode(node, includeProvenance, lean) {
111
+ const base = {
112
+ id: String(node.id),
113
+ origin_id: String(node.origin_id),
114
+ depth: Number(node.depth),
115
+ via_edge_type: String(node.via_edge_type),
116
+ via_node_id: String(node.via_node_id),
117
+ };
118
+ if (lean)
119
+ return base;
120
+ return {
121
+ ...base,
122
+ template: String(node.template),
123
+ component: String(node.component),
124
+ state: String(node.state),
125
+ stability: String(node.stability),
126
+ properties: (node.properties ?? {}),
127
+ ...(includeProvenance
128
+ ? {
129
+ ...(node.extractedFrom !== undefined ? { extractedFrom: node.extractedFrom } : {}),
130
+ ...(node.lastModifiedAt !== undefined ? { lastModifiedAt: node.lastModifiedAt } : {}),
131
+ ...(node.derivation !== undefined ? { derivation: node.derivation } : {}),
132
+ ...(node.derivedBy !== undefined ? { derivedBy: node.derivedBy } : {}),
133
+ }
134
+ : {}),
135
+ };
136
+ }
59
137
  export function createMcpHandlers(graph, source, cache) {
60
138
  const resolveMulti = (src) => cache ? cache.get() : loadMultiGraph({ source: src });
61
139
  return {
62
140
  list_nodes(args) {
63
141
  const run = (targetGraph) => {
64
142
  const filter = parseListNodesFilter(args.filter);
65
- const summaries = listNodes(targetGraph, filter).map(node => ({
66
- id: node.id,
67
- template: node.template,
68
- component: node.component,
69
- state: node.state,
70
- stability: node.stability,
71
- }));
143
+ const summaries = listNodes(targetGraph, filter)
144
+ .map(node => summarizeNode(node, includesProvenance(args)));
72
145
  return formatResult(summaries, args.format, getCompactKeys(args));
73
146
  };
74
147
  if (hasBranch(args)) {
@@ -107,7 +180,15 @@ export function createMcpHandlers(graph, source, cache) {
107
180
  offset: typeof args.offset === 'number' ? args.offset : 0,
108
181
  searchProperties: args.search_properties === true,
109
182
  };
110
- return formatResult(searchNodes(targetGraph, queries, options), args.format, getCompactKeys(args));
183
+ const wantFull = args.full_nodes === true;
184
+ const incProv = includesProvenance(args);
185
+ const results = searchNodes(targetGraph, queries, options).map(result => ({
186
+ score: result.score,
187
+ node: wantFull
188
+ ? fullNode(result.node, incProv)
189
+ : summarizeNode(result.node, incProv),
190
+ }));
191
+ return formatResult(results, args.format, getCompactKeys(args));
111
192
  };
112
193
  if (hasBranch(args) && source) {
113
194
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
@@ -164,12 +245,19 @@ export function createMcpHandlers(graph, source, cache) {
164
245
  const edgeTypes = parseEdgeTypes(args.edge_types)
165
246
  ?? [...SEMANTIC_EDGE_TYPES];
166
247
  const cluster = getClusterView(targetGraph, String(args.node_id), edgeTypes);
248
+ const includeProvenance = includesProvenance(args);
249
+ const clusterPayload = {
250
+ root: fullNode(cluster.root, includeProvenance),
251
+ descendants: cluster.descendants.map(node => fullNode(node, includeProvenance)),
252
+ includedNodes: cluster.includedNodes.map(node => fullNode(node, includeProvenance)),
253
+ edges: cluster.edges.map(e => mapEdge(e, includeProvenance)),
254
+ };
167
255
  if (overlayRefs.length === 0 || !source || !branchRef) {
168
- return formatResult(cluster, args.format, getCompactKeys(args));
256
+ return formatResult(clusterPayload, args.format, getCompactKeys(args));
169
257
  }
170
258
  const multi = await resolveMulti(source);
171
259
  const overlay = computeClusterOverlay(multi, branchRef, overlayRefs, String(args.node_id));
172
- return formatResult({ ...cluster, overlay }, args.format, getCompactKeys(args));
260
+ return formatResult({ ...clusterPayload, overlay }, args.format, getCompactKeys(args));
173
261
  };
174
262
  const branchRef = hasBranch(args) ? String(args.branch) : undefined;
175
263
  if (branchRef) {
@@ -184,23 +272,21 @@ export function createMcpHandlers(graph, source, cache) {
184
272
  ? { ...filter, excludeTemplates: [...STRUCTURAL_NODE_TEMPLATES] }
185
273
  : filter;
186
274
  const nodes = listNodes(targetGraph, effectiveFilter)
187
- .map(node => ({
188
- id: node.id,
189
- template: node.template,
190
- component: node.component,
191
- state: node.state,
192
- stability: node.stability,
193
- }));
194
- const nodeIds = new Set(nodes.map(node => node.id));
195
- const edges = [];
196
- for (const edgeList of targetGraph.edgesByFrom.values()) {
197
- for (const edge of edgeList) {
198
- if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
199
- continue;
200
- edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
275
+ .map(node => summarizeNode(node, includesProvenance(args)));
276
+ const payload = { nodes };
277
+ if (args.include_edges === true) {
278
+ const nodeIds = new Set(nodes.map(node => node.id));
279
+ const edges = [];
280
+ for (const edgeList of targetGraph.edgesByFrom.values()) {
281
+ for (const edge of edgeList) {
282
+ if (!SEMANTIC_EDGE_TYPES.has(edge.type) || !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
283
+ continue;
284
+ edges.push({ id: edge.id, from: edge.from, to: edge.to, type: edge.type });
285
+ }
201
286
  }
287
+ payload.edges = edges;
202
288
  }
203
- return formatResult({ nodes, edges }, args.format, getCompactKeys(args));
289
+ return formatResult(payload, args.format, getCompactKeys(args));
204
290
  };
205
291
  if (hasBranch(args) && source) {
206
292
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
@@ -222,15 +308,18 @@ export function createMcpHandlers(graph, source, cache) {
222
308
  for (const edge of edgeList)
223
309
  edgeTypesInUse.add(edge.type);
224
310
  }
311
+ const includeStatic = args.include_static_enums === true;
225
312
  return formatResult({
226
313
  template_names: [...targetGraph.templates.keys()].sort(),
227
314
  node_templates_in_use: [...nodeTemplatesInUse].sort(),
228
315
  edge_types_in_use: [...edgeTypesInUse].sort(),
229
- valid_edge_types: [...EDGE_TYPES],
230
- states: [...STATE_VALUES],
231
- stabilities: [...STABILITY_VALUES],
232
- lineage_directions: [...LINEAGE_DIRECTIONS],
233
- output_formats: [...OUTPUT_FORMATS],
316
+ ...(includeStatic ? {
317
+ valid_edge_types: [...EDGE_TYPES],
318
+ states: [...STATE_VALUES],
319
+ stabilities: [...STABILITY_VALUES],
320
+ lineage_directions: [...LINEAGE_DIRECTIONS],
321
+ output_formats: [...OUTPUT_FORMATS],
322
+ } : {}),
234
323
  }, args.format, getCompactKeys(args));
235
324
  };
236
325
  if (hasBranch(args) && source) {
@@ -262,7 +351,18 @@ export function createMcpHandlers(graph, source, cache) {
262
351
  includeDanglingEdges: args.include_dangling_edges === true,
263
352
  readsOutboundOnly: args.reads_outbound_only !== false,
264
353
  };
265
- return formatResult(getLineage(targetGraph, nodeIds, options), args.format, getCompactKeys(args));
354
+ const lineage = getLineage(targetGraph, nodeIds, options);
355
+ const lean = args.lean !== false;
356
+ const includeEdges = args.include_edges === true;
357
+ const includeProvenance = includesProvenance(args);
358
+ const payload = {
359
+ nodes: lineage.nodes.map(node => mapLineageNode(node, includeProvenance, lean)),
360
+ };
361
+ if (includeEdges)
362
+ payload.edges = lineage.edges.map(e => mapEdge(e, includeProvenance));
363
+ if (args.include_dangling_edges === true && lineage.dangling_edges)
364
+ payload.dangling_edges = lineage.dangling_edges;
365
+ return formatResult(payload, args.format, getCompactKeys(args));
266
366
  };
267
367
  if (hasBranch(args) && source) {
268
368
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
@@ -275,7 +375,14 @@ export function createMcpHandlers(graph, source, cache) {
275
375
  }
276
376
  },
277
377
  get_linked_fields(args) {
278
- const run = (targetGraph) => formatResult(getLinkedFields(targetGraph, String(args.node_id)), args.format, getCompactKeys(args));
378
+ const run = (targetGraph) => {
379
+ const linked = getLinkedFields(targetGraph, String(args.node_id));
380
+ const incProv = includesProvenance(args);
381
+ return formatResult({
382
+ edges: linked.edges.map(e => mapEdge(e, incProv)),
383
+ nodes: linked.nodes.map(node => fullNode(node, incProv)),
384
+ }, args.format, getCompactKeys(args));
385
+ };
279
386
  if (hasBranch(args)) {
280
387
  return withBranchGraph(source, String(args.branch), branch => run(branch.graph));
281
388
  }
@@ -347,6 +454,241 @@ function errorResult(err) {
347
454
  const message = err instanceof QueryError ? err.message : String(err);
348
455
  return { content: [{ type: 'text', text: message }], isError: true };
349
456
  }
457
+ export function getMcpToolDefinitions() {
458
+ return [
459
+ {
460
+ name: 'list_nodes',
461
+ description: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
462
+ inputSchema: {
463
+ type: 'object',
464
+ properties: {
465
+ filter: {
466
+ type: 'object',
467
+ description: 'Filter criteria',
468
+ properties: {
469
+ templates: {
470
+ type: 'array',
471
+ items: { type: 'string' },
472
+ description: 'Include only these template types (OR semantics)',
473
+ },
474
+ exclude_templates: {
475
+ type: 'array',
476
+ items: { type: 'string' },
477
+ description: 'Exclude these template types',
478
+ },
479
+ component: { type: 'string', description: 'Filter by component name' },
480
+ state: {
481
+ description: 'Filter by lifecycle state as a string or array',
482
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
483
+ },
484
+ stability: {
485
+ description: 'Filter by stability as a string or array',
486
+ oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
487
+ },
488
+ },
489
+ },
490
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
491
+ branch: { type: 'string', description: 'Branch ref to load nodes from' },
492
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
493
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
494
+ },
495
+ },
496
+ },
497
+ {
498
+ name: 'list_templates',
499
+ description: 'List loaded graph templates. Returns name, version, core, abstract, extends, and description for each template.',
500
+ inputSchema: {
501
+ type: 'object',
502
+ properties: {
503
+ branch: { type: 'string', description: 'Branch ref to load templates from' },
504
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
505
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
506
+ },
507
+ },
508
+ },
509
+ {
510
+ name: 'get_template',
511
+ description: 'Get full details for a loaded graph template.',
512
+ inputSchema: {
513
+ type: 'object',
514
+ required: ['name'],
515
+ properties: {
516
+ name: { type: 'string', description: 'Template name' },
517
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
518
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
519
+ },
520
+ },
521
+ },
522
+ {
523
+ name: 'get_cluster',
524
+ description: 'Use when you need the full structural contents of a single node - its schema, fields, and owned children. Not suited for following relationships across the graph; use get_lineage for that. Note: large aggregates may exceed response size limits.',
525
+ inputSchema: {
526
+ type: 'object',
527
+ required: ['node_id'],
528
+ properties: {
529
+ node_id: { type: 'string', description: 'Fully qualified node ID' },
530
+ edge_types: {
531
+ type: 'array',
532
+ items: { type: 'string' },
533
+ description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
534
+ },
535
+ include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
536
+ reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
537
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
538
+ branch: { type: 'string', description: 'Branch ref to load the cluster from' },
539
+ overlay_refs: {
540
+ type: 'array',
541
+ items: { type: 'string' },
542
+ description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
543
+ },
544
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
545
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
546
+ },
547
+ },
548
+ },
549
+ {
550
+ name: 'get_graph',
551
+ description: 'Return semantic nodes (and optionally edges) across the graph. Excludes structural templates and structural edge types by default. Pass include_edges: true to include the semantic edge list.',
552
+ inputSchema: {
553
+ type: 'object',
554
+ properties: {
555
+ filter: {
556
+ type: 'object',
557
+ properties: {
558
+ templates: { type: 'array', items: { type: 'string' } },
559
+ exclude_templates: { type: 'array', items: { type: 'string' } },
560
+ component: { type: 'string' },
561
+ state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
562
+ stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
563
+ },
564
+ },
565
+ include_edges: { type: 'boolean', description: 'Include the semantic edge list in the response. Default false.' },
566
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
567
+ branch: { type: 'string', description: 'Branch ref to load the graph from' },
568
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
569
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
570
+ },
571
+ },
572
+ },
573
+ {
574
+ name: 'get_graph_metadata',
575
+ description: 'Return discoverable graph metadata: template names, node templates in use, edge types in use. Call this first before making traversal queries. The edge_types_in_use field tells you which edge types are actually modelled in the current graph - there is no value traversing edge types that have no entries. Pass include_static_enums: true to also receive valid_edge_types, states, stabilities, lineage_directions, and output_formats.',
576
+ inputSchema: {
577
+ type: 'object',
578
+ properties: {
579
+ include_static_enums: { type: 'boolean', description: 'Include static enum reference fields (valid_edge_types, states, stabilities, lineage_directions, output_formats). Default false.' },
580
+ branch: { type: 'string', description: 'Branch ref to load metadata from' },
581
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
582
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
583
+ },
584
+ },
585
+ },
586
+ {
587
+ name: 'get_lineage',
588
+ description: 'Traverse the graph from one or more origin nodes via BFS and return annotated lineage results. Pass multiple node_ids to expand all origins in parallel in a single call rather than making separate calls - results are merged and deduplicated automatically.\n\nCommon patterns:\n- Event fan-out - direction: downstream, depth: 2 from an event node to see all triggered commands and the operations they invoke.\n- Find all writers to an aggregate - direction: upstream from a DomainModel node to see every command and operation that writes to it.\n- Full event chain - direction: downstream, depth: 3 or more to trace event -> command -> operation -> produced event chains.',
589
+ inputSchema: {
590
+ type: 'object',
591
+ required: ['node_ids'],
592
+ properties: {
593
+ node_ids: {
594
+ type: 'array',
595
+ items: { type: 'string' },
596
+ description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
597
+ },
598
+ depth: { type: 'number', description: 'Max hops. Default 2.' },
599
+ direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Traversal direction. Default downstream.' },
600
+ edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
601
+ node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
602
+ exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
603
+ include_dangling_edges: { type: 'boolean', description: 'Include dangling edges in the response when present. Default false.' },
604
+ reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
605
+ lean: { type: 'boolean', description: 'Return minimal lineage node shape. Default true.' },
606
+ include_edges: { type: 'boolean', description: 'Include the edges list in the response. Default false.' },
607
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
608
+ branch: { type: 'string', description: 'Branch ref to load the lineage from' },
609
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
610
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
611
+ },
612
+ },
613
+ },
614
+ {
615
+ name: 'get_linked_fields',
616
+ description: 'Get all maps-to edges touching fields owned by the given root node.',
617
+ inputSchema: {
618
+ type: 'object',
619
+ required: ['node_id'],
620
+ properties: {
621
+ node_id: { type: 'string', description: 'Fully qualified root node ID' },
622
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
623
+ branch: { type: 'string', description: 'Branch ref to load linked fields from' },
624
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
625
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
626
+ },
627
+ },
628
+ },
629
+ {
630
+ name: 'get_graph_summary',
631
+ description: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
632
+ inputSchema: {
633
+ type: 'object',
634
+ properties: {
635
+ branch: { type: 'string', description: 'Branch ref to load the summary from' },
636
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
637
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
638
+ },
639
+ },
640
+ },
641
+ {
642
+ name: 'search_nodes',
643
+ description: 'Fuzzy search for root-level nodes by ID segments. Returns slim node summaries (id, template, component, state, stability) by default. Pass full_nodes: true to include properties. Prefer this over list_nodes when you have a domain term to search for - it returns ranked, targeted results without noise. Use list_nodes only when you need a complete inventory of nodes matching specific filter criteria.',
644
+ inputSchema: {
645
+ type: 'object',
646
+ required: ['queries'],
647
+ properties: {
648
+ queries: {
649
+ type: 'array',
650
+ items: { type: 'string' },
651
+ description: 'Search terms. OR semantics; any matching term qualifies the node.',
652
+ },
653
+ templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
654
+ exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
655
+ page_size: { type: 'number', description: 'Max results to return. Default 10.' },
656
+ offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
657
+ search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
658
+ full_nodes: { type: 'boolean', description: 'Include properties on each result node. Default false.' },
659
+ include_provenance: { type: 'boolean', description: 'Include provenance fields on returned nodes. Default false.' },
660
+ branch: { type: 'string', description: 'Branch ref to search within' },
661
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
662
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
663
+ },
664
+ },
665
+ },
666
+ {
667
+ name: 'list_branches',
668
+ description: 'List branches available from the configured graph source and their load status.',
669
+ inputSchema: {
670
+ type: 'object',
671
+ properties: {
672
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
673
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
674
+ },
675
+ },
676
+ },
677
+ {
678
+ name: 'diff_branch',
679
+ description: 'Diff a branch against the default branch.',
680
+ inputSchema: {
681
+ type: 'object',
682
+ required: ['branch'],
683
+ properties: {
684
+ branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
685
+ format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
686
+ compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
687
+ },
688
+ },
689
+ },
690
+ ];
691
+ }
350
692
  export async function startMcpServer(options = {}) {
351
693
  const { noWeb = false, watch = false } = options;
352
694
  const config = createGraphRuntimeConfig();
@@ -397,228 +739,7 @@ export async function startMcpServer(options = {}) {
397
739
  };
398
740
  });
399
741
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
400
- tools: [
401
- {
402
- name: 'list_nodes',
403
- description: 'List nodes in the graph. Returns id, template, component, state, stability for each matched node.',
404
- inputSchema: {
405
- type: 'object',
406
- properties: {
407
- filter: {
408
- type: 'object',
409
- description: 'Filter criteria',
410
- properties: {
411
- templates: {
412
- type: 'array',
413
- items: { type: 'string' },
414
- description: 'Include only these template types (OR semantics)',
415
- },
416
- exclude_templates: {
417
- type: 'array',
418
- items: { type: 'string' },
419
- description: 'Exclude these template types',
420
- },
421
- component: { type: 'string', description: 'Filter by component name' },
422
- state: {
423
- description: 'Filter by lifecycle state as a string or array',
424
- oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
425
- },
426
- stability: {
427
- description: 'Filter by stability as a string or array',
428
- oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }],
429
- },
430
- },
431
- },
432
- branch: { type: 'string', description: 'Branch ref to load nodes from' },
433
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
434
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
435
- },
436
- },
437
- },
438
- {
439
- name: 'list_templates',
440
- description: 'List loaded graph templates. Returns name, version, core, abstract, extends, and description for each template.',
441
- inputSchema: {
442
- type: 'object',
443
- properties: {
444
- branch: { type: 'string', description: 'Branch ref to load templates from' },
445
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
446
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
447
- },
448
- },
449
- },
450
- {
451
- name: 'get_template',
452
- description: 'Get full details for a loaded graph template.',
453
- inputSchema: {
454
- type: 'object',
455
- required: ['name'],
456
- properties: {
457
- name: { type: 'string', description: 'Template name' },
458
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
459
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
460
- },
461
- },
462
- },
463
- {
464
- name: 'get_cluster',
465
- description: 'Get the full cluster for a root node.',
466
- inputSchema: {
467
- type: 'object',
468
- required: ['node_id'],
469
- properties: {
470
- node_id: { type: 'string', description: 'Fully qualified node ID' },
471
- edge_types: {
472
- type: 'array',
473
- items: { type: 'string' },
474
- description: 'Edge types to follow for external node inclusion. Defaults to all semantic types.',
475
- },
476
- include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the cluster. Default false.' },
477
- reads_outbound_only: { type: 'boolean', description: 'Restrict reads edges to outbound only. Default true.' },
478
- branch: { type: 'string', description: 'Branch ref to load the cluster from' },
479
- overlay_refs: {
480
- type: 'array',
481
- items: { type: 'string' },
482
- description: 'Branch refs to overlay. Returns ghost field data alongside the cluster.',
483
- },
484
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
485
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
486
- },
487
- },
488
- },
489
- {
490
- name: 'get_graph',
491
- description: 'Return all semantic nodes and edges. Excludes structural templates and structural edge types by default.',
492
- inputSchema: {
493
- type: 'object',
494
- properties: {
495
- filter: {
496
- type: 'object',
497
- properties: {
498
- templates: { type: 'array', items: { type: 'string' } },
499
- exclude_templates: { type: 'array', items: { type: 'string' } },
500
- component: { type: 'string' },
501
- state: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
502
- stability: { oneOf: [{ type: 'string' }, { type: 'array', items: { type: 'string' } }] },
503
- },
504
- },
505
- branch: { type: 'string', description: 'Branch ref to load the graph from' },
506
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
507
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
508
- },
509
- },
510
- },
511
- {
512
- name: 'get_graph_metadata',
513
- description: 'Return discoverable graph metadata: template names, node templates in use, edge types, and valid enum values.',
514
- inputSchema: {
515
- type: 'object',
516
- properties: {
517
- branch: { type: 'string', description: 'Branch ref to load metadata from' },
518
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
519
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
520
- },
521
- },
522
- },
523
- {
524
- name: 'get_lineage',
525
- description: 'Traverse the graph from one or more origin nodes via BFS and return annotated lineage results.',
526
- inputSchema: {
527
- type: 'object',
528
- required: ['node_ids'],
529
- properties: {
530
- node_ids: {
531
- type: 'array',
532
- items: { type: 'string' },
533
- description: 'Fully-qualified IDs of origin nodes. All expand in parallel.',
534
- },
535
- depth: { type: 'number', description: 'Max hops. Default 2.' },
536
- direction: { type: 'string', enum: ['downstream', 'upstream', 'both'], description: 'Traversal direction. Default downstream.' },
537
- edge_types: { type: 'array', items: { type: 'string' }, description: 'Edge types to traverse. Default: all non-structural.' },
538
- node_types: { type: 'array', items: { type: 'string' }, description: 'Allowlist of node templates.' },
539
- exclude_node_types: { type: 'array', items: { type: 'string' }, description: 'Denylist of node templates.' },
540
- include_dangling_edges: { type: 'boolean', description: 'Include edges to nodes outside the result set. Default false.' },
541
- reads_outbound_only: { type: 'boolean', description: 'Do not follow inbound reads edges in upstream traversal. Default true.' },
542
- branch: { type: 'string', description: 'Branch ref to load the lineage from' },
543
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
544
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
545
- },
546
- },
547
- },
548
- {
549
- name: 'get_linked_fields',
550
- description: 'Get all maps-to edges touching fields owned by the given root node.',
551
- inputSchema: {
552
- type: 'object',
553
- required: ['node_id'],
554
- properties: {
555
- node_id: { type: 'string', description: 'Fully qualified root node ID' },
556
- branch: { type: 'string', description: 'Branch ref to load linked fields from' },
557
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
558
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
559
- },
560
- },
561
- },
562
- {
563
- name: 'get_graph_summary',
564
- description: 'Return high-level statistics: node count, component count, orphan breakdown, edge counts by type, diagnostic count.',
565
- inputSchema: {
566
- type: 'object',
567
- properties: {
568
- branch: { type: 'string', description: 'Branch ref to load the summary from' },
569
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
570
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
571
- },
572
- },
573
- },
574
- {
575
- name: 'search_nodes',
576
- description: 'Fuzzy search for root-level nodes by ID segments. Returns ranked results with score.',
577
- inputSchema: {
578
- type: 'object',
579
- required: ['queries'],
580
- properties: {
581
- queries: {
582
- type: 'array',
583
- items: { type: 'string' },
584
- description: 'Search terms. OR semantics; any matching term qualifies the node.',
585
- },
586
- templates: { type: 'array', items: { type: 'string' }, description: 'Include only these template types.' },
587
- exclude_templates: { type: 'array', items: { type: 'string' }, description: 'Exclude these template types.' },
588
- page_size: { type: 'number', description: 'Max results to return. Default 10.' },
589
- offset: { type: 'number', description: 'Result offset for pagination. Default 0.' },
590
- search_properties: { type: 'boolean', description: 'Also match name, description, and x-aka properties.' },
591
- branch: { type: 'string', description: 'Branch ref to search within' },
592
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
593
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
594
- },
595
- },
596
- },
597
- {
598
- name: 'list_branches',
599
- description: 'List branches available from the configured graph source and their load status.',
600
- inputSchema: {
601
- type: 'object',
602
- properties: {
603
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
604
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
605
- },
606
- },
607
- },
608
- {
609
- name: 'diff_branch',
610
- description: 'Diff a branch against the default branch.',
611
- inputSchema: {
612
- type: 'object',
613
- required: ['branch'],
614
- properties: {
615
- branch: { type: 'string', description: 'Branch ref to diff against the default branch' },
616
- format: { type: 'string', enum: ['yaml', 'json', 'toon'], description: 'Output format. Defaults to yaml.' },
617
- compact_keys: { type: 'boolean', description: 'Use compact graph keys in the selected output format.' },
618
- },
619
- },
620
- },
621
- ],
742
+ tools: getMcpToolDefinitions(),
622
743
  }));
623
744
  server.setRequestHandler(CallToolRequestSchema, async (request) => {
624
745
  if (loadError) {
@@ -33,24 +33,38 @@ When likely relationships are absent, treat naming, shared component context, sc
33
33
 
34
34
  ## Recommended workflow
35
35
 
36
- 1. Orient - call get_graph_summary first. Returns node count, component count, orphan count, edge counts by type, and diagnostic count.
36
+ 1. Call get_graph_metadata first to discover which edge types are in use and what node templates exist.
37
37
 
38
- 2. Discover valid values - call get_graph_metadata when you need the available template names, edge types, or enum values for filters and traversal options.
38
+ 2. Use search_nodes with domain terms to find relevant starting nodes. Avoid list_nodes for discovery - it returns full inventories rather than ranked matches.
39
39
 
40
- 3. Find nodes - use search_nodes with one or more terms (OR semantics). It fuzzy-matches node IDs and, when search_properties is enabled, names, descriptions, and x-aka aliases. Pass templates to restrict to a type, for example ["DomainModel"].
40
+ 3. Call get_lineage with multiple node_ids batched together rather than separate calls per node.
41
41
 
42
- 4. Inspect a node - use get_cluster with a fully-qualified node ID. Returns the root, its owned descendants, and included semantic neighbors.
42
+ 4. Use direction "downstream" with depth 2 from events to trace event -> command -> operation chains.
43
43
 
44
- 5. Trace relationships - use get_lineage from one or more node IDs. Default: depth 2 downstream. Use direction "both" and a higher depth to see event flow around a node. Each result node carries origin_id, depth, via_edge_type, and via_node_id. When multiple origins reach the same node, origins lists all origin IDs.
44
+ 5. Use direction "upstream" from a DomainModel node to find all writers to that aggregate.
45
45
 
46
- 6. Broad scan - use get_graph or list_nodes with filters to fetch nodes across the graph. get_graph supports templates, exclude_templates, component, state, and stability filters.
46
+ 6. Avoid get_cluster for traversal questions - use it only when you need a node's full structural detail (schema, fields). Prefer get_lineage for following relationships.
47
47
 
48
- ## Output format tips
48
+ 7. Add include_provenance: true only when you need to bridge a finding to the source codebase.
49
49
 
50
- - Default format is YAML.
51
- - Use format "json" when you want conventional structured output for downstream parsing.
52
- - Use format "toon" when you want the most token-efficient machine-readable output, especially for large node or edge lists.
53
- - Add compact_keys true to shorten common keys (id->i, template->t, component->cp, state->s, stability->st).
50
+ ## Output format and token efficiency
51
+
52
+ Start with format "toon" and compact_keys true. TOON is the most token-efficient machine-readable format and compact_keys shortens common field names. Fall back to format "yaml" if a downstream consumer needs human-readable output, or format "json" if it needs conventional structured parsing.
53
+
54
+ When compact_keys is true the following field names are shortened in the response:
55
+
56
+ id → i template → t component → cp
57
+ state → s stability → st properties → p
58
+ nodes → n edges → e root → r
59
+ children → ch from → fr to → to
60
+ type → ty notes → nt version → v
61
+ core → c abstract → a extends → ex
62
+ origin_id → oi depth → d via_edge_type → vet
63
+ via_node_id → vni lastModifiedAt → lm extractedFrom → xf
64
+ derivation → dv derivedBy → db
65
+
66
+ - get_lineage is lean by default: it returns only id (i), origin_id (oi), depth (d), via_edge_type (vet), and via_node_id (vni) unless lean is set to false.
67
+ - get_lineage omits edges by default; add include_edges true when you need graph reconstruction or edge-level auditing.
54
68
 
55
69
  ## Common patterns
56
70
 
@@ -41,6 +41,12 @@ const COMPACT_KEY_MAP = {
41
41
  lastModifiedAt: 'lm',
42
42
  extractedFrom: 'xf',
43
43
  properties: 'p',
44
+ origin_id: 'oi',
45
+ depth: 'd',
46
+ via_edge_type: 'vet',
47
+ via_node_id: 'vni',
48
+ derivation: 'dv',
49
+ derivedBy: 'db',
44
50
  root: 'r',
45
51
  children: 'ch',
46
52
  edges: 'e',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atolis-hq/corum",
3
- "version": "0.1.35",
3
+ "version": "0.1.37",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
package/web/app.jsx CHANGED
@@ -530,26 +530,25 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
530
530
  .catch(() => setBranchDiff(null));
531
531
  }, [isOnNonDefaultBranch, viewingRef, defaultBranchRef]);
532
532
 
533
- const componentCount = new Set(nodes.map(n => n.component).filter(Boolean)).size;
534
- const nodeCount = nodes.length;
535
533
  const totalEdges = stats ? Object.values(stats.edgesByType).reduce((a, b) => a + b, 0) : '…';
536
534
 
537
535
  const templateMap = new Map(templates.map(t => [t.name, t]));
538
536
 
539
- const nodesByTemplate = [...nodes.reduce((acc, node) => {
540
- acc.set(node.template, (acc.get(node.template) ?? 0) + 1);
541
- return acc;
542
- }, new Map()).entries()].sort((a, b) => b[1] - a[1]);
537
+ const nodesByTemplate = stats
538
+ ? Object.entries(stats.nodesByTemplate).sort((a, b) => b[1] - a[1])
539
+ : [];
540
+
541
+ const nodesByComponent = stats
542
+ ? Object.entries(stats.nodesByComponent).sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0]))
543
+ : [];
543
544
 
544
- const nodesByState = [...nodes.reduce((acc, node) => {
545
- acc.set(node.state, (acc.get(node.state) ?? 0) + 1);
546
- return acc;
547
- }, new Map()).entries()].sort((a, b) => b[1] - a[1]);
545
+ const nodesByState = stats
546
+ ? Object.entries(stats.nodesByState).sort((a, b) => b[1] - a[1])
547
+ : [];
548
548
 
549
- const nodesByStability = [...nodes.reduce((acc, node) => {
550
- acc.set(node.stability, (acc.get(node.stability) ?? 0) + 1);
551
- return acc;
552
- }, new Map()).entries()].sort((a, b) => b[1] - a[1]);
549
+ const nodesByStability = stats
550
+ ? Object.entries(stats.nodesByStability).sort((a, b) => b[1] - a[1])
551
+ : [];
553
552
 
554
553
  const edgeRows = stats
555
554
  ? Object.entries(stats.edgesByType).filter(([, count]) => count > 0).sort((a, b) => b[1] - a[1])
@@ -562,8 +561,8 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
562
561
  return (
563
562
  <div className="content">
564
563
  <div className="dashboard-hero">
565
- <HeroCard value={componentCount} label="Components" />
566
- <HeroCard value={nodeCount} label="Nodes" />
564
+ <HeroCard value={stats ? stats.componentCount : '…'} label="Components" />
565
+ <HeroCard value={stats ? stats.nodeCount : '…'} label="Nodes" />
567
566
  <HeroCard value={totalEdges} label="Edges" />
568
567
  <HeroCard value={stats ? stats.orphanNodeCount : '…'} label="Orphan Nodes" />
569
568
  </div>
@@ -584,6 +583,7 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
584
583
  <div className="dashboard-panel">
585
584
  <div className="card-head">Nodes by Type</div>
586
585
  <div className="card-body" style={{ padding: '12px 16px' }}>
586
+ {stats === null && <div className="label-sm">Loading…</div>}
587
587
  {nodesByTemplate.map(([name, count]) => {
588
588
  const tmpl = templateMap.get(name);
589
589
  const colour = tmpl?.ui?.colour ?? 'var(--ink-4)';
@@ -600,6 +600,19 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
600
600
  </div>
601
601
  </div>
602
602
 
603
+ <div className="dashboard-panel">
604
+ <div className="card-head">Nodes by Component</div>
605
+ <div className="card-body" style={{ padding: '12px 16px' }}>
606
+ {stats === null && <div className="label-sm">Loading…</div>}
607
+ {nodesByComponent.map(([name, count]) => (
608
+ <div key={name} className="stat-row">
609
+ <span className="stat-row-label">{name}</span>
610
+ <span className="stat-row-value">{count}</span>
611
+ </div>
612
+ ))}
613
+ </div>
614
+ </div>
615
+
603
616
  <div className="dashboard-panel">
604
617
  <div className="card-head">Orphan Nodes by Type</div>
605
618
  <div className="card-body" style={{ padding: '12px 16px' }}>
@@ -640,6 +653,7 @@ function DashboardPage({ nodes, templates, gitMode, viewingRef, branches, branch
640
653
  <div className="dashboard-panel">
641
654
  <div className="card-head">State & Stability</div>
642
655
  <div className="card-body" style={{ padding: '12px 16px' }}>
656
+ {stats === null && <div className="label-sm">Loading…</div>}
643
657
  {nodesByState.map(([state, count]) => (
644
658
  <div key={state} className="stat-row">
645
659
  <span className="stat-row-label"><StateTag state={state} /></span>
package/web/style.css CHANGED
@@ -1526,10 +1526,22 @@ button {
1526
1526
 
1527
1527
  .dashboard-grid {
1528
1528
  display: grid;
1529
- grid-template-columns: 1fr 1fr;
1529
+ grid-template-columns: repeat(3, minmax(260px, 1fr));
1530
1530
  gap: 16px;
1531
1531
  }
1532
1532
 
1533
+ @media (max-width: 960px) {
1534
+ .dashboard-grid {
1535
+ grid-template-columns: repeat(2, minmax(260px, 1fr));
1536
+ }
1537
+ }
1538
+
1539
+ @media (max-width: 640px) {
1540
+ .dashboard-grid {
1541
+ grid-template-columns: 1fr;
1542
+ }
1543
+ }
1544
+
1533
1545
  .dashboard-panel {
1534
1546
  overflow: hidden;
1535
1547
  border: 1px solid var(--rule-2);