diff --git a/app/Config/Routes.php b/app/Config/Routes.php
index 7924d6b..7cb4334 100644
--- a/app/Config/Routes.php
+++ b/app/Config/Routes.php
@@ -126,18 +126,33 @@ $routes->group('api', function ($routes) {
         $routes->patch('/', 'Contact\MedicalSpecialtyController::update');
     });
 
+    // Lib ValueSet (file-based)
     $routes->group('valueset', function ($routes) {
         $routes->get('/', 'ValueSetController::index');
         $routes->get('(:any)', 'ValueSetController::index/$1');
         $routes->post('refresh', 'ValueSetController::refresh');
 
-        $routes->get('items', 'ValueSetController::items');
-        $routes->get('items/(:num)', 'ValueSetController::showItem/$1');
-        $routes->post('items', 'ValueSetController::createItem');
-        $routes->put('items/(:num)', 'ValueSetController::updateItem/$1');
-        $routes->delete('items/(:num)', 'ValueSetController::deleteItem/$1');
+        // User ValueSet (database-based)
+        $routes->group('user', function ($routes) {
+            $routes->group('items', function ($routes) {
+                $routes->get('/', 'ValueSetController::items');
+                $routes->get('(:num)', 'ValueSetController::showItem/$1');
+                $routes->post('/', 'ValueSetController::createItem');
+                $routes->put('(:num)', 'ValueSetController::updateItem/$1');
+                $routes->delete('(:num)', 'ValueSetController::deleteItem/$1');
+            });
+
+            $routes->group('def', function ($routes) {
+                $routes->get('/', 'ValueSetDefController::index');
+                $routes->get('(:num)', 'ValueSetDefController::show/$1');
+                $routes->post('/', 'ValueSetDefController::create');
+                $routes->put('(:num)', 'ValueSetDefController::update/$1');
+                $routes->delete('(:num)', 'ValueSetDefController::delete/$1');
+            });
+        });
     });
 
