docs(commands): document nemoclaw internal:* command family

[laitingsheng]

Summary

Adds an "Internal Commands" section to docs/reference/commands.mdx listing the nine nemoclaw internal <topic> <action> commands. The commands are already registered as hidden in oclif (static hidden = true, added in #3074/#3075/#3083/#3090/#3108 on 2026-05-06), so they are absent from nemoclaw --help, but they had no documented description anywhere — operators who became aware of them through other paths had no canonical reference.

Related Issue

Fixes #3782
Closes #3938

Changes

• docs/reference/commands.mdx: new "Internal Commands" section between nemoclaw uninstall and "Environment Variables". Lists each of the nine commands, the wrapper script that calls it, and a one-line purpose. Header explicitly states the family is not part of the supported public CLI surface and that flags/output/exit codes may change without notice.

Note: the orthogonal "_commandIDs leak via oclif validation stack trace" symptom called out in #3782 is not addressed here — that is the separate UX bug the original report flagged as out of scope for the hide/document fix.

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

• 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
• make 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)

---

Signed-off-by: Tinson Lai tinsonl@nvidia.com

Summary by CodeRabbit

• Documentation
  • Added a new section documenting internal CLI commands and their usage contexts.
  • Clarifies these commands are omitted from standard help, are not part of the supported public CLI surface, and may change between releases.
  • Includes a mapping of internal commands to the installer/uninstaller and other internal tooling contexts for reference.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a new "Internal Commands" section to docs/reference/commands.mdx documenting the hidden nemoclaw internal <topic> <action> command family, noting these commands are omitted from nemoclaw --help, unsupported, and subject to change; includes a table mapping each internal command to its caller script and purpose.

Changes

Internal Commands Documentation

Layer / File(s)

Summary

Internal Commands documentation section docs/reference/commands.mdx

Adds "Internal Commands" section documenting the hidden nemoclaw internal <topic> <action> family, explicitly noting these commands are omitted from help, unsupported, and unstable. Includes a reference table mapping the 9 internal commands to their caller scripts and purposes (npm linking/shimming, CoreDNS fix, DNS proxy setup, installer planning/inspection, release-tag resolution, env normalization, uninstall classification/plan/run).

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I’m a rabbit in the code-laced night,
I hopped to docs to set things right.
Nine secret hops now shown and known,
No more whispers in the console’s tone.
🐇📜

🚥 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 describes the primary change: documenting the internal nemoclaw commands family in the CLI reference guide.
Linked Issues check	✅ Passed	The PR implements option (b) from both linked issues #3782 and #3938: documenting all nine internal:* commands in the commands.md reference with descriptions of their purpose and usage context.
Out of Scope Changes check	✅ Passed	All changes are in-scope: the documentation-only addition of an Internal Commands section to commands.mdx covering the nine specified internal commands and explicitly excluding the out-of-scope oclif validation leak issue.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

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

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/internal-commands-3782

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

---

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

[github-actions]

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

[github-actions]

E2E Advisor Recommendation

Required E2E: None
Optional E2E: None

Workflow run

Full advisor summary

E2E Recommendation Advisor

Base: origin/main
Head: HEAD
Confidence: high

Required E2E

• None. Documentation-only change to docs/reference/commands.mdx. The diff adds reference text for internal commands and does not modify runtime code or user-flow behavior, so existing E2E jobs are not needed for this PR.

Optional E2E

• None.

New E2E recommendations

• None.

[coderabbitai]

🧹 Nitpick comments (1)

docs/reference/commands.mdx (1)

1131-1131: ⚡ Quick win

Use second person for reader guidance.

Line 1131 addresses the reader as “Operators”; prefer direct second person (“you”) to match docs voice consistency.

As per coding guidelines, "Second person ("you") when addressing the reader."

🤖 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 `@docs/reference/commands.mdx` at line 1131, Replace the impersonal phrasing
"Operators should not invoke them directly; use the user-facing commands or
wrapper scripts above instead." with a second-person version addressing the
reader—e.g., "You should not invoke these directly; use the user-facing commands
or wrapper scripts above instead."—so update that sentence in
docs/reference/commands.mdx to use "you" and adjust "them" to "these" for
clarity and voice consistency.

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

