From 814a9569b0499099609c54d07b4acafb15a259ac Mon Sep 17 00:00:00 2001
From: Jeisson <jeissonvargas.acidlabs@latam.com>
Date: Mon, 13 Jul 2026 11:09:42 -0500
Subject: [PATCH 1/3] feat(query): add relevance-aware graph retrieval

---
 README.md                      |  14 +
 graphify/__main__.py           |   3 +
 graphify/cli.py                | 106 ++--
 graphify/security.py           |  15 +-
 graphify/serve.py              | 982 ++++++++++++++++++++++++++++++---
 tests/test_cli_export.py       |  10 +-
 tests/test_explain_cli.py      |  17 +
 tests/test_path_cli.py         |  16 +
 tests/test_search_relevance.py | 880 +++++++++++++++++++++++++++++
 tests/test_security.py         |  27 +
 tests/test_serve.py            |  47 ++
 tests/test_serve_http.py       | 165 +++++-
 uv.lock                        | 212 +++----
 13 files changed, 2257 insertions(+), 237 deletions(-)
 create mode 100644 tests/test_search_relevance.py

diff --git a/README.md b/README.md
index 0a883e75b..2e89b26f3 100644
--- a/README.md
+++ b/README.md
@@ -634,9 +634,23 @@ graphify-out/
 
 /graphify query "what connects attention to the optimizer?"
 /graphify query "..." --dfs --budget 1500
+/graphify query "authentication community:Backend"
+/graphify query "Q: stale cache include:memory"
+/graphify query "callers god:RequestRouter"
 /graphify path "DigestAuth" "Response"
+/graphify path "src/auth.py::validate()" "src/http.py::respond()"  # disambiguate duplicate labels
 /graphify explain "SwinTransformer"
 
+# Query retrieval is staged across code, docs, tests, and likely communities.
+# Saved Q: work-memory nodes are fallback-only unless include:memory is present.
+# community:<id|label> and god:<label> scope both retrieval and traversal.
+# Quote filter labels containing spaces, for example community:"Authentication Flow".
+# Query normalization keeps the first 32 terms and at most 128 characters per term.
+# Ambiguous path/explain labels return ranked source-file::label identities and IDs; CLI lookup errors exit 2.
+# Source-qualified lookup bounds paths to 4,096 characters, 256 components, and 255 characters per component.
+# Query loads adjacent .graphify_labels.json names; canonical sidecar names override embedded community_name values.
+# Label sidecars are accepted atomically up to 1 MiB and 4,096 validated entries; invalid artifacts fall back safely.
+
 graphify save-result --question "Q" --answer "A" --nodes Foo Bar --outcome useful   # record how a Q&A turned out (work memory; outcome ∈ useful|dead_end|corrected)
 graphify reflect                   # aggregate graphify-out/memory/ outcomes into reflections/LESSONS.md
 graphify reflect --if-stale        # no-op when LESSONS.md is already newer than every input (cheap to run each session)
diff --git a/graphify/__main__.py b/graphify/__main__.py
index 82e422e0d..54acd1bcc 100644
--- a/graphify/__main__.py
+++ b/graphify/__main__.py
@@ -558,6 +558,9 @@ def _run_cli() -> None:
         print("    --context C             explicit edge-context filter (repeatable)")
         print("    --budget N              cap output at N tokens (default 2000)")
         print("    --graph <path>          path to graph.json (default graphify-out/graph.json)")
+        print("    query filters           include:memory, community:<id|label>, god:<label>")
+        print("    query limits            first 32 normalized terms, 128 characters per term")
+        print("  path/explain identities use <source-file>::<label> or an exact node ID; lookup errors exit 2")
         print("  affected \"X\"             reverse traversal to find nodes impacted by X")
         print("    --relation R            edge relation to traverse in reverse (repeatable)")
         print("    --depth N               reverse traversal depth (default 2)")
diff --git a/graphify/cli.py b/graphify/cli.py
index 0bb124777..42f8f070c 100644
--- a/graphify/cli.py
+++ b/graphify/cli.py
@@ -352,9 +352,17 @@ def dispatch_command(cmd: str) -> None:
             sys.exit(1)
     elif cmd == "query":
         if len(sys.argv) < 3:
-            print("Usage: graphify query \"<question>\" [--dfs] [--context C] [--budget N] [--graph path]", file=sys.stderr)
+            print(
+                "Usage: graphify query \"<question> [include:memory] "
+                "[community:<id|label>] [god:<label>]\" "
+                "[--dfs] [--context C] [--budget N] [--graph path]",
+                file=sys.stderr,
+            )
             sys.exit(1)
-        from graphify.serve import _query_graph_text
+        from graphify.serve import (
+            _attach_adjacent_community_labels,
+            _query_graph_text,
+        )
         from graphify.security import sanitize_label
         from networkx.readwrite import json_graph
         from graphify import querylog
@@ -411,6 +419,7 @@ def dispatch_command(cmd: str) -> None:
                 G = json_graph.node_link_graph(_raw, edges="links")
             except TypeError:
                 G = json_graph.node_link_graph(_raw)
+            _attach_adjacent_community_labels(G, gp)
             try:
                 from graphify.build import graph_has_legacy_ids as _legacy
                 if _legacy(_raw.get("nodes", [])):
@@ -446,6 +455,9 @@ def dispatch_command(cmd: str) -> None:
             token_budget=budget,
             duration_ms=(_time.perf_counter() - _t0) * 1000,
         )
+        if _result.startswith("Error:"):
+            print(_result, file=sys.stderr)
+            sys.exit(2)
         print(_result)
     elif cmd == "affected":
         if len(sys.argv) < 3:
@@ -602,7 +614,8 @@ def dispatch_command(cmd: str) -> None:
                 file=sys.stderr,
             )
             sys.exit(1)
-        from graphify.serve import _pick_scored_endpoint, _score_nodes
+        from graphify.serve import _format_resolution_error, _resolve_node
+        from graphify.security import sanitize_label as _sl
         from networkx.readwrite import json_graph
         import networkx as _nx
 
@@ -627,41 +640,32 @@ def dispatch_command(cmd: str) -> None:
             G = json_graph.node_link_graph(_raw, edges="links")
         except TypeError:
             G = json_graph.node_link_graph(_raw)
