docs: fix the package publish anchor that breaks on the published site

[vincentkoc]

What

docs/publishing.md:216 links to ./cli.md#package-publish-source. That anchor does not exist on the published site, so the link 404s on docs.openclaw.ai while resolving fine on GitHub.

The heading it targets is ### \package publish `indocs/cli.md. OpenClaw's publishing parser (scripts/lib/docs-markdown.mjsin openclaw/openclaw) percent-encodes punctuation rather than stripping it, so the real anchor id ispackage-publish-%3Csource%3E`.

This is a third instance of the class fixed in #3618, which corrected the two other cross-page anchors in this same file. Line 336 of this file already uses the encoded form, so line 216 was the lone outlier.

Why it matters beyond the 404

openclaw/openclaw's docs CI mirrors this repo (OPENCLAW_DOCS_SYNC_CLAWHUB_REPO) and has an anchor audit (pnpm docs:check-links:anchors) that is not yet gated in CI. Work is underway to gate it. While the mirror is present, that audit enforces ClawHub fragments too, so this link is currently the only thing keeping that audit non-green.

Validation

Ran openclaw's anchor audit against a checkout of this branch:

Before:

checked_internal_links=12585
broken_links=1
mirrored_clawhub_docs=yes
clawhub/publishing.md:216 :: /clawhub/cli#package-publish-source :: fragment not found

After:

checked_internal_links=12585
broken_links=0
omitted_compatibility_aliases=1
mirrored_clawhub_docs=yes

I also swept every docs/*.md in this repo for the same defect class using the same parser; this was the only remaining broken in-repo fragment.

[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.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
clawhub	Ready	Preview	Sep 9, 2026 3:11pm UTC

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 9, 2026, 11:11 AM ET / 15:11 UTC.

ClawSweeper review

What this changes

Corrects the publishing guide’s package-publish link to target the encoded heading on the published CLI reference.

Merge readiness

✅ Ready for maintainer review

No blocking findings. Current main retains the broken fragment, and the published CLI page exposes the encoded heading targeted by this PR. The earlier merged anchor fix addressed different links.

Priority: P3
Reviewed head: 2162ac9e05c54da108a32f25a75981d466bb031c

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused documentation fix supported by a before/after anchor audit and independently verified published heading.
Proof confidence	🐚 platinum hermit (4/6)	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	7 items	Current main still needs the correction: Current main uses package-publish-source at line 216; the reviewed branch changes only that fragment. The target heading is package publish <source> in docs/cli.md:703. Published anchor contract: The specification assigns incoming-link repairs to ClawHub’s canonical docs source and states that synchronization preserves fragments. This establishes the dependency on the documentation publisher’s heading contract. Publisher parser inspected: The PR explicitly depends on this parser. Its source uses markdown-it-anchor, preserves canonical heading IDs, and adds compatibility aliases separately.
Findings	None	None.
Security	None	None.

How this fits together

ClawHub owns the publishing guide and CLI reference source. The OpenClaw documentation publisher renders those files into pages whose heading IDs determine where cross-page links land.

flowchart LR
  A[Publishing guide] --> B[Cross-page link]
  C[CLI reference heading] --> D[Documentation publisher]
  D --> E[Encoded heading ID]
  B --> E
  E --> F[Package publishing instructions]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Diff size	+1/-1 across 1 documentation file	The patch changes one navigation fragment without changing runtime behavior.

Technical review

Best possible solution:

Keep canonical source links aligned with published heading IDs while preserving the existing CLI heading and renderer contract.

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

Yes: current main links to a fragment absent from the published CLI page, whose HTML contains the proposed encoded ID. This was verified through source and HTML inspection, without a browser click reproduction.

Is this the best way to solve the issue?

Yes—the one-link correction is the narrowest fix. Renaming the target heading or changing renderer behavior would unnecessarily affect other links.

AGENTS.md: found and applied where relevant.

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

Labels

Label changes:

• add P3: This is a bounded documentation-navigation correction with no runtime or publishing-policy changes.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.

Label justifications:

• P3: This is a bounded documentation-navigation correction with no runtime or publishing-policy changes.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.

Evidence

What I checked:

• Current main still needs the correction: Current main uses package-publish-source at line 216; the reviewed branch changes only that fragment. The target heading is package publish <source> in docs/cli.md:703. (docs/publishing.md:216, 6b25e866fb91)
• Published anchor contract: The specification assigns incoming-link repairs to ClawHub’s canonical docs source and states that synchronization preserves fragments. This establishes the dependency on the documentation publisher’s heading contract. (specs/openclaw-docs-extraction.md:48, 2162ac9e05c5)
• Publisher parser inspected: The PR explicitly depends on this parser. Its source uses markdown-it-anchor, preserves canonical heading IDs, and adds compatibility aliases separately. (scripts/lib/docs-markdown.mjs:351, 5623bf28ac36)
• Published destination verified: Read-only inspection of https://docs.openclaw.ai/clawhub/cli found the exact heading ID package-publish-%3Csource%3E, plus a decoded compatibility alias; the old package-publish-source ID was absent.
• Related merged work and routing: GitHub confirms docs: fix two anchors that break on the published site #3618 merged. Its two hunks corrected recovery and package-transfer links, leaving this package-publish link distinct. Local file history identifies Vincent Koc’s related documentation work; full blame traversal failed because historical objects could not be fetched, so no line-introduction attribution is claimed. (docs/publishing.md, d3bde70e3c93)
• Release and live PR state: The v0.23.3 publishing guide predates this package CLI cross-reference, so it does not establish a shipped fix. REST inspection confirms this PR remains open and unmerged at the supplied head and base. (docs/publishing.md, 87ca030c30f3)

Likely related people:

• vincentkoc: 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.