docs: document per-driver compute-driver features

- README.md gains a "Choosing Which Compute Drivers Are Compiled In"
  section covering the four driver features, the extension-only
  build shape, and the startup-time compiled-out rejection.
- architecture/compute-runtimes.md gains a "Compile-Time Driver
  Selection" section covering the four driver features, the
  extension-only zero-driver build, the startup-time missing-driver
  error, filtered auto-detection, and the always-available extension
  driver path.
- docs/reference/gateway-config.mdx gains a matching reference
  section under "Choosing Which Drivers Are Compiled In" with a
  per-feature table, single-driver / mixed / extension-only build
  examples, and the startup-time rejection contract.

Signed-off-by: Dimitar Mirchev <28221091+dimityrmirchev@users.noreply.github.com>

Author: dimityrmirchev

README.md

@@ -252,12 +252,23 @@ OpenShell collects anonymous telemetry to help improve the project for developer
 
 Disable telemetry at runtime by setting `OPENSHELL_TELEMETRY_ENABLED=false` on the gateway deployment. OpenShell propagates this deployment setting into sandbox supervisor environments so sandbox-side telemetry collection is disabled as well.
 
-You can also compile telemetry out entirely. Telemetry support is a default-on `telemetry` Cargo feature; building with `--no-default-features` produces binaries that contain no telemetry endpoint, no telemetry HTTP client, and no emission code. Build telemetry-free artifacts with, for example, `cargo build --release -p openshell-server --no-default-features` (gateway) and the equivalent for `openshell-sandbox` and `openshell-driver-vm`. With telemetry compiled out, the gateway emits nothing and reports telemetry disabled to the sandboxes it launches.
+You can also compile telemetry out entirely. Telemetry support is a default-on `telemetry` Cargo feature; building `openshell-server` with `--no-default-features` and selecting only the driver features you need produces a gateway that contains no telemetry endpoint, no telemetry HTTP client, and no emission code. The gateway requires at least one compute driver to link; for example, `cargo build --release -p openshell-server --bin openshell-gateway --no-default-features --features driver-kubernetes,driver-docker,driver-podman,driver-vm` builds a telemetry-free gateway with every driver. Build telemetry-free `openshell-sandbox` and `openshell-driver-vm` binaries with a plain `--no-default-features`. With telemetry compiled out, the gateway emits nothing and reports telemetry disabled to the sandboxes it launches.
 
 Telemetry events are limited to anonymous operational categories and counts, such as sandbox lifecycle outcomes, provider profile buckets, policy decision counts, and aggregate network activity denial categories. OpenShell telemetry does not collect sandbox names or IDs, hostnames, file paths, binary paths, prompts, credentials, provider names, model names, or user content.
 
 Opting out applies only to telemetry emitted by OpenShell. Third-party services, model providers, inference endpoints, agents, or tools that you configure and use with OpenShell may have their own terms and privacy practices.
 
+## Choosing Which Compute Drivers Are Compiled In
+
+Each built-in compute driver — Kubernetes, Docker, Podman, VM — is gated by a Cargo feature on `openshell-server` (`driver-kubernetes`, `driver-docker`, `driver-podman`, `driver-vm`), all enabled by default. Operators who only need one driver can produce a slimmer gateway with a reduced supply-chain surface by building with `--no-default-features` and enabling the drivers they want:
+
+```shell
+cargo build --release -p openshell-server --bin openshell-gateway \
+  --no-default-features --features driver-kubernetes,telemetry
+```
+
+Any non-empty driver subset is a valid build, including zero built-in drivers (an extension-only gateway that reaches an out-of-tree driver over `[openshell.drivers.<name>].socket_path`). What the gateway needs at *runtime* is a `compute_drivers` entry it can serve: either a built-in this binary was built with, or an extension driver name with a matching socket_path entry. Naming a built-in that this gateway was not built with fails at startup with a message naming both the driver and the Cargo flag that re-enables it. Extension drivers reached via `--compute-driver-socket` work regardless of the feature set. See the [gateway configuration reference](docs/reference/gateway-config.mdx) for details.
+
 ## Notice and Disclaimer
 
 This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided "AS IS", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.

