From dc26423820d3fc6e300256a9ae76b7acb6d6af6e Mon Sep 17 00:00:00 2001
From: freezingflamecode <274730460+freezingflamecode@users.noreply.github.com>
Date: Thu, 9 Apr 2026 09:25:05 -0700
Subject: [PATCH] =?UTF-8?q?feat:=20add=20--directed=20flag=20to=20preserve?=
 =?UTF-8?q?=20edge=20direction=20(source=E2=86=92target)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Undirected graphs store edges in arbitrary order, causing 60% of arrows
in HTML visualization to point the wrong way. This adds an opt-in
--directed flag that builds a DiGraph, preserving call/import direction.

Default remains undirected for backward compatibility. Louvain/Leiden
community detection converts to undirected internally as required.

Includes worked example with A/B test evidence (worked/directed-graph/).
---
 README.md                       |  1 +
 graphify/analyze.py             |  4 +++-
 graphify/build.py               | 19 +++++++++++-----
 graphify/cluster.py             | 25 +++++++++++++--------
 graphify/export.py              |  7 +++---
 graphify/skill-claw.md          | 23 ++++++++++---------
 graphify/skill-codex.md         | 23 ++++++++++---------
 graphify/skill-droid.md         | 23 ++++++++++---------
 graphify/skill-opencode.md      | 23 ++++++++++---------
 graphify/skill-trae.md          | 23 ++++++++++---------
 graphify/skill-windows.md       | 23 ++++++++++---------
 graphify/skill.md               | 23 ++++++++++---------
 graphify/watch.py               |  5 +++--
 worked/directed-graph/review.md | 39 +++++++++++++++++++++++++++++++++
 14 files changed, 170 insertions(+), 91 deletions(-)
 create mode 100644 worked/directed-graph/review.md

diff --git a/README.md b/README.md
index 6423a8774..a1d5a773b 100644
--- a/README.md
+++ b/README.md
@@ -171,6 +171,7 @@ When the user types `/graphify`, invoke the Skill tool with `skill: "graphify"`
 /graphify ./raw                    # run on a specific folder
 /graphify ./raw --mode deep        # more aggressive INFERRED edge extraction
 /graphify ./raw --update           # re-extract only changed files, merge into existing graph
+/graphify ./raw --directed          # build directed graph (preserves edge direction: source→target)
 /graphify ./raw --cluster-only     # rerun clustering on existing graph, no re-extraction
 /graphify ./raw --no-viz           # skip HTML, just produce report + JSON
 /graphify ./raw --obsidian                          # also generate Obsidian vault (opt-in)
diff --git a/graphify/analyze.py b/graphify/analyze.py
index 50f85acaf..1da426bde 100644
--- a/graphify/analyze.py
+++ b/graphify/analyze.py
@@ -468,7 +468,9 @@ def graph_diff(G_old: nx.Graph, G_new: nx.Graph) -> dict:
         for n in removed_node_ids
     ]
 
