Skip to content

docs(browser): clarify JSON flag placement#103155

Merged
steipete merged 2 commits into
openclaw:mainfrom
soldforaloss:contrib/soldforaloss/browser-json-docs
Jul 12, 2026
Merged

docs(browser): clarify JSON flag placement#103155
steipete merged 2 commits into
openclaw:mainfrom
soldforaloss:contrib/soldforaloss/browser-json-docs

Conversation

@soldforaloss

@soldforaloss soldforaloss commented Jul 9, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What Problem This Solves

The browser CLI reference described --json as a common flag without explaining the preferred placement or the supported trailing compatibility path. One browser tool page also showed the trailing openclaw browser status --json form without clarifying the canonical browser-level form.

AI-assisted: yes.

Why This Change Was Made

This updates the browser CLI reference to show openclaw browser --json status as the canonical form while noting that trailing placement, such as openclaw browser status --json, remains supported when the selected child command does not define its own --json. The matching browser tool page now uses the same distinction. The change is docs-only and does not alter CLI behavior.

User Impact

Users following the browser docs get the preferred command form without being told that the supported trailing form is invalid.

Evidence

  • git diff --check
  • OPENCLAW_CHECK_CHANGED_REMOTE_CHILD=1 pnpm check:changed -- docs/cli/browser.md docs/tools/browser.md
  • Verified the edited docs mention both canonical openclaw browser --json status and supported trailing openclaw browser status --json for non-colliding child commands.
  • ACP Codex review was unavailable due to authentication; local Codex CLI fallback was logged in but timed out before returning review results.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS triage: low-signal-docs Candidate: docs-only change looks low signal; maintainer review needed. labels Jul 9, 2026
@soldforaloss
soldforaloss force-pushed the contrib/soldforaloss/browser-json-docs branch from 0a230c9 to c003deb Compare July 10, 2026 04:29
@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. labels Jul 10, 2026
@clawsweeper

clawsweeper Bot commented Jul 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed July 10, 2026, 11:20 PM ET / July 11, 2026, 03:20 UTC.

Summary
Clarifies in two browser documentation pages that parent-first --json placement is preferred while trailing placement remains supported when the selected child command does not own the same option.

PR surface: Docs +5. Total +5 across 2 files.

Reproducibility: not applicable. as a runtime bug report. The documented option-order behavior is nevertheless high-confidence from current parser source, focused tests, Commander 15 source, and the merged implementation proof.

Review metrics: none identified.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🌊 off-meta tidepool
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • none.

Risk before merge

  • [P1] The branch is mergeable but behind the current base, so maintainers should refresh or otherwise gate the final merged result against current main before landing.

Maintainer options:

  1. Decide the mitigation before merge
    Land the revised dual-order clarification after normal current-base and exact-head checks, keeping parent-first as the documentation convention without implying that supported trailing placement is invalid.
  2. Pause or close
    Do not merge this PR until maintainers decide whether the risk is worth taking.

Next step before merge

  • No automated repair is needed; maintainers should apply normal current-base refresh and merge gating.

Security
Cleared: The Markdown-only diff introduces no executable code, dependency, permission, credential, downloaded-artifact, publishing, or supply-chain change.

Review details

Best possible solution:

Land the revised dual-order clarification after normal current-base and exact-head checks, keeping parent-first as the documentation convention without implying that supported trailing placement is invalid.

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

Not applicable as a runtime bug report. The documented option-order behavior is nevertheless high-confidence from current parser source, focused tests, Commander 15 source, and the merged implementation proof.

Is this the best way to solve the issue?

Yes. Updating the existing browser CLI and tool references is the narrowest maintainable solution, and the revised wording now accurately distinguishes the recommended convention from the supported compatibility path.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against ffc8051cacb5.

Label changes

Label changes:

  • add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
  • add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
  • remove rating: 🦐 gold shrimp: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.
  • remove status: ⏳ waiting on author: Current PR status label is status: 👀 ready for maintainer look.

Label justifications:

  • P3: This is a narrow, low-risk documentation accuracy improvement with no runtime behavior change.
  • 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: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed

PR surface:

Docs +5. Total +5 across 2 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 2 8 3 +5
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 2 8 3 +5

What I checked:

Likely related people:

  • steipete: Performed the maintainer rewrite, black-box validation, and merge of the lazy parent-option compatibility implementation documented by this PR. (role: reviewer, rewrite author, and merger of related behavior; confidence: high; commits: c1f9087e8e84; files: src/cli/program/action-reparse.ts, src/cli/program/action-reparse.test.ts, extensions/browser/src/cli/browser-cli.lazy.test.ts)
  • ml12580: Authored the related merged CLI repair and its regression evidence for parent options placed after lazy browser subcommands. (role: original implementation contributor; confidence: high; commits: abb859ee23f9, c1f9087e8e84; files: src/cli/program/action-reparse.ts, src/cli/program/action-reparse.test.ts, extensions/browser/src/cli/browser-cli.lazy.test.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works
  • 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.
Review history (2 earlier review cycles)
  • reviewed 2026-07-10T07:28:04.839Z sha c003deb :: needs changes before merge. :: [P2] Avoid requiring an option order the CLI supports
  • reviewed 2026-07-11T00:48:58.710Z sha db806e3 :: needs changes before merge. :: [P2] Avoid requiring an option order the CLI supports

@soldforaloss
soldforaloss force-pushed the contrib/soldforaloss/browser-json-docs branch from db806e3 to 82dde7a Compare July 11, 2026 03:00
@clawsweeper clawsweeper Bot added rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels Jul 11, 2026
@steipete steipete self-assigned this Jul 11, 2026
@steipete
steipete force-pushed the contrib/soldforaloss/browser-json-docs branch from 82dde7a to ef7bcdc Compare July 12, 2026 05:56
@steipete

steipete commented Jul 12, 2026

Copy link
Copy Markdown
Contributor

Maintainer refresh and verification are complete on ef7bcdc0d39.

I kept the contributor's dual-order clarification, rebased it onto current main, and made the convention consistent across the browser CLI, browser tool, and browser-control JSON examples. The wording now calls parent-first placement unambiguous rather than implying that trailing placement is invalid.

Contract verification:

  • Read the current lazy-command reparse path in src/cli/program/action-reparse.ts: browser-level options after a lazily loaded child are hoisted unless the selected child owns the same option.
  • Read the focused coverage in src/cli/program/action-reparse.test.ts and extensions/browser/src/cli/browser-cli.lazy.test.ts, including nested commands and child-option collisions.
  • Built the exact refreshed head with OPENCLAW_BUILD_ALL_NO_PNPM=1 node scripts/build-all.mjs qaRuntime.
  • Started an isolated Gateway from that build and ran both documented forms against it:
    • openclaw browser --json status
    • openclaw browser status --json
  • Both returned the same structured status fields: profile=openclaw, enabled=true, running=false, transport=cdp, headless=false, headlessSource=default.

Docs verification:

  • node scripts/format-docs.mjs --check — 699 files clean.
  • node scripts/check-docs-mdx.mjs docs/cli/browser.md docs/tools/browser.md docs/tools/browser-control.md — passed.
  • node scripts/docs-link-audit.mjs — 5,891 internal links checked, 0 broken.
  • git diff --check — passed.
  • Fresh Codex autoreview — no findings; patch is correct, confidence 0.99.

@steipete
steipete merged commit 5459a94 into openclaw:main Jul 12, 2026
39 checks passed
@steipete

steipete commented Jul 12, 2026

Copy link
Copy Markdown
Contributor

Merged via squash.

github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Jul 12, 2026
@soldforaloss @steipete
docs(browser): clarify JSON flag placement (openclaw#103155)
3fb5c30 
* docs(browser): clarify JSON flag placement

* docs(browser): align JSON flag examples

---------

Co-authored-by: Peter Steinberger <[email protected]>
@github-actions github-actions Bot mentioned this pull request Jul 12, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@steipete steipete

Labels

docs Improvements or additions to documentation P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: XS status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. triage: low-signal-docs Candidate: docs-only change looks low signal; maintainer review needed.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@soldforaloss @steipete