docs(gateway): consolidate gateway TOML examples into docs reference

Replaces the per-driver example files under examples/gateway/ with a
single published reference page at docs/reference/gateway-config.mdx
covering source precedence, layout, the full example, and the four
per-driver examples (Kubernetes, Docker, Podman, microVM). Drew flagged
during PR #1317 review that the examples belong with the user-facing
docs rather than in a sibling examples/ directory.

The cross-references in architecture/gateway.md and RFC 0003 are updated
to point at the new docs page; the round-trip test in config_file.rs is
removed (schema coverage stays on the inline parses_full_example test
and per-field merge tests — doc-snippet drift belongs in a separate
docs-lint, not in a cross-tree Rust unit test).

Author: TaylorMutch

architecture/gateway.md

@@ -204,8 +204,8 @@ CLI flag  >  OPENSHELL_* env var  >  TOML file  >  built-in default
 
 The TOML file is opt-in via `--config <PATH>` / `OPENSHELL_GATEWAY_CONFIG`.
 When unset, the gateway behaves exactly as before — CLI flags and env vars
-drive every setting. See `examples/gateway/gateway.example.toml` for a
-worked example and RFC 0003 for the full schema.
+drive every setting. See `docs/reference/gateway-config.mdx` for worked
+per-driver examples and RFC 0003 for the full schema.
 
 `database_url` is env-only and rejected when present in the file
 (`OPENSHELL_DB_URL` / `--db-url`).

crates/openshell-server/src/config_file.rs

@@ -479,25 +479,4 @@ version = 2
             .expect_err("missing file must be io error");
         assert!(matches!(err, ConfigFileError::Io { .. }));
     }
-
-    /// Lock in that every checked-in example under `examples/gateway/`
-    /// round-trips through the loader. Catches schema drift the moment a
-    /// field is renamed or a doc snippet falls out of date.
-    #[test]
-    fn checked_in_examples_parse() {
-        let repo_root = Path::new(env!("CARGO_MANIFEST_DIR"))
-            .parent()
-            .and_then(Path::parent)
-            .expect("crate manifest has grandparent");
-        for name in [
-            "gateway.example.toml",
-            "kubernetes.example.toml",
-            "docker.example.toml",
-            "podman.example.toml",
-            "microvm.example.toml",
-        ] {
-            let path = repo_root.join("examples/gateway").join(name);
-            load(&path).unwrap_or_else(|e| panic!("{name} failed to parse: {e}"));
-        }
-    }
 }

docs/reference/gateway-config.mdx

