upstream-release-docs.yml

name: Upstream Release Docs

# Reacts to Renovate-authored PRs that bump a `version:` in
# .github/upstream-projects.yaml. For all four tracked projects
# (toolhive, toolhive-registry-server, toolhive-studio,
# toolhive-cloud-ui), the flow is identical:
#
#   1. Renovate opens a version-bump PR
#   2. This workflow fires on the PR event, detects which project
#      changed, shallow-clones the upstream at the new tag
#   3. Syncs declared upstream assets into static/ via sync-assets.mjs
#      (release-asset downloads, tarball extractions, file-from-clone
#      copies — see `assets:` in upstream-projects.yaml)
#   4. For toolhive specifically, downloads the CRD manifests tarball
#      and runs extract-crd-schemas.mjs + generate-crd-pages.mjs +
#      bundle-upstream-schema.mjs to produce our opinionated reference
#      MDX (the CRD tarball and toolhive-core schemas are shipped as
#      release assets by stacklok/toolhive#4982)
#   5. Runs two Claude Opus sessions: a generation pass running the
#      upstream-release-docs skill, then a fresh-context editorial
#      pass running docs-review over the changed files. Both have
#      `gh` CLI access so they can fetch PR descriptions and linked
#      issues for product context.
#   6. Auto-fixes prettier/eslint on the skill-touched files,
#      commits everything to the PR branch, augments the PR body,
#      assigns reviewers from non-bot release contributors
#
# Renovate is configured with rebaseWhen: never + recreateWhen: never
# so we can push commits without force-push races.

on:
  pull_request:
    types: [opened, reopened]
    paths:
      - '.github/upstream-projects.yaml'
  workflow_dispatch:
    inputs:
      pr_number:
        description: 'Retry-only: PR number to re-augment (must be an open Renovate PR). Leave blank to bootstrap a new PR via project_id + new_tag.'
        required: false
        type: string
      project_id:
        description: 'Bootstrap a new PR: id from .github/upstream-projects.yaml (e.g. toolhive-registry-server). Requires new_tag.'
        required: false
        type: string
      new_tag:
        description: 'Bootstrap a new PR: the upstream tag to document (e.g. v1.3.0). Requires project_id.'
        required: false
        type: string

permissions:
  contents: write
  pull-requests: write
  # Required by anthropics/claude-code-action@v1 for OIDC token exchange.
  id-token: write

concurrency:
  # Workflow-level group so two simultaneous upstream releases don't
  # run the skill in parallel on shared concept pages.
  group: upstream-release-docs
  cancel-in-progress: false