-    def edge_key(G: nx.Graph, u: str, v: str, data: dict) -> tuple:
+    def edge_key(G: nx.Graph | nx.DiGraph, u: str, v: str, data: dict) -> tuple:
+        if G.is_directed():
+            return (u, v, data.get("relation", ""))
         return (min(u, v), max(u, v), data.get("relation", ""))
 
     old_edge_keys = {
diff --git a/graphify/build.py b/graphify/build.py
index 1bcb51b17..4e49cfbd8 100644
--- a/graphify/build.py
+++ b/graphify/build.py
@@ -26,13 +26,18 @@
 from .validate import validate_extraction
 
 
-def build_from_json(extraction: dict) -> nx.Graph:
+def build_from_json(extraction: dict, *, directed: bool = False) -> nx.Graph | nx.DiGraph:
+    """Build a NetworkX graph from an extraction dict.
+
+    directed=True produces a DiGraph that preserves edge direction (source→target).
+    directed=False (default) produces an undirected Graph for backward compatibility.
+    """
     errors = validate_extraction(extraction)
     # Dangling edges (stdlib/external imports) are expected - only warn about real schema errors.
     real_errors = [e for e in errors if "does not match any node id" not in e]
     if real_errors:
         print(f"[graphify] Extraction warning ({len(real_errors)} issues): {real_errors[0]}", file=sys.stderr)
-    G = nx.Graph()
+    G = nx.DiGraph() if directed else nx.Graph()
     for node in extraction.get("nodes", []):
         G.add_node(node["id"], **{k: v for k, v in node.items() if k != "id"})
     node_set = set(G.nodes())
@@ -41,8 +46,7 @@ def build_from_json(extraction: dict) -> nx.Graph:
         if src not in node_set or tgt not in node_set:
             continue  # skip edges to external/stdlib nodes - expected, not an error
         attrs = {k: v for k, v in edge.items() if k not in ("source", "target")}
-        # Preserve original edge direction - undirected graphs lose it otherwise,
-        # causing display functions to show edges backwards.
+        # _src/_tgt kept for backward compatibility with existing consumers.
         attrs["_src"] = src
         attrs["_tgt"] = tgt
         G.add_edge(src, tgt, **attrs)
@@ -52,9 +56,12 @@ def build_from_json(extraction: dict) -> nx.Graph:
     return G
 
 
-def build(extractions: list[dict]) -> nx.Graph:
+def build(extractions: list[dict], *, directed: bool = False) -> nx.Graph | nx.DiGraph:
     """Merge multiple extraction results into one graph.
 
+    directed=True produces a DiGraph that preserves edge direction (source→target).
+    directed=False (default) produces an undirected Graph for backward compatibility.
+
     Extractions are merged in order. For nodes with the same ID, the last
     extraction's attributes win (NetworkX add_node overwrites). Pass AST
     results before semantic results so semantic labels take precedence, or
@@ -67,4 +74,4 @@ def build(extractions: list[dict]) -> nx.Graph:
         combined["hyperedges"].extend(ext.get("hyperedges", []))
         combined["input_tokens"] += ext.get("input_tokens", 0)
         combined["output_tokens"] += ext.get("output_tokens", 0)
-    return build_from_json(combined)
+    return build_from_json(combined, directed=directed)
diff --git a/graphify/cluster.py b/graphify/cluster.py
index 363d555c8..328381631 100644
--- a/graphify/cluster.py
+++ b/graphify/cluster.py
@@ -56,22 +56,28 @@ def _partition(G: nx.Graph) -> dict[str, int]:
 _MIN_SPLIT_SIZE = 10             # only split if community has at least this many nodes
 
 
-def cluster(G: nx.Graph) -> dict[int, list[str]]:
+def cluster(G: nx.Graph | nx.DiGraph) -> dict[int, list[str]]:
     """Run Leiden community detection. Returns {community_id: [node_ids]}.
 
     Community IDs are stable across runs: 0 = largest community after splitting.
     Oversized communities (> 25% of graph nodes, min 10) are split by running
     a second Leiden pass on the subgraph.
+
+    Accepts directed or undirected graphs. Directed graphs are converted to
+    undirected internally since Louvain/Leiden require undirected input.
     """
     if G.number_of_nodes() == 0:
         return {}
     if G.number_of_edges() == 0:
         return {i: [n] for i, n in enumerate(sorted(G.nodes))}
 
+    # Louvain/Leiden require undirected graphs
+    G_undirected = G.to_undirected() if G.is_directed() else G
+
     # Leiden warns and drops isolates - handle them separately
-    isolates = [n for n in G.nodes() if G.degree(n) == 0]
-    connected_nodes = [n for n in G.nodes() if G.degree(n) > 0]
-    connected = G.subgraph(connected_nodes)
+    isolates = [n for n in G_undirected.nodes() if G_undirected.degree(n) == 0]
+    connected_nodes = [n for n in G_undirected.nodes() if G_undirected.degree(n) > 0]
+    connected = G_undirected.subgraph(connected_nodes)
 
     raw: dict[int, list[str]] = {}
     if connected.number_of_nodes() > 0:
@@ -85,12 +91,12 @@ def cluster(G: nx.Graph) -> dict[int, list[str]]:
         raw[next_cid] = [node]
         next_cid += 1
 
-    # Split oversized communities
-    max_size = max(_MIN_SPLIT_SIZE, int(G.number_of_nodes() * _MAX_COMMUNITY_FRACTION))
+    # Split oversized communities (use undirected for Leiden compatibility)
+    max_size = max(_MIN_SPLIT_SIZE, int(G_undirected.number_of_nodes() * _MAX_COMMUNITY_FRACTION))
     final_communities: list[list[str]] = []
     for nodes in raw.values():
         if len(nodes) > max_size:
-            final_communities.extend(_split_community(G, nodes))
+            final_communities.extend(_split_community(G_undirected, nodes))
         else:
             final_communities.append(nodes)
 
@@ -117,14 +123,15 @@ def _split_community(G: nx.Graph, nodes: list[str]) -> list[list[str]]:
         return [sorted(nodes)]
 
 
-def cohesion_score(G: nx.Graph, community_nodes: list[str]) -> float:
+def cohesion_score(G: nx.Graph | nx.DiGraph, community_nodes: list[str]) -> float:
     """Ratio of actual intra-community edges to maximum possible."""
     n = len(community_nodes)
     if n <= 1:
         return 1.0
     subgraph = G.subgraph(community_nodes)
     actual = subgraph.number_of_edges()
-    possible = n * (n - 1) / 2
+    # Directed: max edges = n*(n-1); undirected: n*(n-1)/2
+    possible = n * (n - 1) if G.is_directed() else n * (n - 1) / 2
     return round(actual / possible, 2) if possible > 0 else 0.0
 
 
diff --git a/graphify/export.py b/graphify/export.py
index 16271a730..affeaa004 100644
--- a/graphify/export.py
+++ b/graphify/export.py
@@ -104,8 +104,9 @@ def _hyperedge_script(hyperedges_json: str) -> str:
 </script>"""
 
 
-def _html_script(nodes_json: str, edges_json: str, legend_json: str) -> str:
+def _html_script(nodes_json: str, edges_json: str, legend_json: str, *, directed: bool = False) -> str:
     return f"""<script>
+const GRAPH_IS_DIRECTED = {'true' if directed else 'false'};
 const RAW_NODES = {nodes_json};
 const RAW_EDGES = {edges_json};
 const LEGEND = {legend_json};
@@ -130,7 +131,7 @@ def _html_script(nodes_json: str, edges_json: str, legend_json: str) -> str:
   dashes: e.dashes,
   width: e.width,
   color: e.color,
-  arrows: {{ to: {{ enabled: true, scaleFactor: 0.5 }} }},
+  arrows: {{ to: {{ enabled: GRAPH_IS_DIRECTED, scaleFactor: 0.5 }} }},
 }})));
 
 const container = document.getElementById('graph');
@@ -425,7 +426,7 @@ def to_html(
   </div>
   <div id="stats">{stats}</div>
 </div>
-{_html_script(nodes_json, edges_json, legend_json)}
+{_html_script(nodes_json, edges_json, legend_json, directed=G.is_directed())}
 {_hyperedge_script(hyperedges_json)}
 </body>
 </html>"""
diff --git a/graphify/skill-claw.md b/graphify/skill-claw.md
index eb3409526..d92a50df4 100644
--- a/graphify/skill-claw.md
+++ b/graphify/skill-claw.md
@@ -15,6 +15,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify <path>                                      # full pipeline on specific path
 /graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
 /graphify <path> --update                             # incremental - re-extract only new/changed files
+/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
 /graphify <path> --cluster-only                       # rerun clustering on existing graph
 /graphify <path> --no-viz                             # skip visualization, just report + JSON
 /graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
@@ -110,6 +111,8 @@ Then act on it:
 
 **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it.
 
+Also note whether `--directed` was given. If it was, set `DIRECTED=True` and pass `directed=DIRECTED` to every `build_from_json()` call. Directed graphs preserve edge direction (source→target), producing arrows in the HTML visualization and `"directed": true` in graph.json.
+
 This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (Claude, costs tokens).
 
 **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**
@@ -302,7 +305,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = cluster(G)
 cohesion = score_all(G, communities)
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -355,7 +358,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -393,7 +396,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
@@ -424,7 +427,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -447,7 +450,7 @@ from graphify.build import build_from_json
 from graphify.export import to_cypher
 from pathlib import Path
 
-G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()))
+G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()), directed=DIRECTED)
 to_cypher(G, 'graphify-out/cypher.txt')
 print('cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt')
 "
@@ -465,7 +468,7 @@ from pathlib import Path
 
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 result = push_to_neo4j(G, uri='NEO4J_URI', user='NEO4J_USER', password='NEO4J_PASSWORD', communities=communities)
@@ -488,7 +491,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -509,7 +512,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 to_graphml(G, communities, 'graphify-out/graph.graphml')
@@ -685,7 +688,7 @@ G_existing = json_graph.node_link_graph(existing_data, edges='links')
 
 # Load new extraction
 new_extraction = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extraction)
+G_new = build_from_json(new_extraction, directed=DIRECTED)
 
 # Merge: new nodes/edges into existing graph
 G_existing.update(G_new)
@@ -709,7 +712,7 @@ from pathlib import Path
 # Load old graph (before update) from backup written before merge
 old_data = json.loads(Path('.graphify_old.json').read_text()) if Path('.graphify_old.json').exists() else None
 new_extract = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extract)
+G_new = build_from_json(new_extract, directed=DIRECTED)
 
 if old_data:
     G_old = json_graph.node_link_graph(old_data, edges='links')
diff --git a/graphify/skill-codex.md b/graphify/skill-codex.md
index 12f17c480..9c2893817 100644
--- a/graphify/skill-codex.md
+++ b/graphify/skill-codex.md
@@ -15,6 +15,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify <path>                                      # full pipeline on specific path
 /graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
 /graphify <path> --update                             # incremental - re-extract only new/changed files
