Description

docs/reference/architecture.md and docs/get-started/prerequisites.md describe the OpenShell gateway exclusively as a Docker container that embeds a k3s cluster running the sandbox as a Kubernetes pod. That description is now out of date as of NemoClaw 0.0.39 (#3001), which routes onboarding through the OpenShell Docker-driver gateway on Linux and Apple Silicon. On those platforms, the sandbox runs as a Docker container alongside the gateway rather than as a Kubernetes pod inside an embedded k3s cluster.

The 0.0.39 release notes in docs/about/release-notes.md call out the Docker-driver migration. The release just shipped, so it makes sense the architecture and prerequisites pages have not had a chance to catch up yet. Filing this so the gap is on the docs team's radar, with a proposed PR ready when convenient.

Where the pages are out of date:

1. git log v0.0.38..v0.0.39 --oneline | grep -i 'docker\|k3s\|driver' shows feat(onboard): use OpenShell Docker GPU sandboxes #3001 (feat(onboard): use OpenShell Docker GPU sandboxes) and fix(onboard): use Docker-driver gateway on macOS OpenShell 0.0.37 #3383 (fix(onboard): use Docker-driver gateway on macOS OpenShell 0.0.37).
2. src/lib/onboard.ts:3411-3416 - isLinuxDockerDriverGatewayEnabled returns true for platform === "linux" and for platform === "darwin" && arch === "arm64". So Linux and Apple Silicon use the Docker-driver gateway by default with no opt-in.
3. docs/reference/architecture.md:93-94 - "The OpenShell gateway runs as a container that embeds a k3s cluster. The sandbox runs as a Kubernetes pod inside that embedded cluster." - universal statement, no platform qualification.
4. docs/reference/architecture.md:117 - the deployment-topology Mermaid diagram nests the sandbox inside an "Embedded k3s cluster" subgraph, with no Docker-driver variant.
5. docs/reference/architecture.md:148-150 - the layering table calls out Gateway container -> embedded k3s control plane, k3s -> Kubernetes control plane that schedules the sandbox pod, Sandbox pod -> Pod in the embedded k3s cluster. None of those apply on the Docker-driver path.
6. docs/get-started/prerequisites.md:35 - "the Docker daemon, k3s, and the OpenShell gateway run alongside the export pipeline" - describes RAM consumption framed around k3s as a separate process.

Current dual-path reality:

src/lib/cluster-image-patch.ts:11-17 confirms the legacy k3s path is still required on those platforms ("until the upstream OpenShell roadmap migration off k3s lands. NemoClaw downstream cannot wait."), so the docs cannot drop k3s entirely yet.

Affected Page

• docs/reference/architecture.md (lines 93-94, 117, 148-150)
• docs/get-started/prerequisites.md (lines 35, 55)

Issue Type

Inaccurate information

Suggested Fix

Refresh both pages so the architecture text and diagrams reflect the dual-path reality, and the prerequisites RAM note no longer lists k3s as a standalone process. Concretely:

• docs/reference/architecture.md: add a one-paragraph "Compute model" lead-in to the Deployment Topology section that names both paths and the platform matrix above. Identify the existing topology diagram as the legacy k3s path. Update the layering table to include both rows for "Sandbox" depending on driver.
• docs/get-started/prerequisites.md:35: rewrite the RAM-consumer sentence to drop k3s as a standalone listing (it is an internal detail of the gateway container image, not a separate top-level process users budget RAM for).
• docs/get-started/prerequisites.md:55: keep the existing fuse-overlayfs note but reword "limitation in k3s" to "limitation in the OpenShell gateway image".

A PR with the proposed changes is up at #3433. Open to any reframing the docs team prefers.