Fix broken link checker CI and the broken links it surfaced

[samkim]

Summary

• Fixes the link checker workflow, which has been failing on every PR (e.g. run 34430009666) with no vercel deployment found, exiting.... patrickedqvist/wait-for-vercel-preview hardcodes actorName: 'vercel[bot]', but this repo's own vercel-preview.yml/vercel-production.yml create GitHub Deployments as github-actions[bot] (no native Vercel GitHub App integration), so it always timed out. Replaced with an inline actions/github-script step that queries the Deployments API directly by commit sha + environment, mirroring the equivalent step already in authzed/web's test.yml. Also bumps actions/checkout@v3 (node16, deprecated) to the node24 v6 pin already used elsewhere in this repo.
• With the checker actually running, it surfaced 3 real broken links (/spicedb/getting-started, /authzed/guides, /materialize/getting-started) and ~460 anchor-mismatch warnings. Root-caused both:
  • The 3 broken links come from nextra-theme-docs's breadcrumb component, which links a top-level section's crumb (e.g. "SpiceDB") to its first child folder's bare route when the section has no index page of its own, instead of resolving to a real leaf page. No content links to these bare paths directly, so fixed via redirects in next.config.mjs rather than content edits.
  • The anchor warnings are because Nextra doesn't render heading ids into server-rendered HTML (added client-side after hydration), so the crawler flags every #fragment link as a false-positive missing anchor. link-checker-full.yaml already carries --no-check-anchors for this reason; added it to link-checker.yaml too.
• Documented all three quirks in a new CLAUDE.md "Known Quirks" section for future reference.

Test plan

• yamllint -c .yamllint on both workflow files
• pnpm run format:check (oxfmt)
• Extracted and syntax-checked the new inline script (wrapped in an async function to match how github-script executes it)
• Dry-ran the new deployment-lookup query against live GitHub API data for the actual failing PR (docs(authzed): product-availability pill on concept pages; Audit Logging self-hosted section framed as SpiceDB Enterprise #586) and for a recent push-to-main deployment — confirmed it finds the right deployment and environment_url in both cases
• Built the docs site locally (pnpm build && pnpm start) and ran the exact filiph/linkcheck Docker image the workflow uses against it — before: 3 errors / 461 warnings; after both fixes: 0 errors / 0 warnings, exit code 0
• Confirmed all three redirects return 308 to the correct destination page
• Not yet verified live in GitHub Actions (needs this PR's own CI run)

🤖 Generated with Claude Code

[github-actions]

Preview deployment status for this pull request.

Name	Status	Preview	Updated (UTC)
docs	🟢 Ready	Visit Preview	Sep 18, 2026 05:33pm