docs: remove legacy markdown docs and refresh MDX checks

.agents/skills/nemoclaw-contributor-update-docs/SKILL.md

@@ -67,16 +67,16 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi
 
 | Code area | Likely doc page(s) |
 |---|---|
-| `nemoclaw/src/commands/` (launch, connect, status, logs) | `docs/reference/commands.md` |
-| `nemoclaw/src/commands/` (new command) | May need a new page or entry in `docs/reference/commands.md` |
-| `nemoclaw/src/blueprint/` | `docs/about/architecture.md` |
-| `nemoclaw/src/cli.ts` or `nemoclaw/src/index.ts` | `docs/reference/commands.md`, `docs/get-started/quickstart.md` |
-| `nemoclaw-blueprint/orchestrator/` | `docs/about/architecture.md` |
-| `nemoclaw-blueprint/policies/` | `docs/reference/network-policies.md` |
-| `nemoclaw-blueprint/blueprint.yaml` | `docs/about/architecture.md`, `docs/reference/inference-profiles.md` |
-| `scripts/` (setup, start) | `docs/get-started/quickstart.md` |
-| `Dockerfile` | `docs/about/architecture.md` |
-| Inference-related changes | `docs/reference/inference-profiles.md` |
+| `nemoclaw/src/commands/` (launch, connect, status, logs) | `docs/reference/commands.mdx` |
+| `nemoclaw/src/commands/` (new command) | May need a new page or entry in `docs/reference/commands.mdx` |
+| `nemoclaw/src/blueprint/` | `docs/reference/architecture.mdx` |
+| `nemoclaw/src/cli.ts` or `nemoclaw/src/index.ts` | `docs/reference/commands.mdx`, `docs/get-started/quickstart.mdx` |
+| `nemoclaw-blueprint/orchestrator/` | `docs/reference/architecture.mdx` |
+| `nemoclaw-blueprint/policies/` | `docs/reference/network-policies.mdx` |
+| `nemoclaw-blueprint/blueprint.yaml` | `docs/reference/architecture.mdx`, `docs/inference/inference-options.mdx` |
+| `scripts/` (setup, start) | `docs/get-started/quickstart.mdx` |
+| `Dockerfile` | `docs/reference/architecture.mdx` |
+| Inference-related changes | `docs/inference/inference-options.mdx` |
 
 If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
 
@@ -131,7 +131,7 @@ When updating an existing page:
 When creating a new page:
 
 - Follow the frontmatter template from existing pages in `docs/`.
-- Add the page to the appropriate `toctree` in `docs/index.md`.
+- Add the page to the appropriate navigation entry in `docs/index.yml`.
 
 ## Step 6: Present the Results
 
@@ -141,8 +141,8 @@ After drafting all updates, present a summary to the user:
 ## Doc Updates from Commits
 
 ### Updated pages
-- `docs/reference/commands.md`: Added `eject` command documentation (from commit abc1234).
-- `docs/reference/network-policies.md`: Updated policy schema for new egress rule (from commit def5678).
+- `docs/reference/commands.mdx`: Added `eject` command documentation (from commit abc1234).
+- `docs/reference/network-policies.mdx`: Updated policy schema for new egress rule (from commit def5678).
 
 ### New pages needed
 - None (or list any new pages created).
@@ -189,7 +189,7 @@ Check for:
 Commit changes and open a pull request with a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:
 
 ```markdown
-- #<doc-impacting-PR-number> -> `docs/path.md`: Description of the doc change reflecting the source code changes in the PR.
+- #<doc-impacting-PR-number> -> `docs/path.mdx`: Description of the doc change reflecting the source code changes in the PR.
 ```
 
 Apply the `documentation` label and the corresponding release label so reviewers can identify doc-only changes for the target release.
@@ -220,7 +220,7 @@ User says: "Catch up the docs for everything merged since v0.1.0."
 10. **Release prep only:** Commit changes and open a pull request with the `documentation` label and the corresponding `vX.Y.Z` release label. Include a concise summary of the doc updates and a source summary that links each identified merged PR to its matching doc page. Include the PR number, affected doc page, links, and description of the doc change in this shape:
 
    ```markdown
-   - #<doc-impacting-PR-number> -> `docs/path.md`: Description of the doc change reflecting the source code changes in the PR.
+   - #<doc-impacting-PR-number> -> `docs/path.mdx`: Description of the doc change reflecting the source code changes in the PR.
    ```
 
    If the release label does not exist, report that the PR was created without the release label or that PR creation failed because the label was missing.

.agents/skills/nemoclaw-user-configure-inference/SKILL.md

@@ -6,7 +6,7 @@ description: "Connects NemoClaw to a local inference server. Use when setting up
 <!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# Use a Local Inference Server with NemoClaw
+# Use a Local Inference Server
 
 ## Gotchas
 
@@ -24,7 +24,7 @@ All approaches use the same `inference.local` routing model.
 The agent inside the sandbox never connects to your model server directly.
 OpenShell intercepts inference traffic and forwards it to the local endpoint you configure.
 
-## Step 1: Ollama
+## Ollama
 
 Ollama is the default local inference option.
 The onboard wizard detects Ollama automatically when it is installed or running on the host.
@@ -146,7 +146,7 @@ Run onboard without `--non-interactive` to get the interactive `[y/N]` prompt th
 | `NEMOCLAW_MODEL` | Ollama model tag to use. Optional. |
 | `NEMOCLAW_YES` | Set to `1` to auto-accept the model-download confirmation prompt. Optional. |
 
-## Step 2: OpenAI-Compatible Server
+## OpenAI-Compatible Server
 
 This option works with any server that implements `/v1/chat/completions`, including vLLM, TensorRT-LLM, llama.cpp, LocalAI, and others.
 For compatible endpoints, NemoClaw uses `/v1/chat/completions` by default.
@@ -224,7 +224,7 @@ If you already onboarded and the sandbox is failing at runtime, re-run
 into the image.
 Refer to Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for details.
 
-## Step 3: Anthropic-Compatible Server
+## Anthropic-Compatible Server
 
 If your local server implements the Anthropic Messages API (`/v1/messages`), choose **Other Anthropic-compatible endpoint** during onboarding instead.
 
