Visitar URL original
docs(cli): split the doctor command reference by reader job by vincentkoc · Pull Request #142855 · openclaw/openclaw · GitHub
Skip to content

docs(cli): split the doctor command reference by reader job - #142855

Merged
vincentkoc merged 1 commit into
mainfrom
docs-audit/split-cli-doctor
Sep 9, 2026
Merged

vincentkoc merged 1 commit into
mainfrom
docs-audit/split-cli-doctor

Conversation

@vincentkoc

Copy link
Copy Markdown
Member

docs/cli/doctor.md was 65,756 characters across 17 H2 sections, mixing CLI reference, operator how-to, and plugin-author explanation on one page (audit finding r3-0103, blocking). It is now a short index over seven children, one per reader job.

Children

Page Sections moved
cli/doctor/running Postures, Examples, Options
cli/doctor/recovery Gateway service recovery, Remote Gateway recovery, Control UI assets, Invalid Gateway tokens, macOS launchctl env overrides
cli/doctor/lint Lint mode, Check selection, Post-upgrade mode
cli/doctor/health-contract Structured health checks (check authors, not operators)
cli/doctor/state-migrations Legacy state migration
cli/doctor/sqlite-maintenance Shared state SQLite compaction, Session SQLite migration
cli/doctor/checks Other checks and repairs (the former Notes)

Naming and index shape follow the landed docs/gateway/doctor/ split. Run doctor matches the sibling exactly, which is why it needed no new glossary entry.

Anchor preservation

Per-anchor redirects are not possible here: a path is not a fragment, and redirectSource() throws on any source containing [?#]. Every original anchor therefore stays alive on the parent index as an authored <a id="..." /> stub pointing at its new home, the same mechanism docs/gateway/doctor.md uses.

Ids were computed with parseDocsDocument, not a slug approximation. That matters for the punctuated heading macOS: `launchctl` env overrides, which mints both an encoded id (macos%3A-launchctl-env-overrides) and a cleaned one (macos-launchctl-env-overrides); both are stubbed.

  • 20 pre-split ids: 18 stubbed, 2 (openclaw-doctor, related) still published by the index itself and therefore deliberately not stubbed, which would otherwise raise duplicate authored/canonical ID.
  • All 20 verified to resolve against the post-split children by parsing the new index and each child and calling resolveDocsFragment, rather than relying on a passing link audit.
  • parseDocsDocument reports 0 collisions on the index and on all seven children.

Inbound anchor links from nine other pages (#session-sqlite-migration, #lint-mode, #downgrading-after-session-sqlite-migration) continue to resolve.

Losslessness

Asserted mechanically against the pre-split file, not by eye:

  • Fences 11 -> 11, every one byte-identical on both info string and body.
  • Table rows 49 -> 49 preserved, +8 for the new index page table.
  • Links: 16/16 original targets retained.
  • Words 8,391 -> 8,840 (+449: index page table, anchor map, and one orienting sentence per child).
  • Index 65,756 -> 5,859 chars; children range 3,208-15,772 chars.

Prose was not rewritten. The one declared exception is two orphaned directional cross-references whose targets moved to a different child, now real links:

  • "still follow the selected posture above" -> [posture](/cli/doctor/running#postures)
  • "subject to the mode's selection rules below" -> [selection rules](/cli/doctor/sqlite-maintenance#session-sqlite-migration)

A third directional reference ("the normal migration validation sequence above") stayed correct because both it and its target live in sqlite-maintenance.md.

Validation

check-docs-mdx passed on 1006 files. docs-link-audit reports broken_links=0 over 10,352 internal links. docs-link-audit --anchors reports the 3 pre-existing docs/maturity/* #windows-app-node failures and nothing else. format-docs --check, the i18n glossary check (6 new zh-CN entries, 0 duplicate sources), and markdownlint-cli2 are all clean.

Test lanes: render-maturity-docs, docs-source-anchors, and docs-sync-publish pass 20/20. The taxonomy validator matters here because taxonomy.yaml carries 8 references to docs/cli/doctor.md; all 8 are anchor-free and still resolve to the surviving cli/doctor route.

Notes for review

  • Duplication with docs/gateway/doctor/, recorded not fixed. The lint selector flags (--severity-min, --all, --only, --skip) are documented both in docs/gateway/doctor/running.md:147-151 and here, and the skills-readiness check is described both in docs/gateway/doctor/checks.md:78 and in this page's check inventory. No content was moved between the two trees.
  • docs/cli/doctor.md is not owned by @openclaw/openclaw-secops in .github/CODEOWNERS (that list covers approvals.md, sandbox.md, security.md, secrets.md only).
  • Deferred audit findings, all prose-shape work outside a mechanical split: r3-0104, r3-0105, r3-0106, r3-0107, r3-0109, r3-1150, r3-1151, r3-1152, r3-1153, r3-1154.

docs/cli/doctor.md was 65,756 characters and 17 H2 sections mixing CLI
reference, operator how-to, and plugin-author explanation. It is now a short
index over seven children, one per reader job:

- cli/doctor/running            Postures, Examples, Options
- cli/doctor/recovery           Gateway service, Remote Gateway, Control UI
                                assets, Invalid Gateway tokens, launchctl
- cli/doctor/lint               Lint mode, Check selection, Post-upgrade mode
- cli/doctor/health-contract    Structured health checks (check authors)
- cli/doctor/state-migrations   Legacy state migration
- cli/doctor/sqlite-maintenance Shared state compaction, Session SQLite
- cli/doctor/checks             Other checks and repairs

Anchor strategy: per-anchor routes are impossible here, because a path is not
a fragment and redirectSource() rejects any source containing [?#]. Every
original anchor therefore stays alive on the parent index as an authored
<a id="..." /> stub pointing at its new home. Ids were computed with
parseDocsDocument, not a slug approximation, so the punctuated heading
"macOS: `launchctl` env overrides" keeps both the encoded
(macos%3A-launchctl-env-overrides) and cleaned (macos-launchctl-env-overrides)
forms. 20 pre-split ids: 18 stubbed, 2 (openclaw-doctor, related) still
published by the index itself, so no duplicate authored/canonical ID is
raised. All 20 verified to resolve against the post-split children.

Losslessness, asserted mechanically against the pre-split file:
- fences 11 -> 11, every one byte-identical on info string and body
- table rows 49 -> 49 preserved (+8 for the new index page table)
- links: 16/16 original targets retained
- words 8,391 -> 8,840 (+449 = index page table, anchor map, child intros)
- index 65,756 -> 5,859 chars; children 3,208-15,772 chars

Prose was not rewritten. The one declared exception is two orphaned
directional cross-references whose targets moved to a different child, now
real links: "the selected posture above" -> /cli/doctor/running#postures, and
"the mode's selection rules below" ->
/cli/doctor/sqlite-maintenance#session-sqlite-migration.

Closes audit findings: r3-0103, r3-0108
@clawsweeper

clawsweeper Bot commented Sep 9, 2026 •

Copy link
Copy Markdown
Contributor

🦞👀
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.

@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation size: XS maintainer Maintainer-authored PR labels Sep 9, 2026
@clawsweeper clawsweeper Bot added P3 Low-priority cleanup, docs, polish, ergonomics, or speculative work. 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. labels Sep 9, 2026
@clawsweeper

clawsweeper Bot commented Sep 9, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed September 9, 2026, 1:35 AM ET / 05:35 UTC.

ClawSweeper review

What this changes

Splits the Doctor CLI reference into seven task-focused pages, preserving old section links and adding navigation and translation glossary entries.

Merge readiness

✅ Ready for maintainer review

The split remains useful: pinned main still has the single-page reference, and the branch preserves its substantive content and section destinations. No actionable introduced defect was found; this maintainer-authored PR should remain on the normal review path.

Priority: P3
Reviewed head: 6df8d41fb3c899fb00c84a9866c6ca25d1a0f2d3

Review scores

Measure Result What it means
Overall readiness 🐚 platinum hermit (4/6) A focused documentation split with preserved content, compatible section links, and detailed reported validation.
Proof confidence 🌊 off-meta tidepool Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality 🐚 platinum hermit (4/6) No actionable review findings were identified.

Verification

Check Result Evidence
Real behavior Not applicable Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Evidence reviewed 6 items Pinned scope and current state: The introduced delta contains only documentation, navigation, and glossary changes. The live REST response confirms the PR remains open and unmerged at the reviewed head.
Content preservation: Independent whitespace-normalized paragraph comparison found only the two declared cross-reference edits. Reading their destinations confirmed both now point to the moved content.
Existing link compatibility: The parent retains explicit section anchors, including both macOS heading forms, and links them to the corresponding child sections. The publishing parser reserves authored HTML IDs and supports encoded fragment resolution.
Findings None None.
Security None None.

How this fits together

The Doctor documentation helps operators choose diagnostic and repair commands and helps plugin authors understand health checks. The documentation index routes readers to focused instructions while preserving existing incoming links.

flowchart TD
  A[Documentation navigation] --> C[Doctor reference index]
  B[Existing section links] --> C
  C --> D[Choose a reader task]
  D --> E[Run and diagnose]
  D --> F[Recover and migrate state]
  D --> G[Author health checks]
Loading

Before merge

None.

Agent review details

Security

None.

PR surface

Docs +146. Total +146 across 10 files.

View PR surface stats
Area Files Added Removed Net
Source 0 0 0 0
Tests 0 0 0 0
Docs 10 862 716 +146
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 10 862 716 +146

Review metrics

None.

Technical review

Best possible solution:

Retain the task-focused reference pages with stable legacy anchors and explicit links between related operator instructions.

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

Not applicable: this is a documentation reorganization; the original mixed-purpose page and its replacement structure are directly inspectable.

Is this the best way to solve the issue?

Yes. The split follows the existing Gateway Doctor documentation pattern, preserves substantive guidance, and repairs the two cross-page directional references.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

  • add P3: This improves documentation navigation without changing runtime behavior, configuration, or stored data.
  • 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/.

Label justifications:

  • P3: This improves documentation navigation without changing runtime behavior, configuration, or stored data.
  • 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

What I checked:

  • Pinned scope and current state: The introduced delta contains only documentation, navigation, and glossary changes. The live REST response confirms the PR remains open and unmerged at the reviewed head. (6df8d41fb3c8)
  • Content preservation: Independent whitespace-normalized paragraph comparison found only the two declared cross-reference edits. Reading their destinations confirmed both now point to the moved content. Public docs: docs/cli/doctor.md. (docs/cli/doctor.md:33, 6df8d41fb3c8)
  • Existing link compatibility: The parent retains explicit section anchors, including both macOS heading forms, and links them to the corresponding child sections. The publishing parser reserves authored HTML IDs and supports encoded fragment resolution. (scripts/lib/docs-markdown.mjs:421, 6df8d41fb3c8)
  • Still necessary on main: Pinned main retains the original Postures, Options, Lint, recovery, migration, and other-check sections in the single CLI page. The Gateway documentation split is an adjacent precedent, not a replacement for this work. No release inclusion is claimed. Public docs: docs/cli/doctor.md. (docs/cli/doctor.md:33, 1ab71b84dc29)
  • Merged documentation precedent: GitHub verifies docs(gateway): split the doctor page by reader job #141961 was authored by vincentkoc and merged on September 8. Its commit adds the task-focused Gateway Doctor index now present at lines 12–13, establishing relevant prior area work beyond this proposal. Public docs: docs/gateway/doctor.md. (docs/gateway/doctor.md:12, 4c0f520506d1)
  • Validation and review limits: The introduced diff passes git diff --check. The supplied PR body reports successful MDX, glossary, formatting, link, and focused documentation checks, with three unrelated existing anchor failures. Those repository checks were not rerun under this read-only review; the checkout remains clean. (6df8d41fb3c8)

Likely related people:

  • unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; 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.

@vincentkoc
vincentkoc merged commit b04a3f8 into main Sep 9, 2026
67 checks passed
@vincentkoc
vincentkoc deleted the docs-audit/split-cli-doctor branch September 9, 2026 05:39
vincentkoc added a commit that referenced this pull request Sep 9, 2026
The cli/doctor split (#142855) landed; the shared zh-CN glossary
conflicted. Union keyed on source: base 797, branch 794, merged 800
entries, 0 duplicate sources. No cli/update page conflicted, so main's
changes needed no re-extraction.

Re-checked after the merge: the 5 directional references are the ones
verified same-page before the rebase, and docs-link-audit --anchors
reports only the 3 pre-existing #windows-app-node failures on
docs/maturity/*, which this PR does not touch.
vincentkoc added a commit to LiuwqGit/openclaw that referenced this pull request Sep 9, 2026
…1-prep

* commit 'b04a3f83adad8bd6a2ca8408e7940fc6bcbde212': (636 commits)
  docs(cli): split the doctor command reference by reader job (openclaw#142855)
  fix(ui): explain paused weekly skill reviews (openclaw#142840)
  docs(automations): describe supported schedule options (openclaw#135964)
  fix(image): close registration resources after generation (openclaw#142843)
  fix(slack): keep ack reactions independent of status reactions (openclaw#142595)
  fix(ui): avoid flashes when switching cold sessions (openclaw#134868)
  refactor(tests): share independent no-queued-reply expectations (openclaw#142845)
  perf: reduce generated media reference formatting overhead (openclaw#142836)
  fix: sessions_yield keeps long transcript history available (openclaw#137381)
  fix(music): close registration resources after generation (openclaw#142834)
  fix: update confirmation shows stale commit counts after refresh (openclaw#142837)
  fix(ci): retain Android emulator post-timeout evidence (openclaw#142835)
  fix(talk): retain final delivery across delegation waves (openclaw#142830)
  docs(gateway): run Linux system services as the state owner (openclaw#136266)
  fix(models): align static Anthropic aliases with manifest (openclaw#137376)
  test(gateway): simplify session lifecycle gates and report early rollback failures (openclaw#142833)
  refactor(ai): keep model policy parsing independent of transport host (openclaw#142804)
  refactor: simplify interactive SDK forwarding (openclaw#142824)
  fix(cli): finish pending cleanup before automatic macOS exit (openclaw#142814)
  docs(memory-lancedb): clarify enforced compatibility ranges (openclaw#142827)
  ...
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request Sep 10, 2026
…#142855)

docs/cli/doctor.md was 65,756 characters and 17 H2 sections mixing CLI
reference, operator how-to, and plugin-author explanation. It is now a short
index over seven children, one per reader job:

- cli/doctor/running            Postures, Examples, Options
- cli/doctor/recovery           Gateway service, Remote Gateway, Control UI
                                assets, Invalid Gateway tokens, launchctl
- cli/doctor/lint               Lint mode, Check selection, Post-upgrade mode
- cli/doctor/health-contract    Structured health checks (check authors)
- cli/doctor/state-migrations   Legacy state migration
- cli/doctor/sqlite-maintenance Shared state compaction, Session SQLite
- cli/doctor/checks             Other checks and repairs

Anchor strategy: per-anchor routes are impossible here, because a path is not
a fragment and redirectSource() rejects any source containing [?#]. Every
original anchor therefore stays alive on the parent index as an authored
<a id="..." /> stub pointing at its new home. Ids were computed with
parseDocsDocument, not a slug approximation, so the punctuated heading
"macOS: `launchctl` env overrides" keeps both the encoded
(macos%3A-launchctl-env-overrides) and cleaned (macos-launchctl-env-overrides)
forms. 20 pre-split ids: 18 stubbed, 2 (openclaw-doctor, related) still
published by the index itself, so no duplicate authored/canonical ID is
raised. All 20 verified to resolve against the post-split children.

Losslessness, asserted mechanically against the pre-split file:
- fences 11 -> 11, every one byte-identical on info string and body
- table rows 49 -> 49 preserved (+8 for the new index page table)
- links: 16/16 original targets retained
- words 8,391 -> 8,840 (+449 = index page table, anchor map, child intros)
- index 65,756 -> 5,859 chars; children 3,208-15,772 chars

Prose was not rewritten. The one declared exception is two orphaned
directional cross-references whose targets moved to a different child, now
real links: "the selected posture above" -> /cli/doctor/running#postures, and
"the mode's selection rules below" ->
/cli/doctor/sqlite-maintenance#session-sqlite-migration.

Closes audit findings: r3-0103, r3-0108
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Improvements or additions to documentation maintainer Maintainer-authored PR 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.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant