docs: Document AUTHCONTEXT secret lookup chain and Key Vault underscore limitation (#2168)

### ❔What, Why & How

AUTHCONTEXT secret resolution had several undocumented behaviors that
could cause silent wrong-credential deployments with no log evidence:
the dash variant was never mentioned, Key Vault silently dropped
underscore secrets, and the generic fallback gave no warning.

#### Code change

- **`Actions/ReadSecrets/ReadSecretsHelper.psm1`**: Emit a warning when
a Key Vault lookup is skipped because the secret name contains `_`.
Previously returned `$null` with zero log output. The warning is now
emitted via `OutputWarning` from `Actions/.Modules/DebugLogHelper.psm1`
instead of a raw `Write-Host` call.

```powershell
# Before: silent null return
if ($secret.Contains('_')) {
    return $null
}

# After: warning emitted via OutputWarning
if ($secret.Contains('_')) {
    OutputWarning "Secret name '$secret' contains an underscore ('_'), which is not supported in Azure Key Vault. ..."
    return $null
}
```

#### Documentation changes

- **`Scenarios/secrets.md`** — Rewrote the `AuthContext` section to
document:
- Full three-step lookup chain in explicit precedence order:
`{envName}-AuthContext` → `{envName}_AuthContext` → `AuthContext`
- Azure Key Vault rejects underscore names → use the dash variant for
KV-stored secrets
- Generic `AuthContext` fallback is silent; in multi-tenant repos this
can deploy with the wrong credentials
- **`Scenarios/RegisterSandboxEnvironment.md`** and
**`Scenarios/RegisterProductionEnvironment.md`** — Removed inaccurate
notes about GitHub Environment secret scope at the Initialization
auth-check step; the auth check only runs for unknown environment names
(not found as a GitHub Environment or in settings), so properly
configured GitHub Environments are unaffected.

### ✅ Checklist

- [ ] Add tests (E2E, unit tests)
- [ ] Update RELEASENOTES.md
- [x] Update documentation (e.g. for new settings or scenarios)
- [ ] Add telemetry

<!-- START COPILOT ORIGINAL PROMPT -->



<details>

<summary>Original prompt</summary>


----

*This section details on the original issue you should resolve*

<issue_title>[Bug]: AUTHCONTEXT secret resolution undocumented -- silent
Key Vault underscore failure, undocumented dash variant, silent
org-level fallback trap, GitHub Environment secrets invisible at
auth-check step</issue_title>
<issue_description>## AL-Go version

v8.2

## Describe the issue

There are five related problems with AUTHCONTEXT secret resolution that
together create silent wrong-environment deployments with no errors and
no warnings. Each problem is individually confusing; together they are a
reliability and security hazard in multi-environment and multi-tenant
repos. I am documenting all five here as a single issue because fixing
any one of them in isolation without fixing the others would still leave
users in a broken state.

---

### Finding 1: The full lookup chain is undocumented -- the dash variant
is never mentioned

Both `Templates/Per Tenant Extension/.github/workflows/CICD.yaml` (line
351) and `Templates/Per Tenant
Extension/.github/workflows/PublishToEnvironment.yaml` (line 90)
declare:

```yaml
getSecrets: '{envName}-AuthContext,{envName}_AuthContext,AuthContext'
```

The PowerShell resolution logic in `PublishToEnvironment.yaml` lines
100-106 then evaluates them in this exact order:

```powershell
"$($envName)-AuthContext", "$($envName)_AuthContext", "AuthContext" | ForEach-Object {
    if (!($authContext)) {
        if ($secrets."$_") {
            Write-Host "Using $_ secret as AuthContext"
            $authContext = $secrets."$_"
            $secretName = $_
        }
    }
}
```

The dash variant `{envName}-AuthContext` is tried **first** and is the
highest-priority lookup. It is never mentioned anywhere in the
documentation. `Scenarios/secrets.md` documents only
`<EnvironmentName>_AuthContext` (underscore). A user reading the
documentation has no way to know the dash variant exists, let alone that
it takes precedence.

This matters practically because the dash variant is the only one of the
three that works correctly with Azure Key Vault (see Finding 2 below).

---

### Finding 2: Azure Key Vault silently skips all underscore secrets --
`{env}_AuthContext` silently returns null

`Actions/ReadSecrets/ReadSecretsHelper.psm1` lines 158-161:

```powershell
if ($secret.Contains('_')) {
    # Secret name contains a '_', which is not allowed in Key Vault secret names
    return $null
}
```

When Azure Key Vault is configured as the secrets provider, any
requested secret name containing an underscore is immediately returned
as `$null`. No error is thrown. No warning is written to the log. No
indication is given that the lookup was skipped.

The consequence: the documented pattern `<EnvironmentName>_AuthContext`
is **silently non-functional when Azure Key Vault is in use**. A user
who reads `Scenarios/secrets.md`, creates a Key Vault secret named
`MY-UAT_AuthContext`, and triggers a deployment to `MY-UAT` will get no
error. The workflow log will not mention that the Key Vault lookup was
skipped. The workflow silently falls through to the generic
`AuthContext` fallback.

The dash variant `{env}-AuthContext` does work with Key Vault because
dashes are permitted in Key Vault secret names. This is never
documented.

---

### Finding 3: The generic `AuthContext` fallback is a silent
cross-environment credential trap

When neither `{env}-AuthContext` nor `{env}_AuthContext` resolves to a
value, AL-Go silently falls back to the generic `AuthContext` secret.
The only log evidence of this is the message `Using AuthContext secret
as AuthContext`. There is no warning that this is a fallback, no
indication that a per-environment secret was expected but not found, and
no indication that the credentials being used may not correspond to the
target environment.

In organizations that define `AUTHCONTEXT` at the org level and share it
with all repositories (a common pattern for product repos), every
environment in every repo that lacks a per-environment secret will
silently deploy using the org-level credential.

In a multi-tenant PTE scenario this creates a security isolation
failure:

- A `TenantApps` repo has environments `CUSTOMER-A-UAT` and
`CUSTOMER-B-UAT`
- Neither has a per-environment `AuthContext` secret defined
- The org-level `AUTHCONTEXT` belongs to Customer A's BC service account
- A developer triggers `Publish To Environment` targeting
`CUSTOMER-B-UAT`
- AL-Go resolves to the org-level `AUTHCONTEXT` (Customer A's
credentials) with no warning
- The workflow reports success; the log says "Using AuthContext secret
as AuthContext"
- No error is thrown and no credential mismatch is flagged

In regulated industries where BC tenant isolation is a compliance
requirement, this silent fallback is particularly dangerous.

---

### Finding 4: GitHub Environment secrets are invisible at the
auth-check initialization step

In both `CICD.yaml` and...

</details>



<!-- START COPILOT CODING AGENT SUFFIX -->

- Fixes microsoft/AL-Go#2153

<!-- START COPILOT CODING AGENT TIPS -->
---

📍 Connect Copilot coding agent with [Jira](https://gh.io/cca-jira-docs),
[Azure Boards](https://gh.io/cca-azure-boards-docs) or
[Linear](https://gh.io/cca-linear-docs) to delegate work to Copilot in
one click without leaving your project management tool.

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: spetersenms <79980472+spetersenms@users.noreply.github.com>
Co-authored-by: Maria Zhelezova <43066499+mazhelez@users.noreply.github.com>
Co-authored-by: Alexander Holstrup <117829001+aholstrup1@users.noreply.github.com>