jobs:
  augment:
    runs-on: ubuntu-latest
    timeout-minutes: 90
    # Gate: two accepted entry points.
    #   - pull_request: Renovate-authored PR touching upstream-projects.yaml
    #     (the `paths:` filter on the trigger already narrows to YAML edits).
    #   - workflow_dispatch: human manually retries or bootstraps.
    # Human-authored PRs that happen to edit the YAML are out of scope and
    # should be reviewed normally without skill augmentation.
    if: |
      github.event_name == 'workflow_dispatch' ||
      (
        github.event_name == 'pull_request' &&
        github.event.pull_request.user.login == 'renovate[bot]'
      )
    env:
      GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - name: Validate workflow_dispatch inputs
        if: github.event_name == 'workflow_dispatch'
        env:
          PR_NUMBER_IN: ${{ github.event.inputs.pr_number }}
          PROJECT_ID_IN: ${{ github.event.inputs.project_id }}
          NEW_TAG_IN: ${{ github.event.inputs.new_tag }}
        run: |
          # Exactly one of: (pr_number) OR (project_id + new_tag).
          if [ -n "$PR_NUMBER_IN" ] && { [ -n "$PROJECT_ID_IN" ] || [ -n "$NEW_TAG_IN" ]; }; then
            echo "::error::Provide either pr_number (retry) or project_id + new_tag (bootstrap), not both."
            exit 1
          fi
          if [ -z "$PR_NUMBER_IN" ] && { [ -z "$PROJECT_ID_IN" ] || [ -z "$NEW_TAG_IN" ]; }; then
            echo "::error::Bootstrap mode requires both project_id and new_tag."
            exit 1
          fi

      - name: Resolve PR number and head ref
        id: pr
        env:
          EVENT: ${{ github.event_name }}
          DISPATCH_PR: ${{ github.event.inputs.pr_number }}
          PROJECT_ID_IN: ${{ github.event.inputs.project_id }}
          NEW_TAG_IN: ${{ github.event.inputs.new_tag }}
          EVENT_PR: ${{ github.event.pull_request.number }}
          EVENT_HEAD_REF: ${{ github.event.pull_request.head.ref }}
        run: |
          case "$EVENT" in
            pull_request)
              PR_NUMBER="$EVENT_PR"
              HEAD_REF="$EVENT_HEAD_REF"
              MODE="react"
              ;;
            workflow_dispatch)
              if [ -n "$DISPATCH_PR" ]; then
                PR_NUMBER="$DISPATCH_PR"
                # --repo is required because this step runs before the
                # actions/checkout below — gh otherwise looks for a
                # local .git context and fails with "not a git repository".
                HEAD_REF=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json headRefName --jq .headRefName)
                AUTHOR=$(gh pr view "$PR_NUMBER" --repo "$GITHUB_REPOSITORY" --json author --jq '.author.login')
                case "$AUTHOR" in
                  app/renovate|renovate[bot]|app/github-actions|github-actions[bot])
                    ;;
                  *)
                    echo "::error::PR #$PR_NUMBER author '$AUTHOR' is not an accepted bot. Retry mode accepts renovate[bot] or github-actions[bot]; use bootstrap (project_id + new_tag) for a fresh manual PR."
                    exit 1
                    ;;
                esac
                MODE="retry"
              else
                # Bootstrap: branch and PR are created in the next step.
                PR_NUMBER=""
                HEAD_REF=""
                MODE="bootstrap"
              fi
              ;;
          esac
          {
            echo "number=$PR_NUMBER"
            echo "head_ref=$HEAD_REF"
            echo "mode=$MODE"
          } >> "$GITHUB_OUTPUT"
          echo "Mode: $MODE"

      # Bootstrap: a human manually dispatched with project_id + new_tag.
      # Check out the dispatching branch (main in production; any branch
      # for pre-merge testing — just dispatch via `gh workflow run --ref
      # <branch>`), bump the YAML, create the PR, and emit its number +
      # branch so the rest of the workflow proceeds as if Renovate had
      # opened it.
      - name: Checkout dispatching branch for bootstrap
        if: steps.pr.outputs.mode == 'bootstrap'
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ github.ref_name }}
          fetch-depth: 0

      - name: Setup (bootstrap)
        if: steps.pr.outputs.mode == 'bootstrap'
        uses: ./.github/actions/setup

      - name: Set up Git (bootstrap)
        if: steps.pr.outputs.mode == 'bootstrap'
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"

      - name: Bootstrap branch and PR
        id: bootstrap
        if: steps.pr.outputs.mode == 'bootstrap'
        env:
          PROJECT_ID: ${{ github.event.inputs.project_id }}
          NEW_TAG: ${{ github.event.inputs.new_tag }}
          BASE_REF: ${{ github.ref_name }}
          ACTOR: ${{ github.actor }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          # Branch name intentionally distinct from Renovate's
          # docs/upstream-<id> so the two paths don't collide.
          BRANCH="manual/upstream-${PROJECT_ID}-${NEW_TAG}"
          if git ls-remote --exit-code --heads origin "$BRANCH" >/dev/null 2>&1; then
            echo "::error::Branch $BRANCH already exists on origin. Delete it or use retry mode with the existing PR's number."
            exit 1
          fi
          git checkout -b "$BRANCH"

          node scripts/upstream-release/bump-yaml.mjs \
            --id "$PROJECT_ID" \
            --tag "$NEW_TAG"

          git add .github/upstream-projects.yaml
          git commit -m "Bump $PROJECT_ID to $NEW_TAG"
          git push origin "$BRANCH"

          # Heredoc so the YAML indent doesn't leak into the PR body.
          cat > /tmp/bootstrap-body.md <<EOF
          Manually dispatched by @$ACTOR via workflow run $RUN_URL.

          This PR was created by the \`Upstream Release Docs\` workflow's bootstrap mode to document a release without waiting for Renovate. Content edits will be pushed as additional commits by the same workflow run.
          EOF
          # Strip the leading 10-space indent the heredoc inherits from
          # YAML nesting so the body renders cleanly.
          sed -i 's/^          //' /tmp/bootstrap-body.md

          gh pr create \
            --base "$BASE_REF" \
            --head "$BRANCH" \
            --title "Update $PROJECT_ID to $NEW_TAG (manual dispatch)" \
            --body-file /tmp/bootstrap-body.md

          PR_NUMBER=$(gh pr view "$BRANCH" --json number --jq .number)
          echo "number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
          echo "head_ref=$BRANCH" >> "$GITHUB_OUTPUT"

      # Normalize the (possibly bootstrap-created) PR number, head_ref,
      # and base_ref into a single step output so later steps reference
      # one place. base_ref drives detect-change.mjs (the baseline to
      # diff against) and the CRD-regen paths.
      - name: Resolve effective PR metadata
        id: eff
        env:
          EVENT: ${{ github.event_name }}
          PR_FROM_RESOLVE: ${{ steps.pr.outputs.number }}
          HEAD_FROM_RESOLVE: ${{ steps.pr.outputs.head_ref }}
          PR_FROM_BOOTSTRAP: ${{ steps.bootstrap.outputs.number }}
          HEAD_FROM_BOOTSTRAP: ${{ steps.bootstrap.outputs.head_ref }}
          BASE_FROM_EVENT: ${{ github.event.pull_request.base.ref }}
          DISPATCH_REF_NAME: ${{ github.ref_name }}
        run: |
          if [ -n "$PR_FROM_BOOTSTRAP" ]; then
            # Bootstrap mode: the PR was just created with --base set to
            # the dispatching branch (main in production; feat branch
            # when testing pre-merge).
            NUMBER="$PR_FROM_BOOTSTRAP"
            HEAD="$HEAD_FROM_BOOTSTRAP"
            BASE="$DISPATCH_REF_NAME"
          elif [ "$EVENT" = "pull_request" ]; then
            NUMBER="$PR_FROM_RESOLVE"
            HEAD="$HEAD_FROM_RESOLVE"
            BASE="$BASE_FROM_EVENT"
          else
            # workflow_dispatch retry: look up the PR's base_ref.
            # --repo because in retry mode there's no prior checkout.
            NUMBER="$PR_FROM_RESOLVE"
            HEAD="$HEAD_FROM_RESOLVE"
            BASE=$(gh pr view "$NUMBER" --repo "$GITHUB_REPOSITORY" --json baseRefName --jq .baseRefName)
          fi
          {
            echo "number=$NUMBER"
            echo "head_ref=$HEAD"
            echo "base_ref=$BASE"
          } >> "$GITHUB_OUTPUT"

      - name: Checkout PR branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ steps.eff.outputs.head_ref }}
          fetch-depth: 0

      # NOTE: we inline the node/deps setup rather than calling the
      # ./.github/actions/setup composite because that composite starts
      # with its own actions/checkout that overwrites the PR-branch
      # checkout above with the dispatching branch.
      - name: Set up Node.js
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: '24.15.0'

      - name: Cache dependencies
        id: cache
        uses: actions/cache@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
        with:
          path: ./node_modules
          key: modules-${{ hashFiles('package-lock.json') }}

      - name: Install dependencies
        if: steps.cache.outputs.cache-hit != 'true'
        run: npm ci

      - name: Set up Git
        run: |
          git config --global user.name "github-actions[bot]"
          git config --global user.email "github-actions[bot]@users.noreply.github.com"

      - name: Detect changed project
        id: detect
        env:
          # Pass the PR's actual base (main in production; dispatching
          # branch when bootstrap was run via gh workflow run --ref).
          BASE_REF: origin/${{ steps.eff.outputs.base_ref }}
        run: node scripts/upstream-release/detect-change.mjs

      - name: Verify prev_tag exists upstream
        env:
          REPO: ${{ steps.detect.outputs.repo }}
          PREV_TAG: ${{ steps.detect.outputs.prev_tag }}
        run: |
          # Sanity check: if the pinned prev_tag doesn't exist upstream
          # (e.g., a fake v0.0.0 seed, a retagged release, a deleted tag),
          # fail early rather than let the skill produce a confusing diff.
          if ! gh api "repos/$REPO/git/refs/tags/$PREV_TAG" --silent 2>/dev/null; then
            echo "::error::prev_tag $PREV_TAG does not exist in $REPO. The pinned version in .github/upstream-projects.yaml may be wrong or the upstream tag was deleted. Fix the pinned version and re-run."
            exit 1
          fi

      - name: Shallow-clone upstream at new tag
        id: clone
        env:
          REPO: ${{ steps.detect.outputs.repo }}
          NEW_TAG: ${{ steps.detect.outputs.new_tag }}
        run: |
          SCRATCH=$(mktemp -d)
          git clone --depth 1 --branch "$NEW_TAG" \
            "https://github.com/${REPO}.git" \
            "$SCRATCH/upstream"
          echo "scratch_dir=$SCRATCH/upstream" >> "$GITHUB_OUTPUT"

      - name: Sync declared assets
        env:
          PROJECT_ID: ${{ steps.detect.outputs.id }}
          CLONE_DIR: ${{ steps.clone.outputs.scratch_dir }}
          REPO: ${{ steps.detect.outputs.repo }}
          NEW_TAG: ${{ steps.detect.outputs.new_tag }}
        run: |
          node scripts/upstream-release/sync-assets.mjs \
            --id "$PROJECT_ID" \
            --clone "$CLONE_DIR" \
            --repo "$REPO" \
            --tag "$NEW_TAG"

      # toolhive ships CRD manifests as a release asset tarball (see
      # stacklok/toolhive#4982). We extract it to a temp dir and run our
      # opinionated transforms: extract per-CRD JSON schemas + examples,
      # generate MDX reference pages. Bundling the upstream-registry
      # schema (resolves the remote MCP-server $refs for our JSON-Schema
      # viewer) also runs here.
      - name: Extract CRDs + generate reference MDX (toolhive)
        if: steps.detect.outputs.id == 'toolhive'
        env:
          REPO: ${{ steps.detect.outputs.repo }}
          NEW_TAG: ${{ steps.detect.outputs.new_tag }}
        run: |
          TMP=$(mktemp -d)
          gh release download "$NEW_TAG" --repo "$REPO" \
            --pattern "thv-crds.tar.gz" --dir "$TMP"
          mkdir -p "$TMP/crds"
          tar -xzf "$TMP/thv-crds.tar.gz" -C "$TMP/crds"
          TOOLHIVE_CRD_DIR="$TMP/crds" node scripts/extract-crd-schemas.mjs
          node scripts/generate-crd-pages.mjs
          node scripts/bundle-upstream-schema.mjs
          rm -rf "$TMP"

      # Commit AND PUSH the refreshed reference assets (synced release-
      # asset files + regenerated toolhive CRD MDX if applicable) before
      # the skill runs. Pushing here — rather than batching the push
      # with the skill-content commit later — means refresh work is
      # preserved on the PR even if the skill step fails or is
      # cancelled. Also keeps the skill's content commit clean and
      # lets the autogen-detect step below distinguish skill touches
      # from our own legitimate refresh writes.
      - name: Commit + push refreshed reference assets
        env:
          PROJECT_ID: ${{ steps.detect.outputs.id }}
          NEW_TAG: ${{ steps.detect.outputs.new_tag }}
          HEAD_REF: ${{ steps.eff.outputs.head_ref }}
        run: |
          git add -A
          if git diff --cached --quiet; then
            echo "No reference changes for $PROJECT_ID $NEW_TAG."
          else
            git commit -m "Refresh reference assets for $PROJECT_ID $NEW_TAG"
            # Someone may have pushed to HEAD_REF between our checkout
            # and now (merges from main, etc). Rebase onto the latest
            # tip before pushing so we don't fail with "fetch first".
            git fetch origin "$HEAD_REF" --quiet
            git rebase "origin/$HEAD_REF" || {
              echo "::error::Rebase of the refresh commit onto origin/$HEAD_REF hit conflicts. Resolve manually on the PR branch."
              exit 1
            }
            git push origin "HEAD:$HEAD_REF"
          fi

      # Anchor the "skill touched" set for the autofix step below.
      # HEAD at this point is either the refresh commit (if it was
      # non-empty) or the PR's pre-workflow tip. Either way, anything
      # committed between this SHA and HEAD after the skill runs is
      # attributable to the skill.
      - name: Capture pre-skill SHA
        id: pre_skill
        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"

      - name: Extract reviewers and contributors from release compare
        id: reviewers
        env:
          REPO: ${{ steps.detect.outputs.repo }}
          PREV: ${{ steps.detect.outputs.prev_tag }}
          NEW: ${{ steps.detect.outputs.new_tag }}
          REVIEW_REPO: ${{ github.repository }}
        run: |
          # Get non-bot commit authors in the release range.
          if COMPARE=$(gh api "repos/$REPO/compare/$PREV...$NEW" \
              --jq '[.commits[].author.login? // empty] | unique | .[]' 2>/dev/null); then
            echo "compare_ok=true" >> "$GITHUB_OUTPUT"
          else
            COMPARE=""
            echo "compare_ok=false" >> "$GITHUB_OUTPUT"
          fi

          # Filter out bot accounts.
          CANDIDATES=$(echo "$COMPARE" |
            grep -Ev '(\[bot\]$|^github-actions|^stacklokbot$|^dependabot|^renovate|^copilot)' || true)

          # Split candidates into two groups:
          #   - ASSIGN_LIST: collaborators on this repo -- safe to pass
          #     to `gh pr edit --add-reviewer`. GitHub rejects the
          #     entire call with 422 if any name in the list isn't a
          #     collaborator, so the filter is mandatory to avoid
          #     dropping valid reviewers alongside invalid ones.
          #   - MENTION_LIST: everyone else. Upstream contributors
          #     (often Stacklok employees with private org membership
          #     we can't detect via GITHUB_TOKEN, which lacks
          #     read:org) still deserve a ping so they see the PR
          #     documenting their work. @-mentioning in the PR body
          #     handles that without needing reviewer-assignment
          #     rights.
          # Future: a PAT with read:org could let us also check
          # membership in the `stackers` team and promote those to
          # ASSIGN_LIST. Deferred -- not wiring a secret in now.
          ASSIGN_LIST=""
          MENTION_LIST=""
          while IFS= read -r login; do
            [ -z "$login" ] && continue
            if gh api "repos/$REVIEW_REPO/collaborators/$login" --silent 2>/dev/null; then
              ASSIGN_LIST="${ASSIGN_LIST:+$ASSIGN_LIST,}$login"
            else
              MENTION_LIST="${MENTION_LIST:+$MENTION_LIST }@$login"
            fi
          done <<< "$CANDIDATES"

          # Cap auto-assignments at 5 to avoid review fatigue. Mentions
          # aren't capped -- they're cheap and the block is a single
          # PR-body notification.
          ASSIGN_LIST=$(echo "$ASSIGN_LIST" | tr ',' '\n' | head -5 | paste -sd, -)

          echo "list=$ASSIGN_LIST" >> "$GITHUB_OUTPUT"
          {
            echo "mention_block<<MENTION_EOF"
            if [ -n "$MENTION_LIST" ]; then
              echo "Release contributors who aren't collaborators on this repo and so couldn't be auto-assigned as reviewers. Mentioning them so they see the PR documenting their work:"
              echo ""
              echo "$MENTION_LIST"
            fi
            echo "MENTION_EOF"
          } >> "$GITHUB_OUTPUT"
          echo "Auto-assigned: ${ASSIGN_LIST:-<none>}"
          echo "Mentioned:     ${MENTION_LIST:-<none>}"

      - name: Read docs_paths hint
        id: hints
        env:
          PROJECT_ID: ${{ steps.detect.outputs.id }}
        run: |
          HINTS=$(node -e "
            const yaml = require('yaml');
            const fs = require('fs');
            const p = yaml.parse(fs.readFileSync('.github/upstream-projects.yaml','utf8')).projects.find(x=>x.id===process.env.PROJECT_ID);
            console.log(JSON.stringify(p?.docs_paths ?? []));
          ")
          echo "docs_paths=$HINTS" >> "$GITHUB_OUTPUT"

      # Invocation 1: generation. Runs /upstream-release-docs end-to-
      # end (all 6 phases, including the skill's own internal
      # docs-review in Phase 5). Uses Opus 4.7 — generation benefits
      # from the stronger model on long multi-file edits and source
      # verification.
      - name: Run upstream-release-docs skill (generation)
        id: skill_gen
        uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          additional_permissions: |
            actions: read
          # Allow the action to run when the triggering PR was opened
          # by Renovate. Without this, claude-code-action refuses to
          # run for bot-initiated workflows as a safety default.
          allowed_bots: 'renovate'
          # Real-time visibility into skill progress during long runs.
          # track_progress posts a sticky tracking comment on the PR
          # that updates as the skill works through each phase —
          # BUT it's only supported for pull_request / issue_comment
          # /* events. Setting it on workflow_dispatch fails the
          # action with "track_progress is only supported for events
          # ... Current event: workflow_dispatch", so gate it on the
          # triggering event.
          # display_report surfaces the Claude Code Report in the
          # Actions Step Summary regardless of trigger.
          track_progress: ${{ github.event_name == 'pull_request' }}
          display_report: true
          # Grant the `gh` CLI so the skill can fetch PR descriptions,
          # compare ranges, and view linked issues as it was designed
          # to. Without this, Claude Code's default Bash allowlist
          # rejects gh and the skill has to work from commit messages
          # only, which misses most of the "why" narrative that PR
          # authors write at open time. GH_TOKEN for auth is already
          # in the job env at the top of this workflow.
          claude_args: |
            --model claude-opus-4-7
            --allowed-tools "Bash(gh:*)"
          prompt: |
            You are running in GitHub Actions with no interactive user. Follow
            these steps exactly and do NOT ask clarifying questions -- proceed
            best-effort at every decision point.

            PROJECT:    ${{ steps.detect.outputs.id }}
            REPO:       ${{ steps.detect.outputs.repo }}
            PREV_TAG:   ${{ steps.detect.outputs.prev_tag }}
            NEW_TAG:    ${{ steps.detect.outputs.new_tag }}
            CLONE:      ${{ steps.clone.outputs.scratch_dir }}
            DOCS_HINTS: ${{ steps.hints.outputs.docs_paths }}

            Run /upstream-release-docs ${{ steps.detect.outputs.repo }} ${{ steps.detect.outputs.new_tag }}
            Execute all 6 phases. Prefer reading source code from the
            local clone at ${{ steps.clone.outputs.scratch_dir }}
            instead of `gh api contents?ref=<tag>` -- it's already at
            the tag and doesn't consume API quota.

            For Phase 2 step 4 (context on major new features), do the
            following INSTEAD of the skill's default "ask the user"
            behavior (there is no interactive user here):
              1. Use `gh pr view <NUMBER> --repo ${{ steps.detect.outputs.repo }}
                 --json title,body,author` to fetch the PR description
                 for each major new feature. The PR body typically
                 contains the "why" framing the author wrote when
                 opening the PR -- motivation, intended consumers,
                 design decisions.
              2. If the PR body references linked issues (look for
                 "Closes #N", "Fixes #N", "Refs #N"), fetch those
                 with `gh issue view <N> --repo ${{ steps.detect.outputs.repo }}`
                 when they are likely to contain product context.
              3. Write the "why"/consumer narrative directly in the
                 relevant docs page using what you learned. This is a
                 best-effort pass -- reviewers will refine it during
                 normal review.
              4. Only defer to GAPS.md when the rationale demonstrably
                 cannot be derived from available sources. Genuine
                 examples: the PR body points to an internal design
                 doc or product spec you cannot access; multiple
                 plausible consumer narratives exist and picking one
                 would mislead readers; a release timeline or
                 commitment needs product-team confirmation.

            GAPS.md contract (only if you genuinely need to defer):
              - ONLY include content gaps a human reviewer must fill
                in. Do NOT include environment/sandbox limitations
                (e.g. "couldn't run npm build") -- those are
                infrastructure concerns; the PR's CI handles them.
                Do NOT include "not a gap, documented for clarity"
                commentary.
              - Each entry MUST include a "Helper prompt for local
                Claude" block a reviewer can paste verbatim into
                their local Claude Code to resolve the gap. The
                prompt must reference the specific file(s) to edit,
                the PR number that provides context, and the narrow
                piece of information the human needs to supply or
                confirm.
              - Each entry MUST @-mention the PR author (skip this
                for bot authors: renovate[bot], github-actions[bot],
                stacklokbot).

            GAPS.md entry format:
              ```
              ### <Feature name> (PR #123 by @alice)

              <One paragraph: what's missing, why you couldn't
              resolve it from available sources.>

              **File(s):** path/to/file.mdx

              **Helper prompt for local Claude:**
              > <Paste-ready prompt. Self-contained. References the
              > specific file(s), the PR number, and the narrow
              > piece of info needed. A human should be able to
              > paste this into `claude` locally and get a usable
              > response without additional context.>
              ```

            Do NOT create GAPS.md if every feature's "why" was
            resolvable from PR descriptions. An empty GAPS.md is
            worse than no file.

            Follow the skill's own guidance on auto-generated reference
            files (Phase 4 step 5, Phase 4 step 6) -- do not hand-edit
            docs/toolhive/reference/cli/, static/api-specs/, or
            docs/toolhive/reference/crds/. Those are synced or
            regenerated from release assets by earlier steps in this
            workflow; if a release genuinely needs hand-written
            reference updates, note that in GAPS.md.

            If you conclude there are no doc-relevant changes for this
            release (Phase 3 impact map is empty), stop and write
            NO_CHANGES.md at repo root with a one-line explanation.
            Still do not hand-edit any file.

      # Invocation 2: editorial re-review with FRESH CONTEXT. Running
      # docs-review in a separate session — with no exposure to the
      # generation session's internal reasoning — tends to catch style
      # and structure issues the generation pass rationalized away.
      # Also uses Opus 4.7 since docs-review benefits from the same
      # model quality.
      - name: Run docs-review on skill output (fresh context)
        id: skill_review
        if: always() && steps.skill_gen.conclusion == 'success'
        uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          additional_permissions: |
            actions: read
          allowed_bots: 'renovate'
          track_progress: ${{ github.event_name == 'pull_request' }}
          display_report: true
          # gh access parallels skill_gen so the review pass can
          # re-verify claims against PR descriptions and linked
          # issues if needed.
          claude_args: |
            --model claude-opus-4-7
            --allowed-tools "Bash(gh:*)"
          prompt: |
            You are running in GitHub Actions with no interactive user. Follow
            these steps exactly and do NOT ask clarifying questions -- proceed
            best-effort at every decision point.

            A previous Claude session just generated content for the
            upstream release ${{ steps.detect.outputs.repo }} ${{ steps.detect.outputs.new_tag }}.
            You are a fresh reviewer with no prior context from that
            session. Your job is purely editorial.

            Run /docs-review over every file the previous commit
            changed (use `git show --name-only HEAD` or `git diff
            --name-only HEAD~1 HEAD` to find them). Apply every
            actionable fix per the skill's standard guidance.

            If you spot a factual concern, re-verify against the
            local clone at ${{ steps.clone.outputs.scratch_dir }}
            first. You also have gh CLI access -- use `gh pr view
            <N> --repo ${{ steps.detect.outputs.repo }}` to pull
            context from the upstream PR if needed. Don't introduce
            new claims; only refine what's already there.

            Do NOT re-run /upstream-release-docs. Do NOT touch files
            under docs/toolhive/reference/cli/, static/api-specs/,
            or docs/toolhive/reference/crds/ — those are
            regenerated from release assets and aren't yours to edit.

            Do NOT touch GAPS.md or NO_CHANGES.md at the repo root
            if they exist -- they're signal files handed off to the
            next workflow step, not part of the docs.

      # Auto-apply the same formatters the project's pre-commit hook
      # runs, scoped to the files the skill touched. The skill's
      # sandbox doesn't include npm run prettier/eslint, so without
      # this step any formatting drift lands on PR CI as a "Lint and
      # format checks" failure requiring a human push. Scope via git
      # diff vs the pre-skill SHA so we don't reformat auto-generated
      # reference assets (which would fight the generators).
      - name: Auto-fix prettier and eslint on skill-touched files
        id: autofix
        if: always() && steps.skill_gen.conclusion == 'success'
        env:
          BASELINE_SHA: ${{ steps.pre_skill.outputs.sha }}
        run: |
          # Files the skill added/modified, excluding the three
          # auto-generated reference paths.
          CHANGED=$(git diff --name-only "$BASELINE_SHA..HEAD" -- \
            ':!docs/toolhive/reference/cli/' \
            ':!docs/toolhive/reference/crds/' \
            ':!static/api-specs/' \
            2>/dev/null | \
            grep -E '\.(md|mdx|ts|tsx|js|jsx|mjs|cjs|css|json|jsonc|yaml|yml)$' || true)
          if [ -z "$CHANGED" ]; then
            echo "No skill-touched files in scope for autofix."
            exit 0
          fi
          echo "Running prettier --write and eslint --fix on:"
          echo "$CHANGED"
          # xargs -0 with a NUL-delimited list so filenames with
          # spaces survive.
          printf '%s\n' "$CHANGED" | tr '\n' '\0' | \
            xargs -0 npx prettier --write --log-level warn
          # eslint --fix against mdx/ts/tsx/js only.
          LINT_TARGETS=$(printf '%s\n' "$CHANGED" | \
            grep -E '\.(mdx|ts|tsx|js|jsx|mjs|cjs)$' || true)
          if [ -n "$LINT_TARGETS" ]; then
            printf '%s\n' "$LINT_TARGETS" | tr '\n' '\0' | \
              xargs -0 npx eslint --fix --no-error-on-unmatched-pattern || \
              echo "::warning::eslint --fix reported non-zero; proceeding."
          fi
          if git diff --quiet; then
            echo "No formatting changes needed."
          else
            git add -A
            git commit -m "Apply prettier and eslint fixups to skill output"
          fi

      - name: Capture skill signal files
        id: signals
        run: |
          GAPS_BODY=""
          NO_CHANGES_BODY=""
          if [ -f GAPS.md ]; then
            GAPS_BODY=$(cat GAPS.md)
            rm GAPS.md
          fi
          if [ -f NO_CHANGES.md ]; then
            NO_CHANGES_BODY=$(cat NO_CHANGES.md)
            rm NO_CHANGES.md
          fi

          # Build full markdown fragments here so the PR body edit
          # step can treat them as plain strings.
          {
            echo "note_block<<NOTE_EOF"
            if [ -n "$NO_CHANGES_BODY" ]; then
              echo "> [!NOTE]"
              echo "> The skill reported no doc-relevant changes for this"
              echo "> release. This PR only bumps the version reference"
              echo "> and any pin_files substitutions."
              echo ">"
              echo "> $NO_CHANGES_BODY"
            fi
            echo "NOTE_EOF"

            echo "gaps_block<<GAPS_EOF"
            if [ -n "$GAPS_BODY" ]; then
              echo "## Gaps needing human context"
              echo ""
              echo "$GAPS_BODY"
            fi
            echo "GAPS_EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Apply pin_files substitutions
        env:
          PROJECT_ID: ${{ steps.detect.outputs.id }}
          NEW_TAG: ${{ steps.detect.outputs.new_tag }}
        run: |
          node scripts/upstream-release/apply-pin-files.mjs \
            --id "$PROJECT_ID" \
            --tag "$NEW_TAG"

      - name: Detect touches to auto-generated paths
        id: autogen
        # Runs AFTER the skill and AFTER the refresh commit above, so
        # the staged diff represents skill-introduced changes only.
        run: |
          git add -A
          TOUCHED=$(git diff --cached --name-only -- \
            'docs/toolhive/reference/cli/' \
            'static/api-specs/' \
            'docs/toolhive/reference/crds/' | paste -sd, - || true)
          {
            echo "note<<AUTOGEN_EOF"
            if [ -n "$TOUCHED" ]; then
              echo "> [!WARNING]"
              echo "> The skill touched files under auto-generated paths:"
              echo "> \`$TOUCHED\`"
              echo ">"
              echo "> These paths are synced or regenerated from release"
              echo "> assets earlier in this workflow. Review the skill's"
              echo "> changes and revert them if they should come from the"
              echo "> refresh step instead."
            fi
            echo "AUTOGEN_EOF"
          } >> "$GITHUB_OUTPUT"

      - name: Commit and push
        id: push
        env:
          PROJECT_ID: ${{ steps.detect.outputs.id }}
          NEW_TAG: ${{ steps.detect.outputs.new_tag }}
          HEAD_REF: ${{ steps.eff.outputs.head_ref }}
        run: |
          # Stage any skill content and add a content commit if non-empty.
          git add -A
          if ! git diff --cached --quiet; then
            git commit -m "Add upstream-release-docs content for $PROJECT_ID $NEW_TAG"
          else
            echo "No skill content changes to commit."
          fi

          # Skill can take 20-45 min; during that window someone may
          # push merges-from-main or other commits to the PR branch.
          # Handle that safely:
          #   - If our local HEAD is already on origin (no new work
          #     to push), exit cleanly.
          #   - Otherwise rebase any local-only commits onto the
          #     latest origin tip, then push. Conflicts fail loudly.
          git fetch origin "$HEAD_REF" --quiet
          if git merge-base --is-ancestor HEAD "origin/$HEAD_REF" 2>/dev/null; then
            echo "Origin is at or ahead of local; nothing to push."
          else
            git rebase "origin/$HEAD_REF" || {
              echo "::error::Rebase of local commits onto origin/$HEAD_REF hit conflicts. Resolve manually on the PR branch."
              exit 1
            }
            git push origin "HEAD:$HEAD_REF"
          fi

      - name: Augment PR body (marker-delimited section)
        # Runs even if earlier steps soft-failed so the augmentation
        # survives partial failures; a subsequent workflow_dispatch
        # retry will re-enter here.
        if: always() && steps.detect.outputs.id != ''
        env:
          PR_NUMBER: ${{ steps.eff.outputs.number }}
          PROJECT_ID: ${{ steps.detect.outputs.id }}
          NEW_TAG: ${{ steps.detect.outputs.new_tag }}
          PREV_TAG: ${{ steps.detect.outputs.prev_tag }}
          REPO: ${{ steps.detect.outputs.repo }}
          NOTE_BLOCK: ${{ steps.signals.outputs.note_block }}
          GAPS_BLOCK: ${{ steps.signals.outputs.gaps_block }}
          AUTOGEN_NOTE: ${{ steps.autogen.outputs.note }}
          COMPARE_OK: ${{ steps.reviewers.outputs.compare_ok }}
          MENTION_BLOCK: ${{ steps.reviewers.outputs.mention_block }}
          ASSIGN_LIST: ${{ steps.reviewers.outputs.list }}
        run: |
          START='<!-- upstream-release-docs:start -->'
          END='<!-- upstream-release-docs:end -->'

          # Build our section.
          {
            echo "$START"
            echo ""
            echo "## Content additions by upstream-release-docs"
            echo ""
            echo "Source-verified against \`$REPO\` at tag \`$NEW_TAG\` (was \`$PREV_TAG\`). Two Claude Opus sessions produced this update: a generation pass running the \`upstream-release-docs\` skill over all six phases, then a fresh-context editorial pass running \`docs-review\` over the changed files. Prettier and ESLint auto-fixes were applied afterward."
            echo ""
            if [ "$COMPARE_OK" != "true" ]; then
              echo "> [!WARNING]"
              echo "> Could not compare \`$PREV_TAG\` against \`$NEW_TAG\` upstream, so no reviewers were auto-assigned from release contributors. The pinned previous tag may have been retagged or deleted."
              echo ""
            fi
            if [ -n "$NOTE_BLOCK" ]; then
              echo "$NOTE_BLOCK"
              echo ""
            fi
            if [ -n "$AUTOGEN_NOTE" ]; then
              echo "$AUTOGEN_NOTE"
              echo ""
            fi
            echo "### Review guidance"
            echo ""
            echo "Machine-generated reference files under \`docs/toolhive/reference/cli/\`, \`static/api-specs/\`, and \`docs/toolhive/reference/crds/\` are synced or regenerated from upstream release assets (separate commit, titled \"Refresh reference assets\") and should be spot-checked only. Commits authored by the skill contain hand-edited prose; review those for accuracy, not just style. If the \"Gaps needing human context\" section below is populated, each entry includes a **Helper prompt for local Claude** that a reviewer can paste verbatim into their local Claude Code session to resolve the gap. Fill those in before merging."
            echo ""
            if [ -n "$GAPS_BLOCK" ]; then
              echo "$GAPS_BLOCK"
              echo ""
            fi
            echo "### Release contributors"
            echo ""
            if [ -n "$ASSIGN_LIST" ]; then
              # Comma list -> @-mention list for rendering.
              ASSIGNED_MENTIONS=$(echo "$ASSIGN_LIST" | tr ',' '\n' | sed 's/^/@/' | paste -sd' ' -)
              echo "Auto-assigned as reviewers (collaborators on this repo): $ASSIGNED_MENTIONS"
              echo ""
            fi
            if [ -n "$MENTION_BLOCK" ]; then
              echo "$MENTION_BLOCK"
              echo ""
            fi
            if [ -z "$ASSIGN_LIST" ] && [ -z "$MENTION_BLOCK" ]; then
              echo "No non-bot contributors were found in the release range."
              echo ""
            fi
            echo "$END"
          } > /tmp/section.md

          # Read existing body, replace or append our marked section.
          EXISTING=$(gh pr view "$PR_NUMBER" --json body --jq .body)
          if echo "$EXISTING" | grep -qF "$START"; then
            # Replace existing section.
            printf '%s\n' "$EXISTING" | awk -v start="$START" -v end="$END" -v repl_file=/tmp/section.md '
              BEGIN { in_section = 0 }
              $0 == start { in_section = 1; while ((getline line < repl_file) > 0) print line; next }
              $0 == end   { if (in_section) { in_section = 0; next } }
              !in_section { print }
            ' > /tmp/pr-body.md
          else
            # Append.
            {
              printf '%s\n\n---\n\n' "$EXISTING"
              cat /tmp/section.md
            } > /tmp/pr-body.md
          fi

          gh pr edit "$PR_NUMBER" --body-file /tmp/pr-body.md

      - name: Add reviewers
        if: always() && steps.reviewers.outputs.list != ''
        env:
          PR_NUMBER: ${{ steps.eff.outputs.number }}
          REVIEWERS: ${{ steps.reviewers.outputs.list }}
        run: gh pr edit "$PR_NUMBER" --add-reviewer "$REVIEWERS"

      - name: Comment on augmentation failure
        # Runs only when a preceding step failed. Comments a retry
        # pointer on the PR so a human can see the run URL.
        if: failure()
        env:
          PR_NUMBER: ${{ steps.eff.outputs.number }}
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
          gh pr comment "$PR_NUMBER" --body "Automated docs augmentation failed. Run: $RUN_URL

          Retry via the \`Upstream Release Docs\` workflow with \`pr_number=$PR_NUMBER\` once the underlying issue is resolved." || true