Nitpick comments:
In `@docs/reference/commands.mdx`:
- Line 1131: Replace the impersonal phrasing "Operators should not invoke them
directly; use the user-facing commands or wrapper scripts above instead." with a
second-person version addressing the reader—e.g., "You should not invoke these
directly; use the user-facing commands or wrapper scripts above instead."—so
update that sentence in docs/reference/commands.mdx to use "you" and adjust
"them" to "these" for clarity and voice consistency.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 95715cd1-088f-41e6-a805-5c6fd2392e13

📥 Commits

Reviewing files that changed from the base of the PR and between 449f6f4 and 4efdf9f.

📒 Files selected for processing (1)

• docs/reference/commands.mdx

[github-actions]

PR Review Advisor

Recommendation: blocked
Confidence: high
Analyzed HEAD: f20f89e0953e9e570571ff0f15530441b2a9cc1b
Findings: 2 blocker(s), 1 warning(s), 0 suggestion(s)

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

Limitations: Review is based on trusted metadata and the provided diff; no commands, scripts, tests, package-manager operations, or docs builds were executed.; CI was still pending for the exact head SHA at review time, so final pass/fail status could not be verified.; Review thread state was not fully available; CodeRabbit remained pending in the status rollup.; An E2E Advisor comment was found recommending no E2E, but the current head SHA also shows an E2E recommendation check still in progress, so the E2E advisor status is treated as ambiguous.; Linked issue acceptance was mapped from the provided issue bodies and comments; no additional issue timeline events were fetched.

Workflow run

Full advisor summary

PR Review Advisor

Base: origin/main
Head: HEAD
Analyzed SHA: f20f89e0953e9e570571ff0f15530441b2a9cc1b
Recommendation: blocked
Confidence: high

Docs-only change appears low risk and aligned with the linked issues, but merge is blocked by pending CI and GitHub BLOCKED merge state for the current head SHA.

Gate status

• CI: pending — Trusted context reports 13 status context(s) appear pending for head SHA f20f89e; GraphQL shows in-progress/queued checks including get-pr-info, cli-parity, preview, E2E recommendation, PR review advisor, CodeQL, unit-vitest-linux, ShellCheck SARIF, and sandbox image builds, plus CodeRabbit pending.
• Mergeability: fail — mergeStateStatus=BLOCKED; pull request mergeable_state=blocked and reviewDecision=REVIEW_REQUIRED.
• Review threads: unknown — No review thread state was available; GraphQL reviewThreads.nodes is empty, but trusted gate summary reports no review thread state was available and CodeRabbit is pending.
• Risky code tested: pass — No risky code areas detected by path heuristics; the only changed file is docs/reference/commands.mdx.

🔴 Blockers

• Required status checks are still pending for the current head SHA: The current head SHA cannot be considered merge-ready while required checks and security/static-analysis jobs are still in progress or queued.
  • Recommendation: Wait for all required CI/status checks for f20f89e to complete successfully before merge consideration.
  • Evidence: Trusted context reports ci.status=pending with 13 pending contexts; GraphQL shows in-progress/queued checks including CodeQL, preview, E2E recommendation, PR review advisor, unit-vitest-linux, ShellCheck SARIF, and sandbox image builds.
• GitHub merge state is blocked: GitHub reports the pull request is blocked and still requires review, so branch protection requirements are not satisfied.
  • Recommendation: Resolve branch protection requirements, required reviews, and required checks before merge consideration.
  • Evidence: Trusted context reports mergeStateStatus=BLOCKED; pull_request.mergeable_state=blocked; GraphQL reviewDecision=REVIEW_REQUIRED.

🟡 Warnings

