fix(docs): preserve AgentOnly list spacing

[miyoungc]

Summary

Fixes generated agent-variant docs so adjacent Markdown list items stay adjacent when one or more neighboring <AgentOnly> blocks are filtered out.
The renderer now strips wrapper lines and skipped block contents without injecting replacement blank lines.

Changes

• Reworked scripts/sync-agent-variant-docs.ts to render <AgentOnly> blocks line-by-line instead of replacing skipped blocks with a newline.
• Added a regression test covering adjacent variant-only prerequisite list items.

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: This fixes docs build-tool rendering behavior and does not add a new user-facing workflow, command, page, or authoring rule.
• 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 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 --project integration test/agent-variant-docs.test.ts test/sync-agent-variant-docs.test.ts passed; npm run docs:check-agent-variants 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)
• 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

• Bug Fixes

  • Improved rendering of variant-specific content so matching sections keep their original line spacing.
  • Prevented extra blank lines from appearing between adjacent list items after filtering.
  • Ensured content for non-selected variants is no longer shown in the output.

• Tests

  • Added coverage for variant-based rendering to verify list formatting and content filtering.

[coderabbitai]

📝 Walkthrough

Walkthrough

Replaces the regex-based rendering of <AgentOnly variant="..."> blocks in the docs sync script with a line-by-line state machine that buffers inner content and conditionally emits it via a new agentOnlyVariantMatches helper. Adds a test verifying preserved list-item adjacency after variant filtering.

Changes

AgentOnly Variant Rendering Rewrite

Layer / File(s)	Summary
Line-by-line AgentOnly parser scripts/sync-agent-variant-docs.ts	Replaces the global regex replacement with a state machine that detects opening/closing <AgentOnly> tags, buffers inner lines, and adds agentOnlyVariantMatches to check the comma-separated variant attribute against the active variant before emitting buffered content.
List adjacency test test/agent-variant-docs.test.ts	Adds a test rendering the openclaw variant that asserts adjacent bullet lines remain adjacent (no extra blank line) after filtering, and confirms non-selected variant content is excluded.

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

🚥 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 clearly and concisely describes the main docs-rendering fix to preserve AgentOnly list spacing.
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 docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/agent-variant-spacing

---

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

[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 `@scripts/sync-agent-variant-docs.ts`:
- Around line 87-126: The fallback in stripAgentOnlyBlocksForVariant currently
emits an unclosed <AgentOnly> block verbatim, which can leak broken markup into
generated docs. Update stripAgentOnlyBlocksForVariant to treat a leftover
openBlock as a hard error instead of appending openBlock.openLine and buffered
lines, so malformed docs fail loudly during sync rather than shipping invalid
output.

🪄 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: 64236966-25be-4822-9120-ad63656f1834

📥 Commits

Reviewing files that changed from the base of the PR and between e2777f8 and 2f0a053.

📒 Files selected for processing (2)

• scripts/sync-agent-variant-docs.ts
• test/agent-variant-docs.test.ts

[github-actions]

PR Review Advisor — No blocking findings

Merge posture: No blocking advisor findings
Primary next action: No advisor follow-up required beyond maintainer review.
Open items: 0 required · 0 warnings · 0 suggestions · 0 test follow-ups

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]

PR Review Advisor (Nemotron Ultra) — No blocking findings

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

Workflow run details

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. No E2E is recommended. The deterministic risk plan requires no jobs, and the PR only changes documentation-generation tooling plus its unit tests. The diff cannot affect NemoClaw runtime/user flows such as onboarding, sandbox lifecycle, credentials, network/security policy, inference routing, deployment, or assistant behavior.

Optional E2E

• None.

New E2E recommendations

• None.

[github-actions]

E2E Target Recommendation

Required E2E targets: None
Optional E2E targets: None

Workflow run

Full E2E target advisor summary

E2E Target Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E targets

• None. No E2E target dispatch is required because the PR only changes agent-variant documentation generation logic and a non-E2E unit test; it does not modify test/e2e/, .github/workflows/e2e.yaml, or directly target-relevant E2E paths.

Optional E2E targets

• None.

Relevant changed files

• None.

[github-code-quality]

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 fix/agent-variant-sp... branch remains at 77%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 4df9fc2	fix/agent-variant-sp... 2f0a053	+/-
src/lib/inference/config.ts	98%	93%	-5%
src/lib/inferen...time-context.ts	96%	94%	-2%
src/lib/agent/onboard.ts	71%	70%	-1%
src/lib/agent/base-image.ts	82%	84%	+2%
src/lib/agent/t...ersion-drift.ts	88%	96%	+8%
src/lib/agent/b...availability.ts	63%	74%	+11%
src/lib/onboard/config-sync.ts	31%	46%	+15%
src/lib/agent/t...-enforcement.ts	75%	100%	+25%
src/lib/sandbox...rsion-scheme.ts	73%	100%	+27%

---

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

[cv]

Approved at exact head 2f0a05322b1e9d42c2929ffe68c409715b5ace60.

• The AgentOnly line-oriented renderer preserves adjacent list items, with focused regression coverage.
• All current checks are green; the three older cancelled check records are superseded by later successful runs of the same checks.
• Both exact-head review advisors recommend merge_as_is.
• The PR body has DCO and the commit is GitHub Verified.
• CodeRabbit's minor unclosed-block suggestion concerns preserved pre-existing malformed-input behavior, not a regression introduced here.

No live E2E target is required for this docs-generation fix.