From 624ce828fd60b005796c90c4ee684d515eb5881c Mon Sep 17 00:00:00 2001
From: mahdahar <89adham@gmail.com>
Date: Wed, 7 Jan 2026 06:38:09 +0700
Subject: [PATCH] create agents.md for valueset scanning

---
 AGENTS.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5af0c47
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,86 @@
+# Valueset Data Scanning - Agent Instructions
+
+## Quick Reference
+
+**Database Tables:**
+- [`valuesetdef`](app/Models/ValueSet/ValueSetDefModel.php:8) - Category definitions (VSetID, VSName, VSDesc)
+- [`valueset`](app/Models/ValueSet/ValueSetModel.php:8) - Actual values (VID, VSetID, VValue, VDesc, VOrder)
+
+## Agent Workflow for Valueset Queries
+
+### Step 1: Identify the Request Type
+
+**Category Search:**
+```
+User: "Show me all values in [CATEGORY_NAME]"
+Agent: Search valuesetdef by VSName → Get VSetID → Query values by VSetID
+```
+
+**Reference Search:**
+```
+User: "Show me values for [TABLE.COLUMN]"
+Agent: Search valuesetdef by VSDesc → Get VSetID → Query values by VSetID
+```
+
+**ID Search:**
+```
+User: "Show me values for VSetDefID [ID]"
+Agent: Directly query values by VSetID
+```
+
+**Filtered Search:**
+```
+User: "Find values containing [TERM] in [CATEGORY]"
+Agent: Search valuesetdef by VSName → Get VSetID → Query values with LIKE filter
+```
+
+### Step 2: Execute Query
+
+**Model Methods:**
+- [`ValueSetDefModel::getValueSetDefs($param)`](app/Models/ValueSet/ValueSetDefModel.php:18) - Search categories
+- [`ValueSetModel::getValueSetByValueSetDef($VSetID)`](app/Models/ValueSet/ValueSetModel.php:52) - Get values by category
+- [`ValueSetModel::getValueSets($param, $page, $limit, $VSetID)`](app/Models/ValueSet/ValueSetModel.php:18) - Get values with filters
+
+### Step 3: Return Results
+
+**Response Format:**
+```json
+{
+  "VSetID": 27,
+  "VSName": "Test Type",
+  "values": [
+    { "VID": 1, "VValue": "TEST", "VDesc": "Test", "VOrder": 1 },
+    { "VID": 2, "VValue": "PARAM", "VDesc": "Parameter", "VOrder": 2 }
+  ]
+}
+```
+
+## Common Valuesets
+
+| VSetDefID | VSName | VSDesc | Search Keywords |
+|-----------|--------|--------|-----------------|
+| 3 | Gender | - | gender, sex |
+| 27 | Test Type | `testdefsite.TestType` | test, type, testdefsite |
+| 15 | Specimen Type | - | specimen, type, blood, urine |
+| 31 | Range Types | `refnum.RangeType` | range, refnum |
+| 46 | Num Ref Type | `refnum.NumRefType` | numeric, reference |
+
+## Example Agent Conversations
+
+**User:** "Show me Gender values"
+**Agent:**
+1. `getValueSetDefs("Gender")` → VSetID = 3
+2. `getValueSetByValueSetDef(3)` → Returns values
+3. Output: Female, Male, Unknown
+
+**User:** "What values for testdefsite.TestType?"
+**Agent:**
+1. `getValueSetDefs("testdefsite.TestType")` → VSetID = 27
+2. `getValueSetByValueSetDef(27)` → Returns values
+3. Output: TEST, PARAM, CALC, GROUP, TITLE
+
+**User:** "Find values with 'STAT' in Priority"
+**Agent:**
+1. `getValueSetDefs("Priority")` → VSetID = 1
+2. `getValueSets("STAT", null, 50, 1)` → Returns matching values
+3. Output: STAT, STAT2 (if exists)