diff --git a/docs/configuration.md b/docs/configuration.md
index 6e58fda3..3e75b5ba 100644
--- a/docs/configuration.md
+++ b/docs/configuration.md
@@ -45,7 +45,9 @@ When `gateway_url` / `api_key` are not passed explicitly, the SDK resolves each
 fallback chain (see `agent_assembly.core.gateway_resolver`):
 
 1. **Explicit argument** — the value you pass to `init_assembly()`.
-2. **Environment variable** — `AAASM_GATEWAY_URL` / `AAASM_API_KEY`.
+2. **Environment variable** — `AA_GATEWAY_URL` / `AA_API_KEY`. (The legacy
+   `AAASM_GATEWAY_URL` / `AAASM_API_KEY` names still resolve but emit a
+   `DeprecationWarning` — prefer the `AA_*` names.)
 3. **Config file** — `~/.aasm/config.yaml`.
 4. **Local default** — probe `http://localhost:7391/healthz`; if no gateway is running, the
    SDK attempts to **auto-start** a local one (`aasm start --mode local --foreground`).
@@ -71,8 +73,8 @@ For the full gateway configuration surface (policy files, budgets, mTLS) and the
 [CLI reference](https://docs.agent-assembly.com/core/latest/cli/overview.html) docs.
 
 ```bash
-export AAASM_GATEWAY_URL="https://gateway.example.com"
-export AAASM_API_KEY="…"
+export AA_GATEWAY_URL="https://gateway.example.com"
+export AA_API_KEY="…"
 ```
 
 ### Config file format
diff --git a/docs/examples/preparing-the-runtime-environment.md b/docs/examples/preparing-the-runtime-environment.md
index 5a8c1306..292b48d8 100644
--- a/docs/examples/preparing-the-runtime-environment.md
+++ b/docs/examples/preparing-the-runtime-environment.md
@@ -124,7 +124,7 @@ uv run python src/main.py
     The examples pass `gateway_url` / `api_key` **explicitly** to `init_assembly()`, reading
     them from the `AGENT_ASSEMBLY_*` variables shown above and defaulting to
     `http://localhost:8080`. The SDK *itself* has a separate built-in resolver chain that,
-    when you **omit** those arguments, reads `AASM_GATEWAY_URL` / `AASM_API_KEY`, then
+    when you **omit** those arguments, reads `AA_GATEWAY_URL` / `AA_API_KEY`, then
     `~/.aasm/config.yaml`, then probes a local gateway on `http://localhost:7391`. See
     [Configuration](../configuration.md#resolution-order) for that resolver. The examples use
     explicit arguments, so they use the `AGENT_ASSEMBLY_*` names and the `:8080` default —
diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md
index 194ff924..0278cbcc 100644
--- a/docs/troubleshooting.md
+++ b/docs/troubleshooting.md
@@ -11,7 +11,7 @@ safe.
 
 | Message | Cause | Fix |
 | --- | --- | --- |
-| `gateway_url is required` | No gateway URL could be resolved (no argument, no `AAASM_GATEWAY_URL`, no config file, no local gateway). | Pass `gateway_url=...`, set `AAASM_GATEWAY_URL`, or start a local gateway. See [Configuration](configuration.md#resolution-order). |
+| `gateway_url is required` | No gateway URL could be resolved (no argument, no `AA_GATEWAY_URL`, no config file, no local gateway). | Pass `gateway_url=...`, set `AA_GATEWAY_URL`, or start a local gateway. See [Configuration](configuration.md#resolution-order). |
 | `mode must be one of: auto, ebpf, proxy, sdk-only` | An unknown `mode` value. | Use one of the four valid modes. |
 | `enforcement_mode must be one of: enforce, observe, disabled` | An unknown `enforcement_mode`. | Use a valid posture or leave it `None`. |
 | `eBPF mode is not supported on this platform.` | `mode="ebpf"` on a non-Linux host. | Use `mode="sdk-only"` or `mode="proxy"` off Linux. |
@@ -24,7 +24,7 @@ network layer but the gateway didn't answer.
 
 - Confirm the gateway is running and the URL is correct — by default the SDK probes
   `http://localhost:7391/healthz`.
-- Check `AAASM_GATEWAY_URL` / `AAASM_API_KEY` aren't pointing somewhere stale.
+- Check `AA_GATEWAY_URL` / `AA_API_KEY` (or the deprecated `AAASM_*` aliases) aren't pointing somewhere stale.
 - For a quick local loop, run an `aasm` gateway yourself, or let the SDK auto-start one
   (`aasm start --mode local --foreground`). If auto-start fails, ensure the `aasm` binary is
   on `PATH` — install it via the `agent-assembly[runtime]` extra or the Homebrew tap.