docs: centralize documentation guidance

[miyoungc]

Summary

Simplifies documentation governance into a one-way authority flow with one owner for each concern. DORI routing now lives in docs/AGENTS.md, and explicit topology checks prevent guidance links from recreating cycles.

Changes

• Route repository instructions to docs/AGENTS.md, documentation procedures to docs/CONTRIBUTING.md, writing rules to WRITING.md, and terminology to the controlled word list.
• Move DORI capability detection and fallback routing into docs/AGENTS.md; keep docs/DORI_SETUP.md limited to explicit installation and configuration requests.
• Reduce the shared documentation-writing contract and task skills to downward links plus task-specific requirements.
• Remove the return link from the controlled word list to WRITING.md and add tests for the resulting acyclic authority graph.

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: No supported product behavior changed; documentation governance is the change.
• 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: An independent Codex Desktop documentation writer reviewed .agents/skills/_shared/controlled-words.md, .agents/skills/_shared/documentation-writing-review.md, .agents/skills/nemoclaw-contributor-create-pr/SKILL.md, .agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md, AGENTS.md, CONTRIBUTING.md, WRITING.md, docs/AGENTS.md, docs/CONTRIBUTING.md, docs/DORI_SETUP.md, docs/resources/engineer-agentic-documentation.mdx, and the topology assertions in test/maintainer-skills-policy.test.ts and test/skills-frontmatter.test.ts. The initial review found no findings after the return link from the controlled word list was removed and confirmed that DORI routing is owned by docs/AGENTS.md. After the requested reverts, an independent Codex Desktop documentation writer re-reviewed AGENTS.md and CONTRIBUTING.md, found no findings, confirmed that the restored links remain one-way, and reviewed the writing rules and documentation style. npm run docs passed with 0 errors and 1 existing warning; the targeted skills, policy, route, and link tests passed; normal hooks passed; and git diff --check passed.
• 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 — command/result or justification: test/skills-frontmatter.test.ts passed 30 of 30 tests; the targeted documentation-authority policy tests passed 2 of 2; and the route and link suites passed 45 of 45.
• 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) — Result: passed with 0 errors and 1 existing 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

  • Clarified documentation ownership, routing, review procedures, and contribution requirements.
  • Added guidance for claim accuracy, product naming, formatting, warnings, copyable commands, and agent-variant documentation.
  • Updated setup and engineering documentation references to the current style and contribution guides.
  • Simplified and consolidated documentation workflow instructions.

• Tests

  • Updated policy and routing checks to validate the revised documentation guidance and link relationships.

[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: 555163a1-d0c5-4d5f-8fbd-2bc83c6510cb

📥 Commits

Reviewing files that changed from the base of the PR and between 99cbcf5 and 6aae132.

📒 Files selected for processing (2)

• AGENTS.md
• CONTRIBUTING.md

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

• AGENTS.md

---

📝 Walkthrough

Walkthrough

The change reorganizes documentation guidance around docs/AGENTS.md, docs/CONTRIBUTING.md, WRITING.md, DORI routing, and the Documentation Writer Review Receipt procedure. It adds claim-accuracy rules, updates references, and revises policy tests.

Changes

Documentation governance

Layer / File(s)	Summary
Documentation authority contracts .agents/skills/_shared/*, .agents/skills/nemoclaw-*/SKILL.md, AGENTS.md, CONTRIBUTING.md, WRITING.md	Shared and repository guidance now routes documentation work to focused writing, contributor, and review-receipt procedures. WRITING.md adds claim-accuracy rules.
Documentation-agent workflow docs/AGENTS.md, docs/DORI_SETUP.md	Documentation-agent guidance now defines DORI routing, skill selection, editing prerequisites, execution requirements, and updated fallback links.
Public documentation rules and references docs/CONTRIBUTING.md, docs/resources/engineer-agentic-documentation.mdx	The contributor guide adds validation, variant, terminology, formatting, warning, and style-authority rules. The engineering documentation describes the separated control stack.
Policy and routing validation test/maintainer-skills-policy.test.ts, test/skills-frontmatter.test.ts	Tests validate changelog requirements, one-way documentation authority links, and routing to WRITING.md and docs/CONTRIBUTING.md.

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

Sequence Diagram(s)

sequenceDiagram
  participant DocumentationTask
  participant DocsAgents
  participant DORI
  participant DocsContributorGuide
  DocumentationTask->>DocsAgents: Read routing and workflow rules
  DocsAgents->>DORI: Detect host capabilities and apply fallback rules
  DORI->>DocsContributorGuide: Route public documentation work
  DocsAgents->>DocsContributorGuide: Apply procedures and verification

Loading

Possibly related PRs

• NVIDIA/NemoClaw#8374: Both changes update the documentation control stack and implementation map in docs/resources/engineer-agentic-documentation.mdx.
• NVIDIA/NemoClaw#8396: Both changes touch contributor skill routing and test/skills-frontmatter.test.ts.

Suggested reviewers: cv, jyaunches, apurvvkumaria

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/dedupe-doc-guidance

---

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

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8166.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): Failed after a partial review · low confidence · 0 blockers · 0 warnings · 0 suggestions

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

1 semantic terminology decision

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

• conflict — public-facing documentation at docs/CONTRIBUTING.md:8: Use the established term `user-facing documentation`, or define a concrete scope difference and apply each term consistently.

E2E guidance

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

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.

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

[apurvvkumaria]

Resolved the repository contract failure in the documentation-routing refactor.

• Restored the route from the shared documentation contract to the root PR requirements, which own fallback validation when normal hooks do not run.
• test/skills-frontmatter.test.ts passes 30 of 30 tests.
• npm run validate:pr passes.
• npm run docs completes with 0 errors and 2 warnings.
• An independent documentation writer reviewed all seven changed governance files and found no further content correction.
• The new commit is signed, includes a DCO declaration, and GitHub reports it as Verified.

This remains a documentation-governance change with no sensitive runtime path changes. The PR remains a draft; I did not change its review routing or readiness state.

[apurvvkumaria]

Follow-up: the transient advisor retry passed. All current required checks are green, all review threads are resolved, and approval is recorded. The PR remains a draft, so the author-controlled readiness decision is the only remaining merge gate; I have not changed that state.

[apurvvkumaria]

Merge-train status: all current checks pass and approval is present. The only remaining gate is the draft state, which requires the contributor to confirm the PR is ready for merge. I will re-audit and merge normally once it is marked ready.

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit 6aae132 in the codex/dedupe-doc-gui... branch remains at 96%, unchanged from commit 422fe95 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 6aae132 in the codex/dedupe-doc-gui... branch remains at 82%, unchanged from commit 422fe95 in the main branch.

---

_{Updated August 06, 2026 01:52 UTC}

[coderabbitai]

Actionable comments posted: 1

Caution

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

⚠️ Outside diff range comments (1)

AGENTS.md (1)

24-24: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win

Load the shared documentation contract in nemoclaw-contributor-onboard-messaging-channel.

This skill reviews and updates user-facing documentation but does not load .agents/skills/_shared/documentation-writing-review.md, WRITING.md, or docs/CONTRIBUTING.md. Add explicit routing before removing the global requirement.

🤖 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 `@AGENTS.md` at line 24, Update the
nemoclaw-contributor-onboard-messaging-channel skill instructions to explicitly
load and follow .agents/skills/_shared/documentation-writing-review.md,
WRITING.md, and docs/CONTRIBUTING.md before removing or relaxing the global
documentation requirement.

🤖 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/AGENTS.md`:
- Line 60: Update the guidance around
`.agents/skills/nemoclaw-user-guide/SKILL.md` to identify it as an autogenerated
output from `docs/`; instruct maintainers to edit the relevant `docs/` source
and regenerate the skill rather than modifying the generated file directly.

---

Outside diff comments:
In `@AGENTS.md`:
- Line 24: Update the nemoclaw-contributor-onboard-messaging-channel skill
instructions to explicitly load and follow
.agents/skills/_shared/documentation-writing-review.md, WRITING.md, and
docs/CONTRIBUTING.md before removing or relaxing the global documentation
requirement.

🪄 Autofix

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: a343d1ed-feb1-45df-8b09-39716c26cfc8

📥 Commits

Reviewing files that changed from the base of the PR and between 7b4c42d and 99cbcf5.

📒 Files selected for processing (13)

• .agents/skills/_shared/controlled-words.md
• .agents/skills/_shared/documentation-writing-review.md
• .agents/skills/nemoclaw-contributor-create-pr/SKILL.md
• .agents/skills/nemoclaw-maintainer-refactor-docs/SKILL.md
• AGENTS.md
• CONTRIBUTING.md
• WRITING.md
• docs/AGENTS.md
• docs/CONTRIBUTING.md
• docs/DORI_SETUP.md
• docs/resources/engineer-agentic-documentation.mdx
• test/maintainer-skills-policy.test.ts
• test/skills-frontmatter.test.ts