Validate and fix local development setup

- Add scripts/validate-prerequisites.ps1 to check tool versions, git
  submodules, Azure auth, azd environment config, subscription alignment,
  and Fabric/Purview feature readiness before deployment
- Add .env.example as a documented reference of all environment variables
  used by azd and infra/main.bicepparam (not auto-loaded by azd)
- Add docs/local_development.md with step-by-step local setup guide,
  deployment instructions, troubleshooting, and recommended first-run config
- Update .devcontainer/devcontainer.json with postCreateCommand to
  auto-init submodules and run prerequisite validation on container creation
- Update README.md to reference the new local development guide

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Harmanpreet-Microsoft

.devcontainer/devcontainer.json

@@ -10,5 +10,6 @@
         "ghcr.io/azure/azure-dev/azd:latest": {},
         "ghcr.io/devcontainers/features/azure-cli:1": {},
         "ghcr.io/devcontainers/features/powershell:2.0.0": {}
-    }
+    },
+    "postCreateCommand": "git submodule update --init --recursive && pwsh ./scripts/validate-prerequisites.ps1 -SkipAzureChecks"
 }

.env.example

@@ -0,0 +1,73 @@
+# ============================================================
+# Environment Variable Reference for Deploy-Your-AI-Application-In-Production
+# ============================================================
+#
+# This file is a REFERENCE ONLY. It is NOT auto-loaded by azd.
+#
+# The primary way to set these values is via Azure Developer CLI:
+#   azd env new <environment-name>
+#   azd env set <VARIABLE_NAME> <value>
+#
+# Use this file to understand which variables are available and
+# what they control. Copy values into your azd environment with
+# `azd env set` or edit `infra/main.bicepparam` for source-controlled defaults.
+# ============================================================
+
+# ---- Required ----
+
+# Azure subscription ID for deployment
+AZURE_SUBSCRIPTION_ID=
+
+# Azure region (e.g., eastus2). Check service availability before choosing.
+AZURE_LOCATION=eastus2
+
+# Cosmos DB location override (leave empty to use AZURE_LOCATION)
+AZURE_COSMOS_LOCATION=
+
+# Entra object ID of the deploying identity (user, group, or service principal).
+# Set this if Microsoft Graph lookup is blocked in your tenant.
+AZURE_PRINCIPAL_ID=
+
+# Principal type for RBAC assignments (User, Group, or ServicePrincipal)
+AZURE_PRINCIPAL_TYPE=User
+
+# ---- Network-Isolated Deployments (Jump VM credentials) ----
+
+# Jump box VM admin username (default: testvmuser)
+VM_ADMIN_USERNAME=testvmuser
+
+# Jump box VM admin password (use a strong password)
+VM_ADMIN_PASSWORD=
+
+# ---- PostgreSQL (when deployPostgreSql = true) ----
+
+# PostgreSQL admin password. If not set, a random password is generated and stored in Key Vault.
+POSTGRES_ADMIN_PASSWORD=
+
+# ---- Fabric Configuration ----
+
+# Fabric capacity mode: 'create', 'byo', or 'none'
+fabricCapacityMode=create
+
+# ---- Feature Flags ----
+
+# Deploy VM Key Vault (set to 'false' to skip)
+DEPLOY_VM_KEY_VAULT=true
+
+# Deploy VNet subnets (set to 'false' to skip)
+DEPLOY_SUBNETS=true
+
+# Enable side-by-side deployment mode
+SIDE_BY_SIDE=true
+
+# Use User-Assigned Identity instead of system-assigned
+USE_UAI=false
+
+# Use Container App API Key authentication
+USE_CAPP_API_KEY=false
+
+# Enable agentic retrieval in AI Foundry
+ENABLE_AGENTIC_RETRIEVAL=false
+
+# Existing VNet resource ID (when useExistingVNet = true in main.bicepparam)
+EXISTING_VNET_RESOURCE_ID=

README.md

@@ -272,6 +272,7 @@ Supporting documentation
 
 | Document | Description |
 |----------|-------------|
+| [Local Development Setup](./docs/local_development.md) | Set up your local environment, validate prerequisites, and deploy |
 | [Deployment Guide](./docs/deploymentguide.md) | Complete deployment instructions |
 | [Post Deployment Steps](./docs/post_deployment_steps.md) | Verify your deployment |
 | [PostgreSQL Mirroring](./docs/postgresql_mirroring.md) | Automate or troubleshoot the Fabric connection and PostgreSQL mirror flow |