Skip to content

docs(inference): split guides into nested topics - #6659

Merged
miyoungc merged 13 commits into
mainfrom
codex/nested-inference-toc
Jul 11, 2026
Merged

docs(inference): split guides into nested topics#6659
miyoungc merged 13 commits into
mainfrom
codex/nested-inference-toc

Conversation

@miyoungc

@miyoungc miyoungc commented Jul 10, 2026

Copy link
Copy Markdown
Collaborator

Summary

Reorganize the inference documentation into nested, task-focused pages so readers no longer have to navigate five oversized guides.
Add variant-aware navigation, stable redirects, and route validation that keeps the new published paths correct across OpenClaw, Hermes, and Deep Agents.

Changes

  • Split provider choice, hosted setup, local setup, custom endpoints, inference management, and troubleshooting into focused leaf pages.
  • Add a Configure Agents section for progressive tool disclosure, OpenClaw context compaction, heartbeats, sub-agents, and manifests.
  • Redirect the previous inference URLs and migrate references throughout the docs to the nested published routes.
  • Move the generated provider-status table and contributor docs routing to their new canonical pages.
  • Guard all inference and Configure Agents pages against source-path versus published-route drift, with updated regression coverage.

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:
  • 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: Independent documentation review completed; source-to-destination retention, agent-variant behavior, redirects, and published-route resolution were audited before handoff.
  • Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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, or tests are marked not applicable above — command/result or justification: npx vitest run test/check-docs-published-routes.test.ts test/model-capability-audit-doc.test.ts test/inference-options-docs.test.ts passed with 25 tests.
  • 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) — build passed with 0 errors and two warnings: unauthenticated redirect checking and the existing light-mode accent contrast warning.
  • 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
    • Reorganized inference guidance into dedicated pages for choosing a provider/model, local servers, custom endpoints, routing, validation, model limits, inference timeouts, and route verification.
    • Added new guides for Ollama, vLLM, NVIDIA NIM, OpenAI, Anthropic, Gemini, OpenRouter, Hermes, custom endpoints, model router, switching providers/models, agent heartbeats, progressive tool disclosure, and context compaction.
    • Updated navigation, cross-links, redirects, and release-note references; removed legacy “Inference Options” pages.
  • Bug Fixes
    • Strengthened checks for broken inference documentation links and redirects.
  • Tests
    • Updated/expanded inference documentation and published-route coverage to match the new structure.

Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
@miyoungc miyoungc added area: docs Documentation, examples, guides, or docs build area: skills Skills, agent behaviors, prompts, or skill packaging labels Jul 10, 2026
@miyoungc miyoungc self-assigned this Jul 10, 2026
@coderabbitai

coderabbitai Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

The PR reorganizes NemoClaw inference documentation into focused provider, model, setup, configuration, validation, and management pages. It updates navigation, redirects, cross-references, generated-doc targets, adds agent configuration pages, and extends published-route validation tests.

Changes

Inference documentation restructure

