fix(docs): drop the unsupported audit option from the documented logs command

[laitingsheng]

Summary

The MCP troubleshooting page told readers to run logs --audit, but the sandbox logs command declares only --follow, --tail/-n, and --since and rejects any other flag, so the documented invocation exited with Nonexistent flag: --audit. The page now shows the supported invocation and states that the command already reads both OpenClaw gateway output and OpenShell audit events.

Related Issue

Fixes #8315

Changes

• Correct the audit-record lookup in docs/reference/troubleshoot-mcp-servers.mdx to logs --tail 200, name the two log sources with the wording already used in docs/reference/commands.mdx, and state the warning path when OpenShell audit logs cannot be enabled.
• Add test/cli/logs-documented-invocations.test.ts, which collects every runnable logs invocation from the published pages and runs each one through the CLI, so a documented flag that the parser rejects fails the suite.

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:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: docs/reference/troubleshoot-mcp-servers.mdx. An independent review confirmed that the documentation and command behavior agree, published routes remain valid, and the completed changes have no controlled-word or formatting findings. No further documentation changes are needed.
• Agent: Codex

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: npx vitest run --project integration test/cli/logs-documented-invocations.test.ts test/cli/logs.test.ts — 2 files, 22 tests passed. With the old --audit line restored, the new file fails on Nonexistent flag: --audit.
• 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)
• 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

  • Updated troubleshooting guidance to use nemoclaw logs --tail 200.
  • Clarified that logs include gateway output and OpenShell audit events.
  • Documented warnings that may appear when audit logging cannot be enabled.

• Tests

  • Added validation to ensure documented log commands are runnable and use supported options.

[coderabbitai]

📝 Walkthrough

Walkthrough

The troubleshooting documentation removes the unsupported --audit option and explains combined log output. A new test discovers runnable nemoclaw logs commands in published MDX files and verifies their execution.

Changes

Logs documentation and validation

Layer / File(s)	Summary
Combined logs documentation and validation docs/reference/troubleshoot-mcp-servers.mdx, test/cli/logs-documented-invocations.test.ts	The troubleshooting command now uses combined logs without --audit. The test discovers documented commands, requires at least five invocations, and checks exit status and unsupported-flag errors.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% 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
Linked Issues check	✅ Passed	The documentation removes the unsupported --audit flag and the test verifies documented logs commands execute successfully, satisfying issue #8315.
Out of Scope Changes check	✅ Passed	All changes support issue #8315 by correcting the documentation and adding a regression test for documented logs commands.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly describes the main change: removing the unsupported --audit option from the documented logs command, which aligns with the PR objectives and file modifications.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/troubleshoot-mcp-logs-flag

---