-        src_scored = _score_nodes(G, [t.lower() for t in source_label.split()])
-        tgt_scored = _score_nodes(G, [t.lower() for t in target_label.split()])
-        if not src_scored:
-            print(f"No node matching '{source_label}' found.", file=sys.stderr)
-            sys.exit(1)
-        if not tgt_scored:
-            print(f"No node matching '{target_label}' found.", file=sys.stderr)
-            sys.exit(1)
-        src_nid = _pick_scored_endpoint(G, src_scored, source_label)
-        tgt_nid = _pick_scored_endpoint(G, tgt_scored, target_label)
+        src_resolution = _resolve_node(G, source_label)
+        tgt_resolution = _resolve_node(G, target_label)
+        if src_resolution.node_id is None:
+            print(
+                _format_resolution_error(G, source_label, src_resolution, role="source"),
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        if tgt_resolution.node_id is None:
+            print(
+                _format_resolution_error(G, target_label, tgt_resolution, role="target"),
+                file=sys.stderr,
+            )
+            sys.exit(2)
+        src_nid = src_resolution.node_id
+        tgt_nid = tgt_resolution.node_id
         # Ambiguity guard: when both queries resolve to the same node, the
         # shortest path is trivially zero hops, which is almost never what the
         # caller wanted (see bug #828).
         if src_nid == tgt_nid:
             print(
-                f"'{source_label}' and '{target_label}' both resolved to the same "
-                f"node '{src_nid}'. Use a more specific label or the exact node ID.",
+                f"'{_sl(source_label)}' and '{_sl(target_label)}' both resolved to the same "
+                f"node '{_sl(str(src_nid))}'. Use a more specific label or the exact node ID.",
                 file=sys.stderr,
             )
             sys.exit(1)
-        for _name, _scored, _nid in (
-            ("source", src_scored, src_nid),
-            ("target", tgt_scored, tgt_nid),
-        ):
-            # A close runner-up only made the resolution ambiguous when the raw
-            # score head is what got picked; a full-token override was chosen on
-            # token coverage, not score, so the head's margin is irrelevant.
-            if len(_scored) >= 2 and _nid == _scored[0][1]:
-                _top, _runner = _scored[0][0], _scored[1][0]
-                if _top > 0 and (_top - _runner) / _top < 0.10:
-                    print(
-                        f"warning: {_name} match was ambiguous "
-                        f"(top score {_top:g}, runner-up {_runner:g})",
-                        file=sys.stderr,
-                    )
         try:
             path_nodes = _nx.shortest_path(G.to_undirected(as_view=True), src_nid, tgt_nid)
         except (_nx.NetworkXNoPath, _nx.NodeNotFound):
@@ -681,13 +685,15 @@ def dispatch_command(cmd: str) -> None:
                 forward = False
             rel = edata.get("relation", "")
             conf = edata.get("confidence", "")
-            conf_str = f" [{conf}]" if conf else ""
+            safe_rel = _sl(str(rel))
+            conf_str = f" [{_sl(str(conf))}]" if conf else ""
             if i == 0:
-                segments.append(G.nodes[u].get("label", u))
+                segments.append(_sl(str(G.nodes[u].get("label") or u)))
+            neighbor = _sl(str(G.nodes[v].get("label") or v))
             if forward:
-                segments.append(f"--{rel}{conf_str}--> {G.nodes[v].get('label', v)}")
+                segments.append(f"--{safe_rel}{conf_str}--> {neighbor}")
             else:
-                segments.append(f"<--{rel}{conf_str}-- {G.nodes[v].get('label', v)}")
+                segments.append(f"<--{safe_rel}{conf_str}-- {neighbor}")
         print(f"Shortest path ({hops} hops):\n  " + " ".join(segments))
         from graphify import querylog
         querylog.log_query(
@@ -701,7 +707,12 @@ def dispatch_command(cmd: str) -> None:
         if len(sys.argv) < 3:
             print('Usage: graphify explain "<node>" [--graph path]', file=sys.stderr)
             sys.exit(1)
-        from graphify.serve import _find_node
+        from graphify.serve import (
+            _format_resolution_error,
+            _resolve_node,
+            _source_display,
+        )
+        from graphify.security import sanitize_label as _sl
         from networkx.readwrite import json_graph
 
         label = sys.argv[2]
@@ -724,19 +735,17 @@ def dispatch_command(cmd: str) -> None:
             G = json_graph.node_link_graph(_raw, edges="links")
         except TypeError:
             G = json_graph.node_link_graph(_raw)
-        matches = _find_node(G, label)
-        if not matches:
-            print(f"No node matching '{label}' found.")
-            sys.exit(0)
-        nid = matches[0]
+        resolution = _resolve_node(G, label)
+        if resolution.node_id is None:
+            print(_format_resolution_error(G, label, resolution), file=sys.stderr)
+            sys.exit(2)
+        nid = resolution.node_id
         d = G.nodes[nid]
-        print(f"Node: {d.get('label', nid)}")
-        print(f"  ID:        {nid}")
-        print(
-            f"  Source:    {d.get('source_file', '')} {d.get('source_location', '')}".rstrip()
-        )
-        print(f"  Type:      {d.get('file_type', '')}")
-        print(f"  Community: {d.get('community_name') or d.get('community', '')}")
+        print(f"Node: {_sl(str(d.get('label') or nid))}")
+        print(f"  ID:        {_sl(str(nid))}")
+        print(f"  Source:    {_sl(_source_display(d))}")
+        print(f"  Type:      {_sl(str(d.get('file_type', '')))}")
+        print(f"  Community: {_sl(str(d.get('community_name') or d.get('community', '')))}")
         # Work-memory overlay: a derived experiential hint from `graphify reflect`,
         # merged in display-only from the .graphify_learning.json sidecar next to
         # graph.json. No line when the node has no overlay entry.
@@ -775,7 +784,8 @@ def dispatch_command(cmd: str) -> None:
                 rel = edata.get("relation", "")
                 conf = edata.get("confidence", "")
                 arrow = "-->" if direction == "out" else "<--"
-                print(f"  {arrow} {G.nodes[nb].get('label', nb)} [{rel}] [{conf}]")
+                neighbor = _sl(str(G.nodes[nb].get("label") or nb))
+                print(f"  {arrow} {neighbor} [{_sl(str(rel))}] [{_sl(str(conf))}]")
             if len(connections) > 20:
                 print(f"  ... and {len(connections) - 20} more")
         from graphify import querylog
diff --git a/graphify/security.py b/graphify/security.py
index 2dbe5bd77..7999de608 100644
--- a/graphify/security.py
+++ b/graphify/security.py
@@ -8,6 +8,7 @@
 import urllib.error
 import urllib.parse
 import urllib.request
+import unicodedata
 from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
@@ -388,18 +389,28 @@ def check_graph_file_size_cap(path: Path) -> None:
 # ---------------------------------------------------------------------------
 
 _CONTROL_CHAR_RE = re.compile(r"[\x00-\x1f\x7f]")
+_UNSAFE_LABEL_CATEGORIES = frozenset({"Cc", "Cf", "Cs", "Zl", "Zp"})
 _MAX_LABEL_LEN = 256
 
 
 def sanitize_label(text: str | None) -> str:
-    """Strip control characters and cap length.
+    """Strip record-forging Unicode controls/formats and cap length.
 
     Safe for embedding in JSON data (inside <script> tags) and plain text.
     For direct HTML injection, wrap the result with html.escape().
+
+    Unicode categories Cc/Cf/Cs/Zl/Zp cover C0/C1 controls, bidi and invisible
+    formatting controls, isolated surrogates, and Unicode line/paragraph
+    separators. Printable letters, marks, symbols, punctuation, and normal
+    spaces are preserved.
     """
     if text is None:
         return ""
-    text = _CONTROL_CHAR_RE.sub("", str(text))
+    text = "".join(
+        char
+        for char in str(text)
+        if unicodedata.category(char) not in _UNSAFE_LABEL_CATEGORIES
+    )
     if len(text) > _MAX_LABEL_LEN:
         text = text[:_MAX_LABEL_LEN]
     return text
diff --git a/graphify/serve.py b/graphify/serve.py
index 33db0108f..9035218a3 100644
--- a/graphify/serve.py
+++ b/graphify/serve.py
@@ -5,6 +5,9 @@
 import re
 import sys
 from array import array
+from collections import OrderedDict
+from dataclasses import dataclass
+from difflib import get_close_matches
 from pathlib import Path
 import networkx as nx
 from networkx.readwrite import json_graph
@@ -18,6 +21,102 @@
     _jieba = None
 
 
+_COMMUNITY_LABELS_FILENAME = ".graphify_labels.json"
+_MAX_COMMUNITY_LABELS_BYTES = 1024 * 1024
+_MAX_COMMUNITY_LABEL_ENTRIES = 4096
+_MAX_COMMUNITY_LABEL_LENGTH = 1024
+
+
+def _load_adjacent_community_labels(graph_path: str | Path) -> dict[int, str]:
+    """Load the canonical label artifact beside graph.json, if it is usable."""
+    labels_path = Path(graph_path).resolve().parent / _COMMUNITY_LABELS_FILENAME
+    try:
+        if labels_path.stat().st_size > _MAX_COMMUNITY_LABELS_BYTES:
+            return {}
+        with labels_path.open("rb") as stream:
+            payload = stream.read(_MAX_COMMUNITY_LABELS_BYTES + 1)
+        if len(payload) > _MAX_COMMUNITY_LABELS_BYTES:
+            return {}
+        data = json.loads(payload.decode("utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return {}
+    if not isinstance(data, dict):
+        return {}
+    wrappers = [key for key in ("labels", "communities") if key in data]
+    if len(wrappers) > 1:
+        return {}
+    if wrappers:
+        data = data[wrappers[0]]
+        if not isinstance(data, dict):
+            return {}
+    if len(data) > _MAX_COMMUNITY_LABEL_ENTRIES:
+        return {}
+    labels: dict[int, str] = {}
+    for raw_cid, raw_label in data.items():
+        try:
+            cid = int(raw_cid)
+        except (TypeError, ValueError):
+            return {}
+        if cid < 0 or cid in labels:
+            return {}
+        if isinstance(raw_label, dict):
+            raw_label = next(
+                (
+                    raw_label[key]
+                    for key in ("label", "name", "title")
+                    if raw_label.get(key) not in (None, "")
+                ),
+                "",
+            )
+        if not isinstance(raw_label, str) or len(raw_label) > _MAX_COMMUNITY_LABEL_LENGTH:
+            return {}
+        label = sanitize_label(raw_label).strip()
+        if not label:
+            return {}
+        labels[cid] = label
+    return labels
+
+
+def _attach_adjacent_community_labels(G: nx.Graph, graph_path: str | Path) -> None:
+    """Overlay canonical labels in memory without rewriting graph.json.
+
+    The adjacent artifact wins over embedded ``community_name`` values for IDs
+    present in the current graph. Missing, malformed, partial, or stale extra
+    entries are ignored, preserving embedded names and numeric community lookup.
+    """
+    labels = _load_adjacent_community_labels(graph_path)
+    present = set(_communities_from_graph(G))
+    current = {cid: label for cid, label in labels.items() if cid in present}
+    G.graph["_community_labels"] = current
+    for _, data in G.nodes(data=True):
+        try:
+            cid = int(data.get("community"))
+        except (TypeError, ValueError):
+            continue
+        if cid in current:
+            data["community_name"] = current[cid]
+
+
+def _query_context_key(
+    graph_path: str | Path,
+) -> tuple[int, int, int | None, int | None, int | None, int | None]:
+    """Return a cache key that invalidates on graph or label artifact changes."""
+    graph = Path(graph_path)
+    stat = graph.stat()
+    labels_path = graph.resolve().parent / _COMMUNITY_LABELS_FILENAME
+    try:
+        labels_stat = labels_path.stat()
+        labels_key = (
+            labels_stat.st_mtime_ns,
+            labels_stat.st_size,
+            labels_stat.st_ctime_ns,
+            labels_stat.st_ino,
+        )
+    except OSError:
+        labels_key = (None, None, None, None)
+    return stat.st_mtime_ns, stat.st_size, *labels_key
+
+
 def _load_graph(graph_path: str) -> nx.Graph:
     try:
         resolved = Path(graph_path).resolve()
@@ -45,6 +144,7 @@ def _load_graph(graph_path: str) -> nx.Graph:
             G = json_graph.node_link_graph(data, edges="links")
         except TypeError:
             G = json_graph.node_link_graph(data)
+        _attach_adjacent_community_labels(G, resolved)
         # Attach the work-memory overlay (derived sidecar next to graph.json) so
         # the query/MCP read surface can annotate NODE lines display-only. Empty
         # when no sidecar exists, leaving un-annotated output byte-identical.
@@ -107,6 +207,29 @@ def _is_searchable(term: str) -> bool:
     return True
 
 
+# Bound untrusted query normalization and graph-local IDF state. These limits are
+# well above normal natural-language/symbol queries while preventing one request
+# or a stream of unique requests from retaining unbounded work or cache entries.
+_MAX_QUERY_TERMS = 32
+_MAX_QUERY_TERM_LENGTH = 128
+_MAX_IDF_CACHE_ENTRIES = 512
+
+
+def _bounded_normalized_terms(terms) -> list[str]:
+    normalized: list[str] = []
+    seen: set[str] = set()
+    for raw in terms:
+        bounded = str(raw)[:_MAX_QUERY_TERM_LENGTH * 2]
+        for match in re.finditer(r"\w+", _strip_diacritics(bounded).lower()):
+            token = match.group(0)[:_MAX_QUERY_TERM_LENGTH]
+            if token and token not in seen:
+                seen.add(token)
+                normalized.append(token)
+                if len(normalized) >= _MAX_QUERY_TERMS:
+                    return normalized
+    return normalized
+
+
 # English question/filler words dropped from query terms so content words drive
 # BFS seeding. Without this, "how does the frontier cache work" seeds on "how"/
 # "the"/"work" (which prefix-match prose labels like "Working Principles" at 100x)
@@ -131,21 +254,107 @@ def _query_terms(question: str) -> list[str]:
     seeding. Falls back to the unfiltered terms if the query is all stopwords, so
     a question like "how does it work" still seeds on something."""
     terms: list[str] = []
-    for raw in question.split():
+    for raw_match in re.finditer(r"\S+", str(question)):
+        raw = raw_match.group(0)[:_MAX_QUERY_TERM_LENGTH]
         if _has_chinese(raw):
             for seg in _segment_chinese(raw.lower().strip()):
-                seg = seg.strip()
+                seg = seg.strip()[:_MAX_QUERY_TERM_LENGTH]
                 if seg and _is_searchable(seg):
                     terms.append(seg)
+                    if len(terms) >= _MAX_QUERY_TERMS:
+                        break
         else:
             # Strip punctuation without touching Unicode characters (avoid NFKD mangling non-Latin scripts)
-            for tok in re.findall(r"\w+", raw.lower()):
+            for match in re.finditer(r"\w+", raw.lower()):
+                tok = match.group(0)[:_MAX_QUERY_TERM_LENGTH]
                 if _is_searchable(tok):
                     terms.append(tok)
+                    if len(terms) >= _MAX_QUERY_TERMS:
+                        break
+        if len(terms) >= _MAX_QUERY_TERMS:
+            break
     content = [t for t in terms if t not in _QUERY_STOPWORDS]
     return content or terms
 
 
+@dataclass(frozen=True)
+class _QueryDirectives:
+    text: str
+    include_memory: bool = False
+    community: str | None = None
+    god: str | None = None
+
+
+_QUERY_SCOPE_RE = re.compile(
+    r"(?<!\w)(community|god):(?:\"([^\"]*)\"|'([^']*)'|([^\s]*))",
+    re.IGNORECASE,
+)
+
+
+def _parse_query_directives(question: str) -> _QueryDirectives:
+    """Remove search directives while preserving their values for scoping."""
+    include_memory = bool(re.search(r"(?<!\w)include:memory\b", question, re.IGNORECASE))
+    values: dict[str, str] = {}
+
+    def capture(match: re.Match) -> str:
+        values[match.group(1).lower()] = next(
+            value for value in match.groups()[1:] if value is not None
+        ).strip()
+        return " "
+
+    text = _QUERY_SCOPE_RE.sub(capture, question)
+    text = re.sub(r"(?<!\w)include:memory\b", " ", text, flags=re.IGNORECASE)
+    return _QueryDirectives(
+        text=" ".join(text.split()),
+        include_memory=include_memory,
+        community=values.get("community"),
+        god=values.get("god"),
+    )
+
+
+def _is_memory_node(data: dict) -> bool:
+    source = str(data.get("source_file") or "").replace("\\", "/").lower()
+    parts = [part for part in source.split("/") if part and part != "."]
+    return any(
+        parts[index:index + 2] == ["graphify-out", "memory"]
+        for index in range(len(parts) - 1)
+    )
+
+
+def _node_scope(data: dict) -> str:
+    if _is_memory_node(data):
+        return "memory"
+    source = str(data.get("source_file") or "").replace("\\", "/").lower()
+    parts = [part for part in source.split("/") if part]
+    name = parts[-1] if parts else ""
+    if (
+        any(part in {"test", "tests", "spec", "specs", "__tests__"} for part in parts)
+        or name.startswith("test_")
+        or ".test." in name
+        or ".spec." in name
+    ):
+        return "tests"
+    file_type = str(data.get("file_type") or "").lower()
+    if (
+        file_type in {"document", "paper", "rationale"}
+        or any(part in {"doc", "docs", "documentation"} for part in parts)
+        or Path(name).suffix in {".md", ".mdx", ".rst", ".txt", ".adoc"}
+    ):
+        return "docs"
+    return "code"
+
+
+def _query_scope_order(question: str, include_memory: bool) -> list[str]:
+    terms = set(_search_tokens(question))
+    if include_memory:
+        return ["memory", "code", "docs", "tests"]
+    if terms & {"test", "tests", "testing", "spec", "specs", "fixture", "fixtures"}:
+        return ["tests", "code", "docs"]
+    if terms & {"doc", "docs", "documentation", "readme", "guide", "paper"}:
+        return ["docs", "code", "tests"]
+    return ["code", "docs", "tests"]
+
+
 _EXACT_MATCH_BONUS = 1000.0
 _PREFIX_MATCH_BONUS = 100.0
 _SUBSTRING_MATCH_BONUS = 1.0
@@ -153,16 +362,26 @@ def _query_terms(question: str) -> list[str]:
 
 
 def _compute_idf(G: nx.Graph, terms: list[str]) -> dict[str, float]:
-    """IDF weights for query terms, cached in G.graph['_idf_cache'].
+    """IDF weights in a deterministic graph-local least-recently-used cache.
 
     Common terms like 'error' or 'exception' that match hundreds of nodes get
     low weights; rare identifiers like 'FooBarService' get high weights.
     Cache is stored on the graph object itself so it auto-invalidates when
     a hot-reload replaces G with a new object.
     """
-    cache: dict[str, float] = G.graph.setdefault("_idf_cache", {})
+    terms = _bounded_normalized_terms(terms)
+    existing = G.graph.get("_idf_cache")
+    if not isinstance(existing, OrderedDict):
+        existing = OrderedDict(existing or {})
+        G.graph["_idf_cache"] = existing
+    cache: OrderedDict[str, float] = existing
+    while len(cache) > _MAX_IDF_CACHE_ENTRIES:
+        cache.popitem(last=False)
     N = G.number_of_nodes() or 1
     uncached = [t for t in terms if t not in cache]
+    for term in terms:
+        if term in cache:
+            cache.move_to_end(term)
     if uncached:
         df: dict[str, int] = {t: 0 for t in uncached}
         for _, data in G.nodes(data=True):
@@ -174,6 +393,9 @@ def _compute_idf(G: nx.Graph, terms: list[str]) -> dict[str, float]:
                     df[t] += 1
         for t in uncached:
             cache[t] = math.log(1 + N / (1 + df[t]))
+            cache.move_to_end(t)
+            while len(cache) > _MAX_IDF_CACHE_ENTRIES:
+                cache.popitem(last=False)
     return {t: cache.get(t, math.log(1 + N)) for t in terms}
 
 
@@ -219,14 +441,37 @@ def _get_trigram_index(G: nx.Graph) -> dict:
         return idx
     ids = list(G.nodes())
     postings: dict[str, array] = {}
+    scopes: dict[str, str] = {}
+    memory_ids: set[str] = set()
+    community_names: dict[object, str] = {}
+    community_nodes: dict[object, set[str]] = {}
     for i, nid in enumerate(ids):
-        for g in _trigrams(_node_search_text(G.nodes[nid], nid)):
+        data = G.nodes[nid]
+        for g in _trigrams(_node_search_text(data, nid)):
             bucket = postings.get(g)
             if bucket is None:
                 bucket = array("i")
                 postings[g] = bucket
             bucket.append(i)
-    idx = {"ids": ids, "postings": postings, "set_cache": {}}
+        scope = _node_scope(data)
+        scopes[nid] = scope
+        if scope == "memory":
+            memory_ids.add(nid)
+        cid = data.get("community")
+        if cid is not None:
+            community_names.setdefault(
+                cid, str(data.get("community_name") or f"Community {cid}")
+            )
+            community_nodes.setdefault(cid, set()).add(nid)
+    idx = {
+        "ids": ids,
+        "postings": postings,
+        "set_cache": {},
+        "scopes": scopes,
+        "memory_ids": frozenset(memory_ids),
+        "community_names": community_names,
+        "community_nodes": community_nodes,
+    }
     G.graph["_trigram_index"] = idx
     return idx
 
@@ -288,7 +533,7 @@ def _score_nodes(G: nx.Graph, terms: list[str]) -> list[tuple[float, str]]:
     # Dedupe tokens, order-preserving (as _pick_seeds already does): a repeated
     # query word must not double-count every tier, and with coverage scaling
     # below it would also inflate the matched-term ratio (#1602).
-    norm_terms = list(dict.fromkeys(tok for t in terms for tok in _search_tokens(t)))
+    norm_terms = _bounded_normalized_terms(terms)
     n_terms = len(norm_terms)
     idf = _compute_idf(G, norm_terms)
     # Whole-query string for full-label matching (mirrors _find_node's `term`).
@@ -372,6 +617,84 @@ def _score_nodes(G: nx.Graph, terms: list[str]) -> list[tuple[float, str]]:
     return scored
 
 
+def _stage_candidates(
+    G: nx.Graph,
+    scored: list[tuple[float, str]],
+    question: str,
+    *,
+    include_memory: bool = False,
+    limit: int = 24,
+    global_quota: int = 2,
+) -> tuple[list[tuple[float, str]], dict]:
+    """Retain global, per-scope, and likely-community candidates in score order."""
+    if not scored:
+        return [], {"scopes": [], "communities": [], "global": 0, "cross_community": 0}
+
+    scope_order = _query_scope_order(question, include_memory)
+    ranked_scopes = {scope: rank for rank, scope in enumerate(scope_order)}
+    globally_ranked = sorted(
+        scored,
+        key=lambda item: (
+            -item[0],
+            len(str(G.nodes[item[1]].get("label") or item[1])),
+            str(G.nodes[item[1]].get("source_file") or ""),
+            str(item[1]),
+        ),
+    )
+    scope_preferred = sorted(
+        globally_ranked,
+        key=lambda item: (
+            ranked_scopes.get(_lookup_node_scope(G, item[1]), len(ranked_scopes)),
+            -item[0],
+            str(G.nodes[item[1]].get("source_file") or ""),
+            str(item[1]),
+        ),
+    )
+
+    likely_communities: list[object] = []
+    for _, nid in globally_ranked:
+        community = G.nodes[nid].get("community")
+        if community is not None and community not in likely_communities:
+            likely_communities.append(community)
+        if len(likely_communities) == 2:
+            break
+
+    limit = max(0, limit)
+    global_top = globally_ranked[:min(limit, max(0, global_quota))]
+    selected_ids = {nid for _, nid in global_top}
+
+    for scope in scope_order:
+        head = next(
+            (item for item in globally_ranked if _lookup_node_scope(G, item[1]) == scope),
+            None,
+        )
+        if head is not None and head[1] not in selected_ids and len(selected_ids) < limit:
+            selected_ids.add(head[1])
+
+    cross_community = [
+        item for item in globally_ranked
+        if likely_communities and G.nodes[item[1]].get("community") not in likely_communities
+    ][:max(0, global_quota)]
+    for _, nid in cross_community:
+        if len(selected_ids) >= limit:
+            break
+        selected_ids.add(nid)
+
+    for _, nid in scope_preferred:
+        if len(selected_ids) >= limit:
+            break
+        selected_ids.add(nid)
+
+    staged = [item for item in globally_ranked if item[1] in selected_ids]
+    scopes = list(dict.fromkeys(_lookup_node_scope(G, nid) for _, nid in staged))
+    return staged, {
+        "scopes": scopes,
+        "communities": likely_communities,
+        "global": len(global_top),
+        "cross_community": sum(nid in selected_ids for _, nid in cross_community),
+    }
+
+
 def _pick_scored_endpoint(G: nx.Graph, scored: list[tuple[float, str]], query: str) -> str:
     """Pick a path endpoint from a _score_nodes result, preferring full-token matches.
 
@@ -403,6 +726,7 @@ def _pick_seeds(
     *,
     G: "nx.Graph | None" = None,
     terms: list[str] | None = None,
+    eligible_ids: set[str] | None = None,
 ) -> list[str]:
     """Select BFS seed nodes, stopping when score drops too far below the top.
 
@@ -468,6 +792,8 @@ def _seed_label_key(nid: str) -> str:
         norm_terms = sorted({tok for t in terms for tok in _search_tokens(t)})
         for term in norm_terms:
             term_scored = _score_nodes(G, [term])
+            if eligible_ids is not None:
+                term_scored = [item for item in term_scored if item[1] in eligible_ids]
             if not term_scored:
                 continue
             best_score = term_scored[0][0]
@@ -573,6 +899,7 @@ def _filter_graph_by_context(G: nx.Graph, context_filters: list[str] | None) ->
     if not filters:
         return G
     H = G.__class__()
+    H.graph.update(G.graph)
     H.add_nodes_from(G.nodes(data=True))
     if isinstance(G, (nx.MultiGraph, nx.MultiDiGraph)):
         for u, v, key, data in G.edges(keys=True, data=True):
@@ -585,10 +912,27 @@ def _filter_graph_by_context(G: nx.Graph, context_filters: list[str] | None) ->
     return H
 
 
-def _bfs(G: nx.Graph, start_nodes: list[str], depth: int) -> tuple[set[str], list[tuple]]:
+def _traversal_node_key(G: nx.Graph, nid: str) -> tuple:
+    data = G.nodes[nid]
+    return (
+        -G.degree(nid),
+        _strip_diacritics(str(data.get("label") or nid)).lower(),
+        str(data.get("source_file") or "").replace("\\", "/").lower(),
+        str(nid),
+    )
+
+
+def _bfs(
+    G: nx.Graph,
+    start_nodes: list[str],
+    depth: int,
+    max_nodes: int | None = None,
+    excluded_nodes: frozenset[str] | set[str] | None = None,
+) -> tuple[set[str], list[tuple]]:
     # Compute hub threshold: nodes above this degree are not expanded as transit.
     # p99 of degree distribution, floored at 50 to avoid over-blocking small graphs.
-    degrees = [G.degree(n) for n in G.nodes()]
+    excluded = excluded_nodes or frozenset()
+    degrees = [G.degree(n) for n in G.nodes() if n not in excluded]
     if degrees:
         degrees_sorted = sorted(degrees)
         p99_idx = int(len(degrees_sorted) * 0.99)
@@ -599,24 +943,44 @@ def _bfs(G: nx.Graph, start_nodes: list[str], depth: int) -> tuple[set[str], lis
     visited: set[str] = set(start_nodes)
     frontier = set(start_nodes)
     edges_seen: list[tuple] = []
+    edge_keys: set[object] = set()
+    node_limit = max(max_nodes or len(G), len(visited))
+    edge_limit = max(node_limit * 2, len(start_nodes))
     for _ in range(depth):
         next_frontier: set[str] = set()
-        for n in frontier:
+        for n in sorted(frontier, key=lambda nid: _traversal_node_key(G, nid)):
             # Don't expand through high-degree hubs (except seeds - a hub that
             # is the starting node should still be explored).
             if n not in seed_set and G.degree(n) >= hub_threshold:
                 continue
-            for neighbor in G.neighbors(n):
-                if neighbor not in visited:
+            neighbors = sorted(G.neighbors(n), key=lambda nid: _traversal_node_key(G, nid))
+            for neighbor in neighbors:
+                if neighbor in excluded:
+                    continue
+                edge_key = (n, neighbor) if G.is_directed() else frozenset((n, neighbor))
+                selected = neighbor in visited or neighbor in next_frontier
+                if not selected and len(visited) + len(next_frontier) < node_limit:
                     next_frontier.add(neighbor)
+                    selected = True
+                if selected and edge_key not in edge_keys and len(edges_seen) < edge_limit:
+                    edge_keys.add(edge_key)
                     edges_seen.append((n, neighbor))
         visited.update(next_frontier)
         frontier = next_frontier
+        if not frontier:
+            break
     return visited, edges_seen
 
 
-def _dfs(G: nx.Graph, start_nodes: list[str], depth: int) -> tuple[set[str], list[tuple]]:
-    degrees = [G.degree(n) for n in G.nodes()]
+def _dfs(
+    G: nx.Graph,
+    start_nodes: list[str],
+    depth: int,
+    max_nodes: int | None = None,
+    excluded_nodes: frozenset[str] | set[str] | None = None,
+) -> tuple[set[str], list[tuple]]:
+    excluded = excluded_nodes or frozenset()
+    degrees = [G.degree(n) for n in G.nodes() if n not in excluded]
     if degrees:
         degrees_sorted = sorted(degrees)
         p99_idx = int(len(degrees_sorted) * 0.99)
@@ -626,21 +990,61 @@ def _dfs(G: nx.Graph, start_nodes: list[str], depth: int) -> tuple[set[str], lis
     seed_set = set(start_nodes)
     visited: set[str] = set()
     edges_seen: list[tuple] = []
+    edge_keys: set[object] = set()
     stack = [(n, 0) for n in reversed(start_nodes)]
+    node_limit = max(max_nodes or len(G), len(start_nodes))
+    edge_limit = max(node_limit * 2, len(start_nodes))
     while stack:
         node, d = stack.pop()
         if node in visited or d > depth:
             continue
+        if len(visited) >= node_limit:
+            break
         visited.add(node)
         if node not in seed_set and G.degree(node) >= hub_threshold:
             continue
-        for neighbor in G.neighbors(node):
+        neighbors = sorted(
+            G.neighbors(node),
+            key=lambda nid: _traversal_node_key(G, nid),
+            reverse=True,
+        )
+        for neighbor in neighbors:
+            if neighbor in excluded:
+                continue
             if neighbor not in visited:
                 stack.append((neighbor, d + 1))
+                edge_key = (
+                    (node, neighbor) if G.is_directed() else frozenset((node, neighbor))
+                )
+                if edge_key in edge_keys or len(edges_seen) >= edge_limit:
+                    continue
+                edge_keys.add(edge_key)
                 edges_seen.append((node, neighbor))
     return visited, edges_seen
 
 
+def _source_display(data: dict) -> str:
+    source = str(data.get("source_file") or "")
+    location = str(data.get("source_location") or "")
+    if source:
+        return f"{source} {location}" if location else f"{source} (file only)"
+    origin = str(data.get("origin_file") or "")
+    if origin:
+        return f"external/reference (unowned; referenced from {origin})"
+    return "unowned (no source)"
+
+
+def _source_fields(data: dict) -> tuple[str, str]:
+    source = str(data.get("source_file") or "")
+    location = str(data.get("source_location") or "")
+    if source:
+        return source, location or "file-only"
+    origin = str(data.get("origin_file") or "")
+    if origin:
+        return "external/reference", f"unowned; origin={origin}"
+    return "unowned", "no-source"
+
+
 def _subgraph_to_text(G: nx.Graph, nodes: set[str], edges: list[tuple], token_budget: int = 2000, *, seeds: list[str] | None = None) -> str:
     """Render subgraph as text, cutting at token_budget (approx 3 chars/token).
 
@@ -654,7 +1058,7 @@ def _subgraph_to_text(G: nx.Graph, nodes: set[str], edges: list[tuple], token_bu
     overlay = getattr(G, "graph", {}).get("_learning_overlay", {}) or {}
     seed_set = set(seeds or [])
     ordered = [n for n in (seeds or []) if n in nodes] + \
-              sorted(nodes - seed_set, key=lambda n: G.degree(n), reverse=True)
+              sorted(nodes - seed_set, key=lambda nid: _traversal_node_key(G, nid))
     for nid in ordered:
         d = G.nodes[nid]
         # Every LLM-derived field passes through sanitize_label before being
@@ -670,10 +1074,11 @@ def _subgraph_to_text(G: nx.Graph, nodes: set[str], edges: list[tuple], token_bu
             status = sanitize_label(str(entry.get("status", "")))
             if status:
                 learning_suffix = f" learning={status}{':stale' if entry.get('stale') else ''}"
+        source, location = _source_fields(d)
         line = (
             f"NODE {sanitize_label(d.get('label', nid))} "
-            f"[src={sanitize_label(str(d.get('source_file', '')))} "
-            f"loc={sanitize_label(str(d.get('source_location', '')))} "
+            f"[src={sanitize_label(source)} "
+            f"loc={sanitize_label(location)} "
             f"community={sanitize_label(str(d.get('community_name') or d.get('community', '')))}"
             f"{learning_suffix}]"
         )
@@ -715,23 +1120,91 @@ def _query_graph_text(
     token_budget: int = 2000,
     context_filters: list[str] | None = None,
 ) -> str:
-    terms = _query_terms(question)
+    directives = _parse_query_directives(question)
+    scoped_nodes, scope_labels, scope_error = _resolve_query_scope(G, directives)
+    if scope_error:
+        return f"Error: {scope_error}"
+
+    search_text = directives.text or directives.god or ""
+    terms = _query_terms(search_text)
+    if not terms:
+        return "No searchable terms found after applying query filters."
     scored = _score_nodes(G, terms)
-    start_nodes = _pick_seeds(scored, G=G, terms=terms)
+    if scoped_nodes is not None:
+        scored = [item for item in scored if item[1] in scoped_nodes]
+
+    memory_mode = None
+    exclude_memory = False
+    memory_ids = _get_trigram_index(G)["memory_ids"]
+    if directives.include_memory:
+        memory_mode = "included"
+    else:
+        non_memory = [item for item in scored if item[1] not in memory_ids]
+        if non_memory:
+            scored = non_memory
+            exclude_memory = True
+        elif scored:
+            memory_mode = "fallback"
+
+    scored, stage = _stage_candidates(
+        G,
+        scored,
+        search_text,
+        include_memory=directives.include_memory,
+        global_quota=0 if scope_labels else 2,
+    )
+    eligible_ids = {nid for _, nid in scored}
+    start_nodes = _pick_seeds(
+        scored,
+        G=G,
+        terms=terms,
+        eligible_ids=eligible_ids,
+    )
     if not start_nodes:
         return "No matching nodes found."
     resolved_filters, filter_source = _resolve_context_filters(question, context_filters)
-    traversal_graph = _filter_graph_by_context(G, resolved_filters)
-    nodes, edges = _dfs(traversal_graph, start_nodes, depth) if mode == "dfs" else _bfs(traversal_graph, start_nodes, depth)
+    traversal_graph = G if scoped_nodes is None else G.subgraph(scoped_nodes).copy()
+    traversal_graph = _filter_graph_by_context(traversal_graph, resolved_filters)
+    node_budget = max(len(start_nodes), max(4, token_budget // 24))
+    traversal = _dfs if mode == "dfs" else _bfs
+    nodes, edges = traversal(
+        traversal_graph,
+        start_nodes,
+        depth,
+        max_nodes=node_budget,
+        excluded_nodes=memory_ids if exclude_memory else None,
+    )
+    safe_starts = [sanitize_label(str(G.nodes[n].get("label") or n)) for n in start_nodes]
     header_parts = [
-        f"Traversal: {mode.upper()} depth={depth}",
-        f"Start: {[G.nodes[n].get('label', n) for n in start_nodes]}",
+        f"Traversal: {sanitize_label(mode.upper())} depth={depth}",
+        f"Start: {safe_starts}",
     ]
+    if scope_labels:
+        header_parts.append(f"Filter: {', '.join(scope_labels)}")
+    if memory_mode:
+        header_parts.append(f"Memory: {memory_mode}")
+    if stage["scopes"]:
+        header_parts.append(f"Scopes: {', '.join(stage['scopes'])}")
+    if stage["communities"]:
+        header_parts.append(
+            "Candidate communities: "
+            + ", ".join(sanitize_label(str(cid)) for cid in stage["communities"])
+        )
+    if stage["global"]:
+        header_parts.append(f"Global candidates: {stage['global']}")
+    if stage["cross_community"]:
+        header_parts.append(f"Cross-community candidates: {stage['cross_community']}")
     if resolved_filters:
         header_parts.append(f"Context: {', '.join(resolved_filters)} ({filter_source})")
-    header_parts.append(f"{len(nodes)} nodes found")
+    header_parts.append(f"{len(nodes)} nodes found (budget cap {node_budget})")
     header = " | ".join(header_parts) + "\n\n"
-    return header + _subgraph_to_text(traversal_graph, nodes, edges, token_budget)
+    return header + _subgraph_to_text(
+        traversal_graph,
+        nodes,
+        edges,
+        token_budget,
+        seeds=start_nodes,
+    )
 
 
 def _find_node(G: nx.Graph, label: str) -> list[str]:
@@ -802,6 +1275,364 @@ def _find_node(G: nx.Graph, label: str) -> list[str]:
     return source_exact + exact + prefix + substring
 
 
+@dataclass(frozen=True)
+class _NodeResolution:
+    node_id: str | None
+    candidates: tuple[str, ...] = ()
+
+
+def _node_identity(G: nx.Graph, nid: str) -> str:
+    data = G.nodes[nid]
+    label = str(data.get("label") or nid)
+    source = str(data.get("source_file") or "")
+    return f"{source}::{label}" if source else label
+
+
+_MAX_LOOKUP_PATH_LENGTH = 4096
+_MAX_LOOKUP_PATH_COMPONENTS = 256
+_MAX_LOOKUP_PATH_COMPONENT_LENGTH = 255
+
+
+def _normalize_lookup_path(value) -> str | None:
+    """Return a bounded, case-folded path for exact and suffix comparisons."""
+    raw = str(value).replace("\\", "/").strip()
+    if not raw or len(raw) > _MAX_LOOKUP_PATH_LENGTH:
+        return None
+    raw = _strip_diacritics(raw).lower()
+    if len(raw) > _MAX_LOOKUP_PATH_LENGTH:
+        return None
+    parts: list[str] = []
+    for part in raw.split("/"):
+        if not part or part == ".":
+            continue
+        if len(part) > _MAX_LOOKUP_PATH_COMPONENT_LENGTH:
+            return None
+        parts.append(part)
+        if len(parts) > _MAX_LOOKUP_PATH_COMPONENTS:
+            return None
+    return "/".join(parts) or None
+
+
+def _bounded_source_basename(value) -> str | None:
+    raw = str(value).replace("\\", "/").rstrip("/")
+    basename = raw.rsplit("/", 1)[-1]
+    if (
+        not basename
+        or basename in {".", ".."}
+        or len(basename) > _MAX_LOOKUP_PATH_COMPONENT_LENGTH
+    ):
+        return None
+    basename = _strip_diacritics(basename).lower()
+    return (
+        basename
+        if len(basename) <= _MAX_LOOKUP_PATH_COMPONENT_LENGTH
+        else None
+    )
+
+
+def _get_node_lookup_index(G: nx.Graph) -> dict:
+    """Graph-scoped exact lookup tables, invalidated when the graph object is replaced."""
+    cached = G.graph.get("_node_lookup_index")
+    if cached is not None and cached.get("node_count") == len(G):
+        return cached
+
+    folded_ids: dict[str, list[str]] = {}
+    source_exact: dict[str, list[str]] = {}
+    source_basenames: dict[str, list[str]] = {}
+    labels: dict[str, list[str]] = {}
+
+    def add(index: dict, key: str, nid: str) -> None:
+        if key:
+            index.setdefault(key, []).append(nid)
+
+    for nid, data in G.nodes(data=True):
+        nid_text = str(nid)
+        add(folded_ids, nid_text.lower(), nid)
+
+        label = _strip_diacritics(str(data.get("label") or nid)).lower()
+        for key in {label, label.rstrip("()"), " ".join(_search_tokens(label))}:
+            add(labels, key, nid)
+
+        source = data.get("source_file") or ""
+        normalized_source = _normalize_lookup_path(source)
+        if normalized_source:
+            add(source_exact, normalized_source, nid)
+        basename = _bounded_source_basename(source)
+        if basename:
+            add(source_basenames, basename, nid)
+
+    result = {
+        "node_count": len(G),
+        "folded_ids": folded_ids,
+        "source_exact": source_exact,
+        "source_basenames": source_basenames,
+        "labels": labels,
+    }
+    G.graph["_node_lookup_index"] = result
+    return result
+
+
+def _lookup_node_scope(G: nx.Graph, nid: str) -> str:
+    return _get_trigram_index(G)["scopes"][nid]
+
+
+def _eligible_candidates(candidates, eligible_ids: set[str] | None) -> list[str]:
+    if eligible_ids is None:
+        return list(candidates)
+    return [nid for nid in candidates if nid in eligible_ids]
+
+
+def _rank_resolution_candidates(G: nx.Graph, node_ids) -> tuple[str, ...]:
+    return tuple(sorted(
+        dict.fromkeys(node_ids),
+        key=lambda nid: (
+            str(G.nodes[nid].get("source_file") or ""),
+            str(G.nodes[nid].get("source_location") or ""),
+            str(nid),
+        ),
+    ))
+
+
+def _resolve_node(
+    G: nx.Graph,
+    query: str,
+    *,
+    eligible_ids: set[str] | None = None,
+) -> _NodeResolution:
+    """Resolve an ID, path-qualified identity, or readable label without guessing."""
+    raw = str(query).strip()
+    if not raw:
+        return _NodeResolution(None)
+
+    if raw in G and (eligible_ids is None or raw in eligible_ids):
+        return _NodeResolution(raw)
+    lookup = _get_node_lookup_index(G)
+    folded_ids = _eligible_candidates(lookup["folded_ids"].get(raw.lower(), ()), eligible_ids)
+    if len(folded_ids) == 1:
+        return _NodeResolution(folded_ids[0])
+    if len(folded_ids) > 1:
+        return _NodeResolution(None, _rank_resolution_candidates(G, folded_ids))
+
+    if "::" in raw:
+        source_query, label_query = raw.rsplit("::", 1)
+        normalized_source = _normalize_lookup_path(source_query)
+        if normalized_source is None:
+            return _NodeResolution(None)
+        normalized_label = _strip_diacritics(label_query).lower().strip()
+        exact_source = lookup["source_exact"].get(normalized_source, ())
+        source_candidates = exact_source or lookup["source_basenames"].get(
+            normalized_source.rsplit("/", 1)[-1], ()
+        )
+        qualified = []
+        for nid in _eligible_candidates(
+            source_candidates, eligible_ids
+        ):
+            data = G.nodes[nid]
+            candidate_source = _normalize_lookup_path(data.get("source_file") or "")
+            if candidate_source is None or (
+                candidate_source != normalized_source
+                and not candidate_source.endswith(f"/{normalized_source}")
+            ):
+                continue
+            label = _strip_diacritics(str(data.get("label") or nid)).lower()
+            if normalized_label in {label, label.rstrip("()"), " ".join(_search_tokens(label))}:
+                qualified.append(nid)
+        if len(qualified) == 1:
+            return _NodeResolution(qualified[0])
+        return _NodeResolution(None, _rank_resolution_candidates(G, qualified))
+
+    normalized_source = _normalize_lookup_path(raw)
+    source_matches: list[str] = []
+    if normalized_source:
+        exact_source = lookup["source_exact"].get(normalized_source, ())
+        source_candidates = exact_source or lookup["source_basenames"].get(
+            normalized_source.rsplit("/", 1)[-1], ()
+        )
+        source_matches = [
+            nid
+            for nid in _eligible_candidates(source_candidates, eligible_ids)
+            if (candidate_source := _normalize_lookup_path(
+                G.nodes[nid].get("source_file") or ""
+            )) is not None
+            and (
+                candidate_source == normalized_source
+                or candidate_source.endswith(f"/{normalized_source}")
+            )
+        ]
+    if source_matches:
+        basename = _strip_diacritics(Path(raw).name).lower()
+        file_nodes = [
+            nid for nid in source_matches
+            if str(G.nodes[nid].get("source_location") or "") == "L1"
+            and _strip_diacritics(str(G.nodes[nid].get("label") or "")).lower() == basename
+        ]
+        if len(file_nodes) == 1:
+            return _NodeResolution(file_nodes[0])
+        if len(source_matches) == 1:
+            return _NodeResolution(source_matches[0])
+        return _NodeResolution(None, _rank_resolution_candidates(G, source_matches))
+
+    normalized = _strip_diacritics(raw).lower()
+    exact_labels = _eligible_candidates(lookup["labels"].get(normalized, ()), eligible_ids)
+    if len(exact_labels) == 1:
+        return _NodeResolution(exact_labels[0])
+    if len(exact_labels) > 1:
+        return _NodeResolution(None, _rank_resolution_candidates(G, exact_labels))
+
+    scored = _score_nodes(G, _query_terms(raw))
+    if eligible_ids is not None:
+        scored = [item for item in scored if item[1] in eligible_ids]
+    if not scored:
+        return _NodeResolution(None)
+    selected = _pick_scored_endpoint(G, scored, raw)
+    query_tokens = set(_search_tokens(raw))
+    full_token_matches = [
+        nid for _, nid in scored
+        if query_tokens <= set(_search_tokens(G.nodes[nid].get("label") or nid))
+    ]
+    if len(full_token_matches) == 1:
+        return _NodeResolution(full_token_matches[0])
+    if len(full_token_matches) > 1:
+        return _NodeResolution(None, _rank_resolution_candidates(G, full_token_matches))
+    tied = [nid for score, nid in scored if score == scored[0][0]]
+    if len(tied) > 1:
+        return _NodeResolution(None, _rank_resolution_candidates(G, tied))
+    return _NodeResolution(selected)
+
+
+def _format_resolution_error(
+    G: nx.Graph,
+    query: str,
+    resolution: _NodeResolution,
+    role: str = "node",
+) -> str:
+    safe_query = sanitize_label(str(query))
+    safe_role = sanitize_label(str(role))
+    if not resolution.candidates:
+        return f"No node matching {safe_role} '{safe_query}' found."
+    lines = [
+        f"Ambiguous {safe_role} '{safe_query}'. Use a path-qualified identity or exact node ID:"
+    ]
+    for nid in resolution.candidates[:8]:
+        identity = sanitize_label(_node_identity(G, nid))
+        safe_nid = sanitize_label(str(nid))
+        lines.append(f"  - {identity} [id={safe_nid}]")
+    return "\n".join(lines)
+
+
+def _filter_directive(kind: str, value: object) -> str | None:
+    raw = str(value)
+    clean = sanitize_label(raw)
+    if not clean or clean != raw:
+        return None
+    if not re.search(r"[\s\"']", clean):
+        return f"{kind}:{clean}"
+    if '"' not in clean:
+        return f'{kind}:"{clean}"'
+    if "'" not in clean:
+        return f"{kind}:'{clean}'"
+    return None
+
+
+def _filter_suggestions(value: str, choices: list[tuple[str, str | None]]) -> list[str]:
+    if not choices:
+        return []
+    by_search = {search: directive for search, directive in choices if directive}
+    matches = get_close_matches(value, list(by_search), n=5, cutoff=0.2)
+    ranked = matches or list(by_search)[:5]
+    return list(dict.fromkeys(by_search[match] for match in ranked))
+
+
+def _get_god_records(G: nx.Graph) -> list[dict]:
+    cached = G.graph.get("_god_filter_records")
+    if cached is not None and cached.get("node_count") == len(G):
+        return cached["records"]
+    from graphify.analyze import god_nodes
+
+    records = god_nodes(G, top_n=len(G))
+    G.graph["_god_filter_records"] = {"node_count": len(G), "records": records}
+    return records
+
+
+def _resolve_query_scope(
+    G: nx.Graph,
+    directives: _QueryDirectives,
+) -> tuple[set[str] | None, list[str], str | None]:
+    if directives.community is None and directives.god is None:
+        return None, [], None
+
+    lookup = _get_trigram_index(G)
+    allowed: set[str] | None = None
+    labels: list[str] = []
+
+    if directives.community is not None:
+        communities = lookup["community_names"]
+        value = directives.community.strip()
+        if not value:
+            return set(), [], (
+                "Community filter value cannot be empty. "
+                "Use community:<id|label>."
+            )
+        matched = [cid for cid, name in communities.items() if str(cid) == value]
+        if not matched:
+            folded = _strip_diacritics(value).lower()
+            matched = [
+                cid for cid, name in communities.items()
+                if _strip_diacritics(name).lower() == folded
+            ]
+        if len(matched) != 1:
+            choices = [
+                (f"{cid} {name}", _filter_directive("community", cid))
+                for cid, name in sorted(communities.items(), key=lambda item: str(item[0]))
+            ]
+            suggestions = _filter_suggestions(value, choices)
+            suffix = f" Suggestions: {', '.join(suggestions)}." if suggestions else ""
+            safe_value = sanitize_label(value)
+            return set(), [], f"Unknown or ambiguous community filter '{safe_value}'.{suffix}"
+        cid = matched[0]
+        allowed = set(lookup["community_nodes"][cid])
+        safe_cid = sanitize_label(str(cid))
+        labels.append(f"community:{safe_cid} ({sanitize_label(communities[cid])})")
+
+    if directives.god is not None:
+        if not directives.god.strip():
+            return set(), [], (
+                "God filter value cannot be empty. Use god:<label|id>."
+            )
+        god_records = _get_god_records(G)
+        god_ids = {record["id"] for record in god_records}
+        resolution = _resolve_node(G, directives.god, eligible_ids=god_ids)
+        if resolution.node_id is None:
+            if resolution.candidates:
+                suggestions = [
+                    directive
+                    for nid in resolution.candidates[:5]
+                    if (directive := _filter_directive("god", nid)) is not None
+                ]
+                suffix = f" Suggestions: {', '.join(suggestions)}." if suggestions else ""
+                safe_value = sanitize_label(directives.god)
+                return set(), [], f"Ambiguous god filter '{safe_value}'.{suffix}"
+            choices = [
+                (
+                    f"{record['id']} {record['label']}",
+                    _filter_directive("god", record["id"]),
+                )
+                for record in god_records
+            ]
+            suggestions = _filter_suggestions(directives.god, choices)
+            suffix = f" Suggestions: {', '.join(suggestions)}." if suggestions else ""
+            safe_value = sanitize_label(directives.god)
+            return set(), [], f"Unknown god filter '{safe_value}'.{suffix}"
+        god_id = resolution.node_id
+        neighborhood = {god_id, *G.to_undirected(as_view=True).neighbors(god_id)}
+        allowed = neighborhood if allowed is None else allowed & neighborhood
+        labels.append(f"god:{sanitize_label(str(G.nodes[god_id].get('label') or god_id))}")
+
+    if allowed is not None and not allowed:
+        return set(), labels, "The requested community/god filters have no nodes in common."
+    return allowed, labels, None
+
+
 def _filter_blank_stdin() -> None:
     """Filter blank lines from stdin before MCP reads it.
 
@@ -883,8 +1714,7 @@ def _load_ctx(path: str):
         tool error instead of killing a server that is happily serving other
         projects."""
         try:
-            s = Path(path).stat()
-            key = (s.st_mtime_ns, s.st_size)
+            key = _query_context_key(path)
         except FileNotFoundError:
             raise FileNotFoundError(f"graph.json not found: {path}")
         ent = _ctx_cache.get(path)
@@ -901,6 +1731,7 @@ def _load_ctx(path: str):
             # Warm the trigram index before exposing the graph so the first query
             # against it is fast (same rationale as the original startup warm-up).
             _get_trigram_index(new_G)
+            _get_node_lookup_index(new_G)
             comm = _communities_from_graph(new_G)
             _ctx_cache[path] = {"key": key, "G": new_G, "communities": comm}
             return new_G, comm
@@ -941,7 +1772,10 @@ async def list_tools() -> list[types.Tool]:
         _tools = [
             types.Tool(
                 name="query_graph",
-                description="Search the knowledge graph using BFS or DFS. Returns relevant nodes and edges as text context.",
+                description=(
+                    "Search the knowledge graph using staged BFS or DFS. Query filters: "
+                    "include:memory, community:<id|label>, god:<label>."
+                ),
                 inputSchema={
                     "type": "object",
                     "properties": {
@@ -961,7 +1795,7 @@ async def list_tools() -> list[types.Tool]:
             ),
             types.Tool(
                 name="get_node",
-                description="Get full details for a specific node by label or ID.",
+                description="Get a node by label, exact ID, or path::label identity.",
                 inputSchema={
                     "type": "object",
                     "properties": {"label": {"type": "string", "description": "Node label or ID to look up"}},
@@ -1104,29 +1938,29 @@ def _tool_query_graph(arguments: dict) -> str:
         return result
 
     def _tool_get_node(arguments: dict) -> str:
-        label = arguments["label"].lower()
-        matches = [(nid, d) for nid, d in G.nodes(data=True)
-                   if label in (d.get("label") or "").lower() or label == nid.lower()]
-        if not matches:
-            return f"No node matching '{label}' found."
-        nid, d = matches[0]
+        label = arguments["label"]
+        resolution = _resolve_node(G, label)
+        if resolution.node_id is None:
+            return _format_resolution_error(G, label, resolution)
+        nid = resolution.node_id
+        d = G.nodes[nid]
         # Sanitise every LLM-derived field before concatenation (F-010).
         return "\n".join([
             f"Node: {sanitize_label(d.get('label', nid))}",
             f"  ID: {sanitize_label(nid)}",
-            f"  Source: {sanitize_label(str(d.get('source_file', '')))} {sanitize_label(str(d.get('source_location', '')))}",
+            f"  Source: {sanitize_label(_source_display(d))}",
             f"  Type: {sanitize_label(str(d.get('file_type', '')))}",
             f"  Community: {sanitize_label(str(d.get('community_name') or d.get('community', '')))}",
             f"  Degree: {G.degree(nid)}",
         ])
 
     def _tool_get_neighbors(arguments: dict) -> str:
-        label = arguments["label"].lower()
+        label = arguments["label"]
         rel_filter = arguments.get("relation_filter", "").lower()
-        matches = _find_node(G, label)
-        if not matches:
-            return f"No node matching '{label}' found."
-        nid = matches[0]
+        resolution = _resolve_node(G, label)
+        if resolution.node_id is None:
+            return _format_resolution_error(G, label, resolution)
+        nid = resolution.node_id
         lines = [f"Neighbors of {sanitize_label(G.nodes[nid].get('label', nid))}:"]
         for nb in G.successors(nid):
             d = edge_data(G, nid, nb)
@@ -1168,7 +2002,10 @@ def _tool_god_nodes(arguments: dict) -> str:
         from graphify.analyze import god_nodes as _god_nodes
         nodes = _god_nodes(G, top_n=int(arguments.get("top_n", 10)))
         lines = ["God nodes (most connected):"]
-        lines += [f"  {i}. {n['label']} - {n['degree']} edges" for i, n in enumerate(nodes, 1)]
+        lines += [
+            f"  {i}. {sanitize_label(str(n['label']))} - {n['degree']} edges"
+            for i, n in enumerate(nodes, 1)
+        ]
         return "\n".join(lines)
 
     def _tool_graph_stats(_: dict) -> str:
@@ -1184,42 +2021,36 @@ def _tool_graph_stats(_: dict) -> str:
         )
 
     def _tool_shortest_path(arguments: dict) -> str:
-        src_scored = _score_nodes(G, [t.lower() for t in arguments["source"].split()])
-        tgt_scored = _score_nodes(G, [t.lower() for t in arguments["target"].split()])
-        if not src_scored:
-            return f"No node matching source '{arguments['source']}' found."
-        if not tgt_scored:
-            return f"No node matching target '{arguments['target']}' found."
-        src_nid = _pick_scored_endpoint(G, src_scored, arguments["source"])
-        tgt_nid = _pick_scored_endpoint(G, tgt_scored, arguments["target"])
+        src_resolution = _resolve_node(G, arguments["source"])
+        tgt_resolution = _resolve_node(G, arguments["target"])
+        if src_resolution.node_id is None:
+            return _format_resolution_error(
+                G, arguments["source"], src_resolution, role="source"
+            )
+        if tgt_resolution.node_id is None:
+            return _format_resolution_error(
+                G, arguments["target"], tgt_resolution, role="target"
+            )
+        src_nid = src_resolution.node_id
+        tgt_nid = tgt_resolution.node_id
         # Ambiguity guard: when both queries resolve to the same node, the
         # shortest path is trivially zero hops, which is almost never what the
         # caller wanted (see bug #828).
         if src_nid == tgt_nid:
             return (
-                f"'{arguments['source']}' and '{arguments['target']}' both resolved to "
-                f"the same node '{src_nid}'. Use a more specific label or the exact node ID."
+                f"'{sanitize_label(str(arguments['source']))}' and "
+                f"'{sanitize_label(str(arguments['target']))}' both resolved to "
+                f"the same node '{sanitize_label(str(src_nid))}'. "
+                "Use a more specific label or the exact node ID."
             )
-        warnings: list[str] = []
-        for name, scored, nid in (
-            ("source", src_scored, src_nid),
-            ("target", tgt_scored, tgt_nid),
-        ):
-            # Only meaningful when the raw score head is what got picked — a
-            # full-token override was chosen on token coverage, not score.
-            if len(scored) >= 2 and nid == scored[0][1]:
-                top, runner = scored[0][0], scored[1][0]
-                if top > 0 and (top - runner) / top < 0.10:
-                    warnings.append(
-                        f"warning: {name} match was ambiguous "
-                        f"(top score {top:g}, runner-up {runner:g})"
-                    )
         max_hops = int(arguments.get("max_hops", 8))
         try:
             # Use undirected view for path-finding (works regardless of query src/tgt order)
             path_nodes = nx.shortest_path(G.to_undirected(as_view=True), src_nid, tgt_nid)
         except (nx.NetworkXNoPath, nx.NodeNotFound):
-            return f"No path found between '{G.nodes[src_nid].get('label', src_nid)}' and '{G.nodes[tgt_nid].get('label', tgt_nid)}'."
+            source = sanitize_label(str(G.nodes[src_nid].get("label") or src_nid))
+            target = sanitize_label(str(G.nodes[tgt_nid].get("label") or tgt_nid))
+            return f"No path found between '{source}' and '{target}'."
         hops = len(path_nodes) - 1
         if hops > max_hops:
             return f"Path exceeds max_hops={max_hops} ({hops} hops found)."
@@ -1234,15 +2065,16 @@ def _tool_shortest_path(arguments: dict) -> str:
                 forward = False
             rel = edata.get("relation", "")
             conf = edata.get("confidence", "")
-            conf_str = f" [{conf}]" if conf else ""
+            safe_rel = sanitize_label(str(rel))
+            conf_str = f" [{sanitize_label(str(conf))}]" if conf else ""
             if i == 0:
-                segments.append(G.nodes[u].get("label", u))
+                segments.append(sanitize_label(str(G.nodes[u].get("label") or u)))
+            neighbor = sanitize_label(str(G.nodes[v].get("label") or v))
             if forward:
-                segments.append(f"--{rel}{conf_str}--> {G.nodes[v].get('label', v)}")
+                segments.append(f"--{safe_rel}{conf_str}--> {neighbor}")
             else:
-                segments.append(f"<--{rel}{conf_str}-- {G.nodes[v].get('label', v)}")
-        prefix = ("\n".join(warnings) + "\n") if warnings else ""
-        return prefix + f"Shortest path ({hops} hops):\n  " + " ".join(segments)
+                segments.append(f"<--{safe_rel}{conf_str}-- {neighbor}")
+        return f"Shortest path ({hops} hops):\n  " + " ".join(segments)
 
     def _tool_list_prs(arguments: dict) -> str:
         from graphify.prs import fetch_prs, fetch_worktrees, format_prs_text, _detect_default_branch
diff --git a/tests/test_cli_export.py b/tests/test_cli_export.py
index 6173a61aa..88c87fc9f 100644
--- a/tests/test_cli_export.py
+++ b/tests/test_cli_export.py
@@ -254,10 +254,11 @@ def test_path_uses_graphify_out_env(tmp_path):
 
 # ── graphify explain ─────────────────────────────────────────────────────────
 
-def test_explain_runs_without_error(tmp_path):
+def test_explain_unknown_node_returns_usage_error(tmp_path):
     _make_graph(tmp_path)
     r = _run(["explain", "test"], tmp_path)
-    assert r.returncode == 0, r.stderr
+    assert r.returncode == 2
+    assert "No node matching node 'test' found." in r.stderr
 
 
 def test_explain_missing_graph_fails(tmp_path):
@@ -265,7 +266,7 @@ def test_explain_missing_graph_fails(tmp_path):
     assert r.returncode != 0
 
 
-def test_explain_uses_graphify_out_env(tmp_path):
+def test_explain_unknown_uses_graphify_out_env_and_returns_usage_error(tmp_path):
     out = _make_graph(tmp_path)
     custom_out = tmp_path / "custom-graph"
     out.rename(custom_out)
@@ -274,7 +275,8 @@ def test_explain_uses_graphify_out_env(tmp_path):
 
     r = _run(["explain", "test"], tmp_path, env=env)
 
-    assert r.returncode == 0, r.stderr
+    assert r.returncode == 2
+    assert "No node matching node 'test' found." in r.stderr
 
 
 # ── graphify export unknown format ───────────────────────────────────────────
diff --git a/tests/test_explain_cli.py b/tests/test_explain_cli.py
index 7759f30e3..635d31c1c 100644
--- a/tests/test_explain_cli.py
+++ b/tests/test_explain_cli.py
@@ -1,6 +1,7 @@
 """Regression tests for `graphify explain` arrow direction (#853)."""
 from __future__ import annotations
 import json
+import pytest
 import graphify.__main__ as mainmod
 
 
@@ -56,6 +57,22 @@ def test_caller_shows_callee_as_outbound(monkeypatch, tmp_path, capsys):
     assert "<-- " not in out
 
 
+def test_unknown_node_exits_usage_error(monkeypatch, tmp_path, capsys):
+    p = _write_graph(tmp_path)
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(
+        mainmod.sys,
+        "argv",
+        ["graphify", "explain", "missing", "--graph", str(p)],
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    assert exc_info.value.code == 2
+    assert "No node matching node 'missing' found." in capsys.readouterr().err
+
+
 def test_explain_source_file_path_prefers_file_level_node(monkeypatch, tmp_path, capsys):
     source_file = "app/api/example/route.ts"
     graph_data = {
diff --git a/tests/test_path_cli.py b/tests/test_path_cli.py
index 8b979e3a6..b47713e0f 100644
--- a/tests/test_path_cli.py
+++ b/tests/test_path_cli.py
@@ -49,6 +49,22 @@ def test_reverse_arrow(monkeypatch, tmp_path, capsys):
     assert "validateSanitySession() --calls [EXTRACTED]--> createPatchHandler()" not in out
 
 
+def test_unknown_endpoint_exits_usage_error(monkeypatch, tmp_path, capsys):
+    p = _write_graph(tmp_path)
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(
+        mainmod.sys,
+        "argv",
+        ["graphify", "path", "missing", "validate", "--graph", str(p)],
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    assert exc_info.value.code == 2
+    assert "No node matching source 'missing' found." in capsys.readouterr().err
+
+
 def _write_misranking_graph(tmp_path):
     """Graph where IDF scoring ranks a partial-token decoy above the full match.
 
diff --git a/tests/test_search_relevance.py b/tests/test_search_relevance.py
new file mode 100644
index 000000000..d7b471421
--- /dev/null
+++ b/tests/test_search_relevance.py
@@ -0,0 +1,880 @@
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+
+import networkx as nx
+import pytest
+from networkx.readwrite import json_graph
+
+import graphify.__main__ as mainmod
+import graphify.serve as serve_mod
+from graphify.serve import (
+    _bfs,
+    _dfs,
+    _format_resolution_error,
+    _query_graph_text,
+    _resolve_node,
+    _source_display,
+    _stage_candidates,
+    _subgraph_to_text,
+)
+
+
+def _memory_graph() -> nx.Graph:
+    graph = nx.Graph()
+    graph.add_node(
+        "code",
+        label="CacheService",
+        source_file="src/cache.py",
+        source_location="L10-L30",
+        community=0,
+    )
+    graph.add_node(
+        "memory",
+        label="Q: cache invalidation",
+        source_file="graphify-out/memory/cache.md",
+        source_location="L8",
+        community=0,
+    )
+    graph.add_edge("code", "memory", relation="mentions", confidence="EXTRACTED")
+    return graph
+
+
+def test_query_excludes_saved_memory_by_default() -> None:
+    text = _query_graph_text(_memory_graph(), "cache", depth=1)
+
+    assert "NODE CacheService" in text
+    assert "Q: cache invalidation" not in text
+
+
+def test_query_includes_saved_memory_explicitly() -> None:
+    text = _query_graph_text(_memory_graph(), "cache include:memory", depth=1)
+
+    assert "Memory: included" in text
+    assert "Q: cache invalidation" in text
+
+
+def test_query_falls_back_to_memory_when_it_is_the_only_match() -> None:
+    graph = _memory_graph()
+    text = _query_graph_text(graph, "invalidation", depth=1)
+
+    assert "Memory: fallback" in text
+    assert "Q: cache invalidation" in text
+
+
+def test_question_label_in_normal_docs_is_not_saved_memory() -> None:
+    graph = _memory_graph()
+    graph.add_node(
+        "faq",
+        label="Q: cache invalidation FAQ",
+        source_file="docs/faq.md",
+        source_location="L12",
+        community=0,
+    )
+
+    text = _query_graph_text(graph, "cache invalidation FAQ", depth=1)
+
+    assert "NODE Q: cache invalidation FAQ" in text
+    assert "Q: cache invalidation [" not in text
+    assert "Memory:" not in text
+
+
+def _write_community_graph(tmp_path):
+    graph = nx.Graph()
+    graph.add_node(
+        "route",
+        label="RouteHandler",
+        source_file="src/route.py",
+        community=0,
+        community_name="Embedded Runtime",
+    )
+    graph.add_node(
+        "telemetry",
+        label="TelemetrySample",
+        source_file="src/telemetry.py",
+        community=1,
+        community_name="Embedded Telemetry",
+    )
+    path = tmp_path / "graph.json"
+    path.write_text(json.dumps(json_graph.node_link_data(graph, edges="links")))
+    return path
+
+
+def test_adjacent_community_labels_override_embedded_names_and_match_folded(
+    tmp_path,
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text(json.dumps({
+        "0": "Main Rúntime Orchestration",
+        "1": "Telemetry Sampling",
+    }))
+
+    graph = serve_mod._load_graph(str(graph_path))
+    text = _query_graph_text(
+        graph,
+        'RouteHandler community:"main runtime orchestration"',
+        depth=1,
+    )
+
+    assert graph.nodes["route"]["community_name"] == "Main Rúntime Orchestration"
+    assert "Filter: community:0 (Main Rúntime Orchestration)" in text
+    assert "NODE RouteHandler" in text
+
+
+def test_adjacent_community_labels_ignore_stale_extra_ids(tmp_path) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text(json.dumps({
+        "0": "Current Runtime",
+        "99": "Stale Removed Community",
+    }))
+
+    graph = serve_mod._load_graph(str(graph_path))
+
+    assert "Filter: community:0 (Current Runtime)" in _query_graph_text(
+        graph, "RouteHandler community:0"
+    )
+    assert "Unknown or ambiguous community" in _query_graph_text(
+        graph, 'RouteHandler community:"Stale Removed Community"'
+    )
+
+
+def test_malformed_adjacent_community_labels_preserve_embedded_and_numeric(
+    tmp_path,
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text("{not-json")
+
+    graph = serve_mod._load_graph(str(graph_path))
+    text = _query_graph_text(graph, "RouteHandler community:0")
+
+    assert graph.nodes["route"]["community_name"] == "Embedded Runtime"
+    assert "Filter: community:0 (Embedded Runtime)" in text
+
+
+def test_oversized_community_labels_are_rejected_before_open(
+    monkeypatch, tmp_path
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    labels_path = tmp_path / ".graphify_labels.json"
+    labels_path.write_bytes(b"x" * 65)
+    monkeypatch.setattr(serve_mod, "_MAX_COMMUNITY_LABELS_BYTES", 64)
+    original_open = Path.open
+
+    def guarded_open(path, *args, **kwargs):
+        if path == labels_path:
+            raise AssertionError("oversized sidecar must not be opened")
+        return original_open(path, *args, **kwargs)
+
+    monkeypatch.setattr(Path, "open", guarded_open)
+
+    assert serve_mod._load_adjacent_community_labels(graph_path) == {}
+
+
+def test_oversized_community_labels_preserve_embedded_and_numeric(
+    monkeypatch, tmp_path
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text(json.dumps({
+        "0": "Canonical Runtime Name That Exceeds The Patched Test Byte Cap",
+    }))
+    monkeypatch.setattr(serve_mod, "_MAX_COMMUNITY_LABELS_BYTES", 32)
+
+    graph = serve_mod._load_graph(str(graph_path))
+    text = _query_graph_text(graph, "RouteHandler community:0")
+
+    assert graph.nodes["route"]["community_name"] == "Embedded Runtime"
+    assert "Filter: community:0 (Embedded Runtime)" in text
+
+
+def test_community_label_entry_cap_rejects_entire_artifact(
+    monkeypatch, tmp_path
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text(json.dumps({
+        "0": "Canonical Runtime",
+        "1": "Canonical Telemetry",
+        "2": "Stale Extra",
+    }))
+    monkeypatch.setattr(serve_mod, "_MAX_COMMUNITY_LABEL_ENTRIES", 2)
+
+    graph = serve_mod._load_graph(str(graph_path))
+
+    assert graph.graph["_community_labels"] == {}
+    assert graph.nodes["route"]["community_name"] == "Embedded Runtime"
+
+
+@pytest.mark.parametrize(
+    "payload",
+    [
+        [],
+        {"0": 123},
+        {"0": "Would Be Partial", "invalid": "Reject Everything"},
+        {"labels": []},
+        {"labels": {"0": "One"}, "communities": {"1": "Two"}},
+        {"0": {"name": 123}},
+        {"0": "x" * 1025},
+    ],
+)
+def test_malformed_community_label_shapes_reject_entire_artifact(
+    tmp_path, payload
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text(json.dumps(payload))
+
+    graph = serve_mod._load_graph(str(graph_path))
+
+    assert graph.graph["_community_labels"] == {}
+    assert graph.nodes["route"]["community_name"] == "Embedded Runtime"
+
+
+def test_cli_query_uses_adjacent_named_community(
+    monkeypatch, tmp_path, capsys
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text(json.dumps({
+        "0": "Main Runtime Orchestration",
+        "1": "Telemetry Sampling",
+    }))
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(mainmod.sys, "argv", [
+        "graphify",
+        "query",
+        'RouteHandler community:"Main Runtime Orchestration"',
+        "--graph",
+        str(graph_path),
+    ])
+
+    mainmod.main()
+
+    assert "Filter: community:0 (Main Runtime Orchestration)" in capsys.readouterr().out
+
+
+def test_cli_unknown_community_filter_exits_two_with_resolvable_suggestion(
+    monkeypatch, tmp_path, capsys
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    (tmp_path / ".graphify_labels.json").write_text(json.dumps({
+        "0": "Main Runtime Orchestration",
+        "1": "Telemetry Sampling",
+    }))
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(mainmod.sys, "argv", [
+        "graphify",
+        "query",
+        "RouteHandler community:MainRuntim",
+        "--graph",
+        str(graph_path),
+    ])
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    error = capsys.readouterr().err
+    assert exc_info.value.code == 2
+    assert "Error: Unknown or ambiguous community filter" in error
+    assert "community:0" in error
+
+
+def test_cli_ambiguous_god_filter_exits_two_with_exact_id_suggestions(
+    monkeypatch, tmp_path, capsys
+) -> None:
+    graph = nx.Graph()
+    graph.add_node("router_a", label="Router", source_file="src/a.py", community=0)
+    graph.add_node("router_b", label="Router", source_file="src/b.py", community=0)
+    graph.add_node("route", label="RouteHandler", source_file="src/route.py", community=0)
+    graph.add_edges_from([("router_a", "route"), ("router_b", "route")])
+    graph_path = tmp_path / "graph.json"
+    graph_path.write_text(json.dumps(json_graph.node_link_data(graph, edges="links")))
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(mainmod.sys, "argv", [
+        "graphify",
+        "query",
+        "RouteHandler god:Router",
+        "--graph",
+        str(graph_path),
+    ])
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    error = capsys.readouterr().err
+    assert exc_info.value.code == 2
+    assert "Error: Ambiguous god filter 'Router'." in error
+    assert "god:router_a" in error
+    assert "god:router_b" in error
+
+
+@pytest.mark.parametrize(
+    ("directive", "message"),
+    [
+        ('community:" "', "Community filter value cannot be empty"),
+        ('god:" "', "God filter value cannot be empty"),
+    ],
+)
+def test_cli_empty_query_filters_exit_two(
+    monkeypatch, tmp_path, capsys, directive, message
+) -> None:
+    graph_path = _write_community_graph(tmp_path)
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(mainmod.sys, "argv", [
+        "graphify",
+        "query",
+        f"RouteHandler {directive}",
+        "--graph",
+        str(graph_path),
+    ])
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    assert exc_info.value.code == 2
+    assert f"Error: {message}" in capsys.readouterr().err
+
+
+def _overload_graph() -> nx.DiGraph:
+    graph = nx.DiGraph()
+    graph.add_node(
+        "src_a_run",
+        label="run()",
+        source_file="src/a.py",
+        source_location="L3-L7",
+        community=0,
+    )
+    graph.add_node(
+        "src_b_run",
+        label="run()",
+        source_file="src/b.py",
+        source_location="L9-L14",
+        community=1,
+    )
+    graph.add_node("target", label="target()", source_file="src/target.py", community=1)
+    graph.add_edge("src_b_run", "target", relation="calls", confidence="EXTRACTED")
+    return graph
+
+
+def test_plain_duplicate_label_returns_ranked_candidates() -> None:
+    graph = _overload_graph()
+    resolution = _resolve_node(graph, "run")
+
+    assert resolution.node_id is None
+    assert resolution.candidates == ("src_a_run", "src_b_run")
+    message = _format_resolution_error(graph, "run", resolution)
+    assert "src/a.py::run() [id=src_a_run]" in message
+    assert "src/b.py::run() [id=src_b_run]" in message
+
+
+def test_ambiguity_diagnostics_sanitize_graph_controlled_identity_fields() -> None:
+    graph = nx.Graph()
+    graph.add_node(
+        "bad\nid\x1b",
+        label="run()\nFORGED",
+        source_file="src/a.py\rINJECT",
+    )
+    resolution = serve_mod._NodeResolution(None, ("bad\nid\x1b",))
+
+    message = _format_resolution_error(graph, "run", resolution)
+
+    assert message.count("\n") == 1
+    assert "\r" not in message
+    assert "\x1b" not in message
+    assert "src/a.pyINJECT::run()FORGED [id=badid]" in message
+
+
+def test_path_qualified_identity_resolves_duplicate_label() -> None:
+    graph = _overload_graph()
+
+    assert _resolve_node(graph, "src/b.py::run()").node_id == "src_b_run"
+    assert _resolve_node(graph, "src_b_run").node_id == "src_b_run"
+
+
+def test_source_qualified_resolution_supports_exact_suffix_and_basename() -> None:
+    graph = nx.Graph()
+    graph.add_node("target", label="run()", source_file="repo/src/pkg/a.py")
+
+    assert _resolve_node(graph, "repo/src/pkg/a.py::run()").node_id == "target"
+    assert _resolve_node(graph, "src/pkg/a.py::run()").node_id == "target"
+    assert _resolve_node(graph, "a.py::run()").node_id == "target"
+
+
+def test_source_basename_resolution_reports_ambiguity() -> None:
+    graph = nx.Graph()
+    graph.add_node("left", label="run()", source_file="src/left/a.py")
+    graph.add_node("right", label="run()", source_file="src/right/a.py")
+
+    resolution = _resolve_node(graph, "a.py::run()")
+
+    assert resolution.node_id is None
+    assert resolution.candidates == ("left", "right")
+    assert _resolve_node(graph, "left/a.py::run()").node_id == "left"
+
+
+def test_source_index_does_not_materialize_adversarial_suffixes() -> None:
+    graph = nx.Graph()
+    source = "/".join([f"part{index}" for index in range(7_999)] + ["target.py"])
+    graph.add_node("deep", label="target()", source_file=source)
+
+    lookup = serve_mod._get_node_lookup_index(graph)
+
+    assert "source_suffixes" not in lookup
+    assert lookup["source_exact"] == {}
+    assert lookup["source_basenames"] == {"target.py": ["deep"]}
+    assert sum(len(index) for index in (
+        lookup["source_exact"], lookup["source_basenames"]
+    )) == 1
+    assert sum(
+        len(key)
+        for index in (lookup["source_exact"], lookup["source_basenames"])
+        for key in index
+    ) == len("target.py")
+
+
+@pytest.mark.parametrize(
+    "source_query",
+    [
+        "a" * 256,
+        "/".join(["a"] * 257),
+        "a" * 4097,
+    ],
+)
+def test_source_qualified_resolution_rejects_unbounded_queries(
+    source_query: str,
+) -> None:
+    graph = nx.Graph()
+    graph.add_node("target", label="run()", source_file="src/a.py")
+
+    assert _resolve_node(graph, f"{source_query}::run()").node_id is None
+
+
+def test_plain_overload_prefix_does_not_pick_equal_score_arbitrarily() -> None:
+    graph = nx.Graph()
+    graph.add_node("int", label="run(int)", source_file="src/int.py")
+    graph.add_node("str", label="run(str)", source_file="src/str.py")
+
+    resolution = _resolve_node(graph, "run")
+
+    assert resolution.node_id is None
+    assert resolution.candidates == ("int", "str")
+
+
+def _write_graph(tmp_path, graph: nx.Graph):
+    path = tmp_path / "graph.json"
+    path.write_text(json.dumps(json_graph.node_link_data(graph, edges="links")))
+    return path
+
+
+def test_cli_explain_uses_shared_ambiguity_safe_resolver(
+    monkeypatch, tmp_path, capsys
+) -> None:
+    graph_path = _write_graph(tmp_path, _overload_graph())
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(
+        mainmod.sys,
+        "argv",
+        ["graphify", "explain", "run", "--graph", str(graph_path)],
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    assert exc_info.value.code == 2
+    assert _format_resolution_error(
+        _overload_graph(), "run", _resolve_node(_overload_graph(), "run")
+    ) in capsys.readouterr().err
+
+
+def test_cli_ambiguity_diagnostics_strip_control_characters(
+    monkeypatch, tmp_path, capsys
+) -> None:
+    graph = nx.DiGraph()
+    graph.add_node(
+        "a_run\nid",
+        label="run()\nFORGED",
+        source_file="src/a.py\rINJECT",
+    )
+    graph.add_node(
+        "b_run\x1bid",
+        label="run()\x00SECOND",
+        source_file="src/b.py\nSPOOF",
+    )
+    graph_path = _write_graph(tmp_path, graph)
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(
+        mainmod.sys,
+        "argv",
+        ["graphify", "explain", "run", "--graph", str(graph_path)],
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+    output = capsys.readouterr().err
+
+    assert exc_info.value.code == 2
+    assert "\r" not in output
+    assert "\x00" not in output
+    assert "\x1b" not in output
+    assert "src/a.pyINJECT::run()FORGED [id=a_runid]" in output
+    assert "src/b.pySPOOF::run()SECOND [id=b_runid]" in output
+
+
+def test_cli_path_accepts_shared_path_qualified_identity(
+    monkeypatch, tmp_path, capsys
+) -> None:
+    graph_path = _write_graph(tmp_path, _overload_graph())
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(
+        mainmod.sys,
+        "argv",
+        [
+            "graphify",
+            "path",
+            "src/b.py::run()",
+            "target",
+            "--graph",
+            str(graph_path),
+        ],
+    )
+
+    mainmod.main()
+
+    assert "run() --calls [EXTRACTED]--> target()" in capsys.readouterr().out
+
+
+def test_cli_path_ambiguous_endpoint_exits_usage_error(
+    monkeypatch, tmp_path, capsys
+) -> None:
+    graph_path = _write_graph(tmp_path, _overload_graph())
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(
+        mainmod.sys,
+        "argv",
+        ["graphify", "path", "run", "target", "--graph", str(graph_path)],
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    assert exc_info.value.code == 2
+    assert "Ambiguous source 'run'" in capsys.readouterr().err
+
+
+def test_staged_candidates_retain_cross_community_global_quota() -> None:
+    graph = nx.Graph()
+    scored = []
+    for index, community in enumerate((0, 0, 1, 1, 2, 3)):
+        nid = f"n{index}"
+        graph.add_node(
+            nid,
+            label=f"cache_{index}",
+            source_file=f"src/cache_{index}.py",
+            community=community,
+        )
+        scored.append((100.0 - index, nid))
+
+    staged, metadata = _stage_candidates(
+        graph, scored, "cache", limit=5, global_quota=1
+    )
+    selected = {nid for _, nid in staged}
+
+    assert metadata["communities"] == [0, 1]
+    assert metadata["global"] == 1
+    assert selected & {"n4", "n5"}
+    assert len(staged) == 5
+
+
+@pytest.mark.parametrize(
+    ("source_file", "expected_scope"),
+    [("docs/exact.md", "docs"), ("tests/test_exact.py", "tests")],
+)
+def test_staging_never_drops_global_exact_cross_scope_match(
+    source_file: str, expected_scope: str
+) -> None:
+    graph = nx.Graph()
+    graph.add_node("exact", label="ExactTarget", source_file=source_file, community=9)
+    for index in range(10):
+        graph.add_node(
+            f"code_{index}",
+            label=f"TargetHelper{index}",
+            source_file=f"src/helper_{index}.py",
+            community=0,
+        )
+    scored = [(1000.0, "exact")] + [
+        (100.0 - index, f"code_{index}") for index in range(10)
+    ]
+
+    staged, metadata = _stage_candidates(
+        graph, scored, "target", limit=2, global_quota=1
+    )
+
+    assert staged[0] == (1000.0, "exact")
+    assert "exact" in {nid for _, nid in staged}
+    assert expected_scope in metadata["scopes"]
+
+
+def _filtered_graph() -> nx.Graph:
+    graph = nx.Graph()
+    graph.add_node(
+        "router",
+        label="RequestRouter",
+        source_file="src/router.py",
+        source_location="L10-L40",
+        community=0,
+        community_name="Backend Flow",
+    )
+    for index in range(4):
+        graph.add_node(
+            f"route_{index}",
+            label=f"RouteHandler{index}",
+            source_file=f"src/route_{index}.py",
+            community=0,
+            community_name="Backend Flow",
+        )
+        graph.add_edge("router", f"route_{index}", relation="calls")
+    graph.add_node(
+        "ui",
+        label="RouteHandlerUI",
+        source_file="web/ui.py",
+        community=1,
+        community_name="Frontend",
+    )
+    return graph
+
+
+def test_community_filter_scopes_candidates_and_traversal() -> None:
+    text = _query_graph_text(
+        _filtered_graph(), 'RouteHandler community:"Backend Flow"', depth=2
+    )
+
+    assert "Filter: community:0 (Backend Flow)" in text
+    assert "RouteHandler0" in text
+    assert "RouteHandlerUI" not in text
+
+
+def test_god_filter_scopes_to_hub_neighborhood() -> None:
+    text = _query_graph_text(_filtered_graph(), "RouteHandler god:RequestRouter", depth=2)
+
+    assert "Filter: god:RequestRouter" in text
+    assert "RouteHandler0" in text
+    assert "RouteHandlerUI" not in text
+
+
+def test_unknown_filters_return_suggestions() -> None:
+    community = _query_graph_text(_filtered_graph(), "route community:Backnd")
+    god = _query_graph_text(_filtered_graph(), "route god:RequestRuter")
+
+    assert community.startswith("Error: Unknown or ambiguous community filter")
+    assert "community:0" in community
+    assert god.startswith("Error: Unknown god filter")
+    assert "god:router" in god
+
+
+@pytest.mark.parametrize(
+    ("question", "message"),
+    [
+        ('route community:" "', "Community filter value cannot be empty"),
+        ('route community:""', "Community filter value cannot be empty"),
+        ("route community:", "Community filter value cannot be empty"),
+        ('route god:" "', "God filter value cannot be empty"),
+        ('route god:""', "God filter value cannot be empty"),
+        ("route god:", "God filter value cannot be empty"),
+    ],
+)
+def test_empty_filters_return_diagnostics(question: str, message: str) -> None:
+    text = _query_graph_text(_filtered_graph(), question)
+
+    assert text.startswith(f"Error: {message}")
+
+
+def test_community_suggestion_is_copy_paste_resolvable() -> None:
+    graph = _filtered_graph()
+    error = _query_graph_text(graph, "route community:Backnd")
+    suggestion = re.search(r"community:[^, .]+", error)
+
+    assert suggestion is not None
+    resolved = _query_graph_text(graph, f"route {suggestion.group(0)}")
+    assert not resolved.startswith("Error:")
+    assert "Filter: community:0 (Backend Flow)" in resolved
+
+
+def test_filter_diagnostics_sanitize_community_and_god_labels() -> None:
+    graph = _filtered_graph()
+    graph.nodes["router"]["label"] = "RequestRouter\nFORGED\x1b"
+    graph.nodes["router"]["community_name"] = "Backend\rINJECT"
+    for index in range(4):
+        graph.nodes[f"route_{index}"]["community_name"] = "Backend\rINJECT"
+
+    community = _query_graph_text(graph, 'route community:"Backend\rINJECT"')
+    god = _query_graph_text(graph, 'route god:"RequestRouter\nFORGED\x1b"')
+
+    assert "\r" not in community and "INJECT" in community
+    assert "\x1b" not in god
+    assert "Filter: god:RequestRouterFORGED" in god
+
+
+def test_god_filter_resolves_exact_candidate_ranked_after_fifty() -> None:
+    graph = nx.Graph()
+    node_ids = [f"god{index}" for index in range(60)]
+    for index, nid in enumerate(node_ids):
+        graph.add_node(
+            nid,
+            label=f"God{index}",
+            source_file=f"src/entity_{index}.py",
+            community=0,
+        )
+    for index, nid in enumerate(node_ids):
+        graph.add_edge(nid, node_ids[(index + 1) % len(node_ids)])
+
+    text = _query_graph_text(graph, "God55 god:god55", depth=1)
+
+    assert not text.startswith("Error:")
+    assert "Filter: god:God55" in text
+
+
+def test_traversal_stops_at_node_budget_before_rendering() -> None:
+    graph = nx.path_graph([f"n{index}" for index in range(200)])
+    for nid in graph:
+        graph.nodes[nid].update(label=f"node_{nid}", source_file=f"src/{nid}.py")
+
+    visited, _ = _bfs(graph, ["n0"], depth=199, max_nodes=7)
+    text = _query_graph_text(graph, "node", depth=50, token_budget=120)
+
+    assert len(visited) == 7
+    header = text.splitlines()[0]
+    assert "5 nodes found (budget cap 5)" in header
+
+
+def _insertion_order_graph(reverse: bool) -> nx.Graph:
+    graph = nx.Graph()
+    nodes = ["start", "alpha", "beta", "gamma", "alpha_child"]
+    for nid in reversed(nodes) if reverse else nodes:
+        graph.add_node(nid, label=nid, source_file=f"src/{nid}.py", community=0)
+    edges = [
+        ("start", "alpha"),
+        ("start", "beta"),
+        ("start", "gamma"),
+        ("alpha", "alpha_child"),
+        ("alpha", "beta"),
+    ]
+    for source, target in reversed(edges) if reverse else edges:
+        graph.add_edge(source, target, relation="calls", confidence="EXTRACTED")
+    return graph
+
+
+@pytest.mark.parametrize("traversal", [_bfs, _dfs])
+def test_budgeted_traversal_is_independent_of_insertion_order(traversal) -> None:
+    forward = _insertion_order_graph(False)
+    reverse = _insertion_order_graph(True)
+
+    forward_nodes, forward_edges = traversal(forward, ["start"], depth=3, max_nodes=3)
+    reverse_nodes, reverse_edges = traversal(reverse, ["start"], depth=3, max_nodes=3)
+
+    assert forward_nodes == reverse_nodes
+    assert forward_edges == reverse_edges
+
+
+def test_budgeted_bfs_retains_edges_between_selected_nodes() -> None:
+    graph = _insertion_order_graph(False)
+
+    nodes, edges = _bfs(graph, ["start"], depth=2, max_nodes=3)
+
+    assert nodes == {"start", "alpha", "beta"}
+    assert ("alpha", "beta") in edges
+
+
+def test_query_output_is_independent_of_insertion_order() -> None:
+    forward = _query_graph_text(
+        _insertion_order_graph(False), "start", depth=3, token_budget=100
+    )
+    reverse = _query_graph_text(
+        _insertion_order_graph(True), "start", depth=3, token_budget=100
+    )
+
+    assert forward == reverse
+
+
+def test_resolver_reuses_graph_scoped_lookup_index(monkeypatch) -> None:
+    graph = nx.Graph()
+    for index in range(200):
+        graph.add_node(
+            f"node_{index}",
+            label=f"Target{index}",
+            source_file=f"src/target_{index}.py",
+        )
+    calls = 0
+    original = serve_mod._bounded_source_basename
+
+    def counted_basename(value):
+        nonlocal calls
+        calls += 1
+        return original(value)
+
+    monkeypatch.setattr(serve_mod, "_bounded_source_basename", counted_basename)
+
+    assert _resolve_node(graph, "src/target_199.py::Target199").node_id == "node_199"
+    first_scan_calls = calls
+    assert _resolve_node(graph, "src/target_198.py::Target198").node_id == "node_198"
+
+    assert first_scan_calls == len(graph)
+    assert calls == first_scan_calls
+
+
+def test_default_memory_exclusion_reuses_cached_classification(monkeypatch) -> None:
+    graph = nx.Graph()
+    for index in range(200):
+        graph.add_node(
+            f"node_{index}",
+            label=f"CacheTarget{index}",
+            source_file=f"src/cache_{index}.py",
+            community=0,
+        )
+    graph.add_node(
+        "memory",
+        label="Q: cache target",
+        source_file="graphify-out/memory/cache.md",
+        community=0,
+    )
+    calls = 0
+    original = serve_mod._is_memory_node
+
+    def counted_memory(data):
+        nonlocal calls
+        calls += 1
+        return original(data)
+
+    monkeypatch.setattr(serve_mod, "_is_memory_node", counted_memory)
+
+    _query_graph_text(graph, "CacheTarget199", depth=1)
+    first_scan_calls = calls
+    _query_graph_text(graph, "CacheTarget198", depth=1)
+
+    assert first_scan_calls == len(graph)
+    assert calls == first_scan_calls
+
+
+def test_source_rendering_preserves_spans_and_marks_unowned_nodes() -> None:
+    graph = nx.Graph()
+    graph.add_node(
+        "owned",
+        label="owned",
+        source_file="src/owned.py",
+        source_location="L10-L30",
+    )
+    graph.add_node("file_only", label="file", source_file="docs/guide.md")
+    graph.add_node(
+        "external",
+        label="ExternalType",
+        source_file="",
+        source_location="",
+        origin_file="src/consumer.py",
+    )
+    graph.add_node("concept", label="Architecture", source_file="")
+
+    text = _subgraph_to_text(graph, set(graph), [], token_budget=500)
+
+    assert "src=src/owned.py loc=L10-L30" in text
+    assert "src=docs/guide.md loc=file-only" in text
+    assert "src=external/reference loc=unowned; origin=src/consumer.py" in text
+    assert "NODE Architecture [src=unowned loc=no-source" in text
+    assert _source_display(graph.nodes["file_only"]) == "docs/guide.md (file only)"
+    assert "unowned" in _source_display(graph.nodes["external"])
diff --git a/tests/test_security.py b/tests/test_security.py
index 74669f938..8163bf218 100644
--- a/tests/test_security.py
+++ b/tests/test_security.py
@@ -211,6 +211,33 @@ def test_sanitize_label_strips_control_chars():
     assert "\x1f" not in result
     assert "helloworld" in result
 
+
+@pytest.mark.parametrize(
+    "unsafe",
+    [
+        "\x00",  # NUL (C0)
+        "\n",
+        "\r",
+        "\x1b",  # ESC
+        "\x85",  # NEXT LINE (C1)
+        "\u2028",  # line separator
+        "\u2029",  # paragraph separator
+        "\u200e",  # left-to-right mark
+        "\u202e",  # right-to-left override
+        "\u2066",  # left-to-right isolate
+        "\u2069",  # pop directional isolate
+        "\ud800",  # isolated high surrogate
+        "\udfff",  # isolated low surrogate
+    ],
+)
+def test_sanitize_label_strips_record_forging_unicode(unsafe):
+    assert sanitize_label(f"before{unsafe}after") == "beforeafter"
+
+
+def test_sanitize_label_preserves_printable_unicode():
+    text = "café 東京 Ελληνικά العربية 😀"
+    assert sanitize_label(text) == text
+
 def test_sanitize_label_caps_at_256():
     long_label = "a" * 300
     assert len(sanitize_label(long_label)) <= 256
diff --git a/tests/test_serve.py b/tests/test_serve.py
index 859cde026..274ec1b66 100644
--- a/tests/test_serve.py
+++ b/tests/test_serve.py
@@ -20,6 +20,9 @@
     _trigram_candidates,
     _filter_graph_by_context,
     _infer_context_filters,
+    _MAX_IDF_CACHE_ENTRIES,
+    _MAX_QUERY_TERM_LENGTH,
+    _MAX_QUERY_TERMS,
     _query_terms,
     _query_graph_text,
     _resolve_context_filters,
@@ -364,6 +367,16 @@ def test_query_terms_all_stopwords_falls_back_to_unfiltered():
     assert _query_terms("how does it work") == ["how", "does", "work"]
 
 
+def test_query_terms_bound_count_and_length():
+    query = " ".join(["x" * 1000] + [f"unique{index}" for index in range(1000)])
+
+    terms = _query_terms(query)
+
+    assert len(terms) == _MAX_QUERY_TERMS
+    assert max(map(len, terms)) == _MAX_QUERY_TERM_LENGTH
+    assert terms[-1] == f"unique{_MAX_QUERY_TERMS - 2}"
+
+
 def test_query_terms_filters_only_short_english_terms(monkeypatch):
     import graphify.serve as serve_mod
 
@@ -682,6 +695,40 @@ def test_idf_new_graph_starts_fresh():
     assert "_idf_cache" not in G2.graph
 
 
+def test_idf_cache_is_bounded_and_evicts_least_recently_used():
+    G = _make_graph()
+    for start in range(0, _MAX_IDF_CACHE_ENTRIES, _MAX_QUERY_TERMS):
+        _compute_idf(
+            G,
+            [
+                f"hostile{index}"
+                for index in range(start, min(start + _MAX_QUERY_TERMS, _MAX_IDF_CACHE_ENTRIES))
+            ],
+        )
+
+    _compute_idf(G, ["hostile0"])
+    _compute_idf(G, [f"hostile{_MAX_IDF_CACHE_ENTRIES}"])
+    cache = G.graph["_idf_cache"]
+
+    assert len(cache) == _MAX_IDF_CACHE_ENTRIES
+    assert "hostile0" in cache
+    assert "hostile1" not in cache
+    assert f"hostile{_MAX_IDF_CACHE_ENTRIES}" in cache
+
+
+def test_hostile_unique_query_stream_keeps_bounded_idf_state():
+    G = _make_graph()
+    for batch in range(40):
+        terms = [
+            (f"batch{batch}token{index}" + "x" * 1000)
+            for index in range(_MAX_QUERY_TERMS * 2)
+        ]
+        _compute_idf(G, terms)
+
+    assert len(G.graph["_idf_cache"]) == _MAX_IDF_CACHE_ENTRIES
+    assert all(len(term) <= _MAX_QUERY_TERM_LENGTH for term in G.graph["_idf_cache"])
+
+
 def test_idf_rare_term_gets_high_weight():
     """A term matching only 1 of N nodes should get IDF > 1."""
     import math
diff --git a/tests/test_serve_http.py b/tests/test_serve_http.py
index 7d542901b..b919dc40c 100644
--- a/tests/test_serve_http.py
+++ b/tests/test_serve_http.py
@@ -7,6 +7,7 @@
 from __future__ import annotations
 
 import json
+import os
 from pathlib import Path
 
 import pytest
@@ -191,13 +192,173 @@ def _init_session(client) -> dict:
     return headers
 
 
-def _call_tool(client, headers, name, arguments, rid) -> str:
+def _call_tool_result(client, headers, name, arguments, rid) -> dict:
     resp = client.post("/mcp", headers=headers, json={
         "jsonrpc": "2.0", "id": rid, "method": "tools/call",
         "params": {"name": name, "arguments": arguments},
     })
     assert resp.status_code == 200
-    return resp.json()["result"]["content"][0]["text"]
+    return resp.json()["result"]
+
+
+def _call_tool(client, headers, name, arguments, rid) -> str:
+    result = _call_tool_result(client, headers, name, arguments, rid)
+    return result["content"][0]["text"]
+
+
+def test_mcp_query_reloads_adjacent_community_labels_and_returns_diagnostics(
+    tmp_path,
+):
+    graph_path = Path(_graph_file(tmp_path))
+    labels_path = tmp_path / ".graphify_labels.json"
+    labels_path.write_text(json.dumps({"0": "First Runtime Label"}), encoding="utf-8")
+    app = serve_mod._build_http_app(str(graph_path), json_response=True)
+
+    with _client(app) as client:
+        headers = _init_session(client)
+        first = _call_tool(
+            client,
+            headers,
+            "query_graph",
+            {"question": 'Alpha community:"First Runtime Label"'},
+            rid=2,
+        )
+        original_stat = labels_path.stat()
+        replacement = tmp_path / "replacement-labels.json"
+        replacement.write_text(json.dumps({"0": "Other Runtime Label"}), encoding="utf-8")
+        assert replacement.stat().st_size == original_stat.st_size
+        os.utime(
+            replacement,
+            ns=(original_stat.st_atime_ns, original_stat.st_mtime_ns),
+        )
+        os.replace(replacement, labels_path)
+        replaced_stat = labels_path.stat()
+        assert replaced_stat.st_size == original_stat.st_size
+        assert replaced_stat.st_mtime_ns == original_stat.st_mtime_ns
+        second = _call_tool(
+            client,
+            headers,
+            "query_graph",
+            {"question": 'Alpha community:"Other Runtime Label"'},
+            rid=3,
+        )
+        unknown = _call_tool(
+            client,
+            headers,
+            "query_graph",
+            {"question": "Alpha community:MissingRuntime"},
+            rid=4,
+        )
+        empty = _call_tool(
+            client,
+            headers,
+            "query_graph",
+            {"question": 'Alpha community:" "'},
+            rid=5,
+        )
+        labels_path.write_text("{not-json", encoding="utf-8")
+        numeric = _call_tool(
+            client,
+            headers,
+            "query_graph",
+            {"question": "Alpha community:0"},
+            rid=6,
+        )
+
+    assert "Filter: community:0 (First Runtime Label)" in first
+    assert "Filter: community:0 (Other Runtime Label)" in second
+    assert unknown.startswith("Error: Unknown or ambiguous community filter")
+    assert "community:0" in unknown
+    assert empty.startswith("Error: Community filter value cannot be empty")
+    assert "Filter: community:0 (Community 0)" in numeric
+
+
+def test_mcp_node_and_path_use_shared_ambiguity_safe_resolver(tmp_path):
+    graph_path = tmp_path / "duplicates.json"
+    graph_path.write_text(json.dumps({
+        "directed": True,
+        "multigraph": False,
+        "nodes": [
+            {"id": "a_run", "label": "run()", "source_file": "src/a.py"},
+            {"id": "b_run", "label": "run()", "source_file": "src/b.py"},
+            {"id": "target", "label": "target()", "source_file": "src/target.py"},
+        ],
+        "links": [
+            {"source": "b_run", "target": "target", "relation": "calls"},
+        ],
+    }), encoding="utf-8")
+    app = serve_mod._build_http_app(str(graph_path), json_response=True)
+
+    with _client(app) as client:
+        headers = _init_session(client)
+        node_result = _call_tool_result(
+            client, headers, "get_node", {"label": "run"}, rid=2
+        )
+        path_result = _call_tool_result(
+            client,
+            headers,
+            "shortest_path",
+            {"source": "run", "target": "target"},
+            rid=3,
+        )
+        qualified = _call_tool(
+            client,
+            headers,
+            "get_node",
+            {"label": "src/b.py::run()"},
+            rid=4,
+        )
+
+    assert node_result.get("isError", False) is False
+    assert path_result.get("isError", False) is False
+    node_error = node_result["content"][0]["text"]
+    path_error = path_result["content"][0]["text"]
+    assert "src/a.py::run() [id=a_run]" in node_error
+    assert "src/b.py::run() [id=b_run]" in node_error
+    assert "src/a.py::run() [id=a_run]" in path_error
+    assert "src/b.py::run() [id=b_run]" in path_error
+    assert "ID: b_run" in qualified
+
+
+def test_mcp_ambiguity_diagnostics_strip_control_characters(tmp_path):
+    graph_path = tmp_path / "hostile-duplicates.json"
+    graph_path.write_text(json.dumps({
+        "directed": True,
+        "multigraph": False,
+        "nodes": [
+            {
+                "id": "a_run\nid",
+                "label": "run()\nFORGED",
+                "source_file": "src/a.py\rINJECT",
+            },
+            {
+                "id": "b_run\x1bid",
+                "label": "run()\x00SECOND",
+                "source_file": "src/b.py\nSPOOF",
+            },
+            {"id": "target", "label": "target()", "source_file": "src/target.py"},
+        ],
+        "links": [],
+    }), encoding="utf-8")
+    app = serve_mod._build_http_app(str(graph_path), json_response=True)
+
+    with _client(app) as client:
+        headers = _init_session(client)
+        node_error = _call_tool(client, headers, "get_node", {"label": "run"}, rid=2)
+        path_error = _call_tool(
+            client,
+            headers,
+            "shortest_path",
+            {"source": "run", "target": "target"},
+            rid=3,
+        )
+
+    for output in (node_error, path_error):
+        assert "\r" not in output
+        assert "\x00" not in output
+        assert "\x1b" not in output
+        assert "src/a.pyINJECT::run()FORGED [id=a_runid]" in output
+        assert "src/b.pySPOOF::run()SECOND [id=b_runid]" in output
 
 
 def test_project_path_is_optional_on_every_tool(tmp_path):
diff --git a/uv.lock b/uv.lock
index 088ebbbdc..40cbf6c97 100644
--- a/uv.lock
+++ b/uv.lock
@@ -97,7 +97,7 @@ name = "autograd"
 version = "1.8.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/67/1c/3c24ec03c8ba4decc742b1df5a10c52f98c84ca8797757f313e7bdcdf276/autograd-1.8.0.tar.gz", hash = "sha256:107374ded5b09fc8643ac925348c0369e7b0e73bbed9565ffd61b8fd04425683", size = 2562146, upload-time = "2025-05-05T12:49:02.502Z" }
 wheels = [
@@ -477,7 +477,7 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/66/54/eb9bfc647b19f2009dd5c7f5ec51c4e6ca831725f1aea7a993034f483147/contourpy-1.3.2.tar.gz", hash = "sha256:b6945942715a034c671b7fc54f9588126b0b8bf23db2696e3ca8328f3ff0ab54", size = 13466130, upload-time = "2025-04-15T17:47:53.79Z" }
 wheels = [
@@ -555,7 +555,7 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/58/01/1253e6698a07380cd31a736d248a3f2a50a7c88779a1813da27503cadc2a/contourpy-1.3.3.tar.gz", hash = "sha256:083e12155b210502d0bca491432bb04d56dc3432f95a979b429f2848c3dbe880", size = 13466174, upload-time = "2025-07-26T12:03:12.549Z" }
@@ -813,10 +813,10 @@ name = "ctranslate2"
 version = "4.7.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" },
-    { name = "pyyaml", marker = "python_full_version >= '3.11'" },
-    { name = "setuptools", marker = "python_full_version >= '3.11'" },
+    { name = "pyyaml" },
+    { name = "setuptools" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/e0/b69c40c3d739b213a78d327071240590792071b4f890e34088b03b95bb1e/ctranslate2-4.7.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:9017a355dd7c6d29dc3bca6e9fc74827306c61b702c66bb1f6b939655e7de3fa", size = 1255773, upload-time = "2026-02-04T06:11:04.769Z" },
@@ -926,7 +926,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -951,12 +951,12 @@ name = "faster-whisper"
 version = "1.2.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "av", marker = "python_full_version >= '3.11'" },
-    { name = "ctranslate2", marker = "python_full_version >= '3.11'" },
-    { name = "huggingface-hub", marker = "python_full_version >= '3.11'" },
-    { name = "onnxruntime", marker = "python_full_version >= '3.11'" },
-    { name = "tokenizers", marker = "python_full_version >= '3.11'" },
-    { name = "tqdm", marker = "python_full_version >= '3.11'" },
+    { name = "av" },
+    { name = "ctranslate2" },
+    { name = "huggingface-hub" },
+    { name = "onnxruntime" },
+    { name = "tokenizers" },
+    { name = "tqdm" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/05/99/49ee85903dee060d9f08297b4a342e5e0bcfca2f027a07b4ee0a38ab13f9/faster_whisper-1.2.1-py3-none-any.whl", hash = "sha256:79a66ad50688c0b794dd501dc340a736992a6342f7f95e5811be60b5224a26a7", size = 1118909, upload-time = "2025-10-31T11:35:47.794Z" },
@@ -1059,10 +1059,10 @@ name = "gensim"
 version = "4.4.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "smart-open", marker = "python_full_version < '3.13'" },
+    { name = "smart-open" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/1a/80/fe9d2e1ace968041814dbcfce4e8499a643a36c41267fa4b6c4f54cce420/gensim-4.4.0.tar.gz", hash = "sha256:a3f5b626da5518e79a479140361c663089fe7998df8ba52d56e1ded71ac5bdf5", size = 23260095, upload-time = "2025-10-18T02:06:45.962Z" }
 wheels = [
@@ -1090,7 +1090,7 @@ wheels = [
 
 [[package]]
 name = "graphifyy"
-version = "0.9.6"
+version = "0.9.14"
 source = { editable = "." }
 dependencies = [
     { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
@@ -1357,26 +1357,26 @@ name = "graspologic"
 version = "3.4.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "anytree", marker = "python_full_version < '3.13'" },
-    { name = "beartype", marker = "python_full_version < '3.13'" },
-    { name = "future", marker = "python_full_version < '3.13'" },
-    { name = "gensim", marker = "python_full_version < '3.13'" },
-    { name = "graspologic-native", marker = "python_full_version < '3.13'" },
-    { name = "hyppo", marker = "python_full_version < '3.13'" },
-    { name = "joblib", marker = "python_full_version < '3.13'" },
-    { name = "matplotlib", marker = "python_full_version < '3.13'" },
-    { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "anytree" },
+    { name = "beartype" },
+    { name = "future" },
+    { name = "gensim" },
+    { name = "graspologic-native" },
+    { name = "hyppo" },
+    { name = "joblib" },
+    { name = "matplotlib" },
+    { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "networkx", version = "3.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
-    { name = "pot", marker = "python_full_version < '3.13'" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "pot" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "seaborn", marker = "python_full_version < '3.13'" },
-    { name = "statsmodels", marker = "python_full_version < '3.13'" },
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
-    { name = "umap-learn", marker = "python_full_version < '3.13'" },
+    { name = "seaborn" },
+    { name = "statsmodels" },
+    { name = "typing-extensions" },
+    { name = "umap-learn" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/91/bb/0fe2ef85ea775e7b8416b2cf90097aa4b5e0c9c2271d7fe6789bab27d0ca/graspologic-3.4.4.tar.gz", hash = "sha256:79878caf367da3e89046a4ec94291c5b1a5da569f19fdd879d8b45c3563d7110", size = 5134258, upload-time = "2025-09-08T21:44:01.969Z" }
 wheels = [
@@ -1478,15 +1478,15 @@ name = "huggingface-hub"
 version = "1.15.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "filelock", marker = "python_full_version >= '3.11'" },
-    { name = "fsspec", marker = "python_full_version >= '3.11'" },
-    { name = "hf-xet", marker = "(python_full_version >= '3.11' and platform_machine == 'AMD64') or (python_full_version >= '3.11' and platform_machine == 'aarch64') or (python_full_version >= '3.11' and platform_machine == 'amd64') or (python_full_version >= '3.11' and platform_machine == 'arm64') or (python_full_version >= '3.11' and platform_machine == 'x86_64')" },
-    { name = "httpx", marker = "python_full_version >= '3.11'" },
-    { name = "packaging", marker = "python_full_version >= '3.11'" },
-    { name = "pyyaml", marker = "python_full_version >= '3.11'" },
-    { name = "tqdm", marker = "python_full_version >= '3.11'" },
-    { name = "typer", marker = "python_full_version >= '3.11'" },
-    { name = "typing-extensions", marker = "python_full_version >= '3.11'" },
+    { name = "filelock" },
+    { name = "fsspec" },
+    { name = "hf-xet", marker = "platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'" },
+    { name = "httpx" },
+    { name = "packaging" },
+    { name = "pyyaml" },
+    { name = "tqdm" },
+    { name = "typer" },
+    { name = "typing-extensions" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/bb/b6/e22bd20a25299c34b8c5922c1545a6320825b13906eb0f7298edfd034a0b/huggingface_hub-1.15.0.tar.gz", hash = "sha256:28abfdddda3927fd4de6a63cf26ab012498a2c24dae52baf150c5c6edf98a1d5", size = 784100, upload-time = "2026-05-15T11:42:52.149Z" }
 wheels = [
@@ -1511,18 +1511,18 @@ name = "hyppo"
 version = "0.5.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "autograd", marker = "python_full_version < '3.13'" },
-    { name = "future", marker = "python_full_version < '3.13'" },
-    { name = "numba", marker = "python_full_version < '3.13'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
-    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "autograd" },
+    { name = "future" },
+    { name = "numba" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "patsy", marker = "python_full_version < '3.13'" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "patsy" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "statsmodels", marker = "python_full_version < '3.13'" },
+    { name = "statsmodels" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/dd/a6/0d84fe8486a1447da8bdb8ebb249d525fd8c1d0fe038bceb003c6e0513f9/hyppo-0.5.2.tar.gz", hash = "sha256:4634d15516248a43d25c241ed18beeb79bb3210360f7253693b3f154fe8c9879", size = 125115, upload-time = "2025-05-24T18:33:27.418Z" }
 wheels = [
@@ -1552,7 +1552,7 @@ name = "importlib-metadata"
 version = "9.0.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "zipp", marker = "python_full_version < '3.11'" },
+    { name = "zipp" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/a9/01/15bb152d77b21318514a96f43af312635eb2500c96b55398d020c93d86ea/importlib_metadata-9.0.0.tar.gz", hash = "sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc", size = 56405, upload-time = "2026-03-20T06:42:56.999Z" }
 wheels = [
@@ -2279,8 +2279,8 @@ name = "numba"
 version = "0.65.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "llvmlite", marker = "python_full_version < '3.13'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "llvmlite" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/f6/c5/db2ac3685833d626c0dcae6bd2330cd68433e1fd248d15f70998160d3ad7/numba-0.65.1.tar.gz", hash = "sha256:19357146c32fe9ed25059ab915e8465fb13951cf6b0aace3826b76886373ab23", size = 2765600, upload-time = "2026-04-24T02:02:56.551Z" }
 wheels = [
@@ -2440,11 +2440,11 @@ name = "onnxruntime"
 version = "1.26.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "flatbuffers", marker = "python_full_version >= '3.11'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "flatbuffers" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" },
-    { name = "packaging", marker = "python_full_version >= '3.11'" },
-    { name = "protobuf", marker = "python_full_version >= '3.11'" },
+    { name = "packaging" },
+    { name = "protobuf" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/d4/81/29a9eb470994a75eb7b3ccf32be314d7c66675a00ac7b50294816cc2db27/onnxruntime-1.26.0-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:ee1109ef4ef27cad90e823399e61e03b3c6c7bfe0fb820b4baf3678c15be8b3c", size = 18005108, upload-time = "2026-05-08T19:08:11.728Z" },
@@ -2530,10 +2530,10 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "python-dateutil", marker = "python_full_version < '3.11'" },
-    { name = "pytz", marker = "python_full_version < '3.11'" },
-    { name = "tzdata", marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "python-dateutil" },
+    { name = "pytz" },
+    { name = "tzdata" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/33/01/d40b85317f86cf08d853a4f495195c73815fdf205eef3993821720274518/pandas-2.3.3.tar.gz", hash = "sha256:e05e1af93b977f7eafa636d043f9f94c7ee3ac81af99c13508215942e64c993b", size = 4495223, upload-time = "2025-09-29T23:34:51.853Z" }
 wheels = [
@@ -2596,9 +2596,9 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "python-dateutil", marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "tzdata", marker = "(python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform == 'emscripten') or (python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform == 'win32')" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "python-dateutil" },
+    { name = "tzdata", marker = "sys_platform == 'emscripten' or sys_platform == 'win32'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/f8/87/4341c6252d1c47b08768c3d25ac487362bf403f0313ddae4a2a26c9b1b4c/pandas-3.0.3.tar.gz", hash = "sha256:696a4a00a2a2a35d4e5deb3fc946641b96c944f02230e4f76137fe35d806c4fc", size = 4651414, upload-time = "2026-05-11T18:54:29.21Z" }
 wheels = [
@@ -2672,7 +2672,7 @@ name = "patsy"
 version = "1.0.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/be/44/ed13eccdd0519eff265f44b670d46fbb0ec813e2274932dc1c0e48520f7d/patsy-1.0.2.tar.gz", hash = "sha256:cdc995455f6233e90e22de72c37fcadb344e7586fb83f06696f54d92f8ce74c0", size = 399942, upload-time = "2025-10-20T16:17:37.535Z" }
 wheels = [
@@ -2855,8 +2855,8 @@ name = "pot"
 version = "0.9.6.post1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/42/8b/5f939eaf1fbeb7ff914fe540d659486951a056e5537b8f454362045b6c72/pot-0.9.6.post1.tar.gz", hash = "sha256:9b6cc14a8daecfe1268268168cf46548f9130976b22b24a9e8ec62a734be6c43", size = 604243, upload-time = "2025-09-22T12:51:14.894Z" }
@@ -3199,12 +3199,12 @@ name = "pynndescent"
 version = "0.6.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "joblib", marker = "python_full_version < '3.13'" },
-    { name = "llvmlite", marker = "python_full_version < '3.13'" },
-    { name = "numba", marker = "python_full_version < '3.13'" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "joblib" },
+    { name = "llvmlite" },
+    { name = "numba" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/4a/fb/7f58c397fb31666756457ee2ac4c0289ef2daad57f4ae4be8dec12f80b03/pynndescent-0.6.0.tar.gz", hash = "sha256:7ffde0fb5b400741e055a9f7d377e3702e02250616834231f6c209e39aac24f5", size = 2992987, upload-time = "2026-01-08T21:29:58.943Z" }
@@ -3870,10 +3870,10 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "joblib", marker = "python_full_version < '3.11'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
-    { name = "threadpoolctl", marker = "python_full_version < '3.11'" },
+    { name = "joblib" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" } },
+    { name = "threadpoolctl" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/98/c2/a7855e41c9d285dfe86dc50b250978105dce513d6e459ea66a6aeb0e1e0c/scikit_learn-1.7.2.tar.gz", hash = "sha256:20e9e49ecd130598f1ca38a1d85090e1a600147b9c02fa6f15d69cb53d968fda", size = 7193136, upload-time = "2025-09-09T08:21:29.075Z" }
 wheels = [
@@ -3919,10 +3919,10 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "joblib", marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "threadpoolctl", marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "joblib" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" } },
+    { name = "threadpoolctl" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0e/d4/40988bf3b8e34feec1d0e6a051446b1f66225f8529b9309becaeef62b6c4/scikit_learn-1.8.0.tar.gz", hash = "sha256:9bccbb3b40e3de10351f8f5068e105d0f4083b1a65fa07b6634fbc401a6287fd", size = 7335585, upload-time = "2025-12-10T07:08:53.618Z" }
 wheels = [
@@ -3972,7 +3972,7 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0f/37/6964b830433e654ec7485e45a00fc9a27cf868d622838f6b6d9c5ec0d532/scipy-1.15.3.tar.gz", hash = "sha256:eae3cf522bc7df64b42cad3925c876e1b0b6c35c1337c93e12c0f366f55b0eaf", size = 59419214, upload-time = "2025-05-08T16:13:05.955Z" }
 wheels = [
@@ -4033,7 +4033,7 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/7a/97/5a3609c4f8d58b039179648e62dd220f89864f56f7357f5d4f45c29eb2cc/scipy-1.17.1.tar.gz", hash = "sha256:95d8e012d8cb8816c226aef832200b1d45109ed4464303e997c5b13122b297c0", size = 30573822, upload-time = "2026-02-23T00:26:24.851Z" }
 wheels = [
@@ -4104,9 +4104,9 @@ name = "seaborn"
 version = "0.13.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "matplotlib", marker = "python_full_version < '3.13'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
-    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "matplotlib" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/86/59/a451d7420a77ab0b98f7affa3a1d78a313d2f7281a57afb1a34bae8ab412/seaborn-0.13.2.tar.gz", hash = "sha256:93e60a40988f4d65e9f4885df477e2fdaff6b73a9ded434c1ab356dd57eefff7", size = 1457696, upload-time = "2024-01-25T13:21:52.551Z" }
@@ -4146,7 +4146,7 @@ name = "smart-open"
 version = "7.6.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "wrapt", marker = "python_full_version < '3.13'" },
+    { name = "wrapt" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/c5/65/3ada667d32675399001bf022ad3d9f3989b57101351ebc71d6fbe2384634/smart_open-7.6.1.tar.gz", hash = "sha256:4347996e7ba21db7cd1e059632e0b30395407e4f6c660d2ddffc8f2a9ae5f990", size = 54754, upload-time = "2026-05-09T06:23:37.06Z" }
 wheels = [
@@ -4211,12 +4211,12 @@ name = "statsmodels"
 version = "0.14.6"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
-    { name = "packaging", marker = "python_full_version < '3.13'" },
-    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "packaging" },
+    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "patsy", marker = "python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "patsy" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0d/81/e8d74b34f85285f7335d30c5e3c2d7c0346997af9f3debf9a0a9a63de184/statsmodels-0.14.6.tar.gz", hash = "sha256:4d17873d3e607d398b85126cd4ed7aad89e4e9d89fc744cdab1af3189a996c2a", size = 20689085, upload-time = "2025-12-05T23:08:39.522Z" }
@@ -4337,7 +4337,7 @@ name = "tokenizers"
 version = "0.23.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "huggingface-hub", marker = "python_full_version >= '3.11'" },
+    { name = "huggingface-hub" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/c1/60/21f715d9faba5f5407ff759472ade058ec4a507ad62bcea47cb847239a73/tokenizers-0.23.1.tar.gz", hash = "sha256:1feeeadf865a7915adc25445dea30e9933e593c31bb96c277cee36de227c8bfa", size = 365748, upload-time = "2026-04-27T14:43:25.606Z" }
 wheels = [
@@ -4928,10 +4928,10 @@ name = "typer"
 version = "0.25.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "annotated-doc", marker = "python_full_version >= '3.11'" },
-    { name = "click", marker = "python_full_version >= '3.11'" },
-    { name = "rich", marker = "python_full_version >= '3.11'" },
-    { name = "shellingham", marker = "python_full_version >= '3.11'" },
+    { name = "annotated-doc" },
+    { name = "click" },
+    { name = "rich" },
+    { name = "shellingham" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/e4/51/9aed62104cea109b820bbd6c14245af756112017d309da813ef107d42e7e/typer-0.25.1.tar.gz", hash = "sha256:9616eb8853a09ffeabab1698952f33c6f29ffdbceb4eaeecf571880e8d7664cc", size = 122276, upload-time = "2026-04-30T19:32:16.964Z" }
 wheels = [
@@ -4973,14 +4973,14 @@ name = "umap-learn"
 version = "0.5.12"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numba", marker = "python_full_version < '3.13'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
-    { name = "pynndescent", marker = "python_full_version < '3.13'" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "numba" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "pynndescent" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "tqdm", marker = "python_full_version < '3.13'" },
+    { name = "tqdm" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/02/ee/af4171241117f85c74b5ca6448ea1033cc28d599c13651d67289bacd4083/umap_learn-0.5.12.tar.gz", hash = "sha256:6aff02ecac5f2aad9f3c65ee518d7ae93e1a985ae38721fdcffceee4232c33c7", size = 96672, upload-time = "2026-04-08T20:03:54.012Z" }
 wheels = [
@@ -5001,8 +5001,8 @@ name = "uvicorn"
 version = "0.47.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "click", marker = "python_full_version < '3.11' or sys_platform != 'emscripten'" },
-    { name = "h11", marker = "python_full_version < '3.11' or sys_platform != 'emscripten'" },
+    { name = "click" },
+    { name = "h11" },
     { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/f6/b1/8e7077a8641086aea449e1b5752a570f1b5906c64e0a33cd6d93b63a066b/uvicorn-0.47.0.tar.gz", hash = "sha256:7c9a0ea1a9414106bbab7324609c162d8fa0cdcdcb703060987269d77c7bb533", size = 90582, upload-time = "2026-05-14T18:16:54.455Z" }

From 0065aa04ddd8ce42c4c8818f28534d851ca19250 Mon Sep 17 00:00:00 2001
From: Jeisson <jeissonvargas.acidlabs@latam.com>
Date: Mon, 13 Jul 2026 11:09:55 -0500
Subject: [PATCH 2/3] docs(skills): teach scoped graph retrieval

---
 graphify/skill-agents.md                      |  35 +-
 graphify/skill-aider.md                       | 298 ++++------------
 graphify/skill-amp.md                         |  35 +-
 graphify/skill-claw.md                        |  35 +-
 graphify/skill-codex.md                       |  35 +-
 graphify/skill-copilot.md                     |  35 +-
 graphify/skill-devin.md                       | 294 ++++------------
 graphify/skill-droid.md                       |  35 +-
 graphify/skill-kilo.md                        |  35 +-
 graphify/skill-kiro.md                        |  35 +-
 graphify/skill-opencode.md                    |  35 +-
 graphify/skill-pi.md                          |  35 +-
 graphify/skill-trae.md                        |  35 +-
 graphify/skill-vscode.md                      |  35 +-
 graphify/skill-windows.md                     |  35 +-
 graphify/skill.md                             |  35 +-
 graphify/skills/agents/references/query.md    | 327 ++++--------------
 graphify/skills/amp/references/query.md       | 327 ++++--------------
 graphify/skills/claude/references/query.md    | 327 ++++--------------
 graphify/skills/claw/references/query.md      | 327 ++++--------------
 graphify/skills/codex/references/query.md     | 327 ++++--------------
 graphify/skills/copilot/references/query.md   | 327 ++++--------------
 graphify/skills/droid/references/query.md     | 327 ++++--------------
 graphify/skills/kilo/references/query.md      | 327 ++++--------------
 graphify/skills/kiro/references/query.md      | 327 ++++--------------
 graphify/skills/opencode/references/query.md  | 327 ++++--------------
 graphify/skills/pi/references/query.md        | 327 ++++--------------
 graphify/skills/trae/references/query.md      | 327 ++++--------------
 graphify/skills/vscode/references/query.md    | 327 ++++--------------
 graphify/skills/windows/references/query.md   | 327 ++++--------------
 tests/test_skillgen.py                        | 252 +++++++++++++-
 .../expected/graphify__skill-agents.md        |  35 +-
 .../expected/graphify__skill-aider.md         | 298 ++++------------
 .../skillgen/expected/graphify__skill-amp.md  |  35 +-
 .../skillgen/expected/graphify__skill-claw.md |  35 +-
 .../expected/graphify__skill-codex.md         |  35 +-
 .../expected/graphify__skill-copilot.md       |  35 +-
 .../expected/graphify__skill-devin.md         | 294 ++++------------
 .../expected/graphify__skill-droid.md         |  35 +-
 .../skillgen/expected/graphify__skill-kilo.md |  35 +-
 .../skillgen/expected/graphify__skill-kiro.md |  35 +-
 .../expected/graphify__skill-opencode.md      |  35 +-
 tools/skillgen/expected/graphify__skill-pi.md |  35 +-
 .../skillgen/expected/graphify__skill-trae.md |  35 +-
 .../expected/graphify__skill-vscode.md        |  35 +-
 .../expected/graphify__skill-windows.md       |  35 +-
 tools/skillgen/expected/graphify__skill.md    |  35 +-
 ...hify__skills__agents__references__query.md | 327 ++++--------------
 ...raphify__skills__amp__references__query.md | 327 ++++--------------
 ...hify__skills__claude__references__query.md | 327 ++++--------------
 ...aphify__skills__claw__references__query.md | 327 ++++--------------
 ...phify__skills__codex__references__query.md | 327 ++++--------------
 ...ify__skills__copilot__references__query.md | 327 ++++--------------
 ...phify__skills__droid__references__query.md | 327 ++++--------------
 ...aphify__skills__kilo__references__query.md | 327 ++++--------------
 ...aphify__skills__kiro__references__query.md | 327 ++++--------------
 ...fy__skills__opencode__references__query.md | 327 ++++--------------
 ...graphify__skills__pi__references__query.md | 327 ++++--------------
 ...aphify__skills__trae__references__query.md | 327 ++++--------------
 ...hify__skills__vscode__references__query.md | 327 ++++--------------
 ...ify__skills__windows__references__query.md | 327 ++++--------------
 tools/skillgen/fragments/core/aider.md        | 270 +--------------
 tools/skillgen/fragments/core/core.md         |   8 +-
 tools/skillgen/fragments/core/devin.md        | 266 +-------------
 .../fragments/query-contract/default.md       |  15 +
 .../skillgen/fragments/query-stub/default.md  |   6 +-
 .../skillgen/fragments/query-usage/default.md |   8 +
 .../fragments/references/query/default.md     | 317 +++--------------
 tools/skillgen/gen.py                         | 210 ++++++++++-
 tools/skillgen/platforms.toml                 |   4 +-
 70 files changed, 3236 insertions(+), 9440 deletions(-)
 create mode 100644 tools/skillgen/fragments/query-contract/default.md
 create mode 100644 tools/skillgen/fragments/query-usage/default.md

diff --git a/graphify/skill-agents.md b/graphify/skill-agents.md
index 4969929c0..b17b35385 100644
--- a/graphify/skill-agents.md
+++ b/graphify/skill-agents.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-aider.md b/graphify/skill-aider.md
index 8db8f73f2..be49b0c38 100644
--- a/graphify/skill-aider.md
+++ b/graphify/skill-aider.md
@@ -26,11 +26,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -906,269 +909,108 @@ Then run Steps 5–9 as normal (label communities, generate viz, benchmark, clea
 
 ## For /graphify query
 
-Two traversal modes - choose based on the question:
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+**Search contract**
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-Load `graphify-out/graph.json`, then:
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-1. Find the 1-3 nodes whose label best matches key terms in the question.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
+### Query
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+Choose traversal mode from the question:
 
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) > 3]
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
-
-Replace `QUESTION` with the user's actual question, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above.
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-After writing the answer, save it back into the graph so it improves future queries:
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
 
-Replace `QUESTION` with the question, `ANSWER` with your full answer text, `SOURCE_NODES` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
----
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-## For /graphify path
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-Find the shortest path between two named concepts in the graph.
+### Inline NetworkX fallback
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
+```python
+from graphify.serve import _source_display
 
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+display = _source_display(node_data)
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-After writing the explanation, save it back:
+### Save useful results
+
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
 ```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
-## For /graphify explain
+## For /graphify path
 
-Give a plain-language explanation of a single node - everything connected to it.
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
-First check the graph exists:
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
-If it fails, stop and tell the user to run `/graphify <path>` first.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
+Transport behavior differs only in how ambiguity is returned:
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
-After writing the explanation, save it back:
+## For /graphify explain
+
+Prefer the CLI/MCP resolver:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
----
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
+
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
 
 ## For /graphify add
 
diff --git a/graphify/skill-amp.md b/graphify/skill-amp.md
index 4969929c0..b17b35385 100644
--- a/graphify/skill-amp.md
+++ b/graphify/skill-amp.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-claw.md b/graphify/skill-claw.md
index bafbca074..1192ab1f2 100644
--- a/graphify/skill-claw.md
+++ b/graphify/skill-claw.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-codex.md b/graphify/skill-codex.md
index d71f4592d..f19256e8a 100644
--- a/graphify/skill-codex.md
+++ b/graphify/skill-codex.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-copilot.md b/graphify/skill-copilot.md
index bafbca074..1192ab1f2 100644
--- a/graphify/skill-copilot.md
+++ b/graphify/skill-copilot.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-devin.md b/graphify/skill-devin.md
index c444a852d..81f0485f1 100644
--- a/graphify/skill-devin.md
+++ b/graphify/skill-devin.md
@@ -37,11 +37,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -1042,265 +1045,108 @@ Then run Steps 5-9 as normal (label communities, generate viz, benchmark, clean
 
 ## For /graphify query
 
-Two traversal modes - choose based on the question:
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+**Search contract**
 
-Load `graphify-out/graph.json`, then:
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-1. Find the 1-3 nodes whose label best matches key terms in the question.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+### Query
 
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) > 3]
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Choose traversal mode from the question:
 
-Replace `QUESTION` with the user's actual question, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above.
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-After writing the answer, save it back into the graph so it improves future queries:
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
 
----
-
-## For /graphify path
-
-Find the shortest path between two named concepts in the graph.
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-a_term = 'NODE_A'
-b_term = 'NODE_B'
+### Inline NetworkX fallback
 
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-src = find_node(a_term)
-tgt = find_node(b_term)
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
+```python
+from graphify.serve import _source_display
 
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+display = _source_display(node_data)
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names. Then explain the path in plain language - what each hop means, why it's significant.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-After writing the explanation, save it back:
+### Save useful results
+
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
 ```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
-## For /graphify explain
+## For /graphify path
 
-Give a plain-language explanation of a single node - everything connected to it.
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
-First check the graph exists:
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
+Transport behavior differs only in how ambiguity is returned:
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
-Replace `NODE_NAME` with the concept. Then write a 3-5 sentence explanation using source locations as citations.
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
-After writing the explanation, save it back:
+## For /graphify explain
+
+Prefer the CLI/MCP resolver:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
----
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
+
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
 
 ## For /graphify add
 
diff --git a/graphify/skill-droid.md b/graphify/skill-droid.md
index ae1d49325..fa3d1f85e 100644
--- a/graphify/skill-droid.md
+++ b/graphify/skill-droid.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-kilo.md b/graphify/skill-kilo.md
index 6aa87a8bd..a4e11df6d 100644
--- a/graphify/skill-kilo.md
+++ b/graphify/skill-kilo.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-kiro.md b/graphify/skill-kiro.md
index bafbca074..1192ab1f2 100644
--- a/graphify/skill-kiro.md
+++ b/graphify/skill-kiro.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-opencode.md b/graphify/skill-opencode.md
index 8c3ce3eed..4373e39b3 100644
--- a/graphify/skill-opencode.md
+++ b/graphify/skill-opencode.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -642,10 +645,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-pi.md b/graphify/skill-pi.md
index bafbca074..1192ab1f2 100644
--- a/graphify/skill-pi.md
+++ b/graphify/skill-pi.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-trae.md b/graphify/skill-trae.md
index af59166ae..756f7b9c6 100644
--- a/graphify/skill-trae.md
+++ b/graphify/skill-trae.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -648,10 +651,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-vscode.md b/graphify/skill-vscode.md
index 11a2837b5..40cd1c98a 100644
--- a/graphify/skill-vscode.md
+++ b/graphify/skill-vscode.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -646,10 +649,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill-windows.md b/graphify/skill-windows.md
index 0dc73947a..66e361201 100644
--- a/graphify/skill-windows.md
+++ b/graphify/skill-windows.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -672,10 +675,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skill.md b/graphify/skill.md
index bafbca074..1192ab1f2 100644
--- a/graphify/skill.md
+++ b/graphify/skill.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/graphify/skills/agents/references/query.md b/graphify/skills/agents/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/agents/references/query.md
+++ b/graphify/skills/agents/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/amp/references/query.md b/graphify/skills/amp/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/amp/references/query.md
+++ b/graphify/skills/amp/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/claude/references/query.md b/graphify/skills/claude/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/claude/references/query.md
+++ b/graphify/skills/claude/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/claw/references/query.md b/graphify/skills/claw/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/claw/references/query.md
+++ b/graphify/skills/claw/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/codex/references/query.md b/graphify/skills/codex/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/codex/references/query.md
+++ b/graphify/skills/codex/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/copilot/references/query.md b/graphify/skills/copilot/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/copilot/references/query.md
+++ b/graphify/skills/copilot/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/droid/references/query.md b/graphify/skills/droid/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/droid/references/query.md
+++ b/graphify/skills/droid/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/kilo/references/query.md b/graphify/skills/kilo/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/kilo/references/query.md
+++ b/graphify/skills/kilo/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/kiro/references/query.md b/graphify/skills/kiro/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/kiro/references/query.md
+++ b/graphify/skills/kiro/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/opencode/references/query.md b/graphify/skills/opencode/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/opencode/references/query.md
+++ b/graphify/skills/opencode/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/pi/references/query.md b/graphify/skills/pi/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/pi/references/query.md
+++ b/graphify/skills/pi/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/trae/references/query.md b/graphify/skills/trae/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/trae/references/query.md
+++ b/graphify/skills/trae/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/vscode/references/query.md b/graphify/skills/vscode/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/vscode/references/query.md
+++ b/graphify/skills/vscode/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/graphify/skills/windows/references/query.md b/graphify/skills/windows/references/query.md
index 56565eb78..26570dc81 100644
--- a/graphify/skills/windows/references/query.md
+++ b/graphify/skills/windows/references/query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tests/test_skillgen.py b/tests/test_skillgen.py
index 9797267a9..267d9d189 100644
--- a/tests/test_skillgen.py
+++ b/tests/test_skillgen.py
@@ -336,21 +336,167 @@ def test_codex_uses_compact_extraction_windows_uses_verbose():
     assert "(compact)" not in windows_refs["extraction-spec.md"]
 
 
-def test_every_platform_query_has_expansion_and_fallback():
-    """#1325: the unified query reference ships BOTH the vocab-expansion step and
-    the inline NetworkX fallback to every platform (previously split so no host
-    got both — Claude had expansion but no fallback; the rest the reverse)."""
-    for key in ("claude", "codex", "windows", "opencode"):
+def _canonical_query_contract():
+    return gen._read_fragment(gen._QUERY_CONTRACT).rstrip("\n")
+
+
+def test_all_fourteen_split_variants_render_the_exact_contract_block():
+    """Split cores and references derive one byte-identical canonical contract."""
+    platforms = gen.load_platforms()
+    split = {key: platform for key, platform in platforms.items() if platform.bucket == "split"}
+    assert len(split) == 14
+    contract = _canonical_query_contract()
+    for key in split:
         core, refs = _platform_artifacts(key)
-        # Core stub mentions both the vocab-expansion step and the inline fallback.
-        assert "expand the question against the graph's own vocabulary" in core
-        assert "NetworkX traversal" in core
-        # The query reference carries expansion, fallback, and path/explain.
-        q = refs["query.md"]
-        assert "Constrained query expansion" in q
-        assert "If the CLI is unavailable" in q
-        assert "## For /graphify path" in q
-        assert "## For /graphify explain" in q
+        assert core.count(contract) == 1, f"[{key}] core contract drift"
+        assert refs["query.md"].count(contract) == 1, f"[{key}] reference contract drift"
+
+
+def test_both_monolith_variants_render_the_exact_contract_block():
+    """Aider and Devin inline the same byte-identical canonical contract."""
+    platforms = gen.load_platforms()
+    monoliths = {key: platform for key, platform in platforms.items() if platform.bucket == "monolith"}
+    assert set(monoliths) == {"aider", "devin"}
+    contract = _canonical_query_contract()
+    for key, platform in monoliths.items():
+        body = gen.render(platform)[0].content
+        assert body.count(contract) == 1, f"[{key}] monolith contract drift"
+        assert "@@QUERY_REFERENCE@@" not in body
+
+
+def test_generated_guidance_requires_safe_question_arguments():
+    """Question text is data and is never prescribed as raw shell interpolation."""
+    contract = _canonical_query_contract()
+    reference = gen._render_query_reference(monolith=False)
+
+    assert "User-controlled question text is data, never shell syntax" in contract
+    assert "process API with an argument list" in contract
+    assert "Never interpolate raw user text" in contract
+    assert "Pass the user's question and directives to the CLI unchanged" not in reference
+    assert "question = 'QUESTION'" not in reference
+    assert "replace `QUESTION`" not in reference
+    platforms = gen.load_platforms()
+    for key, platform in platforms.items():
+        body = gen.render(platform)[0].content
+        assert 'graphify query "<question>"' not in body, key
+
+
+@pytest.mark.parametrize(
+    ("fragment", "slot"),
+    (
+        ("core/core.md", "@@QUERY_USAGE@@"),
+        ("core/core.md", "@@QUERY_STUB@@"),
+        ("query-stub/default.md", "@@QUERY_CONTRACT@@"),
+        ("references/query/default.md", "@@QUERY_CONTRACT@@"),
+    ),
+)
+@pytest.mark.parametrize("mutation", ("missing", "duplicate"))
+def test_split_render_rejects_missing_or_duplicate_query_slots(
+    monkeypatch, fragment, slot, mutation
+):
+    """Mandatory split query slots fail clearly before replacement."""
+    platforms = gen.load_platforms()
+    original_read = gen._read_fragment
+
+    def read_with_mutated_slot(rel):
+        content = original_read(rel)
+        if rel != fragment:
+            return content
+        if mutation == "missing":
+            return content.replace(slot, "", 1)
+        return content + f"\n{slot}\n"
+
+    monkeypatch.setattr(gen, "_read_fragment", read_with_mutated_slot)
+    with pytest.raises(ValueError, match=f"exactly one {slot} slot"):
+        gen.render(platforms["claude"])
+
+
+def test_reserved_directive_guidance_matches_real_parser():
+    """Literal directive tokens activate the parser, so docs must not forward them."""
+    from graphify.serve import _parse_query_directives
+
+    literal = _parse_query_directives("What does include:memory do?")
+    assert literal.include_memory is True
+    assert literal.text == "What does do?"
+
+    intentional = _parse_query_directives(
+        'target flow include:memory community:"Main Runtime" god:router'
+    )
+    assert intentional.text == "target flow"
+    assert intentional.include_memory is True
+    assert intentional.community == "Main Runtime"
+    assert intentional.god == "router"
+
+    contract = _canonical_query_contract()
+    assert "Reserved directives" in contract
+    assert "If the user asks about the literal syntax" in contract
+    assert "paraphrase the search without the reserved token" in contract
+
+
+def test_fallback_source_guidance_delegates_to_real_source_formatter():
+    """Fallback provenance stays aligned with CLI origin_file semantics."""
+    from graphify.serve import _source_display
+
+    external = {
+        "label": "ExternalType",
+        "source_file": "",
+        "source_location": "",
+        "origin_file": "src/consumer.py",
+        "source_url": "https://example.invalid/type",
+    }
+    assert _source_display(external) == (
+        "external/reference (unowned; referenced from src/consumer.py)"
+    )
+
+    reference = gen._render_query_reference(monolith=False)
+    assert "from graphify.serve import _source_display" in reference
+    assert "recognizes `origin_file` as external/reference provenance" in reference
+    assert "node.get('source_url')" not in reference
+
+
+def test_search_contract_matches_cli_ambiguity_exit_two(
+    tmp_path, monkeypatch, capsys
+):
+    """The documented CLI ambiguity status is linked to the real resolver path."""
+    import json
+    import graphify.__main__ as mainmod
+
+    graph_path = tmp_path / "graph.json"
+    graph_path.write_text(json.dumps({
+        "directed": True,
+        "multigraph": False,
+        "nodes": [
+            {"id": "a_run", "label": "run()", "source_file": "src/a.py"},
+            {"id": "b_run", "label": "run()", "source_file": "src/b.py"},
+        ],
+        "links": [],
+    }), encoding="utf-8")
+    monkeypatch.setattr(mainmod, "_check_skill_version", lambda _: None)
+    monkeypatch.setattr(
+        mainmod.sys,
+        "argv",
+        ["graphify", "explain", "run", "--graph", str(graph_path)],
+    )
+
+    with pytest.raises(SystemExit) as exc_info:
+        mainmod.main()
+
+    assert exc_info.value.code == 2
+    error = capsys.readouterr().err
+    assert "src/a.py::run() [id=a_run]" in error
+    assert "src/b.py::run() [id=b_run]" in error
+    contract = _canonical_query_contract()
+    assert "The CLI exits 2 and prints ranked candidates" in contract
+    assert "MCP/HTTP return the ambiguity diagnostic as successful text" in contract
+
+
+def test_all_sixteen_rendered_variants_are_drift_free():
+    """Committed files and expected snapshots match every platform render."""
+    platforms = gen.load_platforms()
+    assert len(platforms) == 16
+    for key in platforms:
+        problems = gen.check(gen.render_all(platforms, only=key))
+        assert problems == [], f"[{key}]\n" + "\n".join(problems)
 
 
 def test_schema_singleton_passes_across_all_platforms():
@@ -440,7 +586,7 @@ def test_compact_extraction_hosts_use_the_compact_spec():
 
 
 def test_every_split_host_renders_eight_references():
-    """All twelve split hosts render exactly the eight on-demand references."""
+    """All fourteen split hosts render exactly the eight on-demand references."""
     platforms = gen.load_platforms()
     expected = [
         "add-watch.md",
@@ -473,8 +619,18 @@ def test_monoliths_render_inline_single_file_no_references():
         assert "references/" not in arts[0].content or "see `references/" not in arts[0].content.lower()
 
 
+def test_monolith_sources_single_home_the_query_reference_slot():
+    """Canonical monolith sources contain no dead query/path/explain body."""
+    expected = "## For /graphify query\n\n@@QUERY_REFERENCE@@\n\n"
+    for key in ("aider", "devin"):
+        source = gen._read_fragment(f"core/{key}.md")
+        start = source.index("## For /graphify query")
+        end = source.index("## For /graphify add", start)
+        assert source[start:end] == expected, key
+
+
 def test_monolith_roundtrip_passes_for_aider_and_devin():
-    """Each monolith is diff-clean vs v8 except the file_type enum unification."""
+    """Each monolith is diff-clean vs v8 modulo exact sanctioned blocks/fixes."""
     platforms = gen.load_platforms()
     for key in ("aider", "devin"):
         problems = gen.monolith_roundtrip(platforms[key])
@@ -499,6 +655,70 @@ def test_monoliths_change_only_sanctioned_lines():
         assert UNIFIED_DESCRIPTION in rendered
 
 
+def test_monolith_roundtrip_rejects_query_block_drift(monkeypatch):
+    """The shared query exception is exact: one changed line fails roundtrip."""
+    platforms = gen.load_platforms()
+    original_render = gen.render
+
+    def render_with_drift(platform):
+        artifacts = original_render(platform)
+        if platform.key != "aider":
+            return artifacts
+        artifact = artifacts[0]
+        content = artifact.content.replace(
+            "Load this for questions against an existing graph",
+            "Load this only for questions against an existing graph",
+            1,
+        )
+        return [gen.RenderedArtifact(artifact.path, content)]
+
+    monkeypatch.setattr(gen, "render", render_with_drift)
+    problems = gen.monolith_roundtrip(platforms["aider"])
+    assert any("differs from canonical reference" in problem for problem in problems)
+
+
+@pytest.mark.parametrize("slot", ("@@QUERY_USAGE@@", "@@QUERY_REFERENCE@@"))
+@pytest.mark.parametrize("mutation", ("missing", "duplicate"))
+def test_monolith_render_rejects_missing_or_duplicate_markers(
+    monkeypatch, slot, mutation
+):
+    """Every monolith query marker has exact cardinality."""
+    platforms = gen.load_platforms()
+    original_read = gen._read_fragment
+
+    def read_with_tampered_marker(rel):
+        content = original_read(rel)
+        if rel == "core/aider.md":
+            if mutation == "missing":
+                return content.replace(slot, "", 1)
+            return content + f"\n{slot}\n"
+        return content
+
+    monkeypatch.setattr(gen, "_read_fragment", read_with_tampered_marker)
+    with pytest.raises(ValueError, match=f"exactly one {slot} slot"):
+        gen.render(platforms["aider"])
+
+
+def test_monolith_renderer_preserves_prose_and_roundtrip_rejects_it(monkeypatch):
+    """Editable prose around the slot is rendered, never silently discarded."""
+    platforms = gen.load_platforms()
+    original_read = gen._read_fragment
+    added = "UNEXPECTED EDITABLE QUERY PROSE"
+
+    def read_with_extra_prose(rel):
+        content = original_read(rel)
+        if rel == "core/aider.md":
+            return content.replace(
+                "@@QUERY_REFERENCE@@", f"@@QUERY_REFERENCE@@\n\n{added}", 1
+            )
+        return content
+
+    monkeypatch.setattr(gen, "_read_fragment", read_with_extra_prose)
+    assert added in gen.render(platforms["aider"])[0].content
+    problems = gen.monolith_roundtrip(platforms["aider"])
+    assert any("differs from canonical reference" in problem for problem in problems)
+
+
 def test_monoliths_carry_the_1392_runbook_fixes():
     """The four #1392 data-loss/correctness fixes are present in both monoliths.
 
diff --git a/tools/skillgen/expected/graphify__skill-agents.md b/tools/skillgen/expected/graphify__skill-agents.md
index 4969929c0..b17b35385 100644
--- a/tools/skillgen/expected/graphify__skill-agents.md
+++ b/tools/skillgen/expected/graphify__skill-agents.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-aider.md b/tools/skillgen/expected/graphify__skill-aider.md
index 8db8f73f2..be49b0c38 100644
--- a/tools/skillgen/expected/graphify__skill-aider.md
+++ b/tools/skillgen/expected/graphify__skill-aider.md
@@ -26,11 +26,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -906,269 +909,108 @@ Then run Steps 5–9 as normal (label communities, generate viz, benchmark, clea
 
 ## For /graphify query
 
-Two traversal modes - choose based on the question:
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+**Search contract**
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-Load `graphify-out/graph.json`, then:
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-1. Find the 1-3 nodes whose label best matches key terms in the question.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
+### Query
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+Choose traversal mode from the question:
 
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) > 3]
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
-
-Replace `QUESTION` with the user's actual question, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above.
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-After writing the answer, save it back into the graph so it improves future queries:
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
 
-Replace `QUESTION` with the question, `ANSWER` with your full answer text, `SOURCE_NODES` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
----
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-## For /graphify path
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-Find the shortest path between two named concepts in the graph.
+### Inline NetworkX fallback
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
+```python
+from graphify.serve import _source_display
 
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+display = _source_display(node_data)
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-After writing the explanation, save it back:
+### Save useful results
+
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
 ```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
-## For /graphify explain
+## For /graphify path
 
-Give a plain-language explanation of a single node - everything connected to it.
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
-First check the graph exists:
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
-If it fails, stop and tell the user to run `/graphify <path>` first.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
+Transport behavior differs only in how ambiguity is returned:
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
-After writing the explanation, save it back:
+## For /graphify explain
+
+Prefer the CLI/MCP resolver:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
----
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
+
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
 
 ## For /graphify add
 
diff --git a/tools/skillgen/expected/graphify__skill-amp.md b/tools/skillgen/expected/graphify__skill-amp.md
index 4969929c0..b17b35385 100644
--- a/tools/skillgen/expected/graphify__skill-amp.md
+++ b/tools/skillgen/expected/graphify__skill-amp.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-claw.md b/tools/skillgen/expected/graphify__skill-claw.md
index bafbca074..1192ab1f2 100644
--- a/tools/skillgen/expected/graphify__skill-claw.md
+++ b/tools/skillgen/expected/graphify__skill-claw.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-codex.md b/tools/skillgen/expected/graphify__skill-codex.md
index d71f4592d..f19256e8a 100644
--- a/tools/skillgen/expected/graphify__skill-codex.md
+++ b/tools/skillgen/expected/graphify__skill-codex.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-copilot.md b/tools/skillgen/expected/graphify__skill-copilot.md
index bafbca074..1192ab1f2 100644
--- a/tools/skillgen/expected/graphify__skill-copilot.md
+++ b/tools/skillgen/expected/graphify__skill-copilot.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-devin.md b/tools/skillgen/expected/graphify__skill-devin.md
index c444a852d..81f0485f1 100644
--- a/tools/skillgen/expected/graphify__skill-devin.md
+++ b/tools/skillgen/expected/graphify__skill-devin.md
@@ -37,11 +37,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -1042,265 +1045,108 @@ Then run Steps 5-9 as normal (label communities, generate viz, benchmark, clean
 
 ## For /graphify query
 
-Two traversal modes - choose based on the question:
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+**Search contract**
 
-Load `graphify-out/graph.json`, then:
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-1. Find the 1-3 nodes whose label best matches key terms in the question.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+### Query
 
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) > 3]
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Choose traversal mode from the question:
 
-Replace `QUESTION` with the user's actual question, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above.
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-After writing the answer, save it back into the graph so it improves future queries:
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
 
----
-
-## For /graphify path
-
-Find the shortest path between two named concepts in the graph.
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-a_term = 'NODE_A'
-b_term = 'NODE_B'
+### Inline NetworkX fallback
 
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-src = find_node(a_term)
-tgt = find_node(b_term)
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
+```python
+from graphify.serve import _source_display
 
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+display = _source_display(node_data)
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names. Then explain the path in plain language - what each hop means, why it's significant.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-After writing the explanation, save it back:
+### Save useful results
+
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
 ```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
-## For /graphify explain
+## For /graphify path
 
-Give a plain-language explanation of a single node - everything connected to it.
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
-First check the graph exists:
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
+Transport behavior differs only in how ambiguity is returned:
 
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
-Replace `NODE_NAME` with the concept. Then write a 3-5 sentence explanation using source locations as citations.
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
-After writing the explanation, save it back:
+## For /graphify explain
+
+Prefer the CLI/MCP resolver:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
----
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
+
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
 
 ## For /graphify add
 
diff --git a/tools/skillgen/expected/graphify__skill-droid.md b/tools/skillgen/expected/graphify__skill-droid.md
index ae1d49325..fa3d1f85e 100644
--- a/tools/skillgen/expected/graphify__skill-droid.md
+++ b/tools/skillgen/expected/graphify__skill-droid.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -647,10 +650,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-kilo.md b/tools/skillgen/expected/graphify__skill-kilo.md
index 6aa87a8bd..a4e11df6d 100644
--- a/tools/skillgen/expected/graphify__skill-kilo.md
+++ b/tools/skillgen/expected/graphify__skill-kilo.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-kiro.md b/tools/skillgen/expected/graphify__skill-kiro.md
index bafbca074..1192ab1f2 100644
--- a/tools/skillgen/expected/graphify__skill-kiro.md
+++ b/tools/skillgen/expected/graphify__skill-kiro.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-opencode.md b/tools/skillgen/expected/graphify__skill-opencode.md
index 8c3ce3eed..4373e39b3 100644
--- a/tools/skillgen/expected/graphify__skill-opencode.md
+++ b/tools/skillgen/expected/graphify__skill-opencode.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -642,10 +645,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-pi.md b/tools/skillgen/expected/graphify__skill-pi.md
index bafbca074..1192ab1f2 100644
--- a/tools/skillgen/expected/graphify__skill-pi.md
+++ b/tools/skillgen/expected/graphify__skill-pi.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-trae.md b/tools/skillgen/expected/graphify__skill-trae.md
index af59166ae..756f7b9c6 100644
--- a/tools/skillgen/expected/graphify__skill-trae.md
+++ b/tools/skillgen/expected/graphify__skill-trae.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -648,10 +651,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-vscode.md b/tools/skillgen/expected/graphify__skill-vscode.md
index 11a2837b5..40cd1c98a 100644
--- a/tools/skillgen/expected/graphify__skill-vscode.md
+++ b/tools/skillgen/expected/graphify__skill-vscode.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -646,10 +649,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill-windows.md b/tools/skillgen/expected/graphify__skill-windows.md
index 0dc73947a..66e361201 100644
--- a/tools/skillgen/expected/graphify__skill-windows.md
+++ b/tools/skillgen/expected/graphify__skill-windows.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -672,10 +675,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skill.md b/tools/skillgen/expected/graphify__skill.md
index bafbca074..1192ab1f2 100644
--- a/tools/skillgen/expected/graphify__skill.md
+++ b/tools/skillgen/expected/graphify__skill.md
@@ -35,11 +35,14 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
 ```
 
 ## What graphify is for
@@ -50,7 +53,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
@@ -650,10 +653,26 @@ Both are non-default subcommands. `--update` re-extracts only new or changed fil
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
 
 ---
 
diff --git a/tools/skillgen/expected/graphify__skills__agents__references__query.md b/tools/skillgen/expected/graphify__skills__agents__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__agents__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__agents__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__amp__references__query.md b/tools/skillgen/expected/graphify__skills__amp__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__amp__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__amp__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__claude__references__query.md b/tools/skillgen/expected/graphify__skills__claude__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__claude__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__claude__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__claw__references__query.md b/tools/skillgen/expected/graphify__skills__claw__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__claw__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__claw__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__codex__references__query.md b/tools/skillgen/expected/graphify__skills__codex__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__codex__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__codex__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__copilot__references__query.md b/tools/skillgen/expected/graphify__skills__copilot__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__copilot__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__copilot__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__droid__references__query.md b/tools/skillgen/expected/graphify__skills__droid__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__droid__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__droid__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__kilo__references__query.md b/tools/skillgen/expected/graphify__skills__kilo__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__kilo__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__kilo__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__kiro__references__query.md b/tools/skillgen/expected/graphify__skills__kiro__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__kiro__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__kiro__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__opencode__references__query.md b/tools/skillgen/expected/graphify__skills__opencode__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__opencode__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__opencode__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__pi__references__query.md b/tools/skillgen/expected/graphify__skills__pi__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__pi__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__pi__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__trae__references__query.md b/tools/skillgen/expected/graphify__skills__trae__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__trae__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__trae__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__vscode__references__query.md b/tools/skillgen/expected/graphify__skills__vscode__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__vscode__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__vscode__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/expected/graphify__skills__windows__references__query.md b/tools/skillgen/expected/graphify__skills__windows__references__query.md
index 56565eb78..26570dc81 100644
--- a/tools/skillgen/expected/graphify__skills__windows__references__query.md
+++ b/tools/skillgen/expected/graphify__skills__windows__references__query.md
@@ -1,311 +1,104 @@
 # graphify reference: query, path, explain
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+**Search contract**
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
 
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+### Query
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Choose traversal mode from the question:
 
-1. Extract the token vocabulary from node labels:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
-```
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
+```bash
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
 
-### Step 1 — Traversal
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
-
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+### Inline NetworkX fallback
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+display = _source_display(node_data)
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
+### Save useful results
 
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
+```bash
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
+```
 
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/fragments/core/aider.md b/tools/skillgen/fragments/core/aider.md
index 8db8f73f2..6598f87ec 100644
--- a/tools/skillgen/fragments/core/aider.md
+++ b/tools/skillgen/fragments/core/aider.md
@@ -26,11 +26,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+@@QUERY_USAGE@@
 ```
 
 ## What graphify is for
@@ -906,269 +902,7 @@ Then run Steps 5–9 as normal (label communities, generate viz, benchmark, clea
 
 ## For /graphify query
 
-Two traversal modes - choose based on the question:
-
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
-
-Load `graphify-out/graph.json`, then:
-
-1. Find the 1-3 nodes whose label best matches key terms in the question.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
-
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) > 3]
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
-
-Replace `QUESTION` with the user's actual question, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above.
-
-After writing the answer, save it back into the graph so it improves future queries:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
-```
-
-Replace `QUESTION` with the question, `ANSWER` with your full answer text, `SOURCE_NODES` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
-
----
-
-## For /graphify path
-
-Find the shortest path between two named concepts in the graph.
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
-
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
-```
-
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
-
----
-
-## For /graphify explain
-
-Give a plain-language explanation of a single node - everything connected to it.
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
-
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
-
----
+@@QUERY_REFERENCE@@
 
 ## For /graphify add
 
diff --git a/tools/skillgen/fragments/core/core.md b/tools/skillgen/fragments/core/core.md
index a5e117b5c..315632157 100644
--- a/tools/skillgen/fragments/core/core.md
+++ b/tools/skillgen/fragments/core/core.md
@@ -32,11 +32,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+@@QUERY_USAGE@@
 ```
 
 ## What graphify is for
@@ -47,7 +43,7 @@ Drop any folder of code, docs, papers, images, or video into graphify and get a
 
 If the user invoked `/graphify --help` or `/graphify -h` (with no other arguments), print the contents of the `## Usage` section above verbatim and stop. Do not run any commands, do not detect files, do not default the path to `.`. Just print the Usage block and return.
 
-**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query "<question>"` immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
+**Fast path — existing graph:** Before doing anything else, check whether `graphify-out/graph.json` exists. The expected location is `graphify-out/graph.json` relative to the **current working directory** (i.e. the project root where you are running commands). If it exists AND the user's request is a natural-language question about the codebase (e.g. "How does X work?", "What calls Y?", "Trace the data flow through Z") and NOT an explicit rebuild command (`--update`, `--cluster-only`, or a bare path/URL that implies fresh extraction): **skip Steps 1–5 entirely and jump straight to `## For /graphify query`.** Run `graphify query` with the user's question as one structured argument immediately. Do not run detect. Do not check corpus size. Do not ask the user to narrow. The graph is already built — use it.
 
 If no path was given, use `.` (current directory). Do not ask the user for a path.
 
diff --git a/tools/skillgen/fragments/core/devin.md b/tools/skillgen/fragments/core/devin.md
index c444a852d..1646e35cc 100644
--- a/tools/skillgen/fragments/core/devin.md
+++ b/tools/skillgen/fragments/core/devin.md
@@ -37,11 +37,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify add <url>                                   # fetch URL, save to ./raw, update graph
 /graphify add <url> --author "Name"                   # tag who wrote it
 /graphify add <url> --contributor "Name"              # tag who added it to the corpus
-/graphify query "<question>"                          # BFS traversal - broad context
-/graphify query "<question>" --dfs                    # DFS - trace a specific path
-/graphify query "<question>" --budget 1500            # cap answer at N tokens
-/graphify path "AuthModule" "Database"                # shortest path between two concepts
-/graphify explain "SwinTransformer"                   # plain-language explanation of a node
+@@QUERY_USAGE@@
 ```
 
 ## What graphify is for
@@ -1042,265 +1038,7 @@ Then run Steps 5-9 as normal (label communities, generate viz, benchmark, clean
 
 ## For /graphify query
 
-Two traversal modes - choose based on the question:
-
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
-
-Load `graphify-out/graph.json`, then:
-
-1. Find the 1-3 nodes whose label best matches key terms in the question.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
-
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) > 3]
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
-```
-
-Replace `QUESTION` with the user's actual question, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above.
-
-After writing the answer, save it back into the graph so it improves future queries:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
-```
-
----
-
-## For /graphify path
-
-Find the shortest path between two named concepts in the graph.
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
-```
-
-Replace `NODE_A` and `NODE_B` with the actual concept names. Then explain the path in plain language - what each hop means, why it's significant.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
-
----
-
-## For /graphify explain
-
-Give a plain-language explanation of a single node - everything connected to it.
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text())
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept. Then write a 3-5 sentence explanation using source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
-
----
+@@QUERY_REFERENCE@@
 
 ## For /graphify add
 
diff --git a/tools/skillgen/fragments/query-contract/default.md b/tools/skillgen/fragments/query-contract/default.md
new file mode 100644
index 000000000..0cb9a1847
--- /dev/null
+++ b/tools/skillgen/fragments/query-contract/default.md
@@ -0,0 +1,15 @@
+**Search contract**
+
+- **Shell safety:** User-controlled question text is data, never shell syntax. Use an MCP/structured argument API or a process API with an argument list. If a shell is unavoidable, correctly escape or encode the question as one argv value. Never interpolate raw user text into a quoted command or code template.
+- **Reserved directives:** `include:memory`, `community:...`, and `god:...` are control syntax, not semantic search text. Append them only when intentionally activating that behavior. If the user asks about the literal syntax, answer from documentation or paraphrase the search without the reserved token; forwarding it would activate the parser.
+- **Default retrieval:** Query retrieval is staged across code, documentation, tests, and likely communities. Saved `graphify-out/memory` Q&A nodes are fallback-only unless `include:memory` is intentionally active.
+
+| Need | Action |
+|------|--------|
+| Use prior saved Q&A as candidates | Add `include:memory`. |
+| Limit retrieval to a community or god node | Add `community:<id|label>` or `god:<label|id>`; quote labels containing spaces. Named communities come from `.graphify_labels.json` beside `graph.json`. Prefer names in durable instructions because numeric community IDs can change after rebuilds. |
+| Control work and output size | Pass `--budget N`; it bounds deterministic traversal as well as final text. |
+| Resolve an ambiguous `path` or `explain` label | The CLI exits 2 and prints ranked candidates. MCP/HTTP return the ambiguity diagnostic as successful text. In both cases, never guess; rerun with `<source-file>::<label>` or the exact node ID. |
+| Cite a result | Preserve Graphify's truthful source display: a known span, `(file only)`, external/reference provenance from `origin_file`, or `(no source)`. Fallback code must call `graphify.serve._source_display` rather than inventing locations or a separate provenance contract. |
+
+Advanced directives require the Graphify CLI or MCP implementation. The inline NetworkX fallback cannot emulate them: never pass `include:memory`, `community:...`, or `god:...` into fallback label matching.
diff --git a/tools/skillgen/fragments/query-stub/default.md b/tools/skillgen/fragments/query-stub/default.md
index 696796ec5..0ac3e8ca1 100644
--- a/tools/skillgen/fragments/query-stub/default.md
+++ b/tools/skillgen/fragments/query-stub/default.md
@@ -1,7 +1,9 @@
 When `graphify-out/graph.json` already exists and the user asks a question about the corpus, answer from the graph rather than rebuilding it:
 
 ```bash
-graphify query "<question>"
+graphify query "Where is authentication validated?"
 ```
 
-Before traversal, expand the question against the graph's own vocabulary so a wording mismatch does not collapse the answer to noise. If the `graphify query` CLI is unavailable, fall back to an inline NetworkX traversal of `graphify-out/graph.json`. Answer using only what the graph output contains, and quote `source_location` when citing a specific fact. For that vocab-expansion step, the BFS/DFS traversal modes, the `--budget` cap, the NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
+@@QUERY_CONTRACT@@
+
+The example is a fixed literal, not an interpolation template. If a plain query finds no useful vocabulary match, retry with relevant labels that actually exist in the graph; do not invent nodes or edges. For CLI examples, the constrained inline NetworkX fallback, `save-result` feedback, and the `/graphify path` and `/graphify explain` flows, see `references/query.md`.
diff --git a/tools/skillgen/fragments/query-usage/default.md b/tools/skillgen/fragments/query-usage/default.md
new file mode 100644
index 000000000..0712b3791
--- /dev/null
+++ b/tools/skillgen/fragments/query-usage/default.md
@@ -0,0 +1,8 @@
+/graphify query "<question-argv>"                     # pass the question as one data argument; never interpolate shell text
+/graphify query "<question-argv>" --dfs               # trace a specific chain with staged retrieval
+/graphify query "<question-argv>" --budget 1500       # bound deterministic traversal and final output
+/graphify query 'community:"Main Runtime" target flow' # scope to a named community (quote spaces)
+/graphify query 'god:"Auth Gateway" request flow'      # scope to a named god node
+/graphify query "include:memory prior decision"        # explicitly include saved Q&A in retrieval
+/graphify path "src/auth.py::AuthModule" "Database"   # qualify an ambiguous label with its source file
+/graphify explain "src/model.py::SwinTransformer"      # explain one source-qualified node
diff --git a/tools/skillgen/fragments/references/query/default.md b/tools/skillgen/fragments/references/query/default.md
index 56565eb78..5f4a77629 100644
--- a/tools/skillgen/fragments/references/query/default.md
+++ b/tools/skillgen/fragments/references/query/default.md
@@ -1,311 +1,90 @@
-# graphify reference: query, path, explain
+@@QUERY_REFERENCE_HEADING@@
 
-Load this when the user asks a question against an existing graph, or runs `/graphify path` or `/graphify explain`. The core's query stub points here for the full traversal flow. These flows use the `graphify query` CLI when it is available and fall back to an inline NetworkX traversal otherwise.
+Load this for questions against an existing graph and for `query`, `path`, or `explain`.
 
-Two traversal modes - choose based on the question:
+@@QUERY_CONTRACT@@
 
-| Mode | Flag | Best for |
-|------|------|----------|
-| BFS (default) | _(none)_ | "What is X connected to?" - broad context, nearest neighbors first |
-| DFS | `--dfs` | "How does X reach Y?" - trace a specific chain or dependency path |
-
-First check the graph exists:
-```bash
-$(cat graphify-out/.graphify_python) -c "
-from pathlib import Path
-if not Path('graphify-out/graph.json').exists():
-    print('ERROR: No graph found. Run /graphify <path> first to build the graph.')
-    raise SystemExit(1)
-"
-```
-If it fails, stop and tell the user to run `/graphify <path>` first.
+### Query
 
-### Step 0 — Constrained query expansion (REQUIRED before traversal)
+Choose traversal mode from the question:
 
-graphify's `query` CLI matches nodes via case-folded substring + IDF — there is **no stemming, no synonyms, no cross-language match** inside the binary, and the inline fallback below matches the same way. If the user's question uses different language or different domain vocabulary than the graph's labels (user says "обработчик" / graph says "handler"; user says "authentication" / graph says "Guardian"), the literal matcher returns 0 hits and the answer collapses to noise.
+| Mode | Flag | Best for |
+|------|------|----------|
+| BFS (default) | _(none)_ | Broad context and nearest related concepts. |
+| DFS | `--dfs` | A specific chain, dependency, or data flow. |
 
-Fix this **without inventing tokens** by expanding the query against the actual graph vocabulary first:
+Use the CLI or MCP through a structured argument API whenever possible. If launching a process, put the complete semantic question in one argv element and add reserved directives only as an intentional part of that same argument. The commands below contain fixed literals; they are not templates for raw string interpolation.
 
-1. Extract the token vocabulary from node labels:
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, re
-from pathlib import Path
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-vocab = set()
-for n in data['nodes']:
-    for c in re.findall(r'[^\W\d_]+', n.get('label','') or '', re.UNICODE):
-        parts = re.findall(r'[A-Z]+(?=[A-Z][a-z])|[A-Z]?[a-z]+|[A-Z]+', c) or [c]
-        for p in parts:
-            t = p.lower()
-            if 3 <= len(t) <= 30:
-                vocab.add(t)
-Path('graphify-out/.vocab.txt').write_text('\n'.join(sorted(vocab)), encoding='utf-8')
-print(f'vocab: {len(vocab)} tokens')
-"
+graphify query "Where is authentication validated?"
+graphify query "How does capture reach inference?" --dfs --budget 3000
+graphify query 'controller latency community:"Main Runtime"'
+graphify query 'request flow god:"Auth Gateway"'
+graphify query "why was polling retained? include:memory"
 ```
 
-2. Read `graphify-out/.vocab.txt`. Then for the user's question, select **up to 12 tokens from this exact list** that semantically match the query intent. Hard constraints:
-   - You MUST pick only tokens present in the vocabulary file. Do NOT invent tokens.
-   - If a query concept has no plausible token in the vocab, skip it — do not substitute a near-synonym from training memory.
-   - If **no** vocab tokens match the query at all, output an empty list and tell the user the corpus has no relevant vocabulary for this question. Do not fabricate a search.
-   - Translate cross-language: Russian "аутентификация" → look for `auth`, `credential`, `token`, `security` IFF present in vocab.
-   - Morphology: "handlers" maps to `handler` IFF present; "todos" maps to `todo` IFF present.
+Keep semantic text separate from reserved control syntax. For example, if the user asks what `include:memory` means, answer from these instructions or query for `memory inclusion behavior`; do not forward the literal reserved token unless the user intends to include saved Q&A.
 
-3. Print the selection explicitly to the user before running the query, so the expansion is auditable:
-```
-Query expanded to (from graph vocab, N tokens): [token1, token2, ...]
-```
-If the list is empty, say so plainly and stop — do not proceed to traversal.
+Answer only from the returned subgraph. Preserve source display exactly; never turn file-only, external/reference, or missing provenance into an invented line number.
 
-### Step 1 — Traversal
+If a plain query returns no useful match because the user's wording differs from graph labels, inspect labels already present in `graph.json` and retry with the closest relevant graph vocabulary. Do not invent labels, synonyms, nodes, or edges.
 
-Build the **expanded query string** by joining the selected tokens with spaces. Use this string as `QUESTION` below — NOT the original user question. (The original question is preserved only for `save-result` at the end.)
+### Inline NetworkX fallback
 
-Prefer the CLI when it is installed:
-```bash
-graphify query "QUESTION"
-# or: graphify query "QUESTION" --dfs --budget 3000
-```
+Use fallback only when the CLI and MCP implementation are unavailable and the request is a plain, unscoped query. It cannot emulate staged scope selection, advanced directives, label-sidecar resolution, or CLI budget semantics.
 
-If the CLI is unavailable, load `graphify-out/graph.json` and run the traversal inline:
+- Pass the question into fallback code as structured data, never by inserting it into shell or Python source.
+- If intentional behavior requires `include:memory`, `community:...`, or `god:...`, stop and report that CLI/MCP is required. Do not pass directive text into fallback matching.
+- If the user is discussing a directive literally, paraphrase the semantic terms before matching so the reserved token is not activated.
+- Keep fallback traversal deterministic and bounded, and label its display cap as different from CLI `--budget` semantics.
+- Delegate source rendering to the implementation helper so fallback and CLI stay aligned:
 
-1. Find the 1-3 nodes whose label best matches the expanded tokens.
-2. Run the appropriate traversal from each starting node.
-3. Read the subgraph - node labels, edge relations, confidence tags, source locations.
-4. Answer using **only** what the graph contains. Quote `source_location` when citing a specific fact.
-5. If the graph lacks enough information, say so - do not hallucinate edges.
+```python
+from graphify.serve import _source_display
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import sys, json
-from networkx.readwrite import json_graph
-import networkx as nx
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-question = 'QUESTION'
-mode = 'MODE'  # 'bfs' or 'dfs'
-terms = [t.lower() for t in question.split() if len(t) >= 3]  # match the vocab threshold; keeps api/jwt/ios (#1392)
-
-# Find best-matching start nodes
-scored = []
-for nid, ndata in G.nodes(data=True):
-    label = ndata.get('label', '').lower()
-    score = sum(1 for t in terms if t in label)
-    if score > 0:
-        scored.append((score, nid))
-scored.sort(reverse=True)
-start_nodes = [nid for _, nid in scored[:3]]
-
-if not start_nodes:
-    print('No matching nodes found for query terms:', terms)
-    sys.exit(0)
-
-subgraph_nodes = set()
-subgraph_edges = []
-
-if mode == 'dfs':
-    # DFS: follow one path as deep as possible before backtracking.
-    # Depth-limited to 6 to avoid traversing the whole graph.
-    visited = set()
-    stack = [(n, 0) for n in reversed(start_nodes)]
-    while stack:
-        node, depth = stack.pop()
-        if node in visited or depth > 6:
-            continue
-        visited.add(node)
-        subgraph_nodes.add(node)
-        for neighbor in G.neighbors(node):
-            if neighbor not in visited:
-                stack.append((neighbor, depth + 1))
-                subgraph_edges.append((node, neighbor))
-else:
-    # BFS: explore all neighbors layer by layer up to depth 3.
-    frontier = set(start_nodes)
-    subgraph_nodes = set(start_nodes)
-    for _ in range(3):
-        next_frontier = set()
-        for n in frontier:
-            for neighbor in G.neighbors(n):
-                if neighbor not in subgraph_nodes:
-                    next_frontier.add(neighbor)
-                    subgraph_edges.append((n, neighbor))
-        subgraph_nodes.update(next_frontier)
-        frontier = next_frontier
-
-# Token-budget aware output: rank by relevance, cut at budget (~4 chars/token)
-token_budget = BUDGET  # default 2000
-char_budget = token_budget * 4
-
-# Score each node by term overlap for ranked output
-def relevance(nid):
-    label = G.nodes[nid].get('label', '').lower()
-    return sum(1 for t in terms if t in label)
-
-ranked_nodes = sorted(subgraph_nodes, key=relevance, reverse=True)
-
-lines = [f'Traversal: {mode.upper()} | Start: {[G.nodes[n].get(\"label\",n) for n in start_nodes]} | {len(subgraph_nodes)} nodes']
-for nid in ranked_nodes:
-    d = G.nodes[nid]
-    lines.append(f'  NODE {d.get(\"label\", nid)} [src={d.get(\"source_file\",\"\")} loc={d.get(\"source_location\",\"\")}]')
-for u, v in subgraph_edges:
-    if u in subgraph_nodes and v in subgraph_nodes:
-        _raw = G[u][v]; d = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-        lines.append(f'  EDGE {G.nodes[u].get(\"label\",u)} --{d.get(\"relation\",\"\")} [{d.get(\"confidence\",\"\")}]--> {G.nodes[v].get(\"label\",v)}')
-
-output = '\n'.join(lines)
-if len(output) > char_budget:
-    output = output[:char_budget] + f'\n... (truncated at ~{token_budget} token budget - use --budget N for more)'
-print(output)
-"
+display = _source_display(node_data)
 ```
 
-Replace `QUESTION` with the **expanded** query string, `MODE` with `bfs` or `dfs`, and `BUDGET` with the token budget (default `2000`, or whatever `--budget N` specifies). Then answer based on the subgraph output above, using only what the graph contains.
+`_source_display` preserves known spans and file-only locations, recognizes `origin_file` as external/reference provenance, and marks unowned nodes honestly. Do not create a separate `source_url`-only provenance rule; if runtime URL handling evolves, the shared helper remains the source of truth.
 
-After writing the answer, save it back into the graph so it improves future queries. Include the expanded tokens inside the `--answer` text (e.g. `"Expanded from original query via vocab: [tokens]. Then traversed..."`) so the next `--update` extracts the expansion history as a graph node:
+### Save useful results
+
+After answering, save the original question and cited node labels through structured arguments. This fixed-literal example records a useful result:
 
 ```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "ORIGINAL_QUESTION" --answer "ANSWER" --type query --nodes NODE1 NODE2
+graphify save-result --question "Where is authentication validated?" --answer "AuthGuard validates authentication." --type query --nodes AuthGuard --outcome useful
 ```
 
-Replace `ORIGINAL_QUESTION` with the user's verbatim question, `ANSWER` with your full answer text (containing the expanded-token trace), `NODE1 NODE2` with the list of node labels you cited. This closes the feedback loop: the next `--update` will extract this Q&A as a node in the graph.
-
-**Work memory (self-improving loop).** Add an `--outcome` so future sessions learn from this one — append `--outcome useful|dead_end|corrected` to the `save-result` command (and `--correction "the right answer"` when correcting):
-
-- `useful` — the cited nodes answered the question well (they become *preferred sources*).
-- `dead_end` — the question/path led nowhere; don't re-derive it next time.
-- `corrected` — the saved answer was wrong; `--correction` records what was right.
-
-At the **start** of graph work, refresh and read the lessons: run `graphify reflect --if-stale` (cheap, deterministic, no LLM; `--if-stale` makes it a no-op when `LESSONS.md` is already newer than every input, e.g. when the git hook just refreshed it), then read `graphify-out/reflections/LESSONS.md`. It lists **preferred sources** (start there), **known dead ends** (skip them), and prior **corrections**. Running `reflect` yourself keeps the lessons current even without the git hook installed; if the post-commit hook *is* installed, `--if-stale` means your session-start run costs almost nothing.
-
----
+Use `--outcome dead_end` when traversal did not answer the question. Use `--outcome corrected` with a correction argument when replacing a wrong result. Before graph work, run `graphify reflect --if-stale` and read `graphify-out/reflections/LESSONS.md` when it exists.
 
 ## For /graphify path
 
-Find the shortest path between two named concepts in the graph. Prefer the CLI when installed:
-
-```bash
-graphify path "NODE_A" "NODE_B"
-```
-
-If the CLI is unavailable, run it inline:
+Prefer the CLI/MCP resolver. Plain labels are allowed only when unique:
 
 ```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-a_term = 'NODE_A'
-b_term = 'NODE_B'
-
-def find_node(term):
-    term = term.lower()
-    scored = sorted(
-        [(sum(1 for w in term.split() if w in G.nodes[n].get('label','').lower()), n)
-         for n in G.nodes()],
-        reverse=True
-    )
-    return scored[0][1] if scored and scored[0][0] > 0 else None
-
-src = find_node(a_term)
-tgt = find_node(b_term)
-
-if not src or not tgt:
-    print(f'Could not find nodes matching: {a_term!r} or {b_term!r}')
-    sys.exit(0)
-
-try:
-    path = nx.shortest_path(G, src, tgt)
-    print(f'Shortest path ({len(path)-1} hops):')
-    for i, nid in enumerate(path):
-        label = G.nodes[nid].get('label', nid)
-        if i < len(path) - 1:
-            _raw = G[nid][path[i+1]]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-            rel = edge.get('relation', '')
-            conf = edge.get('confidence', '')
-            print(f'  {label} --{rel}--> [{conf}]')
-        else:
-            print(f'  {label}')
-except nx.NetworkXNoPath:
-    print(f'No path found between {a_term!r} and {b_term!r}')
-except nx.NodeNotFound as e:
-    print(f'Node not found: {e}')
-"
+graphify path "AuthModule" "Database"
+graphify path "src/auth.py::AuthModule" "src/db.py::Database"
 ```
 
-Replace `NODE_A` and `NODE_B` with the actual concept names from the user. Then explain the path in plain language - what each hop means, why it's significant.
+Transport behavior differs only in how ambiguity is returned:
 
-After writing the explanation, save it back:
+- CLI: exits with status 2 and prints ranked candidates.
+- MCP/HTTP: returns the same ambiguity diagnostic as successful tool-result text; it does not turn ambiguity into a transport error.
 
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Path from NODE_A to NODE_B" --answer "ANSWER" --type path_query --nodes NODE_A NODE_B
-```
+Both require the same response: never choose a candidate by position or score. Rerun with the printed `<source-file>::<label>` selector or exact node ID.
 
----
+If CLI/MCP is unavailable, use NetworkX only after obtaining exact node IDs from `graph.json`; do not fuzzy-match labels in fallback code. Explain every hop using only returned relations and confidence, preserve truthful source markers, and save useful explanations with `--type path_query`.
 
 ## For /graphify explain
 
-Give a plain-language explanation of a single node - everything connected to it. Prefer the CLI when installed:
+Prefer the CLI/MCP resolver:
 
 ```bash
-graphify explain "NODE_NAME"
+graphify explain "SwinTransformer"
+graphify explain "src/model.py::SwinTransformer"
+graphify explain "EXACT_NODE_ID"
 ```
 
-If the CLI is unavailable, run it inline:
+The same transport rule applies: CLI ambiguity exits 2; MCP/HTTP ambiguity is successful diagnostic text. In both cases, rerun with a ranked source-qualified label or exact ID and never guess. If CLI/MCP is unavailable, inspect only an exact node ID in NetworkX and stop if it does not exist.
 
-```bash
-$(cat graphify-out/.graphify_python) -c "
-import json, sys
-import networkx as nx
-from networkx.readwrite import json_graph
-from pathlib import Path
-
-data = json.loads(Path('graphify-out/graph.json').read_text(encoding='utf-8'))
-G = json_graph.node_link_graph(data, edges='links')
-
-term = 'NODE_NAME'
-term_lower = term.lower()
-
-# Find best matching node
-scored = sorted(
-    [(sum(1 for w in term_lower.split() if w in G.nodes[n].get('label','').lower()), n)
-     for n in G.nodes()],
-    reverse=True
-)
-if not scored or scored[0][0] == 0:
-    print(f'No node matching {term!r}')
-    sys.exit(0)
-
-nid = scored[0][1]
-data_n = G.nodes[nid]
-print(f'NODE: {data_n.get(\"label\", nid)}')
-print(f'  source: {data_n.get(\"source_file\",\"unknown\")}')
-print(f'  type: {data_n.get(\"file_type\",\"unknown\")}')
-print(f'  degree: {G.degree(nid)}')
-print()
-print('CONNECTIONS:')
-for neighbor in G.neighbors(nid):
-    _raw = G[nid][neighbor]; edge = next(iter(_raw.values()), {}) if isinstance(G, nx.MultiGraph) else _raw
-    nlabel = G.nodes[neighbor].get('label', neighbor)
-    rel = edge.get('relation', '')
-    conf = edge.get('confidence', '')
-    src_file = G.nodes[neighbor].get('source_file', '')
-    print(f'  --{rel}--> {nlabel} [{conf}] ({src_file})')
-"
-```
-
-Replace `NODE_NAME` with the concept the user asked about. Then write a 3-5 sentence explanation of what this node is, what it connects to, and why those connections are significant. Use the source locations as citations.
-
-After writing the explanation, save it back:
-
-```bash
-$(cat graphify-out/.graphify_python) -m graphify save-result --question "Explain NODE_NAME" --answer "ANSWER" --type explain --nodes NODE_NAME
-```
+Write a concise explanation of what the node is, what it connects to, and why those connections matter. Render provenance through `graphify.serve._source_display` so the explanation matches CLI semantics.
diff --git a/tools/skillgen/gen.py b/tools/skillgen/gen.py
index 93e403f27..b96b8c79b 100644
--- a/tools/skillgen/gen.py
+++ b/tools/skillgen/gen.py
@@ -13,7 +13,7 @@
     python -m tools.skillgen --check         # byte-diff render vs committed + expected/, exit 1 on drift
     python -m tools.skillgen --audit-coverage# per host: assert every heading of that host's own v8 body single-homes in its render
     python -m tools.skillgen --schema-singleton  # assert the file_type enum is byte-identical everywhere
-    python -m tools.skillgen --monolith-roundtrip# assert each monolith == v8 modulo the enum unification
+    python -m tools.skillgen --monolith-roundtrip# assert each monolith == v8 modulo exact sanctioned blocks/fixes
     python -m tools.skillgen --always-on-roundtrip# assert each always_on/*.md reproduces its former constant
     python -m tools.skillgen --bless         # rewrite expected/ from the current render
 
@@ -140,6 +140,18 @@ def _v8_baseline_ref(platform_key: str) -> str:
 # weaker matcher (#1325).
 _QUERY_REFERENCE = "references/query/default.md"
 _QUERY_STUB = "query-stub/default.md"
+_QUERY_CONTRACT = "query-contract/default.md"
+_QUERY_USAGE = "query-usage/default.md"
+_QUERY_REFERENCE_SPLIT_HEADING = "# graphify reference: query, path, explain"
+_QUERY_REFERENCE_MONOLITH_HEADING = "## For /graphify query"
+_QUERY_SECTION_END = "## For /graphify add"
+_V8_QUERY_USAGE_LINES = (
+    '/graphify query "<question>"                          # BFS traversal - broad context',
+    '/graphify query "<question>" --dfs                    # DFS - trace a specific path',
+    '/graphify query "<question>" --budget 1500            # cap answer at N tokens',
+    '/graphify path "AuthModule" "Database"                # shortest path between two concepts',
+    '/graphify explain "SwinTransformer"                   # plain-language explanation of a node',
+)
 # The hooks reference is host-flavored. Most hosts read CLAUDE.md and wire
 # always-on via `graphify claude install` (the shared body). The agents-md hosts
 # (trae, trae-cn, amp) read AGENTS.md and wire it via `graphify <host> install`.
@@ -228,6 +240,14 @@ def _v8_baseline_ref(platform_key: str) -> str:
     "## What graphify is for",  # lean intro; v8 hosts had verbose intro prose, no heading.
 })
 
+# The new query runbook keeps the v8 behavior but removes two implementation-led
+# step names. Vocabulary retry now lives under ``### Query`` and is fallback-only;
+# traversal choice and CLI execution live under that same decision-first heading.
+SHARED_QUERY_CONSOLIDATION_ALLOWLIST: frozenset[str] = frozenset({
+    "### Step 0 — Constrained query expansion (REQUIRED before traversal)",
+    "### Step 1 — Traversal",
+})
+
 _CONSOLIDATION_ALLOWLIST: dict[str, frozenset[str]] = {
     # kilo's terse v8 step/part/section headings, renamed/re-leveled by the
     # shared lean core. Content is preserved under the core's richer headings
@@ -258,7 +278,11 @@ def _v8_baseline_ref(platform_key: str) -> str:
 
 def _audit_allowlist(platform_key: str) -> frozenset[str]:
     """The full set of v8 headings the audit may skip for this host."""
-    return SHARED_INTRO_ALLOWLIST | _CONSOLIDATION_ALLOWLIST.get(platform_key, frozenset())
+    return (
+        SHARED_INTRO_ALLOWLIST
+        | SHARED_QUERY_CONSOLIDATION_ALLOWLIST
+        | _CONSOLIDATION_ALLOWLIST.get(platform_key, frozenset())
+    )
 
 
 @dataclass(frozen=True)
@@ -336,6 +360,74 @@ def _normalise(text: str) -> str:
     return text.rstrip("\n") + "\n"
 
 
+def _require_exact_slot(text: str, slot: str, context: str) -> None:
+    """Require one template slot so missing/duplicate content cannot vanish."""
+    count = text.count(slot)
+    if count != 1:
+        raise ValueError(
+            f"{context} must contain exactly one {slot} slot; found {count}"
+        )
+
+
+def _render_query_reference(*, monolith: bool) -> str:
+    """Render the shared query runbook for a split reference or inline monolith."""
+    template = _read_fragment(_QUERY_REFERENCE)
+    _require_exact_slot(
+        template, "@@QUERY_REFERENCE_HEADING@@", "query reference"
+    )
+    _require_exact_slot(template, "@@QUERY_CONTRACT@@", "query reference")
+    contract = _read_fragment(_QUERY_CONTRACT).rstrip("\n")
+    heading = (
+        _QUERY_REFERENCE_MONOLITH_HEADING
+        if monolith
+        else _QUERY_REFERENCE_SPLIT_HEADING
+    )
+    body = (
+        template.replace("@@QUERY_REFERENCE_HEADING@@", heading)
+        .replace("@@QUERY_CONTRACT@@", contract)
+    )
+    if "@@" in body:
+        leftover = sorted(set(re.findall(r"@@\w+@@", body)))
+        raise ValueError(f"unfilled query-reference slots: {leftover}")
+    return _normalise(body)
+
+
+def _render_monolith(platform: Platform) -> str:
+    """Render a monolith by filling its exact usage and query-reference slots."""
+    body = _read_fragment(f"core/{platform.monolith}.md")
+    context = f"monolith '{platform.key}'"
+    _require_exact_slot(body, "@@QUERY_USAGE@@", context)
+    _require_exact_slot(body, "@@QUERY_REFERENCE@@", context)
+    usage = _read_fragment(_QUERY_USAGE).rstrip("\n")
+    body = body.replace("@@QUERY_USAGE@@", usage)
+
+    marker = "@@QUERY_REFERENCE@@"
+    if (
+        body.count(_QUERY_REFERENCE_MONOLITH_HEADING) != 1
+        or body.count(_QUERY_SECTION_END) != 1
+    ):
+        raise ValueError(
+            f"{context} must contain exactly one query heading and one add heading"
+        )
+    query_start = body.index(_QUERY_REFERENCE_MONOLITH_HEADING)
+    query_end = body.index(_QUERY_SECTION_END, query_start)
+    marker_index = body.index(marker)
+    if not query_start < marker_index < query_end:
+        raise ValueError(
+            f"{context} query marker must be between the query and add headings"
+        )
+    query = _render_query_reference(monolith=True)
+    heading_prefix = _QUERY_REFERENCE_MONOLITH_HEADING + "\n\n"
+    if not query.startswith(heading_prefix):
+        raise ValueError("rendered monolith query reference is missing its heading")
+    query_body = query.removeprefix(heading_prefix).rstrip("\n")
+    body = body.replace(marker, query_body)
+    if "@@" in body:
+        leftover = sorted(set(re.findall(r"@@\w+@@", body)))
+        raise ValueError(f"unfilled monolith slots for '{platform.key}': {leftover}")
+    return _normalise(body)
+
+
 @dataclass(frozen=True)
 class RenderedArtifact:
     """A single generated file: its repo-relative path and exact bytes."""
@@ -360,13 +452,22 @@ def _render_frontmatter(platform: Platform) -> str:
 def _render_core(platform: Platform) -> str:
     """Fill the shared core template's per-platform slots for this platform."""
     template = _read_fragment(f"core/{platform.core}.md")
+    context = f"split core '{platform.key}'"
+    _require_exact_slot(template, "@@QUERY_USAGE@@", context)
+    _require_exact_slot(template, "@@QUERY_STUB@@", context)
 
     if platform.dispatch is None:
         raise ValueError(f"split platform '{platform.key}' is missing a dispatch variant")
 
     install = _read_fragment(f"shell/{platform.shell}.md").rstrip("\n")
     dispatch = _read_fragment(f"dispatch/{platform.dispatch}.md").rstrip("\n")
-    query_stub = _read_fragment(_QUERY_STUB).rstrip("\n")
+    query_contract = _read_fragment(_QUERY_CONTRACT).rstrip("\n")
+    query_stub_template = _read_fragment(_QUERY_STUB)
+    _require_exact_slot(query_stub_template, "@@QUERY_CONTRACT@@", "query stub")
+    query_stub = query_stub_template.replace(
+        "@@QUERY_CONTRACT@@", query_contract
+    ).rstrip("\n")
+    query_usage = _read_fragment(_QUERY_USAGE).rstrip("\n")
 
     if platform.extra_sections:
         extra = "".join(
@@ -381,6 +482,7 @@ def _render_core(platform: Platform) -> str:
         .replace("@@INSTALL@@", install)
         .replace("@@DISPATCH@@", dispatch)
         .replace("@@QUERY_STUB@@", query_stub)
+        .replace("@@QUERY_USAGE@@", query_usage)
         .replace("@@HOOKS_TARGET@@", platform.hooks_target)
         .replace("@@EXTRA@@", extra)
     )
@@ -428,7 +530,7 @@ def render(platform: Platform) -> list[RenderedArtifact]:
     yields a single inline skill body.
     """
     if platform.bucket == "monolith":
-        body = _read_fragment(f"core/{platform.monolith}.md")
+        body = _render_monolith(platform)
         return [RenderedArtifact(platform.skill_dst, body)]
 
     if platform.bucket != "split":
@@ -448,6 +550,8 @@ def render(platform: Platform) -> list[RenderedArtifact]:
         # read verbatim.
         if name == "hooks" and platform.hooks_variant == "agents-md":
             body = _render_agents_md_hooks(platform)
+        elif name == "query":
+            body = _render_query_reference(monolith=False)
         else:
             body = _read_fragment(references[name])
         rel = f"{platform.refs_dst}/{name}.md"
@@ -944,12 +1048,47 @@ def _is_sanctioned_monolith_diff(line: str) -> bool:
     return not line.strip() or any(pred(line) for pred in _SANCTIONED_MONOLITH_DIFFS)
 
 
+def _remove_exact_block(
+    lines: list[str], block: tuple[str, ...], label: str
+) -> tuple[list[str], str | None]:
+    """Remove one exact contiguous block or return a strict roundtrip error."""
+    starts = [
+        index
+        for index in range(len(lines) - len(block) + 1)
+        if tuple(lines[index:index + len(block)]) == block
+    ]
+    if len(starts) != 1:
+        return lines, f"expected exactly one {label} block, found {len(starts)}"
+    start = starts[0]
+    return lines[:start] + lines[start + len(block):], None
+
+
+def _remove_heading_section(
+    lines: list[str], start_heading: str, end_heading: str, label: str
+) -> tuple[list[str], str | None]:
+    """Remove one frozen heading range, preserving the end heading."""
+    starts = [index for index, line in enumerate(lines) if line == start_heading]
+    if len(starts) != 1:
+        return lines, f"expected exactly one {label} start heading, found {len(starts)}"
+    start = starts[0]
+    ends = [
+        index for index, line in enumerate(lines[start + 1:], start + 1)
+        if line == end_heading
+    ]
+    if len(ends) != 1:
+        return lines, f"expected exactly one {label} end heading, found {len(ends)}"
+    return lines[:start] + lines[ends[0]:], None
+
+
 def monolith_roundtrip(platform: Platform) -> list[str]:
     """Assert a monolith renders diff-clean vs its v8 blob modulo allowed changes.
 
     The monolith bodies are hand-maintained single files frozen against a pinned
     pristine v8 blob (``roundtrip_ref``); this is the guard that stops an
-    arbitrary edit (even a blessed one) from drifting them. Sanctioned changes are
+    arbitrary edit (even a blessed one) from drifting them. The generated query
+    usage and query/path/explain sections are removed only when they byte-match
+    their canonical shared fragments; the corresponding frozen-v8 blocks are then
+    removed before the remaining multiset diff. Other sanctioned changes are
     enumerated as predicates in ``_SANCTIONED_MONOLITH_DIFFS``: the file_type enum
     unification, the unified frontmatter description, the chunk-cleanup rewrite
     (#1172), the four #1392 runbook fixes (directed propagation, content-only
@@ -966,7 +1105,8 @@ def monolith_roundtrip(platform: Platform) -> list[str]:
     if platform.roundtrip_ref is None:
         return [f"[{platform.key}] monolith is missing roundtrip_ref"]
 
-    rendered_lines = render(platform)[0].content.splitlines()
+    rendered_content = render(platform)[0].content
+    rendered_lines = rendered_content.splitlines()
     # Strip trigger lines from the original — they are non-spec and their removal
     # (#1180) is a permitted diff.
     original_lines = [
@@ -974,10 +1114,62 @@ def monolith_roundtrip(platform: Platform) -> list[str]:
         if not _is_trigger_line(l)
     ]
 
+    problems: list[str] = []
+    rendered_usage = tuple(_read_fragment(_QUERY_USAGE).splitlines())
+    rendered_lines, error = _remove_exact_block(
+        rendered_lines, rendered_usage, "canonical query usage"
+    )
+    if error:
+        problems.append(f"[{platform.key}] {error}")
+    original_lines, error = _remove_exact_block(
+        original_lines, _V8_QUERY_USAGE_LINES, "frozen-v8 query usage"
+    )
+    if error:
+        problems.append(f"[{platform.key}] {error}")
+
+    if (
+        rendered_content.count(_QUERY_REFERENCE_MONOLITH_HEADING) != 1
+        or rendered_content.count(_QUERY_SECTION_END) != 1
+    ):
+        problems.append(
+            f"[{platform.key}] rendered query section must have exactly one start and end heading"
+        )
+        return problems
+    query_start = rendered_content.index(_QUERY_REFERENCE_MONOLITH_HEADING)
+    query_end = rendered_content.index(_QUERY_SECTION_END, query_start)
+    rendered_query_section = rendered_content[query_start:query_end]
+    canonical_query_section = (
+        _render_query_reference(monolith=True).rstrip("\n") + "\n\n"
+    )
+    if rendered_query_section != canonical_query_section:
+        problems.append(
+            f"[{platform.key}] rendered query/path/explain section differs from canonical reference"
+        )
+        return problems
+
+    # Strip only after the complete rendered section has matched the canonical
+    # bytes. This prevents an extra line that happens to match another sanctioned
+    # monolith predicate from hiding inside the query replacement.
+    rendered_query = tuple(canonical_query_section.splitlines())
+    rendered_lines, error = _remove_exact_block(
+        rendered_lines, rendered_query, "canonical query/path/explain"
+    )
+    if error:
+        problems.append(f"[{platform.key}] {error}")
+    original_lines, error = _remove_heading_section(
+        original_lines,
+        _QUERY_REFERENCE_MONOLITH_HEADING,
+        _QUERY_SECTION_END,
+        "frozen-v8 query/path/explain",
+    )
+    if error:
+        problems.append(f"[{platform.key}] {error}")
+    if problems:
+        return problems
+
     added = Counter(rendered_lines) - Counter(original_lines)
     removed = Counter(original_lines) - Counter(rendered_lines)
 
-    problems: list[str] = []
     for line in list(added.elements()) + list(removed.elements()):
         if _is_sanctioned_monolith_diff(line):
             continue
@@ -1055,7 +1247,7 @@ def _parse_args(argv: list[str]) -> argparse.Namespace:
     p.add_argument("--check", action="store_true", help="byte-diff render vs committed + expected/, exit 1 on drift")
     p.add_argument("--audit-coverage", action="store_true", help="per host: assert every heading of that host's own v8 body single-homes in its render")
     p.add_argument("--schema-singleton", action="store_true", help="assert the file_type enum is byte-identical everywhere")
-    p.add_argument("--monolith-roundtrip", action="store_true", help="assert each monolith == v8 modulo the enum unification")
+    p.add_argument("--monolith-roundtrip", action="store_true", help="assert each monolith == v8 modulo exact sanctioned blocks/fixes")
     p.add_argument("--always-on-roundtrip", action="store_true", help="assert each always_on/*.md reproduces its former __main__.py constant byte for byte")
     p.add_argument("--bless", action="store_true", help="rewrite expected/ from the current render")
     return p.parse_args(argv)
@@ -1115,7 +1307,7 @@ def main(argv: list[str] | None = None) -> int:
             for m in all_problems:
                 print(f"  {m}", file=sys.stderr)
             return 1
-        print("monolith-roundtrip OK: each monolith matches v8 modulo the enum unification.")
+        print("monolith-roundtrip OK: each monolith matches v8 modulo exact sanctioned blocks/fixes.")
         return 0
 
     if args.always_on_roundtrip:
diff --git a/tools/skillgen/platforms.toml b/tools/skillgen/platforms.toml
index 0856d2269..08a919ceb 100644
--- a/tools/skillgen/platforms.toml
+++ b/tools/skillgen/platforms.toml
@@ -189,8 +189,8 @@ extraction = "verbose"
 
 # Monoliths: rendered inline as a single body, no split, no references/. The
 # render must be diff-clean against the v8 blob in roundtrip_ref except for the
-# file_type enum unification (5-value -> 6-value superset). monolith-roundtrip
-# guards that.
+# exact shared query usage/query-reference blocks and explicitly sanctioned
+# runbook fixes. monolith-roundtrip guards those narrow exceptions.
 
 [platform.aider]
 bucket = "monolith"

From 70ccf41f2ae8d2031a403d5da5b84204226cf3af Mon Sep 17 00:00:00 2001
From: Jeisson <jeissonvargas.acidlabs@latam.com>
Date: Mon, 13 Jul 2026 11:19:51 -0500
Subject: [PATCH 3/3] chore(lock): keep upstream resolution

---
 uv.lock | 212 ++++++++++++++++++++++++++++----------------------------
 1 file changed, 106 insertions(+), 106 deletions(-)

diff --git a/uv.lock b/uv.lock
index 40cbf6c97..088ebbbdc 100644
--- a/uv.lock
+++ b/uv.lock
@@ -97,7 +97,7 @@ name = "autograd"
 version = "1.8.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/67/1c/3c24ec03c8ba4decc742b1df5a10c52f98c84ca8797757f313e7bdcdf276/autograd-1.8.0.tar.gz", hash = "sha256:107374ded5b09fc8643ac925348c0369e7b0e73bbed9565ffd61b8fd04425683", size = 2562146, upload-time = "2025-05-05T12:49:02.502Z" }
 wheels = [
@@ -477,7 +477,7 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/66/54/eb9bfc647b19f2009dd5c7f5ec51c4e6ca831725f1aea7a993034f483147/contourpy-1.3.2.tar.gz", hash = "sha256:b6945942715a034c671b7fc54f9588126b0b8bf23db2696e3ca8328f3ff0ab54", size = 13466130, upload-time = "2025-04-15T17:47:53.79Z" }
 wheels = [
@@ -555,7 +555,7 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/58/01/1253e6698a07380cd31a736d248a3f2a50a7c88779a1813da27503cadc2a/contourpy-1.3.3.tar.gz", hash = "sha256:083e12155b210502d0bca491432bb04d56dc3432f95a979b429f2848c3dbe880", size = 13466174, upload-time = "2025-07-26T12:03:12.549Z" }
@@ -813,10 +813,10 @@ name = "ctranslate2"
 version = "4.7.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" },
-    { name = "pyyaml" },
-    { name = "setuptools" },
+    { name = "pyyaml", marker = "python_full_version >= '3.11'" },
+    { name = "setuptools", marker = "python_full_version >= '3.11'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/cb/e0/b69c40c3d739b213a78d327071240590792071b4f890e34088b03b95bb1e/ctranslate2-4.7.1-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:9017a355dd7c6d29dc3bca6e9fc74827306c61b702c66bb1f6b939655e7de3fa", size = 1255773, upload-time = "2026-02-04T06:11:04.769Z" },
@@ -926,7 +926,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -951,12 +951,12 @@ name = "faster-whisper"
 version = "1.2.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "av" },
-    { name = "ctranslate2" },
-    { name = "huggingface-hub" },
-    { name = "onnxruntime" },
-    { name = "tokenizers" },
-    { name = "tqdm" },
+    { name = "av", marker = "python_full_version >= '3.11'" },
+    { name = "ctranslate2", marker = "python_full_version >= '3.11'" },
+    { name = "huggingface-hub", marker = "python_full_version >= '3.11'" },
+    { name = "onnxruntime", marker = "python_full_version >= '3.11'" },
+    { name = "tokenizers", marker = "python_full_version >= '3.11'" },
+    { name = "tqdm", marker = "python_full_version >= '3.11'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/05/99/49ee85903dee060d9f08297b4a342e5e0bcfca2f027a07b4ee0a38ab13f9/faster_whisper-1.2.1-py3-none-any.whl", hash = "sha256:79a66ad50688c0b794dd501dc340a736992a6342f7f95e5811be60b5224a26a7", size = 1118909, upload-time = "2025-10-31T11:35:47.794Z" },
@@ -1059,10 +1059,10 @@ name = "gensim"
 version = "4.4.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "smart-open" },
+    { name = "smart-open", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/1a/80/fe9d2e1ace968041814dbcfce4e8499a643a36c41267fa4b6c4f54cce420/gensim-4.4.0.tar.gz", hash = "sha256:a3f5b626da5518e79a479140361c663089fe7998df8ba52d56e1ded71ac5bdf5", size = 23260095, upload-time = "2025-10-18T02:06:45.962Z" }
 wheels = [
@@ -1090,7 +1090,7 @@ wheels = [
 
 [[package]]
 name = "graphifyy"
-version = "0.9.14"
+version = "0.9.6"
 source = { editable = "." }
 dependencies = [
     { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
@@ -1357,26 +1357,26 @@ name = "graspologic"
 version = "3.4.4"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "anytree" },
-    { name = "beartype" },
-    { name = "future" },
-    { name = "gensim" },
-    { name = "graspologic-native" },
-    { name = "hyppo" },
-    { name = "joblib" },
-    { name = "matplotlib" },
-    { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "anytree", marker = "python_full_version < '3.13'" },
+    { name = "beartype", marker = "python_full_version < '3.13'" },
+    { name = "future", marker = "python_full_version < '3.13'" },
+    { name = "gensim", marker = "python_full_version < '3.13'" },
+    { name = "graspologic-native", marker = "python_full_version < '3.13'" },
+    { name = "hyppo", marker = "python_full_version < '3.13'" },
+    { name = "joblib", marker = "python_full_version < '3.13'" },
+    { name = "matplotlib", marker = "python_full_version < '3.13'" },
+    { name = "networkx", version = "3.4.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "networkx", version = "3.6.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "pot" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "pot", marker = "python_full_version < '3.13'" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "seaborn" },
-    { name = "statsmodels" },
-    { name = "typing-extensions" },
-    { name = "umap-learn" },
+    { name = "seaborn", marker = "python_full_version < '3.13'" },
+    { name = "statsmodels", marker = "python_full_version < '3.13'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+    { name = "umap-learn", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/91/bb/0fe2ef85ea775e7b8416b2cf90097aa4b5e0c9c2271d7fe6789bab27d0ca/graspologic-3.4.4.tar.gz", hash = "sha256:79878caf367da3e89046a4ec94291c5b1a5da569f19fdd879d8b45c3563d7110", size = 5134258, upload-time = "2025-09-08T21:44:01.969Z" }
 wheels = [
@@ -1478,15 +1478,15 @@ name = "huggingface-hub"
 version = "1.15.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "filelock" },
-    { name = "fsspec" },
-    { name = "hf-xet", marker = "platform_machine == 'AMD64' or platform_machine == 'aarch64' or platform_machine == 'amd64' or platform_machine == 'arm64' or platform_machine == 'x86_64'" },
-    { name = "httpx" },
-    { name = "packaging" },
-    { name = "pyyaml" },
-    { name = "tqdm" },
-    { name = "typer" },
-    { name = "typing-extensions" },
+    { name = "filelock", marker = "python_full_version >= '3.11'" },
+    { name = "fsspec", marker = "python_full_version >= '3.11'" },
+    { name = "hf-xet", marker = "(python_full_version >= '3.11' and platform_machine == 'AMD64') or (python_full_version >= '3.11' and platform_machine == 'aarch64') or (python_full_version >= '3.11' and platform_machine == 'amd64') or (python_full_version >= '3.11' and platform_machine == 'arm64') or (python_full_version >= '3.11' and platform_machine == 'x86_64')" },
+    { name = "httpx", marker = "python_full_version >= '3.11'" },
+    { name = "packaging", marker = "python_full_version >= '3.11'" },
+    { name = "pyyaml", marker = "python_full_version >= '3.11'" },
+    { name = "tqdm", marker = "python_full_version >= '3.11'" },
+    { name = "typer", marker = "python_full_version >= '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version >= '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/bb/b6/e22bd20a25299c34b8c5922c1545a6320825b13906eb0f7298edfd034a0b/huggingface_hub-1.15.0.tar.gz", hash = "sha256:28abfdddda3927fd4de6a63cf26ab012498a2c24dae52baf150c5c6edf98a1d5", size = 784100, upload-time = "2026-05-15T11:42:52.149Z" }
 wheels = [
@@ -1511,18 +1511,18 @@ name = "hyppo"
 version = "0.5.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "autograd" },
-    { name = "future" },
-    { name = "numba" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "autograd", marker = "python_full_version < '3.13'" },
+    { name = "future", marker = "python_full_version < '3.13'" },
+    { name = "numba", marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "patsy" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "patsy", marker = "python_full_version < '3.13'" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "statsmodels" },
+    { name = "statsmodels", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/dd/a6/0d84fe8486a1447da8bdb8ebb249d525fd8c1d0fe038bceb003c6e0513f9/hyppo-0.5.2.tar.gz", hash = "sha256:4634d15516248a43d25c241ed18beeb79bb3210360f7253693b3f154fe8c9879", size = 125115, upload-time = "2025-05-24T18:33:27.418Z" }
 wheels = [
@@ -1552,7 +1552,7 @@ name = "importlib-metadata"
 version = "9.0.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "zipp" },
+    { name = "zipp", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/a9/01/15bb152d77b21318514a96f43af312635eb2500c96b55398d020c93d86ea/importlib_metadata-9.0.0.tar.gz", hash = "sha256:a4f57ab599e6a2e3016d7595cfd72eb4661a5106e787a95bcc90c7105b831efc", size = 56405, upload-time = "2026-03-20T06:42:56.999Z" }
 wheels = [
@@ -2279,8 +2279,8 @@ name = "numba"
 version = "0.65.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "llvmlite" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "llvmlite", marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/f6/c5/db2ac3685833d626c0dcae6bd2330cd68433e1fd248d15f70998160d3ad7/numba-0.65.1.tar.gz", hash = "sha256:19357146c32fe9ed25059ab915e8465fb13951cf6b0aace3826b76886373ab23", size = 2765600, upload-time = "2026-04-24T02:02:56.551Z" }
 wheels = [
@@ -2440,11 +2440,11 @@ name = "onnxruntime"
 version = "1.26.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "flatbuffers" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "flatbuffers", marker = "python_full_version >= '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
     { name = "numpy", version = "2.4.6", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.13'" },
-    { name = "packaging" },
-    { name = "protobuf" },
+    { name = "packaging", marker = "python_full_version >= '3.11'" },
+    { name = "protobuf", marker = "python_full_version >= '3.11'" },
 ]
 wheels = [
     { url = "https://files.pythonhosted.org/packages/d4/81/29a9eb470994a75eb7b3ccf32be314d7c66675a00ac7b50294816cc2db27/onnxruntime-1.26.0-cp311-cp311-macosx_14_0_arm64.whl", hash = "sha256:ee1109ef4ef27cad90e823399e61e03b3c6c7bfe0fb820b4baf3678c15be8b3c", size = 18005108, upload-time = "2026-05-08T19:08:11.728Z" },
@@ -2530,10 +2530,10 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "python-dateutil" },
-    { name = "pytz" },
-    { name = "tzdata" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "python-dateutil", marker = "python_full_version < '3.11'" },
+    { name = "pytz", marker = "python_full_version < '3.11'" },
+    { name = "tzdata", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/33/01/d40b85317f86cf08d853a4f495195c73815fdf205eef3993821720274518/pandas-2.3.3.tar.gz", hash = "sha256:e05e1af93b977f7eafa636d043f9f94c7ee3ac81af99c13508215942e64c993b", size = 4495223, upload-time = "2025-09-29T23:34:51.853Z" }
 wheels = [
@@ -2596,9 +2596,9 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "python-dateutil" },
-    { name = "tzdata", marker = "sys_platform == 'emscripten' or sys_platform == 'win32'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "python-dateutil", marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "tzdata", marker = "(python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform == 'emscripten') or (python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform == 'win32')" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/f8/87/4341c6252d1c47b08768c3d25ac487362bf403f0313ddae4a2a26c9b1b4c/pandas-3.0.3.tar.gz", hash = "sha256:696a4a00a2a2a35d4e5deb3fc946641b96c944f02230e4f76137fe35d806c4fc", size = 4651414, upload-time = "2026-05-11T18:54:29.21Z" }
 wheels = [
@@ -2672,7 +2672,7 @@ name = "patsy"
 version = "1.0.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/be/44/ed13eccdd0519eff265f44b670d46fbb0ec813e2274932dc1c0e48520f7d/patsy-1.0.2.tar.gz", hash = "sha256:cdc995455f6233e90e22de72c37fcadb344e7586fb83f06696f54d92f8ce74c0", size = 399942, upload-time = "2025-10-20T16:17:37.535Z" }
 wheels = [
@@ -2855,8 +2855,8 @@ name = "pot"
 version = "0.9.6.post1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/42/8b/5f939eaf1fbeb7ff914fe540d659486951a056e5537b8f454362045b6c72/pot-0.9.6.post1.tar.gz", hash = "sha256:9b6cc14a8daecfe1268268168cf46548f9130976b22b24a9e8ec62a734be6c43", size = 604243, upload-time = "2025-09-22T12:51:14.894Z" }
@@ -3199,12 +3199,12 @@ name = "pynndescent"
 version = "0.6.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "joblib" },
-    { name = "llvmlite" },
-    { name = "numba" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "joblib", marker = "python_full_version < '3.13'" },
+    { name = "llvmlite", marker = "python_full_version < '3.13'" },
+    { name = "numba", marker = "python_full_version < '3.13'" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/4a/fb/7f58c397fb31666756457ee2ac4c0289ef2daad57f4ae4be8dec12f80b03/pynndescent-0.6.0.tar.gz", hash = "sha256:7ffde0fb5b400741e055a9f7d377e3702e02250616834231f6c209e39aac24f5", size = 2992987, upload-time = "2026-01-08T21:29:58.943Z" }
@@ -3870,10 +3870,10 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "joblib" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" } },
-    { name = "threadpoolctl" },
+    { name = "joblib", marker = "python_full_version < '3.11'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
+    { name = "threadpoolctl", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/98/c2/a7855e41c9d285dfe86dc50b250978105dce513d6e459ea66a6aeb0e1e0c/scikit_learn-1.7.2.tar.gz", hash = "sha256:20e9e49ecd130598f1ca38a1d85090e1a600147b9c02fa6f15d69cb53d968fda", size = 7193136, upload-time = "2025-09-09T08:21:29.075Z" }
 wheels = [
@@ -3919,10 +3919,10 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "joblib" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" } },
-    { name = "threadpoolctl" },
+    { name = "joblib", marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
+    { name = "threadpoolctl", marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0e/d4/40988bf3b8e34feec1d0e6a051446b1f66225f8529b9309becaeef62b6c4/scikit_learn-1.8.0.tar.gz", hash = "sha256:9bccbb3b40e3de10351f8f5068e105d0f4083b1a65fa07b6634fbc401a6287fd", size = 7335585, upload-time = "2025-12-10T07:08:53.618Z" }
 wheels = [
@@ -3972,7 +3972,7 @@ resolution-markers = [
     "python_full_version < '3.11'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0f/37/6964b830433e654ec7485e45a00fc9a27cf868d622838f6b6d9c5ec0d532/scipy-1.15.3.tar.gz", hash = "sha256:eae3cf522bc7df64b42cad3925c876e1b0b6c35c1337c93e12c0f366f55b0eaf", size = 59419214, upload-time = "2025-05-08T16:13:05.955Z" }
 wheels = [
@@ -4033,7 +4033,7 @@ resolution-markers = [
     "python_full_version >= '3.11' and python_full_version < '3.13' and sys_platform != 'emscripten' and sys_platform != 'win32'",
 ]
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/7a/97/5a3609c4f8d58b039179648e62dd220f89864f56f7357f5d4f45c29eb2cc/scipy-1.17.1.tar.gz", hash = "sha256:95d8e012d8cb8816c226aef832200b1d45109ed4464303e997c5b13122b297c0", size = 30573822, upload-time = "2026-02-23T00:26:24.851Z" }
 wheels = [
@@ -4104,9 +4104,9 @@ name = "seaborn"
 version = "0.13.2"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "matplotlib" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "matplotlib", marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/86/59/a451d7420a77ab0b98f7affa3a1d78a313d2f7281a57afb1a34bae8ab412/seaborn-0.13.2.tar.gz", hash = "sha256:93e60a40988f4d65e9f4885df477e2fdaff6b73a9ded434c1ab356dd57eefff7", size = 1457696, upload-time = "2024-01-25T13:21:52.551Z" }
@@ -4146,7 +4146,7 @@ name = "smart-open"
 version = "7.6.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "wrapt" },
+    { name = "wrapt", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/c5/65/3ada667d32675399001bf022ad3d9f3989b57101351ebc71d6fbe2384634/smart_open-7.6.1.tar.gz", hash = "sha256:4347996e7ba21db7cd1e059632e0b30395407e4f6c660d2ddffc8f2a9ae5f990", size = 54754, upload-time = "2026-05-09T06:23:37.06Z" }
 wheels = [
@@ -4211,12 +4211,12 @@ name = "statsmodels"
 version = "0.14.6"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "packaging" },
-    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "packaging", marker = "python_full_version < '3.13'" },
+    { name = "pandas", version = "2.3.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "pandas", version = "3.0.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "patsy" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "patsy", marker = "python_full_version < '3.13'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/0d/81/e8d74b34f85285f7335d30c5e3c2d7c0346997af9f3debf9a0a9a63de184/statsmodels-0.14.6.tar.gz", hash = "sha256:4d17873d3e607d398b85126cd4ed7aad89e4e9d89fc744cdab1af3189a996c2a", size = 20689085, upload-time = "2025-12-05T23:08:39.522Z" }
@@ -4337,7 +4337,7 @@ name = "tokenizers"
 version = "0.23.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "huggingface-hub" },
+    { name = "huggingface-hub", marker = "python_full_version >= '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/c1/60/21f715d9faba5f5407ff759472ade058ec4a507ad62bcea47cb847239a73/tokenizers-0.23.1.tar.gz", hash = "sha256:1feeeadf865a7915adc25445dea30e9933e593c31bb96c277cee36de227c8bfa", size = 365748, upload-time = "2026-04-27T14:43:25.606Z" }
 wheels = [
@@ -4928,10 +4928,10 @@ name = "typer"
 version = "0.25.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "annotated-doc" },
-    { name = "click" },
-    { name = "rich" },
-    { name = "shellingham" },
+    { name = "annotated-doc", marker = "python_full_version >= '3.11'" },
+    { name = "click", marker = "python_full_version >= '3.11'" },
+    { name = "rich", marker = "python_full_version >= '3.11'" },
+    { name = "shellingham", marker = "python_full_version >= '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/e4/51/9aed62104cea109b820bbd6c14245af756112017d309da813ef107d42e7e/typer-0.25.1.tar.gz", hash = "sha256:9616eb8853a09ffeabab1698952f33c6f29ffdbceb4eaeecf571880e8d7664cc", size = 122276, upload-time = "2026-04-30T19:32:16.964Z" }
 wheels = [
@@ -4973,14 +4973,14 @@ name = "umap-learn"
 version = "0.5.12"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "numba" },
-    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" } },
-    { name = "pynndescent" },
-    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "numba", marker = "python_full_version < '3.13'" },
+    { name = "numpy", version = "1.26.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" },
+    { name = "pynndescent", marker = "python_full_version < '3.13'" },
+    { name = "scikit-learn", version = "1.7.2", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scikit-learn", version = "1.8.0", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11' or python_full_version >= '3.13'" },
+    { name = "scipy", version = "1.15.3", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.11'" },
     { name = "scipy", version = "1.17.1", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version >= '3.11' and python_full_version < '3.13'" },
-    { name = "tqdm" },
+    { name = "tqdm", marker = "python_full_version < '3.13'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/02/ee/af4171241117f85c74b5ca6448ea1033cc28d599c13651d67289bacd4083/umap_learn-0.5.12.tar.gz", hash = "sha256:6aff02ecac5f2aad9f3c65ee518d7ae93e1a985ae38721fdcffceee4232c33c7", size = 96672, upload-time = "2026-04-08T20:03:54.012Z" }
 wheels = [
@@ -5001,8 +5001,8 @@ name = "uvicorn"
 version = "0.47.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "click" },
-    { name = "h11" },
+    { name = "click", marker = "python_full_version < '3.11' or sys_platform != 'emscripten'" },
+    { name = "h11", marker = "python_full_version < '3.11' or sys_platform != 'emscripten'" },
     { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/f6/b1/8e7077a8641086aea449e1b5752a570f1b5906c64e0a33cd6d93b63a066b/uvicorn-0.47.0.tar.gz", hash = "sha256:7c9a0ea1a9414106bbab7324609c162d8fa0cdcdcb703060987269d77c7bb533", size = 90582, upload-time = "2026-05-14T18:16:54.455Z" }