docs: give pages with duplicate titles distinct names by vincentkoc · Pull Request #140208 · openclaw/openclaw

vincentkoc · 2026-09-06T15:19:31Z

What

Renames the frontmatter title: on 13 CLI pages so no two pages share a title. One line per file, no prose or route changes.

Why

A frontmatter scan over git ls-files docs found 22 titles shared by two or more pages. Search results, breadcrumbs, and the sidebar showed two identical entries with no way to tell them apart, for example docs/cli/hooks.md and docs/automation/hooks.md both titled Hooks.

The topic page keeps the plain title. The command-scoped CLI page takes the disambiguated one, matching the style already used by its siblings in docs/cli (Attach CLI, Inference CLI, Sandbox CLI).

Out of scope, deliberately

8 plugin-page pairs (beam, geolocation, google-meet, logbook, teams-meetings, webhooks, workboard, zoom-meetings): the second page in each pair is a generated stub under docs/plugins/reference/. The fix belongs in scripts/generate-plugin-inventory-doc.mts, not in a hand edit.
docs/reference/templates/CLAUDE.md, which is a byte-identical copy of AGENTS.md. That needs a delete-or-differentiate decision and a redirect, so it is a separate change.

Validation

node scripts/check-docs-mdx.mjs docs README.md      # passed, 753 files
node scripts/docs-link-audit.mjs                    # 8203 links, 0 broken

Duplicate-title count after the change: 22 to 9, and every remaining pair is one of the deferred cases above.

Found during a full documentation audit.

Several pages shared a frontmatter title with another page, so search results, breadcrumbs and the sidebar showed two identical entries with no way to tell them apart. The topic page keeps the plain title; the command-scoped CLI page takes the disambiguated one, matching the existing sibling style in docs/cli (Attach CLI, Inference CLI, Sandbox CLI, Transcripts CLI, Workboard CLI). - docs/cli/dashboard.md: Dashboard -> Dashboard CLI (vs docs/web/dashboard.md) - docs/cli/doctor.md: Doctor -> Doctor CLI (vs docs/gateway/doctor.md) - docs/cli/hooks.md: Hooks -> Hooks CLI (vs docs/automation/hooks.md) - docs/cli/nodes.md: Nodes -> Nodes CLI (vs docs/nodes/index.md) - docs/cli/pairing.md: Pairing -> Pairing CLI (vs docs/channels/pairing.md) - docs/cli/plugins.md: Plugins -> Plugins CLI (vs docs/tools/plugin.md) - docs/cli/secrets.md: Secrets -> Secrets CLI (vs docs/tools/secrets.md) - docs/cli/security.md: Security -> Security CLI (vs docs/gateway/security/index.md) - docs/cli/setup.md: Setup -> Setup CLI (vs docs/start/setup.md) - docs/cli/skills.md: Skills -> Skills CLI (vs docs/tools/skills.md) - docs/cli/tui.md: TUI -> openclaw tui (vs docs/web/tui.md); "TUI CLI" stacks two acronyms, so this page uses the command-name style already used by docs/cli/status.md and docs/cli/tasks.md - docs/cli/uninstall.md: Uninstall -> Uninstall CLI (vs docs/install/uninstall.md) - docs/plugins/onepassword.md: 1Password -> 1Password plugin, matching the "<Name> plugin" style of its siblings (vs the docs/gateway/1password.md hub) No H1, filename, route, nav entry or docs/docs.json change. Closes audit findings: r4-title-001, r4-title-004, r4-title-005, r4-title-007, r4-title-010, r4-title-011, r4-title-012, r4-title-013, r4-title-014, r4-title-015, r4-title-016, r4-title-017, r4-title-018

clawsweeper · 2026-09-06T15:19:34Z

🦞👀
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 · 2026-09-06T15:25:22Z

Codex review: needs changes before merge. Reviewed September 6, 2026, 11:24 AM ET / 15:24 UTC.

ClawSweeper review

What this changes

Disambiguates titles on twelve CLI reference pages and the 1Password plugin page without changing their URLs or instructions.

Merge readiness

⛔ Needs changes before merge - 2 items remain

The title cleanup remains useful on current main, but missing translation-glossary entries cause a concrete docs-validation failure. Maintainer authorship and protected labels also exclude automatic closure.

Priority: P3
Reviewed head: fed697e692dfe011ef0fe9c3ac019bfdced65be2

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	A focused and useful documentation cleanup needs one mechanical glossary repair before it is ready.
Proof confidence	🌊 off-meta tidepool	Not applicable: Real behavior proof is not required because this PR only changes files under docs/.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

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	Introduced change and whitespace validation: The pinned merge-base-to-head diff changes only frontmatter titles; its git diff --check completed successfully. The supplied verified test-merge evidence retains the same thirteen-file scope. Current main still contains ambiguous titles: Current main gives both the dashboard CLI and web dashboard pages the title Dashboard, and both the CLI and automation hooks pages the title Hooks. Existing Attach CLI and Sandbox CLI titles support the proposed naming convention. The inspected latest-release hooks page also retains Hooks. Missing glossary entries survive the merge: Only Plugins CLI and Nodes CLI are present among the thirteen proposed titles in the verified test merge's zh-CN glossary. A separate read-only JSON comparison confirmed the eleven missing entries. Main and head have identical glossary-check implementation and glossary contents.
Findings	1 actionable finding	[P2] Add glossary entries for the renamed page titles
Security	None	None.

How this fits together

OpenClaw publishes Markdown documentation using page metadata for reader-facing titles. Changed titles also pass through a translation-glossary check before publication.

flowchart LR
  A[Documentation pages] --> B[Distinct page titles]
  B --> C[Translation glossary check]
  C --> D[Documentation publication]
  D --> E[Reader navigation and search]

Before merge

Add glossary entries for the renamed page titles (P2) - Eleven new titles, including Dashboard CLI, are absent from docs/.i18n/glossary.zh-CN.json; only Nodes CLI and Plugins CLI already exist. scripts/check-docs-i18n-glossary.mts requires exact glossary entries for newly introduced titles and exits 1 when they are missing, so these changes fail pnpm check:docs. Add the eleven source/translation entries without weakening the checker.
Complete next step (P2) - Add translations for the eleven missing title terms in docs/.i18n/glossary.zh-CN.json and pass pnpm docs:check-i18n-glossary.

Findings

[P2] Add glossary entries for the renamed page titles — docs/cli/dashboard.md:6

Agent review details

Security

None.

PR surface

Docs 0. Total 0 across 13 files.

View PR surface stats

Area	Files	Added	Removed
Source	0	0	0
Tests	0	0	0
Docs	13	13	13
Config	0	0	0
Generated	0	0	0
Other	0	0	0
Total	13	13	13

Review metrics

Metric	Value	Why it matters
Title translation coverage	11 renamed titles lack glossary entries; 2 already covered	The existing docs gate requires exact glossary coverage for each newly introduced title.

Technical review

Best possible solution:

Keep the distinct titles and supply their missing translations in the existing glossary while preserving routes, headings, and generated-page ownership.

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

Yes, by source inspection: eleven new titles fail the checker's exact glossary lookup and reach its failure exit. The repository checker was not executed during this read-only review.

Is this the best way to solve the issue?

Yes, title-only disambiguation fits existing documentation conventions; completing the established translation glossary is the narrow remaining repair.

Full review comments:

[P2] Add glossary entries for the renamed page titles — docs/cli/dashboard.md:6
Eleven new titles, including Dashboard CLI, are absent from docs/.i18n/glossary.zh-CN.json; only Nodes CLI and Plugins CLI already exist. scripts/check-docs-i18n-glossary.mts requires exact glossary entries for newly introduced titles and exits 1 when they are missing, so these changes fail pnpm check:docs. Add the eleven source/translation entries without weakening the checker.
Confidence: 0.99

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

add P3: This is a bounded documentation discoverability improvement with no runtime change.
add rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
add status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Label justifications:

P3: This is a bounded documentation discoverability improvement with no runtime change.
rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: Real behavior proof is not required because this PR only changes files under docs/.

Evidence

What I checked:

Introduced change and whitespace validation: The pinned merge-base-to-head diff changes only frontmatter titles; its git diff --check completed successfully. The supplied verified test-merge evidence retains the same thirteen-file scope. Public docs: docs/cli/dashboard.md. (docs/cli/dashboard.md:6, fed697e692df)
Current main still contains ambiguous titles: Current main gives both the dashboard CLI and web dashboard pages the title Dashboard, and both the CLI and automation hooks pages the title Hooks. Existing Attach CLI and Sandbox CLI titles support the proposed naming convention. The inspected latest-release hooks page also retains Hooks. Public docs: docs/cli/hooks.md. (docs/cli/hooks.md:7, c367c68577c3)
Missing glossary entries survive the merge: Only Plugins CLI and Nodes CLI are present among the thirteen proposed titles in the verified test merge's zh-CN glossary. A separate read-only JSON comparison confirmed the eleven missing entries. Main and head have identical glossary-check implementation and glossary contents. Public docs: docs/.i18n/glossary.zh-CN.json. (docs/.i18n/glossary.zh-CN.json:907, 6b5aa987679f)
Source-proven validation failure: The checker extracts short Latin-script titles, requires an exact glossary source for newly introduced terms, and exits with status 1 when entries are missing. package.json includes this checker in check:docs, which CI invokes. The checker itself was inspected, not executed. (scripts/check-docs-i18n-glossary.mts:211, fed697e692df)
Relevant history and inspection limits: Current-main history records Vincent Koc's prior maintenance of the glossary checker and Peter Steinberger's earlier script migration. Deeper follow/blame inspection encountered unavailable historical objects; introduction attribution remains unverified. No maintainer-notes directory exists in this checkout. (scripts/check-docs-i18n-glossary.mts, 63f265c0ddb9)
Policy and supplied discussion: Root and docs AGENTS.md were read fully. Docs policy explicitly requires glossary coverage for changed English titles and reserves generated plugin-reference pages for their generator, consistent with the PR's deliberate deferral. The supplied discussion contains no substantive human review comments; the author reports MDX and link checks, but not the glossary check. Public docs: docs/AGENTS.md. (docs/AGENTS.md, fed697e692df)

Likely related people:

Vincent Koc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
Peter Steinberger: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

Add the eleven missing zh-CN glossary entries and pass the docs glossary check.

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.

Several pages shared a frontmatter title with another page, so search results, breadcrumbs and the sidebar showed two identical entries with no way to tell them apart. The topic page keeps the plain title; the command-scoped CLI page takes the disambiguated one, matching the existing sibling style in docs/cli (Attach CLI, Inference CLI, Sandbox CLI, Transcripts CLI, Workboard CLI). - docs/cli/dashboard.md: Dashboard -> Dashboard CLI (vs docs/web/dashboard.md) - docs/cli/doctor.md: Doctor -> Doctor CLI (vs docs/gateway/doctor.md) - docs/cli/hooks.md: Hooks -> Hooks CLI (vs docs/automation/hooks.md) - docs/cli/nodes.md: Nodes -> Nodes CLI (vs docs/nodes/index.md) - docs/cli/pairing.md: Pairing -> Pairing CLI (vs docs/channels/pairing.md) - docs/cli/plugins.md: Plugins -> Plugins CLI (vs docs/tools/plugin.md) - docs/cli/secrets.md: Secrets -> Secrets CLI (vs docs/tools/secrets.md) - docs/cli/security.md: Security -> Security CLI (vs docs/gateway/security/index.md) - docs/cli/setup.md: Setup -> Setup CLI (vs docs/start/setup.md) - docs/cli/skills.md: Skills -> Skills CLI (vs docs/tools/skills.md) - docs/cli/tui.md: TUI -> openclaw tui (vs docs/web/tui.md); "TUI CLI" stacks two acronyms, so this page uses the command-name style already used by docs/cli/status.md and docs/cli/tasks.md - docs/cli/uninstall.md: Uninstall -> Uninstall CLI (vs docs/install/uninstall.md) - docs/plugins/onepassword.md: 1Password -> 1Password plugin, matching the "<Name> plugin" style of its siblings (vs the docs/gateway/1password.md hub) No H1, filename, route, nav entry or docs/docs.json change. Closes audit findings: r4-title-001, r4-title-004, r4-title-005, r4-title-007, r4-title-010, r4-title-011, r4-title-012, r4-title-013, r4-title-014, r4-title-015, r4-title-016, r4-title-017, r4-title-018

vincentkoc requested a review from a team as a code owner September 6, 2026 15:19

openclaw-barnacle Bot added docs Improvements or additions to documentation security Security documentation extensions: onepassword 1Password plugin size: XS maintainer Maintainer-authored PR labels Sep 6, 2026

vincentkoc merged commit c16d479 into main Sep 6, 2026
67 checks passed

vincentkoc deleted the docs-audit/pr-005 branch September 6, 2026 15:25

vincentkoc mentioned this pull request Sep 6, 2026

docs(plugins): mark generated reference pages and fix their shared template #140254

Merged

Navigation Menu

Repository navigation

docs: give pages with duplicate titles distinct names - #140208

docs: give pages with duplicate titles distinct names#140208
vincentkoc merged 1 commit into
mainfrom
docs-audit/pr-005

vincentkoc commented Sep 6, 2026

Uh oh!

clawsweeper Bot commented Sep 6, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Sep 6, 2026

Security

PR surface

Review metrics

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

vincentkoc commented Sep 6, 2026

What

Why

Out of scope, deliberately

Validation

Uh oh!

clawsweeper Bot commented Sep 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

ClawSweeper review complete

Uh oh!

clawsweeper Bot commented Sep 6, 2026

ClawSweeper review

What this changes

Merge readiness

Review scores

Verification

How this fits together

Before merge

Findings

Security

PR surface

Review metrics

Technical review

Labels

Evidence

Rank-up moves

Rating scale

Workflow

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

clawsweeper Bot commented Sep 6, 2026 •

edited

Loading