From 02b7d00863e4bc34d61dda88e57ec6144a814b0f Mon Sep 17 00:00:00 2001
From: harjoth <harjoth.khara@gmail.com>
Date: Sat, 13 Jun 2026 10:33:31 -0700
Subject: [PATCH] docs: fix broken internal links to Windows Prerequisites and
 Hermes Quickstart

Fern resolves relative markdown links by source-file path, so several links resolved to missing or wrong pages:

- Windows Prerequisites links used the nav slug path
  (../get-started/prerequisites/windows-preparation); the source file is
  docs/get-started/windows-preparation.mdx.
- Hermes Quickstart links used an out-of-tree path
  (../../hermes/get-started/quickstart) or pointed at the OpenClaw quickstart
  in a "Quickstart with Hermes" context; the source file is
  docs/get-started/quickstart-hermes.mdx.

Point each link at its real source file (matching the file-path convention
from #5099) and add a regression test covering the corrected targets.

Fixes #5076

Signed-off-by: harjoth <harjoth.khara@gmail.com>
---
 docs/about/overview.mdx            |  2 +-
 docs/get-started/prerequisites.mdx |  2 +-
 docs/reference/troubleshooting.mdx | 10 ++---
 test/repro-5076-docs-links.test.ts | 62 ++++++++++++++++++++++++++++++
 4 files changed, 69 insertions(+), 7 deletions(-)
 create mode 100644 test/repro-5076-docs-links.test.ts

diff --git a/docs/about/overview.mdx b/docs/about/overview.mdx
index 689849cde16..6f3470ba29b 100644
--- a/docs/about/overview.mdx
+++ b/docs/about/overview.mdx
@@ -84,7 +84,7 @@ Navigate to the following topics to learn more about NemoClaw and how to install
 
 - [Architecture Overview](how-it-works) to understand how NemoClaw works.
 - [Ecosystem](ecosystem) to understand how Hermes, OpenShell, and NemoClaw relate in the wider stack, and when to use NemoClaw versus OpenShell.
-- [Quickstart with Hermes](../get-started/quickstart) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`.
+- [Quickstart with Hermes](../get-started/quickstart-hermes) to install NemoClaw and run your first Hermes sandbox with `$$nemoclaw`.
 - [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant.
 - [NemoClaw Community](https://github.com/NVIDIA/nemoclaw-community) to explore community-driven blueprint examples, showcases, and integrations.
 - [Inference Options](../inference/inference-options) to check the inference providers that NemoClaw supports and how inference routing works.
diff --git a/docs/get-started/prerequisites.mdx b/docs/get-started/prerequisites.mdx
index d5fd11b62c0..046510e1938 100644
--- a/docs/get-started/prerequisites.mdx
+++ b/docs/get-started/prerequisites.mdx
@@ -84,6 +84,6 @@ The table comes from [`ci/platform-matrix.json`](https://github.com/NVIDIA/NemoC
 
 ## Next Steps
 
-- [Prepare Windows for NemoClaw](prerequisites/windows-preparation) if you are using Windows.
+- [Prepare Windows for NemoClaw](windows-preparation) if you are using Windows.
 - [Quickstart](quickstart) to install NemoClaw and launch your first sandboxed agent.
 - [Agent Skills](../resources/agent-skills) to load NemoClaw guidance into an AI coding assistant before setup.
diff --git a/docs/reference/troubleshooting.mdx b/docs/reference/troubleshooting.mdx
index 6c5f9004536..4f378b71513 100644
--- a/docs/reference/troubleshooting.mdx
+++ b/docs/reference/troubleshooting.mdx
@@ -1424,7 +1424,7 @@ If you run other services on Spark that expect port 3000, bind them to a differe
 <a id="windows-wsl-2"></a>
 ## Windows Subsystem for Linux
 
-For environment setup steps, see [Windows Prerequisites](../get-started/prerequisites/windows-preparation).
+For environment setup steps, see [Windows Prerequisites](../get-started/windows-preparation).
 
 ### `wsl --install --no-distribution` returns Forbidden (403)
 
@@ -1500,12 +1500,12 @@ sudo systemctl stop ollama
 OLLAMA_CONTEXT_LENGTH=16384 ollama serve
 ```
 
-For additional troubleshooting, see the [Windows Setup](../get-started/prerequisites/windows-preparation) page.
+For additional troubleshooting, see the [Windows Setup](../get-started/windows-preparation) page.
 <AgentOnly variant="openclaw">
 For first-time OpenClaw setup, see the [Quickstart](../get-started/quickstart).
 </AgentOnly>
 <AgentOnly variant="hermes">
-For first-time Hermes setup, see [Quickstart with Hermes](../get-started/quickstart).
+For first-time Hermes setup, see [Quickstart with Hermes](../get-started/quickstart-hermes).
 </AgentOnly>
 
 ## Podman
@@ -1602,7 +1602,7 @@ After the rebuild completes, return to the Skills page to confirm the skill is r
 ## Hermes
 
 The issues below are common problems you may encounter when running Hermes through `nemohermes`.
-For setup, refer to [Quickstart with Hermes](../../hermes/get-started/quickstart).
+For setup, refer to [Quickstart with Hermes](../get-started/quickstart-hermes).
 
 ### Port 8642 in a browser shows a blank page or `Cannot GET /`
 
@@ -1704,7 +1704,7 @@ Reset a specific provider's credentials with `nemohermes credentials reset <prov
 
 ### `Brave Search` policy preset has no effect under Hermes
 
-The Hermes wizard intentionally omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration (see [Quickstart with Hermes](../../hermes/get-started/quickstart) and [Network Policies](network-policies)).
+The Hermes wizard intentionally omits the Brave Search preset because Hermes does not use NemoClaw's OpenClaw web-search configuration (see [Quickstart with Hermes](../get-started/quickstart-hermes) and [Network Policies](network-policies)).
 If you add the `brave` preset to a Hermes sandbox after onboarding, the L7 egress allowlist opens for Brave's endpoints but the agent itself does not start consuming the credential.
 Configure Hermes web search from the agent's own configuration inside the sandbox.
 
diff --git a/test/repro-5076-docs-links.test.ts b/test/repro-5076-docs-links.test.ts
new file mode 100644
index 00000000000..0a7709ba6ac
--- /dev/null
+++ b/test/repro-5076-docs-links.test.ts
@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { describe, it, expect } from "vitest";
+import fs from "node:fs";
+import path from "node:path";
+
+// Regression for issue #5076: several docs pages linked to internal pages
+// through paths that do not exist as Fern source files. Fern resolves relative
+// `[](…)` links by SOURCE-FILE path (see merged #5099/#5088, which fixed the
+// same class for Sandbox Hardening), so these links 404 in the rendered site:
+//
+//   - Windows Prerequisites lives at docs/get-started/windows-preparation.mdx,
+//     not docs/get-started/prerequisites/windows-preparation.mdx — the
+//     `prerequisites/` segment is the nav slug, not a directory.
+//   - The Hermes Quickstart lives at docs/get-started/quickstart-hermes.mdx;
+//     `../../hermes/get-started/quickstart` escapes the docs/ tree entirely,
+//     and the OpenClaw `../get-started/quickstart` is the wrong target for a
+//     "Quickstart with Hermes" link.
+const REPO_ROOT = path.dirname(import.meta.dirname);
+const read = (...rel: string[]) =>
+  fs.readFileSync(path.join(REPO_ROOT, "docs", ...rel), "utf-8");
+
+describe("docs internal-link targets resolve to real source files (#5076)", () => {
+  it("troubleshooting.mdx links Windows Prerequisites by its real file path", () => {
+    const text = read("reference", "troubleshooting.mdx");
+    expect(text).not.toMatch(/get-started\/prerequisites\/windows-preparation/);
+    expect(text).toMatch(/\]\(\.\.\/get-started\/windows-preparation\)/);
+  });
+
+  it("troubleshooting.mdx links the Hermes Quickstart by its real file path", () => {
+    const text = read("reference", "troubleshooting.mdx");
+    // Neither the out-of-tree path nor the OpenClaw quickstart (wrong target).
+    expect(text).not.toMatch(/\.\.\/\.\.\/hermes\/get-started\/quickstart/);
+    expect(text).not.toMatch(
+      /\[Quickstart with Hermes\]\(\.\.\/get-started\/quickstart\)/,
+    );
+    expect(text).toMatch(/\]\(\.\.\/get-started\/quickstart-hermes\)/);
+    // The OpenClaw quickstart link is correct and must stay put.
+    expect(text).toMatch(/\[Quickstart\]\(\.\.\/get-started\/quickstart\)/);
+  });
+
+  it("prerequisites.mdx links Windows Prerequisites by its real file path", () => {
+    const text = read("get-started", "prerequisites.mdx");
+    expect(text).not.toMatch(/\]\(prerequisites\/windows-preparation\)/);
+    expect(text).toMatch(/\]\(windows-preparation\)/);
+  });
+
+  it("overview.mdx points the Hermes Quickstart link at the Hermes page", () => {
+    const text = read("about", "overview.mdx");
+    expect(text).toMatch(
+      /\[Quickstart with Hermes\]\(\.\.\/get-started\/quickstart-hermes\)/,
+    );
+    expect(text).not.toMatch(
+      /\[Quickstart with Hermes\]\(\.\.\/get-started\/quickstart\)/,
+    );
+    // The OpenClaw quickstart link is correct and must stay put.
+    expect(text).toMatch(
+      /\[Quickstart with OpenClaw\]\(\.\.\/get-started\/quickstart\)/,
+    );
+  });
+});