docs-check.yml

name: Docs check

# ci.yml ignores docs/** and **/*.md, so documentation drift was never caught.
# This workflow runs the documentation checks: the English/Chinese pair check,
# the whole-tree page/ADR check, the AGENTS.md/CLAUDE.md policy-sync gate, and
# a VitePress build, which fails on a dead link anywhere in the tree.
# `check:release-docs` stays out of CI on purpose because prerelease branches
# must supply the stable documentation version explicitly.

on:
  push:
    branches: [main]
    paths:
      - 'docs/**'
      - 'README*.md'
      - 'AGENTS.md'
      - 'CLAUDE.md'
      - 'packages/shared/src/changelog*.ts'
      - 'scripts/check-*.mjs'
      - 'docs/scripts/**'
      - '.github/workflows/docs-check.yml'
  pull_request:
    paths:
      - 'docs/**'
      - 'README*.md'
      - 'AGENTS.md'
      - 'CLAUDE.md'
      - 'packages/shared/src/changelog*.ts'
      - 'scripts/check-*.mjs'
      - 'docs/scripts/**'
      - '.github/workflows/docs-check.yml'
  workflow_dispatch:

permissions:
  contents: read

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

jobs:
  docs:
    name: Docs checks
    runs-on: ubuntu-latest
    timeout-minutes: 20
    steps:
      - uses: actions/checkout@v7

      - uses: pnpm/action-setup@v6

      - uses: actions/setup-node@v7
        with:
          # Same Node as ci.yml (matches the runtime Electron 43 bundles).
          node-version: 24
          cache: pnpm

      - name: Install dependencies
        run: pnpm install --frozen-lockfile

      - name: Check AGENTS.md / CLAUDE.md policy sync
        run: pnpm check:agent-policy

      - name: Check locale pairs and every documentation page
        run: pnpm docs:check

      - name: Build the documentation site (dead links and routes)
        run: pnpm docs:build