Fix documentation based on PR feedback: update doc count to 263, clarify hooks, add AVM details

Co-authored-by: diberry <[email protected]>

Author: Copilot

docs/01-getting-started.md

@@ -53,19 +53,16 @@ azd up
 
 ### 4. Wait for Document Indexing
 
-After deployment completes, the system will automatically index PDF documents into Azure AI Search. The sample includes **262 documents** that need to be indexed before you can use the `/answer` endpoint effectively.
+After deployment completes, the system will automatically index PDF documents into Azure AI Search. The sample includes **263 documents** that need to be indexed before you can use the `/answer` endpoint effectively.
 
 You can check the indexing status in the deployment output, or use the Azure Portal to view your Azure AI Search service.
 
 ### 5. Test the API
 
-Once indexing is complete, you can test the API:
+Once indexing is complete, you can test the API using the URL displayed at the end of the `azd up` command:
 
 ```bash
-# Get the deployed app URL from azd
-azd env get-values | grep SERVICE_API_URI
-
-# Test the API
+# Test the API (use the URL from azd up output)
 curl -X POST <YOUR_API_URL>/answer \
   -H "Content-Type: application/json" \
   -d '{"question": "What are the standard benefit options?"}'
@@ -90,7 +87,7 @@ If deployment fails, check:
 ### Can't Query Documents
 
 If queries return empty results:
-- Ensure all 262 documents are indexed (check `INDEX_DOCUMENT_COUNT` in environment variables)
+- Ensure all 263 documents are indexed (check `INDEX_DOCUMENT_COUNT` in environment variables)
 - Wait a few minutes after deployment for indexing to complete
 - Check the Azure AI Search service in the Azure Portal
 

docs/02-local-development.md

@@ -62,13 +62,9 @@ This will install dependencies for both the root project and all workspace packa
 
 ### 2. Configure Environment Variables
 
-Create a `.env` file in the repository root:
+**Prerequisites**: Complete the `azd up` deployment first (see [Getting Started](./01-getting-started.md)), which automatically creates the `.env` file with all necessary Azure resource information.
 
-```bash
-cp sample.env .env
-```
-
-Edit `.env` with your Azure resource information:
+If you need to manually update environment variables, edit the `.env` file in the repository root:
 
 ```bash
 # Azure OpenAI
@@ -132,14 +128,16 @@ The API server will start on `http://localhost:3000`.
 
 ### Working with Vector Data
 
+**Note**: If you deployed with `azd up`, vector data is already loaded. These commands are only needed if you're setting up from scratch without using `azd up`.
+
 ```bash
-# Load PDF documents into Azure AI Search index
+# Load PDF documents into Azure AI Search index (only needed if not using azd up)
 npm run load_data
 
-# Test embedding generation
+# Test embedding generation (useful for verifying Azure OpenAI authentication)
 npm run embed
 
-# Test LLM completion
+# Test LLM completion (useful for verifying Azure OpenAI authentication)
 npm run llm
 ```
 

docs/03-infrastructure-deployment.md

@@ -141,7 +141,6 @@ All configuration is injected as environment variables:
 - Azure OpenAI instance names and model names
 - API versions for completions and embeddings
 - `SET_PASSWORDLESS=true` for managed identity authentication
-- `AZURE_CLIENT_ID` for the managed identity
 
 ## Deployment Commands
 
@@ -162,29 +161,29 @@ This runs the complete deployment pipeline:
 
 ### Incremental Commands
 
+**Note**: These commands are handled automatically by `azd up` hooks. You typically won't need to run them manually unless you're doing custom development.
+
 ```bash
 # Provision/update infrastructure only
 azd provision
 
 # Deploy application code only (infrastructure must exist)
 azd deploy
 
-# View environment variables
-azd env get-values
-
-# Set environment variable
-azd env set KEY value
-
 # Delete all resources
-azd down
+azd down --purge
 ```
 
+**About `--purge` flag**: Using `azd down --purge` immediately releases Azure resource quotas. Without `--purge`, some resources (like OpenAI deployments) may hold quota for up to 48 hours, which could prevent redeployment.
+
 ## Bicep Infrastructure as Code
 