Layer / File(s) Summary
Navigation and redirect wiring
.pre-commit-config.yaml, docs/index.yml, fern/docs.yml, scripts/generate-platform-docs.py, .agents/.../SKILL.md
Replaces legacy inference navigation and redirect targets with the reorganized page hierarchy and generated-document mappings.
Provider selection and setup guidance
docs/inference/choose-*.mdx, docs/inference/set-up-*.mdx, docs/inference/use-*.mdx
Adds focused guidance for provider/model selection, local servers, compatible APIs, hosted providers, Ollama, vLLM, NIM, custom endpoints, and the Model Router.
Inference configuration and validation
docs/inference/configure-*.mdx, docs/inference/custom-endpoint-security.mdx, docs/inference/understand-provider-validation.mdx, docs/inference/how-inference-routing-works.mdx
Documents timeout, model capability, model limit, endpoint-security, routing, API-selection, and provider-validation behavior.
Route management and troubleshooting
docs/inference/switch-*.mdx, docs/inference/view-active-inference-route.mdx, docs/inference/verify-inference-route.mdx, docs/reference/troubleshooting.mdx
Adds provider/model switching, active-route inspection, route verification, and structured tool-call troubleshooting guidance.
Agent configuration pages
docs/configure-agents/*
Adds documentation for OpenClaw heartbeats, progressive tool disclosure, and context compaction.
Cross-document references
README.md, docs/about/*, docs/get-started/*, docs/reference/*, docs/security/*, docs/manage-sandboxes/*, docs/deployment/*, docs/monitoring/*, scripts/*, src/*
Repoints internal links, release-note references, source comments, and generated-report links to the new documentation structure.
Published-route validation
scripts/check-docs-published-routes.ts, test/*, .coderabbit.yaml
Adds dynamic inference/configure-agents source coverage, Fern redirect validation, updated structure tests, and route-link review instructions.

Estimated code review effort: 4 (Complex) | ~60 minutes

Possibly related PRs

  • NVIDIA/NemoClaw#5162: Updates contributor skill references for the reorganized inference documentation.
  • NVIDIA/NemoClaw#5244: Overlaps with legacy inference-options and local/vLLM documentation targets.
  • NVIDIA/NemoClaw#5440: Overlaps with declarative-agent-manifest documentation and navigation changes.

Suggested labels: chore, area: inference

Suggested reviewers: ericksoa, kjw3, cv

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
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.
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: reorganizing inference docs into nested, task-focused topics.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch codex/nested-inference-toc

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

@github-code-quality

github-code-quality Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage remains at 96%, unchanged from the main branch.

TypeScript / code-coverage/cli

The overall coverage in the codex/nested-inferen... branch remains at 77%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.
File main 78d5bc3 codex/nested-inferen... ab2d710 +/-
src/lib/actions...light-guards.ts 88% 71% -17%
src/lib/actions...confirmation.ts 81% 69% -12%
src/lib/onboard...e-patch-flow.ts 71% 61% -10%
src/lib/messagi...nes/template.ts 100% 92% -8%
src/lib/actions...estore-phase.ts 93% 87% -6%
src/lib/inference/config.ts 98% 93% -5%
src/lib/credentials/store.ts 59% 61% +2%
src/lib/adapters/http/probe.ts 89% 91% +2%
src/lib/actions...ge-preflight.ts 74% 94% +20%
src/lib/sandbox...rsion-scheme.ts 73% 100% +27%

Updated July 11, 2026 00:45 UTC
Code Coverage is in Public Preview. Learn more and provide us with your feedback.

@github-actions

Copy link
Copy Markdown
Contributor

@miyoungc
miyoungc marked this pull request as draft July 10, 2026 21:36
@copy-pr-bot

copy-pr-bot Bot commented Jul 10, 2026

Copy link
Copy Markdown

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.

@miyoungc
miyoungc marked this pull request as ready for review July 10, 2026 21:37
Comment thread test/inference-options-docs.test.ts Fixed
@miyoungc
miyoungc marked this pull request as draft July 10, 2026 21:38
Comment thread test/inference-options-docs.test.ts Fixed

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 12

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
docs/inference/use-openrouter.mdx (1)

58-58: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Add the missing period.

This related-topic sentence should end with a period to comply with the documentation guidelines.

-- [Understand Provider Validation](../validate-and-troubleshoot/understand-provider-validation) describes provider validation behavior.
+- [Understand Provider Validation](../validate-and-troubleshoot/understand-provider-validation) describes provider validation behavior.
🤖 Prompt for 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.

In `@docs/inference/use-openrouter.mdx` at line 58, Add a period to the end of the
related-topic sentence in the documentation.

Source: Coding guidelines

🤖 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/about/overview.mdx`:
- Line 73: Correct the inference-provider links in the overview table, including
the entries corresponding to the “Routed inference” and the other affected rows,
by replacing ../inference/learn-and-choose/choose-inference-provider with
../inference/choose-inference-provider.

In `@docs/configure-agents/understand-context-compaction.mdx`:
- Line 35: Update the model-limits reference near “Configure Model Limits” to
use the relative link ../inference/configure-model-limits, removing the
incorrect manage-inference path.

In `@docs/get-started/quickstart-hermes.mdx`:
- Line 87: Update the inference-provider links in quickstart-hermes.mdx,
including the references near the related repeated locations, to use
../inference/choose-inference-provider so they resolve to the existing page
instead of the nonexistent nested route.

In `@docs/inference/fix-tool-calling-failures.mdx`:
- Line 52: The onboarding instructions use the wrong provider option for an
already-running parser-aware vLLM server. Update this section to select “Local
vLLM (already running)” and reserve “Local vLLM [experimental]” for the
managed-install workflow, or explicitly distinguish both setup paths.

In `@docs/inference/set-up-ollama.mdx`:
- Around line 96-107: Update the Windows Ollama setup and restart guidance to
avoid exposing the unauthenticated API on all interfaces: either require and
document a Windows Firewall rule that restricts port 11434 to WSL/Docker
traffic, or configure OLLAMA_HOST to bind only to the adapter/address required
by host.docker.internal. Apply the restriction consistently to every
Windows-host launch path.

In `@docs/inference/set-up-openai-compatible-endpoint.mdx`:
- Around line 44-52: Clarify the onboarding validation statement to distinguish
endpoint types: state that a real inference request is performed before sandbox
creation only for host-routable endpoints, while the sandbox-internal
host.openshell.internal alias skips that probe and must be verified through the
runtime route after onboarding.

In `@docs/inference/set-up-vllm.mdx`:
- Around line 118-123: Update the `HF_TOKEN` example in the vLLM setup
instructions to quote the placeholder value, using valid shell syntax such as
`export HF_TOKEN="<your-hf-token>"`, so users can copy the command without
triggering redirection parsing.

In `@docs/inference/understand-provider-validation.mdx`:
- Line 84: The OpenAI-compatible endpoint link in the inference documentation
points to the wrong location; update the link target in the relevant markdown
entry to the sibling path set-up-openai-compatible-endpoint, removing the
../custom-endpoints/ prefix.

In `@docs/inference/use-nvidia-endpoints.mdx`:
- Around line 50-51: Update the links in the inference documentation list to use
the local targets `choose-model` and `understand-provider-validation`, while
preserving their existing link text.

In `@docs/inference/view-active-inference-route.mdx`:
- Line 73: Update the “Verify the Sandbox Inference Route” link in the relevant
documentation to target the sibling page `verify-inference-route` instead of the
incorrect `../validate-and-troubleshoot/verify-inference-route` path.

In `@docs/manage-sandboxes/workspace-files.mdx`:
- Line 108: Update the “Set Up Task-Specific Sub-Agents” link in the
workspace-files documentation to target ../inference/set-up-sub-agent, unless
the intended fix is to add the missing configure-agents page.

In `@test/model-capability-audit-doc.test.ts`:
- Around line 73-77: Add negative assertions in the model-capability audit test
alongside the existing positive link checks, verifying that the exact superseded
inference-provider and tool-calling hrefs are absent from markdown. Keep the
assertions focused on the old paths so the migration test fails if stale links
remain.

---

Outside diff comments:
In `@docs/inference/use-openrouter.mdx`:
- Line 58: Add a period to the end of the related-topic sentence in the
documentation.
🪄 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: e6db73f3-664f-4d85-b8dc-b8e956efff26

📥 Commits

Reviewing files that changed from the base of the PR and between 58d8559 and d20fc0d.

📒 Files selected for processing (75)
  • .agents/skills/nemoclaw-contributor-update-docs/SKILL.md
  • .pre-commit-config.yaml
  • README.md
  • docs/about/ecosystem-deepagents.mdx
  • docs/about/how-it-works.mdx
  • docs/about/overview.mdx
  • docs/about/release-notes.mdx
  • docs/configure-agents/configure-agent-heartbeats.mdx
  • docs/configure-agents/progressive-tool-disclosure.mdx
  • docs/configure-agents/understand-context-compaction.mdx
  • docs/deployment/brev-web-ui.mdx
  • docs/deployment/deploy-to-remote-gpu.mdx
  • docs/get-started/quickstart-hermes.mdx
  • docs/get-started/quickstart-langchain-deepagents-code.mdx
  • docs/get-started/quickstart.mdx
  • docs/get-started/windows-preparation.mdx
  • docs/index.yml
  • docs/inference/choose-compatible-inference-api.mdx
  • docs/inference/choose-inference-provider.mdx
  • docs/inference/choose-local-inference-server.mdx
  • docs/inference/choose-model.mdx
  • docs/inference/configure-inference-timeouts.mdx
  • docs/inference/configure-model-capabilities.mdx
  • docs/inference/configure-model-limits.mdx
  • docs/inference/custom-endpoint-security.mdx
  • docs/inference/declarative-agents-manifest.mdx
  • docs/inference/fix-tool-calling-failures.mdx
  • docs/inference/how-inference-routing-works.mdx
  • docs/inference/inference-options.mdx
  • docs/inference/inference-overview.mdx
  • docs/inference/local-compatible-inference-setup.mdx
  • docs/inference/model-capability-audit.mdx
  • docs/inference/set-up-anthropic-compatible-endpoint.mdx
  • docs/inference/set-up-model-router.mdx
  • docs/inference/set-up-nvidia-nim.mdx
  • docs/inference/set-up-ollama.mdx
  • docs/inference/set-up-openai-compatible-endpoint.mdx
  • docs/inference/set-up-sub-agent.mdx
  • docs/inference/set-up-vllm.mdx
  • docs/inference/switch-inference-providers.mdx
  • docs/inference/switch-models.mdx
  • docs/inference/switch-providers.mdx
  • docs/inference/tool-calling-reliability.mdx
  • docs/inference/understand-provider-validation.mdx
  • docs/inference/use-anthropic.mdx
  • docs/inference/use-google-gemini.mdx
  • docs/inference/use-hermes-provider.mdx
  • docs/inference/use-local-inference.mdx
  • docs/inference/use-nvidia-endpoints.mdx
  • docs/inference/use-openai.mdx
  • docs/inference/use-openrouter.mdx
  • docs/inference/verify-inference-route.mdx
  • docs/inference/view-active-inference-route.mdx
  • docs/manage-sandboxes/lifecycle.mdx
  • docs/manage-sandboxes/runtime-controls.mdx
  • docs/manage-sandboxes/workspace-files.mdx
  • docs/monitoring/monitor-sandbox-activity.mdx
  • docs/reference/architecture.mdx
  • docs/reference/cli-selection-guide.mdx
  • docs/reference/commands.mdx
  • docs/reference/enterprise-readiness.mdx
  • docs/reference/platform-support.mdx
  • docs/reference/troubleshooting.mdx
  • docs/security/best-practices.mdx
  • docs/security/credential-rotation.mdx
  • fern/docs.yml
  • scripts/bench/lib.ts
  • scripts/check-docs-published-routes.ts
  • scripts/generate-platform-docs.py
  • src/lib/onboard/install-ollama-linux.ts
  • src/lib/onboard/model-router-python.ts
  • test/check-docs-published-routes.test.ts
  • test/generate-platform-docs.test.ts
  • test/inference-options-docs.test.ts
  • test/model-capability-audit-doc.test.ts
💤 Files with no reviewable changes (5)
  • docs/inference/use-local-inference.mdx
  • docs/inference/inference-options.mdx
  • docs/inference/local-compatible-inference-setup.mdx
  • docs/inference/switch-inference-providers.mdx
  • docs/inference/tool-calling-reliability.mdx

Comment thread docs/about/overview.mdx
Comment thread docs/configure-agents/understand-context-compaction.mdx
Comment thread docs/get-started/quickstart-hermes.mdx
Comment thread docs/inference/fix-tool-calling-failures.mdx Outdated
Comment thread docs/inference/set-up-ollama.mdx
Comment thread docs/inference/understand-provider-validation.mdx
Comment thread docs/inference/use-nvidia-endpoints.mdx Outdated
Comment thread docs/inference/view-active-inference-route.mdx Outdated
Comment thread docs/manage-sandboxes/workspace-files.mdx
Comment thread test/model-capability-audit-doc.test.ts
@github-actions

github-actions Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

E2E Advisor Recommendation

Required E2E: onboard-repair, onboard-resume, cloud-onboard
Optional E2E: model-router-provider-routed-inference, ollama-auth-proxy

Dispatch hint: onboard-repair,onboard-resume

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

  • onboard-repair (high): Required by the deterministic risk plan for lifecycle-state changes in src/lib/onboard/install-ollama-linux.ts and src/lib/onboard/model-router-python.ts. Validates repair convergence, stale resource handling, registry/session state, and live sandbox/gateway consistency after interrupted or drifted onboarding.
  • onboard-resume (medium): Required by the deterministic risk plan for lifecycle-state changes in src/lib/onboard/install-ollama-linux.ts and src/lib/onboard/model-router-python.ts. Validates resumable onboarding state, credential hydration from persisted/gateway state, and convergence after injected interruption.
  • cloud-onboard (high): Changed onboard, trace timing, scorecard, or E2E workflow code can affect cloud onboard wall-clock behavior and should refresh the trusted cloud-onboard trace timing signal.

Optional E2E

  • model-router-provider-routed-inference (medium): Useful adjacent coverage because src/lib/onboard/model-router-python.ts participates in Model Router host Python discovery and venv setup, which can affect Model Router provider onboarding and routed inference behavior.
  • ollama-auth-proxy (medium): Useful adjacent coverage because src/lib/onboard/install-ollama-linux.ts is part of local Ollama onboarding/install behavior. Run if reviewers want extra confidence around local Ollama route/proxy behavior after the onboarding helper change.

New E2E recommendations

  • None.

Dispatch hint

  • Workflow: .github/workflows/e2e.yaml
  • jobs input: onboard-repair,onboard-resume

@github-actions

github-actions Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

E2E Target Recommendation

Required E2E targets: onboard-repair, onboard-resume
Optional E2E targets: None

Dispatch required E2E targets:

  • gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=onboard-repair
  • gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=onboard-resume

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

  • onboard-repair: Onboarding and sandbox state must converge across persisted metadata, reported status, and the live runtime.
    • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=onboard-repair
  • onboard-resume: Onboarding and sandbox state must converge across persisted metadata, reported status, and the live runtime.
    • Dispatch: gh workflow run e2e.yaml --ref <pr-head-ref> --field jobs=onboard-resume

Optional E2E targets

  • None.

Relevant changed files

  • src/lib/onboard/install-ollama-linux.ts
  • src/lib/onboard/model-router-python.ts

@github-actions

github-actions Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: Add or justify PRA-T1 and any related test follow-ups.
Open items: 0 required · 0 warnings · 0 suggestions · 4 test follow-ups
Since last review: 0 prior items resolved · 0 still apply · 0 new items found

Action checklist

  • PRA-T1 Add or justify test follow-up: Runtime validation
  • PRA-T2 Add or justify test follow-up: Runtime validation
  • PRA-T3 Add or justify test follow-up: Runtime validation
  • PRA-T4 Add or justify test follow-up: Runtime validation
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 — Run the `onboard-repair` E2E job for Onboarding and sandbox state must converge across persisted metadata, reported status, and the live runtime. Matched files: `src/lib/onboard/install-ollama-linux.ts`, `src/lib/onboard/model-router-python.ts`.. Deterministic regression risks require live validation: lifecycle-state. RiskPlan tier 2 marks lifecycle-state because src/lib/onboard/install-ollama-linux.ts and src/lib/onboard/model-router-python.ts changed. Read-only inspection showed those changes are comment-only doc-reference updates, so no missing static regression test is warranted, but onboard-repair and onboard-resume remain the deterministic live validation floor.
  • PRA-T2 Runtime validation — Run or confirm the `onboard-repair` E2E job to validate partial-failure and repair convergence across persisted metadata, reported status, live gateway/sandbox state, and owned-resource cleanup for the touched onboarding surfaces.. Deterministic regression risks require live validation: lifecycle-state. RiskPlan tier 2 marks lifecycle-state because src/lib/onboard/install-ollama-linux.ts and src/lib/onboard/model-router-python.ts changed. Read-only inspection showed those changes are comment-only doc-reference updates, so no missing static regression test is warranted, but onboard-repair and onboard-resume remain the deterministic live validation floor.
  • PRA-T3 Runtime validation — Run the `onboard-resume` E2E job for Onboarding and sandbox state must converge across persisted metadata, reported status, and the live runtime. Matched files: `src/lib/onboard/install-ollama-linux.ts`, `src/lib/onboard/model-router-python.ts`.. Deterministic regression risks require live validation: lifecycle-state. RiskPlan tier 2 marks lifecycle-state because src/lib/onboard/install-ollama-linux.ts and src/lib/onboard/model-router-python.ts changed. Read-only inspection showed those changes are comment-only doc-reference updates, so no missing static regression test is warranted, but onboard-repair and onboard-resume remain the deterministic live validation floor.
  • PRA-T4 Runtime validation — Run or confirm the `onboard-resume` E2E job to validate resumed onboarding state convergence across persisted metadata, reported status, live gateway/sandbox state, and owned-resource cleanup for the touched onboarding surfaces.. Deterministic regression risks require live validation: lifecycle-state. RiskPlan tier 2 marks lifecycle-state because src/lib/onboard/install-ollama-linux.ts and src/lib/onboard/model-router-python.ts changed. Read-only inspection showed those changes are comment-only doc-reference updates, so no missing static regression test is warranted, but onboard-repair and onboard-resume remain the deterministic live validation floor.

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

github-actions Bot commented Jul 10, 2026

Copy link
Copy Markdown
Contributor

PR Review Advisor (Nemotron Ultra) — Changes requested

Merge posture: Do not merge yet
Primary next action: Fix PRA-1: SKILL.md inference mapping table does not cover new focused inference doc pages; then add or justify PRA-T1.
Open items: 1 required · 5 warnings · 1 suggestion · 6 test follow-ups
Since last review: 0 prior items resolved · 4 still apply · 3 new items found

Action checklist

  • PRA-1 Fix: SKILL.md inference mapping table does not cover new focused inference doc pages in .agents/skills/nemoclaw-contributor-update-docs/SKILL.md:85
  • PRA-2 Resolve or justify: Redirect validation for deleted inference pages not explicitly verified in scripts/check-docs-published-routes.ts:1
  • PRA-3 Resolve or justify: Release notes links updated to new inference doc paths but not all verified against published routes in docs/about/release-notes.mdx:1
  • PRA-5 Resolve or justify: Missing regression test for lifecycle-state invariant: partial failure and retry converge without ghost resources or stale ports in src/lib/onboard/install-ollama-linux.ts:1
  • PRA-6 Resolve or justify: Missing regression test for lifecycle-state invariant: status agrees with independently probed gateway and sandbox state in src/lib/onboard/model-router-python.ts:1
  • PRA-7 Resolve or justify: Missing regression test for lifecycle-state invariant: cleanup preserves unrelated sandboxes and removes only owned resources in src/lib/onboard/install-ollama-linux.ts:1
  • PRA-T1 Add or justify test follow-up: Runtime validation
  • PRA-T2 Add or justify test follow-up: Runtime validation
  • PRA-T3 Add or justify test follow-up: Missing regression test for lifecycle-state invariant: partial failure and retry converge without ghost resources or stale ports
  • PRA-T4 Add or justify test follow-up: Missing regression test for lifecycle-state invariant: status agrees with independently probed gateway and sandbox state
  • PRA-T5 Add or justify test follow-up: Missing regression test for lifecycle-state invariant: cleanup preserves unrelated sandboxes and removes only owned resources
  • PRA-T6 Add or justify test follow-up: Acceptance clause
  • PRA-4 In-scope improvement: Test file named after deleted documentation file in test/inference-options-docs.test.ts:1

Findings index

ID Severity Category Location Required action
PRA-1 Required scope .agents/skills/nemoclaw-contributor-update-docs/SKILL.md:85 Expand the SKILL.md mapping table with explicit rows for each inference sub-area (e.g., 'Choose provider/model' -> choose-inference-provider.mdx, choose-model.mdx; 'Hosted provider setup' -> use-nvidia-endpoints.mdx, use-openrouter.mdx, use-openai.mdx, use-anthropic.mdx, use-google-gemini.mdx, set-up-model-router.mdx; 'Local inference' -> choose-local-inference-server.mdx, set-up-ollama.mdx, set-up-vllm.mdx, set-up-nvidia-nim.mdx; 'Custom endpoints' -> set-up-openai-compatible-endpoint.mdx, set-up-anthropic-compatible-endpoint.mdx, choose-compatible-inference-api.mdx, custom-endpoint-security.mdx; 'Inference management' -> view-active-inference-route.mdx, switch-models.mdx, switch-providers.mdx, configure-model-limits.mdx, configure-model-capabilities.mdx, configure-inference-timeouts.mdx; 'Inference validation' -> understand-provider-validation.mdx, verify-inference-route.mdx, model-capability-audit.mdx).
PRA-2 Resolve/justify architecture scripts/check-docs-published-routes.ts:1 Verify fern/docs.yml contains redirects for all deleted inference pages to their new published route equivalents. Run 'npm run docs' and 'node scripts/check-docs-published-routes.ts' to validate.
PRA-3 Resolve/justify scope docs/about/release-notes.mdx:1 Run 'npm run docs' followed by 'node scripts/check-docs-published-routes.ts' to validate all release-notes inference links resolve to published routes. Fix any broken links.
PRA-4 Improvement architecture test/inference-options-docs.test.ts:1 Rename test file to 'test/inference-docs-consolidation.test.ts' or 'test/inference-docs-structure.test.ts' to reflect its actual scope of validating the new inference documentation structure, navigation, and cross-references.
PRA-5 Resolve/justify tests src/lib/onboard/install-ollama-linux.ts:1 Add deterministic regression test covering Ollama Linux install partial failure and retry scenarios, verifying no ghost containers, volumes, or port bindings remain after interruption and retry converges to clean state.
PRA-6 Resolve/justify tests src/lib/onboard/model-router-python.ts:1 Add deterministic regression test covering model router onboarding status verification against independently probed gateway route and sandbox inference connectivity.
PRA-7 Resolve/justify tests src/lib/onboard/install-ollama-linux.ts:1 Add deterministic regression test covering cleanup path on install-ollama-linux.ts and model-router-python.ts, verifying unrelated sandbox metadata and resources are preserved.

🚨 Required before merge

Address these before merging unless a maintainer explicitly overrides the advisor with rationale.

PRA-1 Required — SKILL.md inference mapping table does not cover new focused inference doc pages

  • Location: .agents/skills/nemoclaw-contributor-update-docs/SKILL.md:85
  • Category: scope
  • Problem: The contributor skill's 'Code area -> Likely doc page(s)' table has only one row for 'Inference-related changes' pointing to 'docs/inference/how-inference-routing-works.mdx' with a note to update the focused page that owns the behavior. The new inference restructure created 26 focused pages across 6 navigation sections (learn-and-choose, hosted-inference, local-inference, custom-endpoints, manage-inference, validate-inference). Contributors using the automated doc-update skill may not discover the correct focused page for a given inference change, leading to stale or misplaced documentation.
  • Impact: Future inference-related code changes may not trigger correct doc updates; contributors guided by the skill could update the wrong page or miss pages entirely, causing documentation drift.
  • Required action: Expand the SKILL.md mapping table with explicit rows for each inference sub-area (e.g., 'Choose provider/model' -> choose-inference-provider.mdx, choose-model.mdx; 'Hosted provider setup' -> use-nvidia-endpoints.mdx, use-openrouter.mdx, use-openai.mdx, use-anthropic.mdx, use-google-gemini.mdx, set-up-model-router.mdx; 'Local inference' -> choose-local-inference-server.mdx, set-up-ollama.mdx, set-up-vllm.mdx, set-up-nvidia-nim.mdx; 'Custom endpoints' -> set-up-openai-compatible-endpoint.mdx, set-up-anthropic-compatible-endpoint.mdx, choose-compatible-inference-api.mdx, custom-endpoint-security.mdx; 'Inference management' -> view-active-inference-route.mdx, switch-models.mdx, switch-providers.mdx, configure-model-limits.mdx, configure-model-capabilities.mdx, configure-inference-timeouts.mdx; 'Inference validation' -> understand-provider-validation.mdx, verify-inference-route.mdx, model-capability-audit.mdx).
  • Expected follow-up: Fix before merge or get explicit maintainer override.
  • Verification: Compare SKILL.md mapping table rows against actual file list in docs/inference/*.mdx and docs/index.yml navigation sections for inference.
  • Missing regression test: Add test that validates SKILL.md mappings cover all files in docs/inference/*.mdx by cross-referencing with docs/index.yml nav entries.
  • Done when: The required change is committed and verification passes: Compare SKILL.md mapping table rows against actual file list in docs/inference/*.mdx and docs/index.yml navigation sections for inference.
  • Evidence: SKILL.md diff shows line 85 changed from 'inference-options.mdx' to 'how-inference-routing-works.mdx' with note Context tool shows 26 new inference pages across 6 nav sections Prior review PRA-1 flagged this exact risk
Review findings by urgency: 1 required fix, 5 items to resolve/justify, 1 in-scope improvement

⚠️ 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-2 Resolve/justify — Redirect validation for deleted inference pages not explicitly verified

  • Location: scripts/check-docs-published-routes.ts:1
  • Category: architecture
  • Problem: The PR deletes 15+ inference documentation files (inference-options.mdx, switch-inference-providers.mdx, use-local-inference.mdx, local-compatible-inference-setup.mdx, tool-calling-reliability.mdx, switch-models.mdx, switch-providers.mdx, and others). Fern redirects in fern/docs.yml must map these deleted source routes to new published routes. The checker validates redirects but the review has not confirmed all legacy routes have correct redirects.
  • Impact: Users and AI agents following old links (bookmarks, search results, external references) will hit 404s if redirects are missing or incorrect. Contributor onboarding skill may guide to deleted paths.
  • Recommended action: Verify fern/docs.yml contains redirects for all deleted inference pages to their new published route equivalents. Run 'npm run docs' and 'node scripts/check-docs-published-routes.ts' to validate.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Check fern/docs.yml redirects array for entries mapping old inference routes (e.g., /inference/inference-options, /inference/use-local-inference, /inference/switch-inference-providers) to new routes under /user-guide/*/inference/learn-and-choose/, /local-inference/, /manage-inference/, /validate-inference/. Run the published-route checker.
  • Missing regression test: Add CI step that fails on any broken redirect in fern/docs.yml for inference routes; the existing check-docs-published-routes.ts validates this but should be confirmed to run in CI.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Check fern/docs.yml redirects array for entries mapping old inference routes (e.g., /inference/inference-options, /inference/use-local-inference, /inference/switch-inference-providers) to new routes under /user-guide/*/inference/learn-and-choose/, /local-inference/, /manage-inference/, /validate-inference/. Run the published-route checker.
  • Evidence: Diff shows 15+ deleted inference doc files fern/docs.yml redirects updated in this PR (100 lines changed) Prior review PRA-2 flagged cross-reference integrity risk check-docs-published-routes.ts findBrokenPublishedRedirects validates inference redirects

PRA-3 Resolve/justify — Release notes links updated to new inference doc paths but not all verified against published routes

  • Location: docs/about/release-notes.mdx:1
  • Category: scope
  • Problem: Release notes for v0.0.55 through v0.0.79 (80 lines changed) have been updated to reference new inference doc paths (e.g., 'Choose an Inference Provider' instead of 'Inference Options', 'Choose a Local Inference Server' instead of 'Use Ollama for Local Inference' / 'Set Up Self-Hosted Inference Servers'). The checker validates release-notes inference links, but manual confirmation that all 20+ updated links resolve to actual published Fern routes is needed.
  • Impact: Release note readers clicking 'For more information' links may hit 404s if any link target is incorrect or the published route differs from the written link.
  • Recommended action: Run 'npm run docs' followed by 'node scripts/check-docs-published-routes.ts' to validate all release-notes inference links resolve to published routes. Fix any broken links.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Run the published-route checker which includes release-notes inference link validation; examine output for violations.
  • Missing regression test: The existing check-docs-published-routes.ts already guards release-notes inference links; ensure it runs in CI and passes.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Run the published-route checker which includes release-notes inference link validation; examine output for violations.
  • Evidence: Diff shows 80 lines changed in release-notes.mdx with updated inference doc links check-docs-published-routes.ts includes findBrokenPublishedInferenceRoutes for about/release-notes.mdx Prior review PRA-3 flagged cross-reference integrity risk

PRA-5 Resolve/justify — Missing regression test for lifecycle-state invariant: partial failure and retry converge without ghost resources or stale ports

  • Location: src/lib/onboard/install-ollama-linux.ts:1
  • Category: tests
  • Problem: The riskPlan identifies 'lifecycle-state' family with invariant 'partial failure and retry converge without ghost resources or stale ports' matched to install-ollama-linux.ts. No checked-in test coverage visible in diff for this invariant on the changed file.
  • Impact: Onboarding partial failures (e.g., Ollama install interrupted, network timeout, Docker pull failure) could leave ghost resources, stale ports, or inconsistent state that breaks subsequent retry or fresh onboarding.
  • Recommended action: Add deterministic regression test covering Ollama Linux install partial failure and retry scenarios, verifying no ghost containers, volumes, or port bindings remain after interruption and retry converges to clean state.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Search test/ for tests covering install-ollama-linux.ts partial failure paths; check if onboard-repair/onboard-resume jobs exercise this invariant.
  • Missing regression test: Add test in test/onboard-repair.test.ts or test/onboard-resume.test.ts covering Ollama Linux install interruption at each phase (download, container start, health check) and verify clean retry convergence.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Search test/ for tests covering install-ollama-linux.ts partial failure paths; check if onboard-repair/onboard-resume jobs exercise this invariant.
  • Evidence: riskPlan matches install-ollama-linux.ts to lifecycle-state family Invariant: 'partial failure and retry converge without ghost resources or stale ports' Required jobs: onboard-repair, onboard-resume (auto-enabled) No test changes for install-ollama-linux.ts visible in diff

PRA-6 Resolve/justify — Missing regression test for lifecycle-state invariant: status agrees with independently probed gateway and sandbox state

  • Location: src/lib/onboard/model-router-python.ts:1
  • Category: tests
  • Problem: The riskPlan identifies 'lifecycle-state' family with invariant 'status agrees with independently probed gateway and sandbox state' matched to model-router-python.ts. No checked-in test coverage visible in diff for this invariant on the changed file.
  • Impact: Model router onboarding could report success while gateway route or sandbox state is actually misconfigured, leading to silent inference failures when agents attempt to use inference.local.
  • Recommended action: Add deterministic regression test covering model router onboarding status verification against independently probed gateway route and sandbox inference connectivity.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Search test/ for tests covering model-router-python.ts status verification; check if onboard-resume job exercises status/gateway agreement.
  • Missing regression test: Add test in test/onboard-resume.test.ts or test/model-router.test.ts verifying model router onboarding reports status only after independent gateway route probe and sandbox inference.local health check both succeed.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Search test/ for tests covering model-router-python.ts status verification; check if onboard-resume job exercises status/gateway agreement.
  • Evidence: riskPlan matches model-router-python.ts to lifecycle-state family Invariant: 'status agrees with independently probed gateway and sandbox state' Required jobs: onboard-repair, onboard-resume (auto-enabled) No test changes for model-router-python.ts visible in diff

PRA-7 Resolve/justify — Missing regression test for lifecycle-state invariant: cleanup preserves unrelated sandboxes and removes only owned resources

  • Location: src/lib/onboard/install-ollama-linux.ts:1
  • Category: tests
  • Problem: The riskPlan identifies 'lifecycle-state' family with invariant 'cleanup preserves unrelated sandboxes and removes only owned resources' matched to install-ollama-linux.ts (and model-router-python.ts). No checked-in test coverage visible in diff for this invariant on the changed files.
  • Impact: Onboarding cleanup or repair could incorrectly remove unrelated sandbox metadata, volumes, or state, causing data loss for other sandboxes.
  • Recommended action: Add deterministic regression test covering cleanup path on install-ollama-linux.ts and model-router-python.ts, verifying unrelated sandbox metadata and resources are preserved.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Search test/ for tests covering cleanup behavior on these onboarding files; check if onboard-repair job exercises selective cleanup.
  • Missing regression test: Add test in test/onboard-repair.test.ts covering cleanup on partial failure for both files, asserting unrelated sandbox registry entries, volumes, and state remain intact.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Search test/ for tests covering cleanup behavior on these onboarding files; check if onboard-repair job exercises selective cleanup.
  • Evidence: riskPlan matches both onboarding files to lifecycle-state family Invariant: 'cleanup preserves unrelated sandboxes and removes only owned resources' Required jobs: onboard-repair, onboard-resume (auto-enabled) No test changes for these files visible in diff

💡 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.

PRA-4 Improvement — Test file named after deleted documentation file

  • Location: test/inference-options-docs.test.ts:1
  • Category: architecture
  • Problem: The test file 'test/inference-options-docs.test.ts' retains its name referencing the deleted 'docs/inference/inference-options.mdx' file. The test scope now validates the new inference documentation structure, navigation, and cross-references, not the old inference-options page.
  • Impact: Misleading test file name obscures the test's actual purpose and makes it harder to find related tests. Future maintainers may not realize this test covers the consolidated inference docs structure.
  • Suggested action: Rename test file to 'test/inference-docs-consolidation.test.ts' or 'test/inference-docs-structure.test.ts' to reflect its actual scope of validating the new inference documentation structure, navigation, and cross-references.
  • Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
  • Verification: Check test file name and its describe block content to confirm it validates new inference docs structure.
  • Missing regression test: No new test needed; rename is a maintenance improvement.
  • Done when: The local improvement is applied, or the PR notes why it should be deferred.
  • Evidence: Diff shows test/inference-options-docs.test.ts modified (251 lines changed) but not renamed Prior review PRA-4 flagged this naming mismatch File content now tests new inference doc structure per commit 'test(docs): keep fence parsing linear'
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 — Run the `onboard-repair` E2E job for Onboarding and sandbox state must converge across persisted metadata, reported status, and the live runtime. Matched files: `src/lib/onboard/install-ollama-linux.ts`, `src/lib/onboard/model-router-python.ts`.. Deterministic regression risks require live validation: lifecycle-state. Deterministic regression risks require live validation: lifecycle-state family with 3 invariants matched to install-ollama-linux.ts and model-router-python.ts. Required jobs onboard-repair and onboard-resume are validation floor, not checked-in tests. No unit/mocked tests cover the 3 invariants for these files.
  • PRA-T2 Runtime validation — Run the `onboard-resume` E2E job for Onboarding and sandbox state must converge across persisted metadata, reported status, and the live runtime. Matched files: `src/lib/onboard/install-ollama-linux.ts`, `src/lib/onboard/model-router-python.ts`.. Deterministic regression risks require live validation: lifecycle-state. Deterministic regression risks require live validation: lifecycle-state family with 3 invariants matched to install-ollama-linux.ts and model-router-python.ts. Required jobs onboard-repair and onboard-resume are validation floor, not checked-in tests. No unit/mocked tests cover the 3 invariants for these files.
  • PRA-T3 Missing regression test for lifecycle-state invariant: partial failure and retry converge without ghost resources or stale ports — Add deterministic regression test covering Ollama Linux install partial failure and retry scenarios, verifying no ghost containers, volumes, or port bindings remain after interruption and retry converges to clean state.
  • PRA-T4 Missing regression test for lifecycle-state invariant: status agrees with independently probed gateway and sandbox state — Add deterministic regression test covering model router onboarding status verification against independently probed gateway route and sandbox inference connectivity.
  • PRA-T5 Missing regression test for lifecycle-state invariant: cleanup preserves unrelated sandboxes and removes only owned resources — Add deterministic regression test covering cleanup path on install-ollama-linux.ts and model-router-python.ts, verifying unrelated sandbox metadata and resources are preserved.
  • PRA-T6 Acceptance clause — Redirect the previous inference URLs and migrate references throughout the docs to the nested published routes — add test evidence or identify existing coverage. fern/docs.yml redirects updated (100 lines) for deleted routes; 40+ doc files updated with new inference links; but not all legacy routes explicitly verified (F-002)
Since last review details

Current findings, using the urgency labels above:

PRA-1 Required — SKILL.md inference mapping table does not cover new focused inference doc pages

  • Location: .agents/skills/nemoclaw-contributor-update-docs/SKILL.md:85
  • Category: scope
  • Problem: The contributor skill's 'Code area -> Likely doc page(s)' table has only one row for 'Inference-related changes' pointing to 'docs/inference/how-inference-routing-works.mdx' with a note to update the focused page that owns the behavior. The new inference restructure created 26 focused pages across 6 navigation sections (learn-and-choose, hosted-inference, local-inference, custom-endpoints, manage-inference, validate-inference). Contributors using the automated doc-update skill may not discover the correct focused page for a given inference change, leading to stale or misplaced documentation.
  • Impact: Future inference-related code changes may not trigger correct doc updates; contributors guided by the skill could update the wrong page or miss pages entirely, causing documentation drift.
  • Required action: Expand the SKILL.md mapping table with explicit rows for each inference sub-area (e.g., 'Choose provider/model' -> choose-inference-provider.mdx, choose-model.mdx; 'Hosted provider setup' -> use-nvidia-endpoints.mdx, use-openrouter.mdx, use-openai.mdx, use-anthropic.mdx, use-google-gemini.mdx, set-up-model-router.mdx; 'Local inference' -> choose-local-inference-server.mdx, set-up-ollama.mdx, set-up-vllm.mdx, set-up-nvidia-nim.mdx; 'Custom endpoints' -> set-up-openai-compatible-endpoint.mdx, set-up-anthropic-compatible-endpoint.mdx, choose-compatible-inference-api.mdx, custom-endpoint-security.mdx; 'Inference management' -> view-active-inference-route.mdx, switch-models.mdx, switch-providers.mdx, configure-model-limits.mdx, configure-model-capabilities.mdx, configure-inference-timeouts.mdx; 'Inference validation' -> understand-provider-validation.mdx, verify-inference-route.mdx, model-capability-audit.mdx).
  • Expected follow-up: Fix before merge or get explicit maintainer override.
  • Verification: Compare SKILL.md mapping table rows against actual file list in docs/inference/*.mdx and docs/index.yml navigation sections for inference.
  • Missing regression test: Add test that validates SKILL.md mappings cover all files in docs/inference/*.mdx by cross-referencing with docs/index.yml nav entries.
  • Done when: The required change is committed and verification passes: Compare SKILL.md mapping table rows against actual file list in docs/inference/*.mdx and docs/index.yml navigation sections for inference.
  • Evidence: SKILL.md diff shows line 85 changed from 'inference-options.mdx' to 'how-inference-routing-works.mdx' with note Context tool shows 26 new inference pages across 6 nav sections Prior review PRA-1 flagged this exact risk

PRA-2 Resolve/justify — Redirect validation for deleted inference pages not explicitly verified

  • Location: scripts/check-docs-published-routes.ts:1
  • Category: architecture
  • Problem: The PR deletes 15+ inference documentation files (inference-options.mdx, switch-inference-providers.mdx, use-local-inference.mdx, local-compatible-inference-setup.mdx, tool-calling-reliability.mdx, switch-models.mdx, switch-providers.mdx, and others). Fern redirects in fern/docs.yml must map these deleted source routes to new published routes. The checker validates redirects but the review has not confirmed all legacy routes have correct redirects.
  • Impact: Users and AI agents following old links (bookmarks, search results, external references) will hit 404s if redirects are missing or incorrect. Contributor onboarding skill may guide to deleted paths.
  • Recommended action: Verify fern/docs.yml contains redirects for all deleted inference pages to their new published route equivalents. Run 'npm run docs' and 'node scripts/check-docs-published-routes.ts' to validate.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Check fern/docs.yml redirects array for entries mapping old inference routes (e.g., /inference/inference-options, /inference/use-local-inference, /inference/switch-inference-providers) to new routes under /user-guide/*/inference/learn-and-choose/, /local-inference/, /manage-inference/, /validate-inference/. Run the published-route checker.
  • Missing regression test: Add CI step that fails on any broken redirect in fern/docs.yml for inference routes; the existing check-docs-published-routes.ts validates this but should be confirmed to run in CI.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Check fern/docs.yml redirects array for entries mapping old inference routes (e.g., /inference/inference-options, /inference/use-local-inference, /inference/switch-inference-providers) to new routes under /user-guide/*/inference/learn-and-choose/, /local-inference/, /manage-inference/, /validate-inference/. Run the published-route checker.
  • Evidence: Diff shows 15+ deleted inference doc files fern/docs.yml redirects updated in this PR (100 lines changed) Prior review PRA-2 flagged cross-reference integrity risk check-docs-published-routes.ts findBrokenPublishedRedirects validates inference redirects

PRA-3 Resolve/justify — Release notes links updated to new inference doc paths but not all verified against published routes

  • Location: docs/about/release-notes.mdx:1
  • Category: scope
  • Problem: Release notes for v0.0.55 through v0.0.79 (80 lines changed) have been updated to reference new inference doc paths (e.g., 'Choose an Inference Provider' instead of 'Inference Options', 'Choose a Local Inference Server' instead of 'Use Ollama for Local Inference' / 'Set Up Self-Hosted Inference Servers'). The checker validates release-notes inference links, but manual confirmation that all 20+ updated links resolve to actual published Fern routes is needed.
  • Impact: Release note readers clicking 'For more information' links may hit 404s if any link target is incorrect or the published route differs from the written link.
  • Recommended action: Run 'npm run docs' followed by 'node scripts/check-docs-published-routes.ts' to validate all release-notes inference links resolve to published routes. Fix any broken links.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Run the published-route checker which includes release-notes inference link validation; examine output for violations.
  • Missing regression test: The existing check-docs-published-routes.ts already guards release-notes inference links; ensure it runs in CI and passes.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Run the published-route checker which includes release-notes inference link validation; examine output for violations.
  • Evidence: Diff shows 80 lines changed in release-notes.mdx with updated inference doc links check-docs-published-routes.ts includes findBrokenPublishedInferenceRoutes for about/release-notes.mdx Prior review PRA-3 flagged cross-reference integrity risk

PRA-4 Improvement — Test file named after deleted documentation file

  • Location: test/inference-options-docs.test.ts:1
  • Category: architecture
  • Problem: The test file 'test/inference-options-docs.test.ts' retains its name referencing the deleted 'docs/inference/inference-options.mdx' file. The test scope now validates the new inference documentation structure, navigation, and cross-references, not the old inference-options page.
  • Impact: Misleading test file name obscures the test's actual purpose and makes it harder to find related tests. Future maintainers may not realize this test covers the consolidated inference docs structure.
  • Suggested action: Rename test file to 'test/inference-docs-consolidation.test.ts' or 'test/inference-docs-structure.test.ts' to reflect its actual scope of validating the new inference documentation structure, navigation, and cross-references.
  • Expected follow-up: Prefer a current-PR fix when local to changed code; defer only with rationale or linked follow-up.
  • Verification: Check test file name and its describe block content to confirm it validates new inference docs structure.
  • Missing regression test: No new test needed; rename is a maintenance improvement.
  • Done when: The local improvement is applied, or the PR notes why it should be deferred.
  • Evidence: Diff shows test/inference-options-docs.test.ts modified (251 lines changed) but not renamed Prior review PRA-4 flagged this naming mismatch File content now tests new inference doc structure per commit 'test(docs): keep fence parsing linear'

PRA-5 Resolve/justify — Missing regression test for lifecycle-state invariant: partial failure and retry converge without ghost resources or stale ports

  • Location: src/lib/onboard/install-ollama-linux.ts:1
  • Category: tests
  • Problem: The riskPlan identifies 'lifecycle-state' family with invariant 'partial failure and retry converge without ghost resources or stale ports' matched to install-ollama-linux.ts. No checked-in test coverage visible in diff for this invariant on the changed file.
  • Impact: Onboarding partial failures (e.g., Ollama install interrupted, network timeout, Docker pull failure) could leave ghost resources, stale ports, or inconsistent state that breaks subsequent retry or fresh onboarding.
  • Recommended action: Add deterministic regression test covering Ollama Linux install partial failure and retry scenarios, verifying no ghost containers, volumes, or port bindings remain after interruption and retry converges to clean state.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Search test/ for tests covering install-ollama-linux.ts partial failure paths; check if onboard-repair/onboard-resume jobs exercise this invariant.
  • Missing regression test: Add test in test/onboard-repair.test.ts or test/onboard-resume.test.ts covering Ollama Linux install interruption at each phase (download, container start, health check) and verify clean retry convergence.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Search test/ for tests covering install-ollama-linux.ts partial failure paths; check if onboard-repair/onboard-resume jobs exercise this invariant.
  • Evidence: riskPlan matches install-ollama-linux.ts to lifecycle-state family Invariant: 'partial failure and retry converge without ghost resources or stale ports' Required jobs: onboard-repair, onboard-resume (auto-enabled) No test changes for install-ollama-linux.ts visible in diff

PRA-6 Resolve/justify — Missing regression test for lifecycle-state invariant: status agrees with independently probed gateway and sandbox state

  • Location: src/lib/onboard/model-router-python.ts:1
  • Category: tests
  • Problem: The riskPlan identifies 'lifecycle-state' family with invariant 'status agrees with independently probed gateway and sandbox state' matched to model-router-python.ts. No checked-in test coverage visible in diff for this invariant on the changed file.
  • Impact: Model router onboarding could report success while gateway route or sandbox state is actually misconfigured, leading to silent inference failures when agents attempt to use inference.local.
  • Recommended action: Add deterministic regression test covering model router onboarding status verification against independently probed gateway route and sandbox inference connectivity.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Search test/ for tests covering model-router-python.ts status verification; check if onboard-resume job exercises status/gateway agreement.
  • Missing regression test: Add test in test/onboard-resume.test.ts or test/model-router.test.ts verifying model router onboarding reports status only after independent gateway route probe and sandbox inference.local health check both succeed.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Search test/ for tests covering model-router-python.ts status verification; check if onboard-resume job exercises status/gateway agreement.
  • Evidence: riskPlan matches model-router-python.ts to lifecycle-state family Invariant: 'status agrees with independently probed gateway and sandbox state' Required jobs: onboard-repair, onboard-resume (auto-enabled) No test changes for model-router-python.ts visible in diff

PRA-7 Resolve/justify — Missing regression test for lifecycle-state invariant: cleanup preserves unrelated sandboxes and removes only owned resources

  • Location: src/lib/onboard/install-ollama-linux.ts:1
  • Category: tests
  • Problem: The riskPlan identifies 'lifecycle-state' family with invariant 'cleanup preserves unrelated sandboxes and removes only owned resources' matched to install-ollama-linux.ts (and model-router-python.ts). No checked-in test coverage visible in diff for this invariant on the changed files.
  • Impact: Onboarding cleanup or repair could incorrectly remove unrelated sandbox metadata, volumes, or state, causing data loss for other sandboxes.
  • Recommended action: Add deterministic regression test covering cleanup path on install-ollama-linux.ts and model-router-python.ts, verifying unrelated sandbox metadata and resources are preserved.
  • Expected follow-up: Resolve in this PR or explain why the risk is acceptable.
  • Verification: Search test/ for tests covering cleanup behavior on these onboarding files; check if onboard-repair job exercises selective cleanup.
  • Missing regression test: Add test in test/onboard-repair.test.ts covering cleanup on partial failure for both files, asserting unrelated sandbox registry entries, volumes, and state remain intact.
  • Done when: The risk is fixed or explicitly justified in the PR. Verification: Search test/ for tests covering cleanup behavior on these onboarding files; check if onboard-repair job exercises selective cleanup.
  • Evidence: riskPlan matches both onboarding files to lifecycle-state family Invariant: 'cleanup preserves unrelated sandboxes and removes only owned resources' Required jobs: onboard-repair, onboard-resume (auto-enabled) No test changes for these files visible in diff

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.

Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
@miyoungc
miyoungc marked this pull request as ready for review July 10, 2026 21:44
@miyoungc
miyoungc marked this pull request as draft July 10, 2026 21:53

@wmanning-docker wmanning-docker left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the nested inference docs split. I found a blocking route issue for the Deep Agents variant:

  • fern/docs.yml redirects /user-guide/deepagents/inference/use-local-inference to /user-guide/deepagents/inference/local-inference/set-up-ollama, but the Deep Agents navigation intentionally does not publish set-up-ollama (only vLLM/NIM under Local Inference). That legacy Deep Agents URL will redirect to a non-published route/404. Please make the :variant redirect conditional or add an explicit Deep Agents redirect to /user-guide/deepagents/inference/local-inference (or another published Deep Agents page).
  • The shared release notes now link to ../inference/local-inference/set-up-ollama in entries such as v0.0.79/v0.0.78. When rendered for Deep Agents, those links also resolve to the same unpublished Deep Agents Ollama route. Please wrap Ollama-only references in AgentOnly or point shared text at the published Local Inference landing page.

I verified with the published route index: the generated Deep Agents release notes produce unresolved /user-guide/deepagents/inference/local-inference/set-up-ollama links.

miyoungc added 4 commits July 10, 2026 14:58
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
@miyoungc
miyoungc marked this pull request as ready for review July 10, 2026 23:08
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
@miyoungc
miyoungc marked this pull request as draft July 10, 2026 23:21

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (2)
test/check-docs-published-routes.test.ts (1)

117-135: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Cover destination-only variant expansion.

The fixture places :variant in both the redirect source and destination, so it does not verify redirects with a fixed source and variant-specific destination. Add that behavioral case to prevent regressions where only one side is expanded.

As per path instructions, keep the test focused on observable route-validation behavior rather than implementation details.

🤖 Prompt for 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.

In `@test/check-docs-published-routes.test.ts` around lines 117 - 135, Extend the
test “validates variant redirect destinations independently” with a redirect
whose source is fixed and whose destination contains :variant, then assert
findBrokenPublishedRedirects reports the expected expanded destination and
variant. Keep the assertion focused on observable validation output and preserve
the existing source-and-destination variant coverage.

Source: Path instructions

test/inference-options-docs.test.ts (1)

222-227: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick win

Cover equivalent --host syntax in the bind-address test.

The current assertion misses forms such as --host=0.0.0.0, allowing a non-loopback example to regress while the test still passes. Extract the documented --host values and assert that every value is 127.0.0.1.

Proposed test adjustment
-    expect(markdown).toContain("--host 127.0.0.1");
-    expect(markdown).not.toContain("--host 0.0.0.0");
+    const hostValues = [...markdown.matchAll(/--host(?:=|\s+)([^\s`]+)/g)].map(
+      ([, value]) => value,
+    );
+    expect(hostValues).toEqual(["127.0.0.1"]);
🤖 Prompt for 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.

In `@test/inference-options-docs.test.ts` around lines 222 - 227, Update the
loopback bind test in the test named "uses a loopback-only bind for the local
vLLM server example" to extract host values from both `--host VALUE` and
`--host=VALUE` syntax, then assert every extracted value equals `127.0.0.1`
instead of relying on substring checks.

Source: Path instructions

🤖 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 `@scripts/check-docs-published-routes.ts`:
- Around line 290-297: Update findBrokenPublishedInferenceRoutes to match both
inference section roots and nested routes: accept resolved paths ending with
“/inference” as well as paths containing “/inference/”, preserving the existing
filtering behavior.

---

Nitpick comments:
In `@test/check-docs-published-routes.test.ts`:
- Around line 117-135: Extend the test “validates variant redirect destinations
independently” with a redirect whose source is fixed and whose destination
contains :variant, then assert findBrokenPublishedRedirects reports the expected
expanded destination and variant. Keep the assertion focused on observable
validation output and preserve the existing source-and-destination variant
coverage.

In `@test/inference-options-docs.test.ts`:
- Around line 222-227: Update the loopback bind test in the test named "uses a
loopback-only bind for the local vLLM server example" to extract host values
from both `--host VALUE` and `--host=VALUE` syntax, then assert every extracted
value equals `127.0.0.1` instead of relying on substring checks.
🪄 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: 0a02b5e6-9a48-4367-a19b-c5cd4a104043

📥 Commits

Reviewing files that changed from the base of the PR and between ef3e95f and 793f480.

📒 Files selected for processing (15)
  • .agents/skills/nemoclaw-contributor-update-docs/SKILL.md
  • docs/about/release-notes.mdx
  • docs/index.yml
  • docs/inference/choose-local-inference-server.mdx
  • docs/inference/how-inference-routing-works.mdx
  • docs/inference/set-up-model-router.mdx
  • docs/inference/set-up-nvidia-nim.mdx
  • docs/inference/set-up-ollama.mdx
  • docs/inference/set-up-vllm.mdx
  • docs/inference/use-hermes-provider.mdx
  • docs/inference/use-openrouter.mdx
  • fern/docs.yml
  • scripts/check-docs-published-routes.ts
  • test/check-docs-published-routes.test.ts
  • test/inference-options-docs.test.ts
✅ Files skipped from review due to trivial changes (8)
  • docs/inference/use-hermes-provider.mdx
  • docs/inference/set-up-nvidia-nim.mdx
  • docs/inference/use-openrouter.mdx
  • docs/inference/set-up-model-router.mdx
  • docs/inference/set-up-vllm.mdx
  • .agents/skills/nemoclaw-contributor-update-docs/SKILL.md
  • docs/inference/how-inference-routing-works.mdx
  • docs/about/release-notes.mdx
🚧 Files skipped from review as they are similar to previous changes (3)
  • docs/index.yml
  • fern/docs.yml
  • docs/inference/set-up-ollama.mdx

Comment thread scripts/check-docs-published-routes.ts
miyoungc added 2 commits July 10, 2026 16:28
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
@miyoungc
miyoungc marked this pull request as ready for review July 10, 2026 23:35

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🤖 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/model-capability-audit.mdx`:
- Around line 159-168: Fix the provider link in the “Next Steps” section by
updating the link target in “Choose an Inference Provider” to
../choose-inference-provider, removing the nonexistent learn-and-choose segment
while preserving the link text.

In `@test/inference-options-docs.test.ts`:
- Around line 247-252: Prevent the troubleshooting section extraction in “keeps
tool-calling remediation canonical in troubleshooting” from using -1 as the
slice endpoint. After locating the next heading with indexOf, use the markdown
length when no subsequent “###” section exists, so the final section is captured
completely and the test does not silently truncate it.
🪄 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: bd24bc5d-d13d-4f57-ae4d-20985fde6656

📥 Commits

Reviewing files that changed from the base of the PR and between 793f480 and 2cf3485.

📒 Files selected for processing (30)
  • docs/about/release-notes.mdx
  • docs/configure-agents/progressive-tool-disclosure.mdx
  • docs/index.yml
  • docs/inference/choose-compatible-inference-api.mdx
  • docs/inference/choose-local-inference-server.mdx
  • docs/inference/choose-model.mdx
  • docs/inference/configure-inference-timeouts.mdx
  • docs/inference/custom-endpoint-security.mdx
  • docs/inference/how-inference-routing-works.mdx
  • docs/inference/model-capability-audit.mdx
  • docs/inference/set-up-anthropic-compatible-endpoint.mdx
  • docs/inference/set-up-nvidia-nim.mdx
  • docs/inference/set-up-ollama.mdx
  • docs/inference/set-up-openai-compatible-endpoint.mdx
  • docs/inference/set-up-vllm.mdx
  • docs/inference/switch-models.mdx
  • docs/inference/understand-provider-validation.mdx
  • docs/inference/use-anthropic.mdx
  • docs/inference/use-google-gemini.mdx
  • docs/inference/use-nvidia-endpoints.mdx
  • docs/inference/use-openai.mdx
  • docs/inference/use-openrouter.mdx
  • docs/inference/verify-inference-route.mdx
  • docs/inference/view-active-inference-route.mdx
  • docs/reference/architecture.mdx
  • docs/reference/commands.mdx
  • docs/reference/troubleshooting.mdx
  • fern/docs.yml
  • test/inference-options-docs.test.ts
  • test/model-capability-audit-doc.test.ts
✅ Files skipped from review due to trivial changes (22)
  • docs/inference/use-anthropic.mdx
  • docs/inference/choose-model.mdx
  • docs/inference/verify-inference-route.mdx
  • docs/configure-agents/progressive-tool-disclosure.mdx
  • docs/inference/use-openai.mdx
  • docs/reference/architecture.mdx
  • docs/reference/commands.mdx
  • docs/inference/choose-local-inference-server.mdx
  • docs/inference/configure-inference-timeouts.mdx
  • docs/inference/use-openrouter.mdx
  • docs/inference/switch-models.mdx
  • docs/inference/view-active-inference-route.mdx
  • docs/inference/use-google-gemini.mdx
  • docs/inference/use-nvidia-endpoints.mdx
  • docs/inference/how-inference-routing-works.mdx
  • docs/inference/understand-provider-validation.mdx
  • docs/inference/set-up-nvidia-nim.mdx
  • docs/inference/custom-endpoint-security.mdx
  • docs/inference/set-up-openai-compatible-endpoint.mdx
  • docs/inference/set-up-anthropic-compatible-endpoint.mdx
  • docs/about/release-notes.mdx
  • docs/inference/set-up-vllm.mdx
🚧 Files skipped from review as they are similar to previous changes (4)
  • test/model-capability-audit-doc.test.ts
  • docs/index.yml
  • fern/docs.yml
  • docs/inference/set-up-ollama.mdx

Comment thread docs/inference/model-capability-audit.mdx
Comment thread test/inference-options-docs.test.ts
Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
@miyoungc
miyoungc marked this pull request as draft July 10, 2026 23:46

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
test/inference-options-docs.test.ts (1)

151-153: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Closing-fence backreference doesn't allow longer closing fences.

^\1[ \t]*$ requires the closing fence to match the opening fence's exact string. CommonMark only requires the closing fence to have at least as many backticks/tildes as the opening one — a common pattern when nesting fenced examples with a longer outer fence. If any docs/inference/*.mdx file uses this pattern, the block won't be stripped and the compact-list-item test could false-positive on content that's actually inside a code fence.

🔧 Proposed fix
-  return markdown.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1[ \t]*$/gm, "");
+  return markdown.replace(/^(`{3,}|~{3,})[^\n]*\n[\s\S]*?^\1+[ \t]*$/gm, "");
🤖 Prompt for 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.

In `@test/inference-options-docs.test.ts` around lines 151 - 153, Update
stripFencedCodeBlocks to capture the fence character and opening length
separately, then accept a closing fence consisting of at least that many
matching backticks or tildes with only trailing spaces or tabs. Preserve support
for both fence styles and ensure longer closing fences are stripped correctly.
🤖 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.

Nitpick comments:
In `@test/inference-options-docs.test.ts`:
- Around line 151-153: Update stripFencedCodeBlocks to capture the fence
character and opening length separately, then accept a closing fence consisting
of at least that many matching backticks or tildes with only trailing spaces or
tabs. Preserve support for both fence styles and ensure longer closing fences
are stripped correctly.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 13e0fb7d-b3d0-469d-84a0-e0ee858e9aff

📥 Commits

Reviewing files that changed from the base of the PR and between 2cf3485 and fa50edc.

📒 Files selected for processing (2)
  • .coderabbit.yaml
  • test/inference-options-docs.test.ts

Signed-off-by: Miyoung Choi <miyoungc@nvidia.com>
@miyoungc
miyoungc marked this pull request as ready for review July 10, 2026 23:52
Signed-off-by: Carlos Villela <cvillela@nvidia.com>
@cv

cv commented Jul 11, 2026

Copy link
Copy Markdown
Collaborator

Follow-up review completed on b03063728.

  • Confirmed the human Deep Agents concern is already fixed: shared legacy local-inference redirects and release-note links now target the published local chooser, and the expanded redirect checker reports no variant violations.
  • Addressed the remaining valid review items: inference-root filtering, destination-only :variant coverage, superseded-link absence, --host= parsing, final-section slicing, and CommonMark longer closing fences.
  • Corrected a related vLLM topology regression found during review. The examples now remain reachable from both host validation and the OpenShell Docker bridge, with default-deny and bridge-subnet-only firewall guidance.
  • Kept the nested Fern route links that reviewers had resolved as flat source paths; those suggestions would have produced unpublished routes. Each thread now includes the route-specific rationale.
  • Did not run live onboarding E2E because the matched src/lib/onboard changes in this docs PR are comment/reference-only and the follow-up commit changes only docs, route validation, and tests.

Verification:

  • npx vitest run test/check-docs-published-routes.test.ts test/model-capability-audit-doc.test.ts test/inference-options-docs.test.ts — 25 passed.
  • npm run docs:check-routes — passed.
  • npm run docs — 0 errors; warnings are the unauthenticated Fern redirect check and the existing light-mode contrast warning.
  • Normal pre-commit, commit-msg, and pre-push hooks — passed.

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

cv commented Jul 11, 2026

Copy link
Copy Markdown
Collaborator

Advisor follow-up for the current head:

  • PRA-1 / PRA-T6: no code change. The mapping table is explicitly a starting point and already directs inference changes to the focused provider, model, setup, management, or validation owner. Enumerating every page would duplicate docs/index.yml, the canonical navigation inventory, and create a second list that can drift.
  • PRA-2 / PRA-3: resolved by evidence. npm run docs:check-routes validates all inference redirects and renders every release-note agent variant; it passes. npm run docs also passes with 0 errors.
  • PRA-4: deferred as rename-only churn. The existing file still contains the historical model task-fit coverage associated with its name, and renaming does not improve observable behavior.
  • PRA-5 through PRA-7 and PRA-T1 through PRA-T5: not applicable to this documentation PR. The matched src/lib/onboard/install-ollama-linux.ts and src/lib/onboard/model-router-python.ts diffs change documentation references in comments only; no lifecycle, status, cleanup, or runtime behavior changed. The checked-in route and docs tests cover the actual changed behavior.

@miyoungc
miyoungc merged commit 97cba6f into main Jul 11, 2026
46 checks passed
@miyoungc
miyoungc deleted the codex/nested-inference-toc branch July 11, 2026 01:20
Hadar301 pushed a commit to Hadar301/NemoClaw-OpenShift that referenced this pull request Jul 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area: docs Documentation, examples, guides, or docs build area: skills Skills, agent behaviors, prompts, or skill packaging

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants