adding instructions to install extension.

Author: EMaher

docs/ci-cd/azure-devops.md

@@ -127,25 +127,26 @@ The pipeline runs automatically when changes to artifact files or configuration
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `COMMIT_ID_CHOICE` | string | `publish-artifacts-in-last-commit` | Choose `publish-artifacts-in-last-commit` for incremental publish, or `publish-all-artifacts-in-repo` for a full publish |
-| `ENVIRONMENT` | string | `all` | Which environment to publish to: `all`, `dev`, or `prod` |
+| `ENVIRONMENT` | string | `dev` | Which environment to publish to (for example `dev` or `prod`) |
 
 ### Multi-Stage Deployment
 
-The pipeline generates one stage per environment. Stages run sequentially — each stage depends on the previous:
+The pipeline generates one stage per environment. The selected stage runs based on the `ENVIRONMENT` parameter.
 
 ```mermaid
 flowchart LR
-    A[Publish_dev] --> B[Publish_prod]
+  A[ENVIRONMENT=dev] --> B[Publish_dev]
+  C[ENVIRONMENT=prod] --> D[Publish_prod]
 ```
 
 Each stage:
 
-1. **Conditionally runs** — Only executes if the `ENVIRONMENT` parameter matches the stage name or is `all`
+1. **Conditionally runs** — Only executes when the `ENVIRONMENT` parameter matches the stage name
 2. **Uses a deployment job** — Wraps the publish step in a `deployment` job targeting an [Azure DevOps environment](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/environments) for approval gates
 3. **Loads per-environment variables** — Each stage uses its own variable group (`apim-dev`, `apim-prod`)
 4. **Authenticates per-environment** — Uses environment-specific service connections (`AZURE_SERVICE_CONNECTION_DEV`, `AZURE_SERVICE_CONNECTION_PROD`)
 5. **Substitutes tokens** — Replaces `{#[TOKEN_NAME]#}` placeholders in `configuration.<env>.yaml` with secret variable values before publishing
-6. **Applies overrides** — Passes `--override configuration.{env}.yaml` to apply [environment-specific overrides](../guides/environment-overrides.md)
+6. **Applies overrides** — Passes `--overrides configuration.{env}.yaml` to apply [environment-specific overrides](../guides/environment-overrides.md)
 
 ### Publish Pipeline Walkthrough
 
@@ -156,15 +157,15 @@ For incremental publish (default), `--commit-id $(Build.SourceVersion)` is passe
   displayName: 'Publish to dev (incremental - last commit only)'
   condition: ne('${{ parameters.COMMIT_ID_CHOICE }}', 'publish-all-artifacts-in-repo')
   inputs:
-    azureSubscription: '$(AZURE_SERVICE_CONNECTION_DEV)'
+    azureSubscription: 'AZURE_SERVICE_CONNECTION_DEV'
     scriptType: 'bash'
     scriptLocation: 'inlineScript'
     inlineScript: |
       npx apiops publish \
         --resource-group $(APIM_RESOURCE_GROUP_DEV) \
         --service-name $(APIM_SERVICE_NAME_DEV) \
         --source ./apim-artifacts \
-        --override configuration.dev.yaml \
+        --overrides configuration.dev.yaml \
         --commit-id $(Build.SourceVersion) \
         --subscription-id $(AZURE_SUBSCRIPTION_ID)
 ```
@@ -300,6 +301,11 @@ To replace `{#[TOKEN_NAME]#}` placeholders in `configuration.<env>.yaml` with se
 
 1. **Install the [Replace Tokens extension](https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens)** in your Azure DevOps organization (if not already installed).
 
+  You can do this via CLI:
+  ```bash
+  az devops extension install --publisher-id qetza --extension-id replacetokens
+  ```
+
 2. **Add secret variables** to the `apim-<env>` variable group. See the Azure DevOps documentation for [adding variables to a variable group](https://learn.microsoft.com/en-us/azure/devops/pipelines/library/variable-groups) and [marking variables as secret](https://learn.microsoft.com/en-us/azure/devops/pipelines/process/set-secret-variables).
 
    For example, to substitute `{#[BACKEND_URL]#}` in your configuration file:
@@ -326,10 +332,11 @@ See the [Token Substitution Guide](../guides/token-substitution.md) for full det
 |---------|-------|-----|
 | `AzureCLI@2` fails with "service connection not found" | Variable group not linked or variable name mismatch | Verify the variable group is linked to the pipeline and `AZURE_SERVICE_CONNECTION` is defined |
 | Extract shows "No changes to commit" | APIM config hasn't changed since last extract | Expected behavior — no branch is created |
-| Publish stage is skipped | `ENVIRONMENT` parameter doesn't match the stage | Set `ENVIRONMENT` to `all` or the specific stage name |
+| Publish stage is skipped | `ENVIRONMENT` parameter doesn't match the stage | Set `ENVIRONMENT` to the specific stage name (for example `dev` or `prod`) |
 | `npm ci` fails | `package.json` or `package-lock.json` missing | Run `apiops init` to generate project files, then commit them |
 | "publish-all-artifacts-in-repo" deploys everything | Expected — this mode publishes all artifacts, ignoring git diff | Use `publish-artifacts-in-last-commit` (default) for incremental |
 | Approval gate blocks deployment | Environment checks configured | Approve in **Pipelines → Environments → {env}** |
+| Run is stuck with "This pipeline needs permission to access a resource" | Environment resource isn't authorized for pipeline use | Authorize the environment in Azure DevOps or run the prompt step that PATCHes `pipelinePermissions/environment/{id}` with `{"allPipelines":{"authorized":true}}` |
 | `--subscription-id` error | `AZURE_SUBSCRIPTION_ID` not set in variable group | Add it to the relevant variable group |
 
 ---

docs/guides/token-substitution.md

@@ -97,7 +97,9 @@ Result: the placeholder `{#[PAYMENT_API_KEY]#}` is replaced with `sk-live-abc123
 ## Azure DevOps Setup
 
 > [!IMPORTANT]
-> The [Replace Tokens extension](https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens) must be installed in your Azure DevOps organization from the Visual Studio Marketplace.
+> The [Replace Tokens extension](https://marketplace.visualstudio.com/items?itemName=qetza.replacetokens) must be installed in your Azure DevOps organization.
+> You can install it from Marketplace or via CLI:
+> `az devops extension install --publisher-id qetza --extension-id replacetokens`
 
 ### Mapping Variables to Tokens
 
@@ -112,6 +114,9 @@ The substitution task will automatically replace `{#[PROD_SECRET_VALUE]#}` with
 ### Step-by-Step for Azure DevOps
 
 1. **Install the Replace Tokens extension** in your Azure DevOps organization if not already present.
+  ```bash
+  az devops extension install --publisher-id qetza --extension-id replacetokens
+  ```
 
 2. **Add secret variables to your variable group:**
    - Go to **Pipelines → Library → apim\<env\>** (e.g., `apim-prod`)

src/templates/shared/identity-setup-azure-devops-core.md

@@ -101,6 +101,18 @@ Install the extension (works in both shells):
 az extension add --name azure-devops
 ```
 
+Install the Azure DevOps Replace Tokens extension (required by publish pipeline):
+
+**PowerShell:**
+```powershell
+az devops extension install --publisher-id qetza --extension-id replacetokens
+```
+
+**Git Bash:**
+```bash
+az devops extension install --publisher-id qetza --extension-id replacetokens
+```
+
 Set organization defaults:
 
 For self-hosted Azure DevOps Server, use your server/collection URL format: