docs: document agentic documentation engineering workflow

[miyoungc]

Summary

Adds a professional guide to NemoClaw's repository-embedded, agentic documentation engineering workflow while keeping the new source page out of Fern navigation for now. The workflow statically resolves canonical $$nemoclaw and <AgentOnly> source into agent-specific variants without runtime documentation components.

Changes

• Add the canonical agentic documentation engineering guide under docs/resources/.
• Document how repository instructions and the update-docs skill move feature documentation into engineering PRs, leaving writers to review and restructure material as it grows.
• Resolve agent-specific names and conditional blocks during variant generation, reject unresolved runtime variant syntax, and update the focused tests and contributor guidance.
• Remove the runtime AgentGuide component and its imports from canonical documentation sources.
• Keep the guide source tracked without registering its generated variants in the Fern navigation or documentation build.

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:
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

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 — 3 focused Vitest files, 36 tests passed initially; 2 focused files, 17 tests passed after the audited AgentOnly boundary refinement; independent before/after audits confirmed identical nonblank content across all 209 generated variants
• 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 variant-generation tests cover this change
• 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) — completed with 0 errors and one pre-existing Fern 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

• New Features

  • Added a new documentation guide for an agentic documentation operating model and delivery contract.
  • Documentation now consistently uses explicit $$nemoclaw CLI commands for examples.
  • Improved deterministic, build-time variant handling for agent-specific documentation.

• Bug Fixes

  • Fixed formatting issues around variant-gated content (especially list/paragraph boundaries).
  • Added stronger validation to fail builds if unresolved directives, imports, or runtime agent components remain in published output.

• Tests

  • Expanded and adjusted variant-filtering and negative-case tests to match the updated directive/rendering behavior.

[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: 39bd7a04-44da-4ef6-aed2-13d4b7532ec0

📥 Commits

Reviewing files that changed from the base of the PR and between 6d8e551 and 1fb0a1d.

📒 Files selected for processing (5)

• docs/get-started/prerequisites.mdx
• docs/get-started/windows-preparation.mdx
• docs/inference/choose-inference-provider.mdx
• docs/manage-sandboxes/recover-rebuild-sandboxes.mdx
• docs/security/best-practices.mdx

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

• docs/manage-sandboxes/recover-rebuild-sandboxes.mdx
• docs/inference/choose-inference-provider.mdx
• docs/get-started/windows-preparation.mdx
• docs/get-started/prerequisites.mdx
• docs/security/best-practices.mdx

---

📝 Walkthrough

Walkthrough

The PR migrates agent-specific documentation to build-time AgentOnly directives, updates variant rendering and validation, removes local AgentGuide imports, replaces AgentCli references with literal commands, and adds an agentic documentation guide.

Changes

Agent variant documentation

Layer / File(s)	Summary
Build-time directive contract docs/AGENTS.md, docs/CONTRIBUTING.md, docs/resources/engineer-agentic-documentation.mdx	Defines AgentOnly authoring rules, deterministic variant generation, route mapping, validation, governance, and readiness criteria.
Static variant rendering and validation scripts/sync-agent-variant-docs.mts, test/*agent-variant-docs*.test.ts, test/check-docs-published-routes.test.ts	Trims list-boundary whitespace, rejects unresolved runtime markers, updates placeholder handling, and expands rendering and failure-mode coverage.
Source-page migration docs/about/*, docs/configure-agents/*, docs/deployment/*, docs/get-started/*, docs/inference/*, docs/manage-sandboxes/*, docs/monitoring/*, docs/network-policy/*, docs/reference/*, docs/security/*	Removes local AgentGuide imports, replaces AgentCli references with literal $$nemoclaw commands, and retains agent-specific blocks for build-time resolution.

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

Sequence Diagram(s)

sequenceDiagram
  participant SourceMDX
  participant renderAgentVariantPage
  participant AgentOnlyResolver
  participant assertStaticallyResolvedVariantPage
  SourceMDX->>renderAgentVariantPage: provide source variant page
  renderAgentVariantPage->>AgentOnlyResolver: resolve AgentOnly blocks
  AgentOnlyResolver-->>renderAgentVariantPage: filtered markdown
  AgentOnlyResolver->>assertStaticallyResolvedVariantPage: provide rendered output
  assertStaticallyResolvedVariantPage-->>renderAgentVariantPage: resolved page or error

Loading

Possibly related PRs

• NVIDIA/NemoClaw#5528: Overlaps on removing the AgentOnly import from the model capability audit page.
• NVIDIA/NemoClaw#6344: Covers related multi-variant AgentOnly handling in the documentation tooling.
• NVIDIA/NemoClaw#6425: Updates related command-reference and agent-variant rendering expectations.

Suggested labels: feature

🚥 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 accurately summarizes the new documentation guide and workflow-focused changes.
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/agentic-docs-source-only

---

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

[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 codex/agentic-docs-s... branch remains at 80%, unchanged from the main branch.

Show a code coverage summary of the most impacted files.

File	main 0339d88	codex/agentic-docs-s... 1fb0a1d	+/-
src/lib/core/pr...mpt-activity.ts	92%	67%	-25%
src/lib/credentials/store.ts	64%	59%	-5%
src/lib/adapter...hell/resolve.ts	100%	100%	0%
src/lib/agent/defs.ts	81%	81%	0%
src/lib/sandbox...rce-identity.ts	91%	91%	0%
src/lib/securit...p-url-target.ts	100%	100%	0%
src/lib/state/config-io.ts	93%	93%	0%
src/lib/state/registry-mcp.ts	100%	100%	0%
src/lib/state/registry.ts	83%	86%	+3%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

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

[github-actions]

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

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

[cv]

Approved on the refreshed exact head after the deterministic gate passed: 56 current checks green, no conflicts, no unresolved major/critical review findings, DCO present, and all 7 commits verified. I also ran the three focused renderer/synchronization suites (37 tests) and the strict Fern docs build successfully. The renderer keeps runtime components out of agent variants while preserving paragraph/list boundaries and link rewriting.