Document how people, pods and CI jobs should authenticate to ate-api

README.md

@@ -252,7 +252,7 @@ We provide several sample applications demonstrating Agent Substrate's capabilit
 * [Glossary](docs/glossary.md): Core terms (Actor, Atespace, ActorTemplate, WorkerPool, Worker, ate-api-server, atenet, atelet, ateworker) and how they relate.
 * [Integration Repositories](docs/integration-repos.md): Where integrations live, how their repositories are named, and how fixes flow back to core.
 * [Observability Guide](docs/observability.md): Guide to actor logging, metrics, and distributed tracing.
-* [Authentication Guide](docs/authentication.md): Configure trusted JWT providers and human credentials.
+* [Authentication Guide](docs/authentication.md): Which credential people, pods and CI jobs should use with the Substrate API, and how to trust more JWT issuers.
 * [Egress Traffic](docs/egress-traffic.md): Which protocols an Actor may reach the outside world with and which are blocked.
 * [Enabling man-in-the-middle (MITM) interception for Actor Egress policy](docs/egress-trust-bundle.md): Egress policies such as header injection depend on MITM interception of Actor traffic. This guide explains how an Actor should be configured to enable interception.
 * [Request Parking](docs/request-parking.md): How the router parks requests through transient worker-pool saturation.

cmd/kubectl-ate/README.md

@@ -24,7 +24,9 @@ go run ./cmd/kubectl-ate <command>
 ## Connection & Auto Port-Forwarding
 By default, `kubectl-ate` will automatically read your `~/.kube/config`, discover the `ate-api-server` pods in your cluster, and establish a temporary background port-forward tunnel to execute gRPC calls securely.
 
-If you prefer to route traffic directly (e.g., through a LoadBalancer or when running natively inside a cluster pod), simply provide the `--endpoint` flag to bypass the tunnel.
+If you prefer to route traffic directly (e.g., from a pod in a namespace labeled `ate.dev/api-access=true`), simply provide the `--endpoint` flag to bypass the tunnel. Either way, `kubectl-ate` reads the CA that verifies `ate-api-server` from the cluster, so it needs a kubeconfig or in-cluster config.
+
+For which credential to pass with `--token-file`, see the [Authentication Guide](../../docs/authentication.md#people-running-kubectl-ate).
 
 ## Tracing
 The CLI supports on-demand tracing using the `--trace` flag. When enabled, the CLI will generate a trace ID and signal to the server that it wants the request to be traced.
@@ -66,7 +68,7 @@ These flags can be appended to any command:
 | `--kubeconfig` | | Path to your kubeconfig file | `~/.kube/config` |
 | `--context` | | Name of the kubeconfig context to use | current context |
 | `--endpoint` | | Manual gRPC endpoint override (e.g., `localhost:8080`) | |
-| `--token-file` | | Path to a bearer token for ate-api authentication, or `-` for stdin | Kubernetes ServiceAccount token |
+| `--token-file` | | Path to a bearer token for ate-api authentication, or `-` for stdin | a token for the shared `ate-client` ServiceAccount |
 | `--output` | `-o` | Output format (`table`, `json`, `yaml`) | `table` |
 | `--trace` | | Enable on-demand tracing for the request | `false` |
 | `--verbose` | `-v` | Increase output verbosity; may be repeated or stacked (e.g., `-v`, `-vv`, `-vvvvv`) | `0` |