diff --git a/README.md b/README.md
index cc1fde5..7daf90c 100644
--- a/README.md
+++ b/README.md
@@ -32,6 +32,19 @@ This plugin is currently in **active development**. Major features are being imp
 
 ---
 
+## 📊 Permission Resolution Logic
+
+When checking permissions, **user-defined permissions always override group-defined ones**, and groups are sorted by weight:
+
+| User Permission | Group Permission | Final Result | Source       |
+| --------------- | ---------------- | ------------ | ------------ |
+| `true`          | `false`          | ✅ `true`     | `user`       |
+| `false`         | `true`           | ❌ `false`    | `user`       |
+| *(none)*        | `true`           | ✅ `true`     | `group:name` |
+| *(none)*        | *(none)*         | ❌ `false`    | `none`       |
+
+---
+
 ## 🔧 Installation
 
 > ⚠️ No public releases yet. Clone and build manually.