Add graph.json schema version metadata

README.md

@@ -68,6 +68,10 @@ graphify-out/
 └── graph.json       the full graph — query it anytime without re-reading your files
 ```
 
+The persisted graph includes `graph.schema_version` so integrations can detect
+incompatible format changes, plus `graph.graphify_version` identifying the
+Graphify release that produced it.
+
 **Works in** Claude Code, Cursor, Codex, Gemini CLI, GitHub Copilot, and 15+ more — [pick your platform](#install).
 
 ---

graphify/export.py

@@ -172,6 +172,20 @@ from graphify.exporters.base import COMMUNITY_COLORS  # noqa: E402,F401
 from graphify.exporters.html import to_html  # noqa: E402,F401
 
 
+# Increment when the persisted graph structure changes incompatibly for consumers.
+GRAPH_SCHEMA_VERSION = 1
+
+
+def _graphify_version() -> str | None:
+    """Return the installed graphify version for graph provenance."""
+    try:
+        from importlib.metadata import version
+
+        return version("graphifyy")
+    except Exception:
+        return None
+
+
 # Fallback scores for an edge that carries a confidence tier but no
 # confidence_score. The INFERRED default was 0.5, which references/extraction-spec.md
 # rules out in as many words — "never omit it, never use 0.5 as a default" — and
@@ -433,6 +447,11 @@ def to_json(G: nx.Graph, communities: dict[int, list[str]], output_path: str, *,
     if isinstance(data.get("graph"), dict) and "hyperedges" in data["graph"]:
         data["graph"]["hyperedges"] = hyperedges
     data["hyperedges"] = hyperedges
+    graph_metadata = data.setdefault("graph", {})
+    graph_metadata["schema_version"] = GRAPH_SCHEMA_VERSION
+    graphify_version = _graphify_version()
+    if graphify_version is not None:
+        graph_metadata["graphify_version"] = graphify_version
     # Fallback provenance comes from the repo the graph is being written INTO
     # (output_path lives in <target>/graphify-out/), never the shell's cwd —
     # the same cwd-anchoring mistake #2316 fixed for `update`.

tests/test_export.py

@@ -30,6 +30,18 @@ def test_to_json_valid_json():
         assert "nodes" in data
         assert "links" in data
 
+
+def test_to_json_includes_graph_schema_metadata(tmp_path):
+    G = make_graph()
+    out = tmp_path / "graph.json"
+
+    assert to_json(G, {}, str(out))
+
+    graph_metadata = json.loads(out.read_text())["graph"]
+    assert graph_metadata["schema_version"] == 1
+    assert graph_metadata["graphify_version"]
+
+
 def test_to_json_nodes_have_community():
     G = make_graph()
     communities = cluster(G)