docs(proxy): document agent env routing

Author: echobt

docs/challenges.md

@@ -37,3 +37,17 @@ Public routes are exposed through:
 ```
 
 The master blocks `/internal/*`, `/health`, and `/version` from the public proxy.
+
+## Proxy failure behavior
+
+Platform proxy should preserve challenge-origin non-2xx responses when the challenge answered with a safe response. Transport failures, unreachable services, missing Kubernetes targets, DNS failures, and connection timeouts become safe 502 responses at Platform. Frontends should render unavailable copy and retry with backoff instead of showing raw text such as `Platform request failed with status 502`.
+
+Operator checklist for challenge 502s:
+
+1. Confirm ingress includes `/challenges` and routes it to Platform proxy.
+2. Confirm the slug maps to a running challenge service.
+3. Confirm challenge service health, service DNS, service port, and pod readiness.
+4. In Kubernetes target mode, confirm target assignment, target health, and capacity state.
+5. Check whether the response came from proxy transport handling or from the challenge origin. Only transport failures should be rewritten to 502.
+
+Agent Challenge env and launch routes are public proxy routes, but Platform does not store their request bodies or per-submission env values. The allowed Platform paths are `GET/PUT /challenges/agent-challenge/submissions/{id}/env`, `POST /challenges/agent-challenge/submissions/{id}/env/confirm-empty`, and `POST /challenges/agent-challenge/submissions/{id}/launch`. The challenge-local paths are `GET/PUT /submissions/{id}/env`, `POST /submissions/{id}/env/confirm-empty`, and `POST /submissions/{id}/launch`. Only signed miner headers `X-Hotkey`, `X-Signature`, `X-Nonce`, and `X-Timestamp` are preserved for those routes.

docs/miner/README.md

@@ -43,6 +43,10 @@ GET /v1/registry
 GET /challenges/agent-challenge/benchmarks
 GET /challenges/agent-challenge/submissions/{id}/status
 GET /challenges/agent-challenge/submissions/{id}/events
+GET /challenges/agent-challenge/submissions/{id}/env
+PUT /challenges/agent-challenge/submissions/{id}/env
+POST /challenges/agent-challenge/submissions/{id}/env/confirm-empty
+POST /challenges/agent-challenge/submissions/{id}/launch
 GET /challenges/agent-challenge/leaderboard
 ```
 
@@ -59,6 +63,54 @@ For v1 lists, `/challenges/agent-challenge/submissions` returns the latest 100 s
 
 The public proxy blocks `/internal/*`, `/health`, and `/version`.
 
+## Agent Challenge Miner Env Actions
+
+After Agent Challenge analysis allows an artifact, a master validator pauses it at public state `Waiting for miner action`. The exact challenge lifecycle is `analysis_allowed -> waiting_miner_env -> tb_queued -> tb_running`. The miner must either save env vars or confirm that no env vars are needed before launch.
+
+Platform public paths, including the exact shorthand `GET/PUT /challenges/agent-challenge/submissions/{id}/env`:
+
+```http
+GET /challenges/agent-challenge/submissions/{id}/env
+PUT /challenges/agent-challenge/submissions/{id}/env
+POST /challenges/agent-challenge/submissions/{id}/env/confirm-empty
+POST /challenges/agent-challenge/submissions/{id}/launch
+```
+
+Agent Challenge local paths behind the proxy, including the exact shorthand `GET/PUT /submissions/{id}/env`:
+
+```http
+GET /submissions/{id}/env
+PUT /submissions/{id}/env
+POST /submissions/{id}/env/confirm-empty
+POST /submissions/{id}/launch
+```
+
+These requests are signed by the miner. Docs and examples must use fake placeholders only:
+
+```http
+X-Hotkey: <miner-hotkey>
+X-Signature: <signature>
+X-Nonce: <nonce>
+X-Timestamp: <timestamp>
+```
+
+Env keys must match `^[A-Za-z_][A-Za-z0-9_]{0,127}$`. Each request can contain at most 64 keys, each value is limited to 16 KiB, and the total payload is limited to 128 KiB. `PUT /env` replaces the full env set. `POST /env/confirm-empty` is required when the agent needs zero env vars, so it does not stay stuck waiting for miner action. `POST /launch` locks env metadata and starts Terminal-Bench queueing.
+
+Env values are write-only. Responses expose metadata only: keys, count, empty confirmation, lock state, and timestamps. Values are scoped to the master validator, encrypted at rest in Agent Challenge storage, injected into the Harbor/Terminal-Bench runtime, and cannot be retrieved after submission. Platform registry and Platform proxy do not store per-submission env values. Platform only forwards the allowed signed miner headers for these env and launch routes and keeps other sensitive caller headers stripped.
+
+## Agent Challenge 502 Troubleshooting
+
+A 502 under `/challenges/agent-challenge/...` is a safe unavailable state from Platform proxy transport handling. Frontends should render safe unavailable copy, not raw text such as `Platform request failed with status 502`.
+
+Checklist:
+
+1. Confirm ingress routes `/challenges` to Platform proxy. A route for `/v1/challenges` alone is not enough.
+2. Confirm Platform proxy slug routing points at the Agent Challenge service and still blocks `/internal/*`, `/health`, and `/version`.
+3. Confirm Agent Challenge health, pod readiness, service DNS, and service port from the Platform namespace.
+4. In Kubernetes target mode, confirm target assignment, target health, and capacity state.
+5. Separate proxy transport failures from challenge-origin non-2xx responses. Transport failures become safe 502 responses. Challenge-origin non-2xx responses should pass through as safe validation, auth, replay, rate-limit, or challenge error responses.
+6. If the failing request is an env action, confirm the request uses `GET/PUT /challenges/agent-challenge/submissions/{id}/env`, `POST /challenges/agent-challenge/submissions/{id}/env/confirm-empty`, or `POST /challenges/agent-challenge/submissions/{id}/launch`, and includes only the signed miner header names above.
+
 ## What Platform Does For Miners
 
 Platform provides:

docs/security.md

@@ -11,6 +11,7 @@
 * Internal challenge calls require per-challenge shared tokens.
 * Public proxy strips sensitive headers.
 * Public proxy blocks internal challenge paths.
+* Agent Challenge env and launch proxy routes preserve only `X-Hotkey`, `X-Signature`, `X-Nonce`, and `X-Timestamp` for signed miner actions.
 
 ## Production Policy Boundaries
 
@@ -43,6 +44,10 @@ Kubernetes broker runs attempt to delete the Job, NetworkPolicy, and mount Secre
 
 Admin tokens, challenge tokens, kubeconfigs, production database URLs, per-challenge database URLs, registry credentials, and wallet material must come from files, environment variables, or Kubernetes Secrets. Don't store clear text secrets in registry metadata responses, docs, or evidence files.
 
+Agent Challenge miner env values are per-submission secrets owned by the challenge, not by Platform registry. They are master-validator scoped, encrypted at rest by Agent Challenge, injected into Harbor/Terminal-Bench runtime, and cannot be retrieved after submission. Platform proxy forwards the request body to the challenge but must not parse, persist, log, registry-serialize, or evidence-capture submitted env values. Public responses can expose metadata only: env keys, count, empty confirmation, lock state, and timestamps.
+
 ## Failure Behavior
 
 If a challenge fails health checks or `get_weights`, its contribution is zero for that epoch. The master doesn't auto-disable it.
+
+For public challenge requests, transport failures at ingress, Platform proxy, challenge service discovery, or Kubernetes target routing become safe 502 responses. Challenge-origin non-2xx responses should pass through when they are safe. User interfaces should render unavailable copy and must not display raw text such as `Platform request failed with status 502`.