better-dsh 0.2.5 → 0.3.0-a

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/aws-bedrock.md

@@ -1,196 +0,0 @@
----
-sidebar_position: 14
-title: "AWS Bedrock"
-description: "Use Hermes Agent with Amazon Bedrock — native Converse API, Anthropic SDK routing, OpenAI models via Bedrock Mantle, IAM authentication, Guardrails, and cross-region inference"
----
-
-# AWS Bedrock
-
-Hermes Agent supports Amazon Bedrock as a native provider. This gives you full access to the Bedrock ecosystem: IAM authentication, Guardrails, cross-region inference profiles, and all foundation models.
-
-Hermes routes each model family through the API that serves it best:
-
-| Model family | API route | Why |
-|---|---|---|
-| Anthropic Claude | Anthropic SDK (`AnthropicBedrock`) | Prompt caching, thinking budgets, adaptive thinking — features not exposed via Converse |
-| OpenAI GPT-5.5 / GPT-5.6 (Sol, Terra, Luna) | Bedrock Mantle **OpenAI Responses** endpoint (`bedrock-mantle.<region>.api.aws/openai/v1`) | These models are Mantle-only — their model cards list bedrock-runtime/Converse as unsupported |
-| Everything else (Nova, DeepSeek, Llama, GPT-OSS, …) | Native **Converse API** (`bedrock-runtime`) | Full Bedrock feature set: Guardrails, inference profiles, streaming |
-
-All three routes share the same AWS credential chain and region resolution — no separate configuration is needed. Requests to the Mantle endpoint are authenticated with `AWS_BEARER_TOKEN_BEDROCK` when set, or SigV4-signed via the standard boto3 credential chain otherwise.
-
-## Prerequisites
-
-- **AWS credentials** — any source supported by the [boto3 credential chain](https://boto3.amazonaws.com/v1/documentation/api/latest/guide/credentials.html):
-  - IAM instance role (EC2, ECS, Lambda — zero config)
-  - `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` environment variables
-  - `AWS_PROFILE` for SSO or named profiles
-  - `aws configure` for local development
-- **boto3** — install with `cd ~/.hermes/hermes-agent && uv pip install -e ".[bedrock]"`
-- **IAM permissions** — at minimum:
-  - `bedrock:InvokeModel` and `bedrock:InvokeModelWithResponseStream` (for inference)
-  - `bedrock:ListFoundationModels` and `bedrock:ListInferenceProfiles` (for model discovery)
-
-:::tip EC2 / ECS / Lambda
-On AWS compute, attach an IAM role with `AmazonBedrockFullAccess` and you're done. No API keys, no `.env` configuration — Hermes detects the instance role automatically.
-:::
-
-## Quick Start
-
-```bash
-# Install with Bedrock support
-cd ~/.hermes/hermes-agent && uv pip install -e ".[bedrock]"
-
-# Select Bedrock as your provider
-hermes model
-# → Choose "More providers..." → "AWS Bedrock"
-# → Select your region and model
-
-# Start chatting
-hermes chat
-```
-
-## Configuration
-
-After running `hermes model`, your `~/.hermes/config.yaml` will contain:
-
-```yaml
-model:
-  default: us.anthropic.claude-sonnet-4-6
-  provider: bedrock
-  base_url: https://bedrock-runtime.us-east-2.amazonaws.com
-
-bedrock:
-  region: us-east-2
-```
-
-### Region
-
-Set the AWS region in any of these ways (highest priority first):
-
-1. `bedrock.region` in `config.yaml`
-2. `AWS_REGION` environment variable
-3. `AWS_DEFAULT_REGION` environment variable
-4. Default: `us-east-1`
-
-### Guardrails
-
-To apply [Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) to all model invocations:
-
-```yaml
-bedrock:
-  region: us-east-2
-  guardrail:
-    guardrail_identifier: "abc123def456"  # From the Bedrock console
-    guardrail_version: "1"                # Version number or "DRAFT"
-    stream_processing_mode: "async"       # "sync" or "async"
-    trace: "disabled"                     # "enabled", "disabled", or "enabled_full"
-```
-
-The guardrail is attached on the Converse route (`guardrailConfig`) and on the Claude route (InvokeModel headers via the Anthropic Bedrock SDK, so prompt caching and thinking are kept). A blocked request surfaces as a content-filter refusal rather than as model text. `stream_processing_mode` only applies to Converse.
-
-AWS does not apply Guardrails to the Mantle Responses endpoint used by `openai.gpt-5.x` models ([AWS docs](https://docs.aws.amazon.com/bedrock/latest/userguide/bedrock-mantle.html)); use a Converse-served model when a guardrail is required.
-
-### Model Discovery
-
-Hermes auto-discovers available models via the Bedrock control plane. You can customize discovery:
-
-```yaml
-bedrock:
-  discovery:
-    enabled: true
-    provider_filter: ["anthropic", "amazon"]  # Only show these providers
-    refresh_interval: 3600                     # Cache for 1 hour
-```
-
-### Prompt caching (cachePoint)
-
-Hermes automatically applies prompt caching on the Bedrock **Converse API** path by inserting `cachePoint` markers after the system prompt, tool definitions, and the latest message. Because sending a `cachePoint` block to a model that doesn't support it raises a `ValidationException`, markers are only added for models on a known-good allowlist (Anthropic Claude and Amazon Nova model IDs); unknown models default to no cache markers. Claude models normally use the AnthropicBedrock SDK path, which has its own prompt caching — the Converse `cachePoint` path covers Nova and the bearer-token Claude fallback. No configuration needed; cache reads/writes show up in usage accounting.
-
-### Context-window probing
-
-For models whose context window isn't in Hermes' static table, Hermes can probe the real limit by sending oversized requests at fixed tiers (~1.3M and ~2.2M tokens) and parsing the `maximum` reported in Bedrock's length-validation error. Probed values feed the same metadata cache as the static table; stale cached entries that under-report a model's window (e.g. entries seeded before a model's 1M window went GA) are dropped automatically in favor of the larger known value.
-
-## Available Models
-
-Bedrock models use **inference profile IDs** for on-demand invocation. The `hermes model` picker shows these automatically, with recommended models at the top:
-
-| Model | ID | Notes |
-|-------|-----|-------|
-| Claude Sonnet 4.6 | `us.anthropic.claude-sonnet-4-6` | Recommended — best balance of speed and capability |
-| Claude Opus 4.6 | `us.anthropic.claude-opus-4-6-v1` | Most capable |
-| Claude Haiku 4.5 | `us.anthropic.claude-haiku-4-5-20251001-v1:0` | Fastest Claude |
-| OpenAI GPT-5.6 Sol | `openai.gpt-5.6-sol` | OpenAI frontier model (via Bedrock Mantle) |
-| OpenAI GPT-5.6 Terra | `openai.gpt-5.6-terra` | Balanced (via Bedrock Mantle) |
-| OpenAI GPT-5.6 Luna | `openai.gpt-5.6-luna` | Fast, affordable (via Bedrock Mantle) |
-| OpenAI GPT-5.5 | `openai.gpt-5.5` | Previous OpenAI flagship (via Bedrock Mantle) |
-| Amazon Nova Pro | `us.amazon.nova-pro-v1:0` | Amazon's flagship |
-| Amazon Nova Micro | `us.amazon.nova-micro-v1:0` | Fastest, cheapest |
-| DeepSeek V3.2 | `deepseek.v3.2` | Strong open model |
-| Llama 4 Scout 17B | `us.meta.llama4-scout-17b-instruct-v1:0` | Meta's latest |
-
-:::info Cross-Region Inference
-Models prefixed with `us.` use cross-region inference profiles, which provide better capacity and automatic failover across AWS regions. Models prefixed with `global.` route across all available regions worldwide. OpenAI `openai.*` model IDs are served by Bedrock Mantle in the configured region and don't use inference-profile prefixes.
-:::
-
-## Switching Models Mid-Session
-
-Use the `/model` command during a conversation:
-
-```
-/model us.amazon.nova-pro-v1:0
-/model deepseek.v3.2
-/model us.anthropic.claude-opus-4-6-v1
-```
-
-## Diagnostics
-
-```bash
-hermes doctor
-```
-
-The doctor checks:
-- Whether AWS credentials are available (env vars, IAM role, SSO)
-- Whether `boto3` is installed
-- Whether the Bedrock API is reachable (ListFoundationModels)
-- Number of available models in your region
-
-## Gateway (Messaging Platforms)
-
-Bedrock works with all Hermes gateway platforms (Telegram, Discord, Slack, Feishu, etc.). Configure Bedrock as your provider, then start the gateway normally:
-
-```bash
-hermes gateway setup
-hermes gateway start
-```
-
-The gateway reads `config.yaml` and uses the same Bedrock provider configuration.
-
-## Troubleshooting
-
-### "No API key found" / "No AWS credentials"
-
-Hermes checks for credentials in this order:
-1. `AWS_BEARER_TOKEN_BEDROCK`
-2. `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`
-3. `AWS_PROFILE`
-4. EC2 instance metadata (IMDS)
-5. ECS container credentials
-6. Lambda execution role
-
-If none are found, run `aws configure` or attach an IAM role to your compute instance.
-
-### "Invocation of model ID ... with on-demand throughput isn't supported"
-
-Use an **inference profile ID** (prefixed with `us.` or `global.`) instead of the bare foundation model ID. For example:
-- ❌ `anthropic.claude-sonnet-4-6`
-- ✅ `us.anthropic.claude-sonnet-4-6`
-
-### "ThrottlingException"
-
-You've hit the Bedrock per-model rate limit. Hermes automatically retries with backoff. To increase limits, request a quota increase in the [AWS Service Quotas console](https://console.aws.amazon.com/servicequotas/).
-
-## One-Click AWS Deployment
-
-For a fully automated deployment on EC2 with CloudFormation:
-
-**[sample-hermes-agent-on-aws-with-bedrock](https://github.com/JiaDe-Wu/sample-hermes-agent-on-aws-with-bedrock)** — creates VPC, IAM role, EC2 instance, and configures Bedrock automatically. Deploy in any region with one click.

package/docs/80_upstream-docs-and-skills/hermes-dev-skill/src/docs/guides/azure-foundry.md

@@ -1,334 +0,0 @@
----
-sidebar_position: 15
-title: "Microsoft Foundry"
-description: "Use Hermes Agent with Microsoft Foundry — OpenAI-style and Anthropic-style endpoints, auto-detection of transport and deployed models"
----
-
-# Microsoft Foundry
-
-Hermes Agent's `azure-foundry` provider supports Microsoft Foundry (formerly Azure AI Foundry) and Azure OpenAI. A single Foundry resource can host models with two different wire formats:
-
-- **OpenAI-style** — `POST /v1/chat/completions` on endpoints like `https://<resource>.openai.azure.com/openai/v1`. Used for GPT-4.x, GPT-5.x, Llama, Mistral, and most open-weight models.
-- **Anthropic-style** — `POST /v1/messages` on endpoints like `https://<resource>.services.ai.azure.com/anthropic`. Used when Microsoft Foundry serves Claude models via the Anthropic Messages API format.
-
-The setup wizard probes your endpoint and auto-detects which transport it uses, which deployments are available, and each model's context length.
-
-## Prerequisites
-
-- A Microsoft Foundry or Azure OpenAI resource with at least one deployment
-- The deployment's endpoint URL
-- **Either** an API key (from the Azure Portal under "Keys and Endpoint") **or** the **Azure AI User** RBAC role on the Foundry resource if you plan to use Microsoft Entra ID (the keyless path Microsoft recommends). Some tenants may show the role as **Foundry User** during Microsoft's rename rollout.
-
-## Quick Start
-
-```bash
-hermes model
-# → Select "Azure Foundry"
-# → Enter your endpoint URL
-# → Choose Authentication:
-#     1. API key
-#     2. Microsoft Entra ID  (managed identity / workload identity / az login)
-# → (Entra) Hermes probes DefaultAzureCredential; on success it never asks for a key
-# → (API key) Enter your API key
-# Hermes probes the endpoint and auto-detects transport + models
-# → Pick a model from the list (or type a deployment name manually)
-```
-
-The wizard will:
-
-1. **Sniff the URL path** — URLs ending in `/anthropic` are recognised as Microsoft Foundry Claude routes.
-2. **Probe `GET <base>/models`** — if the endpoint returns an OpenAI-shaped model list, Hermes switches to `chat_completions` and prefills a picker with the returned deployment IDs.
-3. **Probe Anthropic Messages shape** — fallback for endpoints that do not expose `/models` but do accept the Anthropic Messages format.
-4. **Fall back to manual entry** — private/gated endpoints that reject every probe still work; you pick the API mode and type a deployment name by hand.
-
-Context length for the chosen model is resolved via Hermes' standard metadata chain (`models.dev`, provider metadata, and hardcoded family fallbacks) and stored in `config.yaml` so the model can size its own context window correctly.
-
-## Microsoft Entra ID (keyless, RBAC) — recommended
-
-Microsoft recommends [keyless authentication with Microsoft Entra ID](https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id) for production Foundry workloads. Hermes supports Entra ID for **both** API surfaces:
-
-- **OpenAI-style** (`api_mode: chat_completions` / `codex_responses`) — GPT-4/5, Llama, Mistral, DeepSeek, etc.
-- **Anthropic-style** (`api_mode: anthropic_messages`) — Claude models on Microsoft Foundry.
-
-Foundry's RBAC is per-resource (`Azure AI User` grants both surfaces; some tenants may display `Foundry User`) and Microsoft documents the same inference scope (`https://ai.azure.com/.default`) for both. Under the hood:
-
-- OpenAI-style uses the OpenAI Python SDK's native callable `api_key=` contract — the SDK mints a fresh JWT per request automatically.
-- Anthropic-style uses an `httpx.Client` with a request event hook installed by `agent.azure_identity_adapter.build_bearer_http_client`, because the Anthropic SDK does not accept callable `auth_token` natively. The hook rewrites `Authorization: Bearer <fresh-jwt>` per outbound request. Same Microsoft RBAC, same Foundry scope — the SDK contract is the only difference.
-
-### Why use Entra ID?
-
-- No long-lived API keys to rotate or revoke.
-- RBAC-driven access — grant or remove `Azure AI User` on the Foundry resource, no config rewrite needed.
-- Access and audit logs are segmented by assignee instead of all callers sharing one static key.
-- Single auth surface for Azure VMs, AKS pods, App Service, Functions, Container Apps, and Foundry Agent Service via managed identity.
-- Workload identity and service-principal flows for CI/CD pipelines.
-
-### One-time setup (Azure side)
-
-1. In the Azure Portal, open your Foundry resource → **Access control (IAM)** → **Add → Add role assignment**.
-2. Pick the **Azure AI User** role (or **Foundry User** if your tenant has the renamed role).
-3. Assign it to:
-   - **Your user account** for local development with `az login`.
-   - **A managed identity or workload identity** for Azure-hosted compute (recommended for production).
-   - **A Foundry Agent Service hosted agent's agent identity** when Hermes runs inside a hosted agent.
-   - **A service principal** for CI/CD pipelines when workload identity is not available.
-4. Wait ~5 minutes for the role to propagate.
-
-Azure CLI equivalent:
-
-```bash
-az role assignment create \
-  --assignee <principal-or-agent-identity-client-id> \
-  --role "Azure AI User" \
-  --scope <foundry-resource-id>
-```
-
-### One-time setup (Hermes side)
-
-```bash
-hermes model
-# → Select "Azure Foundry"
-# → Enter your endpoint URL
-# → Authentication: 2 (Microsoft Entra ID)
-# → (optional) user-assigned managed identity client ID
-# → (optional) Azure tenant ID
-# → Hermes probes DefaultAzureCredential() and reports which inner
-#    credential succeeded (e.g. AzureCliCredential, ManagedIdentityCredential)
-```
-
-The wizard runs a bounded preflight probe (10 s timeout). On failure it offers to "save anyway, validate later" — useful when configuring on a machine that doesn't yet have credentials but will at runtime (e.g. preparing config for a managed-identity deployment).
-
-`azure-identity` is installed automatically on first use via Hermes' lazy-install path. To pre-install:
-
-```bash
-pip install azure-identity
-```
-
-### Configuration written to `config.yaml`
-
-```yaml
-model:
-  provider: azure-foundry
-  base_url: https://my-resource.openai.azure.com/openai/v1
-  api_mode: chat_completions
-  auth_mode: entra_id
-  default: gpt-4o
-  context_length: 128000
-  entra:
-    scope: https://ai.azure.com/.default        # only when overriding the default
-```
-
-Hermes only manages one Entra-specific knob in `config.yaml`:
-
-- **`scope`** — the OAuth resource scope. Defaults to Microsoft's documented inference scope (`https://ai.azure.com/.default`). Override only if your resource was provisioned against a non-standard audience.
-
-Everything else (tenant, service principal secret, federated token file, sovereign cloud authority, broker preferences) is read by `azure-identity` directly from the standard `AZURE_*` environment variables — see the [credential resolution order](#credential-resolution-order) below. Set those in `~/.hermes/.env` or your deployment environment, exactly as Microsoft's SDK reference describes.
-
-No secrets land in `~/.hermes/.env` for Entra mode — `azure-identity` caches tokens in-process (and where available, in your OS keychain / `~/.IdentityService`).
-
-### Credential resolution order
-
-`azure-identity`'s `DefaultAzureCredential` walks this chain on each token request, stopping at the first credential that returns a token:
-
-1. **Environment credential** — `AZURE_TENANT_ID` + `AZURE_CLIENT_ID` + `AZURE_CLIENT_SECRET` (or `AZURE_CLIENT_CERTIFICATE_PATH` / `AZURE_FEDERATED_TOKEN_FILE`).
-2. **Workload Identity** — `AZURE_FEDERATED_TOKEN_FILE` (AKS federated tokens / OIDC).
-3. **Managed Identity** — IMDS endpoint (`169.254.169.254`) for virtual machines; `IDENTITY_ENDPOINT` for App Service / Functions / Container Apps. Foundry Agent Service hosted agents use the hosted agent's agent identity.
-4. **Visual Studio Code** — Azure account extension.
-5. **Azure CLI** — `az login` session.
-6. **Azure Developer CLI** — `azd auth login`.
-7. **Azure PowerShell** — `Connect-AzAccount`.
-8. **Broker** (Windows / WSL only) — Web Account Manager.
-
-Interactive browser credential is excluded by default for unattended Hermes runs; use Azure CLI, Azure Developer CLI, managed identity, workload identity, or service principal credentials instead.
-
-### Deployment patterns
-
-**Local development:**
-```bash
-az login
-hermes model   # pick Azure Foundry → Entra ID
-hermes         # uses your az login token
-```
-
-**Azure VM / Functions / App Service / Container Apps (system-assigned managed identity):**
-1. Enable system-assigned identity on the compute resource.
-2. Grant the identity `Azure AI User` (or `Foundry User`) on the Foundry resource.
-3. Set `model.auth_mode: entra_id` in config.yaml — no env vars needed.
-
-**Azure VM / Functions / App Service / Container Apps (user-assigned managed identity):**
-- Set `AZURE_CLIENT_ID` to the user-assigned identity's client ID so `DefaultAzureCredential` picks the right one.
-
-**Foundry Agent Service hosted agent:**
-- Create the hosted agent and grant that agent's identity `Azure AI User` (or `Foundry User`) on the Foundry resource. Hermes uses `ManagedIdentityCredential` from inside the hosted agent; role assignment belongs on the agent identity, not just the parent project or your user.
-
-**AKS Workload Identity (replaces AAD Pod Identity):**
-- Annotate the pod's service account with the workload identity client ID.
-- The pod's federated token file is auto-detected via `AZURE_FEDERATED_TOKEN_FILE`.
-- `model.auth_mode: entra_id` works without further config changes.
-
-**Service principal in CI:**
-- Set `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` in the runner env.
-
-#### Sovereign clouds (Government, China)
-
-Export `AZURE_AUTHORITY_HOST` (e.g. `https://login.microsoftonline.us` for Azure Government, `https://login.partner.microsoftonline.cn` for Azure China). `azure-identity` reads it directly.
-
-### Health checks
-
-`hermes doctor` runs a 10 s probe against `DefaultAzureCredential` when `model.auth_mode: entra_id`, reporting which inner credential won (env vars present, managed identity endpoint reachable, etc.).
-
-`hermes auth` shows a structured status block:
-
-```
-azure-foundry (Microsoft Entra ID):
-  Endpoint: https://my-resource.openai.azure.com/openai/v1
-  Scope: https://ai.azure.com/.default
-  Status: configured; live token probe is skipped here
-```
-
-### Limitations
-
-- **Anthropic-style endpoints use an httpx event hook.** The Anthropic Python SDK does not accept a callable `auth_token` natively (≤ 0.86.0). Hermes installs a request event hook on a custom `httpx.Client` that mints a fresh JWT per outbound request and rewrites `Authorization: Bearer <jwt>`. This is functionally equivalent to the OpenAI SDK's native `Callable[[], str]` contract but adds one indirection layer. If the Anthropic SDK adds first-class callable-auth support in a future release, Hermes will switch to it transparently.
-- **Batch jobs and `multiprocessing.Pool`.** The Entra token provider is a closure that cannot be pickled across process boundaries. `batch_runner.py` automatically drops the callable from the worker config and lets each worker process rebuild its own provider from `config.yaml` — no user action required, but each worker pays one chain walk at startup.
-- **No bearer JWT persistence in `auth.json`.** Hermes does not duplicate `azure-identity`'s internal token cache; cold starts walk the credential chain on first inference.
-
-## Configuration (written to `config.yaml`)
-
-After running the wizard you'll see something like this:
-
-```yaml
-model:
-  provider: azure-foundry
-  base_url: https://my-resource.openai.azure.com/openai/v1
-  api_mode: chat_completions         # or "anthropic_messages"
-  default: gpt-5.4-mini              # your deployment / model name
-  context_length: 400000             # auto-detected
-```
-
-And in `~/.hermes/.env`:
-
-```
-AZURE_FOUNDRY_API_KEY=<your-azure-key>
-```
-
-## OpenAI-style endpoints (GPT, Llama, etc.)
-
-Azure OpenAI's v1 GA endpoint accepts the standard `openai` Python client with minimal changes:
-
-```yaml
-model:
-  provider: azure-foundry
-  base_url: https://my-resource.openai.azure.com/openai/v1
-  api_mode: chat_completions
-  default: gpt-5.4
-```
-
-Important behaviour:
-
-- **GPT-5.x, codex, and o-series auto-route to the Responses API.** Microsoft Foundry deploys GPT-5 / codex / o1 / o3 / o4 models as Responses-API-only — calling `/chat/completions` against them returns `400 "The requested operation is unsupported."`. Hermes detects these model families by name and upgrades `api_mode` to `codex_responses` transparently, even when `config.yaml` still reads `api_mode: chat_completions`. GPT-4, GPT-4o, Llama, Mistral, and other deployments stay on `/chat/completions`.
-- **`max_completion_tokens` is used automatically.** Azure OpenAI (like direct OpenAI) requires `max_completion_tokens` for gpt-4o, o-series, and gpt-5.x models. Hermes sends the right parameter based on the endpoint.
-- **Pre-v1 endpoints that require `api-version`.** If you have a legacy base URL like `https://<resource>.openai.azure.com/openai?api-version=2025-04-01-preview`, Hermes extracts the query string and forwards it via `default_query` on every request (the OpenAI SDK otherwise drops it when joining paths).
-
-## Anthropic-style endpoints (Claude via Microsoft Foundry)
-
-For Claude deployments, use the Anthropic-style route:
-
-```yaml
-model:
-  provider: azure-foundry
-  base_url: https://my-resource.services.ai.azure.com/anthropic
-  api_mode: anthropic_messages
-  default: claude-sonnet-4-6
-```
-
-Important behaviour:
-
-- **`/v1` is stripped from the base URL.** The Anthropic SDK appends `/v1/messages` to every request URL — Hermes removes any trailing `/v1` before handing the URL to the SDK to avoid double-`/v1` paths.
-- **`api-version` is sent via `default_query`, not appended to the URL.** Azure Anthropic requires an `api-version` query string. Baking it into the base URL produces malformed paths like `/anthropic?api-version=.../v1/messages` and returns 404. Hermes passes `api-version=2025-04-15` via the Anthropic SDK's `default_query` instead.
-- **Bearer auth is used instead of `x-api-key`.** Azure's Anthropic-compatible route requires `Authorization: Bearer <key>` rather than Anthropic's native `x-api-key` header. Hermes detects `azure.com` in the base URL and routes the API key through the SDK's `auth_token` field so the right header reaches the upstream.
-- **1M context window beta header is kept.** Azure still gates the 1M-token Claude context (Opus 4.6/4.7, Sonnet 4.6) behind the `anthropic-beta: context-1m-2025-08-07` header. Hermes keeps that beta header on Azure paths (it's stripped from native Anthropic OAuth requests because some subscriptions reject it, but Azure requires it).
-- **OAuth token refresh is disabled.** Azure deployments use static API keys. The `~/.claude/.credentials.json` OAuth token refresh loop that applies to Anthropic Console is explicitly skipped for Azure endpoints to prevent the Claude Code OAuth token from overwriting your Azure key mid-session.
-
-## Alternative: `provider: anthropic` + Azure base URL
-
-If you already have `provider: anthropic` configured and just want to point it at Microsoft Foundry for Claude, you can skip the `azure-foundry` provider entirely:
-
-```yaml
-model:
-  provider: anthropic
-  base_url: https://my-resource.services.ai.azure.com/anthropic
-  key_env: AZURE_ANTHROPIC_KEY
-  default: claude-sonnet-4-6
-```
-
-With `AZURE_ANTHROPIC_KEY` set in `~/.hermes/.env`. Hermes detects `azure.com` in the base URL and short-circuits around the Claude Code OAuth token chain so the Azure key is used directly with `x-api-key` auth.
-
-`key_env` is the canonical snake_case field name; `api_key_env` (and the camelCase `keyEnv` / `apiKeyEnv`) are accepted as aliases. If both `key_env` and `AZURE_ANTHROPIC_KEY`/`ANTHROPIC_API_KEY` are set, the `key_env`-named env var wins.
-
-## Model discovery
-
-Azure does **not** expose a pure-API-key endpoint to list your *deployed* model deployments. Deployment enumeration requires Azure Resource Manager authentication (`az cognitiveservices account deployment list`) with an Azure AD principal, not the inference API key.
-
-What Hermes can do:
-
-- Azure OpenAI v1 endpoints (`<resource>.openai.azure.com/openai/v1`) expose `GET /models` with the resource's **available** model catalog. Hermes uses this list to prefill the model picker.
-- Microsoft Foundry `/anthropic` routes: detected via URL path, model name entered manually.
-- Private / firewalled endpoints: manual entry with a friendly "couldn't probe" message.
-
-You can always type a deployment name directly — Hermes does not validate against the returned list.
-
-## Environment variables
-
-| Variable | Purpose |
-|----------|---------|
-| `AZURE_FOUNDRY_API_KEY` | Primary API key for Microsoft Foundry / Azure OpenAI (api_key mode) |
-| `AZURE_FOUNDRY_BASE_URL` | Endpoint URL (set via `hermes model`; env var is used as a fallback) |
-| `AZURE_ANTHROPIC_KEY` | Used by `provider: anthropic` + Azure base URL (alternative to `ANTHROPIC_API_KEY`) |
-| `AZURE_TENANT_ID` | Entra ID tenant for service-principal flows |
-| `AZURE_CLIENT_ID` | Entra ID client ID (service principal, workload identity, or user-assigned managed identity) |
-| `AZURE_CLIENT_SECRET` | Service principal secret |
-| `AZURE_CLIENT_CERTIFICATE_PATH` | Service principal cert (alternative to secret) |
-| `AZURE_FEDERATED_TOKEN_FILE` | Workload Identity federated token path (AKS) |
-| `AZURE_AUTHORITY_HOST` | Sovereign cloud authority host override |
-| `IDENTITY_ENDPOINT` / `MSI_ENDPOINT` | Managed Identity endpoint for App Service, Functions, and Container Apps; VMs usually use IMDS instead |
-
-The Azure SDK reads the `AZURE_*` env vars directly. Hermes never inspects them other than to report which sources are present in `hermes doctor` output.
-
-## Troubleshooting
-
-**401 Unauthorized on gpt-5.x deployments.**
-Azure serves gpt-5.x on `/chat/completions`, not `/responses`. Hermes handles this automatically when the URL contains `openai.azure.com`, but if you see a 401 with an `Invalid API key` body, check that `api_mode` in your `config.yaml` is `chat_completions`.
-
-**404 on `/v1/messages?api-version=.../v1/messages`.**
-This is the malformed-URL bug from pre-fix Azure Anthropic setups. Upgrade Hermes — the `api-version` parameter is now passed via `default_query` rather than baked into the base URL, so the SDK can't corrupt it during URL joining.
-
-**Wizard says "Auto-detection incomplete."**
-The endpoint rejected both the `/models` probe and the Anthropic Messages probe. This is normal for private endpoints behind a firewall or with an IP allow-list. Fall back to manual API mode selection and type your deployment name — everything still works, Hermes just can't prefill the picker.
-
-**Wrong transport picked.**
-Run `hermes model` again and the wizard will re-probe. If the probe still picks the wrong mode, you can edit `config.yaml` directly:
-
-```yaml
-model:
-  provider: azure-foundry
-  api_mode: anthropic_messages   # or chat_completions
-```
-
-**Entra ID: "credential chain exhausted" or 401 Unauthorized after switching to `auth_mode: entra_id`.**
-- Run `az login` to refresh your developer session (the cached token may have expired).
-- Verify the `Azure AI User` (or `Foundry User`) role assignment took effect: `az role assignment list --assignee <user-or-identity-id>` should list it on your Foundry resource. Role propagation can take up to 5 minutes.
-- For user-assigned managed identities, double-check `AZURE_CLIENT_ID` matches the identity attached to the compute resource.
-- Run `hermes doctor` — the Azure Entra probe reports whether token acquisition succeeded and includes a remediation hint.
-
-**Entra ID: wizard preflight hangs or times out.**
-The 10 s preflight is a soft check. Choose "Save anyway and validate later" and run `hermes doctor` after deploying to the target environment. Common causes include an unreachable token service or stale local login state — prefer workload identity in CI, set `AZURE_TENANT_ID`+`AZURE_CLIENT_ID`+`AZURE_CLIENT_SECRET` when using a service principal, or run `az login` for local development.
-
-**401 on Anthropic-style endpoint with Entra ID.**
-Verify the same `Azure AI User` (or `Foundry User`) role is assigned on the Foundry resource (it covers both `/openai/v1` and `/anthropic` paths). If the OpenAI-style probe works during the wizard but `claude-*` requests fail at runtime, the most common cause is a stale `model.entra.scope` left over from an earlier wizard run — delete the `entra.scope` line from `config.yaml` so the runtime falls back to the default `https://ai.azure.com/.default` scope.
-
-## Related
-
-- [Environment variables](/reference/environment-variables)
-- [Configuration](/user-guide/configuration)
-- [AWS Bedrock](/guides/aws-bedrock) — the other major cloud provider integration
-- [Microsoft: Configure Entra ID for Foundry](https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id) — upstream documentation for the keyless path