Clarify sandbox and auth docs

[Rachael-Graham]

This update fixes and clarifies documentation around Agent Substrate behavior and setup. It explains the gVisor/micro-VM sandbox model, updates Shared vs Dedicated isolation language, corrects the default issuer setup for Kubernetes auth, and adds warnings about the open-source identity/authentication behavior. The kind provisioner is also aligned with the same issuer-discovery fix.

[kristin-kronstain-brown]

Claude gave me way more feedback than I was expecting. Seems like it could be valid but you won't hurt my feelings if you ignore it.

Findings

Should fix (arguably blocking)

1. installation.md, step 6: the new issuer sentence claims more than the config supports.

The new sentence says "Kubernetes distributions advertise different issuers, so read the issuer from the cluster." The config still always writes certificateAuthorityFile and discoveryTokenFile. Agent Substrate's own installer adds those two lines only for the in-cluster issuers https://kubernetes.default.svc and https://kubernetes.default.svc.cluster.local (cmd/ate-setup/internal/steps/create.go:176-184). Its comment says that an external issuer "needs neither."

• Likely failure (inferred from cmd/ateapi/internal/oidcjwt/http.go, not reproduced on a cluster): Setting certificateAuthorityFile replaces the HTTP client's root CAs with the cluster CA, so JWKS discovery against an external issuer fails TLS.
• Who is affected: kind and default kubeadm clusters work. A cluster with a custom --service-account-issuer does not.
• Suggested fix: Scope the sentence to in-cluster issuers, or add a note that a cluster with an external issuer omits the two lines.

Should fix

2. identity.md: the page now contradicts itself.

The new warnings say that the open source build "neither authenticates nor authorizes" and that its authenticator "declines nothing." These unchanged lines still say the opposite:

• Front-matter description: "Understand how kagent authenticates callers"
• Intro bullet: "is authenticated by kagent's own gRPC API"
• The kagent plane intro: "kagent authenticates these calls itself"

Suggested fix: Reword the unchanged lines, for example "kagent resolves a principal for these calls itself." The warning can then explain that the open source build does not verify that principal.

3. identity.md: the user_id query parameter does not apply to the gRPC API.

The gRPC interceptor calls Authenticate(ctx, headers, url.Values{}) (go/core/internal/grpcserver/interceptors.go), so the AgentInstance API reads only the x-user-id metadata. The user_id query parameter applies only to HTTP /mcp, and there it takes precedence over the header (go/core/internal/httpserver/auth/authn.go:24-31).

Suggested wording: "On the gRPC API, it reads the caller's identity from the X-User-Id header. On /mcp, it also reads the user_id query parameter, which takes precedence."

Nits

4. core-concepts.md: repeated point and a loose phrase. "kagent implements only Shared" and "kagent does not implement Dedicated yet" say the same thing. Also, "adds no compute" is less precise than the original, because the bound agent still uses compute. What the nesting avoids is a second Actor.

5. kagent-kind.sh: lost traceability. The rewritten comment drops the kagent#2763 and #2770 references, which explain why the line exists. Consider keeping them.

6. identity.md: two sentences give the reader nothing to act on. The last two sentences of the new /mcp warning ("kagent's core library takes its authenticator from the program that embeds it. A distribution that verifies caller identity supplies one of its own.") do not tell an open source reader what to do. Consider cutting them, or saying what the reader can do.