docs: generate agent variant code samples

[miyoungc]

Summary

Adds build-time generation for agent-specific docs variants so shared source samples can use $$nemoclaw while Fern still renders native fenced code blocks.

Tested preview:

• nemoclaw: https://nvidia-preview-pr-4721.docs.buildwithfern.com/nemoclaw/latest/user-guide/openclaw/manage-sandboxes/lifecycle
• nemohermes: https://nvidia-preview-pr-4721.docs.buildwithfern.com/nemoclaw/latest/user-guide/hermes/manage-sandboxes/lifecycle

Changes

• Generate OpenClaw and Hermes lifecycle docs from docs/manage-sandboxes/lifecycle.mdx and route both Fern variants to generated pages.
• Collapse simple duplicate lifecycle code blocks to $$nemoclaw sentinel samples while keeping AgentOnly for real content differences.
• Keep generated MDX ignored and idempotent so docs:preview:watch does not loop on generated files.
• Update docs-to-skills handling and add a focused variant-rendering test.

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)

Verification

git commit --no-verify and git push --no-verify were used at the user's request after a hook run failed in unrelated broad tests.

• npx prek run --all-files passes
• npm test passes
• Tests added or updated for new or changed behavior
• No secrets, API keys, or credentials committed
• Docs updated for user-facing behavior changes
• 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)

Verified locally:

• npm test -- test/agent-variant-docs.test.ts
• npm run docs (passes with the existing Fern warning)
• python3 scripts/docs-to-skills.py docs/ .agents/skills/ --prefix nemoclaw-user --doc-platform fern-mdx --dry-run

---

Signed-off-by: Miyoung Choi miyoungc@nvidia.com

Summary by CodeRabbit

Release Notes

• New Features

  • Added environment variables for OpenClaw conversation diagnostics and remote deployment configuration
  • Introduced agent-variant-specific documentation generation

• Documentation

  • Updated CLI command examples and contributor guidelines with standardized formatting rules
  • Added guidance for OpenClaw OTEL diagnostics configuration
  • Added remote deployment documentation

• Chores

  • Updated build workflow to use project-local tooling
  • Updated documentation generation configuration

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

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR introduces a $$nemoclaw build-time placeholder to consolidate variant-specific CLI command documentation, eliminating duplicate OpenClaw/Hermes command blocks. It updates the Fern preview workflow to use npm-driven generation, enhances the variant sync script to generate per-agent lifecycle files, and refactors lifecycle.mdx and supporting documentation to use the unified placeholder syntax.

Changes

Unified CLI placeholder for variant documentation generation

Layer / File(s)	Summary
Placeholder specification and documentation guidelines .agents/skills/nemoclaw-contributor-update-docs/SKILL.md, docs/CONTRIBUTING.md, .gitignore	The $$nemoclaw placeholder is defined as a build-time sentinel that resolves to either nemoclaw or nemohermes, and contributors are instructed to use it instead of duplicating code blocks when only the command name differs. .gitignore updated to exclude .generated.mdx files.
Build infrastructure and variant rendering engine .github/workflows/docs-preview-pr.yaml, scripts/sync-agent-variant-docs.ts	Fern preview workflow now runs npm run docs before generating previews, switching from global Fern CLI to npx-based invocation. Script configuration and constants added for agent variants, and renderAgentVariantPage() function exported to create per-variant MDX by stripping <AgentOnly> blocks and rewriting the CLI sentinel. Helper functions for file reading and writing added.
Variant page generation integration scripts/sync-agent-variant-docs.ts	main() workflow extended to generate per-agent variant lifecycle pages in both --check validation and normal update modes, using the new rendering and file-writing helpers.
Lifecycle documentation consolidation with placeholder docs/manage-sandboxes/lifecycle.mdx	All operational command examples (sandbox management, diagnostics, onboarding, provider switching, gateway/credential recovery, rebuild, upgrades, snapshots, uninstall) rewritten to use $$nemoclaw instead of variant-specific nemoclaw vs nemohermes snippets, with related prose and reference links updated.
Navigation and reference documentation updates docs/index.yml, docs/reference/commands-nemohermes.mdx	Navigation entries updated to point to generated agent-specific lifecycle files. Hermes reference documentation expanded with OpenClaw OTEL diagnostics environment variables, tracing configuration section, and remote deployment/Brev environment variable documentation.
Downstream tooling and test coverage scripts/docs-to-skills.py, scripts/watch-fern-preview.ts, test/agent-variant-docs.test.ts	docs-to-skills.py preprocesses $$nemoclaw to nemoclaw and excludes .generated.mdx files from skill conversion. File watcher ignores .generated.mdx paths to prevent spurious rebuilds. New test suite validates renderAgentVariantPage() rendering logic for both agent variants.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• NVIDIA/NemoClaw#4632: Established the agent-variant documentation generation pipeline in scripts/sync-agent-variant-docs.ts, which this PR extends to generate per-variant lifecycle pages using the unified $$nemoclaw placeholder approach.

