docs(runtimes): driver TOML examples omit [openshell] version = 2 and fail preflight

[fede-kamel]

User Story

As an operator configuring a compute driver from the Runtimes documentation, I want the TOML snippets there to be valid on their own, so that copying one into a fresh gateway.toml doesn't stop the gateway from starting.

Problem Statement

The Docker, Podman, and MicroVM sections of docs/how-it-works/sandboxes/runtimes.mdx show snippets like this:

[openshell.gateway]
compute_driver = "docker"

[openshell.drivers.docker]
socket_path = "/var/run/docker.sock"

Put into a new ~/.config/openshell/gateway.toml (the Linux package installs none), this makes the service fail at ExecStartPre=openshell-gateway config preflight:

gateway config preflight failed: ... category=missing_version detected_version=missing;
the file was preserved unchanged; migrate it before restarting the gateway

The snippets omit [openshell] / version = 2, which configuration.mdx shows but runtimes.mdx doesn't.

Impact / Why This Matters

The error tells the user to follow the schema v2 migration steps. That's confusing for someone who never had a v1 file, and it isn't obvious that the documented snippet itself is incomplete. The gateway stays down until they find the missing key.

Acceptance Criteria

• The TOML examples in runtimes.mdx include [openshell] / version = 2, or the page states once, before the first example, that every file needs it.
• Optional: when a file has only v2-shaped tables and no version key, the preflight message suggests adding [openshell] version = 2 rather than pointing to a migration.

Reproduction Steps

1. Linux install with no existing ~/.config/openshell/gateway.toml.
2. Copy the Docker driver snippet from runtimes.mdx into that file.
3. Run openshell-gateway config preflight. It fails with missing_version.

Environment

• OpenShell 0.1.2, gateway as a systemd user service (Debian package layout)

[purp]

📋 triage-agent

Triage Assessment

Classification: validated-bug

Summary

Confirmed from code and docs on main. Standalone gateway TOML examples in docs/how-it-works/sandboxes/runtimes.mdx omit [openshell] / version = 2, and gateway preflight rejects any file with an openshell table but no version key. High confidence.

Investigation

• runtimes.mdx has five standalone examples that start at [openshell.gateway] with no schema version: lines 30-33 (driver selection), 43-49 (extension driver), 87-93 (Docker), 163-166 (Podman), 186-194 (VM). That is two more than the issue lists. The bind-mount fragment at 142-149 is a partial example meant to be merged into an existing file.
• crates/openshell-server/src/config_file.rs:674-684: preflight() returns missing_version when detected_version() (:618-635) finds an openshell table without version. [openshell.gateway] creates that table implicitly, so each snippet fails exactly as reported. parse_and_validate (:581-585) applies the same rule when the gateway loads the file.
• The error text (config_file.rs:486) always says "migrate it before restarting the gateway" and links the schema v2 migration section (:481). The missing_version category does not distinguish a fresh file from a legacy v1 file, which explains the confusing guidance.
• docs/how-it-works/gateways/configuration.mdx:46-48 and :68-74 document the requirement correctly. The gap is limited to runtimes.mdx.
• The requirement was introduced by the schema v2 cutover (refactor(config): normalize and enforce gateway schema v2 #2814) and has shipped since v0.1.0. It is still present in v0.1.2 (latest) and on main.
• No duplicate issues found. docs(runtimes): show required schema version in gateway TOML examples #3910 (open, by the reporter) proposes a docs change to runtimes.mdx.
• The optional acceptance criterion (a preflight hint for v2-shaped files that lack a version) is a separate gateway change. It looks feasible: the gateway would need to recognise v2-only tables before choosing the message.

Impact Signals

• Affected users/scope: Users who build a new gateway.toml from the Runtimes page, especially Linux package installs, which ship no config file. The gateway service stays down until the file is fixed.
• Regression: Docs drift since the schema v2 cutover (refactor(config): normalize and enforce gateway schema v2 #2814). No runtime behavior regressed.
• Workaround: Available. Add [openshell] / version = 2 at the top of the file, as shown in the Gateway Configuration reference.
• Evidence quality: High. The failing code path and the affected doc lines are both directly observable on main.

Human Decision Required

Decide whether OpenShell should address this issue. If yes, apply
state:accepted, associate it with a roadmap item, or do both, and decide
whether the work remains human-owned. Either action records acceptance;
roadmap placement additionally records sequencing.
To queue investigation or planning for an unattended agent, also apply
agent:plan-requested. You can instead directly ask an agent to use
create-spike or build-from-issue on this issue; the agent will warn about
missing expected workflow labels and continue without changing them. If no,
close it as not planned and record the rationale.