docs(inference): split guides into nested topics

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

@@ -107,10 +107,10 @@ For each relevant commit, determine which doc page(s) it affects. Use this mappi
 | `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` |
+| `nemoclaw-blueprint/blueprint.yaml` | `docs/reference/architecture.mdx`, `docs/inference/how-inference-routing-works.mdx` |
 | `scripts/` (setup, start) | `docs/get-started/quickstart.mdx` |
 | `Dockerfile` | `docs/reference/architecture.mdx` |
-| Inference-related changes | `docs/inference/inference-options.mdx` |
+| Inference-related changes | Start at `docs/inference/how-inference-routing-works.mdx`, then update the focused provider, model, setup, management, or validation page that owns the behavior. |
 
 If a commit does not map to any existing page but introduces a user-visible concept, flag it as needing a new page.
 If a commit already changes files under `docs/`, include those pages in the target page list and run a docs review or edit pass against them using the style guidance in Step 5.

.coderabbit.yaml

@@ -24,6 +24,30 @@ reviews:
   # them from each PR diff and the current workflows instead of a duplicated,
   # manually synchronized path-to-job catalog.
   path_instructions:
+    - path: "docs/**"
+      instructions: &fern-doc-links |
+        Review internal documentation links as Fern published routes, not as
+        source-file-relative paths.
+
+        - Resolve a link with the enclosing section slugs and page slug declared
+          in `docs/index.yml`. A valid route can differ from the target MDX file's
+          directory, and shared pages can be published from generated
+          `_build/agent-variants/*.generated.mdx` navigation entries.
+        - Account for the OpenClaw, Hermes, and Deep Agents navigation variants and
+          `<AgentOnly>` filtering. A route only needs to exist for every variant in
+          which the link is rendered.
+        - Treat extensionless route-style links as intentional. Do not suggest an
+          `.mdx` path or a source-directory-relative replacement merely because no
+          matching source file exists at that relative path.
+        - Before reporting a broken internal route or redirect, resolve it the same
+          way as `scripts/check-docs-published-routes.ts` and check the redirects in
+          `fern/docs.yml`. Flag a missing published route, missing generated-page
+          source, invalid relevant-variant route, or invalid anchor, but do not
+          report a route as broken solely because its filesystem path is absent.
+
+    - path: "fern/docs.yml"
+      instructions: *fern-doc-links
+
     - path: "src/**"
       instructions: |
         Apply a migration-completion review whenever a PR introduces a

.pre-commit-config.yaml

@@ -89,9 +89,9 @@ repos:
     hooks:
       - id: platform-matrix-sync
         name: Sync platform matrix to docs
-        entry: bash -c 'python3 scripts/generate-platform-docs.py && git add docs/get-started/prerequisites.mdx docs/inference/inference-options.mdx docs/reference/platform-support.mdx'
+        entry: bash -c 'python3 scripts/generate-platform-docs.py && git add docs/get-started/prerequisites.mdx docs/inference/choose-inference-provider.mdx docs/reference/platform-support.mdx'
         language: system
-        files: ^(ci/platform-matrix\.json|docs/get-started/prerequisites\.mdx|docs/inference/inference-options\.mdx|docs/reference/platform-support\.mdx|scripts/generate-platform-docs\.py)$
+        files: ^(ci/platform-matrix\.json|docs/get-started/prerequisites\.mdx|docs/inference/choose-inference-provider\.mdx|docs/reference/platform-support\.mdx|scripts/generate-platform-docs\.py)$
         pass_filenames: false
         priority: 3
 

README.md

@@ -53,7 +53,7 @@ Refer to the following pages on the official documentation website for more info
 | [Ecosystem](https://docs.nvidia.com/nemoclaw/latest/about/ecosystem.html) | How OpenClaw, OpenShell, and NemoClaw form a stack and when to use NemoClaw versus OpenShell alone. |
 | [Architecture Details](https://docs.nvidia.com/nemoclaw/latest/reference/architecture.html) | Detailed description of Plugin structure, blueprint lifecycle, sandbox environment, and host-side state. |
 | [Prerequisites](https://docs.nvidia.com/nemoclaw/latest/get-started/prerequisites.html) | Hardware, software, and supported platforms, with any platform-specific pre-setup. |
-| [Inference Options](https://docs.nvidia.com/nemoclaw/latest/inference/inference-options.html) | Supported providers, validation, and routed inference configuration. |
+| [Choose an Inference Provider](https://docs.nvidia.com/nemoclaw/latest/user-guide/openclaw/inference/learn-and-choose/choose-inference-provider) | Supported providers, validation, and routed inference configuration. |
 | [Network Policies](https://docs.nvidia.com/nemoclaw/latest/reference/network-policies.html) | Baseline rules, operator approval flow, and egress control. |
 | [Customize Network Policy](https://docs.nvidia.com/nemoclaw/latest/network-policy/customize-network-policy.html) | Static and dynamic policy changes, presets. |
 | [Security Best Practices](https://docs.nvidia.com/nemoclaw/latest/security/best-practices.html) | Controls reference, risk framework, and posture profiles for sandbox security. |

docs/about/ecosystem-deepagents.mdx

@@ -98,6 +98,6 @@ Use the following table to choose NemoClaw or custom OpenShell integration.
 - [Architecture Overview](how-it-works) describes how NemoClaw runs, the blueprint, sandbox creation, routing, and protection layers for Deep Agents.
 - [Architecture Details](../reference/architecture) describes the Deep Agents blueprint, file layout, policy paths, and managed runtime internals.
 - [Quickstart with Deep Agents](../get-started/quickstart) installs NemoClaw and launches your first Deep Agents sandbox.
-- [Inference Options](../inference/inference-options) explains provider choices and the `inference.local` route.
+- [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) explains provider choices and the `inference.local` route.
 - [Deep Agents Code overview](https://docs.langchain.com/oss/python/deepagents/code/overview) explains upstream `dcode` capabilities and commands.
 - [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) collects community-driven blueprint examples, showcases, and integrations that demonstrate complete blueprint patterns.

docs/about/how-it-works.mdx

@@ -194,7 +194,7 @@ NemoClaw's runtime context tells supported agents to try allowed network and fil
 - Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths.
 - Follow [Quickstart with OpenClaw](../get-started/quickstart) to launch your first sandbox.
 - Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle.
-- Read [Inference Options](../inference/inference-options) for detailed provider configuration.
+- Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for detailed provider configuration.
 - For details on the baseline rules, refer to [Network Policies](../reference/network-policies).
 - For container-level hardening, refer to [Sandbox Hardening](../manage-sandboxes/sandbox-hardening).
 
@@ -204,7 +204,7 @@ NemoClaw's runtime context tells supported agents to try allowed network and fil
 - Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths.
 - Follow [Quickstart with Hermes](../get-started/quickstart) to launch your first sandbox.
 - Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle.
-- Read [Inference Options](../inference/inference-options) for detailed provider configuration.
+- Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for detailed provider configuration.
 - For details on the baseline rules, refer to [Network Policies](../reference/network-policies).
 
 </AgentOnly>
@@ -213,7 +213,7 @@ NemoClaw's runtime context tells supported agents to try allowed network and fil
 - Read [Ecosystem](ecosystem) for stack-level relationships and NemoClaw versus OpenShell-only paths.
 - Follow [Quickstart with Deep Agents](../get-started/quickstart) to launch your first sandbox.
 - Read [Architecture](../reference/architecture) for the full technical structure, including file layouts and the blueprint lifecycle.
-- Read [Inference Options](../inference/inference-options) for detailed provider configuration.
+- Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) for detailed provider configuration.
 - For details on the baseline rules, refer to [Network Policies](../reference/network-policies).
 
 </AgentOnly>

docs/about/overview.mdx

@@ -70,7 +70,7 @@ NemoClaw provides these benefits to mitigate those risks.
 | Benefit                    | Description                                                                                                            |
 |----------------------------|------------------------------------------------------------------------------------------------------------------------|
 | Sandboxed execution        | Every agent runs inside an OpenShell sandbox with Landlock, seccomp, and network namespace isolation. The sandbox grants no access by default. |
-| Routed inference           | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. Refer to [Inference Options](../inference/inference-options).          |
+| Routed inference           | The OpenShell gateway routes model traffic to your selected provider, transparent to the agent. You can switch providers or models. Refer to [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider).          |
 | Declarative network policy | YAML defines egress rules. OpenShell blocks unknown hosts and surfaces them to the operator for approval.                 |
 | Single CLI                 | The <AgentCli /> command orchestrates the full stack: gateway, sandbox, inference provider, and network policy.           |
 | Blueprint lifecycle        | Versioned blueprints handle sandbox creation, digest verification, and reproducible setup.                             |
@@ -97,7 +97,7 @@ Use these topics to learn more about NemoClaw and how to install and use it.
 - Follow [Quickstart with OpenClaw](../get-started/quickstart) to install NemoClaw and run your first OpenClaw sandbox.
 - Read [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs.
 - Explore [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) for community-driven blueprint examples, showcases, and integrations.
-- Read [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works.
+- Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) to check the inference providers that NemoClaw supports and how inference routing works.
 
 </AgentOnly>
 <AgentOnly variant="hermes">
@@ -107,7 +107,7 @@ Use these topics to learn more about NemoClaw and how to install and use it.
 - Follow [Quickstart with Hermes](../get-started/quickstart) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`.
 - Read [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs.
 - Explore [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) for community-driven blueprint examples, showcases, and integrations.
-- Read [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works.
+- Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) to check the inference providers that NemoClaw supports and how inference routing works.
 
 </AgentOnly>
 <AgentOnly variant="deepagents">
@@ -117,6 +117,6 @@ Use these topics to learn more about NemoClaw and how to install and use it.
 - Follow [Quickstart with Deep Agents](../get-started/quickstart) to install NemoClaw and run your first Deep Agents sandbox with `$$nemoclaw`.
 - Read [AI Agent Docs](../resources/agent-skills) to let your AI coding assistant fetch NemoClaw Markdown docs.
 - Explore [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) for community-driven blueprint examples, showcases, and integrations.
-- Read [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works.
+- Read [Choose an Inference Provider](../inference/learn-and-choose/choose-inference-provider) to check the inference providers that NemoClaw supports and how inference routing works.
 
 </AgentOnly>