Suggested labels

documentation, enhancement

Suggested reviewers

• cv

Poem

🐰 A placeholder born: $$nemoclaw,
Building bridges 'tween variants with care,
No more duplicate blocks, a cleaner draw—
One sentinel renders what's needed, right there!
From source to variant pages we flow,
Generated and watched—let the docs grow! 🌱

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 11.76% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: generate agent variant code samples' clearly and concisely summarizes the main change: building a system to automatically generate agent-specific documentation variants from shared source files using a sentinel placeholder.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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 agent/agent-code-component

---

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: docs-validation-e2e

Dispatch hint: docs-validation-e2e

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. No required E2E is recommended. The PR is limited to documentation, docs preview CI, docs/skills generation tooling, ignore rules, and unit-test coverage. It does not change installer/onboarding code, sandbox lifecycle implementation, credential handling, security boundaries, network policy enforcement, inference routing, deployment runtime, or real assistant user flows.

Optional E2E

• docs-validation-e2e (low): Optional confidence check for docs/link/CLI-reference validation after changing generated docs navigation, command-reference content, and docs-generation scripts. Not merge-blocking because the PR does not alter runtime CLI or sandbox behavior.

New E2E recommendations

• None.

Dispatch hint

• Workflow: .github/workflows/nightly-e2e.yaml
• jobs input: docs-validation-e2e

[github-actions]

E2E Scenario Advisor Recommendation

Required scenario E2E: None
Optional scenario E2E: None

Workflow run

Full scenario advisor summary

E2E Scenario Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required scenario E2E

• None. No scenario E2E recommendation: changes are limited to documentation, docs preview workflow/tooling, generated-doc/skill sync helpers, .gitignore, and non-scenario tests. No files under test/e2e-scenario/ or .github/workflows/e2e-scenarios*.yaml are changed, and the modified paths do not affect scenario E2E runtime, catalogs, expected states, validation suites, onboarding helpers, or scenario workflows.

Optional scenario E2E

• None.

Relevant changed files

• None.

[github-actions]

PR Review Advisor

Findings: 1 needs attention, 8 worth checking, 0 nice ideas
Since last review: 0 prior items resolved, 8 still apply, 1 new item found

Review findings

🛠️ Needs attention

• FERN_TOKEN is exposed to PR-controlled docs and package code (.github/workflows/docs-preview-pr.yaml:58): The token-bearing preview step still runs repository-controlled commands after exporting FERN_TOKEN. On same-repository PRs where secrets are available, a malicious change to package scripts, the sync script, or Fern configuration can execute with the Fern token in scope. The earlier npm ci --ignore-scripts step reduces install-hook risk, but it does not protect later npm run or npx execution under the secret environment.
  • Recommendation: Run all PR-controlled validation and generation before any step that has FERN_TOKEN. Derive and pin or allowlist the Fern CLI version from trusted base code before entering the token-bearing step, and expose FERN_TOKEN only to the minimal trusted Fern preview invocation.
  • Evidence: The Generate preview URL step sets FERN_TOKEN, then runs npm run docs:check-agent-variants, reads FERN_VERSION from ./fern/fern.config.json, and executes npx --yes "fern-api@${FERN_VERSION}" generate.

🔎 Worth checking

• Source-of-truth review needed: Generated lifecycle pages from docs/manage-sandboxes/lifecycle.mdx: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: docs/index.yml points lifecycle navigation at .generated.mdx files, .gitignore excludes generated MDX, and scripts/sync-agent-variant-docs.ts --check writes generated lifecycle files.
• Preview comment URL is trusted from repo-influenced CLI output (.github/workflows/docs-preview-pr.yaml:66): The workflow extracts the first matching http(s) URL from Fern output and posts it to the PR. Because the CLI version and output are influenced by repository content in the current design, a trusted-code-boundary failure can also make the workflow publish a misleading or attacker-controlled preview URL.
  • Recommendation: After separating secret-bearing execution from PR-controlled code, constrain the parsed preview URL to expected Fern-owned hostnames or use a trusted structured output from Fern if available.
  • Evidence: URL=$(echo "$OUTPUT" | sed -nE 's/.*Published docs to (https?:\/\/[^[:space:]]+).*/\1/p' | head -n1) accepts any http(s) URL matching the output text, and the next step comments PREVIEW_URL on the PR.
• --check mode writes ignored generated lifecycle docs (scripts/sync-agent-variant-docs.ts:34): The check command is used as validation, but it mutates the ignored generated lifecycle pages instead of verifying that they already exist and match expected content. Because docs/index.yml routes Fern navigation to those ignored files, this can silently create or repair missing or stale outputs and weakens the validation signal.
  • Recommendation: Make --check compare every generated target against expected contents and exit non-zero when any target is missing or stale. Keep writes in docs:sync-agent-variants, or rename the command if mutation is intentional and update callers and docs accordingly.
  • Evidence: In the checkOnly branch, the script checks commands-nemohermes.mdx and then calls writeGeneratedFiles(generatedVariantPages). .gitignore ignores docs/**/*.generated.mdx, while docs/index.yml points lifecycle pages to lifecycle.openclaw.generated.mdx and lifecycle.hermes.generated.mdx.
• Direct docs:live can start before generated lifecycle pages exist (package.json:34): The PR routes Fern navigation to ignored generated lifecycle pages, but the direct local docs-live command still starts Fern without syncing those files first. In a clean checkout, the generated lifecycle MDX files are absent, so direct Fern development can fail or render stale locally generated pages depending on prior commands.
  • Recommendation: Run docs:sync-agent-variants before docs:live, document the required manual generation step for direct Fern commands, or commit the generated pages if they are now part of the Fern navigation source of truth.
  • Evidence: docs/index.yml points to manage-sandboxes/lifecycle.openclaw.generated.mdx and lifecycle.hermes.generated.mdx; .gitignore excludes docs/**/*.generated.mdx; package.json docs:live runs Fern directly rather than syncing agent variants first.
• Variant-generation tests do not cover real lifecycle or generated-file invariants (test/agent-variant-docs.test.ts:16): The added tests validate a short synthetic fixture, but the risky behavior is the real lifecycle source, generated navigation targets, check/sync file semantics, docs-to-skills interaction, and absence of leaked sentinels or MDX components in generated pages.
  • Recommendation: Add tests that render docs/manage-sandboxes/lifecycle.mdx for both variants and assert no $$nemoclaw or AgentOnly remains, expected OpenClaw and Hermes commands are substituted throughout, and docs/index.yml targets are generated. Add a check-mode test that missing or stale generated files fail without writing, plus a docs-to-skills test for excluding generated MDX while handling the shared source.
  • Evidence: The only new tests call renderAgentVariantPage on an inline source fixture. The PR also changes .gitignore, docs/index.yml, scripts/docs-to-skills.py, and scripts/sync-agent-variant-docs.ts behavior without tests for those real-file invariants.
• Docs-to-skills can preserve both AgentOnly branches from the shared lifecycle source (scripts/docs-to-skills.py:414): For Fern MDX, docs-to-skills replaces $$nemoclaw with nemoclaw and excludes generated MDX files, so the shared lifecycle source remains the skill input. The Fern MDX cleaner handles standard components but no AgentOnly resolution was found, so generated skills can include both OpenClaw and Hermes-only prose while shared command examples are forced to nemoclaw.
  • Recommendation: Generate skills from one concrete rendered variant, or teach docs-to-skills to resolve AgentOnly blocks deliberately for the intended skill audience and add a regression test against docs/manage-sandboxes/lifecycle.mdx.
  • Evidence: parse_doc does body = body.replace("$$nemoclaw", "nemoclaw") for Fern MDX; _is_excluded_doc skips .generated.mdx; lifecycle.mdx still contains AgentOnly variant="openclaw" and variant="hermes" blocks.
• Generated lifecycle pages need a clearer source-of-truth contract (docs/index.yml:74): The PR makes ignored generated files the Fern navigation targets for the lifecycle page, but the source-of-truth contract is incomplete. It is not established why the generated targets should be ignored rather than committed, why the shared source cannot be rendered directly, what invariant prevents missing or stale generated files, or when this workaround can be removed.
  • Recommendation: Document the source boundary and removal condition, and make validation enforce the invariant that generated nav targets must exist and match the shared source output without being repaired by check mode. Prefer a source-level fix if Fern can render the variants directly.
  • Evidence: docs/index.yml routes lifecycle pages to .generated.mdx files, .gitignore ignores those files, and scripts/sync-agent-variant-docs.ts --check writes generated lifecycle files instead of only checking them.
