diff --git a/docs/awf-config-spec.md b/docs/awf-config-spec.md
index e2ab04ed5..a196ca455 100644
--- a/docs/awf-config-spec.md
+++ b/docs/awf-config-spec.md
@@ -1825,6 +1825,19 @@ the first supporting AWF release. Older AWF versions reject the closed
 
 While the backend is still starting, mcpg may return retryable HTTP `503 backend_unavailable`. AWF retries `initialize` with bounded backoff until `AWF_ENCLAVE_MCP_READINESS_TIMEOUT_MS` expires, then fails closed before the primary agent starts.
 
+The gateway has two separate authorization hops. AWF's upstream
+`Authorization` header authenticates mcpg to the AWF-owned enclave server with
+`AWF_ENCLAVE_MCP_CAPABILITY`. mcpg then generates the client-facing gateway
+`Authorization` header from its gateway agent ID/API key; this is the header
+present in mcpg's rewritten gateway output consumed by engine config adapters.
+That downstream credential is distinct from the AWF capability.
+
+Adapters consuming mcpg's rewritten output MUST keep the client-facing
+`Authorization` value runtime-only: they must not resolve it while generating
+configuration or persist the resolved credential under `GITHUB_WORKSPACE` (or
+any other agent-readable path). The AWF upstream contract cannot enforce this
+requirement on the downstream output/converter path.
+
 For `issues-read-v1`, the compiler supplies
 `AWF_ENCLAVE_GITHUB_PROXY_CONTAINER`,
 `AWF_ENCLAVE_GITHUB_PROXY_IDENTITY`,
diff --git a/docs/enclaves-architecture.md b/docs/enclaves-architecture.md
index 376146eef..3cd963e68 100644
--- a/docs/enclaves-architecture.md
+++ b/docs/enclaves-architecture.md
@@ -66,6 +66,21 @@ executor tools. The compiler generates a fresh 64-character lowercase
 hexadecimal capability, substitutes it into the mcpg authorization header, and
 passes it to AWF without exposing it to the primary agent.
 
+### Gateway authorization boundaries
+
+There are two separate authorization hops. AWF's upstream contract
+authenticates mcpg to the AWF-owned enclave server with the
+`AWF_ENCLAVE_MCP_CAPABILITY`. mcpg independently authenticates the client-facing
+gateway endpoint with its gateway agent ID/API key; that is the credential
+returned in mcpg's rewritten gateway output.
+
+Engine config adapters consume mcpg's rewritten output, not AWF's upstream
+contract. Therefore adapters MUST treat the client-facing `Authorization`
+header as a runtime-only value: they must not resolve it while generating
+configuration, and must never persist the resolved gateway credential under
+`GITHUB_WORKSPACE` or any other agent-readable path. AWF's upstream template
+does not enforce this downstream requirement.
+
 `gh-aw-mcpg` may start before the enclave server. While the backend is
 unavailable, mcpg returns retryable HTTP `503 backend_unavailable`; AWF retries
 the complete `initialize` handshake with bounded 500 ms backoff until