docs: add per-agent documentation variants

.github/workflows/docs-links-pr.yaml

@@ -9,7 +9,6 @@ on:
     types: [opened, reopened, synchronize]
     paths:
       - "**/*.md"
-      - "**/*.mdx"
       - ".github/workflows/docs-links-pr.yaml"
       - "test/e2e/e2e-cloud-experimental/check-docs.sh"
 
@@ -34,9 +33,10 @@ jobs:
           base="${{ github.event.pull_request.base.sha }}"
           head="${{ github.event.pull_request.head.sha }}"
           mapfile -t doc_files < <(
+            # Fern preview validates MDX routes after building variant navigation.
+            # This raw Markdown checker only verifies repository-local .md links.
             git diff --name-only --diff-filter=ACMR "$base" "$head" -- \
               '*.md' \
-              '*.mdx' \
               ':(exclude)node_modules/**' \
               ':(exclude)dist/**' \
               ':(exclude)vendor/**' \

docs/_components/AgentGuide.tsx

@@ -0,0 +1,124 @@
+/*
+ * SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Resolves OpenClaw vs Hermes user-guide variant from injected route data.
+ * Prefer passing `variant` or `pathname` from the page or route that renders the
+ * component so SSR output does not depend on browser-only globals. The window
+ * fallback preserves the current client-side behavior for unwrapped pages.
+ */
+declare const React: unknown;
+
+export type GuideVariant = "openclaw" | "hermes";
+export type GuideVariantSource =
+  | GuideVariant
+  | string
+  | {
+      variant?: GuideVariant | null;
+      activeVariant?: GuideVariant | null;
+      pathname?: string | null;
+    }
+  | null
+  | undefined;
+
+type GuideContextProps = {
+  variant?: GuideVariant | null;
+  activeVariant?: GuideVariant | null;
+  pathname?: string | null;
+};
+
+const GUIDE_PATH = "/user-guide/";
+const HERMES_PATH = `${GUIDE_PATH}hermes`;
+const OPENCLAW_PATH = `${GUIDE_PATH}openclaw`;
+
+export function getGuideVariant(source?: GuideVariantSource): GuideVariant {
+  return resolveGuideVariant(source) ?? resolveGuideVariant(readWindowPathname()) ?? "openclaw";
+}
+
+export function guideBasePath(source?: GuideVariantSource): string {
+  const pathname = resolveGuidePathname(source) ?? readWindowPathname();
+  if (!pathname) return "";
+  const guideIndex = pathname.indexOf(GUIDE_PATH);
+  return guideIndex === -1 ? "" : pathname.slice(0, guideIndex);
+}
+
+/** Full site path for the active guide variant (includes /user-guide/{variant}). */
+export function guidePath(suffix: string, source?: GuideVariantSource): string {
+  const normalized = suffix.startsWith("/") ? suffix : `/${suffix}`;
+  return `${guideBasePath(source)}${GUIDE_PATH}${getGuideVariant(source)}${normalized}`;
+}
+
+export function AgentCli(props: GuideContextProps = {}) {
+  return <code>{getGuideVariant(props) === "hermes" ? "nemohermes" : "nemoclaw"}</code>;
+}
+
+export function AgentProductName(props: GuideContextProps = {}) {
+  return <>{getGuideVariant(props) === "hermes" ? "NemoHermes" : "NemoClaw"}</>;
+}
+
+export function AgentOnly({
+  variant,
+  activeVariant,
+  pathname,
+  children,
+}: {
+  variant: GuideVariant;
+  activeVariant?: GuideVariant | null;
+  pathname?: string | null;
+  children: unknown;
+}) {
+  if (getGuideVariant({ activeVariant, pathname }) !== variant) {
+    return null;
+  }
+  return <>{children}</>;
+}
+
+export function GuideLink({
+  href,
+  variant,
+  activeVariant,
+  pathname,
+  children,
+}: {
+  href: string;
+  variant?: GuideVariant | null;
+  activeVariant?: GuideVariant | null;
+  pathname?: string | null;
+  children: unknown;
+}) {
+  const resolved =
+    href.startsWith("http://") || href.startsWith("https://")
+      ? href
+      : guidePath(href, { variant, activeVariant, pathname });
+  return <a href={resolved}>{children}</a>;
+}
+
+function resolveGuideVariant(source?: GuideVariantSource): GuideVariant | null {
+  if (!source) return null;
+  if (source === "openclaw" || source === "hermes") return source;
+  if (typeof source === "string") return resolveGuideVariantFromPathname(source);
+  return (
+    source.activeVariant ??
+    source.variant ??
+    resolveGuideVariantFromPathname(source.pathname ?? null)
+  );
+}
+
+function resolveGuidePathname(source?: GuideVariantSource): string | null {
+  if (!source || source === "openclaw" || source === "hermes") return null;
+  if (typeof source === "string") return source;
+  return source.pathname ?? null;
+}
+
+function resolveGuideVariantFromPathname(pathname: string | null): GuideVariant | null {
+  if (!pathname) return null;
+  if (pathname.includes(HERMES_PATH)) return "hermes";
+  if (pathname.includes(OPENCLAW_PATH)) return "openclaw";
+  return null;
+}
+
+function readWindowPathname(): string | null {
+  return typeof window === "undefined" ? null : window.location.pathname;
+}

docs/about/ecosystem-hermes.mdx

@@ -0,0 +1,102 @@
+---
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+title: "Ecosystem"
+sidebar-title: "Ecosystem"
+description: "How Hermes, OpenShell, and NemoClaw form one stack, where NemoClaw sits, what it adds beyond a DIY OpenShell deployment, and when to use the reference integration versus OpenShell alone."
+description-agent: "Explains how Hermes, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond integrating OpenShell yourself, and when to prefer NemoHermes versus OpenShell. Use when users ask about Hermes, OpenShell, and NemoClaw together, or when to use NemoClaw versus OpenShell for Hermes."
+keywords: ["nemoclaw ecosystem", "hermes agent", "nemohermes", "nemoclaw vs openshell", "run hermes openshell sandbox"]
+content:
+  type: "concept"
+---
+NemoClaw provides onboarding, lifecycle management, and Hermes operations within OpenShell containers.
+Use the `nemohermes` CLI alias when you work from the Hermes agent guide; it is equivalent to `nemoclaw` with the Hermes agent pre-selected.
+
+This page describes how the ecosystem is formed across projects, where NemoClaw sits relative to [OpenShell](https://github.com/NVIDIA/OpenShell) and [Hermes](https://hermes-agent.nousresearch.com/docs/), and how to choose between NemoHermes and OpenShell alone.
+
+## How the Stack Fits Together
+
+There are three pieces in a NemoClaw for Hermes deployment: Hermes, OpenShell, and NemoClaw, each with a distinct scope.
+The following diagram shows how they fit together.
+
+```mermaid
+flowchart TB
+    NC["🦞 NVIDIA NemoClaw<br/>CLI, blueprint"]
+    OS["🐚 NVIDIA OpenShell<br/>Gateway, policy, inference routing"]
+    HM["Hermes<br/>Agent in sandbox"]
+
+    NC -->|orchestrates| OS
+    OS -->|isolates and runs| HM
+
+    classDef nv fill:#76b900,stroke:#333,color:#fff
+    classDef nvLight fill:#e6f2cc,stroke:#76b900,color:#1a1a1a
+    classDef nvDark fill:#333,stroke:#76b900,color:#fff
+
+    class NC nv
+    class OS nv
+    class HM nvDark
+
+    linkStyle 0 stroke:#76b900,stroke-width:2px
+    linkStyle 1 stroke:#76b900,stroke-width:2px
+```
+
+NemoClaw sits above OpenShell in the operator workflow.
+It drives OpenShell APIs and CLI to create and configure the sandbox that runs Hermes.
+Models and endpoints sit behind OpenShell's inference routing.
+NemoClaw onboarding wires provider choice into that routing, including the Hermes Provider route when you onboard through `nemohermes`.
+
+The following table shows the scope of each component in the stack.
+
+| Project | Scope |
+|---------|--------|
+| [Hermes](https://hermes-agent.nousresearch.com/docs/) | The agent: runtime, tools, messaging adapters, and an OpenAI-compatible API inside the container. It does not define the sandbox or the host gateway. |
+| [OpenShell](https://github.com/NVIDIA/OpenShell) | The execution environment: sandbox lifecycle, network, filesystem, and process policy, inference routing, and the operator-facing `openshell` CLI for those primitives. |
+| NemoClaw | The NVIDIA reference stack on the host: `nemohermes` / `nemoclaw` CLI, versioned blueprint, channel messaging configured for OpenShell-managed delivery, and state migration helpers so Hermes runs inside OpenShell in a documented, repeatable way. |
+
+## NemoClaw Path versus OpenShell Path
+
+Both paths assume OpenShell can sandbox a workload.
+The difference is who owns the integration work.
+
+| Path | What it means |
+|------|---------------|
+| **NemoClaw path** | You adopt the reference stack. NemoClaw's Hermes blueprint encodes a hardened image, default policies, and orchestration so `nemohermes onboard` can stand up a known-good Hermes-on-OpenShell setup with less custom glue. |
+| **OpenShell path** | You use OpenShell as the platform and supply your own container, Hermes install steps, policy YAML, provider setup, and any host bridges. OpenShell stays the sandbox and policy engine; nothing requires NemoClaw's blueprint or CLI. |
+
+## What NemoClaw Adds Beyond DIY OpenShell
+
+You can run Hermes inside OpenShell without NemoClaw by building your own image, writing policy YAML, registering providers, and wiring inference routes yourself.
+That path is valid when you need full control over the container layout.
+
+NemoClaw builds on OpenShell with additional security hardening, automation, and lifecycle tooling for Hermes.
+The following table compares DIY OpenShell integration with `nemohermes onboard`.
+
+| Capability | DIY OpenShell + Hermes | `nemohermes onboard` |
+|---|---|---|
+| Sandbox isolation | Yes, when you apply OpenShell seccomp, Landlock, network namespace isolation, and no-new-privileges enforcement through your policy. | Yes. NemoClaw applies these through the blueprint and layers a Hermes-specific restrictive policy on top. |
+| Credential handling | You create OpenShell providers manually with `openshell provider create` and configure placeholder resolution at egress. | NemoClaw creates OpenShell providers during onboarding and filters sensitive host environment variables from the sandbox creation command to reduce accidental leakage through build args. |
+| Image hardening | Depends on your base image and install steps. | NemoClaw strips build toolchains (`gcc`, `g++`, `make`) and network probes (`netcat`) from the runtime image to reduce attack surface. |
+| Filesystem policy | You define read-only and read-write paths in policy YAML. | NemoClaw defines a targeted layout: system paths (`/usr`, `/lib`, `/etc`) are read-only; `/sandbox` and `/sandbox/.hermes` are writable for agent state and configuration. |
+| Inference setup | You configure OpenShell inference routing and Hermes `config.yaml` manually. | NemoClaw validates credentials from the host, configures the OpenShell route, and bakes model settings into `/sandbox/.hermes/config.yaml`. Hermes Provider onboarding is available through `nemohermes`. |
+| Channel messaging | OpenShell delivers channel tokens through its provider system and L7 proxy; you configure Hermes platform adapters manually. | NemoClaw automates supported channel setup during onboarding and bakes Hermes env/config with placeholder tokens that OpenShell resolves at egress. |
+| Blueprint versioning | No NemoClaw blueprint; your image tag is whatever you built locally. | NemoClaw downloads the blueprint artifact, checks version compatibility, and verifies its digest before applying. Running `nemohermes onboard` on different machines produces the same sandbox. |
+| State migration | Not included unless you build it. | NemoClaw migrates agent state across machines with credential stripping and integrity verification. |
+| Process count limits | You set process count limits manually with `--ulimit` or orchestrator config. | NemoClaw applies `ulimit -u 512` in the container entrypoint on top of OpenShell's seccomp and privilege dropping. |
+
+## When to Use Which
+
+Use the following table to decide when to use NemoHermes versus OpenShell alone.
+
+| Situation | Prefer |
+|-----------|--------|
+| You want Hermes with minimal assembly, NVIDIA defaults, and the documented install and onboard flow. | NemoClaw (`nemohermes`) |
+| You need maximum flexibility for custom images, a layout that does not match the NemoClaw Hermes blueprint, or a workload outside this reference stack. | OpenShell with your own integration |
+| You are standardizing on the NVIDIA reference for always-on Hermes agents with policy and inference routing. | NemoClaw (`nemohermes`) |
+| You are building internal platform abstractions where the NemoClaw CLI or blueprint is not the right fit. | OpenShell (and your orchestration) |
+
+## Related topics
+
+- [Overview](overview) contains what NemoClaw is, capabilities, benefits, and use cases.
+- [How It Works](how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Hermes.
+- [Architecture](../reference/architecture) shows the repository structure and technical diagrams.
+- [Quickstart with Hermes](../get-started/quickstart-hermes) installs NemoClaw and launches your first Hermes sandbox.

docs/about/ecosystem.mdx

@@ -15,7 +15,7 @@ This page describes how the ecosystem is formed across projects, where NemoClaw
 
 ## How the Stack Fits Together
 
-There are three pieces that are put together in a NemoClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope.
+There are three pieces that are put together in a NemoClaw for OpenClaw deployment: OpenClaw, OpenShell, and NemoClaw, each with a distinct scope.
 The following diagram shows how they fit together.
 
 ```mermaid
@@ -96,6 +96,6 @@ Use the following table to decide when to use NemoClaw versus OpenShell.
 
 ## Related topics
 
-- [Overview](/about/overview) contains what NemoClaw is, capabilities, benefits, and use cases.
-- [How It Works](/about/how-it-works) describes how NemoClaw runs, plugin, blueprint, sandbox creation, routing, protection layers.
-- [Architecture](/reference/architecture) shows the repository structure and technical diagrams.
+- [Overview](overview) contains what NemoClaw is, capabilities, benefits, and use cases.
+- [How It Works](how-it-works) describes how NemoClaw runs, plugin, blueprint, sandbox creation, routing, protection layers.
+- [Architecture](../reference/architecture) shows the repository structure and technical diagrams.