• OpenClaw OTEL diagnostics appear in the Hermes command reference (docs/reference/commands-nemohermes.mdx:1600): The generated Hermes command reference now includes an OpenClaw Conversation OTEL Diagnostics section with nemohermes examples. If this diagnostic path is OpenClaw-specific, the generator has transformed command names while preserving semantics that do not apply to Hermes.
  • Recommendation: Verify whether Hermes supports NEMOCLAW_OPENCLAW_OTEL and the openclaw-diagnostics-otel-local preset. If not, wrap the source section in AgentOnly variant="openclaw" or add Hermes-specific wording before generating commands-nemohermes.mdx.
  • Evidence: docs/reference/commands-nemohermes.mdx contains 'OpenClaw Conversation OTEL Diagnostics', 'NEMOCLAW_OPENCLAW_OTEL=1 nemohermes onboard', and 'nemohermes <sandbox-name> policy-add openclaw-diagnostics-otel-local --yes'.

🌱 Nice ideas

• None.

Since last review details

Current findings:

• Source-of-truth review needed: Generated lifecycle pages from docs/manage-sandboxes/lifecycle.mdx: The advisor marked localized patch analysis as needs_followup.
  • Recommendation: Identify the invalid state, source boundary, source-fix constraint, regression test, and removal condition before merging the localized behavior.
  • Evidence: docs/index.yml points lifecycle navigation at .generated.mdx files, .gitignore excludes generated MDX, and scripts/sync-agent-variant-docs.ts --check writes generated lifecycle files.
• FERN_TOKEN is exposed to PR-controlled docs and package code (.github/workflows/docs-preview-pr.yaml:58): The token-bearing preview step still runs repository-controlled commands after exporting FERN_TOKEN. On same-repository PRs where secrets are available, a malicious change to package scripts, the sync script, or Fern configuration can execute with the Fern token in scope. The earlier npm ci --ignore-scripts step reduces install-hook risk, but it does not protect later npm run or npx execution under the secret environment.
  • Recommendation: Run all PR-controlled validation and generation before any step that has FERN_TOKEN. Derive and pin or allowlist the Fern CLI version from trusted base code before entering the token-bearing step, and expose FERN_TOKEN only to the minimal trusted Fern preview invocation.
  • Evidence: The Generate preview URL step sets FERN_TOKEN, then runs npm run docs:check-agent-variants, reads FERN_VERSION from ./fern/fern.config.json, and executes npx --yes "fern-api@${FERN_VERSION}" generate.
• Preview comment URL is trusted from repo-influenced CLI output (.github/workflows/docs-preview-pr.yaml:66): The workflow extracts the first matching http(s) URL from Fern output and posts it to the PR. Because the CLI version and output are influenced by repository content in the current design, a trusted-code-boundary failure can also make the workflow publish a misleading or attacker-controlled preview URL.
  • Recommendation: After separating secret-bearing execution from PR-controlled code, constrain the parsed preview URL to expected Fern-owned hostnames or use a trusted structured output from Fern if available.
  • Evidence: URL=$(echo "$OUTPUT" | sed -nE 's/.*Published docs to (https?:\/\/[^[:space:]]+).*/\1/p' | head -n1) accepts any http(s) URL matching the output text, and the next step comments PREVIEW_URL on the PR.
• --check mode writes ignored generated lifecycle docs (scripts/sync-agent-variant-docs.ts:34): The check command is used as validation, but it mutates the ignored generated lifecycle pages instead of verifying that they already exist and match expected content. Because docs/index.yml routes Fern navigation to those ignored files, this can silently create or repair missing or stale outputs and weakens the validation signal.
  • Recommendation: Make --check compare every generated target against expected contents and exit non-zero when any target is missing or stale. Keep writes in docs:sync-agent-variants, or rename the command if mutation is intentional and update callers and docs accordingly.
  • Evidence: In the checkOnly branch, the script checks commands-nemohermes.mdx and then calls writeGeneratedFiles(generatedVariantPages). .gitignore ignores docs/**/*.generated.mdx, while docs/index.yml points lifecycle pages to lifecycle.openclaw.generated.mdx and lifecycle.hermes.generated.mdx.