@@ -0,0 +1,212 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Gateway Configuration File"
+sidebar-title: "Gateway Config"
+description: "Reference for the OpenShell gateway TOML configuration file (RFC 0003)."
+keywords: "Generative AI, Cybersecurity, AI Agents, Sandboxing, Gateway, Configuration, TOML, Reference"
+position: 5
+---
+
+The OpenShell gateway reads its configuration from a TOML file when `--config` or `OPENSHELL_GATEWAY_CONFIG` is set. CLI flags and `OPENSHELL_*` environment variables always override the file. See [RFC 0003](https://github.com/NVIDIA/OpenShell/blob/main/rfc/0003-gateway-configuration/README.md) for the full schema.
+
+## Source Precedence
+
+```text
+CLI flag  >  OPENSHELL_* env var  >  TOML file  >  built-in default
+```
+
+`database_url` and `ssh_handshake_secret` are env-only. The loader rejects them when they appear in the file.
+
+## Layout
+
+The file is rooted at `[openshell]`. Gateway-wide settings live under `[openshell.gateway]`. Each compute driver owns its own `[openshell.drivers.<name>]` table. Shared keys set at gateway scope are inherited into driver tables when not overridden.
+
+```toml
+[openshell]
+version = 1
+
+[openshell.gateway]
+# ... gateway-wide settings ...
+
+[openshell.gateway.tls]
+# ... gateway listener TLS ...
+
+[openshell.gateway.oidc]
+# ... JWT bearer auth ...
+
+[openshell.drivers.kubernetes]
+# ... driver-specific settings ...
+```
+
+## Full Example
+
+A complete gateway configuration covering every section. Trim to the fields you need.
+
+```toml
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address          = "0.0.0.0:8080"
+health_bind_address   = "0.0.0.0:8081"
+metrics_bind_address  = "0.0.0.0:9090"
+
+log_level             = "info"
+
+# When empty the gateway auto-detects (Kubernetes -> Podman -> Docker). VM is
+# never auto-detected and requires an explicit entry here.
+compute_drivers       = ["kubernetes"]
+
+sandbox_namespace     = "openshell"
+sandbox_ssh_port      = 2222
+ssh_gateway_host      = "127.0.0.1"
+ssh_gateway_port      = 8080
+
+# Subject Alternative Names baked into the gateway server certificate.
+# Wildcard DNS SANs (e.g. "*.dev.openshell.localhost") also enable sandbox
+# service URLs under that domain.
+server_sans                  = ["openshell", "*.dev.openshell.localhost"]
+# Allow plaintext HTTP routing for loopback sandbox service URLs.
+enable_loopback_service_http = true
+
+# Shared driver defaults — inherited into [openshell.drivers.<name>] tables
+# when the driver-specific table does not override them.
+default_image          = "ghcr.io/nvidia/openshell/sandbox:latest"
+supervisor_image       = "ghcr.io/nvidia/openshell/supervisor:latest"
+client_tls_secret_name = "openshell-client-tls"
+
+# Gateway listener TLS (distinct from the per-driver guest_tls_*).
+[openshell.gateway.tls]
+cert_path             = "/etc/openshell/certs/gateway.pem"
+key_path              = "/etc/openshell/certs/gateway-key.pem"
+client_ca_path        = "/etc/openshell/certs/client-ca.pem"
+allow_unauthenticated = false
+
+[openshell.gateway.oidc]
+issuer        = "https://idp.example.com/realms/openshell"
+audience      = "openshell-cli"
+jwks_ttl_secs = 3600
+roles_claim   = "realm_access.roles"
+admin_role    = "openshell-admin"
+user_role     = "openshell-user"
+```
+
+`image_pull_policy` is intentionally not a shared gateway key. Kubernetes uses `Always | IfNotPresent | Never` while Podman uses `always | missing | never | newer`. Set it inside the relevant driver table.
+
+## Per-Driver Examples
+
+### Kubernetes
+
+The gateway runs as a Pod and creates sandbox Pods in another namespace. mTLS material for sandboxes is delivered via a Kubernetes Secret rather than host-side file paths.
+
+```toml
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address          = "0.0.0.0:8080"
+health_bind_address   = "0.0.0.0:8081"
+metrics_bind_address  = "0.0.0.0:9090"
+log_level             = "info"
+compute_drivers       = ["kubernetes"]
+
+default_image          = "ghcr.io/nvidia/openshell/sandbox:latest"
+supervisor_image       = "ghcr.io/nvidia/openshell/supervisor:latest"
+client_tls_secret_name = "openshell-client-tls"
+
+[openshell.gateway.tls]
+cert_path      = "/etc/openshell-tls/server/tls.crt"
+key_path       = "/etc/openshell-tls/server/tls.key"
+client_ca_path = "/etc/openshell-tls/client-ca/ca.crt"
+
+[openshell.drivers.kubernetes]
+namespace                  = "agents"
+grpc_endpoint              = "https://openshell-gateway.agents.svc:8080"
+image_pull_policy          = "IfNotPresent"
+# Use the image volume on K8s >= 1.35 (GA in 1.36); switch to "init-container"
+# on older clusters or where the ImageVolume feature gate is off.
+supervisor_sideload_method = "image-volume"
+```
+
+### Docker
+
+Sandboxes run as containers on a local bridge network. The supervisor binary is bind-mounted from the host (no in-cluster image pull required); guest mTLS material is supplied as host paths.
+
+```toml
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address    = "127.0.0.1:8080"
+log_level       = "info"
+compute_drivers = ["docker"]
+
+supervisor_image = "ghcr.io/nvidia/openshell/supervisor:latest"
+guest_tls_ca     = "/etc/openshell/certs/ca.pem"
+guest_tls_cert   = "/etc/openshell/certs/client.pem"
+guest_tls_key    = "/etc/openshell/certs/client-key.pem"
+
+[openshell.drivers.docker]
+network_name   = "openshell-docker"
+# Skip the image-pull-and-extract step by pointing at a locally built binary.
+supervisor_bin = "/usr/local/libexec/openshell/openshell-sandbox"
+```
+
+### Podman
+
+Sandboxes run as Podman containers on a user-mode bridge network. The supervisor image is mounted read-only via Podman's `type=image` mount; guest mTLS material is supplied as host paths.
+
+```toml
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address    = "127.0.0.1:8080"
+log_level       = "info"
+compute_drivers = ["podman"]
+
+default_image     = "ghcr.io/nvidia/openshell/sandbox:latest"
+supervisor_image  = "ghcr.io/nvidia/openshell/supervisor:latest"
+guest_tls_ca      = "/etc/openshell/certs/ca.pem"
+guest_tls_cert    = "/etc/openshell/certs/client.pem"
+guest_tls_key     = "/etc/openshell/certs/client-key.pem"
+
+[openshell.drivers.podman]
+# Rootless socket path. For root Podman use /run/podman/podman.sock.
+socket_path       = "/run/user/1000/podman/podman.sock"
+network_name      = "openshell"
+stop_timeout_secs = 10
+image_pull_policy = "missing"   # Podman vocabulary: always | missing | never | newer
+```
+
+### MicroVM
+
+Each sandbox runs inside its own libkrun microVM managed by the standalone `openshell-driver-vm` subprocess. Use this driver when you want stronger isolation than container namespaces alone.
+
+```toml
+[openshell]
+version = 1
+
+[openshell.gateway]
+bind_address    = "127.0.0.1:8080"
+log_level       = "info"
+# VM is never auto-detected; an explicit entry here is required.
+compute_drivers = ["vm"]
+
+default_image  = "ghcr.io/nvidia/openshell/sandbox:latest"
+guest_tls_ca   = "/var/lib/openshell/guest-tls/ca.pem"
+guest_tls_cert = "/var/lib/openshell/guest-tls/client.pem"
+guest_tls_key  = "/var/lib/openshell/guest-tls/client-key.pem"
+
+[openshell.drivers.vm]
+state_dir      = "/var/lib/openshell/vm"
+# Where the gateway looks for the openshell-driver-vm subprocess binary.
+driver_dir     = "/usr/local/libexec/openshell"
+vcpus          = 2
+mem_mib        = 2048
+krun_log_level = 1
+```

docs/reference/sandbox-compute-drivers.mdx

@@ -32,6 +32,8 @@ Common gateway options:
 | `--sandbox-image <image>` | `OPENSHELL_SANDBOX_IMAGE` | Set the default sandbox image used when a sandbox create request does not specify one. |
 | `--grpc-endpoint <url>` | `OPENSHELL_GRPC_ENDPOINT` | Set the gateway callback endpoint that sandbox workloads use to connect back to OpenShell. |
 
+For the full file-based configuration surface — including gateway-wide settings, TLS, OIDC, and per-driver tables — see the [Gateway Configuration File](./gateway-config) reference. Each driver section below documents the CLI flags and environment variables; their TOML equivalents live in the `[openshell.drivers.<name>]` tables on that page.
+
 Sandbox create supports `--cpu` and `--memory` for per-sandbox compute sizing.
 Docker and Podman apply them as runtime limits. Kubernetes applies them as both
 container requests and limits. The VM driver accepts the fields but currently