• Same-file documentation drift risk (docs/reference/commands.mdx): The patch edits a highly active reference documentation file with many recent commits and multiple open PRs touching the same file. The target file still exists and the added section is in-scope, but final placement and wording may drift relative to concurrent docs and CLI-reference updates.
  • Recommendation: Before merge, re-check the final branch against latest main and nearby docs PRs to ensure the Internal Commands section remains correctly placed and does not contradict newer command-reference edits.
  • Evidence: Trusted drift evidence shows docs/reference/commands.mdx has recent history; open same-file overlaps include PRs docs(reference): document remote-deploy env vars #3349, docs(reference,quickstart): explain --fresh/--yes and the curl|bash flag form #3351, docs(reference): add env-var index + document gateway lifecycle tunables (#3059) #3652, docs: fix onboarding, topology, and messaging channels #3762, Docs/comprehensive documentation cleanup and v0.0.44 synchronization #3766, docs(reference): document openshell settings + sandbox runtime env #3794, fix(snapshot): refuse restore --to existing destination; add --force opt-in #3796, Upgrade OpenClaw to 2026.5.18 #3825, fix(cli): align shields status and logs tail UX #3866, and chore: upgrade agent runtime dependencies #3925.

🔵 Suggestions

• None.

Acceptance coverage

• met — NemoClaw v0.0.44 ships with 9 oclif-registered commands under the
  internal:* namespace that are reachable from the user's shell but are
  not listed in nemoclaw --help and are not documented in
  docs/reference/commands.md:: The diff adds a new ## Internal Commands section to docs/reference/commands.mdx and states the commands are intentionally omitted from nemoclaw --help and are not part of the supported public CLI surface.
• met — internal:dev:npm-link-or-shim: The added table includes nemoclaw internal dev npm-link-or-shim with caller scripts/npm-link-or-shim.sh and purpose Run npm link, falling back to a user-local NemoClaw development shim.
• met — internal:dns:fix-coredns: The added table includes nemoclaw internal dns fix-coredns with caller scripts/fix-coredns.sh and purpose Patch CoreDNS to use a non-loopback upstream resolver.
• met — internal:dns:setup-proxy: The added table includes nemoclaw internal dns setup-proxy with caller scripts/setup-dns-proxy.sh and purpose Configure the DNS forwarder bridge inside a sandbox pod.
• met — internal:installer:normalize-env: The added table includes nemoclaw internal installer normalize-env with a purpose describing normalizing installer ref and provider environment values without applying installation changes.
• met — internal:installer:plan: The added table includes nemoclaw internal installer plan with a purpose describing building a deterministic installer plan without applying it.
• met — internal:installer:resolve-release-tag: The added table includes nemoclaw internal installer resolve-release-tag with a purpose describing resolving the installer ref using the same precedence as install.sh.
• met — internal:uninstall:classify-shim: The added table includes nemoclaw internal uninstall classify-shim with a purpose describing classifying whether a NemoClaw shim path is safe to remove.
• met — internal:uninstall:plan: The added table includes nemoclaw internal uninstall plan with a purpose describing building a deterministic uninstall plan without applying it.
• met — internal:uninstall:run-plan: The added table includes nemoclaw internal uninstall run-plan with caller uninstall.sh and purpose Execute the host-side uninstall plan.
• missing — These commands do not appear in oclif's registered command list and
  nemoclaw internal: returns "Unknown command", OR: This PR is documentation-only and does not modify oclif command registration or direct invocation behavior.
• met — They are documented as an "Internal — not user-callable" group in
  commands.md with a short description of each.: The diff implements the documentation alternative in docs/reference/commands.mdx: it adds an Internal Commands section, says operators should not invoke the commands directly, and provides a short purpose for each command.
• partial — Preferred: mark the 9 internal:* commands as hidden: true (oclif
  supports a hidden flag on commands) so they are dropped from the public
  command surface and from any introspected _commandIDs listing.: The diff does not change command registration. It documents that commands are intentionally omitted from help via static hidden = true, but this review did not verify the underlying code change because only docs/reference/commands.mdx changed.
• met — Alternative: add a "Internal commands (installer/uninstaller use only)"
  section near the bottom of commands.md that lists each, with a short
  sentence saying it is invoked by the install/uninstall scripts and is
  not part of the supported public CLI surface.: The new section is added near the bottom of the reference before Environment Variables, lists all nine commands, lists callers or helper roles, and states they are not part of the supported public CLI surface.
