name: Docs

# Runs on EVERY pull request / push to main — no `paths:` filter. When `links`
# is a required status check, path-filtering it silently blocks code-only PRs:
# the workflow is skipped, the required check never reports, and the merge box
# waits forever. `make docs-check` validates the whole doc tree regardless of
# what a PR touched and takes only seconds, so it is cheap to always report.
on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: docs-${{ github.ref }}
  cancel-in-progress: true

jobs:
  links:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6

      - name: Validate Markdown docs
        run: make docs-check