@hegemonart/get-design-done 1.51.0 → 1.52.0

package/scripts/lib/design-context/integration-map.mjs

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/integration-map.mjs - Phase 52 (DesignContext graph), executor D.
+//
+// Renders an Atomic-Design integration map (mermaid) from the canonical
+// DesignContext graph at .design/context-graph.json. The map groups nodes into
+// the four Atomic-Design tiers (Atomic, Molecular, Organism, Template) using the
+// `layer` node subtype as the tier authority, then draws the `composes` and
+// `extends` edges between entities so a reader sees how the system assembles.
+//
+// Tier assignment
+// ---------------
+// A `layer` node carries a subtype of Atomic / Molecular / Organism / Template
+// and a set of `composes`/`extends` edges to the entities that sit in that tier.
+// Every entity reachable from a layer node by a composes/extends edge is placed
+// in that layer's tier. An entity with no layer membership lands in an
+// "Unlayered" bucket so nothing is silently dropped. When the graph has NO layer
+// nodes at all (a pre-taxonomy graph), every composes/extends participant falls
+// into "Unlayered" and the map still renders.
+//
+// Pure render seam
+// ----------------
+// render(graph) -> mermaid markdown string. No I/O, no Date.now(), no deps. The
+// CLI main() reads .design/context-graph.json and atomic-writes
+// .design/INTEGRATION-MAP.md via the sibling graph/atomic-write helper. main() is
+// non-fatal when the graph is absent or unreadable: it prints a notice to stderr
+// and returns 0, so a pipeline step that always runs it never breaks a build.
+//
+// No network, no optional deps, no top-level Date.now() (stamped only in main()).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { writeFileSync, renameSync, unlinkSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname, basename, join, resolve } from 'node:path';
+
+const DEFAULT_GRAPH = path.join('.design', 'context-graph.json');
+const DEFAULT_OUT = path.join('.design', 'INTEGRATION-MAP.md');
+
+// The four Atomic-Design tiers, in render order (broad to composed).
+const TIERS = ['Atomic', 'Molecular', 'Organism', 'Template'];
+const UNLAYERED = 'Unlayered';
+
+// Edges that express assembly. composes = whole -> part; extends = special -> base.
+const ASSEMBLY_EDGE_TYPES = new Set(['composes', 'extends']);
+
+function nodeList(graph) {
+  return Array.isArray(graph && graph.nodes) ? graph.nodes : [];
+}
+function edgeList(graph) {
+  return Array.isArray(graph && graph.edges) ? graph.edges : [];
+}
+
+/**
+ * Map every node id to its Atomic-Design tier. A `layer` node's subtype names a
+ * tier; the entities it composes/extends inherit that tier. Ids not reached from
+ * any layer land in UNLAYERED. A node id may appear under at most one tier (first
+ * layer membership wins, layers walked in TIERS order then by id for stability).
+ */
+function tierByNodeId(graph) {
+  const nodes = nodeList(graph);
+  const edges = edgeList(graph);
+  const byId = new Map(nodes.filter((n) => n && typeof n.id === 'string').map((n) => [n.id, n]));
+
+  // Layer nodes grouped by their tier subtype.
+  const layerNodes = nodes.filter((n) => n && n.type === 'layer' && typeof n.id === 'string');
+  const tierOfLayer = new Map();
+  for (const ln of layerNodes) {
+    const sub = TIERS.includes(ln.subtype) ? ln.subtype : UNLAYERED;
+    tierOfLayer.set(ln.id, sub);
+  }
+
+  // For each layer, the entities it reaches via a composes/extends edge.
+  const assignment = new Map(); // nodeId -> tier
+  const orderedLayers = [...layerNodes].sort((a, b) => {
+    const ta = TIERS.indexOf(tierOfLayer.get(a.id));
+    const tb = TIERS.indexOf(tierOfLayer.get(b.id));
+    if (ta !== tb) return (ta === -1 ? TIERS.length : ta) - (tb === -1 ? TIERS.length : tb);
+    return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+  });
+
+  for (const ln of orderedLayers) {
+    const tier = tierOfLayer.get(ln.id) || UNLAYERED;
+    for (const e of edges) {
+      if (!e || !ASSEMBLY_EDGE_TYPES.has(e.type)) continue;
+      // A layer "owns" the member regardless of edge direction: the member is the
+      // non-layer endpoint of an assembly edge that touches this layer.
+      let member = null;
+      if (e.source === ln.id) member = e.target;
+      else if (e.target === ln.id) member = e.source;
+      if (member && byId.has(member) && !assignment.has(member)) assignment.set(member, tier);
+    }
+    // The layer node itself sits in its own tier.
+    if (!assignment.has(ln.id)) assignment.set(ln.id, tier);
+  }
+
+  return { assignment, byId };
+}
+
+/** Sanitize a node id into a mermaid-safe node key (alnum + underscore). */
+function mermaidKey(id) {
+  return 'n_' + String(id).replace(/[^A-Za-z0-9]+/g, '_').replace(/^_+|_+$/g, '');
+}
+
+/** Escape a label for a mermaid quoted node label. */
+function mermaidLabel(node) {
+  const name = (node && (node.name || node.id)) || '';
+  const type = (node && node.type) || '';
+  const text = type ? `${name} (${type})` : `${name}`;
+  return text.replace(/"/g, "'").replace(/[\r\n]+/g, ' ');
+}
+
+/**
+ * Pure render: build the Atomic-Design integration map as mermaid markdown.
+ * @param {object} graph  a DesignContext graph ({nodes[], edges[]}) or empty/absent.
+ * @returns {string} markdown with a fenced mermaid flowchart, always non-empty.
+ */
+export function render(graph) {
+  const nodes = nodeList(graph);
+  const edges = edgeList(graph);
+  const { assignment, byId } = tierByNodeId(graph);
+
+  // Bucket every assembly participant by tier (so the diagram only draws nodes
+  // that actually take part in composition, plus their layer nodes).
+  const buckets = new Map([...TIERS, UNLAYERED].map((t) => [t, []]));
+  const drawn = new Set();
+  const place = (id) => {
+    if (!byId.has(id) || drawn.has(id)) return;
+    const tier = assignment.get(id) || UNLAYERED;
+    buckets.get(tier).push(id);
+    drawn.add(id);
+  };
+  for (const e of edges) {
+    if (!e || !ASSEMBLY_EDGE_TYPES.has(e.type)) continue;
+    place(e.source);
+    place(e.target);
+  }
+  // Always show layer nodes even if they have no assembly edge yet.
+  for (const n of nodes) if (n && n.type === 'layer') place(n.id);
+
+  const lines = [];
+  lines.push('# Integration Map');
+  lines.push('');
+  lines.push(
+    'Atomic-Design composition map derived from `.design/context-graph.json`. Nodes are grouped ' +
+      'by Atomic-Design tier (from `layer` node subtype); edges show `composes` and `extends` ' +
+      'relationships. Regenerate with `node scripts/lib/design-context/integration-map.mjs`.',
+  );
+  lines.push('');
+
+  const totalDrawn = [...buckets.values()].reduce((acc, ids) => acc + ids.length, 0);
+  if (totalDrawn === 0) {
+    lines.push('_No `composes`/`extends` relationships in the graph yet, so there is nothing to map._');
+    lines.push('');
+    return lines.join('\n');
+  }
+
+  lines.push('```mermaid');
+  lines.push('flowchart TD');
+
+  // Subgraphs per tier (only non-empty ones), in TIERS order then Unlayered.
+  for (const tier of [...TIERS, UNLAYERED]) {
+    const ids = buckets.get(tier);
+    if (!ids.length) continue;
+    lines.push(`  subgraph ${tier}`);
+    for (const id of ids.sort()) {
+      const node = byId.get(id);
+      lines.push(`    ${mermaidKey(id)}["${mermaidLabel(node)}"]`);
+    }
+    lines.push('  end');
+  }
+
+  // Assembly edges (composes = solid arrow; extends = thick "extends" arrow).
+  const seenEdge = new Set();
+  for (const e of edges) {
+    if (!e || !ASSEMBLY_EDGE_TYPES.has(e.type)) continue;
+    if (!byId.has(e.source) || !byId.has(e.target)) continue;
+    const key = `${e.source}--${e.type}-->${e.target}`;
+    if (seenEdge.has(key)) continue;
+    seenEdge.add(key);
+    const a = mermaidKey(e.source);
+    const b = mermaidKey(e.target);
+    if (e.type === 'extends') lines.push(`  ${a} -. extends .-> ${b}`);
+    else lines.push(`  ${a} --> ${b}`);
+  }
+
+  lines.push('```');
+  lines.push('');
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Atomic write (inlined twin of scripts/lib/graph/atomic-write.mjs for a text
+// payload; that helper is JSON-only and the map is markdown). Same tmp+rename
+// invariant: tmp lives in the SAME dir as target (Windows-atomic rename).
+// ---------------------------------------------------------------------------
+
+function atomicWriteText(target, body) {
+  const parent = dirname(target);
+  const base = basename(target);
+  const tmp = join(
+    parent,
+    `.${base}.tmp.${process.pid}.${Date.now()}.${Math.random().toString(36).slice(2, 8)}`,
+  );
+  if (resolve(dirname(tmp)) !== resolve(parent)) {
+    throw new Error(`atomicWriteText invariant: tmp not in same dir as target (tmp=${tmp}, target=${target})`);
+  }
+  mkdirSync(parent, { recursive: true });
+  try {
+    writeFileSync(tmp, body, 'utf8');
+    renameSync(tmp, target);
+  } catch (err) {
+    if (existsSync(tmp)) {
+      try { unlinkSync(tmp); } catch { /* swallow cleanup error; original throw wins */ }
+    }
+    throw err;
+  }
+}
+
+/**
+ * CLI entry. Reads the graph (argv[0] or the default path), renders the map, and
+ * atomic-writes it (argv[1] or the default out). Non-fatal when the graph is
+ * absent or unreadable: prints a notice and returns 0.
+ * @returns {number} process exit code (0 always, by design; this is advisory).
+ */
+export function main(argv = process.argv.slice(2)) {
+  const graphPath = argv[0] || DEFAULT_GRAPH;
+  const outPath = argv[1] || DEFAULT_OUT;
+
+  if (!fs.existsSync(graphPath)) {
+    process.stderr.write(`integration-map: no graph at ${graphPath} (skipping, non-fatal)\n`);
+    return 0;
+  }
+  let graph;
+  try {
+    graph = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`integration-map: unreadable graph ${graphPath} (${err.message}) (skipping, non-fatal)\n`);
+    return 0;
+  }
+
+  const md = render(graph);
+  const stamp = `<!-- generated ${new Date().toISOString()} by scripts/lib/design-context/integration-map.mjs -->\n`;
+  atomicWriteText(outPath, stamp + md);
+  process.stderr.write(`integration-map: wrote ${outPath}\n`);
+  return 0;
+}
+
+// ESM "run as script" guard (Windows + POSIX safe via pathToFileURL).
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) process.exit(main());

package/scripts/lib/design-context/merge-fragments.mjs

@@ -0,0 +1,227 @@
+#!/usr/bin/env node
+// scripts/lib/design-context/merge-fragments.mjs — Phase 52 (DesignContext graph), executor B.
+//
+// Deterministic, dependency-free fragment merger. Reads N mapper Fragments
+// (schema_version 52.0) and produces the single merged Graph
+// (schema_version 52.0, NO `mapper` field) written atomically to disk.
+//
+// Merge rules
+// -----------
+// NODES — deduped by `id`:
+//   - tags          : union (order-stable, de-duplicated)
+//   - summary       : prefer the first NON-STUB summary (non-empty) seen; an
+//                     empty-string summary is a stub the LLM phase fills later
+//   - complexity    : prefer the first non-'moderate' value (the stub default)
+//   - other fields  : first-writer-wins, but later non-empty values fill gaps
+//                     left empty/absent by the first writer (e.g. value, layer,
+//                     subtype). type/name keep the first non-empty.
+//
+// EDGES — deduped by (source,target,type); for each edge we verify BOTH
+// endpoints resolve to a node id that exists in SOME fragment (the merged node
+// set):
+//   - both endpoints resolve  -> keep the edge (this is cross-fragment
+//                                "recovery": the a11y fragment can reference a
+//                                component:* node defined only in the component
+//                                fragment, and the edge survives the merge);
+//   - an endpoint is missing  -> DROP the edge and report it. A missing
+//                                endpoint cannot be recovered (no node with that
+//                                id exists in any fragment), so the edge is
+//                                truly dangling.
+//
+// "Could not fix" items (dropped dangling edges; any unresolved id) are written
+// to stderr, one per line, prefixed `could-not-fix:`.
+//
+// Public API:
+//   merge(fragments) -> { graph, couldNotFix: string[] }   (pure)
+//   main()           -> reads argv globs / .design/fragments/*.json, atomic-writes graph
+//
+// No network, no deps beyond the sibling atomic-write helper, no top-level
+// Date.now() (stamped in main()).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { atomicWriteJson } from '../graph/atomic-write.mjs';
+
+const SCHEMA_VERSION = '52.0';
+const DEFAULT_OUT = path.join('.design', 'context-graph.json');
+const DEFAULT_FRAGMENT_DIR = path.join('.design', 'fragments');
+
+const STUB_COMPLEXITY = 'moderate';
+const NODE_RESERVED = new Set(['id', 'type', 'name', 'summary', 'tags', 'complexity']);
+
+function isNonStubSummary(s) {
+  return typeof s === 'string' && s.trim().length > 0;
+}
+
+/** Merge one node into the accumulator map (dedupe by id). */
+function mergeNode(map, node) {
+  if (!node || typeof node.id !== 'string') return;
+  const existing = map.get(node.id);
+  if (!existing) {
+    // Clone so we never mutate the caller's input objects.
+    map.set(node.id, {
+      id: node.id,
+      type: node.type,
+      name: node.name,
+      summary: isNonStubSummary(node.summary) ? node.summary : '',
+      tags: Array.isArray(node.tags) ? [...new Set(node.tags)] : [],
+      complexity: node.complexity || STUB_COMPLEXITY,
+      ...copyExtras({}, node),
+    });
+    return;
+  }
+
+  // tags: union, order-stable.
+  if (Array.isArray(node.tags) && node.tags.length) {
+    const seen = new Set(existing.tags);
+    for (const t of node.tags) if (!seen.has(t)) { existing.tags.push(t); seen.add(t); }
+  }
+  // summary: first non-stub wins.
+  if (!isNonStubSummary(existing.summary) && isNonStubSummary(node.summary)) {
+    existing.summary = node.summary;
+  }
+  // complexity: first non-default ('moderate' is the stub) wins.
+  if (existing.complexity === STUB_COMPLEXITY && node.complexity && node.complexity !== STUB_COMPLEXITY) {
+    existing.complexity = node.complexity;
+  }
+  // type/name: fill if the first writer left them empty.
+  if (!existing.type && node.type) existing.type = node.type;
+  if (!existing.name && node.name) existing.name = node.name;
+  // extras: fill gaps the first writer did not set.
+  copyExtras(existing, node, /* fillOnly */ true);
+}
+
+/** Copy non-reserved fields from `node` onto `target`. */
+function copyExtras(target, node, fillOnly = false) {
+  for (const k of Object.keys(node)) {
+    if (NODE_RESERVED.has(k)) continue;
+    if (fillOnly && target[k] !== undefined && target[k] !== '' && target[k] !== null) continue;
+    target[k] = node[k];
+  }
+  return target;
+}
+
+/**
+ * Pure merge.
+ * @param {object[]} fragments  array of Fragment objects (each {nodes[], edges[]})
+ * @returns {{graph: object, couldNotFix: string[]}}
+ */
+export function merge(fragments) {
+  const list = Array.isArray(fragments) ? fragments : [fragments];
+  const nodeMap = new Map();
+  const couldNotFix = [];
+
+  // Pass 1: union all nodes (so edge recovery can see ids from any fragment).
+  for (const frag of list) {
+    if (!frag || !Array.isArray(frag.nodes)) continue;
+    for (const n of frag.nodes) mergeNode(nodeMap, n);
+  }
+
+  // Pass 2: dedupe + validate edges against the merged node set.
+  const edgeMap = new Map();
+  for (const frag of list) {
+    if (!frag || !Array.isArray(frag.edges)) continue;
+    for (const e of frag.edges) {
+      if (!e || typeof e.source !== 'string' || typeof e.target !== 'string' || !e.type) {
+        couldNotFix.push(`could-not-fix: malformed edge ${JSON.stringify(e)}`);
+        continue;
+      }
+      const srcOk = nodeMap.has(e.source);
+      const dstOk = nodeMap.has(e.target);
+      if (!srcOk || !dstOk) {
+        // Truly dangling — no node with that id exists in ANY fragment.
+        const missing = [!srcOk ? `source=${e.source}` : null, !dstOk ? `target=${e.target}` : null]
+          .filter(Boolean).join(' ');
+        couldNotFix.push(`could-not-fix: dropped dangling edge (${e.type}) ${missing}`);
+        continue;
+      }
+      // Recovered (or always-resolved) — keep, deduped by (source,target,type).
+      const key = `${e.source}--${e.type}-->${e.target}`;
+      if (!edgeMap.has(key)) {
+        edgeMap.set(key, {
+          source: e.source,
+          target: e.target,
+          type: e.type,
+          direction: e.direction || 'forward',
+          weight: typeof e.weight === 'number' ? e.weight : 0.5,
+        });
+      } else if (typeof e.weight === 'number') {
+        // Keep the max weight when the same edge appears in two fragments.
+        const cur = edgeMap.get(key);
+        if (e.weight > cur.weight) cur.weight = e.weight;
+      }
+    }
+  }
+
+  const graph = {
+    schema_version: SCHEMA_VERSION,
+    generated_at: '',
+    nodes: [...nodeMap.values()],
+    edges: [...edgeMap.values()],
+  };
+  return { graph, couldNotFix };
+}
+
+// ---------------------------------------------------------------------------
+// CLI helpers.
+// ---------------------------------------------------------------------------
+
+/** Resolve argv into a concrete list of fragment file paths. */
+function resolveInputs(argv) {
+  // argv shape: [...inputs?] [--out <path>]
+  const args = [...argv];
+  let out = DEFAULT_OUT;
+  const inputs = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i] === '--out' || args[i] === '-o') { out = args[++i] || out; continue; }
+    inputs.push(args[i]);
+  }
+
+  let files = [];
+  if (inputs.length) {
+    for (const inp of inputs) {
+      let st;
+      try { st = fs.statSync(inp); } catch { continue; }
+      if (st.isDirectory()) {
+        for (const f of fs.readdirSync(inp)) if (f.endsWith('.json')) files.push(path.join(inp, f));
+      } else if (st.isFile()) {
+        files.push(inp);
+      }
+    }
+  } else if (fs.existsSync(DEFAULT_FRAGMENT_DIR)) {
+    for (const f of fs.readdirSync(DEFAULT_FRAGMENT_DIR)) {
+      if (f.endsWith('.json')) files.push(path.join(DEFAULT_FRAGMENT_DIR, f));
+    }
+  }
+  files = [...new Set(files)].sort(); // deterministic order
+  return { files, out };
+}
+
+function readFragment(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (err) {
+    process.stderr.write(`could-not-fix: unreadable fragment ${file} (${err.message})\n`);
+    return null;
+  }
+}
+
+/** CLI entry: read fragments, merge, stamp generated_at, atomic-write graph. */
+export function main(argv = process.argv.slice(2)) {
+  const { files, out } = resolveInputs(argv);
+  const fragments = files.map(readFragment).filter(Boolean);
+  const { graph, couldNotFix } = merge(fragments);
+  graph.generated_at = new Date().toISOString();
+
+  for (const line of couldNotFix) process.stderr.write(line + '\n');
+
+  atomicWriteJson(out, graph);
+  process.stderr.write(
+    `merged ${fragments.length} fragment(s) -> ${out} (${graph.nodes.length} nodes, ${graph.edges.length} edges, ${couldNotFix.length} could-not-fix)\n`,
+  );
+}
+
+const invokedDirectly =
+  process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) main();