+/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
 /graphify <path> --cluster-only                       # rerun clustering on existing graph
 /graphify <path> --no-viz                             # skip visualization, just report + JSON
 /graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
@@ -109,6 +110,8 @@ Then act on it:
 
 **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it.
 
+Also note whether `--directed` was given. If it was, set `DIRECTED=True` and pass `directed=DIRECTED` to every `build_from_json()` call. Directed graphs preserve edge direction (source→target), producing arrows in the HTML visualization and `"directed": true` in graph.json.
+
 This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (Claude, costs tokens).
 
 **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**
@@ -358,7 +361,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = cluster(G)
 cohesion = score_all(G, communities)
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -411,7 +414,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -449,7 +452,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
@@ -480,7 +483,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -503,7 +506,7 @@ from graphify.build import build_from_json
 from graphify.export import to_cypher
 from pathlib import Path
 
-G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()))
+G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()), directed=DIRECTED)
 to_cypher(G, 'graphify-out/cypher.txt')
 print('cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt')
 "
@@ -521,7 +524,7 @@ from pathlib import Path
 
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 result = push_to_neo4j(G, uri='NEO4J_URI', user='NEO4J_USER', password='NEO4J_PASSWORD', communities=communities)
@@ -544,7 +547,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -565,7 +568,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 to_graphml(G, communities, 'graphify-out/graph.graphml')
@@ -741,7 +744,7 @@ G_existing = json_graph.node_link_graph(existing_data, edges='links')
 
 # Load new extraction
 new_extraction = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extraction)
+G_new = build_from_json(new_extraction, directed=DIRECTED)
 
 # Merge: new nodes/edges into existing graph
 G_existing.update(G_new)
@@ -765,7 +768,7 @@ from pathlib import Path
 # Load old graph (before update) from backup written before merge
 old_data = json.loads(Path('.graphify_old.json').read_text()) if Path('.graphify_old.json').exists() else None
 new_extract = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extract)
+G_new = build_from_json(new_extract, directed=DIRECTED)
 
 if old_data:
     G_old = json_graph.node_link_graph(old_data, edges='links')
diff --git a/graphify/skill-droid.md b/graphify/skill-droid.md
index 42647e66c..54d60ea72 100644
--- a/graphify/skill-droid.md
+++ b/graphify/skill-droid.md
@@ -15,6 +15,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify <path>                                      # full pipeline on specific path
 /graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
 /graphify <path> --update                             # incremental - re-extract only new/changed files
+/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
 /graphify <path> --cluster-only                       # rerun clustering on existing graph
 /graphify <path> --no-viz                             # skip visualization, just report + JSON
 /graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
@@ -110,6 +111,8 @@ Then act on it:
 
 **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it.
 
+Also note whether `--directed` was given. If it was, set `DIRECTED=True` and pass `directed=DIRECTED` to every `build_from_json()` call. Directed graphs preserve edge direction (source→target), producing arrows in the HTML visualization and `"directed": true` in graph.json.
+
 This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (Claude, costs tokens).
 
 **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**
@@ -355,7 +358,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = cluster(G)
 cohesion = score_all(G, communities)
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -408,7 +411,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -446,7 +449,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
@@ -477,7 +480,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -500,7 +503,7 @@ from graphify.build import build_from_json
 from graphify.export import to_cypher
 from pathlib import Path
 
-G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()))
+G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()), directed=DIRECTED)
 to_cypher(G, 'graphify-out/cypher.txt')
 print('cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt')
 "
@@ -518,7 +521,7 @@ from pathlib import Path
 
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 result = push_to_neo4j(G, uri='NEO4J_URI', user='NEO4J_USER', password='NEO4J_PASSWORD', communities=communities)
@@ -541,7 +544,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -562,7 +565,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 to_graphml(G, communities, 'graphify-out/graph.graphml')
@@ -738,7 +741,7 @@ G_existing = json_graph.node_link_graph(existing_data, edges='links')
 
 # Load new extraction
 new_extraction = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extraction)
+G_new = build_from_json(new_extraction, directed=DIRECTED)
 
 # Merge: new nodes/edges into existing graph
 G_existing.update(G_new)
@@ -762,7 +765,7 @@ from pathlib import Path
 # Load old graph (before update) from backup written before merge
 old_data = json.loads(Path('.graphify_old.json').read_text()) if Path('.graphify_old.json').exists() else None
 new_extract = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extract)
+G_new = build_from_json(new_extract, directed=DIRECTED)
 
 if old_data:
     G_old = json_graph.node_link_graph(old_data, edges='links')
diff --git a/graphify/skill-opencode.md b/graphify/skill-opencode.md
index 1f07cca71..7aced2821 100644
--- a/graphify/skill-opencode.md
+++ b/graphify/skill-opencode.md
@@ -15,6 +15,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify <path>                                      # full pipeline on specific path
 /graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
 /graphify <path> --update                             # incremental - re-extract only new/changed files
+/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
 /graphify <path> --cluster-only                       # rerun clustering on existing graph
 /graphify <path> --no-viz                             # skip visualization, just report + JSON
 /graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
@@ -110,6 +111,8 @@ Then act on it:
 
 **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it.
 
+Also note whether `--directed` was given. If it was, set `DIRECTED=True` and pass `directed=DIRECTED` to every `build_from_json()` call. Directed graphs preserve edge direction (source→target), producing arrows in the HTML visualization and `"directed": true` in graph.json.
+
 This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (Claude, costs tokens).
 
 **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**
@@ -354,7 +357,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = cluster(G)
 cohesion = score_all(G, communities)
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -407,7 +410,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -445,7 +448,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
@@ -476,7 +479,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -499,7 +502,7 @@ from graphify.build import build_from_json
 from graphify.export import to_cypher
 from pathlib import Path
 
-G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()))
+G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()), directed=DIRECTED)
 to_cypher(G, 'graphify-out/cypher.txt')
 print('cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt')
 "
@@ -517,7 +520,7 @@ from pathlib import Path
 
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 result = push_to_neo4j(G, uri='NEO4J_URI', user='NEO4J_USER', password='NEO4J_PASSWORD', communities=communities)
@@ -540,7 +543,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -561,7 +564,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 to_graphml(G, communities, 'graphify-out/graph.graphml')
@@ -737,7 +740,7 @@ G_existing = json_graph.node_link_graph(existing_data, edges='links')
 
 # Load new extraction
 new_extraction = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extraction)
+G_new = build_from_json(new_extraction, directed=DIRECTED)
 
 # Merge: new nodes/edges into existing graph
 G_existing.update(G_new)
@@ -761,7 +764,7 @@ from pathlib import Path
 # Load old graph (before update) from backup written before merge
 old_data = json.loads(Path('.graphify_old.json').read_text()) if Path('.graphify_old.json').exists() else None
 new_extract = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extract)
+G_new = build_from_json(new_extract, directed=DIRECTED)
 
 if old_data:
     G_old = json_graph.node_link_graph(old_data, edges='links')
diff --git a/graphify/skill-trae.md b/graphify/skill-trae.md
index c0cfffb9e..12b2aebf1 100644
--- a/graphify/skill-trae.md
+++ b/graphify/skill-trae.md
@@ -15,6 +15,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify <path>                                      # full pipeline on specific path
 /graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
 /graphify <path> --update                             # incremental - re-extract only new/changed files
+/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
 /graphify <path> --cluster-only                       # rerun clustering on existing graph
 /graphify <path> --no-viz                             # skip visualization, just report + JSON
 /graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
@@ -109,6 +110,8 @@ Then act on it:
 
 **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it.
 
+Also note whether `--directed` was given. If it was, set `DIRECTED=True` and pass `directed=DIRECTED` to every `build_from_json()` call. Directed graphs preserve edge direction (source→target), producing arrows in the HTML visualization and `"directed": true` in graph.json.
+
 This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (LLM, costs tokens).
 
 **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**
