commit 16 / docs fixes to clarity path for script executions

docs/1-Hybrid-Workshop/2-Setup/01.md

@@ -25,6 +25,12 @@ Note: If you had previously created projects, those will be listed as shown abov
 1. Change the default project name to something memorable - I used `ninarasi-ragchat-v1`.
 1. We also want to create a new hub for our new AI project - let's fix that next in the dialog.
 
+??? warning "TROUBLESHOOTING: Your _Create a project_ dialog looks different. (Click to expand)"
+
+    You may see a dialog like this instead. This is typically the case when you don't have a pre-existing Hub selection and the workflow now automatically adds a default Hub resource. In this case, customize the project name as specified in step 1 above, then skip the [step 3](#3-create-new-hub) below and go directly to customize the hub name as described in [step 4](#4-customize-the-hub) **to complete the dialog**.
+
+    ![Create alt](./../img/create-project-alt.png)
+
 ---
 
 ## 3. Create new hub

docs/1-Hybrid-Workshop/2-Setup/07.md

@@ -36,7 +36,7 @@ Note that defaults are provided for everything except the `AIPROJECT_CONNECTION_
 
 1. Open the Azure AI Project overview page. It should look like this:
 
-    ![Project](./../img/p1-01-create/p1-create-project-08.png)
+    ![Project](./../img/p1-01-create/p1-update-conn-string.png)
 
 1. Look for the **Project connection string** under the _Project details_ tab. 
 1. Copy that into `.env` as the _AIPROJECT_CONNECTION_STRING_ value.

docs/1-Hybrid-Workshop/3-Ideate/01.md

@@ -14,9 +14,13 @@ We want to ground chat AI responses in our application data. In this case, we wa
 
 Recall that the `src/config.py` script identifies the `assets/` folder as the source for all static assets. We already created the `src/api/assets` earlier.  Let's copy in the product catalog data into this folder now.
 
-```bash title=""
-cp src.sample/api/assets/products.csv  src/api/assets/
-```
+
+1. Make sure you are in the root directory of the repo.
+1. Then run this command:
+
+    ```bash title=""
+    cp src.sample/api/assets/products.csv  src/api/assets/
+    ```
 
 ---
 

docs/1-Hybrid-Workshop/3-Ideate/02.md

@@ -4,9 +4,12 @@
 
  Let's copy over the `create-search-index.py` script into our application source folder.
 
-```bash title=""
-cp src.sample/api/create-search-index.py  src/api/.
-```
+1. Make sure you are in the root directory of the repo.
+1. Then run this command:
+
+    ```bash title=""
+    cp src.sample/api/create-search-index.py  src/api/.
+    ```
 
 ---
 
@@ -74,11 +77,19 @@ It then **creates the index from CSV** and populates it using the index_client.
 
 ## 3. Run Index Creation Script
 
-To get the index created in Azure AI Search, run the script described above.
+To get the index created in Azure AI Search, 
 
-```bash title=""
-python create-search-index.py
-```
+1. Change to the `src/api` folder 
+
+    ```bash title=""
+    cd src/api
+    ```
+
+1. Run the script:
+
+    ```bash title=""
+    python create-search-index.py
+    ```
 
 ---
 

docs/1-Hybrid-Workshop/3-Ideate/03.md

@@ -4,9 +4,12 @@
 
  Let's copy over the `get_product_documents.py` script into our application source folder.
 
-```bash title=""
-cp src.sample/api/get_product_documents.py  src/api/.
-```
+1. Make sure you are in the root directory of the repo.
+1. Then run this command:
+
+    ```bash title=""
+    cp src.sample/api/get_product_documents.py  src/api/.
+    ```
 
 ---
 

docs/1-Hybrid-Workshop/3-Ideate/04.md

@@ -2,28 +2,41 @@
 
 ## 1. Add Intent Mapping Prompty
 
- Let's copy over the `intent_mapping.prompty` prompt template into our assets folder.
+Let's copy over the `intent_mapping.prompty` prompt template into our assets folder.
 
-```bash title=""
-cp src.sample/api/assets/intent_mapping.prompty src/api/assets/.
-```
+1. Make sure you are in the root directory of the repo.
+1. Then run this command:
+
+    ```bash title=""
+    cp src.sample/api/assets/intent_mapping.prompty src/api/assets/.
+    ```
 
 ---
 
 ## 2. Run Docs Retrieval Script
 
 Before we dive into the details of that file, let's first run the document retrieval script and see what happens. Here's an example with the question we discussed earlier.
 
-```bash title=""
-python get_product_documents.py --query "I need a new tent for 4 people, what would you recommend?"
-```
+1. Change to the `src/api` folder 
+
+    ```bash title=""
+    cd src/api
+    ```
+
+1. Run the script:
 
-```bash title="Response may look like this"
-🧠 Intent mapping: {
-    "intent": "The user is looking for recommendations for a tent suitable for 4 people.",
-    "search_query": "best tents for 4 people"
-}
-```
+    ```bash title=""
+    python get_product_documents.py --query "I need a new tent for 4 people, what would you recommend?"
+    ```
+
+1. Observe the response. It may look like this:
+
+    ```bash title=""
+    🧠 Intent mapping: {
+        "intent": "The user is looking for recommendations for a tent suitable for 4 people.",
+        "search_query": "best tents for 4 people"
+    }
+    ```
 
 The script output shows that it extracted the user intent and formulated a search query from it that related to a product ("best tents for 4 people") - and can be answered by the search index.
 

docs/1-Hybrid-Workshop/3-Ideate/05.md

@@ -4,9 +4,12 @@
 
  Let's copy over the `chat_with_products.py` script into our application source.
 
-```bash title=""
-cp src.sample/api/chat_with_products.py src/api/.
-```
+1. Make sure you are in the root directory of the repo.
+1. Then run this command:
+
+    ```bash title=""
+    cp src.sample/api/chat_with_products.py src/api/.
+    ```
 
 ---
 

docs/1-Hybrid-Workshop/3-Ideate/06.md

@@ -4,9 +4,12 @@
 
  Let's copy over the `grounded_chat.prompty` prompt template into our assets folder.
 
-```bash title=""
-cp src.sample/api/assets/grounded_chat.prompty src/api/assets/.
-```
+1. Make sure you are in the root directory of the repo.
+1. Then run this command:
+
+    ```bash title=""
+    cp src.sample/api/assets/grounded_chat.prompty src/api/assets/.
+    ```
 
 ---
 
@@ -52,15 +55,23 @@ Explore the contents of this template. Notice how the `system` context provides
 
 Run the script with a test query (from the `src/api` folder). 
 
-```bash title=""
-python chat_with_products.py --query "I need a new tent for 4 people, what would you recommend?"
-```
+1. Change to the `src/api` folder 
+
+    ```bash title=""
+    cd src/api
+    ```
+
+1. Run the script:
+
+    ```bash title=""
+    python chat_with_products.py --query "I need a new tent for 4 people, what would you recommend?"
+    ```
 
-Observe the response. It may look like this:
+1. Observe the response. It may look like this:
 
-```bash title=""
-💬 Response: {'content': "I recommend the TrailMaster X4 Tent. It is specifically designed to accommodate four occupants comfortably. The tent features durable water-resistant construction, multiple doors for easy access, and mesh panels for ventilation and bug protection. Additionally, it has a freestanding design for easy setup and relocation, as well as interior pockets for organization. It's a great choice for your camping adventures!", 'role': 'assistant'}
-```
+    ```bash title=""
+    💬 Response: {'content': "I recommend the TrailMaster X4 Tent. It is specifically designed to accommodate four occupants comfortably. The tent features durable water-resistant construction, multiple doors for easy access, and mesh panels for ventilation and bug protection. Additionally, it has a freestanding design for easy setup and relocation, as well as interior pockets for organization. It's a great choice for your camping adventures!", 'role': 'assistant'}
+    ```
 
 **Is the response grounded in product data from the catalog?** 
 
@@ -70,14 +81,18 @@ Observe the response. It may look like this:
 
 Try asking a question that does not relate to the hiking and camping topic:
 
-```bash title=""
-python chat_with_products.py --query "I am looking for a recipe for spicy bean burgers"
-```
+1. Verify you are still in the `src/api` folder. 
+
+1. Then run this script:
 
-Observe the response. It may look like this:
+    ```bash title=""
+    python chat_with_products.py --query "I am looking for a recipe for spicy bean burgers"
+    ```
+
+1. Observe the response. It may look like this:
 
-```bash title=""
-💬 Response: {'content': 'Sorry, I only can answer queries related to outdoor/camping gear and clothing. So, how can I help?', 'role': 'assistant'}
-```
+    ```bash title=""
+    💬 Response: {'content': 'Sorry, I only can answer queries related to outdoor/camping gear and clothing. So, how can I help?', 'role': 'assistant'}
+    ```
 
 **Is this response relevant and grounded in the context for this application?** 

docs/1-Hybrid-Workshop/3-Ideate/07.md

@@ -1,24 +1,32 @@
 # 3.7 Test with Observability
 
-Recall that we activated Application Insights during the setup phase of our projec. This now allows to ask questions _with telemetry enabled_ and get observable traces using _open telemetry_, to help us analyze the cost or performance of our workflows.
+Recall that we activated Application Insights during the setup phase of our project. This now allows to ask questions _with telemetry enabled_ and get observable traces using _open telemetry_, to help us analyze the cost or performance of our workflows.
 
 Let's see this in action.
 
 ## 1. Enable Telemetry on Test
 
+1. Change to the `src/api` folder 
+
+    ```bash title=""
+    cd src/api
+    ```
+
+1. Run the script:
 Run the `Chat with Products` script with `--enable-telemetry` as shown.
 
 
-```bash title=""
-python chat_with_products.py --query "I need hiking gear for a trip to Andalusia - what tents and boots do you recommend?" --enable-telemetry
-```
+    ```bash title=""
+    python chat_with_products.py --query "I need hiking gear for a trip to Andalusia - what tents and boots do you recommend?" --enable-telemetry
+    ```
 
-You should see something like this in the console. Let's explore this next.
-```bash title=""
-Enabled telemetry logging to project, view traces at:
-https://ai.azure.com/tracing?wsid=/subscriptions/XXXX/resourceGroups/ninarasi-ragchat-rg/providers/Microsoft.MachineLearningServices/workspaces/ninarasi-ragchat-v1
-💬 Response: {'content': "For your trip to Andalusia, I recommend the following tents and boots:\n\n**Tents:**\n1. **Alpine Explorer Tent**: This robust, 8-person, 3-season tent is perfect for group camping. It has multiple mesh windows for ventilation and a detachable divider for privacy. Its waterproof feature ensures you stay dry during unexpected rain.\n\n2. **SkyView 2-Person Tent**: If you're looking for a smaller option, this tent comfortably houses two people and is made from durable waterproof materials. It also features an intuitive setup system, effective ventilation, and a rainfly for extra weather protection, making it great for hiking and camping.\n\n**Boots:**\n1. **TrekReady Hiking Boots**: These boots are crafted from leather, ensuring durability and comfort on long hikes. They have a moisture-wicking lining, shock-absorbing midsoles, and excellent traction, making them suitable for various terrains.\n\n2. **TrekStar Hiking Sandals**: If you prefer something lighter and more breathable, consider these lightweight sandals. They offer adjustable straps, excellent traction, toe protection, and a cushioned footbed for comfort during summer treks.\n\nChoose based on your group size and hiking preferences, and you'll be well-prepared for your adventure in Andalusia!", 'role': 'assistant'}
-```
+1. You should see something like this in the console. Let's explore this next.
+
+    ```bash title=""
+    Enabled telemetry logging to project, view traces at:
+    https://ai.azure.com/tracing?wsid=/subscriptions/XXXX/resourceGroups/ninarasi-ragchat-rg/providers/Microsoft.MachineLearningServices/workspaces/ninarasi-ragchat-v1
+    💬 Response: {'content': "For your trip to Andalusia, I recommend the following tents and boots:\n\n**Tents:**\n1. **Alpine Explorer Tent**: This robust, 8-person, 3-season tent is perfect for group camping. It has multiple mesh windows for ventilation and a detachable divider for privacy. Its waterproof feature ensures you stay dry during unexpected rain.\n\n2. **SkyView 2-Person Tent**: If you're looking for a smaller option, this tent comfortably houses two people and is made from durable waterproof materials. It also features an intuitive setup system, effective ventilation, and a rainfly for extra weather protection, making it great for hiking and camping.\n\n**Boots:**\n1. **TrekReady Hiking Boots**: These boots are crafted from leather, ensuring durability and comfort on long hikes. They have a moisture-wicking lining, shock-absorbing midsoles, and excellent traction, making them suitable for various terrains.\n\n2. **TrekStar Hiking Sandals**: If you prefer something lighter and more breathable, consider these lightweight sandals. They offer adjustable straps, excellent traction, toe protection, and a cushioned footbed for comfort during summer treks.\n\nChoose based on your group size and hiking preferences, and you'll be well-prepared for your adventure in Andalusia!", 'role': 'assistant'}
+    ```
 
 ---