docs: enforce guide variant publication scope

[jyaunches]

Summary

This follow-up publishes the OpenShell gateway lifecycle authority and Enterprise Readiness pages in the OpenClaw, Hermes, and Deep Agents guide variants.
It also makes intentional partial publication explicit in source frontmatter and fails the docs build when navigation and source scope differ.

Related Issue

Follow-up to #6576 and #7246.

Changes

• feat(onboard): bind external gateway lifecycle authority #7246 -> docs/deployment/gateway-lifecycle-authority.mdx: Publishes the host-side OpenShell gateway lifecycle contract for every applicable guide variant and distinguishes it from an in-sandbox agent gateway.
• Publishes docs/reference/enterprise-readiness.mdx for LangChain Deep Agents Code and describes the runtime-specific dashboard, observability, and agent gateway boundaries.
• Adds exact agent-variants declarations to 42 intentionally partial source pages. The docs generator compares these declarations with docs/index.yml because navigation alone cannot distinguish an omission from an intentional subset.
• Updates Miyoung’s daily documentation-engineering workflow and its supporting instruction surfaces so guide variant scope is derived from implementation, tests, or accepted product scope.
• Adds focused tests for missing, mismatched, and matching declarations and for all-variant OpenShell gateway routes.

Change footprint

This PR changes 52 files, but most of that count is the baseline required by the new validation:

• 42 files: Add one agent-variants frontmatter line to existing pages whose publication is intentionally limited to a subset of the OpenClaw, Hermes, and Deep Agents guides. Their documentation content does not change.
• 3 files: Correct the user-facing publication and wording for the OpenShell gateway lifecycle and Enterprise Readiness pages: docs/deployment/gateway-lifecycle-authority.mdx, docs/reference/enterprise-readiness.mdx, and docs/index.yml.
• 4 files: Update Miyoung’s documentation-engineering workflow and its instruction surfaces: .agents/skills/nemoclaw-contributor-update-docs/SKILL.md, docs/AGENTS.md, docs/CONTRIBUTING.md, and docs/resources/engineer-agentic-documentation.mdx.
• 3 files: Add executable validation and focused tests: scripts/sync-agent-variant-docs.mts, test/sync-agent-variant-docs.test.ts, and test/check-docs-published-routes.test.ts.

Miyoung’s documentation-engineering workflow

Miyoung’s documentation-engineering workflow is not a separate bot, service, or scheduled GitHub workflow. It is the repository-owned nemoclaw-contributor-update-docs skill that she runs daily with Codex Desktop.

Before this PR, the skill already knew how to render host CLI names for all three guide variants, but its new-page rule only told the documentation engineer to add the “appropriate navigation entry.” It did not require an explicit applicability decision or a source declaration for an intentional subset. Separately, the generator classified a page as shared by intersecting only the OpenClaw and Hermes navigation, and its guard applied only to pages containing the $$nemoclaw placeholder. As a result, a generic page with literal nemoclaw commands could be added only to the OpenClaw navigation and still pass the documentation build.

This PR changes the workflow at each relevant layer:

• .agents/skills/nemoclaw-contributor-update-docs/SKILL.md: Requires the daily documentation scan to determine applicability from implementation, tests, or accepted product scope; publish a page in every applicable guide variant; and declare an intentional subset with agent-variants.
• docs/AGENTS.md: Gives the same rule to agents while they work under docs/.
• docs/CONTRIBUTING.md: Makes the applicability decision and source declaration part of the contributor contract.
• docs/resources/engineer-agentic-documentation.mdx: Updates the public description of the documentation engine so it no longer says that navigation alone defines variant membership.
• scripts/sync-agent-variant-docs.mts: Enforces the rule by comparing each source declaration with its actual OpenClaw, Hermes, and Deep Agents navigation membership during the documentation build.

There is no separate scheduler to adjust. The documentation-writer receipt continues to verify that review happened on the current head; the new generator check supplies the missing publication-scope control.

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: Frontmatter-only scope declarations under sensitive documentation paths were included in the independent implementation and navigation scope audit.
  No security behavior or security claim changed.
• 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: Reviewed .agents/skills/nemoclaw-contributor-update-docs/SKILL.md, docs/AGENTS.md, docs/CONTRIBUTING.md, docs/index.yml, the 45 changed MDX source pages, the generator, and the focused tests.
  The review covered the writing rules, documentation style, guide variant terminology, gateway boundaries, rendered commands, and declared publication scope.
  Focused tests passed 36/36, and npm run docs completed with 0 errors and 2 pre-existing Fern warnings.