@@ -350,7 +353,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = cluster(G)
 cohesion = score_all(G, communities)
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -402,7 +405,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -438,7 +441,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
@@ -469,7 +472,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -492,7 +495,7 @@ from graphify.build import build_from_json
 from graphify.export import to_cypher
 from pathlib import Path
 
-G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()))
+G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()), directed=DIRECTED)
 to_cypher(G, 'graphify-out/cypher.txt')
 print('cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt')
 "
@@ -510,7 +513,7 @@ from pathlib import Path
 
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 result = push_to_neo4j(G, uri='NEO4J_URI', user='NEO4J_USER', password='NEO4J_PASSWORD', communities=communities)
@@ -533,7 +536,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -554,7 +557,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 to_graphml(G, communities, 'graphify-out/graph.graphml')
@@ -714,7 +717,7 @@ existing_data = json.loads(Path('graphify-out/graph.json').read_text())
 G_existing = json_graph.node_link_graph(existing_data, edges='links')
 
 new_extraction = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extraction)
+G_new = build_from_json(new_extraction, directed=DIRECTED)
 
 G_existing.update(G_new)
 print(f'Merged: {G_existing.number_of_nodes()} nodes, {G_existing.number_of_edges()} edges')
@@ -736,7 +739,7 @@ from pathlib import Path
 
 old_data = json.loads(Path('.graphify_old.json').read_text()) if Path('.graphify_old.json').exists() else None
 new_extract = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extract)
+G_new = build_from_json(new_extract, directed=DIRECTED)
 
 if old_data:
     G_old = json_graph.node_link_graph(old_data, edges='links')
diff --git a/graphify/skill-windows.md b/graphify/skill-windows.md
index e0955c61d..c72d38314 100644
--- a/graphify/skill-windows.md
+++ b/graphify/skill-windows.md
@@ -15,6 +15,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify <path>                                      # full pipeline on specific path
 /graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
 /graphify <path> --update                             # incremental - re-extract only new/changed files
+/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
 /graphify <path> --cluster-only                       # rerun clustering on existing graph
 /graphify <path> --no-viz                             # skip visualization, just report + JSON
 /graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
@@ -99,6 +100,8 @@ Then act on it:
 
 **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it.
 
+Also note whether `--directed` was given. If it was, set `DIRECTED=True` and pass `directed=DIRECTED` to every `build_from_json()` call. Directed graphs preserve edge direction (source→target), producing arrows in the HTML visualization and `"directed": true` in graph.json.
+
 This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (Claude, costs tokens).
 
 **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**
@@ -341,7 +344,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = cluster(G)
 cohesion = score_all(G, communities)
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -394,7 +397,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 detection  = json.loads(Path('.graphify_detect.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -434,7 +437,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
@@ -467,7 +470,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -490,7 +493,7 @@ from graphify.build import build_from_json
 from graphify.export import to_cypher
 from pathlib import Path
 
-G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()))
+G = build_from_json(json.loads(Path('.graphify_extract.json').read_text()), directed=DIRECTED)
 to_cypher(G, 'graphify-out/cypher.txt')
 print('cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt')
 "
