Clarify result server key roles and shell CI deps

.github/workflows/result-server-tests.yml

@@ -88,6 +88,14 @@ jobs:
       - name: Check out repository
         uses: actions/checkout@v4
 
+      - name: Check shell test dependencies
+        run: |
+          set -euo pipefail
+          command -v jq
+          jq --version
+          command -v python3
+          python3 --version
+
       - name: Run profiler, profile-data, and estimation shell tests
         run: |
           bash scripts/tests/test_bk_profiler.sh

docs/deploy/key-management.md

@@ -9,12 +9,24 @@ Production deployments must provide:
 - `FLASK_SECRET_KEY`: at least 32 characters, generated randomly.
 - `RESULT_SERVER_KEYS`: one or more runner-scoped ingest keys.
 
-Use runner-scoped keys instead of the legacy `RESULT_SERVER_KEY`:
+Use runner-scoped server keys instead of the legacy server-side
+`RESULT_SERVER_KEY` fallback:
 
 ```text
 RESULT_SERVER_KEYS=runner-a:<RUNNER_A_KEY>,runner-b:<RUNNER_B_KEY>
 ```
 
+`RESULT_SERVER_KEYS` is the server-side registry of accepted posting/query
+keys. It is intentionally broader than the current single-key CI setup so that
+the portal can later accept results from multiple trusted CI sources, such as
+the main BenchKit CI, site-managed runners, collaborator forks, or
+estimator-only pipelines.
+
+Each client job still receives a single `RESULT_SERVER_KEY` secret for its own
+uploads. This client-side key must match one entry in `RESULT_SERVER_KEYS`, and
+it is typically injected through GitLab CI/CD variables or another CI secret
+mechanism rather than stored on the runner host.
+
 Each key must be at least 32 characters and must not use known insecure
 examples such as `dev-api-key`, `changeme`, or `secret`. The production app
 refuses to start when these checks fail.
@@ -37,12 +49,13 @@ For a normal runner key rotation:
 
 1. Add the new key to `RESULT_SERVER_KEYS` while keeping the old key.
 2. Deploy the portal configuration.
-3. Update the runner to use the new key.
+3. Update the corresponding CI secret so affected jobs receive the new
+   client-side `RESULT_SERVER_KEY`.
 4. Confirm successful ingest events for the runner.
 5. Remove the old key after the agreed overlap window.
 
 If a key may have leaked, remove it immediately, deploy the portal, update the
-affected runner, and review ingest logs for suspicious activity.
+affected CI secret, and review ingest logs for suspicious activity.
 
 ## Logging
 

docs/guides/developer-reference.md

@@ -248,8 +248,10 @@ For production portal deployments:
 - Set `FLASK_SECRET_KEY` to a strong secret and run `result_server/app.py`, not `app_dev.py`.
 - `app.py` binds to `127.0.0.1:8800` by default; set `RESULT_SERVER_HOST` and `RESULT_SERVER_PORT` explicitly when the deployment requires a different bind address.
 - Set runner-scoped ingest keys with `RESULT_SERVER_KEYS=runner-a:<RUNNER_A_KEY>,runner-b:<RUNNER_B_KEY>`.
+- `RESULT_SERVER_KEYS` is the server-side registry of accepted posting/query keys. It is intentionally broader than the current single-key CI setup so the portal can later accept results from multiple trusted CI sources such as main BenchKit CI, site-managed runners, collaborator forks, or estimator-only pipelines.
+- Each client job still receives a single `RESULT_SERVER_KEY` secret for its own upload/query operations, usually through GitLab CI/CD variables or another CI secret store. That client-side key must match one entry in server-side `RESULT_SERVER_KEYS`.
 - `FLASK_SECRET_KEY` and each ingest key must be at least 32 characters and must not use known insecure examples such as `dev-api-key`, `changeme`, or `secret`; production startup refuses these values.
-- The legacy `RESULT_SERVER_KEY` variable is still accepted as runner `default` for compatibility, but should be rotated to `RESULT_SERVER_KEYS`.
+- The legacy server-side `RESULT_SERVER_KEY` variable is still accepted as runner `default` for compatibility, but production portal deployments should rotate the accepted-key registry to `RESULT_SERVER_KEYS`.
 - See `docs/deploy/key-management.md` for generation and rotation guidance.
 - `REDIS_URL` must point to a monitored Redis instance; production authentication refuses login when Redis is unavailable.
 - Login verification, API ingest/query, and admin write endpoints use Redis-backed rate limits by default; set `RESULT_SERVER_MAX_UPLOAD_MB` and `RESULT_SERVER_MAX_ARCHIVE_MEMBER_MB` when deployment-specific upload limits are needed.