vibes-plug 2.5.0 → 2.14.1

package/skills/glsl-shader-expert/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: glsl-shader-expert
-description: "Expert guide for writing custom GLSL shaders (Vertex/Fragment) for WebGL using Three.js and Babylon.js. Covers shader materials, post-processing, noise, and performance optimization."
-author: "Roedy Rustam"
+description: "Expert guide for modern web shaders: Three Shading Language (TSL), WebGPU WGSL, Compute Shaders, and WebGL GLSL in Three.js and Babylon.js. Covers procedural generation, compute kernels, and post-processing / Panduan ahli shader web modern: TSL, WGSL, Compute Shader, dan GLSL."
+author: "vibes-plug-swarm"
 ---
 
-# GLSL Shader Expert (WebGL 3D Graphics)
+# Modern Web Shader Expert (TSL, WGSL, Compute Shaders & GLSL)
 
 [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
 
@@ -13,89 +13,178 @@ author: "Roedy Rustam"
 <a name="english"></a>
 ## English
 
+### Orchestration & Integration
+Connects and orchestrates with relevant domain skills:
+- `web-3d-graphics-expert` — WebGPU/WebGL scene rendering and NodeMaterial binding.
+- `web-game-engine-expert` — Physics simulations, particle systems, and VFX materials.
+- `ui-ux-pro-max` — Modern visual effects, glassmorphism, and screen-space distortion.
+- `performance-web-vitals` — GPU profiling, draw call reduction, and compute shader optimization.
+
 ### Description
-Production-grade guidance for writing and integrating custom GLSL (OpenGL Shading Language) shaders into web applications using **Three.js** (`ShaderMaterial` / `RawShaderMaterial`) or **Babylon.js** (`ShaderMaterial`). Focuses on creating advanced visual effects, custom lighting models, procedural textures (noise), and post-processing passes.
+Production-grade guidance for authoring, compiling, and optimizing GPU shaders for modern web applications. Focuses on the cutting-edge **TSL (Three Shading Language)** node system which cross-compiles to both **WGSL (WebGPU)** and **GLSL (WebGL2)**, standalone **WGSL Compute Shaders** for parallel processing (particles, boids, simulation), and legacy **GLSL** optimization.
 
 ### Trigger Conditions
 Activate this skill when the user is:
-- Asking to create custom materials that standard PBR materials cannot achieve.
-- Writing Vertex or Fragment shaders in GLSL.
-- Implementing procedural generation (e.g., Perlin noise, Simplex noise) on the GPU.
-- Creating post-processing effects or screen-space shaders.
-- Optimizing GPU performance by moving CPU calculations to vertex shaders.
-
-### Core Concepts
-
-#### 1. The Graphics Pipeline
-Understand the flow:
-1. **Vertex Shader:** Runs for every vertex. Used to manipulate geometry (position) and pass data (varyings) to the fragment shader. Must set `gl_Position`.
-2. **Fragment Shader:** Runs for every pixel (fragment). Used to determine color. Must set `gl_FragColor`.
-
-#### 2. Three.js `ShaderMaterial` Example
-```javascript
-import * as THREE from 'three';
-
-const vertexShader = `
-  varying vec2 vUv;
-  void main() {
-    vUv = uv;
-    // Standard projection
-    gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
-  }
-`;
-
-const fragmentShader = `
-  uniform float uTime;
-  varying vec2 vUv;
-  void main() {
-    // Simple animated color based on UV coordinates and time
-    vec3 color = vec3(vUv.x, vUv.y, sin(uTime) * 0.5 + 0.5);
-    gl_FragColor = vec4(color, 1.0);
-  }
-`;
-
-const material = new THREE.ShaderMaterial({
-  vertexShader,
-  fragmentShader,
-  uniforms: {
-    uTime: { value: 0 }
-  }
+- Writing custom shader materials in Three.js or Babylon.js.
+- Refactoring legacy GLSL shaders to Three Shading Language (TSL) or WebGPU WGSL.
+- Implementing WebGPU Compute Shaders (`@compute` workgroups, storage buffers).
+- Creating procedural VFX: fluid simulations, volumetric clouds, noise-based terrain, or holographic shields.
+- Designing post-processing screen passes (bloom, chromatic aberration, SSAO/GTAO, depth of field).
+- Optimizing GPU bottlenecks, thread divergence, or ALU instruction counts.
+
+---
+
+### Modern Web Shader Paradigms (2026)
+
+| Paradigm | Target API | Key Advantages | When to Use |
+| :--- | :--- | :--- | :--- |
+| **TSL (Three Shading Language)** | WebGPU + WebGL2 | Cross-compiles node trees to WGSL and GLSL; type-safe JavaScript/TypeScript syntax. | Default standard for modern Three.js (r170+) materials and post-processing. |
+| **WGSL (WebGPU Shading Language)** | WebGPU native | Direct GPU memory access, structured storage buffers, atomic operations. | Raw WebGPU apps, Babylon.js WebGPU compute, custom WebGPU pipelines. |
+| **Compute Shaders** | WebGPU | General-purpose GPU (GPGPU) computing; runs without rasterization or vertex buffers. | 100,000+ particle systems, cloth physics, fluid simulation, GPU boids. |
+| **GLSL (ES 3.0)** | WebGL2 fallback | Universal device compatibility on legacy hardware. | Legacy Three.js/Babylon.js projects and fallback pipelines. |
+
+---
+
+### 1. Three Shading Language (TSL) Node System
+
+TSL replaces string-concatenated GLSL with modular, type-safe node expressions that Three.js automatically compiles to WGSL on WebGPU and GLSL on WebGL2.
+
+```typescript
+import * as THREE from 'three/webgpu';
+import { Fn, float, vec3, color, uv, time, positionLocal, sin, uniform } from 'three/tsl';
+
+// Define custom dynamic uniforms
+const uFrequency = uniform(3.0);
+const uSpeed = uniform(1.5);
+
+// Reusable TSL shader function (Node-based)
+const waterWave = Fn(([freq, spd]) => {
+  const coord = uv();
+  const wave = sin(coord.x.mul(freq).add(time.mul(spd)))
+    .add(sin(coord.y.mul(freq).add(time.mul(spd))))
+    .mul(0.5);
+  return wave;
 });
+
+// Vertex Position displacement in TSL
+const displacedPosition = Fn(() => {
+  const wave = waterWave(uFrequency, uSpeed);
+  const newPos = positionLocal.add(vec3(0.0, wave.mul(0.2), 0.0));
+  return newPos;
+});
+
+// Create Node Material
+const oceanMaterial = new THREE.MeshStandardNodeMaterial();
+oceanMaterial.positionNode = displacedPosition();
+oceanMaterial.colorNode = Fn(() => {
+  const wave = waterWave(uFrequency, uSpeed);
+  const baseColor = color(0x004488);
+  const foamColor = color(0x88eeff);
+  return baseColor.mix(foamColor, wave.add(0.5));
+})();
 ```
-*Note: In the render loop, you must update `material.uniforms.uTime.value += delta;`*
 
-#### 3. Best Practices for Shaders
-- **Avoid Branching:** GPU threads run in lockstep (warps/wavefronts). `if/else` statements can cause significant performance drops. Prefer mathematical functions like `step()`, `smoothstep()`, `mix()`, and `clamp()`.
-- **Precision:** Explicitly declare float precision (`precision mediump float;` or `highp` if necessary). Use `mediump` for colors/UVs to save performance, particularly on mobile.
-- **Use Uniforms Wisely:** Only pass data that changes per frame or per object as uniforms.
+---
+
+### 2. WebGPU Compute Shaders (GPGPU Parallel Processing)
+
+Compute shaders run arbitrary mathematical workloads across thousands of GPU threads simultaneously:
+
+```typescript
+import * as THREE from 'three/webgpu';
+import { Fn, float, vec3, uniform, storage, instanceIndex } from 'three/tsl';
+
+const PARTICLE_COUNT = 65536;
+
+// Create GPU Storage Buffers
+const positionBuffer = new THREE.StorageBufferAttribute(new Float32Array(PARTICLE_COUNT * 3), 3);
+const velocityBuffer = new THREE.StorageBufferAttribute(new Float32Array(PARTICLE_COUNT * 3), 3);
+
+const posStorage = storage(positionBuffer, 'vec3', PARTICLE_COUNT);
+const velStorage = storage(velocityBuffer, 'vec3', PARTICLE_COUNT);
+
+// TSL Compute Kernel (executes per particle on GPU)
+const computeParticles = Fn(() => {
+  const index = instanceIndex;
+  const pos = posStorage.element(index);
+  const vel = velStorage.element(index);
+
+  // Update position based on velocity
+  pos.addAssign(vel.mul(0.016));
+
+  // Bounce off boundaries [-5, 5]
+  vel.y.assign(pos.y.lessThan(-5.0).select(vel.y.abs(), vel.y));
+  vel.y.assign(pos.y.greaterThan(5.0).select(vel.y.abs().negate(), vel.y));
+})().compute(PARTICLE_COUNT);
+
+// In the render loop:
+// renderer.compute(computeParticles);
+// renderer.render(scene, camera);
+```
 
 ---
 
-### Integration with Other Skills (MANDATORY)
-This skill works best when combined with:
-- `web-3d-graphics-expert` — For setting up the core WebGL scene in Three.js/Babylon.js.
-- `web-game-engine-expert` — For linking shader uniforms with physics data (e.g., impact ripples).
-- `ui-ux-pro-max` — For ensuring shader visual effects match the modern Web design tokens.
+### 3. High-Performance Shader Rules (GPU Architecture)
+
+1. **Eliminate Branching Divergence:**
+   - GPU threads execute in lockstep warps (NVIDIA: 32 threads, AMD/Apple: 32-64 threads).
+   - If threads inside the same warp take different branches in an `if/else`, both paths are evaluated serially, destroying throughput.
+   - **Use Math Primitives:** Replace branches with `step()`, `smoothstep()`, `mix()`, `clamp()`, or `select()`.
+   ```glsl
+   // BAD: Divergent GPU branch
+   if (vDepth > 0.5) { color = vec3(1.0); } else { color = vec3(0.0); }
+
+   // GOOD: Branchless step function
+   color = vec3(step(0.5, vDepth));
+   ```
 
-### Referenced By Orchestrators (MANDATORY)
-- `brainstorming` — Add to "3D & Graphics" or "UI/UX & Design Systems".
-- `zero-to-prod-orchestrator` — Phase 5 (Frontend / WebGL Implementation).
+2. **Precision Management:**
+   - Always specify precision for mobile GPUs.
+   - Use `mediump` (16-bit float) for colors, normal vectors, and UVs to gain 2x arithmetic throughput and save bandwidth.
+   - Reserve `highp` (32-bit float) for world-space coordinates and depth calculations.
+
+3. **Precompute on CPU or Vertex Shader:**
+   - Never compute values in the fragment shader (millions of pixels) that are constant across the mesh or linear across vertices.
+   - Move matrix inversions, static lighting directions, or uniform transformations to the CPU or Vertex stage.
 
 ---
 
 <a name="bahasa-indonesia"></a>
 ## Bahasa Indonesia
 
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi skill domain yang relevan:
+- `web-3d-graphics-expert` — Rendering scene WebGPU/WebGL dan integrasi NodeMaterial.
+- `web-game-engine-expert` — Simulasi fisika, sistem partikel, dan material efek game.
+- `ui-ux-pro-max` — Efek visual modern, glassmorphism, dan distorsi screen-space.
+- `performance-web-vitals` — Profiling GPU, optimasi draw call, dan compute shader.
+
 ### Deskripsi
-Panduan ahli untuk menulis dan mengintegrasikan shader GLSL khusus ke dalam aplikasi web menggunakan **Three.js** atau **Babylon.js**. Mencakup pembuatan *Vertex Shader*, *Fragment Shader*, efek visual prosedural, dan optimasi GPU.
+Panduan produksi untuk menulis, mengompilasi, dan mengoptimalkan shader GPU untuk aplikasi web modern. Fokus pada sistem node **TSL (Three Shading Language)** yang dapat dikompilasi silang menjadi **WGSL (WebGPU)** dan **GLSL (WebGL2)**, **Compute Shader WGSL** mandiri untuk pemrosesan paralel GPU skala masif (partikel, boids, simulasi cairan), dan optimasi **GLSL**.
 
 ### Kondisi Pemicu
-- Saat pengguna ingin membuat efek visual kustom (seperti air, hologram, distorsi) yang tidak bisa dilakukan oleh material standar.
-- Menulis kode GLSL untuk *ShaderMaterial*.
-- Mengoptimalkan performa grafis dengan memindahkan komputasi CPU ke GPU.
-
-### Panduan Singkat
-- **Vertex vs Fragment:** *Vertex shader* mengatur posisi dan memanipulasi geometri (`gl_Position`), sedangkan *Fragment shader* mengatur pewarnaan setiap pixel (`gl_FragColor`).
-- **Hindari If/Else:** CPU sangat cepat dalam percabangan (`if/else`), tetapi GPU sangat lambat. Gunakan fungsi interpolasi matematika bawaan GLSL seperti `step()`, `smoothstep()`, dan `mix()`.
-- **Gunakan Uniforms:** Gunakan `uniforms` untuk mengirim data dari JavaScript (seperti waktu, posisi mouse, atau tekstur) ke dalam shader. Update nilai uniform ini di dalam *render loop*.
-- **Presisi (Precision):** Gunakan `precision mediump float;` secara default untuk menyeimbangkan performa dan kualitas visual, terutama untuk optimalisasi *mobile*.
+Aktifkan skill ini ketika pengguna:
+- Menulis *custom shader material* pada Three.js atau Babylon.js.
+- Merefaktor shader GLSL lama menjadi Three Shading Language (TSL) atau WebGPU WGSL.
+- Mengimplementasikan WebGPU Compute Shader (`@compute` workgroups, storage buffers).
+- Membuat efek visual prosedural (simulasi air, awan volumetrik, medan prosedural, perisai hologram).
+- Merancang *post-processing passes* (bloom, chromatic aberration, SSAO, depth of field).
+- Mengatasi bottleneck GPU, *thread divergence*, atau instruksi ALU berlebih.
+
+---
+
+### Prinsip Utama Shader Modern
+
+1. **Adopsi TSL (Three Shading Language)**:
+   - Hindari menulis shader dalam bentuk *string concatenation* GLSL mentah pada proyek modern. Gunakan TSL (`Fn`, `color`, `uv`, `positionLocal`). TSL menjaga keamanan tipe (type-safety) dan otomatis menghasilkan WGSL atau GLSL sesuai runtime.
+
+2. **GPGPU dengan Compute Shader**:
+   - Manfaatkan WebGPU Compute Shader untuk kalkulasi ribuan partikel atau simulasi matematika tanpa melalui tahap rasterisasi atau vertex buffer tradisional.
+
+3. **Aturan Anti-Branching (Branchless Shader)**:
+   - GPU mengeksekusi instruksi dalam kelompok thread (*warp/wavefront*). Percabangan `if/else` yang tidak seragam akan memaksa GPU mengeksekusi kedua cabang secara berurutan (*branch penalty*).
+   - Gunakan fungsi matematika seperti `step()`, `smoothstep()`, dan `mix()` alih-alih percabangan logika kondisional.
+
+4. **Manajemen Presisi**:
+   - Gunakan `mediump` (16-bit float) untuk warna, koordinat UV, dan vektor normal untuk melipatgandakan kecepatan komputasi pada GPU smartphone.
+   - Gunakan `highp` (32-bit float) hanya untuk posisi ruang dunia (*world space*) dan perhitungan kedalaman (*depth*).

package/skills/go-programming-expert/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: go-programming-expert
-description: "Expert-level skill for Go programming (Go 1.23/1.24+). Covers high-performance microservices, concurrency patterns, sqlc, net/http, Gin/Echo/Fiber, gRPC, and testing in English and Indonesian."
-author: "Roedy Rustam"
+description: "Expert-level skill for Go programming (Go 1.25+). Covers high-performance microservices, concurrency patterns, sqlc, net/http, Gin/Echo/Fiber, gRPC, and testing in English and Indonesian."
+author: "Roedy Rustam"
 ---
 
-# Go Programming Expert (Go 1.24 Edition)
+# Go Programming Expert (Go 1.25 Edition)
 
 [English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
 
@@ -13,11 +13,14 @@ author: "Roedy Rustam"
 <a name="english"></a>
 ## English
 
+### Orchestration & Integration
+Connects and orchestrates with relevant domain skills like `brainstorming`, `zero-to-prod-orchestrator`, and `project-context-mapper` to ensure cohesive execution.
+
 ### Description
-Expert-level Go development for building high-performance microservices, APIs, and CLI tools. Covers **Go 1.24** features (range-over-func iterators, generic type aliases, weak pointers), structured logging with `slog`, `net/http` with the new ServeMux patterns, Gin/Echo/Fiber frameworks, sqlc for type-safe SQL, gRPC, and production testing patterns.
+Expert-level Go development for building high-performance microservices, APIs, and CLI tools. Covers **Go 1.25** features (range-over-func iterators, generic type aliases, weak pointers), structured logging with `slog`, `net/http` with the new ServeMux patterns, Gin/Echo/Fiber frameworks, sqlc for type-safe SQL, gRPC, and production testing patterns.
 
 ### Trigger Conditions
-- Writing Go 1.23+ / 1.24+ microservices or APIs.
+- Writing Go 1.24+ / 1.25+ microservices or APIs.
 - Implementing concurrency patterns with goroutines, channels, and `sync` primitives.
 - Using structured logging with `log/slog`.
 - Building HTTP servers with `net/http` ServeMux (Go 1.22+) or Gin/Echo/Fiber.
@@ -25,9 +28,9 @@ Expert-level Go development for building high-performance microservices, APIs, a
 - Implementing gRPC services with protobuf.
 - Writing Go tests with the standard `testing` package + `testify`.
 
-### Go 1.24 — Key Features
+### Go 1.25 — Key Features
 
-#### Range-Over-Func (Go 1.22 → Stable in 1.24)
+#### Range-Over-Func (Go 1.22 → Stable in 1.24/1.25)
 Range over custom iterators — enables functional-style collection operations:
 ```go
 // Define an iterator function
@@ -52,7 +55,7 @@ for n := range Fibonacci() {
 }
 ```
 
-#### Generic Type Aliases (Go 1.24)
+#### Generic Type Aliases (Go 1.24/1.25)
 ```go
 // Type alias with generic parameters
 type Set[T comparable] = map[T]struct{}
@@ -62,7 +65,7 @@ type Result[T any] = struct{ Value T; Err error }
 var s Set[string] = make(map[string]struct{})
 ```
 
-#### Weak Pointers (Go 1.24)
+#### Weak Pointers (Go 1.24/1.25)
 ```go
 import "weak"
 
@@ -250,24 +253,27 @@ func TestGetUser(t *testing.T) {
 <a name="bahasa-indonesia"></a>
 ## Bahasa Indonesia
 
+### Integrasi Orkestrasi
+Terhubung dan mengorkestrasi skill domain yang relevan seperti `brainstorming`, `zero-to-prod-orchestrator`, dan `project-context-mapper` untuk memastikan eksekusi yang kohesif.
+
 ### Deskripsi
-Panduan Go tingkat ahli untuk membangun microservices, API, dan CLI tool berkinerja tinggi. Mencakup fitur **Go 1.24** (range-over-func, generic type alias, weak pointer), structured logging dengan `slog`, ServeMux `net/http` dengan pola baru (Go 1.22+), framework Gin/Echo/Fiber, sqlc untuk SQL type-safe, gRPC, dan pola pengujian produksi.
+Panduan Go tingkat ahli untuk membangun microservices, API, dan CLI tool berkinerja tinggi. Mencakup fitur **Go 1.25** (range-over-func, generic type alias, weak pointer), structured logging dengan `slog`, ServeMux `net/http` dengan pola baru (Go 1.22+), framework Gin/Echo/Fiber, sqlc untuk SQL type-safe, gRPC, dan pola pengujian produksi.
 
 ### Kondisi Pemicu
-- Menulis microservices atau API Go 1.23+/1.24+.
+- Menulis microservices atau API Go 1.24+/1.25+.
 - Mengimplementasikan pola konkurensi dengan goroutine, channel, dan primitif `sync`.
 - Menggunakan structured logging dengan `log/slog`.
 - Membangun HTTP server dengan ServeMux `net/http` (Go 1.22+) atau Gin/Echo/Fiber.
 - Menulis SQL type-safe dengan **sqlc** atau GORM.
 - Mengimplementasikan layanan gRPC dengan protobuf.
 
-### Go 1.24 — Fitur Utama
+### Go 1.25 — Fitur Utama
 
-#### Range-Over-Func (Stabil di 1.24)
-Go 1.24 menstabilkan range over iterator function — memungkinkan koleksi gaya fungsional yang idiomatis tanpa mengekspos slice internal.
+#### Range-Over-Func (Stabil di 1.24/1.25)
+Go 1.24/1.25 menstabilkan range over iterator function — memungkinkan koleksi gaya fungsional yang idiomatis tanpa mengekspos slice internal.
 
 #### Generic Type Alias
-Go 1.24 memungkinkan alias tipe dengan parameter generic, meningkatkan komposibilitas tipe.
+Go 1.24/1.25 memungkinkan alias tipe dengan parameter generic, meningkatkan komposibilitas tipe.
 
 #### Weak Pointer
 `weak.Make()` membuat pointer lemah yang tidak mencegah GC mengumpulkan objek — berguna untuk cache.

package/skills/graph-rag-knowledge-expert/SKILL.md

@@ -0,0 +1,200 @@
+---
+name: graph-rag-knowledge-expert
+description: "Expert guide for Knowledge Graphs, GraphRAG, Microsoft GraphRAG, Neo4j Text2Cypher, multi-hop relational retrieval, and hybrid vector-graph search / Panduan ahli Knowledge Graph, GraphRAG, dan pencarian relasional multi-hop."
+author: "Roedy Rustam"
+---
+
+# GraphRAG & Knowledge Graph Expert (2026 Edition)
+
+[English](#english) | [Bahasa Indonesia](#bahasa-indonesia)
+
+---
+
+<a name="english"></a>
+## English
+
+### Description
+Expert guide for implementing Knowledge Graph-augmented Retrieval (GraphRAG), solving the fatal weaknesses of vector search: multi-hop reasoning, relationship discovery, and global corpus understanding. Covers Microsoft GraphRAG, Neo4j Text2Cypher, FalkorDB, and hybrid Vector + Graph retrieval pipelines.
+
+### Trigger Conditions
+- Complex multi-hop queries where entities are linked through multiple intermediate nodes.
+- High hallucination rate using standard vector RAG on interconnected data.
+- Global corpus queries requiring domain-wide thematic summarization across thousands of documents.
+- Enterprise knowledge bases containing explicitly structured relational entities (e.g., organizations, code dependencies, regulatory rules).
+
+---
+
+## 1. Why GraphRAG Over Pure Vector Search?
+
+| Capability | Pure Vector Search (RAG) | GraphRAG (Graph + Vector) |
+| :--- | :--- | :--- |
+| **Direct Similarity ("What is X?")** | 🟢 Fast, accurate | 🟢 High accuracy |
+| **Multi-Hop Traversal ("How does X affect Z via Y?")** | 🔴 Blind (returns fragmented chunks) | 🟢 Explores interconnected graph edges |
+| **Global Corpus Query ("What are the main themes across all documents?")** | 🔴 Fails (limited to Top-K chunks) | 🟢 Hierarchical Community Summaries |
+| **Hallucination Rate on Complex Queries** | 🔴 Moderate to High (context stitching) | 🟢 Grounded in explicit knowledge edges |
+
+---
+
+## 2. Production Recipe: Text2Cypher Knowledge Graph Querying (TypeScript)
+
+Using Neo4j with deterministic schema introspection, preventing arbitrary syntax hallucinations.
+
+```typescript
+// text2cypher.ts - Safe Neo4j Query Generation & Execution
+import neo4j, { Driver } from 'neo4j-driver';
+import { generateText } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+export class GraphRAGService {
+  private driver: Driver;
+
+  constructor(uri: string, user: string, pass: string) {
+    this.driver = neo4j.driver(uri, neo4j.auth.basic(user, pass));
+  }
+
+  // 1. Fetch live Graph Schema to ground the LLM
+  private async getGraphSchema(): Promise<string> {
+    const session = this.driver.session();
+    try {
+      const result = await session.run(`
+        CALL apoc.meta.schema() YIELD value
+        RETURN value
+      `);
+      return JSON.stringify(result.records[0]?.get('value') || {});
+    } finally {
+      await session.close();
+    }
+  }
+
+  // 2. Synthesize strict read-only Cypher query
+  public async queryGraph(userQuestion: string): Promise<any[]> {
+    const schema = await this.getGraphSchema();
+
+    const { text: cypherQuery } = await generateText({
+      model: openai('gpt-4o-mini'),
+      system: `
+        You are an expert Neo4j Cypher generator.
+        Generate ONLY valid, read-only CYPHER queries based on this schema:
+        ${schema}
+
+        Rules:
+        - Never generate CREATE, MERGE, DELETE, or SET statements.
+        - Always use parameterization where appropriate.
+        - Output ONLY the raw Cypher query, without markdown or backticks.
+      `,
+      prompt: `Translate this question into Cypher: ${userQuestion}`,
+    });
+
+    const sanitizedCypher = cypherQuery.trim().replace(/^```cypher|```$/g, '');
+
+    // 3. Execute with read-only transaction
+    const session = this.driver.session({ defaultAccessMode: neo4j.session.READ });
+    try {
+      const res = await session.run(sanitizedCypher);
+      return res.records.map((r) => r.toObject());
+    } finally {
+      await session.close();
+    }
+  }
+
+  public async close(): Promise<void> {
+    await this.driver.close();
+  }
+}
+```
+
+---
+
+## 3. Production Recipe: Entity & Relation Extraction (Python)
+
+```python
+# graph_extractor.py - Structured Entity & Relation Extraction
+from typing import List
+from pydantic import BaseModel, Field
+import instructor
+from openai import OpenAI
+
+client = instructor.from_openai(OpenAI())
+
+class Entity(BaseModel):
+    name: str = Field(description="Normalized entity name, uppercase")
+    type: str = Field(description="ORGANIZATION, PERSON, TECHNOLOGY, CONCEPT, LOCATION")
+    description: str = Field(description="Summary of entity role")
+
+class Relationship(BaseModel):
+    source_entity: str
+    target_entity: str
+    relation_type: str = Field(description="USES, DEVELOPS, OWNS, LOCATED_IN, DEPENDS_ON")
+    weight: float = Field(default=1.0, ge=0.0, le=1.0)
+    description: str
+
+class KnowledgeGraph(BaseModel):
+    entities: List[Entity]
+    relationships: List[Relationship]
+
+def extract_knowledge_graph(document_text: str) -> KnowledgeGraph:
+    """Extracts entities and relationships from raw text into structured schema."""
+    return client.chat.completions.create(
+        model="gpt-4o-mini",
+        response_model=KnowledgeGraph,
+        messages=[
+            {
+                "role": "system",
+                "content": (
+                    "Extract all named entities and factual relationships between them. "
+                    "Ensure entity names are canonicalized and relationships are directed."
+                ),
+            },
+            {"role": "user", "content": document_text},
+        ],
+        temperature=0.0,
+    )
+```
+
+---
+
+## 4. Microsoft GraphRAG: Hierarchical Communities
+
+For high-level summaries ("Summarize all technical debts reported across the system"):
+1. **Extraction**: Chunk documents ➔ Extract Entities & Relationships.
+2. **Clustering**: Apply **Leiden Algorithm** to detect hierarchical communities (Level 0: Micro, Level 1: Sub-domain, Level 2: Macro domain).
+3. **Summarization**: LLM generates pre-computed summaries for each community cluster.
+4. **Global Search**: Query runs across pre-computed community summaries in parallel, eliminating the need to read millions of tokens at inference time.
+
+---
+
+## Orchestration & Integration
+
+- **`vector-db-rag-expert`**: For hybrid dense-vector similarity search combined with graph path discovery.
+- **`database-orm-expert`**: For maintaining transactional relational mappings alongside graph stores.
+- **`ai-llm-integration-expert`**: Connects reasoning models to multi-hop graph context.
+- **`search-engine-expert`**: For keyword lexical indexing of graph node attributes.
+
+---
+
+<a name="bahasa-indonesia"></a>
+## Bahasa Indonesia
+
+### Deskripsi
+Panduan ahli untuk mengimplementasikan Knowledge Graph-augmented Retrieval (GraphRAG) guna mengatasi kelemahan mendasar vector search murni: pemikiran multi-hop, penemuan relasi entitas tersembunyi, dan pemahaman korpus global. Mencakup Microsoft GraphRAG, Neo4j Text2Cypher, FalkorDB, dan pipeline pencarian hibrida Vector + Graph.
+
+### Kondisi Pemicu
+- Kueri kompleks multi-hop di mana entitas saling terhubung melalui beberapa simpul perantara.
+- Tingkat halusinasi tinggi saat menggunakan RAG vektor standar pada data relasional yang rumit.
+- Kueri korpus global yang membutuhkan ringkasan tematik menyeluruh di ribuan dokumen.
+- Knowledge base enterprise dengan entitas terstruktur eksplisit (organisasi, dependensi kode, regulasi).
+
+### Ringkasan Strategi GraphRAG
+1. **Mengapa GraphRAG?**: Pencarian vektor murni buta terhadap lintasan relasi multi-hop. GraphRAG menautkan entitas melalui edge terarah sehingga model dapat menavigasi dependensi secara deterministik.
+2. **Text2Cypher yang Aman**: Menghasilkan kueri Cypher Neo4j read-only berdasarkan schema meta yang diinjeksi secara ketat tanpa izin write (`CREATE`, `MERGE`, `DELETE`).
+3. **Ekstraksi Terstruktur**: Menggunakan Pydantic / Instructor untuk mengekstrak entitas dan relasi berkualifikasi tipe tinggi langsung dari teks bebas.
+4. **Komunitas Hirarkis (Microsoft GraphRAG)**: Algoritma Leiden untuk mengelompokkan simpul menjadi komunitas mikro hingga makro, memungkinkan kueri global tanpa membaca jutaan token saat inferensi.
+
+---
+
+## Integrasi Orkestrasi
+
+- **`vector-db-rag-expert`**: Untuk pencarian kesamaan vektor padat hibrida yang digabungkan dengan traversal graf.
+- **`database-orm-expert`**: Untuk pemetaan data transaksional relasional bersama penyimpanan graf.
+- **`ai-llm-integration-expert`**: Menghubungkan model penalaran ke konteks graf multi-hop.
+- **`search-engine-expert`**: Pengindeksan leksikal kata kunci untuk atribut simpul graf.