docs(commands): route Install OpenClaw Plugins link to published section (#5445) by yimoj · Pull Request #6385 · NVIDIA/NemoClaw

yimoj · 2026-07-07T08:39:21Z

Summary

The OpenClaw commands reference page linked to the Install OpenClaw Plugins page using its source directory (../deployment/install-openclaw-plugins), but Fern publishes that page under the manage-sandboxes nav section. The link therefore 404s on the live site even though the source file exists on disk. This restores the published-route link and adds a route-level regression guard so the drift cannot recur.

Related Issue

Fixes #5445

Changes

docs/reference/commands.mdx: link Install OpenClaw Plugins via its published nav section (../manage-sandboxes/install-openclaw-plugins) instead of its source directory (../deployment/install-openclaw-plugins).
scripts/check-docs-published-routes.ts: new checker that derives the published route map from docs/index.yml (variant + section slugs) and resolves the commands page's relative links route-relative, the way Fern serves them, failing if any resolves to a route that is not published. Scoped to the commands reference page, which has regressed repeatedly ([All Platforms][Docs] commands.mdx has broken internal link and hardcoded OpenClaw version strings #5445, docs(commands): fix broken plugin link and drop hardcoded agent versions #6290, docs: fix broken link and hardcoded version strings in commands.mdx #5465, docs: fix stale links and skill listing #5460).
package.json: add docs:check-routes and wire it into npm run docs:strict, so a source-path-valid but published-route-broken link fails docs validation.
test/repro-5445-docs-published-route.test.ts: Vitest regression that derives the route from docs/index.yml, asserts the commands link resolves to /user-guide/openclaw/manage-sandboxes/install-openclaw-plugins and not /user-guide/openclaw/deployment/install-openclaw-plugins, plus resolver/extractor robustness cases.

Root cause

PR #6290, tasked with fixing this link, reasoned from the source file path (docs/deployment/install-openclaw-plugins.mdx) and "corrected" a previously-working manage-sandboxes link back to deployment. fern check and source-path checks both pass on the broken form because the source file exists — the missing validation was published-route resolution.

Type of Change

Code change with doc updates

Quality Gates

Tests added or updated for changed behavior
Docs updated for user-facing behavior changes
Docs not applicable — justification: the changed page is the doc; the link target and its content are unchanged, only the route it points to is corrected.

Verification

PR description includes the DCO sign-off declaration and every commit appears as Verified in GitHub
Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
Targeted behavior tests pass for the current change set — command/result: npx vitest run test/repro-5445-docs-published-route.test.ts (8 passed; fails on upstream/main pre-fix, passes post-fix); npm run docs:strict (0 errors).
No secrets, API keys, or credentials committed
npm run docs builds without warnings (doc changes only)

Route-level reporter-workflow evidence

Ground truth from Fern's own link resolver (fern docs broken-links), the same resolution the reader navigates:

Before (upstream/main): 26 broken links, including the commands page → /user-guide/openclaw/deployment/install-openclaw-plugins (404).
After (this branch): 24 broken links — the commands-page install-plugins error is gone, and none added. The remaining 24 are pre-existing, unrelated broken links (nested-page relative links, hermes-variant structural gaps) outside this issue's scope.

fern check alone does not catch this (it passed in #6290); the new docs:check-routes gate does.

Signed-off-by: Yimo Jiang yimoj@nvidia.com

Summary by CodeRabbit

Bug Fixes
- Corrected a documentation link to point to the published “Install OpenClaw Plugins” page under the correct route.
- Improved doc link validation to ensure links resolve to published routes (including correct route selection).
Tests
- Added/expanded regression coverage for the plugin installation link, published-route mapping, and robust markdown link resolution.
Chores
- Enhanced the strict documentation checks to also verify published-route correctness and route mappings.

The OpenClaw commands reference linked to ../deployment/install-openclaw-plugins, mirroring the target's source directory. Fern publishes that page under the manage-sandboxes nav section (docs/index.yml), so the link 404s on the live site even though the source file exists on disk. PR #6290 reverted a previously correct link because fern check and source-path checks both pass on it. Restore the published-route link and add a route-level regression guard: scripts/check-docs-published-routes.ts derives the published route map from docs/index.yml and resolves the commands page's relative links route-relative (as Fern serves them), failing if any resolves to no published route. It is wired into 'npm run docs:strict' and covered by a Vitest regression that fails on upstream/main and passes after the fix. Verified against Fern's own 'fern docs broken-links': the commands-page error is gone (26 -> 24), none added. Fixes #5445 Signed-off-by: Yimo Jiang <yimoj@nvidia.com>

coderabbitai · 2026-07-07T08:39:53Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 24e736e6-df27-4114-8cc6-fbe00e9ebac4

📥 Commits

Reviewing files that changed from the base of the PR and between ebe8ec8 and 400d50d.

📒 Files selected for processing (2)

scripts/check-docs-published-routes.ts
test/repro-5445-docs-published-route.test.ts

🚧 Files skipped from review as they are similar to previous changes (2)

scripts/check-docs-published-routes.ts
test/repro-5445-docs-published-route.test.ts

📝 Walkthrough

Walkthrough

Updates one docs link, adds a published-route validation script, wires it into npm checks, and adds regression tests covering route resolution and markdown link extraction.

Changes

Docs Link Fix and Route Validation Tooling

Layer / File(s)	Summary
Fix broken OpenClaw plugin link `docs/reference/commands.mdx`	Updates the install-openclaw-plugins link target from `../deployment/...` to `../manage-sandboxes/...`.
Published-route index and resolution core `scripts/check-docs-published-routes.ts`	Defines route-index types, builds published routes from `docs/index.yml`, and resolves relative targets against source routes.
Markdown link extraction and violation detection `scripts/check-docs-published-routes.ts`	Extracts markdown links from source pages, filters relative targets, adds violation records, and checks resolved routes for publication.
CLI entry point and npm wiring `scripts/check-docs-published-routes.ts`, `package.json`	Adds the script entrypoint, failure reporting, guarded execution, `docs:check-routes`, and updates `docs:strict` to run it.
Regression test suite `test/repro-5445-docs-published-route.test.ts`	Adds Vitest coverage for the commands link, route mapping, resolution behavior, and markdown parsing edge cases.

Sequence Diagram(s)

sequenceDiagram
  participant scripts/check-docs-published-routes.ts
  participant docs/index.yml
  participant docs/reference/commands.mdx
  participant package.json
  scripts/check-docs-published-routes.ts->>docs/index.yml: buildPublishedRouteIndex()
  scripts/check-docs-published-routes.ts->>docs/reference/commands.mdx: findBrokenPublishedRoutes()
  package.json->>scripts/check-docs-published-routes.ts: npm run docs:check-routes

Estimated code review effort: 3 (Moderate) | ~25 minutes

Related issues: #5445

Suggested labels: area: docs, bug-fix

Suggested reviewers: cv, miyoungc

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The broken link is fixed and regression-covered, but the hardcoded version strings from `#5445` were not addressed.	Replace the hardcoded OpenClaw and Hermes version strings in commands.mdx with placeholders or templated values.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main docs link-routing change and references the issue.
Out of Scope Changes check	✅ Passed	The added route checker, script wiring, and regression test all support the documented link-fix objective.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch fix/5445-docs-published-route-test

Warning

Review ran into problems

🔥 Problems

Git: Failed to clone repository. Please run the @coderabbitai full review command to re-trigger a full review. If the issue persists, set path_filters to include or exclude specific files.

_{Comment @coderabbitai help to get the list of available commands.}

github-code-quality · 2026-07-07T08:40:02Z

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in the fix/5445-docs-publis... branch is 96%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	`main`	`fix/5445-docs-publis...` cb04042	+/-
`nemoclaw/src/se...cret-scanner.ts`	—	100%	—
`nemoclaw/src/commands/slash.ts`	—	100%	—
`nemoclaw/src/li...bprocess-env.ts`	—	100%	—
`nemoclaw/src/bl...eprint/state.ts`	—	98%	—
`nemoclaw/src/onboard/config.ts`	—	98%	—
`nemoclaw/src/bl...int/snapshot.ts`	—	97%	—
`nemoclaw/src/bl...print/runner.ts`	—	95%	—
`nemoclaw/src/co...ration-state.ts`	—	94%	—
`nemoclaw/src/bl...ate-networks.ts`	—	94%	—
`nemoclaw/src/index.ts`	—	94%	—

TypeScript / code-coverage/cli

The overall coverage in the fix/5445-docs-publis... branch is 75%. Coverage data for the main branch is not yet available.

Show a code coverage summary of the most covered files.

File	`main`	`fix/5445-docs-publis...` cb04042	+/-
`src/lib/shields...nsition-lock.ts`	—	85%	—
`src/lib/onboard/preflight.ts`	—	83%	—
`src/lib/actions...all/run-plan.ts`	—	81%	—
`src/lib/state/o...oard-session.ts`	—	80%	—
`src/lib/actions...licy-channel.ts`	—	79%	—
`src/lib/state/sandbox.ts`	—	75%	—
`src/lib/onboard...er-gpu-patch.ts`	—	69%	—
`src/lib/shields/index.ts`	—	68%	—
`src/lib/policy/index.ts`	—	66%	—
`src/lib/onboard.ts`	—	28%	—

_{Updated July 07, 2026 09:14 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.}

github-actions · 2026-07-07T08:40:05Z

🌿 Preview your docs: https://nvidia-preview-pr-6385.docs.buildwithfern.com/nemoclaw

github-actions · 2026-07-07T08:40:07Z

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

None. No E2E is recommended. The PR only changes documentation, documentation validation tooling, package.json docs scripts, and a non-live regression test. It does not alter installer/onboarding, sandbox lifecycle, credentials, security boundaries, network policy, inference routing, deployment/runtime code, or real assistant user flows.

Optional E2E

None.

New E2E recommendations

None.

github-actions · 2026-07-07T08:40:08Z

E2E Target Recommendation

Required E2E targets: None
Optional E2E targets: None

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

None. Changes are limited to documentation, docs-check scripting/package wiring, and a non-E2E regression test outside test/e2e/. They do not affect the canonical E2E target workflow, registry/runtime support, fixtures, live tests, or target-relevant runtime behavior.

Optional E2E targets

None.

Relevant changed files

None.

github-actions · 2026-07-07T08:42:33Z

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

github-actions · 2026-07-07T08:44:24Z

PR Review Advisor (Nemotron Ultra) — Informational

Merge posture: Informational / low confidence
Primary next action: Resolve or justify PRA-1: PR review advisor unavailable.
Open items: 0 required · 1 warning · 0 suggestions · 1 test follow-up
Top item: PR review advisor unavailable

Action checklist

PRA-1 Resolve or justify: PR review advisor unavailable
PRA-T1 Add or justify test follow-up: Runtime validation

Findings index

ID	Severity	Category	Location	Required action
`PRA-1`	Resolve/justify	correctness	—	Re-run the PR Review Advisor or perform a manual review.

Review findings by urgency: 0 required fixes, 1 item to resolve/justify, 0 in-scope improvements

⚠️ Resolve or justify before merge

Investigate these in the current review; either fix them, explain why they are not applicable, or document the accepted risk.

`PRA-1` Resolve/justify — PR review advisor unavailable

Location: not file-specific
Category: correctness
Problem: The automated advisor could not complete: timed out after 900000 ms
Impact: Automated review evidence is incomplete, so human review must cover the changed code manually.
Recommended action: Re-run the PR Review Advisor or perform a manual review.
Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
Verification: Inspect the workflow logs and raw advisor artifact for the execution failure.
Missing regression test: No regression test recommendation is available because the advisor did not complete.
Done when: The risk is fixed or explicitly justified in the PR. Verification: Inspect the workflow logs and raw advisor artifact for the execution failure.
Evidence: timed out after 900000 ms

💡 In-scope improvements

These are lower-risk, not throwaway. Prefer fixing them in this PR when they are local to changed code; defer only with rationale or a linked follow-up.

None.

Test follow-ups to resolve or justify

If these cover changed behavior, prefer adding them in this PR; otherwise state why existing coverage is enough or link the follow-up.

PRA-T1 Runtime validation — Add or identify targeted runtime/integration validation for the changed behavior; do not report external E2E job pass/fail here.. Runtime/sandbox/infrastructure paths need behavioral runtime validation: docs/reference/commands.mdx, package.json, scripts/check-docs-published-routes.ts.

Workflow run details

This is an automated, non-binding review; it still expects maintainers and agents to respond to each required or warning item. Treat suggestions as current-PR improvements when they touch changed code; defer only with maintainer rationale or a linked follow-up. A human maintainer must make the final merge decision.

The route regression read docs/reference/commands.mdx directly in the test and asserted on the extracted link, which the source-shape budget gate (scripts/find-source-shape-tests.ts) flags as source-text coupling (budget 0). Move the docs read into an exported resolvePageLinkByText() in the checker and assert on its returned resolved route + published flag instead. Behavior is unchanged: the test still fails on upstream/main (link resolves to the deployment route) and passes after the fix. Signed-off-by: Yimo Jiang <yimoj@nvidia.com>

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

cv

Substantive review passed. All 43 checks are green, the published-route behavior and regression guard are correct, and the exact-head primary GPT-5.5 advisor returned merge_as_is with no findings. The secondary Nemotron result is info_only because that lane timed out and contains no code finding; its earlier Hermes warning is inapplicable because the OpenClaw-only AgentOnly block is stripped from the generated Hermes page. No actionable CodeRabbit item remains.

…ion (NVIDIA#5445) (NVIDIA#6385) ## Summary The OpenClaw commands reference page linked to the Install OpenClaw Plugins page using its **source directory** (`../deployment/install-openclaw-plugins`), but Fern publishes that page under the **`manage-sandboxes`** nav section. The link therefore 404s on the live site even though the source file exists on disk. This restores the published-route link and adds a route-level regression guard so the drift cannot recur. ## Related Issue Fixes NVIDIA#5445 ## Changes - `docs/reference/commands.mdx`: link `Install OpenClaw Plugins` via its published nav section (`../manage-sandboxes/install-openclaw-plugins`) instead of its source directory (`../deployment/install-openclaw-plugins`). - `scripts/check-docs-published-routes.ts`: new checker that derives the published route map from `docs/index.yml` (variant + section slugs) and resolves the commands page's relative links **route-relative, the way Fern serves them**, failing if any resolves to a route that is not published. Scoped to the commands reference page, which has regressed repeatedly (NVIDIA#5445, NVIDIA#6290, NVIDIA#5465, NVIDIA#5460). - `package.json`: add `docs:check-routes` and wire it into `npm run docs:strict`, so a source-path-valid but published-route-broken link fails docs validation. - `test/repro-5445-docs-published-route.test.ts`: Vitest regression that derives the route from `docs/index.yml`, asserts the commands link resolves to `/user-guide/openclaw/manage-sandboxes/install-openclaw-plugins` and **not** `/user-guide/openclaw/deployment/install-openclaw-plugins`, plus resolver/extractor robustness cases. ## Root cause PR NVIDIA#6290, tasked with fixing this link, reasoned from the source file path (`docs/deployment/install-openclaw-plugins.mdx`) and "corrected" a previously-working `manage-sandboxes` link back to `deployment`. `fern check` and source-path checks both pass on the broken form because the source file exists — the missing validation was published-route resolution. ## Type of Change - [x] Code change with doc updates ## Quality Gates - [x] Tests added or updated for changed behavior - [ ] Docs updated for user-facing behavior changes - [x] Docs not applicable — justification: the changed page is the doc; the link target and its content are unchanged, only the route it points to is corrected. ## Verification - [x] PR description includes the DCO sign-off declaration and every commit appears as `Verified` in GitHub - [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or `npm run check:diff` passed when hooks were skipped or unavailable - [x] Targeted behavior tests pass for the current change set — command/result: `npx vitest run test/repro-5445-docs-published-route.test.ts` (8 passed; fails on upstream/main pre-fix, passes post-fix); `npm run docs:strict` (0 errors). - [x] No secrets, API keys, or credentials committed - [x] `npm run docs` builds without warnings (doc changes only) ### Route-level reporter-workflow evidence Ground truth from Fern's own link resolver (`fern docs broken-links`), the same resolution the reader navigates: - **Before (upstream/main):** 26 broken links, including the commands page → `/user-guide/openclaw/deployment/install-openclaw-plugins` (404). - **After (this branch):** 24 broken links — the commands-page install-plugins error is gone, and **none added**. The remaining 24 are pre-existing, unrelated broken links (nested-page relative links, hermes-variant structural gaps) outside this issue's scope. `fern check` alone does not catch this (it passed in NVIDIA#6290); the new `docs:check-routes` gate does. --- Signed-off-by: Yimo Jiang <yimoj@nvidia.com>  ## Summary by CodeRabbit * **Bug Fixes** * Corrected a documentation link to point to the published “Install OpenClaw Plugins” page under the correct route. * Improved doc link validation to ensure links resolve to published routes (including correct route selection). * **Tests** * Added/expanded regression coverage for the plugin installation link, published-route mapping, and robust markdown link resolution. * **Chores** * Enhanced the strict documentation checks to also verify published-route correctness and route mappings.  --------- Signed-off-by: Yimo Jiang <yimoj@nvidia.com> Signed-off-by: Carlos Villela <cvillela@nvidia.com> Co-authored-by: Carlos Villela <cvillela@nvidia.com>

yimoj added the v0.0.76 label Jul 7, 2026

merge: sync main into docs route fix

cb04042

Signed-off-by: Carlos Villela <cvillela@nvidia.com>

cv approved these changes Jul 7, 2026

View reviewed changes

cv merged commit 5a6f489 into main Jul 7, 2026
43 checks passed

cv deleted the fix/5445-docs-published-route-test branch July 7, 2026 09:28

apurvvkumaria mentioned this pull request Jul 8, 2026

docs: fix broken link and hardcoded version strings in commands.mdx #5465

Closed

13 tasks

wscurran added area: docs Documentation, examples, guides, or docs build chore Build, CI, dependency, or tooling maintenance labels Aug 1, 2026

Uh oh!

Conversation

yimoj commented Jul 7, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related Issue

Changes

Root cause

Type of Change

Quality Gates

Verification

Route-level reporter-workflow evidence

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Review ran into problems

Uh oh!

github-code-quality Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Code Coverage Overview

TypeScript / code-coverage/plugin

TypeScript / code-coverage/cli

Uh oh!

github-actions Bot commented Jul 7, 2026

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Advisor Recommendation

E2E Recommendation Advisor

Required E2E

Optional E2E

New E2E recommendations

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

E2E Target Recommendation

E2E Target Advisor

Required E2E targets

Optional E2E targets

Relevant changed files

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor — No blocking findings

Uh oh!

github-actions Bot commented Jul 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Review Advisor (Nemotron Ultra) — Informational

Action checklist

Findings index

⚠️ Resolve or justify before merge

PRA-1 Resolve/justify — PR review advisor unavailable

💡 In-scope improvements

Uh oh!

cv left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yimoj commented Jul 7, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 7, 2026 •

edited

Loading

github-code-quality Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading

github-actions Bot commented Jul 7, 2026 •

edited

Loading

`PRA-1` Resolve/justify — PR review advisor unavailable