• partial — Related: the bug for "nemoclaw oclif validation errors leak full stack
  trace + internal config dump". Hiding these commands does not by itself
  fix the stack-trace leak — they are two issues with the same UX symptom.: No stack-trace leak code is changed. The PR body notes this is out of scope, and the diff only documents internal commands.
• met — Duplicate of [All Platforms][CLI] nemoclaw internal:* 9 hidden commands registered but undocumented #3782.: Issue [All Platforms][CLI][GitHub Issue #3782] nemoclaw internal:* 9 hidden commands registered but undocumented #3938 comment states Duplicate of #3782.; PR docs(commands): document nemoclaw internal:* command family #3968 links both [All Platforms][CLI] nemoclaw internal:* 9 hidden commands registered but undocumented #3782 and [All Platforms][CLI][GitHub Issue #3782] nemoclaw internal:* 9 hidden commands registered but undocumented #3938 and implements the documentation alternative from [All Platforms][CLI] nemoclaw internal:* 9 hidden commands registered but undocumented #3782.

Security review

• pass — Category 1: Secrets and Credentials: Docs-only change adds command descriptions and wrapper names; no hardcoded secrets, tokens, passwords, connection strings, PEM/key files, credential JSON, or .env content are introduced.
• pass — Category 2: Input Validation and Data Sanitization: Not applicable to runtime input handling; no API handlers, CLI argument parsing, URL handling, deserialization, command execution, path processing, or sanitization logic is changed.
• pass — Category 3: Authentication and Authorization: No authentication, authorization, token validation, ownership checks, or privilege logic is modified. The docs explicitly warn that internal commands are unsupported and should not be invoked directly.
• pass — Category 4: Dependencies and Third-Party Libraries: No dependency manifests, lockfiles, registries, package versions, or third-party libraries are changed.
• pass — Category 5: Error Handling and Logging: No error handling or logging code is changed. The related oclif stack-trace/internal config dump issue remains out of scope and is not made worse by runtime code changes in this PR.
• pass — Category 6: Cryptography and Data Protection: Not applicable — no cryptographic operations, hashing, encryption, key management, or data-protection behavior is changed.
• pass — Category 7: Configuration and Security Headers: No runtime configuration, Dockerfiles, workflow permissions, HTTP endpoints, CORS/CSP headers, port exposure, or container defaults are modified.
• pass — Category 8: Security Testing: Docs-only change cannot directly affect runtime security behavior. Security/static analysis and docs-related CI are still pending and must pass as a merge gate.
• pass — Category 9: Holistic Security Posture: The change improves operator understanding of hidden/internal commands and includes clear unsupported-public-surface and do-not-invoke guidance. No sandbox escape, SSRF, network policy, credential, blueprint, installer trust, workflow boundary, or lifecycle code is changed.

Test / E2E status

• Test depth: unit_sufficient — Changes are limited to tests, documentation, or metadata that cannot affect runtime behavior directly.
• E2E Advisor: ambiguous

✅ What looks good

• The change is narrowly scoped to one documentation file with 19 inserted lines and no runtime code changes.
• The new section clearly states the internal command family is not part of the supported public CLI surface and that flags, output, and exit codes may change without notice.
• All nine internal commands named by the linked issues are represented in the added table with caller/helper context and purpose.
• The E2E Advisor comment recommends no required or optional E2E for this docs-only change.

Review completeness

• Review is based on trusted metadata and the provided diff; no commands, scripts, tests, package-manager operations, or docs builds were executed.
• CI was still pending for the exact head SHA at review time, so final pass/fail status could not be verified.
• Review thread state was not fully available; CodeRabbit remained pending in the status rollup.
• An E2E Advisor comment was found recommending no E2E, but the current head SHA also shows an E2E recommendation check still in progress, so the E2E advisor status is treated as ambiguous.
• Linked issue acceptance was mapped from the provided issue bodies and comments; no additional issue timeline events were fetched.
• Human maintainer review required: yes

[coderabbitai]

🧹 Nitpick comments (2)

docs/reference/commands.mdx (2)

1142-1142: ⚡ Quick win

