feat: render clawctl help from the live command tree

[paulcam206]

Impact

Renders clawctl help from the live command tree using the same heading, layout, and color policy as other commands.

Why This Change Was Made

Help remains synchronized with parser commands and options, including inherited options. Malformed --no-color values now retain ordinary parse-error or explicit-help output instead of escaping through the unexpected-failure boundary.

Evidence

Validated at 9daa288:

• Malformed color/help regressions: 2 passed
• .\scripts\Test-DotNetQuality.ps1 on the complete stack
• .\scripts\Test-NativeAotCli.Tests.ps1: 17 intended scenarios passed
• GitHub CI runs on the current head

Stack

1. feat/clawctl json #69 JSON
2. feat: render clawctl help from the live command tree #70 dynamic help (this PR)
3. feat: report the package and payload build identity from clawctl --version #71 build identity
4. feat: wait for the gateway and report where it is listening #72 narrated gateway startup

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs changes before merge. Reviewed September 17, 2026, 10:35 PM ET / September 18, 2026, 02:35 UTC (Revision 4).

ClawSweeper review

What this changes

Renders clawctl help from its command definitions using the launcher's shared layout and color policy, with regression coverage for malformed color options.

Merge readiness

⛔ Needs changes before merge - 1 item remains

The change remains useful and is absent from current main. The previous malformed-color finding is resolved, and this review found no new blocking defect.

Priority: P3
Reviewed head: 9daa2882b0d0cecfb9d4c1cc60caedc9eb7859d9

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused implementation with relevant regression coverage and no remaining concrete correctness finding.
Proof confidence	🌊 off-meta tidepool	Not applicable: The collaborator-authored PR is exempt from the external proof gate and changes no authority boundary; its reported NativeAOT help scenarios exercise the relevant production entrypoint and renderer.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The collaborator-authored PR is exempt from the external proof gate and changes no authority boundary; its reported NativeAOT help scenarios exercise the relevant production entrypoint and renderer.
Evidence reviewed	7 items	Verified introduced scope: The pinned parent-to-head comparison contains seven files: help implementation, shared rendering changes, documentation, and tests. Production changes total +293/-19 lines; tests add 183 lines. Current main still uses library help: Current main invokes System.CommandLine HelpAction directly; it does not include the proposed shared help renderer. The existing parser already supplies command metadata, so this PR's distinct contribution is consistent presentation. Latest release also retains library help: GitHub identifies v2026.9.4-msix.1 at ad5df93 as the latest release. Its command-line source likewise invokes HelpAction directly; the requested presentation has not shipped there.
Findings	None	None.
Security	None	None.

How this fits together

clawctl manages the packaged Windows environment around OpenClaw. Its parser supplies command descriptions and options to the help renderer, which prints guidance without running installation or gateway operations.

flowchart LR
  A[Help request] --> B[Command parser]
  B --> C[Selected command tree]
  C --> D[Visible commands and inherited options]
  D --> E[Shared console renderer]
  F[Terminal color policy] --> E
  E --> G[Help text]

Loading

Before merge

• Complete next step (P2) - Mark the draft ready when intended and follow the bottom-up stack process: retarget this PR to main before feat/clawctl json #69 merges, then land it after that parent.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production +293/-19; tests +183/-0	Production growth implements the stated shared help presentation and reuses the existing parser and console.

Technical review

Best possible solution:

Keep command metadata in the parser and use the shared renderer for consistent help while preserving discovery, parse-error, and color behavior.

Do we have a high-confidence way to reproduce the issue?

Not applicable to the presentation feature; the earlier malformed-color defect has focused regression coverage, but tests were not run in this read-only review.

Is this the best way to solve the issue?

Yes. Replacing the help action while deriving content from the existing parser avoids a second command catalogue and reuses the established console presentation.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against b904c90c1439.

Labels

Label justifications:

• P3: This improves CLI help presentation without changing operational commands or stored settings.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The collaborator-authored PR is exempt from the external proof gate and changes no authority boundary; its reported NativeAOT help scenarios exercise the relevant production entrypoint and renderer.

Evidence

What I checked:

• Verified introduced scope: The pinned parent-to-head comparison contains seven files: help implementation, shared rendering changes, documentation, and tests. Production changes total +293/-19 lines; tests add 183 lines. (9daa2882b0d0)
• Current main still uses library help: Current main invokes System.CommandLine HelpAction directly; it does not include the proposed shared help renderer. The existing parser already supplies command metadata, so this PR's distinct contribution is consistent presentation. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs, b904c90c1439)
• Latest release also retains library help: GitHub identifies v2026.9.4-msix.1 at ad5df93 as the latest release. Its command-line source likewise invokes HelpAction directly; the requested presentation has not shipped there. (src/OpenClaw.Launcher/ClawCtlCommandLine.cs, ad5df933da4f)
• Previous finding resolved: The help action catches InvalidOperationException when reading malformed --no-color values and disables color. Added tests exercise ordinary parse failure and explicit help through Program.RunControlAsync, checking exit codes, usage output, and absence of unexpected-failure diagnostics. (src/OpenClaw.Launcher/ClawCtlHelp.cs:173, 9daa2882b0d0)
• Relevant native validation: The captured PR body reports two malformed-color regressions and 17 NativeAOT scenarios passing at the reviewed head. The inspected native harness exercises bare invocation, --help, and setup --help through the production entrypoint, checks output, and verifies installation work does not start. These claims were not independently executed during this read-only review. (tests/OpenClaw.Launcher.AotSmoke/SmokeProgram.cs:98, 9daa2882b0d0)
• Stack landing requirements: CONTRIBUTING.md requires validation against the immediate parent, bottom-up merging, and retargeting the child before its parent merges. Live GitHub metadata confirms this PR remains draft and targets the open JSON parent at feat/clawctl json #69. (CONTRIBUTING.md:239, 9daa2882b0d0)

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (3 earlier review cycles)

• reviewed 2026-09-18T01:10:09.474Z sha 257ebf5 :: blocked before merge. :: [P2] Handle invalid color values before reading them in help
• reviewed 2026-09-18T01:54:32.016Z sha e2cb02d :: needs maintainer review before merge. :: none
• reviewed 2026-09-18T02:09:13.701Z sha 0f31faa :: needs changes before merge. :: none

[clawsweeper]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: feat: render clawctl help from the live command tree This is item 1/1 in the current shard. Shard 0/1.

This placeholder means the worker is alive and reading the current context. I will edit this same comment with the actual review when the claws are done clicking.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.