architecture/compute-runtimes.md

@@ -117,3 +117,27 @@ them without changing the sandbox architecture.
 
 When runtime infrastructure changes, validate the relevant sandbox e2e path and
 update the matching driver README if a maintainer-facing constraint changes.
+
+## Compile-Time Driver Selection
+
+Each built-in runtime is gated by a Cargo feature on `openshell-server`:
+`driver-kubernetes`, `driver-docker`, `driver-podman`, `driver-vm`. All
+four are on by default, so the default gateway is byte-equivalent to
+before the feature split. Building `--no-default-features` and selecting a
+subset produces a gateway that carries only the requested drivers, along
+with their transitive dependencies and driver-specific plumbing (Docker's
+supervisor readiness impl, the K8s ServiceAccount authenticator, the VM
+subprocess launcher, and so on).
+
+A zero-driver build is a supported extension-only gateway shape. It
+carries no in-tree driver code and speaks `compute_driver.proto` only to
+out-of-tree drivers named in `compute_drivers` with a matching
+`[openshell.drivers.<name>].socket_path`. A driver named in
+`gateway.toml` that this binary was not built with fails at startup with
+a message naming both the driver and the Cargo flag that re-enables it;
+auto-detection skips drivers that were compiled out and falls through to
+a "no suitable driver" error rather than silently picking a
+different backend. Extension drivers reached via
+`--compute-driver-socket` are always available regardless of driver
+features — they run out-of-process and the gateway only needs to speak
+`compute_driver.proto`.

docs/reference/gateway-config.mdx

@@ -340,3 +340,47 @@ compute_drivers = ["kyma"]
 [openshell.drivers.kyma]
 socket_path = "/run/openshell/kyma-compute-driver.sock"
 ```
+
+## Choosing Which Drivers Are Compiled In
+
+Each built-in compute driver is gated by a Cargo feature on
+`openshell-server`, all enabled by default. Operators who only need one
+driver can produce a smaller gateway with a reduced supply-chain surface
+by building `--no-default-features` and selecting a subset:
+
+| Feature | Compiles in |
+|---|---|
+| `driver-kubernetes` | Kubernetes driver, K8s ServiceAccount authenticator, `kube-rs` and K8s client dependencies. |
+| `driver-docker` | Docker driver, `bollard` and Docker-specific supervisor readiness plumbing. |
+| `driver-podman` | Podman driver and libpod REST client. |
+| `driver-vm` | In-server plumbing for spawning `openshell-driver-vm` and speaking to it over UDS. The driver binary itself is packaged separately. |
+| `telemetry` | Anonymous telemetry emission. |
+
+Kubernetes-only gateway:
+
+```shell
+cargo build --release -p openshell-server --bin openshell-gateway \
+  --no-default-features --features driver-kubernetes,telemetry
+```
+
+Docker + Podman gateway (drops K8s and VM code and their transitive
+dependencies):
+
+```shell
+cargo build --release -p openshell-server --bin openshell-gateway \
+  --no-default-features --features driver-docker,driver-podman,telemetry
+```
+
+Extension-only gateway (no in-tree drivers; talks only to an out-of-tree
+driver over a Unix socket) with disabled telemetry:
+
+```shell
+cargo build --release -p openshell-server --bin openshell-gateway --no-default-features
+```
+
+This build carries no built-in driver code. `compute_drivers` must name an
+extension driver with a matching `[openshell.drivers.<name>].socket_path`.
+Configuring a driver in `gateway.toml` that this gateway was not built with fails at startup with a
+message naming both the driver and the Cargo flag that re-enables it.
+Extension drivers reached via `--compute-driver-socket` do not depend on any
+driver feature and work regardless.