chore: add graphify knowledge graph and IDE integrations

.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "CMD=$(python3 -c \"import json,sys; d=json.load(sys.stdin); print(d.get('tool_input',d).get('command',''))\" 2>/dev/null || true); case \"$CMD\" in *grep*|*rg\\ *|*ripgrep*|*find\\ *|*fd\\ *|*ack\\ *|*ag\\ *)   [ -f graphify-out/graph.json ] &&   echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"MANDATORY: graphify-out/graph.json exists. You MUST run `graphify query \\\"<question>\\\"` before grepping raw files. Only grep after graphify has oriented you, or to modify/debug specific lines.\"}}'   || true ;; esac"
+          }
+        ]
+      },
+      {
+        "matcher": "Read|Glob",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "HIT=$(python3 -c \"import json,sys;d=json.load(sys.stdin);t=d.get('tool_input',d);s=(str(t.get('file_path') or '')+' '+str(t.get('pattern') or '')+' '+str(t.get('path') or '')).lower().replace(chr(92),'/');exts=('.py','.js','.ts','.tsx','.jsx','.go','.rs','.java','.rb','.c','.h','.cpp','.hpp','.cc','.cs','.kt','.swift','.php','.scala','.lua','.sh','.md','.rst','.txt','.mdx');sys.stdout.write('1' if 'graphify-out/' not in s and any(e in s for e in exts) else '')\" 2>/dev/null || true); if [ \"$HIT\" = 1 ] && [ -f graphify-out/graph.json ]; then echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"additionalContext\":\"MANDATORY: graphify-out/graph.json exists. You MUST run graphify before reading source files. Use: `graphify query \\\"<question>\\\"` (scoped subgraph), `graphify explain \\\"<concept>\\\"`, or `graphify path \\\"<A>\\\" \\\"<B>\\\"`. Only read raw files after graphify has oriented you, or to modify/debug specific lines. This rule applies to subagents too \u2014 include it in every subagent prompt involving code exploration.\"}}'; fi || true"
+          }
+        ]
+      }
+    ]
+  }
+}

.cursor/rules/graphify.mdc

@@ -0,0 +1,10 @@
+---
+description: graphify knowledge graph — mandatory exploration workflow
+alwaysApply: true
+---
+
+Before using Read, Grep, Glob, or Bash to explore this codebase, you MUST run graphify first.
+
+Full workflow, commands, exceptions, and subagent requirements: see the **Codebase Navigation (Graphify)** section in [AGENTS.md](../../AGENTS.md).
+
+Include this rule explicitly in every subagent prompt that involves code exploration.

.gitignore

@@ -35,3 +35,14 @@ bin
 *~
 vendor/
 .claude/settings.local.json
+
+# graphify — machine-local files, do not commit
+graphify-out/cache/
+graphify-out/graph.html
+graphify-out/manifest.json
+graphify-out/.graphify_root
+graphify-out/.graphify_python
+graphify-out/.graphify_labels.json
+graphify-out/.graphify_uncached.txt
+graphify-out/cost.json
+graphify-out/[0-9]*/

.opencode/opencode.json

@@ -0,0 +1,5 @@
+{
+  "plugin": [
+    ".opencode/plugins/graphify.js"
+  ]
+}

.opencode/plugins/graphify.js

@@ -0,0 +1,22 @@
+// graphify OpenCode plugin
+// Injects a knowledge graph reminder before bash tool calls when the graph exists.
+import { existsSync } from "fs";
+import { join } from "path";
+
+export const GraphifyPlugin = async ({ directory }) => {
+  let reminded = false;
+
+  return {
+    "tool.execute.before": async (input, output) => {
+      if (reminded) return;
+      if (!existsSync(join(directory, "graphify-out", "graph.json"))) return;
+
+      if (input.tool === "bash") {
+        output.args.command =
+          'echo "[graphify] knowledge graph at graphify-out/. For focused questions, run \`graphify query \"<question>\"\` (scoped subgraph, usually much smaller than GRAPH_REPORT.md) instead of grepping raw files. Read GRAPH_REPORT.md only for broad architecture context." && ' +
+          output.args.command;
+        reminded = true;
+      }
+    },
+  };
+};

AGENTS.md

@@ -17,6 +17,17 @@ The DevWorkspace Operator provides four Kubernetes APIs:
 
 **AI Agent Note**: When modifying workspace resources, understand which API is appropriate for your changes.
 
+## Codebase Navigation (Graphify)
+
+This repository maintains a structural knowledge graph at `graphify-out/`.
+
+- **Avoid** broad `grep`/`find` across `controllers/` or `pkg/` — the graph answers most structural questions faster and with less noise.
+- **Architecture overview**: read `graphify-out/GRAPH_REPORT.md` first — it surfaces god nodes, surprising cross-file connections, and suggested queries.
+- **Specific questions**: use `/graphify query "<question>"` (or `graphify query` in terminal) for a scoped subgraph.
+- **Structural relationships**: use `/graphify path "<StructA>" "<StructB>"` to trace connections between two concepts.
+- **Concept details**: use `/graphify explain "<NodeName>"` for source location, community, and degree.
+- **After modifying code**: run `graphify update .` to keep the graph current (AST-only, no API cost).
+
 ## Advanced Features
 
 ### Workspace Bootstrapping

CONTRIBUTING.md

@@ -42,6 +42,32 @@ After addressing review comments, don't forget to add a comment in the PR afterw
 
 Detailed instructions regarding the DevWorkspace Operator development are provided in this section.
 
+### Codebase Navigation (Graphify)
+
+This repository ships a pre-built knowledge graph (`graphify-out/`) to help navigate the codebase without expensive file searches. After cloning or pulling, run once to anchor the graph to your local paths:
+
+```bash
+graphify update .
+```
+
+Optionally, enable auto-rebuild on every commit:
+
+```bash
+graphify hook install
+```
+
+Once set up, use these commands instead of `grep`/`find` across the source tree:
+
+| Task | Command |
+|---|---|
+| Architecture overview | read `graphify-out/GRAPH_REPORT.md` |
+| Specific question | `/graphify query "<question>"` |
+| Trace relationship | `/graphify path "<StructA>" "<StructB>"` |
+| Concept details | `/graphify explain "<NodeName>"` |
+| After modifying code | `graphify update .` (terminal) |
+
+> **Note:** Do not run `graphify claude install` — graphify guidance is already included in `AGENTS.md`.
+
 ### Prerequisites
 
 To build, test and debug the DevWorkspace Operator the following development tools are required: