Check local links across docs pages

[kiranmagic7]

Summary

• expand the documentation link checker to scan local markdown/image/html links inside docs pages, not only README and the provider index
• resolve docs-page links relative to the file that contains them, so nested links such as ../claude.md are validated correctly
• include the source file in future missing-target or missing-anchor errors

Why

Scripts/check-documentation-links.mjs already runs in lint-linux, but it only covered README links and the provider detail list. The docs tree has additional relative links between pages, including nested docs under docs/refactor and docs/solutions, that were not part of the guard.

Current main has no broken docs-page links; this change makes the existing lint lane catch future drift.

Validation

• node --check Scripts/check-documentation-links.mjs
• node Scripts/check-documentation-links.mjs -> documentation links OK: 134 local links
• git diff --check
• ./Scripts/lint.sh lint-linux

Compatibility

No app behavior changes. The only risk is that future docs-only changes may fail lint when a local docs-page link points outside docs/, has a missing target, or references a missing markdown heading anchor.

Review focus: whether docs-page links should continue to be constrained to targets inside docs/.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed June 24, 2026, 8:56 PM ET / 00:56 UTC.

Summary
The PR expands Scripts/check-documentation-links.mjs to recursively scan docs markdown files, validate local markdown/image/HTML links relative to each source file, and include source filenames in diagnostics.

Reproducibility: not applicable. this is a documentation lint expansion rather than a reported runtime bug. Source inspection and the PR body's command-output proof cover the changed behavior path.

Review metrics: 2 noteworthy metrics.

• Changed surface: 1 file modified, +44/-10. The patch is confined to the existing documentation link checker that lint-linux already runs.
• Reported scanned links: 134 local links. The PR body's copied command output shows the updated checker scanning beyond the current README/provider subset.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🐚 platinum hermit
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:

• [P2] Maintainer should decide whether docs markdown links must stay inside docs or whether approved root documentation files should remain valid targets.

Risk before merge

• [P1] Future docs markdown changes that intentionally link to root-level repository files such as README, CHANGELOG, or LICENSE would fail the lint lane unless maintainers accept a docs-only target boundary.

Maintainer options:

1. Accept the docs-root lint boundary
   Merge as-is if maintainers want every local link from docs markdown pages to resolve inside docs/.
2. Allow intentional root docs links
   Before merge, add explicit exceptions for root-level repository docs if links from docs pages to README, CHANGELOG, LICENSE, or similar files should remain valid.

Next step before merge

• [P2] The remaining action is a maintainer policy decision about allowed docs-page link targets, not a narrow automation repair.

Security
Cleared: The diff only reads repository documentation files with Node fs/path and adds no dependencies, network access, secrets handling, or external command execution.

Review details

Best possible solution:

Merge as-is if docs markdown links should stay inside docs; otherwise add a narrow allowlist for intentional root-level repository docs before merge.

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

Not applicable; this is a documentation lint expansion rather than a reported runtime bug. Source inspection and the PR body's command-output proof cover the changed behavior path.

Is this the best way to solve the issue?

Yes, if maintainers want the docs-root boundary: extending the existing Node checker already called by lint-linux is the narrowest maintainable path. If root-level docs links should be allowed from docs pages, the safer variant is an explicit exception rather than relaxing all local paths.

AGENTS.md: found and applied where relevant.

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

Label changes

Label justifications:

• P3: This is low-risk repository maintenance for documentation lint coverage, with no app runtime behavior change.
• merge-risk: 🚨 automation: The diff makes an existing lint lane stricter, so future docs changes can fail CI on local links that leave docs/.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🐚 platinum hermit and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (live_output): The PR body includes copied live command output from the updated checker and the lint lane, which is sufficient real behavior proof for this non-visual script change.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes copied live command output from the updated checker and the lint lane, which is sufficient real behavior proof for this non-visual script change.

Evidence reviewed

What I checked:

• Repository policy read: AGENTS.md was present and read in full; its relevant guidance favors scoped script changes and CLI/focused validation for script-testable behavior. (AGENTS.md:1, ada3660e9d61)
• Current main checker scope: Current main reads README.md and docs/providers.md, then validates only README docs references and provider detail links rather than recursively scanning docs pages. (Scripts/check-documentation-links.mjs:8, ada3660e9d61)
• PR implementation scope: The PR diff adds recursive docs markdown discovery, collects markdown/image/HTML links from each docs page, validates them relative to the containing file, and preserves the docs-root escape guard. (Scripts/check-documentation-links.mjs:13, 4e80c146e525)
• Lint integration: lint-linux already runs check_documentation_links, so making this checker stricter changes existing CI/lint automation behavior for future docs changes. (Scripts/lint.sh:54, ada3660e9d61)
• Contributor proof: The PR body reports syntax checking, the updated documentation link checker output with 134 local links, git diff --check, and ./Scripts/lint.sh lint-linux. (4e80c146e525)
• Script history: Blame attributes the current documentation link checker content on main to commit f380287, a recent release/appcast update that includes the current script surface. (Scripts/check-documentation-links.mjs:1, f380287041b8)

Likely related people:

• steipete: Current-main blame attributes the documentation link checker and lint hook surface to commit f380287. (role: recent area contributor; confidence: high; commits: f380287041b8, 1843a21feaf9, e5e696a8d5b5; files: Scripts/check-documentation-links.mjs, Scripts/lint.sh, Tests/CodexBarTests/DocumentationLinkTests.swift)
• kiranmagic7: Merged prior work in test: cover local documentation links #1506 introduced local documentation link tests, and Check generated llms index in lint #1701 touched nearby lint automation. (role: adjacent validation contributor; confidence: medium; commits: bba020d57d6f, be3a5f402c5d; files: Tests/CodexBarTests/DocumentationLinkTests.swift, Scripts/lint.sh, Scripts/generate-llms.mjs)

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.