ci.yml

name: CI

# Verify + build. Runs on every PR (including forks), pushes to main, and tags — lint,
# test, build the docs, and on tags publish the release assets. It uploads each build's
# `docs` artifact.
#
# It does NOT publish the site. publish.yml picks this run up on `workflow_run` once it
# completes and deploys from there, so the site's reconstruction cost stays out of every
# PR's critical path and a Pages failure never shows as a red check against an author who
# cannot act on it. This workflow therefore needs no elevated permissions, and its `name:`
# below is load-bearing — publish.yml matches on it.
# The token this workflow's own jobs get, and the ceiling for the reusable workflows it
# calls: nothing here builds or tests with anything but read access. Declared at the top
# rather than left to the repo/org default, which may be write-all. The `release` job
# overrides it upward for the one job that needs to create a Release.
permissions:
  contents: read

on:
  pull_request:
  push:
    branches: [main]
    tags: ['*']            # '*' never matches '/', so e.g. release/x tags don't build

jobs:
  lint:
    uses: ./.github/workflows/_lint.yml

  test:
    uses: ./.github/workflows/_test.yml

  docs:
    uses: ./.github/workflows/docs.yml
    with:
      # This repo is a Node project: install deps then build with myst. docs.yml
      # installs uv too, but it's unused here (the unconditional-uv baseline).
      build-command: npm ci && npm run docs

  release:
    needs: [lint, test, docs]
    if: github.ref_type == 'tag'
    uses: ./.github/workflows/release.yml
    permissions:
      contents: write    # create the GitHub Release + attach assets