_{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 0bf2442 in the fix/troubleshoot-mcp... branch remains at 96%, unchanged from commit 2b68aa1 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 0bf2442 in the fix/troubleshoot-mcp... branch remains at 81%, unchanged from commit 2b68aa1 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 2b68aa1	fix/troubleshoot-mcp... 0bf2442	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/credentials/store.ts	56%	55%	-1%
src/lib/inferen...er-discovery.ts	88%	87%	-1%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/shields/index.ts	73%	74%	+1%

---

_{Updated August 05, 2026 13:28 UTC}

[github-actions]

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

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

test/cli/logs-documented-invocations.test.ts (1)

54-62: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use behavior-oriented titles and add the issue suffix.

Add (#8315) to the parent describe title. Rename the child titles to state the documented command behavior.

Proposed fix

-describe("documented sandbox logs invocations", () => {
+describe("sandbox logs commands documented in published pages run successfully (`#8315`)", () => {
@@
-  it("collects runnable logs invocations from the published pages", () => {
+  it("documents at least five runnable sandbox logs commands", () => {
@@
-    it(`runs the invocation documented at ${reference}`, ({ resources }) => {
+    it(`accepts the sandbox logs command documented at ${reference}`, ({ resources }) => {

As per coding guidelines, use behavior-oriented test titles and place local issue references in a final (#1234) suffix.

🤖 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 `@test/cli/logs-documented-invocations.test.ts` around lines 54 - 62, Update
the parent describe title in the documented logs invocation tests to include the
issue suffix (`#8315`), and rename the child test titles to describe the
documented command behavior rather than implementation details or references.
Keep each issue reference, if present, as the final suffix.

Source: Coding guidelines

🤖 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/reference/troubleshoot-mcp-servers.mdx`:
- Line 149: Update the lead-in sentence for the `logs` command to end with a
period, leaving the command block and surrounding documentation unchanged.

In `@test/cli/logs-documented-invocations.test.ts`:
- Around line 22-51: Remove the five inline if statements from walkMdxFiles and
documentedLogsInvocations. Replace directory/file exclusion and invocation
filtering with linear map/filter operations or named helper predicates,
preserving _build exclusion, recursive traversal, .mdx selection,
placeholder/shell-syntax skipping, and invocation construction.

---

Nitpick comments:
In `@test/cli/logs-documented-invocations.test.ts`:
- Around line 54-62: Update the parent describe title in the documented logs
invocation tests to include the issue suffix (`#8315`), and rename the child test
titles to describe the documented command behavior rather than implementation
details or references. Keep each issue reference, if present, as the final
suffix.

🪄 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: f91b43ba-031f-4ecd-9610-9cc08df8900b

📥 Commits

Reviewing files that changed from the base of the PR and between 2b90d18 and 952aa99.

📒 Files selected for processing (2)

• docs/reference/troubleshoot-mcp-servers.mdx
• test/cli/logs-documented-invocations.test.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections match; Nemotron reported the same number of blockers, 1 fewer warning, the same number of suggestions.

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

3 semantic terminology decisions

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

• established — sandbox log at docs/reference/troubleshoot-mcp-servers.mdx:148: Keep `sandbox log`; repository documentation already uses it for this log surface.
• established — OpenShell audit events at docs/reference/troubleshoot-mcp-servers.mdx:149: Keep `OpenShell audit events`; it matches the existing command and lifecycle documentation.
• justified — policy denial events at docs/reference/troubleshoot-mcp-servers.mdx:156: Keep `policy denial events`; the modifier identifies the affected troubleshooting evidence.

E2E guidance

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

Recommended E2E: None

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Document the `--since` log-source exception

• Location: docs/reference/troubleshoot-mcp-servers.mdx:149
• Category: docs
• Problem: The new statement says that `logs` reads both OpenClaw gateway output and OpenShell audit events, but `logs --since <duration>` deliberately skips the OpenClaw gateway source.
• Impact: Operators who use `--since` can expect gateway records that the command does not collect, which can misdirect incident diagnosis.
• Recommendation: Qualify the two-source statement with the `--since` exception, or change the supported `--since` path to collect the gateway source.
• Verification: Read `showSandboxLogsWithDeps` in `src/lib/actions/sandbox/logs.ts` with a non-null `logsOptions.since` value.
• Test coverage: Add a documentation or CLI behavior test that verifies the documented source behavior for `logs --since`.
• Evidence: docs/reference/troubleshoot-mcp-servers.mdx:149 says `logs` reads both OpenClaw gateway output and OpenShell audit events. src/lib/actions/sandbox/logs.ts:227-229 skips `runOpenclawGatewayLogs` when `logsOptions.since` is set. src/commands/sandbox/logs.ts:35-37 exposes `--since` as a supported flag.

Workflow run details

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

[apurvvkumaria]

Follow-up: all 41 current checks now pass, including aggregate CI, DCO, documentation review, CodeQL, both automated advisor lanes, and the E2E rollup. Both actionable review threads are resolved, and the independent documentation review found no further corrections. Independent approval is the only remaining merge gate.