@@ -242,7 +242,7 @@ $ NEMOCLAW_PROVIDER=anthropicCompatible \
   nemoclaw onboard --non-interactive
 ```
 
-## Step 4: vLLM (Experimental)
+## vLLM (Experimental)
 
 When vLLM is already running on `localhost:8000`, NemoClaw can detect it automatically and query the `/v1/models` endpoint to determine the loaded model.
 On supported Linux hosts with NVIDIA GPUs, the onboard wizard can also install or start a managed vLLM container for you.
@@ -321,7 +321,7 @@ $ NEMOCLAW_EXPERIMENTAL=1 \
 `HUGGING_FACE_HUB_TOKEN` is accepted as an alternative.
 The token check runs on the host before any docker pull, so a missing or empty token aborts onboarding before bandwidth is spent on a 401.
 
-## Step 5: NVIDIA NIM (Experimental)
+## NVIDIA NIM (Experimental)
 
 NemoClaw can pull, start, and manage a NIM container on hosts with a NIM-capable NVIDIA GPU.
 
@@ -357,7 +357,7 @@ $ NEMOCLAW_EXPERIMENTAL=1 \
 
 To select a specific model, set `NEMOCLAW_MODEL`.
 
-## Step 6: Timeout Configuration
+## Timeout Configuration
 
 Local inference requests use a default timeout of 180 seconds.
 Large prompts on hardware such as DGX Spark can exceed shorter timeouts, so NemoClaw sets a higher default for Ollama, vLLM, NIM, and compatible-endpoint setup.
@@ -385,7 +385,7 @@ $ nemoclaw onboard
 
 If onboard ends with `Sandbox '<name>' was created but did not become ready within 180s`, refer to Troubleshooting (use the `nemoclaw-user-reference` skill).
 
-## Step 7: Verify the Configuration
+## Verify the Configuration
 
 After onboarding completes, confirm the active provider and model.
 
@@ -397,7 +397,7 @@ The output shows the provider label (for example, "Local vLLM" or "Other OpenAI-
 For Local Ollama, status also checks the authenticated proxy when a proxy token is available.
 If `Inference` is healthy but `Inference (auth proxy)` is not, rerun onboarding to repair the proxy path that sandbox requests use.
 
-## Step 8: Switch Models at Runtime
+## Switch Models at Runtime
 
 You can change the model without re-running onboard.
 Refer to Switch Inference Models (use the `nemoclaw-user-configure-inference` skill) for the full procedure.

.agents/skills/nemoclaw-user-configure-inference/references/inference-options.md

@@ -30,7 +30,8 @@ NemoClaw uses provider-specific local tokens for those routes, and rebuilds of l
 | Hermes Provider | Hermes only | OpenAI-compatible route | Available when onboarding Hermes Agent through `nemohermes` |
 | Local Ollama | Caveated | Local Ollama API | Available when Ollama is installed or running on the host |
 | Local NVIDIA NIM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a NIM-capable GPU |
-| Local vLLM | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` and a server already running on `localhost:8000` |
+| Local vLLM (already running) | Caveated | Local OpenAI-compatible | Appears in the onboarding menu when NemoClaw detects a server already on `localhost:8000`. No flag required. |
+| Local vLLM (managed install/start) | Experimental | Local OpenAI-compatible | Requires `NEMOCLAW_EXPERIMENTAL=1` or `NEMOCLAW_PROVIDER=install-vllm`. NemoClaw pulls/starts a vLLM container on a supported NVIDIA GPU host. |
 
 ## Provider Options
 
