ci(docs): check linked terms, procedure format, and UI verification

[reemsabawi-mystenlabs]

Adds a Docs / Conventions CI job that catches three classes of review comment the prose style pass misses. Every one of them was raised by hand on a docs PR this week.

Why

On #603 the style gate passed clean and the reviewer still left twelve comments. Eight were mine to catch, and five of those were mechanical:

• OAuth 2.1, Sui wallet (twice), and Walrus Memory account mentioned in prose with no link
• a procedure written as a bolded numbered list while the same page used <Steps> elsewhere
• a ## Troubleshooting section in a format none of the six sibling MCP pages use

The same classes then turned up across four walrus docs PRs while fixing them by hand today. This job checks them instead.

What it checks

1. Linked terms. scripts/docs-conventions.json maps a concept to its canonical page or spec. A changed page that mentions the concept has to link it at least once. Internal targets are validated against docs/docs.json on every run, so a renamed route fails the check rather than rotting. A page never has to link to itself.
2. Procedure format. A page using <Steps> cannot also write a procedure as a bolded numbered list, and a ## Troubleshooting section has to match the format its sibling pages already use. The sibling rule needs at least two agreeing siblings before it fires.
3. UI verification. When changed docs touch a click-through procedure, the pull request body needs a UI verification: line. "Nobody has run it yet" is a valid answer; the point is that the reviewer reads it in the description instead of asking. This one only evaluates on pull_request events.

Verification

Regression-tested against #603 rather than assumed:

Input	Result
Pre-review docs/mcp/claude-connector.md	5 findings, matching 5 of the reviewer's comments one for one
Post-review revision of the same file	clean
Simulated PR body without the marker	fires on the **Add custom connector** step
Simulated PR body with the marker	passes
Every page under docs/	36 link-term findings, 0 format findings

The 36 are pre-existing unlinked terms. The job runs on changed pages only, so they surface as those pages get edited rather than landing as one sweep. Nothing is blocked today.

docs-code-sync and docs-freshness both still pass, and pnpm check:docs runs the same script locally.

Placement

The job sits in test.yml next to docs-code-sync and docs-freshness. It started as a separate docs.yml, written before those two existed on dev; folding it in keeps all three docs jobs together.

UI verification: not applicable. This change is CI configuration and a Node script, with no click-through procedure in it.

Sources

• Findings and classes: the review comments on docs(mcp): Claude custom connector guide, plus OAuth reference corrections #603.
• Sui wallet URL in the term map: the URL MystenLabs/walrus already uses in docs/content/sites/known-restrictions.mdx.
• zkLogin URL: already cited in docs/reference/console-identity-link.md.
• Internal route targets: read from docs/docs.json.
• Troubleshooting house format: read off docs/mcp/{claude-code,codex,cursor,antigravity,opencode}.md, which all use the bulleted form.
• Job shape: mirrors the docs-code-sync and docs-freshness jobs already in .github/workflows/test.yml.
• The script and its config are written fresh for this change; there was no existing checker for these classes.

---

Generated by Claude Code

[jessiemongeon1]

Style Guide Audit

All 1 file(s) pass the style guide audit.