fix(schema): reject the direction-inverting documented_by alias

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "understand-anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.7",
+  "version": "2.9.8",
   "author": {
     "name": "Egonex"
   },

.copilot-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "understand-anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.7",
+  "version": "2.9.8",
   "author": {
     "name": "Egonex"
   },

.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "understand-anything",
   "displayName": "Understand Anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.7",
+  "version": "2.9.8",
   "author": {
     "name": "Egonex"
   },

understand-anything-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "understand-anything",
   "description": "AI-powered codebase understanding — analyze, visualize, and explain any project",
-  "version": "2.9.7",
+  "version": "2.9.8",
   "author": {
     "name": "Egonex"
   },

understand-anything-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@understand-anything/skill",
-  "version": "2.9.7",
+  "version": "2.9.8",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

understand-anything-plugin/packages/core/src/__tests__/schema.test.ts

@@ -245,6 +245,29 @@ describe("schema validation", () => {
     );
   });
 
+  it('drops "documented_by" instead of reversing its meaning', () => {
+    const graph = {
+      ...validGraph,
+      edges: [{ ...validGraph.edges[0], type: "documented_by" }],
+    };
+
+    const result = validateGraph(graph);
+    expect(result.success).toBe(true);
+    expect(result.data!.edges).toHaveLength(0);
+    expect(result.issues).toContainEqual(
+      expect.objectContaining({ level: "dropped", category: "invalid-edge", path: "edges[0]" })
+    );
+  });
+
+  it('preserves the endpoints of canonical "documents" edges', () => {
+    const graph = structuredClone(validGraph);
+    graph.edges[0].type = "documents";
+
+    const result = validateGraph(graph);
+    expect(result.success).toBe(true);
+    expect(result.data!.edges[0]).toEqual(graph.edges[0]);
+  });
+
   it("drops truly invalid edge types after normalization", () => {
     const graph = structuredClone(validGraph);
     (graph.edges[0] as any).type = "totally_bogus";

understand-anything-plugin/packages/core/src/schema.ts

@@ -117,7 +117,6 @@ export const EDGE_TYPE_ALIASES: Record<string, string> = {
   subscribe: "subscribes",
   // Non-code aliases
   describes: "documents",
-  documented_by: "documents",
   creates: "provisions",
   exposes: "serves",
   listens: "serves",
@@ -144,9 +143,9 @@ export const EDGE_TYPE_ALIASES: Record<string, string> = {
   tagged_with: "categorized_under",
   written_by: "authored_by",
   created_by: "authored_by",
-  // Note: "implemented_by" is intentionally NOT aliased to "implements" —
-  // it inverts edge direction (see commit fd0df15). The LLM should use
-  // "implements" with correct source/target instead.
+  // Note: "implemented_by" and "documented_by" are intentionally NOT aliased
+  // to "implements" and "documents": changing the type alone inverts their
+  // meaning. The LLM should use canonical types with correct source/target.
 };
 
 // Design edge aliases — applied only when the graph's kind is "design".

understand-anything-plugin/packages/viewer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "understand-anything-viewer",
-  "version": "2.9.7",
+  "version": "2.9.8",
   "description": "Standalone read-only viewer for Understand-Anything knowledge graphs — no Claude Code or LLM required.",
   "type": "module",
   "license": "MIT",