@@ -508,7 +511,7 @@ from pathlib import Path
 
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 result = push_to_neo4j(G, uri='NEO4J_URI', user='NEO4J_USER', password='NEO4J_PASSWORD', communities=communities)
@@ -531,7 +534,7 @@ extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('.graphify_labels.json').read_text()) if Path('.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -552,7 +555,7 @@ from pathlib import Path
 extraction = json.loads(Path('.graphify_extract.json').read_text())
 analysis   = json.loads(Path('.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 to_graphml(G, communities, 'graphify-out/graph.graphml')
@@ -728,7 +731,7 @@ G_existing = json_graph.node_link_graph(existing_data, edges='links')
 
 # Load new extraction
 new_extraction = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extraction)
+G_new = build_from_json(new_extraction, directed=DIRECTED)
 
 # Merge: new nodes/edges into existing graph
 G_existing.update(G_new)
@@ -752,7 +755,7 @@ from pathlib import Path
 # Load old graph (before update) from backup written before merge
 old_data = json.loads(Path('.graphify_old.json').read_text()) if Path('.graphify_old.json').exists() else None
 new_extract = json.loads(Path('.graphify_extract.json').read_text())
-G_new = build_from_json(new_extract)
+G_new = build_from_json(new_extract, directed=DIRECTED)
 
 if old_data:
     G_old = json_graph.node_link_graph(old_data, edges='links')
diff --git a/graphify/skill.md b/graphify/skill.md
index 84815de7e..f944e2aa4 100644
--- a/graphify/skill.md
+++ b/graphify/skill.md
@@ -15,6 +15,7 @@ Turn any folder of files into a navigable knowledge graph with community detecti
 /graphify <path>                                      # full pipeline on specific path
 /graphify <path> --mode deep                          # thorough extraction, richer INFERRED edges
 /graphify <path> --update                             # incremental - re-extract only new/changed files
+/graphify <path> --directed                            # build directed graph (preserves edge direction: source→target)
 /graphify <path> --cluster-only                       # rerun clustering on existing graph
 /graphify <path> --no-viz                             # skip visualization, just report + JSON
 /graphify <path> --html                               # (HTML is generated by default - this flag is a no-op)
@@ -112,6 +113,8 @@ Then act on it:
 
 **Before starting:** note whether `--mode deep` was given. You must pass `DEEP_MODE=true` to every subagent in Step B2 if it was. Track this from the original invocation - do not lose it.
 
+Also note whether `--directed` was given. If it was, set `DIRECTED=True` and pass `directed=DIRECTED` to every `build_from_json()` call. Directed graphs preserve edge direction (source→target), producing arrows in the HTML visualization and `"directed": true` in graph.json.
+
 This step has two parts: **structural extraction** (deterministic, free) and **semantic extraction** (Claude, costs tokens).
 
 **Run Part A (AST) and Part B (semantic) in parallel. Dispatch all semantic subagents AND start AST extraction in the same message. Both can run simultaneously since they operate on different file types. Merge results in Part C as before.**
@@ -354,7 +357,7 @@ from pathlib import Path
 extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
 detection  = json.loads(Path('graphify-out/.graphify_detect.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = cluster(G)
 cohesion = score_all(G, communities)
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -407,7 +410,7 @@ extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
 detection  = json.loads(Path('graphify-out/.graphify_detect.json').read_text())
 analysis   = json.loads(Path('graphify-out/.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 tokens = {'input': extraction.get('input_tokens', 0), 'output': extraction.get('output_tokens', 0)}
@@ -447,7 +450,7 @@ extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
 analysis   = json.loads(Path('graphify-out/.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('graphify-out/.graphify_labels.json').read_text()) if Path('graphify-out/.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 cohesion = {int(k): v for k, v in analysis['cohesion'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
@@ -480,7 +483,7 @@ extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
 analysis   = json.loads(Path('graphify-out/.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('graphify-out/.graphify_labels.json').read_text()) if Path('graphify-out/.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -503,7 +506,7 @@ from graphify.build import build_from_json
 from graphify.export import to_cypher
 from pathlib import Path
 
-G = build_from_json(json.loads(Path('graphify-out/.graphify_extract.json').read_text()))
+G = build_from_json(json.loads(Path('graphify-out/.graphify_extract.json').read_text()), directed=DIRECTED)
 to_cypher(G, 'graphify-out/cypher.txt')
 print('cypher.txt written - import with: cypher-shell < graphify-out/cypher.txt')
 "
@@ -521,7 +524,7 @@ from pathlib import Path
 
 extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
 analysis   = json.loads(Path('graphify-out/.graphify_analysis.json').read_text())
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 result = push_to_neo4j(G, uri='NEO4J_URI', user='NEO4J_USER', password='NEO4J_PASSWORD', communities=communities)
@@ -544,7 +547,7 @@ extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
 analysis   = json.loads(Path('graphify-out/.graphify_analysis.json').read_text())
 labels_raw = json.loads(Path('graphify-out/.graphify_labels.json').read_text()) if Path('graphify-out/.graphify_labels.json').exists() else {}
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 labels = {int(k): v for k, v in labels_raw.items()}
 
@@ -565,7 +568,7 @@ from pathlib import Path
 extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
 analysis   = json.loads(Path('graphify-out/.graphify_analysis.json').read_text())
 
-G = build_from_json(extraction)
+G = build_from_json(extraction, directed=DIRECTED)
 communities = {int(k): v for k, v in analysis['communities'].items()}
 
 to_graphml(G, communities, 'graphify-out/graph.graphml')
@@ -759,7 +762,7 @@ G_existing = json_graph.node_link_graph(existing_data, edges='links')
 
 # Load new extraction
 new_extraction = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
-G_new = build_from_json(new_extraction)
+G_new = build_from_json(new_extraction, directed=DIRECTED)
 
 # Prune nodes from deleted files
 incremental = json.loads(Path('graphify-out/.graphify_incremental.json').read_text())
@@ -791,7 +794,7 @@ from pathlib import Path
 # Load old graph (before update) from backup written before merge
 old_data = json.loads(Path('graphify-out/.graphify_old.json').read_text()) if Path('graphify-out/.graphify_old.json').exists() else None
 new_extract = json.loads(Path('graphify-out/.graphify_extract.json').read_text())
-G_new = build_from_json(new_extract)
+G_new = build_from_json(new_extract, directed=DIRECTED)
 
 if old_data:
     G_old = json_graph.node_link_graph(old_data, edges='links')
diff --git a/graphify/watch.py b/graphify/watch.py
index a02625274..fb2cba2e6 100644
--- a/graphify/watch.py
+++ b/graphify/watch.py
@@ -11,9 +11,10 @@
 _CODE_EXTENSIONS = CODE_EXTENSIONS
 
 
-def _rebuild_code(watch_path: Path, *, follow_symlinks: bool = False) -> bool:
+def _rebuild_code(watch_path: Path, *, follow_symlinks: bool = False, directed: bool = False) -> bool:
     """Re-run AST extraction + build + cluster + report for code files. No LLM needed.
 
+    directed=True produces a DiGraph that preserves edge direction (source→target).
     Returns True on success, False on error.
     """
     try:
@@ -40,7 +41,7 @@ def _rebuild_code(watch_path: Path, *, follow_symlinks: bool = False) -> bool:
             "total_words": detected.get("total_words", 0),
         }
 
-        G = build_from_json(result)
+        G = build_from_json(result, directed=directed)
         communities = cluster(G)
         cohesion = score_all(G, communities)
         gods = god_nodes(G)
diff --git a/worked/directed-graph/review.md b/worked/directed-graph/review.md
new file mode 100644
index 000000000..6d099f9e1
--- /dev/null
+++ b/worked/directed-graph/review.md
@@ -0,0 +1,39 @@
+## Evidence: Why `--directed` matters
+
+**Corpus**: A Python codebase with 1,150 nodes and 3,403 edges.
+
+### Problem: Undirected graphs show wrong edge direction 60% of the time
+
+We built the same corpus with undirected (current default) and directed graphs, then compared every edge. Results:
+
+| Relation | Total edges | Wrong direction | Wrong % |
+|----------|------------|----------------|---------|
+| `calls` | 184 | 135 | **73%** |
+| `inherits` | 66 | 56 | **85%** |
+| `uses` | 2,088 | 1,340 | **64%** |
+| `rationale_for` | 510 | 509 | **100%** |
+| `imports_from` | 21 | 11 | **52%** |
+| `method` | 310 | 0 | 0% |
+| `contains` | 224 | 0 | 0% |
+| **Total** | **3,403** | **2,051** | **60%** |
+
+`nx.Graph` stores edges in arbitrary order. When vis.js renders arrows (hardcoded `arrows: { to: { enabled: true } }`), 60% point the wrong way. The structural relations (`method`, `contains`) happened to survive because NetworkX stored them in insertion order, but the semantically important ones — `calls`, `inherits`, `uses` — are essentially coin flips.
+
+### Root cause
+
+The original `build.py` uses `nx.Graph()` with `_src`/`_tgt` attributes as a workaround. This preserves direction metadata on the edge dict, but the graph structure itself is undirected. Any consumer reading `graph.json` (LLM agents, vis.js, NetworkX traversal) sees undirected edges and must guess direction.
+
+### A/B test
+
+We ran a controlled A/B test asking "How are the corpus connected?" — scored against a 21-item ground truth checklist across 4 dimensions (root cause accuracy, missed dependencies, story granularity, token cost).
+
+- **Graph-based (undirected)**: 21.7/40 — got flow direction wrong, missed 8 of 21 dependencies
+- **Raw corpus reading**: 30.3/40 — correct direction but expensive (120K+ tokens)
+- **Projected directed graph**: ~26/40 — fixes the direction errors that cost ~6 points
+
+### What the change does
+
+- Adds `--directed` flag — opt-in, default remains undirected for backward compatibility
+- Clustering converts to undirected internally for Louvain/Leiden (they require undirected input)
+- HTML visualization conditionally renders arrows only when the graph is directed
+- All 382 existing tests pass unchanged