Use active voice in the purpose description.

The second sentence uses passive voice ("Called as a library function by"). Active voice is required per the style guide.

Suggested rewording

-| `nemoclaw internal uninstall classify-shim` | Internal inspection helper | Classify whether a NemoClaw shim path is safe to remove. Called as a library function by `internal uninstall run-plan`, not via this command. |
+| `nemoclaw internal uninstall classify-shim` | Internal inspection helper | Classify whether a NemoClaw shim path is safe to remove. `internal uninstall run-plan` calls this as a library function, not via this command. |

As per coding guidelines, active voice is required; the example shows "The CLI creates a gateway" instead of "A gateway is created by the CLI."

🤖 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 `@docs/reference/commands.mdx` at line 1142, The purpose sentence for the
`nemoclaw internal uninstall classify-shim` command currently uses passive
voice; change the second sentence to active voice by stating who calls it.
Update the description for `nemoclaw internal uninstall classify-shim` to
something like "Classify whether a NemoClaw shim path is safe to remove. The
`internal uninstall run-plan` command calls this as a library function,"
ensuring the command names `nemoclaw internal uninstall classify-shim` and
`internal uninstall run-plan` are referenced exactly as in the diff.

---

1138-1140: ⚡ Quick win

Use active voice for these descriptions.

The purpose descriptions for these three internal planning helpers use passive voice ("exposed for external tooling and inspection"). Active voice is required per the style guide.

Suggested rewording

For each of these three rows, replace "exposed for external tooling and inspection" with "This command exposes the logic for external tooling and inspection."

For example, line 1138:

-| `nemoclaw internal installer plan` | Internal planning helper | Build a deterministic installer plan from environment and probe inputs without applying it. Not currently invoked by `install.sh` (which has its own Bash equivalents); exposed for external tooling and inspection. |
+| `nemoclaw internal installer plan` | Internal planning helper | Build a deterministic installer plan from environment and probe inputs without applying it. Not currently invoked by `install.sh` (which has its own Bash equivalents); this command exposes the logic for external tooling and inspection. |

Apply the same change to lines 1139 and 1140.

As per coding guidelines, active voice is required; the example shows "The CLI creates a gateway" instead of "A gateway is created by the CLI."

🤖 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 `@docs/reference/commands.mdx` around lines 1138 - 1140, Update the three table
rows for the internal installer helper commands (`nemoclaw internal installer
plan`, `nemoclaw internal installer resolve-release-tag`, `nemoclaw internal
installer normalize-env`) to use active voice by replacing the phrase "exposed
for external tooling and inspection" with "This command exposes the logic for
external tooling and inspection."; keep the rest of each description unchanged
so only the voice changes.

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

Nitpick comments:
In `@docs/reference/commands.mdx`:
- Line 1142: The purpose sentence for the `nemoclaw internal uninstall
classify-shim` command currently uses passive voice; change the second sentence
to active voice by stating who calls it. Update the description for `nemoclaw
internal uninstall classify-shim` to something like "Classify whether a NemoClaw
shim path is safe to remove. The `internal uninstall run-plan` command calls
this as a library function," ensuring the command names `nemoclaw internal
uninstall classify-shim` and `internal uninstall run-plan` are referenced
exactly as in the diff.
- Around line 1138-1140: Update the three table rows for the internal installer
helper commands (`nemoclaw internal installer plan`, `nemoclaw internal
installer resolve-release-tag`, `nemoclaw internal installer normalize-env`) to
use active voice by replacing the phrase "exposed for external tooling and
inspection" with "This command exposes the logic for external tooling and
inspection."; keep the rest of each description unchanged so only the voice
changes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 870c9165-d51a-4f4e-87bf-94a0452b5579

📥 Commits

Reviewing files that changed from the base of the PR and between 4efdf9f and f20f89e.

📒 Files selected for processing (1)

• docs/reference/commands.mdx

[cv]

These commands are internal and mostly in a transitional state while we try to get more stuff moved over from long and badly vibed out bash scripts into typescript with slightly better quality.

Documenting these gives these commands an air of legitimacy I don't think they should have!