fix(docs): keep agent variant check read-only

[HwangJohn]

Summary

docs:check-agent-variants now reports missing, stale, and out-of-sync generated agent-variant docs without writing or pruning files in --check mode. Normal sync mode still writes and prunes generated files through npm run docs:sync-agent-variants / npm run docs:prepare.

Changes

• Added a read-only check path for generated agent-variant pages.
• Kept the existing sync path responsible for creating, updating, and pruning generated pages.
• Added a process-level regression test proving --check does not rewrite stale contents, create missing generated pages, or delete stale generated pages.

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: docs tooling behavior only; published documentation and user-facing CLI behavior are unchanged.
• 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:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: no-docs-needed
• Evidence: At PR SHA 296395f, the focused integration test passed 1 file and 6 tests. npm run docs passed with the route checker OK, 0 errors, and 2 existing Fern warnings. npm run check:diff passed. The PR changes an internal docs-generation validation command and its tests; it does not change published documentation, user-facing CLI behavior, configuration, APIs, or supported product workflows.
• Agent: Codex Desktop

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: npx vitest run --project integration test/sync-agent-variant-docs.test.ts passed locally and on DGX Spark/Linux; npm run docs:prepare && npm run docs:check-agent-variants passed on DGX Spark/Linux; npm run typecheck:cli passed locally.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not run; focused docs-tooling change covered by targeted tests and npm run check:diff.
• 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: HwangJohn angelic805@gmail.com

Summary by CodeRabbit

• New Features

  • Added a check-only mode for generated agent-variant documentation.
  • Compares rendered outputs against existing generated pages and reports missing, out-of-sync, and stale files.
  • Returns a non-zero exit status and includes resolution guidance when discrepancies are found, without modifying the filesystem.

• Tests

  • Added integration-style coverage for the check mode using a temporary fixture repository, validating both a fully in-sync run and a failure run (missing/out-of-sync/stale).

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

📝 Walkthrough

Walkthrough

The sync script now provides a non-mutating --check mode that detects missing, stale, and out-of-sync generated documentation, reports discrepancies, and exits with status 1. Integration tests verify these behaviors in a temporary repository.

Changes

Generated documentation check

Layer / File(s)	Summary
Non-mutating generated file validation scripts/sync-agent-variant-docs.mts	The --check path compares expected and existing generated files, detects stale outputs, reports mismatches, and sets a failing exit code without writing or pruning files.
Integration coverage for check mode test/sync-agent-variant-docs.test.ts	Temporary repository fixtures execute the real command and verify synchronized success, mismatch reporting, exit status, preservation of existing files, and non-creation of missing outputs.

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

Sequence Diagram(s)

sequenceDiagram
  participant SyncScript
  participant GeneratedDocsFilesystem
  participant Process
  SyncScript->>GeneratedDocsFilesystem: Compare rendered files with generated outputs
  GeneratedDocsFilesystem-->>SyncScript: Report missing, out-of-sync, and stale files
  SyncScript->>Process: Set exit status to 1 when discrepancies exist

Loading

Suggested reviewers: cv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
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.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main change: agent variant docs check mode now stays read-only.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

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

Model lanes

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

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

E2E guidance

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

Recommended E2E: None

1 optional E2E recommendation

• docs-validation

Workflow run details

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

[wscurran]

✨ Thanks for the fix. The read-only check path for agent-variant docs is a clear improvement. Maintainers will review the regression test and check-mode behavior.

[miyoungc]

Thanks for the contribution. After reviewing the current behavior and its history more closely, I agree this addresses a real issue.

Today, the command named docs:check-agent-variants does more than check the generated documentation. It creates missing files, replaces outdated files, and deletes extra files. This is not expected behavior for a command named check: it should report whether the documentation is correct, not repair or delete files while inspecting them.

The documentation workflow now has two separate commands for these jobs:

• docs:check-agent-variants should report problems without changing files.
• docs:sync-agent-variants and docs:prepare should make the necessary changes.

This PR makes that separation clear and prevents the check command from unexpectedly changing or deleting local files.

One blocker remains: the new regression test fails on macOS because the temporary script path is represented differently by macOS and the Node.js module loader (/var/folders versus /private/var/folders). As a result, the test script does not actually run and the failing case incorrectly returns success. Please update the test to execute the script through its resolved path—for example, with realpathSync(fixtureScript)—and rerun the focused test using the repository’s Node 22 version on macOS.

With the macOS test corrected and current CI green, I would be open to accepting this change.

[miyoungc]

Suggested macOS portability fix for the new process-level tests. I applied these exact changes to this PR head and verified all 6 focused tests pass on macOS with Node 22.23.1.