@@ -80,6 +81,28 @@ To use the router in scripted setup, set:
 $ NEMOCLAW_PROVIDER=routed NVIDIA_API_KEY=<your-key> nemoclaw onboard --non-interactive
 ```
 
+### Host Python requirement
+
+The Model Router runs in a host-side virtual environment that NemoClaw creates during onboarding.
+NemoClaw probes `python3.13`, `python3.12`, `python3.11`, `python3.10`, and bare `python3`, and adopts the first interpreter that satisfies both of:
+
+- Version inside `[3.10, 3.14)`.
+- `ensurepip`, `pyexpat`, `ssl`, and `venv` all import without error.
+
+If no candidate qualifies, onboarding aborts and prints the real failure for each candidate.
+This surfaces issues like Homebrew `python@3.14` whose `pyexpat` extension fails to dlopen against the older system `libexpat` on macOS.
+
+To pin a specific interpreter, set `NEMOCLAW_MODEL_ROUTER_PYTHON` to its absolute path before running `nemoclaw onboard`:
+
+```console
+$ NEMOCLAW_MODEL_ROUTER_PYTHON=/opt/homebrew/bin/python3.12 nemoclaw onboard
+```
+
+The pin is strict.
+NemoClaw probes only that interpreter and aborts with the failure reason if it does not qualify, rather than silently falling back to a different python on `PATH`.
+Relative command names such as `python3.12` are rejected; use `command -v python3.12` to find the absolute path.
+If `python -m venv` itself fails for a probe-clean interpreter (for example, a corrupt ensurepip seed), NemoClaw retries with the next healthy candidate when no pin is set; with a pin set, the failure stops onboarding so you can fix or repoint the pinned python.
+
 ## Experimental Options
 
 The following local inference options are experimental.

.agents/skills/nemoclaw-user-configure-inference/references/set-up-sub-agent.md

@@ -1,6 +1,6 @@
 <!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
-# Set up a Task-Specific Sub-Agent
+# Set Up Task-Specific Sub-Agents
 
 OpenClaw documents the sub-agent behavior, `sessions_spawn` tool, `agents.list` configuration, tool policy, nesting, and auth model in [Sub-Agents](https://docs.openclaw.ai/tools/subagents).
 Use that page as the source of truth for how OpenClaw sub-agents work.

.agents/skills/nemoclaw-user-configure-inference/references/switch-inference-providers.md

@@ -1,6 +1,6 @@
 <!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
-# Switch NemoClaw Inference Models at Runtime
+# Switch Inference Models at Runtime
 
 Change the active inference model while the sandbox is running.
 No restart is required.

.agents/skills/nemoclaw-user-configure-security/references/best-practices.md

@@ -438,13 +438,13 @@ Different inference providers have different trust and cost profiles.
 
 ### Experimental Providers
 
-The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and local vLLM.
+The `NEMOCLAW_EXPERIMENTAL=1` environment variable gates local NVIDIA NIM and the managed vLLM install/start path. An already-running vLLM server on `localhost:8000` is offered in the menu without a flag, because selecting it is an explicit user action.
 
 | Aspect | Detail |
 |---|---|
-| Default | Disabled. The onboarding wizard does not show these providers. |
-| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before running `nemoclaw onboard`. |
-| Risk if relaxed | NemoClaw has not fully validated these providers. NIM requires a NIM-capable GPU. vLLM must already be running on `localhost:8000`. Misconfiguration can cause failed inference or unexpected behavior. |
+| Default | Local NVIDIA NIM and managed vLLM install/start are hidden. Already-running vLLM on `localhost:8000` is offered when detected. |
+| What you can change | Set `NEMOCLAW_EXPERIMENTAL=1` before running `nemoclaw onboard` to surface Local NIM and managed vLLM. To request only the managed vLLM path non-interactively, set `NEMOCLAW_PROVIDER=install-vllm`. |
+| Risk if relaxed | NemoClaw has not fully validated these providers. NIM requires a NIM-capable GPU. The managed vLLM path pulls a container image and starts it on a supported NVIDIA GPU host. Misconfiguration can cause failed inference or unexpected behavior. |
 | Recommendation | Use experimental providers only for evaluation. Do not rely on them for always-on assistants. |
 
 ## Posture Profiles

.agents/skills/nemoclaw-user-configure-security/references/credential-storage.md

@@ -1,6 +1,6 @@
 <!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
-# NemoClaw Credential Storage
+# Credential Storage
 
 NemoClaw does not persist provider credentials to host disk.
 The OpenShell gateway is the only system of record for stored credentials.

.agents/skills/nemoclaw-user-deploy-remote/SKILL.md

@@ -6,7 +6,7 @@ description: "Explains how to run NemoClaw on a remote GPU instance, including t
 <!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -->
 <!-- SPDX-License-Identifier: Apache-2.0 -->
 
-# Deploy NemoClaw to a Remote GPU Instance with Brev
+# Deploy NemoClaw to a Remote GPU Instance
 
 ## Gotchas
 
@@ -23,7 +23,7 @@ description: "Explains how to run NemoClaw on a remote GPU instance, including t
 Run NemoClaw on a remote GPU instance through [Brev](https://brev.nvidia.com).
 The preferred path is to provision the VM, run the standard NemoClaw installer on that host, and then run `nemoclaw onboard`.
 
-## Step 1: Quick Start
+## Quick Start
 
 If your Brev instance is already up and has already been onboarded with a sandbox, start with the standard sandbox chat flow:
 
@@ -37,7 +37,7 @@ If the VM is fresh, run the standard installer on that host and then run `nemocl
 
 If you are connecting from your local machine and still need to provision the remote VM, you can still use `nemoclaw deploy <instance-name>` as the legacy compatibility path described below.
 
