diff --git a/README.md b/README.md
index 97413b9e..9ff81e42 100644
--- a/README.md
+++ b/README.md
@@ -406,11 +406,11 @@ madengine discovers models from the MAD package using three methods:
 # Root models (models.json)
 madengine discover --tags pyt_huggingface_bert
 
-# Directory-specific (scripts/{dir}/models.json)
-madengine discover --tags dummy2:dummy_2
+# Directory-specific (scripts/{dir}/models.json), scoped tag: {dir}/{model_or_tag}
+madengine discover --tags dummy2/model1
 
 # Dynamic with parameters (scripts/{dir}/get_models_json.py)
-madengine discover --tags dummy3:dummy_3:batch_size=512
+madengine discover --tags dummy3/model3:batch_size=512
 ```
 
 ## 📊 Performance Profiling
diff --git a/docs/cli-reference.md b/docs/cli-reference.md
index 5bfd8ade..842e0fdf 100644
--- a/docs/cli-reference.md
+++ b/docs/cli-reference.md
@@ -65,11 +65,11 @@ madengine discover --tags dummy,multi,vllm
 # With verbose output
 madengine discover --tags model --verbose
 
-# Directory-specific models
-madengine discover --tags dummy2:dummy_2
+# Directory-specific models (scoped tag: {dir}/{model_or_tag})
+madengine discover --tags dummy2/model1
 
 # Dynamic models with parameters
-madengine discover --tags dummy3:dummy_3:batch_size=512
+madengine discover --tags dummy3/model3:batch_size=512
 ```
 
 **Discovery Methods:**
diff --git a/docs/usage.md b/docs/usage.md
index 24c10166..f06557bb 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -87,18 +87,18 @@ madengine discover --tags dummy pyt_huggingface_bert
 
 ### 2. Directory-Specific Models
 
-Models organized in subdirectories (`scripts/{dir}/models.json`):
+Models organized in subdirectories (`scripts/{dir}/models.json`), selected with scoped tags (`{dir}/{model_or_tag}`):
 
 ```bash
-madengine discover --tags dummy2:dummy_2
+madengine discover --tags dummy2/model1
 ```
 
 ### 3. Dynamic Models with Parameters
 
-Python-generated models (`scripts/{dir}/get_models_json.py`):
+Python-generated models (`scripts/{dir}/get_models_json.py`), with extra args passed after `:`:
 
 ```bash
-madengine discover --tags dummy3:dummy_3:batch_size=512:in=32
+madengine discover --tags dummy3/model3:batch_size=512:in=32
 ```
 
 ## Build Workflow