From a7e4908575210e38f0e6bc3b4ad23b68b24e6cb6 Mon Sep 17 00:00:00 2001
From: Stephen Shao <yu.shao@amd.com>
Date: Wed, 15 Jul 2026 20:31:43 +0000
Subject: [PATCH] docs(discover): fix stale directory-scoped model tag examples

Colon-separated tags (e.g. dummy2:dummy_2) are parsed as model name plus
extra script args, not directory scope. Directory-scoped selection uses
scope/tag syntax (e.g. dummy2/model1) since #109.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 README.md             | 6 +++---
 docs/cli-reference.md | 6 +++---
 docs/usage.md         | 8 ++++----
 3 files changed, 10 insertions(+), 10 deletions(-)

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