-The `infra/main.bicep` file uses Azure Verified Modules (AVM) for best-practice resource configuration:
+The `infra/main.bicep` file uses [Azure Verified Modules (AVM)](https://azure.github.io/Azure-Verified-Modules/) for best-practice resource configuration.
+
+**Why use AVM?** Azure Verified Modules provide pre-built, tested, and maintained Bicep modules that follow Microsoft's best practices. Instead of writing raw Bicep resource definitions, you use these curated modules which handle security, networking, and configuration complexity for you. This reduces errors and ensures your infrastructure follows Azure's recommended patterns.
 
 ```bicep
-// Example: OpenAI deployment
+// Example: OpenAI deployment using AVM
 module openAi 'br/public:avm/res/cognitive-services/account:0.7.1' = {
   params: {
     name: openAiServiceName
@@ -203,10 +202,11 @@ module openAi 'br/public:avm/res/cognitive-services/account:0.7.1' = {
 }
 ```
 
-### Benefits of Bicep:
+### Benefits of Bicep with AVM:
 - **Type safety**: Catch errors at compile time
 - **Intellisense**: Editor support for Azure resource properties
 - **Modularity**: Reusable modules from Azure Verified Modules
+- **Best practices built-in**: Security, networking, and configuration handled correctly
 - **Idempotent**: Safe to run multiple times
 - **Declarative**: Describe desired state, not steps
 
@@ -217,16 +217,28 @@ module openAi 'br/public:avm/res/cognitive-services/account:0.7.1' = {
 The environment name is used to generate unique resource names:
 
 ```bash
-# Resource naming pattern
-${environmentName}${resourceToken}-{service}
-
-# Example with environmentName="lang-exam"
-lang-examxxxxxxxxxxxxx-openai
-lang-examxxxxxxxxxxxxx-search
-lang-examxxxxxxxxxxxxx-rg
+# Resource naming pattern (from infra/main.bicep)
+var prefix = '${environmentName}${resourceToken}'
 ```
 
-**Important**: Keep environment names short (7-10 characters) to avoid exceeding Azure resource name length limits.
+**Important**: Environment name must be **lowercase** and kept short (7-10 characters) to avoid exceeding Azure resource name length limits.
+
+### Resource Naming Table
+
+Based on the Bicep template (`infra/main.bicep`), here are the actual resource names created:
+
+| Resource Type | Naming Pattern | Example (env="langexam") |
+|--------------|----------------|--------------------------|
+| Resource Group | `${prefix}-rg` | `langexamxxxxxxxxxxxxx-rg` |
+| OpenAI Service | `${prefix}-openai` | `langexamxxxxxxxxxxxxx-openai` |
+| AI Search | `${prefix}-search` | `langexamxxxxxxxxxxxxx-search` |
+| Container Registry | `${prefix}acr` (no hyphens) | `langexamxxxxxxxxxxxxxacr` |
+| Log Analytics | `${prefix}-logs` | `langexamxxxxxxxxxxxxx-logs` |
+| Container Apps Environment | `${prefix}-env` | `langexamxxxxxxxxxxxxx-env` |
+| Managed Identity | `${prefix}-identity` | `langexamxxxxxxxxxxxxx-identity` |
+| Container App | `app-${resourceToken}` | `app-xxxxxxxxxxxxx` |
+
+Where `prefix = environmentName + resourceToken` (13-char hash).
 
 ### Resource Token
 
@@ -246,6 +258,16 @@ The application is currently configured to deploy to specific regions with OpenA
 
 These regions support the required GPT and embedding models. See [Azure OpenAI Model Availability](https://learn.microsoft.com/azure/ai-services/openai/concepts/models) for the latest regional information.
 
+**To update allowed regions**: Edit the `location` parameter's `@allowed` array in `infra/main.bicep` (lines 11-15):
+
+```bicep
+@allowed([
+  'eastus2'
+  'swedencentral'
+])
+param location string
+```
+
 ## Monitoring and Troubleshooting
 
 ### View Application Logs
@@ -292,7 +314,7 @@ The resources created incur costs:
 
 **Tip**: Delete resources when not in use:
 ```bash
-azd down
+azd down --purge
 ```
 
 ## Additional Resources

docs/04-testing-with-http-files.md

@@ -216,7 +216,7 @@ If answers are empty or low quality:
    ```bash
    azd env get-values | grep INDEX_DOCUMENT_COUNT
    ```
-   Should show 262 documents.
+   Should show 263 documents.
 
 2. **Verify Azure AI Search connection**:
    - Check `AZURE_AISEARCH_ENDPOINT` in `.env`
@@ -251,7 +251,7 @@ See [Azure Identity Authentication](./05-azure-identity-authentication.md) for m
 1. **Use descriptive questions**: Clear, specific questions get better answers
 2. **Test incrementally**: Start with simple questions, then try complex ones
 3. **Check server logs**: Monitor console output for errors and performance
-4. **Wait for indexing**: Ensure all 262 documents are indexed before testing
+4. **Wait for indexing**: Ensure all 263 documents are indexed before testing
 5. **Version control**: Don't commit `.http` files with production URLs or sensitive data
 
 ## Creating Your Own Test Files

docs/05-azure-identity-authentication.md

@@ -70,6 +70,8 @@ export async function azureADTokenProvider_OpenAI() {
 }
 ```
 
+**About the token provider**: The `azureADTokenProvider` is specific to third-party SDKs like LangChain that don't natively support Azure SDK authentication patterns. When using official Azure SDKs (like `@azure/search-documents`), you can pass the `DefaultAzureCredential` directly without a token provider. However, LangChain's `@langchain/openai` package requires a token provider function that returns a string token, hence this wrapper.
+
 This token provider is used when initializing Azure OpenAI clients in LangChain:
 
 **File**: `packages-v1/langgraph-agent/src/azure/llm.ts`

docs/07-azure-ai-search-vector-store.md

@@ -11,7 +11,7 @@ This guide explains how the application uses Azure AI Search as a vector databas
 - **Scalability**: Handle millions of documents
 
 This application uses Azure AI Search to:
-1. Store embeddings of PDF documents (262 documents)
+1. Store embeddings of PDF documents (263 documents)
 2. Perform similarity search to find relevant documents
 3. Provide context for the LangChain RAG (Retrieval Augmented Generation) system
 
@@ -85,7 +85,7 @@ The application loads documents from the `packages-v1/langgraph-agent/data/` dir
 - **12 JSON files**: Structured data examples
 - **PDF files** (assumed): Employee handbook, benefits documentation
 
-Total: **262 document chunks** after processing
+Total: **263 document chunks** after processing
 
 ### Loading Process
 
@@ -185,11 +185,11 @@ Other search types available (not used in this sample):
 - **`SimilarityHybrid`**: Combines vector and keyword search
 - **`SemanticHybrid`**: Uses semantic ranking for better relevance
 
-## Document Count: 262 Documents
+## Document Count: 263 Documents
 
 ### Why This Matters
 
-The application needs **all 262 documents indexed** before the `/answer` endpoint works effectively:
+The application needs **all 263 documents indexed** before the `/answer` endpoint works effectively:
 
 - **Incomplete index**: May return poor or irrelevant answers
 - **Complete index**: Provides comprehensive context for questions
@@ -202,7 +202,7 @@ azd env get-values | grep INDEX_
 
 # Expected output:
 # INDEX_CREATED=true
-# INDEX_DOCUMENT_COUNT=262
+# INDEX_DOCUMENT_COUNT=263
 ```
 
 ### Indexing Time
@@ -226,7 +226,7 @@ postdeploy:
     else
       npm run load_data
       azd env set INDEX_CREATED true
-      azd env set INDEX_DOCUMENT_COUNT 262
+      azd env set INDEX_DOCUMENT_COUNT 263
     fi
 ```
 
@@ -385,7 +385,7 @@ If queries return no documents:
    ```bash
    azd env get-values | grep INDEX_DOCUMENT_COUNT
    ```
-   Should show 262.
+   Should show 263.
 
 3. **Verify authentication**: Ensure passwordless auth is working
 
@@ -417,7 +417,7 @@ Azure AI Search pricing depends on:
 This sample uses:
 - **SKU**: Basic (~$75/month)
 - **Replicas**: 1 (no high availability)
-- **Partitions**: 1 (sufficient for 262 documents)
+- **Partitions**: 1 (sufficient for 263 documents)
 
 **Cost optimization**:
 - Use Basic tier for development

docs/README.md

@@ -74,7 +74,7 @@ See [Azure Container Apps](./06-azure-container-apps.md) for details.
 
 ### Vector Store Indexing
 
-The application loads **262 documents** into Azure AI Search as embedding vectors. You must wait for indexing to complete before using the `/answer` endpoint.
+The application loads **263 documents** into Azure AI Search as embedding vectors. You must wait for indexing to complete before using the `/answer` endpoint.
 
 See [Azure AI Search Vector Store](./07-azure-ai-search-vector-store.md) for details.
 
@@ -137,8 +137,8 @@ See [Azure Container Apps](./06-azure-container-apps.md) and [Azure AI Search Ve
 
 ### Empty or Poor Answers
 
-- Wait for all 262 documents to be indexed
-- Check `INDEX_DOCUMENT_COUNT` equals 262
+- Wait for all 263 documents to be indexed
+- Check `INDEX_DOCUMENT_COUNT` equals 263
 - Verify Azure AI Search and OpenAI are accessible
 - Review application logs for errors
 
@@ -165,7 +165,7 @@ See [Azure Container Apps](./06-azure-container-apps.md) and [Azure AI Search Ve
 ┌─────────────────────────┐      ┌──────────────────────────┐
 │  Azure OpenAI           │      │  Azure AI Search         │
 │  ├─ GPT-4 (completion) │      │  ├─ Index: northwind     │
-│  └─ Embeddings          │      │  └─ 262 vector docs      │
+│  └─ Embeddings          │      │  └─ 263 vector docs      │
 └─────────────────────────┘      └──────────────────────────┘
 ```