# Documentation quality gate (task 48).
#
# Runs the local link checker over README.md, AGENTS.md, and docs/*.md so a
# stale file or heading reference fails CI. This is the "markdown-link-check
# equivalent" named by the task; it is deliberately offline (only relative
# links are validated) so the job needs no network beyond checkout/setup.
#
# Task 42 owns the main CI workflow. This job is intentionally a separate
# workflow file so it can be added to that pipeline as a required step
# (`docs` job name) without a conflict, and it also runs standalone.
name: docs

on:
  push:
    paths:
      - "README.md"
      - "AGENTS.md"
      - "docs/**"
      - "scripts/check_doc_links.py"
      - ".github/workflows/docs.yml"
  pull_request:
    paths:
      - "README.md"
      - "AGENTS.md"
      - "docs/**"
      - "scripts/check_doc_links.py"
      - ".github/workflows/docs.yml"
  workflow_dispatch: {}

permissions:
  contents: read

jobs:
  link-check:
    name: docs link-check
    runs-on: ubuntu-24.04
    steps:
      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5
      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
        with:
          python-version: "3.x"
      - name: Check documentation links
        run: python3 scripts/check_doc_links.py