name: Docs drift

# CLI reference drift gate — fails when committed docs diverge from auto-generation.

on:
  pull_request:
    paths:
      - 'apps/cli/src/commands/**'
      - 'apps/cli/src/main.ts'
      - 'docs/en/reference/cli/**'
      - 'tools/gen-cli-docs.mjs'
      - 'tools/check-cli-docs.mjs'
      - '.github/actions/setup-workspace/**'
      - '.github/workflows/docs-drift.yml'
  push:
    branches:
      - main
      - development
    paths:
      - 'apps/cli/src/commands/**'
      - 'apps/cli/src/main.ts'
      - 'docs/en/reference/cli/**'
      - 'tools/gen-cli-docs.mjs'
      - 'tools/check-cli-docs.mjs'

permissions:
  contents: read
  pull-requests: read

jobs:
  cli-docs-drift:
    name: CLI docs drift check (gen-cli-docs --check)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      - name: Check CLI docs are up to date
        run: pnpm gen-cli-docs:check

  cli-docs-coverage:
    name: CLI docs coverage check (registered command ↔ markdown page)
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0

      - name: Setup workspace
        uses: ./.github/actions/setup-workspace

      - name: Verify every registered subcommand has a docs page (and vice versa)
        run: pnpm check-cli-docs