package/scripts/lib/manifest/skills.json

@@ -93,6 +93,14 @@
       "user_invocable": true,
       "tools": "Read, Write, Bash, Glob, Grep, AskUserQuestion, ToolSearch"
     },
+    {
+      "name": "context",
+      "description": "Queries the typed DesignContext graph at .design/context-graph.json - the design-semantic map of tokens, components, variants, states, motion, a11y patterns, screens, layers, and design patterns plus the edges between them. Lists and filters nodes and edges, traces a path between two nodes, finds the consumers of a node, and reports unreachable nodes, dependency cycles, and coverage. Use when the user wants to inspect the design graph, find what depends on a token or component, trace how one node reaches another, or check graph health. Activates for requests involving the design context graph, design dependencies, token consumers, component composition, unreachable design nodes, design cycles, or design coverage.",
+      "argument_hint": "[nodes --type X | edges --type Z | path <a> <b> | consumers-of <id> | unreachable | cycles | coverage]",
+      "tools": "Read, Bash",
+      "user_invocable": true,
+      "registered_in_phase": "52"
+    },
     {
       "name": "continue",
       "description": "Alias for {{command_prefix}}resume - restore session context from the most recent checkpoint.",
@@ -244,6 +252,14 @@
       "user_invocable": true,
       "tools": "Read, Write, Bash, Grep, Glob"
     },
+    {
+      "name": "migrate-context",
+      "description": "Migrates a pre-Phase-52 project from the flat .design/map/*.md mapper notes to the typed DesignContext graph at .design/context-graph.json. Reads the old map notes, runs the deterministic extract-*.mjs passes to build mapper fragments, merges them with merge-fragments.mjs, validates the result with validate-design-context.cjs, and flags every low-confidence transform for human review before anything is trusted. Read-first and reversible; --dry-run previews the plan without writing. Use when upgrading a project to the DesignContext graph and .design/map/*.md still holds the only structured design notes. Activates for requests involving migrating design maps, building the context graph from old notes, or DesignContext graph migration.",
+      "argument_hint": "[--dry-run]",
+      "tools": "Read, Write, Bash",
+      "user_invocable": true,
+      "registered_in_phase": "52"
+    },
     {
       "name": "new-cycle",
       "description": "Start a new design cycle. Creates cycle scope in STATE.md, initializes .design/CYCLES.md entry. Each cycle has its own goal and tracks its own decisions/tasks/pipeline runs.",

package/scripts/lib/mcp-tools-lint/index.cjs

@@ -37,7 +37,9 @@ const path = require('node:path');
 
 const DEFAULT_EXEMPTIONS = new Set(['index.ts', 'shared.ts']);
 const DEFAULT_MAX_LOC = 30;
-const DEFAULT_TOOL_CAP = 12;
+// Raised 12 -> 13 in Phase 52 (DesignContext keystone, D5) for the read-only
+// `gdd_context_query` tool. Mirrors the cap in sdk/mcp/gdd-mcp/tools/index.ts.
+const DEFAULT_TOOL_CAP = 13;
 const TOOL_FILE_GLOB = /^gdd_[a-z0-9_]+\.ts$/;
 
 const FORBIDDEN_IMPORT_PATTERNS = Object.freeze([

package/sdk/mcp/gdd-mcp/schemas/gdd_context_query.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "gdd_context_query",
+  "type": "object",
+  "properties": {
+    "input": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["op"],
+      "properties": {
+        "op": {
+          "type": "string",
+          "enum": [
+            "nodes",
+            "edges",
+            "path",
+            "consumers-of",
+            "unreachable",
+            "cycles",
+            "coverage"
+          ],
+          "description": "Which read-only query to run over the DesignContext graph."
+        },
+        "type": {
+          "type": "string",
+          "description": "Node type (op=nodes) or edge type (op=edges) filter."
+        },
+        "tag": {
+          "type": "string",
+          "description": "Tag filter for op=nodes."
+        },
+        "from": {
+          "type": "string",
+          "description": "Source node id for op=path."
+        },
+        "to": {
+          "type": "string",
+          "description": "Target node id for op=path."
+        },
+        "id": {
+          "type": "string",
+          "description": "Node id for op=consumers-of."
+        }
+      }
+    },
+    "output": {
+      "type": "object",
+      "required": ["op", "graph_present", "result"],
+      "properties": {
+        "op": { "type": "string" },
+        "graph_present": { "type": "boolean" },
+        "path": { "type": "string" },
+        "result": {
+          "type": ["array", "object", "null"],
+          "description": "Query result; array for nodes/edges/consumers-of/unreachable/cycles, object for path/coverage, null when the graph is absent."
+        }
+      }
+    }
+  }
+}