• Direct docs:live can start before generated lifecycle pages exist (package.json:34): The PR routes Fern navigation to ignored generated lifecycle pages, but the direct local docs-live command still starts Fern without syncing those files first. In a clean checkout, the generated lifecycle MDX files are absent, so direct Fern development can fail or render stale locally generated pages depending on prior commands.
  • Recommendation: Run docs:sync-agent-variants before docs:live, document the required manual generation step for direct Fern commands, or commit the generated pages if they are now part of the Fern navigation source of truth.
  • Evidence: docs/index.yml points to manage-sandboxes/lifecycle.openclaw.generated.mdx and lifecycle.hermes.generated.mdx; .gitignore excludes docs/**/*.generated.mdx; package.json docs:live runs Fern directly rather than syncing agent variants first.
• Variant-generation tests do not cover real lifecycle or generated-file invariants (test/agent-variant-docs.test.ts:16): The added tests validate a short synthetic fixture, but the risky behavior is the real lifecycle source, generated navigation targets, check/sync file semantics, docs-to-skills interaction, and absence of leaked sentinels or MDX components in generated pages.
  • Recommendation: Add tests that render docs/manage-sandboxes/lifecycle.mdx for both variants and assert no $$nemoclaw or AgentOnly remains, expected OpenClaw and Hermes commands are substituted throughout, and docs/index.yml targets are generated. Add a check-mode test that missing or stale generated files fail without writing, plus a docs-to-skills test for excluding generated MDX while handling the shared source.
  • Evidence: The only new tests call renderAgentVariantPage on an inline source fixture. The PR also changes .gitignore, docs/index.yml, scripts/docs-to-skills.py, and scripts/sync-agent-variant-docs.ts behavior without tests for those real-file invariants.
• Docs-to-skills can preserve both AgentOnly branches from the shared lifecycle source (scripts/docs-to-skills.py:414): For Fern MDX, docs-to-skills replaces $$nemoclaw with nemoclaw and excludes generated MDX files, so the shared lifecycle source remains the skill input. The Fern MDX cleaner handles standard components but no AgentOnly resolution was found, so generated skills can include both OpenClaw and Hermes-only prose while shared command examples are forced to nemoclaw.
  • Recommendation: Generate skills from one concrete rendered variant, or teach docs-to-skills to resolve AgentOnly blocks deliberately for the intended skill audience and add a regression test against docs/manage-sandboxes/lifecycle.mdx.
  • Evidence: parse_doc does body = body.replace("$$nemoclaw", "nemoclaw") for Fern MDX; _is_excluded_doc skips .generated.mdx; lifecycle.mdx still contains AgentOnly variant="openclaw" and variant="hermes" blocks.
• Generated lifecycle pages need a clearer source-of-truth contract (docs/index.yml:74): The PR makes ignored generated files the Fern navigation targets for the lifecycle page, but the source-of-truth contract is incomplete. It is not established why the generated targets should be ignored rather than committed, why the shared source cannot be rendered directly, what invariant prevents missing or stale generated files, or when this workaround can be removed.
  • Recommendation: Document the source boundary and removal condition, and make validation enforce the invariant that generated nav targets must exist and match the shared source output without being repaired by check mode. Prefer a source-level fix if Fern can render the variants directly.
  • Evidence: docs/index.yml routes lifecycle pages to .generated.mdx files, .gitignore ignores those files, and scripts/sync-agent-variant-docs.ts --check writes generated lifecycle files instead of only checking them.
• OpenClaw OTEL diagnostics appear in the Hermes command reference (docs/reference/commands-nemohermes.mdx:1600): The generated Hermes command reference now includes an OpenClaw Conversation OTEL Diagnostics section with nemohermes examples. If this diagnostic path is OpenClaw-specific, the generator has transformed command names while preserving semantics that do not apply to Hermes.
  • Recommendation: Verify whether Hermes supports NEMOCLAW_OPENCLAW_OTEL and the openclaw-diagnostics-otel-local preset. If not, wrap the source section in AgentOnly variant="openclaw" or add Hermes-specific wording before generating commands-nemohermes.mdx.
  • Evidence: docs/reference/commands-nemohermes.mdx contains 'OpenClaw Conversation OTEL Diagnostics', 'NEMOCLAW_OPENCLAW_OTEL=1 nemohermes onboard', and 'nemohermes <sandbox-name> policy-add openclaw-diagnostics-otel-local --yes'.

Workflow run details

This is an automated advisory review. A human maintainer must make the final merge decision.

[github-actions]

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

[miyoungc]

The link check is ok to ignore. It detected example link format in the contributing guide skill.