docs: refactor shared gateway and CA guidance

[miyoungc]

Summary

Consolidates shared gateway route behavior into a focused Manage Inference page and corporate CA behavior into a focused Security page. Troubleshooting remains one searchable reference with concise recovery entries and preserved anchors, while agent-specific guidance reflects the tested support matrix.

Changes

• Add canonical shared gateway route guidance for OpenClaw, Hermes, and Deep Agents, including route drift, provider-global compatibility, and hard-conflict recovery.
• Add canonical corporate CA guidance for OpenClaw and Hermes, including source selection, trust boundaries, custom Dockerfile requirements, and the OpenClaw/Hermes build-time distinction.
• Replace duplicated explanations in inference, command reference, troubleshooting, and historical changelog entries with links to the canonical owners.
• Keep Troubleshooting as one Ctrl-F-friendly page, retain the existing dashboard and corporate TLS headings, and expose shared-route recovery to every supported agent variant.
• Add the new pages to the applicable navigation variants without changing existing routes or requiring redirects.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification: Documentation-only ownership refactor; focused route, link, and changelog tests validate the published structure.
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Verification

• PR description includes a Signed-off-by: line 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, or tests are marked not applicable above — npx vitest run test/check-docs-published-routes.test.ts test/check-docs-links.test.ts test/changelog-docs.test.ts (40 passed)
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only)
  • npm run docs exited successfully. Fern reported the unchanged light-theme contrast warning and a remote FDR redirect comparison warning caused by an HTTP 403.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

• Documentation
  • Added a new guide explaining shared inference gateway routes, including how to interpret live vs recorded route status, handle conflicts, and safely recover compatibility.
  • Added a dedicated guide for trusting corporate MITM/proxy CAs, including the configuration workflow and related best practices.
  • Updated the model/provider switching, active route viewing, command reference, and troubleshooting docs to point to the new shared-route and corporate-CA guides.
  • Extended documentation navigation and changelog references for the new guide pages across supported agent variants.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

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: 646660b2-0a23-449c-9116-e9866fe986a2

📥 Commits

Reviewing files that changed from the base of the PR and between d5ada66 and 21b5037.

📒 Files selected for processing (1)

• docs/inference/use-shared-gateway-routes.mdx

---

📝 Walkthrough

Walkthrough

This documentation update adds dedicated guides for shared inference gateway routes and corporate CA trust. Existing inference, command, troubleshooting, changelog, and navigation pages now link to the new guides and provide shorter cross-references.

Changes

Shared Gateway Routes

Layer / File(s)	Summary
Shared route workflow docs/inference/use-shared-gateway-routes.mdx	Documents shared live routes, onboarding, connect, status, route drift, compatibility checks, and conflict recovery.
Shared route references docs/inference/*, docs/reference/commands.mdx, docs/reference/troubleshooting.mdx, docs/index.yml, docs/changelog/2026-07-14.mdx	Updates related guidance, troubleshooting, command references, navigation, and changelog links for shared gateway routes.

Corporate CA Trust

Layer / File(s)	Summary
Corporate CA trust guide docs/security/configure-corporate-ca-trust.mdx	Documents corporate CA bundle configuration, validation, injection, source selection, Dockerfile requirements, verification, trust constraints, and disabling import.
Corporate CA references docs/reference/troubleshooting.mdx, docs/index.yml, docs/changelog/2026-07-10.mdx, docs/changelog/2026-07-14.mdx	Redirects troubleshooting, navigation, and changelog references to the corporate CA trust guide.

Estimated code review effort: 2 (Simple) | ~10 minutes

Suggested labels: refactor, area: security

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main documentation refactor around shared gateway routing and corporate CA guidance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/post-tag-docs-refactor

---

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

[github-actions]

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: docs-validation

3 optional E2E recommendations

• gateway-drift-preflight
• inference-routing
• security-posture

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/inference/use-shared-gateway-routes.mdx`:
- Around line 59-61: Update the recovery guidance in the affected sandbox
troubleshooting bullets to explicitly require removing the sandbox after backing
it up and before re-onboarding, particularly for incomplete legacy custom-route
metadata and invalid gateway bindings. Keep the existing backup and
re-onboarding instructions, while matching the removal requirement documented in
the troubleshooting reference.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: cdb7a365-47a0-494b-b46f-a79b0969ed3a

📥 Commits

Reviewing files that changed from the base of the PR and between 7d1cef9 and d5ada66.

📒 Files selected for processing (10)

• docs/changelog/2026-07-10.mdx
• docs/changelog/2026-07-14.mdx
• docs/index.yml
• docs/inference/switch-models.mdx
• docs/inference/switch-providers.mdx
• docs/inference/use-shared-gateway-routes.mdx
• docs/inference/view-active-inference-route.mdx
• docs/reference/commands.mdx
• docs/reference/troubleshooting.mdx
• docs/security/configure-corporate-ca-trust.mdx

[prekshivyas]

Reviewed the documentation refactor and latest recovery-guidance fix. Internal links, published Fern routes, generated agent variants, and strict docs validation pass; head-specific E2E checks are green. Approving.