• Agent: Codex Desktop

DGX Station Hardware Evidence

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

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: npm exec -- vitest run test/sync-agent-variant-docs.test.ts test/check-docs-published-routes.test.ts passed 36/36 tests at f8bdabacc.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable; this change does not alter broad runtime behavior or the test harness.
• 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: 0 errors and 2 pre-existing Fern warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only) — not applicable; this PR adds no source page.

---

Signed-off-by: Julie Yaunches jyaunches@nvidia.com

Summary by CodeRabbit

• Documentation

  • Added clearer guidance for identifying which agent variants each guide supports.
  • Improved documentation metadata and navigation so OpenClaw, Hermes, and Deep Agents guides appear in the appropriate sections.
  • Clarified gateway lifecycle authority, enterprise readiness, and related deployment guidance.
  • Updated command examples and troubleshooting instructions for gateway management.

• Bug Fixes

  • Ensured shared documentation is published consistently across applicable guide variants.
  • Added validation to detect missing, mismatched, or broken variant-specific documentation routes.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds explicit agent-variant scope metadata across documentation, derives publication membership from navigation, validates declarations during synchronization, updates shared guide routes and content, and adds tests for scope mismatches and published gateway lifecycle routes.

Changes

Agent-variant documentation scope

Layer / File(s)	Summary
Scope guidance and declarations .agents/skills/..., docs/AGENTS.md, docs/CONTRIBUTING.md, docs/resources/..., docs/{about,configure-agents,deployment,get-started,inference,manage-sandboxes,monitoring,network-policy,security}/...	Documentation rules now require evidence-based variant applicability, generated targets for shared pages, and explicit agent-variants metadata for partial publication. Affected pages declare OpenClaw, Hermes, Deep Agents, or combined scopes.
Navigation membership and scope validation scripts/sync-agent-variant-docs.mts, test/sync-agent-variant-docs.test.ts	Synchronization derives page membership from all navigation variants and rejects missing, invalid, repeated, or mismatched frontmatter declarations. Fixtures cover rejection and acceptance cases.
Published routes and guide content docs/index.yml, docs/deployment/gateway-lifecycle-authority.mdx, docs/reference/enterprise-readiness.mdx, test/check-docs-published-routes.test.ts	Generated navigation targets are added for applicable variants, gateway lifecycle guidance is updated for shared host-side behavior, enterprise-readiness links and boundaries are refined, and published routes are tested for all variants.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DocsIndex as docs/index.yml
  participant SyncScript as sync-agent-variant-docs.mts
  participant PublishedDocs as generated agent-variant docs
  participant RouteTests as check-docs-published-routes.test.ts
  DocsIndex->>SyncScript: provide variant navigation membership
  SyncScript->>SyncScript: validate frontmatter scope
  SyncScript->>PublishedDocs: generate variant targets
  RouteTests->>PublishedDocs: check published routes and links
  PublishedDocs-->>RouteTests: return resolvable route graph

Loading

Possibly related PRs

• NVIDIA/NemoClaw#4632: Established the agent-variant documentation infrastructure extended by this scope validation.
• NVIDIA/NemoClaw#4728: Updated the generated navigation and shared-page rendering flow used here.
• NVIDIA/NemoClaw#6344: Added Deep Agents support to the agent-variant documentation system.

Suggested labels: area: ci, chore, v0.0.98

Suggested reviewers: cv, ericksoa, aasthajh

🚥 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 summarizes the main change: enforcing publication scope for guide variants.

✨ 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 codex/clarify-gateway-doc-variants

---

_{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 in commit f8bdaba in the codex/clarify-gatewa... branch remains at 96%, unchanged from commit 9b1fbd8 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit f8bdaba in the codex/clarify-gatewa... branch remains at 81%, unchanged from commit 9b1fbd8 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 9b1fbd8	codex/clarify-gatewa... f8bdaba	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/sandbox...rce-identity.ts	88%	88%	0%
src/lib/onboard...ndbox-create.ts	83%	91%	+8%
src/lib/onboard...-create-plan.ts	75%	88%	+13%
src/lib/onboard...ndbox-create.ts	33%	83%	+50%

---

_{Updated July 29, 2026 19:11 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-7842.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 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

• full-e2e

Workflow run details

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