+    // Result ValueSet
     $routes->group('result', function ($routes) {
         $routes->group('valueset', function ($routes) {
             $routes->get('/', 'Result\ResultValueSetController::index');
@@ -146,14 +161,6 @@ $routes->group('api', function ($routes) {
             $routes->put('(:num)', 'Result\ResultValueSetController::update/$1');
             $routes->delete('(:num)', 'Result\ResultValueSetController::delete/$1');
         });
-
-        $routes->group('valuesetdef', function ($routes) {
-            $routes->get('/', 'ValueSetDefController::index');
-            $routes->get('(:num)', 'ValueSetDefController::show/$1');
-            $routes->post('/', 'ValueSetDefController::create');
-            $routes->put('(:num)', 'ValueSetDefController::update/$1');
-            $routes->delete('(:num)', 'ValueSetDefController::delete/$1');
-        });
     });
 
     // Counter
diff --git a/public/api-docs.yaml b/public/api-docs.yaml
index 320a8f1..8ea0d04 100644
--- a/public/api-docs.yaml
+++ b/public/api-docs.yaml
@@ -2222,18 +2222,49 @@ paths:
   /api/valueset:
     get:
       tags: [ValueSets]
-      summary: List value set definitions
+      summary: List lib value sets
+      description: List all library/system value sets from JSON files
       security:
         - bearerAuth: []
       parameters:
-        - name: VSetCode
-          in: path
-          description: Optional value set code to get specific valueset
+        - name: search
+          in: query
           schema:
             type: string
+          description: Optional search term to filter value sets
       responses:
         '200':
-          description: List of value sets
+          description: List of lib value sets with item counts
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  status:
+                    type: string
+                  data:
+                    type: object
+                    additionalProperties:
+                      type: integer
+                      description: Number of items in each value set
+
+  /api/valueset/{key}:
+    get:
+      tags: [ValueSets]
+      summary: Get lib value set by key
+      description: Get a specific library/system value set from JSON files
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: key
+          in: path
+          required: true
+          schema:
+            type: string
+          description: Value set key (e.g., marital_status, sex)
+      responses:
+        '200':
+          description: Lib value set details
           content:
             application/json:
               schema:
@@ -2244,23 +2275,29 @@ paths:
                   data:
                     type: array
                     items:
-                      $ref: '#/components/schemas/ValueSetDef'
+                      type: object
+                      properties:
+                        value:
+                          type: string
+                        label:
+                          type: string
 
   /api/valueset/refresh:
     post:
       tags: [ValueSets]
-      summary: Refresh ValueSet cache
-      description: Clear and reload the ValueSet library cache
+      summary: Refresh lib ValueSet cache
+      description: Clear and reload the library/system ValueSet cache from JSON files
       security:
         - bearerAuth: []
       responses:
         '200':
-          description: Cache refreshed
+          description: Lib ValueSet cache refreshed
 
-  /api/valueset/items:
+  /api/valueset/user/items:
     get:
       tags: [ValueSets]
-      summary: List value set items
+      summary: List user value set items
+      description: List value set items from database (user-defined)
       security:
         - bearerAuth: []
       parameters:
@@ -2271,7 +2308,7 @@ paths:
           description: Filter by ValueSet ID
       responses:
         '200':
-          description: List of value set items
+          description: List of user value set items
           content:
             application/json:
               schema:
@@ -2284,7 +2321,8 @@ paths:
 
     post:
       tags: [ValueSets]
-      summary: Create value set item
+      summary: Create user value set item
+      description: Create value set item in database (user-defined)
       security:
         - bearerAuth: []
       requestBody:
@@ -2295,12 +2333,13 @@ paths:
               $ref: '#/components/schemas/ValueSetItem'
       responses:
         '201':
-          description: Value set item created
+          description: User value set item created
 
-  /api/valueset/items/{id}:
+  /api/valueset/user/items/{id}:
     get:
       tags: [ValueSets]
-      summary: Get value set item by ID
+      summary: Get user value set item by ID
+      description: Get value set item from database (user-defined)
       security:
         - bearerAuth: []
       parameters:
@@ -2311,11 +2350,12 @@ paths:
             type: integer
       responses:
         '200':
-          description: Value set item details
+          description: User value set item details
 
     put:
       tags: [ValueSets]
-      summary: Update value set item
+      summary: Update user value set item
+      description: Update value set item in database (user-defined)
       security:
         - bearerAuth: []
       parameters:
@@ -2332,11 +2372,12 @@ paths:
               $ref: '#/components/schemas/ValueSetItem'
       responses:
         '200':
-          description: Value set item updated
+          description: User value set item updated
 
     delete:
       tags: [ValueSets]
-      summary: Delete value set item
+      summary: Delete user value set item
+      description: Delete value set item from database (user-defined)
       security:
         - bearerAuth: []
       parameters:
@@ -2347,21 +2388,23 @@ paths:
             type: integer
       responses:
         '200':
-          description: Value set item deleted
+          description: User value set item deleted
 
-  /api/valuesetdef:
+  /api/valueset/user/def:
     get:
       tags: [ValueSets]
-      summary: List value set definitions
+      summary: List user value set definitions
+      description: List value set definitions from database (user-defined)
       security:
         - bearerAuth: []
       responses:
         '200':
-          description: List of value set definitions
+          description: List of user value set definitions
 
     post:
       tags: [ValueSets]
-      summary: Create value set definition
+      summary: Create user value set definition
+      description: Create value set definition in database (user-defined)
       security:
         - bearerAuth: []
       requestBody:
@@ -2372,12 +2415,13 @@ paths:
               $ref: '#/components/schemas/ValueSetDef'
       responses:
         '201':
-          description: Value set definition created
+          description: User value set definition created
 
-  /api/valuesetdef/{id}:
+  /api/valueset/user/def/{id}:
     get:
       tags: [ValueSets]
-      summary: Get value set definition by ID
+      summary: Get user value set definition by ID
+      description: Get value set definition from database (user-defined)
       security:
         - bearerAuth: []
       parameters:
@@ -2388,11 +2432,12 @@ paths:
             type: integer
       responses:
         '200':
-          description: Value set definition details
+          description: User value set definition details
 
     put:
       tags: [ValueSets]
-      summary: Update value set definition
+      summary: Update user value set definition
+      description: Update value set definition in database (user-defined)
       security:
         - bearerAuth: []
       parameters:
@@ -2409,11 +2454,12 @@ paths:
               $ref: '#/components/schemas/ValueSetDef'
       responses:
         '200':
-          description: Value set definition updated
+          description: User value set definition updated
 
     delete:
       tags: [ValueSets]
-      summary: Delete value set definition
+      summary: Delete user value set definition
+      description: Delete value set definition from database (user-defined)
       security:
         - bearerAuth: []
       parameters:
@@ -2424,7 +2470,7 @@ paths:
             type: integer
       responses:
         '200':
-          description: Value set definition deleted
+          description: User value set definition deleted
 
   # ========================================
   # Master Data Routes