bug: Kubernetes setup guide points at a nonexistent agent-sandbox manifest.yaml asset

Bắt đầu từ dòng 36 và 55 trong docs/kubernetes/setup.mdx, sau đó kiểm tra các release assets của Agent Sandbox v1.0.3 và hành vi của sandbox.yaml. Đảm bảo cả hướng dẫn setup và air-gapped đều sử dụng một core bundle URL hoạt động, đồng thời ghi lại liệu URL có nên được ghim thay vì sử dụng latest hay không.

User Story

As an operator installing OpenShell on Kubernetes for the first time, I want the documented prerequisite commands to work, so that I can complete the setup without having to diagnose a broken URL before I have installed anything.

Problem Statement

docs/kubernetes/setup.mdx:36 instructs operators to install the Agent Sandbox controller and CRDs with:

kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml

That asset no longer exists. Upstream kubernetes-sigs/agent-sandbox renamed its release assets; the current release (v1.0.3) publishes extensions.yaml, sandbox-with-extensions.yaml, and sandbox.yaml, and no manifest.yaml. The latest redirect resolves correctly to the v1.0.3 tag, then 404s on the asset name.

The correct asset is sandbox.yaml. Its contents match what the surrounding documentation already promises at line 39: it creates the agent-sandbox-system namespace, installs the sandboxes.agents.x-k8s.io CRD (served at v1beta1), and starts the controller Deployment along with its ServiceAccount, ClusterRole, ClusterRoleBinding, and Service.

Two nearby lines depend on the same asset name and should be checked in the same change:

• docs/kubernetes/setup.mdx:55 tells air-gapped operators to "mirror the manifest above," which inherits the wrong name.
• The install is pinned to latest, which is what allowed an upstream rename to silently break the documented path.

Impact / Why This Matters

This is the first command in the Kubernetes setup guide, and it fails before any OpenShell component is installed. An operator following the published documentation hits a 404 with no indication of what the correct asset is; latest/download/manifest.yaml gives no hint that the name changed rather than the release being missing.

The current workaround is to inspect the upstream repository's release assets and substitute the correct filename. That is insufficient because it requires the operator to know that OpenShell needs the core controller and CRD bundle specifically — sandbox.yaml — rather than sandbox-with-extensions.yaml or extensions.yaml, a choice the documentation never describes. It also blocks the documented path for air-gapped installs, where the operator must mirror the asset before they can reach a cluster at all.

Because the Kubernetes compute driver cannot function without these CRDs, and the OpenShell chart's preflight check fails without them, this blocks the entire documented Kubernetes install.

Acceptance Criteria

• docs/kubernetes/setup.mdx references an Agent Sandbox asset URL that resolves successfully.
• The documented URL installs the agent-sandbox-system namespace, the sandboxes.agents.x-k8s.io CRD, and the controller, matching the behavior already described at docs/kubernetes/setup.mdx:39.
• The air-gapped mirroring guidance at docs/kubernetes/setup.mdx:55 refers to the same, correct asset.
• A decision is recorded on whether to pin the documented URL to a known-good Agent Sandbox version instead of latest, so a future upstream rename cannot silently break the documented install path again.

Reproduction Steps

1. Follow docs/kubernetes/setup.mdx against any Kubernetes cluster.
2. Run the Agent Sandbox install command from line 36.
3. Observe the command fail before anything is installed.

Environment

• OpenShell: main at cb93f62bf
• OS: macOS 15 (Darwin 25.6.0), arm64
• Runtime: k3d v5 / k3s v1.31.5+k3s1, kubectl client v1.31
• Upstream: kubernetes-sigs/agent-sandbox v1.0.3

Logs

$ kubectl apply -f https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml
error: unable to read URL "https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml", server reported 404 Not Found, status code=404

$ curl -sIL -o /dev/null -w '%{http_code} %{url_effective}\n' \
    https://github.com/kubernetes-sigs/agent-sandbox/releases/latest/download/manifest.yaml
404 https://github.com/kubernetes-sigs/agent-sandbox/releases/download/v1.0.3/manifest.yaml

$ gh api repos/kubernetes-sigs/agent-sandbox/releases/latest --jq '.tag_name, (.assets[] | .name)'
v1.0.3
extensions.yaml
sandbox-with-extensions.yaml
sandbox.yaml

Verified that sandbox.yaml is the correct replacement — applying it produced the agent-sandbox-system namespace, the sandboxes.agents.x-k8s.io CRD at v1beta1, and a Running controller pod.