-## Step 2: Deploy the Instance
+## Deploy the Instance
 
 **Warning:**
 
@@ -65,7 +65,7 @@ The legacy compatibility flow performs the following steps on the VM:
 By default, the compatibility wrapper asks Brev to provision on `gcp`. Override this with `NEMOCLAW_BREV_PROVIDER` if you need a different Brev cloud provider.
 If you export `HF_TOKEN` or `HUGGING_FACE_HUB_TOKEN`, the wrapper forwards those values to the VM so remote setup can pull gated Hugging Face model repositories.
 
-## Step 3: Connect to the Remote Sandbox
+## Connect to the Remote Sandbox
 
 After deployment finishes, the deploy command opens an interactive shell inside the remote sandbox.
 To reconnect after closing the session, run the command again:
@@ -74,23 +74,23 @@ To reconnect after closing the session, run the command again:
 $ nemoclaw deploy <instance-name>
 ```
 
-## Step 4: Monitor the Remote Sandbox
+## Monitor the Remote Sandbox
 
 SSH to the instance and run the OpenShell TUI to monitor activity and approve network requests:
 
 ```console
 $ ssh <instance-name> 'cd ~/nemoclaw && set -a && . .env && set +a && openshell term'
 ```
 
-## Step 5: Verify Inference
+## Verify Inference
 
 Run a test agent prompt inside the remote sandbox:
 
 ```console
 $ openclaw agent --agent main --local -m "Hello from the remote sandbox" --session-id test
 ```
 
-## Step 6: Remote Dashboard Access
+## Remote Dashboard Access
 
 The NemoClaw dashboard validates the browser origin against an allowlist baked
 into the sandbox image at build time.  By default the allowlist only contains
@@ -116,7 +116,7 @@ set on a headless host, the compatibility wrapper prints a warning.
 When `CHAT_UI_URL` points at a non-loopback origin, NemoClaw disables OpenClaw device pairing in the generated sandbox configuration because browser-only remote users cannot complete terminal-based pairing.
 Any device that can reach the configured dashboard origin can connect without pairing, so avoid exposing that origin on internet-reachable or shared-network deployments.
 
-## Step 7: First-Run Readiness Budget
+## First-Run Readiness Budget
 
 On a remote GPU host, the first `nemoclaw onboard` typically does the slowest work of the lifecycle: the sandbox image is built locally and uploaded into the OpenShell gateway, which can stream hundreds of MiB over the VM's link before the readiness wait even starts.
 The post-create readiness wait defaults to 180 seconds (`NEMOCLAW_SANDBOX_READY_TIMEOUT`), which is sized for warm-cache, workstation-class onboarding and can be exceeded on:
@@ -135,7 +135,7 @@ $ nemoclaw onboard
 If onboard ends with `Sandbox '<name>' was created but did not become ready within 180s`, onboard deletes the partially-created sandbox first, so the next attempt with the raised budget starts from a clean state.
 For the inference-probe budget that runs earlier in onboarding, see `NEMOCLAW_LOCAL_INFERENCE_TIMEOUT` (use the `nemoclaw-user-configure-inference` skill).
 
-## Step 8: Proxy Configuration
+## Proxy Configuration
 
 NemoClaw routes sandbox traffic through a gateway proxy that defaults to `10.200.0.1:3128`.
 If your network requires a different proxy, set `NEMOCLAW_PROXY_HOST` and `NEMOCLAW_PROXY_PORT` before onboarding:
@@ -152,7 +152,7 @@ Only alphanumeric characters, dots, hyphens, and colons are accepted for the hos
 The port must be numeric (0-65535).
 Changing the proxy after onboarding requires re-running `nemoclaw onboard`.
 
-## Step 9: GPU Configuration
+## GPU Configuration
 
 The deploy script uses the `NEMOCLAW_GPU` environment variable to select the GPU type.
 The default value is `a2-highgpu-1g:nvidia-tesla-a100:1`.