docs: clarify documentation accuracy assurance

[miyoungc]

Summary

Clarify how the agentic documentation system assures documentation accuracy. The guide now separates build fidelity from semantic accuracy, defines parity-checked reference ownership, and makes NemoClaw's post-development documentation writer review explicit.

Changes

• Define three accuracy-assurance layers: source-derived parity tests, executable journey tests, and evidence-based review and sampling.
• Map the layers to current NemoClaw documentation tests while stating what each layer does and does not prove.
• Establish parity-checked reference pages as the documentation source of truth for downstream pages and agent guidance, with the CLI reference as the concrete example.
• Document how AGENTS.md requires an independent documentation writer review after development changes and before final handoff.
• Add documentation accuracy coverage to the implementation map and review-readiness checklist.

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: compiled CLI parity passed with 84 of 84 public command headings and bidirectional long-form flag parity; independent focused documentation validation passed 5 files with 86 tests, and maintainer validation passed 7 files with 97 tests.
• 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:
• 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: docs-updated
• Evidence: docs/resources/engineer-agentic-documentation.mdx; independently reviewed the completed page against the current repository and documentation instructions for reference ownership, grounding, accuracy, completeness, usability, writing rules, and documentation style. No findings remain.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

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 validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — bash test/e2e/e2e-cloud-experimental/check-docs.sh --only-cli passed with 84 of 84 command headings and bidirectional long-form flag parity; the independent focused Vitest run passed 5 files and 86 tests, and the maintainer focused run passed 7 files and 97 tests.
• Applicable broad gate passed — not applicable to this documentation-only change.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without errors (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

• Documentation
  • Improved guidance for maintaining accurate, consistent documentation.
  • Added layered accuracy checks covering source parity, executable journeys, and evidence-based review.
  • Clarified canonical ownership for reused facts and source-of-truth terms.
  • Expanded implementation mapping and canonical CLI documentation guidance.
  • Strengthened review-readiness requirements, including structured-fact ownership, independent review, and revalidation after updates.
  • Added documentation accuracy testing coverage.

[copy-pr-bot]

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

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 618d4d56-edb4-4c76-b84a-bfd3055572be

📥 Commits

Reviewing files that changed from the base of the PR and between 64c04a8 and 3147884.

📒 Files selected for processing (1)

• docs/resources/engineer-agentic-documentation.mdx

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

• docs/resources/engineer-agentic-documentation.mdx

---

📝 Walkthrough

Walkthrough

The documentation resource now defines canonical ownership for reused facts, layered documentation-accuracy testing, expanded implementation coverage, and review-readiness requirements.

Changes

Documentation accuracy governance

Layer / File(s)	Summary
Accuracy metadata and canonical ownership docs/resources/engineer-agentic-documentation.mdx	Agent metadata now includes documentation accuracy tests. Parity-checked reference pages own reused commands, flags, configuration keys, inventories, and support data.
Layered accuracy-assurance model docs/resources/engineer-agentic-documentation.mdx	The guidance distinguishes source-parity tests, executable journey tests, and evidence-based review and sampling. It states that no single automated gate proves corpus-wide semantic accuracy.
Implementation map and review readiness docs/resources/engineer-agentic-documentation.mdx	The implementation map adds canonical CLI documentation and accuracy-test coverage. Review readiness now includes independent review, revision-linked receipts, invalidation after new commits, and explicit accuracy coverage.

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

Possibly related PRs

• NVIDIA/NemoClaw#8166: Extends the documentation-governance framework introduced by this PR.
• NVIDIA/NemoClaw#8370: Adds related canonical documentation and accuracy-check guidance in other files.

🚥 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 documentation changes that clarify accuracy assurance.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/docs-accuracy-assurance

---

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

[github-actions]

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

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

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 terminology decisions differ; normalized E2E selections match; severity counts match.

5 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• evidence-based review at docs/resources/engineer-agentic-documentation.mdx:507: primary classified it as justified; the second opinion classified it as define.
• documentation writer review at docs/resources/engineer-agentic-documentation.mdx:507: selected only by the second-opinion lane as established.
• documentation source of truth at docs/resources/engineer-agentic-documentation.mdx:189: selected only by the second-opinion lane as define.
• source-derived parity test at docs/resources/engineer-agentic-documentation.mdx:505: selected only by the second-opinion lane as define.
• accuracy assurance at docs/resources/engineer-agentic-documentation.mdx:7: selected only by the second-opinion lane as define.

Second-opinion terminology and E2E selections are advisory. Live E2E does not run automatically for pull requests.

4 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• define — parity-checked reference at docs/resources/engineer-agentic-documentation.mdx:187: Define the term at first use through its ownership and parity-check conditions, as the changed text does.
• define — documentation accuracy at docs/resources/engineer-agentic-documentation.mdx:492: Retain the layered definition and name the evidence type for each accuracy claim.
• define — executable journey test at docs/resources/engineer-agentic-documentation.mdx:506: Retain the table definition that states the procedure coverage and evidence.
• justified — evidence-based review at docs/resources/engineer-agentic-documentation.mdx:507: Retain the modifier and its stated evidence because it distinguishes this layer from automated parity and journey testing.

E2E guidance

Advisory only. A maintainer can dispatch the default E2E suite against this exact revision.

Recommended E2E: None

Workflow run details

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

[apurvvkumaria]

CI classification: the Nemotron advisor lane stopped during its security-review stage because it emitted output before completing the required terminology read. The preserved artifact contains no code or documentation finding. Terra and all repository, documentation, DCO, security-scanning, and E2E-gate checks passed on the current branch. I started the one bounded failed-job retry for this confirmed advisor-protocol transient; no source change is indicated by the failure.

[apurvvkumaria]

Documentation review update: I corrected the two statements that described documentation work as starting alongside implementation. The page now matches the current repository policy: an independent documentation writer reviews completed development changes before final handoff. The correction is signed and GitHub-verified; npm run docs passed with zero errors, the focused documentation suite passed 107/107 tests, and an independent documentation writer found no remaining grounding, scope, usability, or style issues. The PR description and review receipt now refer to the validated commit.

[apurvvkumaria]

Maintainer update for validated commit 79c341fc7:

• Refreshed the branch from current main with a signed, DCO-compliant merge commit. The PR remains limited to docs/resources/engineer-agentic-documentation.mdx.
• Addressed the independent documentation review findings. Product-scope claims now name an accepted issue or accepted design decision as evidence, and the platform-table sentence now names NemoClaw as its actor.
• The final independent review reports docs-updated with no remaining findings across the OpenClaw, Hermes, and Deep Agents variants.
• npm run docs passed with 0 errors and 2 existing warnings. The CLI build passed, and the documentation reference matches all 83 public commands and long-form flags in both directions.
• Security review: PASS across all nine rubric categories. This documentation-only diff changes no executable code, dependencies, credentials, authentication, authorization, cryptography, workflows, policies, configuration, or runtime behavior. It introduces no new security boundary or regression in security evidence.
• Both new commits are GitHub-verified and include DCO declarations.

Fresh repository checks and automated reviews are now running. The merge freeze remains in effect; I did not merge this PR or write to main.

[apurvvkumaria]

Maintainer follow-up on the secondary advisor retry:

The one permitted retry repeated the advisor's external tool-order failure. Its four preserved warnings were reviewed against the current branch, repository policy, and live E2E suite; no code or documentation change is needed.

• F-001/F-002 overlook the repository's real runtime journey tests, including cloud onboarding, resume, credential rotation, snapshots, and sandbox operations. The table defines a separate executable assurance layer; the following text explicitly distinguishes documentation regression assertions and says to pair them with product-behavior tests. Renaming that layer would collapse two different forms of evidence.
• F-003 asks for review-receipt freshness behavior that this page already documents in the workflow section and repeats in Review Readiness. The workflow and its tests also enforce stale-receipt detection.
• F-004 conflates the mandatory documentation-review policy with the advisory automation that records its receipt. AGENTS.md requires the independent review before handoff; the advisory checker is observable evidence and is not the policy itself.

The primary high-confidence advisor completed with no findings, the independent documentation review completed with no findings, all required checks are green, and there are no unresolved review threads. I will not retry the failed secondary lane again for this branch revision. The PR remains unmerged under the release-tag freeze and still needs independent approval plus one final post-tag refresh.

[apurvvkumaria]

Release status update: v0.0.103 has been cut and the merge freeze is lifted. The documented advisor-provider failures remain non-actionable, all required repository gates are green, and there are no unresolved review threads. The remaining gate is independent approval; after approval, the branch will be reconciled with current main and revalidated through the normal protected merge path.

[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]

Note

GitHub couldn't provide a complete incremental comparison for this pull request, so CodeRabbit is performing a full review instead. This review may take a little longer.

[apurvvkumaria]

Maintainer update for current branch revision 3147884a4:

• Reconciled the branch cleanly with current main using a signed merge commit; the effective PR diff remains limited to docs/resources/engineer-agentic-documentation.mdx.
• The required independent documentation-writer review returned docs-updated with no actionable findings across the OpenClaw, Hermes, and Deep Agents variants.
• npm run docs passed with 0 errors and 2 existing warnings. CLI/reference parity passed for all 84 public commands with bidirectional long-form flag parity, and the focused seven-file documentation suite passed 121/121 tests.
• GitHub reports the reconciliation commit as Verified, and it includes the required DCO declaration. The PR description and documentation-review receipt have been refreshed.

Fresh repository checks and automated reviews are running. There are no unresolved review threads; independent approval remains the human merge gate. I did not merge the PR.

[apurvvkumaria]

Maintainer update for current branch revision a0355fb02:

• Reconciled the branch cleanly with current main using a signed merge commit; contributor attribution is preserved and the effective PR diff remains limited to docs/resources/engineer-agentic-documentation.mdx.
• The required independent documentation-writer review passed with no corrections after checking the full page, canonical ownership and routing, grounding, style, and the OpenClaw, Hermes, and Deep Agents generated variants.
• npm run docs passed route validation and Fern with 0 errors and 2 existing warnings. CLI/reference parity passed for all 84 public commands and bidirectional long-form flags. Independent focused validation passed 5 files/86 tests; maintainer focused validation passed 7 files/97 tests. Changed-file hooks and secret scanning also passed.
• The nine-category security review passed: this documentation-only diff introduces no runtime input, authentication, secret, dependency, data-exposure, cryptography, authorization, or fail-closed behavior change, and its assurance claims are grounded in current checked-in tests and source models.
• GitHub reports the new merge commit as Verified, it includes the required DCO declaration, and the documentation-review receipt now covers this branch revision.

Fresh repository checks and automated reviews are running. There are no unresolved review threads; independent approval remains the human merge gate. I have not merged the PR.

[apurvvkumaria]

CI follow-up: the installer-hash job failed before repository code ran because GitHub could not resolve an action download after repeated service errors. I reran only the failed job; it now passes, and every required repository check is green. No source change was needed.

[apurvvkumaria]

Approve — reviewed the current revision. The documentation accuracy layers, parity ownership model, independent writer-review policy, and implementation map align with current repository behavior. No blocking defect found; required checks are green.