ci: add lychee dead-link detection workflows

[Bueller87]

What changed?

Adds three new files for external-link checking via lycheeverse/lychee-action:

• lychee.toml — shared config (1d cache, 3 retries, accepts 429, excludes localhost/LinkedIn).
• .github/workflows/link-check-pr.yml — runs on PRs touching *.md/*.mdx. Scoped to changed files only and limited to external http(s) URLs via --scheme. Non-blocking via continue-on-error: true for a tuning period.
• .github/workflows/link-check-weekly.yml — Monday 12:00 UTC + workflow_dispatch. Builds the site, crawls HTML under build/{docs,community,faq}, and opens/updates a single rolling issue labeled link-rot on failure.

Why?

Catch external 404s before merge and track link rot over time. Internal links are already validated by Docusaurus's onBrokenLinks: 'throw' in build.yml, so the PR check is intentionally external-only — re-checking internal links in lychee would be redundant and prone to false positives because lychee can't replay Docusaurus's slug routing.

How did you verify it?

End-to-end in my fork before opening this PR:

1. Pushed workflows + a canary commit adding [lychee-canary-do-not-merge](https://httpbin.org/status/404) to a docs page.
2. Confirmed Link check (PR) / lychee went red naming the canary URL, while Build stayed green and merge was not blocked.
3. Pushed a revert of the canary; confirmed Link check (PR) / lychee went green.

The weekly workflow only runs from master. Plan is to trigger it once via Actions → workflow_dispatch after merge to validate the build → crawl → issue-create flow.

Potential risks

• Third-party actions pinned to majors: lycheeverse/lychee-action@v2, tj-actions/changed-files@v45, peter-evans/create-issue-from-file@v5. All widely used and actively maintained.
• First weekly run may produce a noisy issue while excludes stabilize; tune lychee.toml (exclude / accept) as flakes appear.
• PR check is non-blocking by design. To enforce after a tuning period, remove continue-on-error: true and mark Link check (PR) / lychee as a required status check in branch protection.

Related changes

None.

[gitar-bot]

Code Review ✅ Approved 2 resolved / 2 findings

Implements automated external dead-link detection with PR checks and a weekly crawler, addressing the initial broken link canary and exit code variable reference. No issues found.

✅ 2 resolved

✅ Bug: Canary broken link must not be merged

📄 docs/03-concepts/11-data-converter.md:452
Line 452 of docs/03-concepts/11-data-converter.md adds [lychee-canary-do-not-merge](https://httpbin.org/status/404) — a deliberately broken link used to verify the CI workflow during development. The commit message even says "add canary broken link to verify lychee PR check". This will introduce a permanent 404 into the published documentation if merged.

✅ Bug: Weekly workflow uses wrong env var for lychee exit code

📄 .github/workflows/link-check-weekly.yml:65
env.lychee_exit_code is never set by lycheeverse/lychee-action@v2. The action exposes the exit code as a step output (steps.<id>.outputs.exit_code), not an environment variable. Because the env var will always be empty/undefined, the condition env.lychee_exit_code != '0' will always be true (empty string != '0'), so the tracking issue will be created on every run regardless of whether links are broken — or, depending on GitHub's evaluation of undefined env vars, it may never trigger correctly.

Rules ✅ All requirements met

Repository Rules

✅ PR Description Quality Standards: The PR description clearly explains the changes, the motivation, verification steps, and potential risks, and includes the required sections.

_{1 rule not applicable. Show all rules by commenting gitar display:verbose.}

Options

Auto-apply is off → Gitar will not commit updates to this branch.
Display: compact → Showing less information.

Comment with these commands to change:

Auto-apply	Compact
gitar auto-apply:on	gitar display:verbose

_{Was this helpful? React with 👍 / 👎 | Gitar}