action.yml

name: 'CodeBoarding Action'
description: 'Visual system-design review on PRs and a versioned architecture baseline kept current on your branch: a Mermaid diff comment on every pull request, and the architecture synced to your branch on push.'
author: 'CodeBoarding'

branding:
  icon: 'git-pull-request'
  color: 'blue'

inputs:
  llm_api_key:
    description: 'Your LLM provider API key (see llm_provider). Optional: when empty, the action runs on the free hosted tier via a GitHub OIDC token (requires "permissions: id-token: write"). Set it (e.g. secrets.OPENROUTER_API_KEY) for unmetered usage or a non-OpenRouter provider.'
    required: false
    default: ''
  llm_provider:
    description: 'Provider for llm_api_key. The key is handed to the engine as that provider''s env var (anthropic -> ANTHROPIC_API_KEY, openai -> OPENAI_API_KEY, ...; aws_bedrock -> AWS_BEARER_TOKEN_BEDROCK, ollama -> OLLAMA_BASE_URL) and the engine auto-selects it. Default openrouter. Ignored on the free hosted tier (always OpenRouter via the proxy).'
    required: false
    default: 'openrouter'
  proxy_url:
    description: 'Base URL of the CodeBoarding hosted LLM proxy used for the free tier (no llm_api_key) and for license_key mode. The engine''s OPENROUTER_BASE_URL is pointed here; the proxy verifies the GitHub OIDC token, meters per repo owner, and swaps in the real key. Override only to point at a self-hosted/dev proxy.'
    required: false
    default: 'https://auduihjmm4b735zci7vyabuikq0hppqn.lambda-url.us-east-1.on.aws'  # prod gha_proxy Function URL (licensing-aws LicensingStack-Stateless-prod)
  license_key:
    description: 'A CodeBoarding license key (e.g. secrets.CODEBOARDING_LICENSE) for unmetered hosted usage via proxy_url. Takes precedence over the free OIDC tier; ignored when llm_api_key is set (BYO key talks to the provider directly).'
    required: false
    default: ''
  github_token:
    description: 'GITHUB_TOKEN used to post the PR comment. Defaults to the workflow token.'
    required: false
    default: ${{ github.token }}
  push_token:
    description: 'Token used for sync-mode git pushes to target_branch. Defaults to the workflow github.token, which can push when the calling workflow grants "permissions: contents: write". Kept separate from github_token so commenting can use a GitHub App token while the push uses the workflow token (whose write access the consumer controls).'
    required: false
    default: ${{ github.token }}
  engine_ref:
    description: 'Git ref (tag/branch/SHA) of CodeBoarding/CodeBoarding used as the analysis engine. Pinned to a release for reproducibility; override to track a newer ref.'
    required: false
    default: 'v0.12.1'
  depth_level:
    description: 'Analysis depth (1-3) for cold-start or force_full rebuilds. Once .codeboarding/analysis.json exists, its metadata.depth_level is the source of truth for incremental analysis and fallback-full recovery. Empty (default): 2 for cold starts.'
    required: false
    default: ''
  agent_model:
    description: 'Analysis model (AGENT_MODEL env var). A bare OpenRouter slug. Defaults to google/gemini-3-flash-preview on OpenRouter; for other providers, empty uses the engine''s per-provider default.'
    required: false
    default: ''
  parsing_model:
    description: 'Parsing model (PARSING_MODEL env var). A bare OpenRouter slug. Defaults to google/gemini-3.1-flash-lite-preview on OpenRouter; for other providers, empty uses the engine''s per-provider default.'
    required: false
    default: ''
  comment_header:
    description: 'Review mode: header line used inside the sticky PR comment.'
    required: false
    default: 'Architecture review'
  diagram_direction:
    description: 'Review mode: Mermaid layout direction: LR, TD, TB, RL, or BT.'
    required: false
    default: 'LR'
  changed_only:
    description: 'Review mode: render only changed components and their incident edges (also auto-applied when the full graph exceeds GitHub''s Mermaid limit).'
    required: false
    default: 'false'
  render_depth:
    description: 'Review mode: component levels to DRAW in the PR Mermaid (independent of depth_level): 1 = top-level flat (default), 2 = +one nesting level as subgraphs, etc. Lets you analyze deep (depth_level=2) but display a clean level-1 diagram.'
    required: false
    default: '1'
  cta_base_url:
    description: 'Review mode: base URL of the click proxy (e.g. https://go.codeboarding.org). When set, the editor link deep-links into VS Code/Cursor via the proxy and a "get the extension" link is added (owner/repo/pr tracked). Empty (default) links to the extension listing instead, since GitHub strips vscode:/cursor: schemes from comment links.'
    required: false
    default: ''
  webview_base_url:
    description: 'Review mode: hosted webview base URL. The PR comment links to an artifact-backed head-vs-base architecture diff; review mode does not commit generated files to PR branches. Set empty to disable the browser link.'
    required: false
    default: 'https://app.codeboarding.org'
  trigger_command:
    description: 'Review mode: slash-command that triggers the action from a PR comment (issue_comment event). A comment whose first word is this runs the diagram on-demand.'
    required: false
    default: '/codeboarding'
  feedback_command:
    description: 'Review mode: slash-command for submitting explicit feedback to CodeBoarding. The command and following text are sent to CodeBoarding via PostHog (not anonymous telemetry, and no analysis runs). Opt out with CODEBOARDING_TELEMETRY=false or DO_NOT_TRACK=1.'
    required: false
    default: '/codeboarding-feedback'
  feedback_max_chars:
    description: 'Review mode: maximum number of feedback characters sent from /codeboarding-feedback (the text is truncated past this).'
    required: false
    default: '4000'
  mode:
    description: 'What the action does. "review" (default): post a Mermaid architecture-diff comment on the PR (pull_request / issue_comment events). "sync": analyze on push and commit the architecture (analysis.json + rendered docs) to target_branch, keeping it versioned and current (the baseline review mode diffs against). Events: push / workflow_dispatch / schedule. Run the two modes from separate workflow files with least-privilege permissions each.'
    required: false
    default: 'review'
  output_dir:
    description: 'Sync mode: directory where the rendered docs and analysis metadata are committed. The action OWNS this directory: pre-existing top-level markdown files in it are deleted on every run, so do not point it at a directory with hand-written docs.'
    required: false
    default: '.codeboarding'
  output_format:
    description: 'Sync mode: rendered docs format. Currently only .md is supported.'
    required: false
    default: '.md'
  target_branch:
    description: 'Sync mode: branch the generated docs are pushed to.'
    required: false
    default: ${{ github.ref_name }}
  write_architecture_md:
    description: 'Sync mode: also write docs/development/architecture.md (all rendered docs concatenated, overview first).'
    required: false
    default: 'true'
  commit_message:
    description: 'Sync mode: commit message for the generated docs. Deliberately carries no "[skip ci]" — the regen loop is prevented by the workflow''s paths-ignore plus the action''s own bot-commit guard, so the marker is unneeded and (via squash-merge) would skip the workflows real merges should run.'
    required: false
    default: 'chore(codeboarding): sync architecture baseline'
  force_full:
    description: 'Sync mode: ignore any committed baseline and run a full analysis from scratch. Use to rebuild a stale or corrupt baseline (the manual escape hatch that replaces the old refresh-baseline workflow).'
    required: false
    default: 'false'

outputs:
  diagram_md:
    description: 'Review mode: path to the rendered ```mermaid block (in the runner workspace).'
    value: ${{ steps.diagram.outputs.diagram_md }}
  n_changed:
    description: 'Review mode: number of components added/modified/deleted, counted recursively.'
    value: ${{ steps.diagram.outputs.n_changed }}
  truncated:
    description: 'Review mode: true if the diagram was reduced to changed-only to fit GitHub''s Mermaid limit.'
    value: ${{ steps.diagram.outputs.truncated }}
  analysis_mode:
    description: 'Sync mode: "full" or "incremental".'
    value: ${{ steps.sync_analyze.outputs.analysis_mode }}
  files_written:
    description: 'Sync mode: number of rendered markdown files in output_dir.'
    value: ${{ steps.sync_commit.outputs.files_written }}
  committed:
    description: 'Sync mode: true when a docs commit was created and pushed.'
    value: ${{ steps.sync_commit.outputs.committed }}
  review_artifact_url:
    description: 'Review mode: GitHub Actions artifact URL containing the PR-head analysis.json and metadata.'
    value: ${{ steps.upload_review_artifact.outputs.artifact-url }}

runs:
  using: 'composite'
  # One spine, two heads. Steps run in four phases; every mode-specific step is
  # gated `if: steps.guard.outputs.mode == 'review' | 'sync'`, and the two modes
  # interleave only because they share the LLM-key lifecycle, NOT because they
  # are unrelated:
  #   1. GUARD            — resolve mode + event eligibility + SHAs (one source of truth)
  #   2. SHARED SETUP     — checkout engine + target, Python/Node/uv, caches, LLM-key prep
  #   3. ANALYSIS (key live) — review: base/seed/head/health ; sync: seed/analyze
  #   4. Drop LLM key, then OUTPUT (no key) — review: diff→artifact→comment ; sync: render→commit
  # The binding between the modes is the committed .codeboarding/analysis.json
  # baseline: sync (phase 3/4) writes it, review (phase 3) reads it as the PR base.
  steps:
    - name: Guard — resolve mode and target
      id: guard
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github_token }}
        # Read from env, NEVER interpolated into the script — a comment body is
        # untrusted input and must not reach the shell as code (injection).
        COMMENT_BODY: ${{ github.event.comment.body }}
        AUTHOR_ASSOC: ${{ github.event.comment.author_association }}
        TRIGGER: ${{ inputs.trigger_command }}
        # Feedback path (/codeboarding-feedback): a lightweight branch that sends
        # the comment text to PostHog and exits before any checkout/engine setup.
        # The script reads CODEBOARDING_POSTHOG_KEY/HOST and the opt-outs
        # DO_NOT_TRACK / CODEBOARDING_TELEMETRY straight from the caller's env: a
        # composite action inherits the calling workflow/job `env:` as real env
        # vars, so those need no re-mapping here. POSTHOG_KEY/HOST below are a
        # redundant alias the script only falls back to if the canonical vars are
        # unset — kept as a hint that the destination is overridable.
        FEEDBACK_COMMAND: ${{ inputs.feedback_command }}
        FEEDBACK_MAX_CHARS: ${{ inputs.feedback_max_chars }}
        POSTHOG_KEY: ${{ env.CODEBOARDING_POSTHOG_KEY }}
        POSTHOG_HOST: ${{ env.CODEBOARDING_POSTHOG_HOST }}
        SENDER_LOGIN: ${{ github.event.sender.login }}
        SENDER_ID: ${{ github.event.sender.id }}
        COMMENT_ID: ${{ github.event.comment.id }}
        COMMENT_URL: ${{ github.event.comment.html_url }}
        REPOSITORY_ID: ${{ github.event.repository.id }}
        RUN_ATTEMPT: ${{ github.run_attempt }}
        ACTION_PATH: ${{ github.action_path }}
        ACTION_REF: ${{ github.action_ref || github.sha }}
        EVENT: ${{ github.event_name }}
        REPOSITORY: ${{ github.repository }}
        PR_NUMBER_PULL: ${{ github.event.pull_request.number }}
        PULL_BASE_SHA: ${{ github.event.pull_request.base.sha }}
        PULL_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        PULL_HEAD_REF: ${{ github.event.pull_request.head.ref }}
        PULL_BASE_REF: ${{ github.event.pull_request.base.ref }}
        PULL_BASE_REPO: ${{ github.event.pull_request.base.repo.full_name }}
        PULL_HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
        ISSUE_NUMBER: ${{ github.event.issue.number }}
        ISSUE_PR_URL: ${{ github.event.issue.pull_request.url }}
        MODE: ${{ inputs.mode }}
        REF_TYPE: ${{ github.ref_type }}
        TARGET_SHA: ${{ github.sha }}
        TARGET_BRANCH: ${{ inputs.target_branch }}
        OUTPUT_DIR: ${{ inputs.output_dir }}
        OUTPUT_FORMAT: ${{ inputs.output_format }}
        WRITE_ARCH: ${{ inputs.write_architecture_md }}
        DEPTH: ${{ inputs.depth_level }}
        HEAD_AUTHOR_EMAIL: ${{ github.event.head_commit.author.email }}
      run: |
        set -uo pipefail
        skip() { echo "::notice::$1 Skipping."; echo "skip=true" >> "$GITHUB_OUTPUT"; exit 0; }

        # Misconfigured inputs hard-fail; event mismatches soft-skip (a workflow
        # may legitimately deliver events the selected mode doesn't handle).
        case "$MODE" in
          review|sync) ;;
          *) echo "::error::mode must be 'review' or 'sync' (got '$MODE')."; exit 1 ;;
        esac
        case "$DEPTH" in
          ''|1|2|3) ;;
          *) echo "::error::depth_level must be 1, 2, or 3 (empty = default cold-start depth 2)."; exit 1 ;;
        esac
        echo "mode=$MODE" >> "$GITHUB_OUTPUT"

        if [ "$MODE" = "sync" ]; then
          # Sync mode: analyze the pushed/selected commit and push generated docs
          # to target_branch. Sync is an explicit opt-in (never inferred from the
          # event) and accepts only non-PR triggers — a branch-pushing mode must
          # not be reachable from a workflow run over PR-head code.
          case "$EVENT" in
            push|workflow_dispatch|schedule) ;;
            *) skip "Unsupported event '$EVENT' in sync mode (use push, workflow_dispatch, or schedule; mode: review handles pull_request)." ;;
          esac
          if [ "$EVENT" = "push" ] && [ "$REF_TYPE" = "tag" ]; then
            skip "Sync mode runs on branch pushes, not tag pushes."
          fi
          # Regen-loop guard: never re-analyze our OWN baseline commit. Sync
          # commits as codeboarding[bot]; if a push's head commit is ours, skip.
          # This holds even if a consumer omits the workflow's paths-ignore (the
          # primary guard), and replaces the old "[skip ci]" marker — which
          # leaked into squash-merge commit messages and wrongly skipped the
          # workflows real merges should run (sync itself, release tooling, CI).
          if [ "$EVENT" = "push" ] && [ "$HEAD_AUTHOR_EMAIL" = "codeboarding[bot]@users.noreply.github.com" ]; then
            skip "Push head commit is CodeBoarding's own baseline commit; not re-analyzing (loop guard)."
          fi
          case "$OUTPUT_FORMAT" in
            .md) ;;
            *) echo "::error::output_format must be .md."; exit 1 ;;
          esac
          case "$OUTPUT_DIR" in
            ""|/*|..|../*|*/../*|*/..) echo "::error::output_dir must be a relative path inside the repository."; exit 1 ;;
          esac
          case "$WRITE_ARCH" in
            true|false) ;;
            *) echo "::error::write_architecture_md must be true or false."; exit 1 ;;
          esac
          [ -n "$TARGET_BRANCH" ] || { echo "::error::target_branch is empty."; exit 1; }
          {
            echo "skip=false"
            echo "target_sha=$TARGET_SHA"
            echo "target_branch=$TARGET_BRANCH"
            echo "start_ts=$(date +%s)"
            echo "checkout_repo=$REPOSITORY"
            echo "checkout_sha=$TARGET_SHA"
          } >> "$GITHUB_OUTPUT"
          echo "Sync mode: analyzing ${REPOSITORY}@${TARGET_SHA}, pushing docs to ${TARGET_BRANCH} (via $EVENT)"
          exit 0
        fi

        # Review mode from here down.
        # Sticky-comment targeting. Written up front so the failure-comment step
        # always has a header even if PR resolution below fails. Automatic
        # pull_request runs reuse one stable header → the comment is updated in
        # place. An on-demand /codeboarding run uses a run-unique header so it
        # posts a NEW comment and never touches comments from earlier runs; its
        # own in-progress→result→failure steps still share it (one comment per
        # invocation). Re-running the same run keeps the same run id, so a re-run
        # updates that invocation's comment rather than spawning another.
        if [ "$EVENT" = "issue_comment" ]; then
          echo "sticky_header=codeboarding-architecture-diff-run-${GITHUB_RUN_ID}" >> "$GITHUB_OUTPUT"
        else
          echo "sticky_header=codeboarding-architecture-diff" >> "$GITHUB_OUTPUT"
        fi

        if [ "$EVENT" = "pull_request" ]; then
          PR_NUMBER="$PR_NUMBER_PULL"
          BASE_SHA="$PULL_BASE_SHA"
          HEAD_SHA="$PULL_HEAD_SHA"
          HEAD_REF="$PULL_HEAD_REF"
          BASE_REF="$PULL_BASE_REF"
          BASE_REPO="$PULL_BASE_REPO"
          HEAD_REPO="$PULL_HEAD_REPO"
        elif [ "$EVENT" = "pull_request_target" ]; then
          skip "pull_request_target is not supported because it can expose secrets to PR-head code; use pull_request or trusted issue_comment."
        elif [ "$EVENT" = "issue_comment" ]; then
          # On-demand "/codeboarding" command. Must be a PR comment whose first
          # word is the trigger; the payload lacks SHAs so we query the API.
          [ -n "$ISSUE_PR_URL" ] || skip "Comment is on a plain issue, not a PR."
          FIRST_WORD="$(printf '%s' "$COMMENT_BODY" | tr -d '\r' | awk 'NR==1{print $1; exit}')"
          # Feedback command: forward the comment text to PostHog, then stop BEFORE
          # the trusted-association check, checkout, engine setup, and LLM key.
          # Sending user-written feedback runs no PR code, so it doesn't need the
          # collaborator gate the analysis path does — the workflow's own `if:`
          # decides who can reach this step. The script swallows its own failures
          # and the guard has no `set -e`, so feedback can never block the action.
          if [ "$FIRST_WORD" = "$FEEDBACK_COMMAND" ]; then
            python3 "$ACTION_PATH/scripts/submit_feedback.py"
            echo "skip=true" >> "$GITHUB_OUTPUT"
            echo "feedback_received=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          [ "$FIRST_WORD" = "$TRIGGER" ] || skip "Comment does not start with '$TRIGGER'."
          # SECURITY (pwn-request guard): issue_comment runs in the base repo WITH
          # secrets for ANY commenter. Only a trusted collaborator may trigger an
          # analysis that checks out + runs over PR-head code with the LLM key present.
          case "$AUTHOR_ASSOC" in
            OWNER|MEMBER|COLLABORATOR) : ;;
            *) skip "Commenter is '$AUTHOR_ASSOC' (not OWNER/MEMBER/COLLABORATOR)." ;;
          esac
          PR_NUMBER="$ISSUE_NUMBER"
          PR_JSON="$(gh api "repos/${REPOSITORY}/pulls/${PR_NUMBER}" 2>/dev/null)" || skip "Could not fetch PR #$PR_NUMBER from the API."
          BASE_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["sha"])' 2>/dev/null)" || skip "Could not parse base SHA from the PR API."
          HEAD_SHA="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["sha"])' 2>/dev/null)" || skip "Could not parse head SHA from the PR API."
          HEAD_REF="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["ref"])' 2>/dev/null)" || HEAD_REF=""
          BASE_REF="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["ref"])' 2>/dev/null)" || BASE_REF=""
          BASE_REPO="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["base"]["repo"]["full_name"])' 2>/dev/null)" || skip "Could not parse base repo from the PR API."
          HEAD_REPO="$(printf '%s' "$PR_JSON" | python3 -c 'import json,sys;print(json.load(sys.stdin)["head"]["repo"]["full_name"])' 2>/dev/null)" || skip "Could not parse head repo from the PR API."
          [ "$HEAD_REPO" = "$REPOSITORY" ] || skip "On-demand runs with secrets are disabled for fork PRs."
        else
          skip "Unsupported event '$EVENT' in review mode (use pull_request or issue_comment; set mode: sync to version your architecture on push)."
        fi

        { [ -n "$PR_NUMBER" ] && [ -n "$BASE_SHA" ] && [ -n "$HEAD_SHA" ] && [ -n "$BASE_REPO" ] && [ -n "$HEAD_REPO" ]; } || skip "Could not resolve PR/base/head SHAs/repos."
        {
          echo "skip=false"
          echo "pr_number=$PR_NUMBER"
          echo "base_sha=$BASE_SHA"
          echo "head_sha=$HEAD_SHA"
          echo "head_ref=$HEAD_REF"
          echo "base_ref=$BASE_REF"
          echo "base_repo=$BASE_REPO"
          echo "head_repo=$HEAD_REPO"
          echo "checkout_repo=$HEAD_REPO"
          echo "checkout_sha=$HEAD_SHA"
          # same_repo gates pushing the head analysis: forks give a read-only token.
          if [ "$HEAD_REPO" = "$REPOSITORY" ]; then echo "same_repo=true"; else echo "same_repo=false"; fi
        } >> "$GITHUB_OUTPUT"
        echo "Resolved PR #$PR_NUMBER (base=$BASE_REPO@$BASE_SHA head=$HEAD_REPO@$HEAD_SHA) via $EVENT"

    # Feedback exits the guard with skip=true, so the analysis "Acknowledge
    # command" step below (gated on skip != 'true') never fires for it; this one
    # reacts instead, keyed on the feedback_received flag the guard set.
    - name: Acknowledge feedback
      if: steps.guard.outputs.feedback_received == 'true'
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github_token }}
        REPOSITORY: ${{ github.repository }}
        COMMENT_ID: ${{ github.event.comment.id }}
      run: |
        # 👍 react to the feedback comment so the user knows it was received.
        gh api -X POST "repos/${REPOSITORY}/issues/comments/${COMMENT_ID}/reactions" \
          -f content='+1' >/dev/null 2>&1 || true

    - name: Acknowledge command
      if: steps.guard.outputs.skip != 'true' && github.event_name == 'issue_comment'
      shell: bash
      env:
        GH_TOKEN: ${{ inputs.github_token }}
        REPOSITORY: ${{ github.repository }}
        COMMENT_ID: ${{ github.event.comment.id }}
      run: |
        # 👀 react to the triggering comment so the user knows it was picked up.
        gh api -X POST "repos/${REPOSITORY}/issues/comments/${COMMENT_ID}/reactions" \
          -f content=eyes >/dev/null 2>&1 || true

    - name: Post in-progress comment
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      continue-on-error: true
      uses: marocchino/sticky-pull-request-comment@v2
      with:
        header: ${{ steps.guard.outputs.sticky_header }}
        number: ${{ steps.guard.outputs.pr_number }}
        message: |
          ### ${{ inputs.comment_header }} · analyzing…

          ⏳ CodeBoarding is analyzing the architecture changes in this PR. This usually takes a few minutes.

          <sub>codeboarding-action · run ${{ github.run_id }}</sub>
        GITHUB_TOKEN: ${{ inputs.github_token }}

    - name: Checkout CodeBoarding engine
      if: steps.guard.outputs.skip != 'true'
      uses: actions/checkout@v4
      with:
        repository: CodeBoarding/CodeBoarding
        ref: ${{ inputs.engine_ref }}
        path: codeboarding-engine
        persist-credentials: false

    # Review mode: the PR head repo at the head SHA. Sync mode: this repo at the
    # pushed/selected SHA. Always credential-free — sync pushes authenticate
    # explicitly via push_token.
    - name: Checkout target repository
      if: steps.guard.outputs.skip != 'true'
      uses: actions/checkout@v4
      with:
        repository: ${{ steps.guard.outputs.checkout_repo }}
        path: target-repo
        fetch-depth: 0
        ref: ${{ steps.guard.outputs.checkout_sha }}
        persist-credentials: false

    - name: Ensure PR comparison commits are fetched
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      shell: bash
      working-directory: target-repo
      env:
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
        BASE_REPO: ${{ steps.guard.outputs.base_repo }}
        BASE_REF: ${{ steps.guard.outputs.base_ref }}
      run: |
        git remote add base "https://github.com/${BASE_REPO}.git" 2>/dev/null || git remote set-url base "https://github.com/${BASE_REPO}.git"
        # The baseline search walks the PR head ancestry, which checkout fetched
        # with fetch-depth: 0. We still fetch the PR base commit for GitHub-style
        # changed-file diffs and for the no-baseline fallback full base analysis.
        if [ -n "$BASE_REF" ]; then
          git fetch --no-tags base "+refs/heads/${BASE_REF}:refs/remotes/codeboarding-base/${BASE_REF}" || true
        fi
        git fetch origin "$BASE_SHA" --depth=2 || true
        if ! git cat-file -e "$BASE_SHA" 2>/dev/null; then
          git remote add base "https://github.com/${BASE_REPO}.git" 2>/dev/null || git remote set-url base "https://github.com/${BASE_REPO}.git"
          git fetch base "$BASE_SHA" --depth=2 || true
        fi
        git cat-file -e "$BASE_SHA" && echo "Base commit reachable." || \
          (echo "::error::Base commit $BASE_SHA is not reachable." && exit 1)

    - name: Resolve analysis depth
      id: resolve_depth
      if: steps.guard.outputs.skip != 'true'
      shell: bash
      env:
        INPUT_DEPTH: ${{ inputs.depth_level }}
      run: |
        set -euo pipefail
        # Explicit input controls cold-start/force_full rebuilds. Existing
        # analysis.json metadata is the source of truth for incremental runs.
        if [ -n "$INPUT_DEPTH" ]; then
          echo "depth=$INPUT_DEPTH" >> "$GITHUB_OUTPUT"
          echo "Using explicit depth_level=$INPUT_DEPTH."
          exit 0
        fi
        DEPTH=2
        echo "depth=$DEPTH" >> "$GITHUB_OUTPUT"
        echo "Using default cold-start depth_level=$DEPTH."

    - name: Set up Python 3.13
      if: steps.guard.outputs.skip != 'true'
      uses: actions/setup-python@v5
      with:
        python-version: '3.13'

    - name: Set up Node.js 20
      if: steps.guard.outputs.skip != 'true'
      uses: actions/setup-node@v4
      with:
        node-version: '20'

    - name: Install uv
      if: steps.guard.outputs.skip != 'true'
      uses: astral-sh/setup-uv@v4
      with:
        enable-cache: true   # cache ~/.cache/uv (wheels/builds) for fast cold installs

    - name: Cache uv venv (engine)
      if: steps.guard.outputs.skip != 'true'
      uses: actions/cache@v4
      with:
        path: codeboarding-engine/.venv
        # No restore-keys: a lockfile change must force a clean cold venv, not
        # restore a venv built from a different lock (`uv pip install -e .` won't
        # downgrade/sync already-installed transitive deps back to this uv.lock).
        key: cb-uv-${{ runner.os }}-${{ hashFiles('codeboarding-engine/pyproject.toml', 'codeboarding-engine/uv.lock') }}

    - name: Cache LSP servers
      if: steps.guard.outputs.skip != 'true'
      uses: actions/cache@v4
      with:
        path: |
          codeboarding-engine/static_analyzer/servers/node_modules
          codeboarding-engine/static_analyzer/servers/bin
        key: cb-lsp-${{ runner.os }}-v1
        restore-keys: |
          cb-lsp-${{ runner.os }}-

    - name: Install Python dependencies
      if: steps.guard.outputs.skip != 'true'
      shell: bash
      working-directory: codeboarding-engine
      run: |
        test -d .venv || uv venv   # reuse the cached venv instead of wiping it (--clear defeated the cache)
        uv pip install -e .

    - name: Install LSP servers
      if: steps.guard.outputs.skip != 'true'
      shell: bash
      working-directory: codeboarding-engine
      run: |
        uv run python install.py --auto-install-npm

    - name: Prepare & verify LLM key
      if: steps.guard.outputs.skip != 'true'
      id: llm
      shell: bash
      env:
        RAW_KEY: ${{ inputs.llm_api_key }}
        RAW_PROVIDER: ${{ inputs.llm_provider }}
        RAW_AGENT_MODEL: ${{ inputs.agent_model }}
        RAW_PARSING_MODEL: ${{ inputs.parsing_model }}
        RAW_LICENSE: ${{ inputs.license_key }}
        RAW_PROXY_URL: ${{ inputs.proxy_url }}
      run: |
        set -euo pipefail
        AUTH_FILE="${RUNNER_TEMP}/openrouter-auth.json"
        trap 'rm -f "$AUTH_FILE"' EXIT

        _strip() { printf '%s' "$1" | tr -d '[:space:]' | sed -e 's/^"//;s/"$//' -e "s/^'//;s/'\$//"; }
        # Cache keys reject some characters (model slugs carry '/'); sanitize for them.
        _safe() { printf '%s' "$1" | tr -c 'A-Za-z0-9._-' '_'; }

        KEY="$(_strip "$RAW_KEY")"
        LICENSE="$(_strip "$RAW_LICENSE")"
        PROXY_URL="$(_strip "$RAW_PROXY_URL")"
        PROXY_URL="${PROXY_URL%/}"   # no trailing slash; engine appends /chat/completions
        AGENT_MODEL="$(_strip "$RAW_AGENT_MODEL")"
        PARSING_MODEL="$(_strip "$RAW_PARSING_MODEL")"
        umask 077

        # Three credential modes, in precedence order:
        #   1. BYO key set            -> talk to the provider directly (current behavior)
        #   2. license_key set        -> hosted proxy, bearer = the license
        #   3. neither (zero-config)  -> hosted proxy, bearer = a GitHub OIDC JWT
        # Modes 2 & 3 force provider=openrouter and point the engine's
        # OPENROUTER_BASE_URL at the proxy (written to cb-base-url). The proxy
        # swaps in the real key, so no provider preflight here.
        if [ -n "$KEY" ]; then
          MODE="byokey"
        elif [ -n "$LICENSE" ]; then
          MODE="license"
        else
          MODE="oidc"
        fi
        echo "mode=$MODE" >> "$GITHUB_OUTPUT"
        echo "Credential mode: $MODE"

        # ── Hosted modes (license / oidc): provider is always OpenRouter via proxy ──
        # The hosted tiers run on CodeBoarding's OpenRouter account, so the engine
        # always talks OpenRouter here (the bearer is the license/OIDC token, which
        # the proxy swaps for the real key). To use a DIFFERENT provider, set
        # llm_api_key for that provider (that's BYO-key mode, below).
        if [ "$MODE" != "byokey" ]; then
          if [ -z "$PROXY_URL" ]; then
            echo "::error::proxy_url is empty but no llm_api_key was provided. Set llm_api_key, or restore proxy_url."
            exit 1
          fi
          # Warn if the user asked for a non-OpenRouter provider but gave no key:
          # the hosted tier can only use OpenRouter, so llm_provider is ignored here.
          PROVIDER_NORM="$(printf '%s' "$RAW_PROVIDER" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9_')"
          if [ -n "$PROVIDER_NORM" ] && [ "$PROVIDER_NORM" != "openrouter" ]; then
            echo "::warning::llm_provider='$PROVIDER_NORM' is ignored on the free/license hosted tier (OpenRouter only). To use $PROVIDER_NORM, pass its key via llm_api_key."
          fi
          PROVIDER_ENV="OPENROUTER_API_KEY"
          AGENT_MODEL="${AGENT_MODEL:-google/gemini-3-flash-preview}"
          PARSING_MODEL="${PARSING_MODEL:-google/gemini-3.1-flash-lite-preview}"

          if [ "$MODE" = "license" ]; then
            BEARER="$LICENSE"
            echo "Using CodeBoarding license via hosted proxy."
          else
            # Mint a GitHub Actions OIDC JWT (audience must match the proxy's).
            # ACTIONS_ID_TOKEN_REQUEST_URL/_TOKEN are injected into the runner
            # process env (NOT the `env` context) only when the job grants
            # `id-token: write`; read them directly from the shell env.
            if [ -z "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || [ -z "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ]; then
              echo "::error::No GitHub OIDC token available. Add \`permissions: id-token: write\` to the job (or set an llm_api_key / license_key). The free hosted tier needs the OIDC token to identify your repository."
              exit 1
            fi
            OIDC_RESP="$(curl -sS --max-time 15 \
              -H "Authorization: Bearer ${ACTIONS_ID_TOKEN_REQUEST_TOKEN}" \
              "${ACTIONS_ID_TOKEN_REQUEST_URL}&audience=codeboarding-proxy" || true)"
            BEARER="$(printf '%s' "$OIDC_RESP" | python3 -c 'import json,sys;print(json.load(sys.stdin).get("value",""))' 2>/dev/null || true)"
            if [ -z "$BEARER" ]; then
              echo "::error::Failed to mint a GitHub OIDC token (is \`permissions: id-token: write\` granted?)."
              exit 1
            fi
            echo "Using the free hosted tier via a GitHub OIDC token (metered per repository owner)."
          fi

          echo "::add-mask::$BEARER"
          printf '%s' "$BEARER" > "${RUNNER_TEMP}/cb-llm-key"
          printf '%s' "$PROVIDER_ENV" > "${RUNNER_TEMP}/cb-provider-env"
          printf '%s' "$PROXY_URL" > "${RUNNER_TEMP}/cb-base-url"
          printf '%s' "$AGENT_MODEL" > "${RUNNER_TEMP}/cb-agent-model"
          printf '%s' "$PARSING_MODEL" > "${RUNNER_TEMP}/cb-parsing-model"
          exit 0
        fi

        # ── BYO key mode: unchanged behavior (talk to the provider directly) ──
        # Resolve the provider -> the env var the engine reads. Convention is
        # <NAME>_API_KEY; two providers don't follow it. The engine is the source
        # of truth: an unknown provider just yields an env var it won't recognize,
        # and the engine errors with the list of valid keys.
        PROVIDER="$(printf '%s' "$RAW_PROVIDER" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9_')"
        PROVIDER="${PROVIDER:-openrouter}"
        case "$PROVIDER" in
          aws_bedrock) PROVIDER_ENV="AWS_BEARER_TOKEN_BEDROCK" ;;
          ollama)      PROVIDER_ENV="OLLAMA_BASE_URL" ;;
          *)           PROVIDER_ENV="$(printf '%s' "$PROVIDER" | tr '[:lower:]' '[:upper:]')_API_KEY" ;;
        esac

        # Normalize a pasted key: strip a leading `<ENV>=`.
        case "$KEY" in "${PROVIDER_ENV}="*) KEY="${KEY#${PROVIDER_ENV}=}";; esac
        KEY="$(_strip "$KEY")"
        echo "::add-mask::$KEY"
        echo "Provider: $PROVIDER -> $PROVIDER_ENV; key length: ${#KEY}"

        if [ "$PROVIDER" = "openrouter" ]; then
          # Default models on OpenRouter when the user didn't pin one (cheap Gemini).
          # Other providers fall through to the engine's own per-provider default.
          AGENT_MODEL="${AGENT_MODEL:-google/gemini-3-flash-preview}"
          PARSING_MODEL="${PARSING_MODEL:-google/gemini-3.1-flash-lite-preview}"
          # OpenRouter-only checks. The litellm 'openrouter/...' model prefix 400s
          # the engine's native OpenRouter call; other providers use native ids.
          for M in "$AGENT_MODEL" "$PARSING_MODEL"; do
            case "$M" in
              openrouter/*)
                echo "::error::Invalid model '$M': drop the 'openrouter/' prefix and use a bare OpenRouter slug, e.g. anthropic/claude-sonnet-4."
                exit 1 ;;
            esac
          done
          # Cheap preflight; other providers are validated by the engine at run time.
          STATUS=$(curl -sS -o "$AUTH_FILE" -w "%{http_code}" \
            -H "Authorization: Bearer $KEY" --max-time 10 \
            https://openrouter.ai/api/v1/auth/key || echo "curl-fail")
          echo "OpenRouter /auth/key response: HTTP $STATUS"
          if [ "$STATUS" != "200" ]; then
            # Surface the upstream error MESSAGE only — never the whole auth body (avoid leaking).
            MSG="$(AUTH_FILE="$AUTH_FILE" python3 -c 'import json,os;print(json.load(open(os.environ["AUTH_FILE"])).get("error",{}).get("message",""))' 2>/dev/null || true)"
            echo "::error::OpenRouter rejected the API key (HTTP $STATUS). ${MSG:-Verify the OPENROUTER_API_KEY secret.}"
            exit 1
          fi
        fi

        # Store key material in runner-temp files. Later shell steps read these
        # explicitly; third-party post-comment actions do not inherit the LLM key.
        # No cb-base-url in BYO mode -> the engine talks to the provider directly.
        printf '%s' "$KEY" > "${RUNNER_TEMP}/cb-llm-key"
        printf '%s' "$PROVIDER_ENV" > "${RUNNER_TEMP}/cb-provider-env"
        printf '%s' "$AGENT_MODEL" > "${RUNNER_TEMP}/cb-agent-model"
        printf '%s' "$PARSING_MODEL" > "${RUNNER_TEMP}/cb-parsing-model"

        # Sanitized copies for use inside actions/cache keys (sync mode).
        {
          echo "cache_provider=$(_safe "$PROVIDER")"
          echo "cache_agent_model=$(_safe "${AGENT_MODEL:-default}")"
          echo "cache_parsing_model=$(_safe "${PARSING_MODEL:-default}")"
        } >> "$GITHUB_OUTPUT"

    - name: Resolve base analysis (committed baseline)
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: base
      shell: bash
      working-directory: target-repo
      env:
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
        HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
        ACTION_PATH: ${{ github.action_path }}
      run: |
        BASE_DIR="${RUNNER_TEMP}/cb-base"
        HEAD_DIR="${RUNNER_TEMP}/cb-head"
        mkdir -p "$BASE_DIR" "$HEAD_DIR"
        echo "base_dir=$BASE_DIR" >> $GITHUB_OUTPUT
        echo "head_dir=$HEAD_DIR" >> $GITHUB_OUTPUT
        BASELINE_SHA=""
        # Use the newest analysis.json reachable by walking backwards through
        # the PR head branch ancestry. If the PR branch is a->b->c->d and master
        # is a->b->m1->m2, this deliberately searches d,c,b,a — not m2,m1,b,a.
        while IFS= read -r candidate; do
          if git cat-file -e "${candidate}:.codeboarding/analysis.json" 2>/dev/null; then
            BASELINE_SHA="$candidate"
            break
          fi
        done < <(git rev-list "$HEAD_SHA" -- .codeboarding/analysis.json 2>/dev/null || true)

        if [ -n "$BASELINE_SHA" ] && git show "${BASELINE_SHA}:.codeboarding/analysis.json" > "${BASE_DIR}/analysis.json" 2>/dev/null; then
          if python3 "$ACTION_PATH/scripts/engine_adapter.py" validate-base \
              --analysis "${BASE_DIR}/analysis.json" \
              --expected-sha "$BASELINE_SHA"; then
            echo "committed=true" >> $GITHUB_OUTPUT
            echo "baseline_sha=$BASELINE_SHA" >> $GITHUB_OUTPUT
            if [ "$BASELINE_SHA" = "$HEAD_SHA" ]; then
              echo "Using committed .codeboarding/analysis.json at PR head ${HEAD_SHA}."
            else
              echo "Using nearest committed .codeboarding/analysis.json at ${BASELINE_SHA} from PR head history ${HEAD_SHA}."
            fi
          else
            rm -f "${BASE_DIR}/analysis.json"
            echo "committed=false" >> $GITHUB_OUTPUT
            echo "baseline_sha=$BASE_SHA" >> $GITHUB_OUTPUT
            echo "Committed baseline at ${BASELINE_SHA} is unusable; will generate a fresh base analysis at ${BASE_SHA}."
          fi
        else
          rm -f "${BASE_DIR}/analysis.json"
          echo "committed=false" >> $GITHUB_OUTPUT
          echo "baseline_sha=$BASE_SHA" >> $GITHUB_OUTPUT
          echo "No committed baseline found in PR head history; will generate one via a full analysis on the base commit ${BASE_SHA}."
        fi

    - name: Restore base artifacts (keyed by baseline SHA)
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: basecache
      uses: actions/cache/restore@v4
      with:
        path: ${{ runner.temp }}/cb-base
        # Fold in the credential mode (byokey/license/oidc). The cache key is
        # otherwise (provider, agent_model, parsing_model) from the raw INPUTS, but
        # the hosted tiers force OpenRouter + Gemini defaults regardless of those
        # inputs. So a free-tier run (oidc, forced Gemini) and a BYO OpenRouter-key
        # run with no model pinned would share a key yet produce different base
        # analyses; the mode discriminator keeps them from reusing each other's cache.
        key: cb-base-v2-${{ runner.os }}-${{ steps.base.outputs.baseline_sha }}-d${{ steps.resolve_depth.outputs.depth }}-${{ inputs.engine_ref }}-${{ steps.llm.outputs.mode }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}

    # A committed analysis.json gives the head analysis stable component ids,
    # but the engine's incremental path ALSO needs the base static_analysis.pkl
    # with its cluster baseline — which git can't provide (the pkl is never
    # committed, by design). Build it here deterministically: LSP + Leiden
    # clustering, no LLM key read. Fail-open: a failed seed degrades to exactly
    # the previous behavior (the head run falls back to a full analysis).
    - name: Seed base static-analysis cache (committed baseline, no cached pkl)
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.base.outputs.committed == 'true' && steps.basecache.outputs.cache-hit != 'true'
      id: seedbase
      continue-on-error: true
      shell: bash
      working-directory: codeboarding-engine
      env:
        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
        CACHING_DOCUMENTATION: 'false'
        ENABLE_MONITORING: 'false'
        ACTION_PATH: ${{ github.action_path }}
        TARGET: ${{ github.workspace }}/target-repo
        BASE_DIR: ${{ steps.base.outputs.base_dir }}
        BASELINE_SHA: ${{ steps.base.outputs.baseline_sha }}
      run: |
        # Clean up any stale registration before re-adding (rm -rf alone leaves a
        # dangling worktree entry that makes a retry's `worktree add` fail).
        BASE_SRC="${RUNNER_TEMP}/base-src"
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
        git -C "$TARGET" worktree prune
        rm -rf "$BASE_SRC"
        git -C "$TARGET" worktree add --detach "$BASE_SRC" "$BASELINE_SHA"
        if uv run python "$ACTION_PATH/scripts/engine_adapter.py" seed \
             --repo "$BASE_SRC" \
             --out "$BASE_DIR" \
             --source-sha "$BASELINE_SHA" \
           && [ -f "$BASE_DIR/static_analysis.pkl" ] && [ -f "$BASE_DIR/static_analysis.sha" ]; then
          echo "seed_ok=true" >> "$GITHUB_OUTPUT"
          echo "::notice::Seeded base static-analysis cache for ${BASELINE_SHA}; head analysis can run incrementally."
        else
          # Never leave a partial pkl/sha pair behind: the save step below would
          # cache it under this base SHA's key and suppress every retry.
          rm -f "$BASE_DIR/static_analysis.pkl" "$BASE_DIR/static_analysis.sha"
          echo "seed_ok=false" >> "$GITHUB_OUTPUT"
          echo "::warning::Base static-analysis seeding failed; head analysis will fall back to a full run."
        fi
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true

    - name: Generate base analysis (no committed baseline)
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.base.outputs.committed == 'false' && steps.basecache.outputs.cache-hit != 'true'
      shell: bash
      working-directory: codeboarding-engine
      env:
        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
        DIAGRAM_DEPTH_LEVEL: ${{ steps.resolve_depth.outputs.depth }}
        CACHING_DOCUMENTATION: 'false'
        ENABLE_MONITORING: 'false'
        ACTION_PATH: ${{ github.action_path }}
        TARGET: ${{ github.workspace }}/target-repo
        BASE_DIR: ${{ steps.base.outputs.base_dir }}
        REPO_NAME: ${{ github.event.repository.name }}
        RUN_ID_BASE: ${{ github.run_id }}-${{ github.run_attempt }}-base
        DEPTH: ${{ steps.resolve_depth.outputs.depth }}
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
      run: |
        # Export the key under the selected provider's env var (only this one),
        # so the engine auto-selects that provider.
        PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
        export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
        # Hosted modes (license/oidc) point the engine at the CodeBoarding proxy;
        # absent in BYO-key mode, where the engine talks to the provider directly.
        if [ -f "${RUNNER_TEMP}/cb-base-url" ]; then
          export OPENROUTER_BASE_URL="$(cat "${RUNNER_TEMP}/cb-base-url")"
        fi
        # The engine_adapter drops this sentinel on a 402 (free-tier cap reached)
        # so the failure-comment step can post a tailored message.
        export CB_QUOTA_SENTINEL="${RUNNER_TEMP}/cb-quota-exhausted"
        # Export the model env only when the user set it; empty -> the engine uses
        # its own valid per-provider default (no stale hardcoded model id to rot).
        AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
        PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
        if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
        if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi

        BASE_SRC="${RUNNER_TEMP}/base-src"
        # Clean up any stale registration before re-adding (rm -rf alone leaves a
        # dangling worktree entry that makes a retry's `worktree add` fail).
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
        git -C "$TARGET" worktree prune
        rm -rf "$BASE_SRC"
        git -C "$TARGET" worktree add --detach "$BASE_SRC" "$BASE_SHA"
        uv run python "$ACTION_PATH/scripts/engine_adapter.py" base \
          --repo "$BASE_SRC" \
          --out "$BASE_DIR" \
          --name "$REPO_NAME" \
          --run-id "$RUN_ID_BASE" \
          --depth "$DEPTH" \
          --source-sha "$BASE_SHA"
        git -C "$TARGET" worktree remove --force "$BASE_SRC" 2>/dev/null || true
        if [ ! -f "$BASE_DIR/analysis.json" ]; then
          echo "::error::Base full analysis ran but analysis.json is missing."
          exit 1
        fi

    # Covers both base-artifact producers: the full analysis (no committed
    # baseline) and the seeded pkl (committed baseline). The seed_ok gate is
    # load-bearing — caching a pkl-less dir under this base SHA's key would
    # permanently suppress seeding retries for it.
    - name: Save generated base artifacts
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.basecache.outputs.cache-hit != 'true' && (steps.base.outputs.committed == 'false' || steps.seedbase.outputs.seed_ok == 'true')
      uses: actions/cache/save@v4
      with:
        path: ${{ runner.temp }}/cb-base
        # Fold in the credential mode (byokey/license/oidc). The cache key is
        # otherwise (provider, agent_model, parsing_model) from the raw INPUTS, but
        # the hosted tiers force OpenRouter + Gemini defaults regardless of those
        # inputs. So a free-tier run (oidc, forced Gemini) and a BYO OpenRouter-key
        # run with no model pinned would share a key yet produce different base
        # analyses; the mode discriminator keeps them from reusing each other's cache.
        key: cb-base-v2-${{ runner.os }}-${{ steps.base.outputs.baseline_sha }}-d${{ steps.resolve_depth.outputs.depth }}-${{ inputs.engine_ref }}-${{ steps.llm.outputs.mode }}-${{ inputs.llm_provider }}-${{ inputs.agent_model }}-${{ inputs.parsing_model }}

    - name: Analyze PR head (incremental from base)
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: analyze
      shell: bash
      working-directory: codeboarding-engine
      env:
        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
        DIAGRAM_DEPTH_LEVEL: ${{ steps.resolve_depth.outputs.depth }}
        CACHING_DOCUMENTATION: 'false'
        ENABLE_MONITORING: 'false'
        ACTION_PATH: ${{ github.action_path }}
        TARGET_REPO: ${{ github.workspace }}/target-repo
        BASE_DIR: ${{ steps.base.outputs.base_dir }}
        HEAD_DIR: ${{ steps.base.outputs.head_dir }}
        REPO_NAME: ${{ github.event.repository.name }}
        RUN_ID_HEAD: ${{ github.run_id }}-${{ github.run_attempt }}-head
        DEPTH: ${{ steps.resolve_depth.outputs.depth }}
        BASELINE_SHA: ${{ steps.base.outputs.baseline_sha }}
        HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
      run: |
        # Export the key under the selected provider's env var (only this one),
        # so the engine auto-selects that provider.
        PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
        export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
        # Hosted modes (license/oidc) point the engine at the CodeBoarding proxy;
        # absent in BYO-key mode, where the engine talks to the provider directly.
        if [ -f "${RUNNER_TEMP}/cb-base-url" ]; then
          export OPENROUTER_BASE_URL="$(cat "${RUNNER_TEMP}/cb-base-url")"
        fi
        # The engine_adapter drops this sentinel on a 402 (free-tier cap reached)
        # so the failure-comment step can post a tailored message.
        export CB_QUOTA_SENTINEL="${RUNNER_TEMP}/cb-quota-exhausted"
        # Export the model env only when the user set it; empty -> the engine uses
        # its own valid per-provider default (no stale hardcoded model id to rot).
        AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
        PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
        if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
        if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi

        # Seed the head dir from the base analysis so incremental stitches
        # component ids from the baseline (stable diff). Base dir is left
        # untouched as the "before" snapshot for the diff.
        cp -a "$BASE_DIR"/. "$HEAD_DIR"/ 2>/dev/null || true
        rm -rf "$HEAD_DIR/health"
        uv run python "$ACTION_PATH/scripts/engine_adapter.py" head \
          --repo "$TARGET_REPO" \
          --out "$HEAD_DIR" \
          --name "$REPO_NAME" \
          --run-id "$RUN_ID_HEAD" \
          --depth "$DEPTH" \
          --base-ref "$BASELINE_SHA" \
          --target-ref "$HEAD_SHA" \
          --source-sha "$HEAD_SHA"
        if [ ! -f "$HEAD_DIR/analysis.json" ]; then
          echo "::error::Head analysis ran but analysis.json is missing."
          exit 1
        fi
        echo "base_analysis=$BASE_DIR/analysis.json" >> $GITHUB_OUTPUT
        echo "head_analysis=$HEAD_DIR/analysis.json" >> $GITHUB_OUTPUT

    - name: Architecture health check (best-effort)
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: health
      continue-on-error: true
      shell: bash
      working-directory: codeboarding-engine
      env:
        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
        ACTION_PATH: ${{ github.action_path }}
        ARTIFACT_DIR: ${{ steps.base.outputs.head_dir }}
        TARGET_REPO: ${{ github.workspace }}/target-repo
        REPO_NAME: ${{ github.event.repository.name }}
      run: |
        rm -f /tmp/cb-issues.txt
        # engine_adapter writes the WARNING/CRITICAL count (0 on any failure — best-effort).
        uv run python "$ACTION_PATH/scripts/engine_adapter.py" health \
          --artifact-dir "$ARTIFACT_DIR" \
          --repo "$TARGET_REPO" \
          --name "$REPO_NAME" \
          --issues-out /tmp/cb-issues.txt || true
        ISSUE_COUNT=$(cat /tmp/cb-issues.txt 2>/dev/null || echo 0)
        echo "issues=$ISSUE_COUNT" >> $GITHUB_OUTPUT
        echo "Architecture issues: $ISSUE_COUNT"

    # ---- Sync mode: analyze the target commit (mirrors the review pipeline's
    # baseline/seed/incremental strategy, but against the committed analysis.json
    # in the working tree instead of the PR base). ----

    - name: Seed sync workdir from committed baseline
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
      id: sync_seed
      shell: bash
      working-directory: target-repo
      env:
        OUTPUT_DIR: ${{ inputs.output_dir }}
        ACTION_PATH: ${{ github.action_path }}
      run: |
        set -euo pipefail
        ANALYSIS_DIR="${RUNNER_TEMP}/cb-sync"
        RENDER_DIR="${RUNNER_TEMP}/cb-sync-render"
        ARCHITECTURE_FILE="${RUNNER_TEMP}/cb-architecture.md"
        rm -rf "$ANALYSIS_DIR" "$RENDER_DIR"
        mkdir -p "$ANALYSIS_DIR" "$RENDER_DIR"
        {
          echo "cb_dir=$ANALYSIS_DIR"
          echo "render_dir=$RENDER_DIR"
          echo "arch_file=$ARCHITECTURE_FILE"
        } >> "$GITHUB_OUTPUT"

        if [ -f "$OUTPUT_DIR/analysis.json" ]; then
          cp "$OUTPUT_DIR/analysis.json" "$ANALYSIS_DIR/analysis.json"
          if [ -f "$OUTPUT_DIR/static_analysis.pkl" ] && [ -f "$OUTPUT_DIR/static_analysis.sha" ]; then
            cp "$OUTPUT_DIR/static_analysis.pkl" "$ANALYSIS_DIR/static_analysis.pkl"
            cp "$OUTPUT_DIR/static_analysis.sha" "$ANALYSIS_DIR/static_analysis.sha"
            echo "committed_cache=true" >> "$GITHUB_OUTPUT"
          else
            echo "committed_cache=false" >> "$GITHUB_OUTPUT"
          fi
          # baseline-info parses metadata.commit_hash and emits it ONLY when it is
          # present and SHA-shaped, so an unusable/injected value never reaches
          # GITHUB_OUTPUT, the cache key, or git. (Pure stdlib — no engine venv.)
          BASELINE_SHA="$(python3 "$ACTION_PATH/scripts/engine_adapter.py" baseline-info \
            --analysis "$ANALYSIS_DIR/analysis.json" | sed -n 's/^commit_hash=//p')"
          if [ -n "$BASELINE_SHA" ]; then
            echo "baseline_present=true" >> "$GITHUB_OUTPUT"
            echo "baseline_sha=$BASELINE_SHA" >> "$GITHUB_OUTPUT"
            echo "Using committed baseline generated for $BASELINE_SHA."
          else
            rm -f "$ANALYSIS_DIR/analysis.json" "$ANALYSIS_DIR/static_analysis.pkl" "$ANALYSIS_DIR/static_analysis.sha"
            echo "baseline_present=false" >> "$GITHUB_OUTPUT"
            echo "baseline_sha=none" >> "$GITHUB_OUTPUT"
            echo "committed_cache=false" >> "$GITHUB_OUTPUT"
            echo "::warning::Committed analysis.json has no usable metadata.commit_hash; a full analysis will run."
          fi
        else
          echo "baseline_present=false" >> "$GITHUB_OUTPUT"
          echo "baseline_sha=none" >> "$GITHUB_OUTPUT"
          echo "committed_cache=false" >> "$GITHUB_OUTPUT"
          echo "No committed baseline found; a full analysis will run."
        fi

    - name: Restore sync static-analysis cache
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync' && steps.sync_seed.outputs.baseline_present == 'true' && steps.sync_seed.outputs.committed_cache != 'true'
      id: sync_cache
      uses: actions/cache/restore@v4
      with:
        path: |
          ${{ runner.temp }}/cb-sync/static_analysis.pkl
          ${{ runner.temp }}/cb-sync/static_analysis.sha
        key: cb-sync-${{ runner.os }}-${{ inputs.engine_ref }}-d${{ steps.resolve_depth.outputs.depth }}-${{ steps.llm.outputs.cache_provider }}-${{ steps.llm.outputs.cache_agent_model }}-${{ steps.llm.outputs.cache_parsing_model }}-${{ steps.sync_seed.outputs.baseline_sha }}

    # Same rationale as the review pipeline's seed step: the committed
    # analysis.json supplies component ids, but the incremental path also needs
    # the baseline static_analysis.pkl (LSP + clustering, no LLM). Fail-open.
    - name: Seed sync static-analysis cache at baseline SHA
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync' && steps.sync_seed.outputs.baseline_present == 'true' && steps.sync_seed.outputs.committed_cache != 'true' && steps.sync_cache.outputs.cache-hit != 'true'
      id: sync_seedcache
      continue-on-error: true
      shell: bash
      working-directory: codeboarding-engine
      env:
        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
        # The seed subcommand defaults to github_action attribution; sync-mode
        # telemetry must report as sync (setdefault never clobbers this).
        CODEBOARDING_SOURCE: 'sync'
        CACHING_DOCUMENTATION: 'false'
        ENABLE_MONITORING: 'false'
        ACTION_PATH: ${{ github.action_path }}
        TARGET_REPO: ${{ github.workspace }}/target-repo
        ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
        BASELINE_SHA: ${{ steps.sync_seed.outputs.baseline_sha }}
      run: |
        set -euo pipefail
        echo "seed_ok=false" >> "$GITHUB_OUTPUT"
        if ! git -C "$TARGET_REPO" cat-file -e "${BASELINE_SHA}^{commit}" 2>/dev/null; then
          echo "::warning::Baseline commit $BASELINE_SHA is not reachable; analysis will fall back to full if needed."
          exit 0
        fi

        # Clean up any stale registration before re-adding (rm -rf alone leaves a
        # dangling worktree entry that makes a retry's `worktree add` fail).
        BASE_SRC="${RUNNER_TEMP}/cb-sync-base-src"
        git -C "$TARGET_REPO" worktree remove --force "$BASE_SRC" 2>/dev/null || true
        git -C "$TARGET_REPO" worktree prune
        rm -rf "$BASE_SRC"
        git -C "$TARGET_REPO" worktree add --detach "$BASE_SRC" "$BASELINE_SHA"
        if uv run python "$ACTION_PATH/scripts/engine_adapter.py" seed \
             --repo "$BASE_SRC" \
             --out "$ANALYSIS_DIR" \
             --source-sha "$BASELINE_SHA" \
           && [ -f "$ANALYSIS_DIR/static_analysis.pkl" ] && [ -f "$ANALYSIS_DIR/static_analysis.sha" ]; then
          echo "seed_ok=true" >> "$GITHUB_OUTPUT"
          echo "::notice::Seeded static-analysis cache for $BASELINE_SHA."
        else
          rm -f "$ANALYSIS_DIR/static_analysis.pkl" "$ANALYSIS_DIR/static_analysis.sha"
          echo "::warning::Static-analysis seeding failed; analysis may fall back to full."
        fi
        git -C "$TARGET_REPO" worktree remove --force "$BASE_SRC" 2>/dev/null || true

    - name: Analyze target repository (sync)
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
      id: sync_analyze
      shell: bash
      working-directory: codeboarding-engine
      env:
        STATIC_ANALYSIS_CONFIG: ${{ github.workspace }}/codeboarding-engine/static_analysis_config.yml
        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
        DIAGRAM_DEPTH_LEVEL: ${{ steps.resolve_depth.outputs.depth }}
        CACHING_DOCUMENTATION: 'false'
        ENABLE_MONITORING: 'false'
        ACTION_PATH: ${{ github.action_path }}
        TARGET_REPO: ${{ github.workspace }}/target-repo
        ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
        REPO_NAME: ${{ github.event.repository.name }}
        RUN_ID_SYNC: ${{ github.run_id }}-${{ github.run_attempt }}-sync
        TARGET_SHA: ${{ steps.guard.outputs.target_sha }}
        DEPTH: ${{ steps.resolve_depth.outputs.depth }}
        FORCE_FULL: ${{ inputs.force_full }}
      run: |
        set -euo pipefail
        # Export the key under the selected provider's env var (only this one),
        # so the engine auto-selects that provider.
        PROVIDER_ENV="$(cat "${RUNNER_TEMP}/cb-provider-env")"
        export "$PROVIDER_ENV"="$(cat "${RUNNER_TEMP}/cb-llm-key")"
        # Hosted modes (license/oidc) point the engine at the CodeBoarding proxy;
        # absent in BYO-key mode, where the engine talks to the provider directly.
        if [ -f "${RUNNER_TEMP}/cb-base-url" ]; then
          export OPENROUTER_BASE_URL="$(cat "${RUNNER_TEMP}/cb-base-url")"
        fi
        # The engine_adapter drops this sentinel on a 402 (free-tier cap reached)
        # so the failure-comment step can post a tailored message.
        export CB_QUOTA_SENTINEL="${RUNNER_TEMP}/cb-quota-exhausted"
        # Export the model env only when the user set it; empty -> the engine uses
        # its own valid per-provider default (no stale hardcoded model id to rot).
        AGENT_MODEL="$(cat "${RUNNER_TEMP}/cb-agent-model")"
        PARSING_MODEL="$(cat "${RUNNER_TEMP}/cb-parsing-model")"
        if [ -n "$AGENT_MODEL" ]; then export AGENT_MODEL; fi
        if [ -n "$PARSING_MODEL" ]; then export PARSING_MODEL; fi

        args=(
          --repo "$TARGET_REPO"
          --out "$ANALYSIS_DIR"
          --name "$REPO_NAME"
          --run-id "$RUN_ID_SYNC"
          --source-sha "$TARGET_SHA"
          --depth "$DEPTH"
        )
        [ "$FORCE_FULL" = "true" ] && args+=(--force-full)
        LOG="${RUNNER_TEMP}/cb-sync-analyze.log"
        uv run python "$ACTION_PATH/scripts/engine_adapter.py" analyze "${args[@]}" | tee "$LOG"
        MODE="$(sed -n 's/^analysis_mode=//p' "$LOG" | tail -1)"
        MODE="${MODE:-unknown}"
        echo "analysis_mode=$MODE" >> "$GITHUB_OUTPUT"
        echo "analysis_path=$ANALYSIS_DIR/analysis.json" >> "$GITHUB_OUTPUT"
        [ -f "$ANALYSIS_DIR/analysis.json" ] || { echo "::error::Analysis ran but analysis.json is missing."; exit 1; }

    - name: Drop LLM key material
      if: always() && steps.guard.outputs.skip != 'true'
      shell: bash
      run: |
        rm -f "${RUNNER_TEMP}/cb-llm-key" \
              "${RUNNER_TEMP}/cb-provider-env" \
              "${RUNNER_TEMP}/cb-base-url" \
              "${RUNNER_TEMP}/cb-agent-model" \
              "${RUNNER_TEMP}/cb-parsing-model"

    - name: Diff analyses → Mermaid
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: diagram
      shell: bash
      env:
        ACTION_PATH: ${{ github.action_path }}
        BASE_ANALYSIS: ${{ steps.analyze.outputs.base_analysis }}
        HEAD_ANALYSIS: ${{ steps.analyze.outputs.head_analysis }}
        DIRECTION: ${{ inputs.diagram_direction }}
        RENDER_DEPTH: ${{ inputs.render_depth }}
        CHANGED_ONLY: ${{ inputs.changed_only }}
      run: |
        case "$CHANGED_ONLY" in
          true|false) ;;
          *) echo "::error::changed_only must be 'true' or 'false'."; exit 1 ;;
        esac
        case "$RENDER_DEPTH" in
          ''|*[!0-9]*) echo "::error::render_depth must be a positive integer."; exit 1 ;;
        esac

        args=(
          --base "$BASE_ANALYSIS"
          --head "$HEAD_ANALYSIS"
          --out "${RUNNER_TEMP}/diagram.md"
          --direction "$DIRECTION"
          --render-depth "$RENDER_DEPTH"
        )
        [ "$CHANGED_ONLY" = "true" ] && args+=(--changed-only)
        META=$(python3 "$ACTION_PATH/scripts/diff_to_mermaid.py" "${args[@]}")
        echo "$META" > "${RUNNER_TEMP}/diagram_meta.json"
        echo "diff meta: $META"
        read CHANGED_COUNT CHANGED RENDERED TRUNCATED < <(python3 -c "import json;d=json.load(open('${RUNNER_TEMP}/diagram_meta.json'));print(d['n_changed'], str(d.get('changed', d['n_changed']>0)).lower(), str(d['rendered']).lower(), str(d['truncated']).lower())")
        echo "n_changed=$CHANGED_COUNT" >> $GITHUB_OUTPUT
        echo "changed=$CHANGED" >> $GITHUB_OUTPUT
        echo "rendered=$RENDERED" >> $GITHUB_OUTPUT
        echo "truncated=$TRUNCATED" >> $GITHUB_OUTPUT
        echo "diagram_md=${RUNNER_TEMP}/diagram.md" >> $GITHUB_OUTPUT

    - name: Prepare PR analysis artifact
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: review_artifact
      shell: bash
      env:
        HEAD_ANALYSIS: ${{ steps.analyze.outputs.head_analysis }}
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
        BASELINE_SHA: ${{ steps.base.outputs.baseline_sha }}
        BASELINE_COMMITTED: ${{ steps.base.outputs.committed }}
        HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
        PR: ${{ steps.guard.outputs.pr_number }}
        OWNER_REPO: ${{ github.repository }}
        RUN_ID: ${{ github.run_id }}
        RUN_ATTEMPT: ${{ github.run_attempt }}
      run: |
        set -euo pipefail
        ARTIFACT_DIR="${RUNNER_TEMP}/codeboarding-pr-artifact"
        ARTIFACT_NAME="codeboarding-pr-${PR}-${HEAD_SHA}"
        export ARTIFACT_NAME
        rm -rf "$ARTIFACT_DIR"
        mkdir -p "$ARTIFACT_DIR"
        cp "$HEAD_ANALYSIS" "$ARTIFACT_DIR/analysis.json"
        python3 - <<'PY' > "$ARTIFACT_DIR/metadata.json"
        import json, os

        baseline_committed = os.environ["BASELINE_COMMITTED"] == "true"
        print(json.dumps({
            "repository": os.environ["OWNER_REPO"],
            "pr": os.environ["PR"],
            "pr_base_sha": os.environ["BASE_SHA"],
            "base_commit_sha": os.environ["BASELINE_SHA"] if baseline_committed else None,
            "base_commit_found": baseline_committed,
            "head_sha": os.environ["HEAD_SHA"],
            "run_id": os.environ["RUN_ID"],
            "run_attempt": os.environ["RUN_ATTEMPT"],
            "artifact_name": os.environ["ARTIFACT_NAME"],
        }, indent=2))
        PY
        echo "path=$ARTIFACT_DIR" >> "$GITHUB_OUTPUT"
        echo "name=$ARTIFACT_NAME" >> "$GITHUB_OUTPUT"

    - name: Upload PR analysis artifact
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: upload_review_artifact
      uses: actions/upload-artifact@v4
      with:
        name: ${{ steps.review_artifact.outputs.name }}
        path: ${{ steps.review_artifact.outputs.path }}
        retention-days: 14

    - name: Build PR comment body
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: body
      shell: bash
      env:
        # Pass event/input-derived strings as DATA (not interpolated into the script).
        HEADER: ${{ inputs.comment_header }}
        BASE_REF: ${{ steps.guard.outputs.base_ref }}
        CTA_BASE: ${{ inputs.cta_base_url }}
        OWNER_REPO: ${{ github.repository }}
        ACTION_PATH: ${{ github.action_path }}
        TARGET_REPO: ${{ github.workspace }}/target-repo
        DIAGRAM_MD: ${{ steps.diagram.outputs.diagram_md }}
        BASE_ANALYSIS: ${{ steps.analyze.outputs.base_analysis }}
        HEAD_ANALYSIS: ${{ steps.analyze.outputs.head_analysis }}
        RUN_ID: ${{ github.run_id }}
        CHANGED_COUNT: ${{ steps.diagram.outputs.n_changed }}
        CHANGED: ${{ steps.diagram.outputs.changed }}
        RENDERED: ${{ steps.diagram.outputs.rendered }}
        TRUNCATED: ${{ steps.diagram.outputs.truncated }}
        PR: ${{ steps.guard.outputs.pr_number }}
        ISSUES: ${{ steps.health.outputs.issues }}
        WEBVIEW_BASE: ${{ inputs.webview_base_url }}
        HEAD_SHA: ${{ steps.guard.outputs.head_sha }}
        ARTIFACT_NAME: ${{ steps.review_artifact.outputs.name }}
        ARTIFACT_URL: ${{ steps.upload_review_artifact.outputs.artifact-url }}
        BASE_SHA: ${{ steps.guard.outputs.base_sha }}
      run: |
        BODY_FILE=$(mktemp)
        OWNER="${OWNER_REPO%%/*}"; REPO="${OWNER_REPO##*/}"

        headline() {
          if [ "$CHANGED" != "true" ]; then echo "no architectural changes";
          elif [ "$CHANGED_COUNT" = "1" ]; then echo "1 component changed";
          elif [ "$CHANGED_COUNT" = "0" ]; then echo "architecture updated";
          else echo "$CHANGED_COUNT components changed"; fi
        }

        # CTA footer: a hosted webview browser link backed by the uploaded PR
        # artifact, editor link(s), and the ⚠️ banner. PR analysis data is not
        # committed to the PR branch.
        cta() {
          local extra=()
          if [ -n "$WEBVIEW_BASE" ] && [ -n "$ARTIFACT_NAME" ]; then
            extra+=(
              --webview-ready
              --webview-base "$WEBVIEW_BASE"
              --head-sha "$HEAD_SHA"
              --base-sha "$BASE_SHA"
              --run-id "$RUN_ID"
              --artifact-name "$ARTIFACT_NAME"
              --artifact-url "$ARTIFACT_URL"
            )
          fi
          python3 "$ACTION_PATH/scripts/build_cta.py" \
            --cta-base "$CTA_BASE" --owner "$OWNER" --repo "$REPO" --pr "$PR" \
            --repo-path "$TARGET_REPO" --issues "${ISSUES:-0}" "${extra[@]}"
        }

        # Per-component changed-file dropdowns: which files made each node change
        # color. The git listing is the PR's own changes (three-dot merge-base..head,
        # the same set as the Files-changed tab; --no-renames so a moved file's old
        # path still appears for the donor component). Node colors compare against
        # the base *tip*, so a node colored only by base-branch churn on a stale PR
        # gets no dropdown. Best-effort: if the git diff fails (e.g. merge-base
        # unreachable on a shallow fork fetch) the script falls back to
        # analysis-derived changes, and if the script fails the section is omitted —
        # the comment always posts.
        FILES_MD="${RUNNER_TEMP}/component_files.md"
        : > "$FILES_MD"
        if [ -n "$BASE_ANALYSIS" ] && [ -n "$HEAD_ANALYSIS" ]; then
          CHANGED_LIST="${RUNNER_TEMP}/changed_files.txt"
          files_args=(--base "$BASE_ANALYSIS" --head "$HEAD_ANALYSIS" --out "$FILES_MD")
          if git -C "$TARGET_REPO" -c core.quotepath=off diff --no-renames --name-only "$BASE_SHA...HEAD" > "$CHANGED_LIST" 2>/dev/null; then
            files_args+=(--changed-files "$CHANGED_LIST")
          fi
          python3 "$ACTION_PATH/scripts/build_component_files.py" "${files_args[@]}" || : > "$FILES_MD"
        fi

        {
          echo "### ${HEADER} · $(headline)"
          echo ""
          if [ "$RENDERED" = "true" ]; then
            cat "$DIAGRAM_MD"
            echo ""
            echo ""
            echo "Colors indicate component changes compared to \`${BASE_REF}\`: 🟩 Added · 🟨 Modified · 🟥 Removed"
            if [ "$TRUNCATED" = "true" ]; then
              echo ""
              echo "<sub>Showing changed components only — the full graph exceeds GitHub's inline Mermaid limit.</sub>"
            fi
          elif [ "$CHANGED" = "true" ]; then
            echo "Architecture changed versus \`${BASE_REF}\`, but the diagram is too large to render inline (GitHub caps inline Mermaid at ~500 edges)."
          else
            echo "No architectural changes detected versus \`${BASE_REF}\`."
          fi
          if [ -n "$ARTIFACT_URL" ]; then
            echo ""
            echo "Download the PR analysis artifacts from this workflow [artifact](${ARTIFACT_URL})."
          fi
          if [ -s "$FILES_MD" ]; then
            echo ""
            cat "$FILES_MD"
          fi
          cta
          echo ""
          echo "<sub>codeboarding-action · run ${RUN_ID}</sub>"
        } > "$BODY_FILE"

        echo "body_file=$BODY_FILE" >> "$GITHUB_OUTPUT"

    - name: Post sticky PR comment
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      uses: marocchino/sticky-pull-request-comment@v2
      with:
        header: ${{ steps.guard.outputs.sticky_header }}
        number: ${{ steps.guard.outputs.pr_number }}
        path: ${{ steps.body.outputs.body_file }}
        GITHUB_TOKEN: ${{ inputs.github_token }}

    # ---- Sync mode: render and commit the architecture. ----

    - name: Render docs
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
      id: sync_render
      shell: bash
      working-directory: codeboarding-engine
      env:
        PROJECT_ROOT: ${{ github.workspace }}/codeboarding-engine
        ACTION_PATH: ${{ github.action_path }}
        ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
        RENDER_DIR: ${{ steps.sync_seed.outputs.render_dir }}
        ARCHITECTURE_FILE: ${{ steps.sync_seed.outputs.arch_file }}
        REPO_NAME: ${{ github.event.repository.name }}
        REPOSITORY: ${{ github.repository }}
        TARGET_BRANCH: ${{ steps.guard.outputs.target_branch }}
        OUTPUT_DIR: ${{ inputs.output_dir }}
        OUTPUT_FORMAT: ${{ inputs.output_format }}
        WRITE_ARCHITECTURE_MD: ${{ inputs.write_architecture_md }}
      run: |
        set -euo pipefail
        REPO_REF="https://github.com/${REPOSITORY}/blob/${TARGET_BRANCH}/${OUTPUT_DIR}"
        uv run python "$ACTION_PATH/scripts/engine_adapter.py" render \
          --analysis "$ANALYSIS_DIR/analysis.json" \
          --out "$RENDER_DIR" \
          --repo-name "$REPO_NAME" \
          --repo-ref "$REPO_REF" \
          --format "$OUTPUT_FORMAT"
        if [ "$WRITE_ARCHITECTURE_MD" = "true" ]; then
          uv run python "$ACTION_PATH/scripts/engine_adapter.py" concat \
            --docs-dir "$RENDER_DIR" \
            --out "$ARCHITECTURE_FILE"
        fi
        echo "docs_dir=$RENDER_DIR" >> "$GITHUB_OUTPUT"
        echo "architecture_file=$ARCHITECTURE_FILE" >> "$GITHUB_OUTPUT"

    - name: Check sync static-analysis cache files
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
      id: sync_cachecheck
      shell: bash
      env:
        ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
      run: |
        set -euo pipefail
        if [ -f "$ANALYSIS_DIR/static_analysis.pkl" ] && [ -f "$ANALYSIS_DIR/static_analysis.sha" ]; then
          echo "has_cache=true" >> "$GITHUB_OUTPUT"
        else
          echo "has_cache=false" >> "$GITHUB_OUTPUT"
          echo "::notice::No static-analysis pkl/sha pair to cache."
        fi

    - name: Save sync static-analysis cache
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync' && steps.sync_cachecheck.outputs.has_cache == 'true'
      continue-on-error: true
      uses: actions/cache/save@v4
      with:
        path: |
          ${{ runner.temp }}/cb-sync/static_analysis.pkl
          ${{ runner.temp }}/cb-sync/static_analysis.sha
        key: cb-sync-${{ runner.os }}-${{ inputs.engine_ref }}-d${{ steps.resolve_depth.outputs.depth }}-${{ steps.llm.outputs.cache_provider }}-${{ steps.llm.outputs.cache_agent_model }}-${{ steps.llm.outputs.cache_parsing_model }}-${{ steps.guard.outputs.target_sha }}

    - name: Commit and push synced architecture
      if: steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
      id: sync_commit
      shell: bash
      working-directory: target-repo
      env:
        ANALYSIS_DIR: ${{ steps.sync_seed.outputs.cb_dir }}
        DOCS_DIR: ${{ steps.sync_render.outputs.docs_dir }}
        ARCHITECTURE_FILE: ${{ steps.sync_render.outputs.architecture_file }}
        OUTPUT_DIR: ${{ inputs.output_dir }}
        OUTPUT_FORMAT: ${{ inputs.output_format }}
        WRITE_ARCHITECTURE_MD: ${{ inputs.write_architecture_md }}
        COMMIT_MESSAGE: ${{ inputs.commit_message }}
        TARGET_BRANCH: ${{ steps.guard.outputs.target_branch }}
        PUSH_TOKEN: ${{ inputs.push_token }}
        REPOSITORY: ${{ github.repository }}
        SERVER_URL: ${{ github.server_url }}
      run: |
        set -euo pipefail
        echo "committed=false" >> "$GITHUB_OUTPUT"
        echo "files_written=0" >> "$GITHUB_OUTPUT"
        [ -n "$PUSH_TOKEN" ] && echo "::add-mask::$PUSH_TOKEN"

        # Replace the previously committed rendered docs wholesale: stale files
        # (components that no longer exist) must be deleted, not left behind.
        shopt -s nullglob
        old_md=()
        if [ -d "$OUTPUT_DIR" ]; then
          while IFS= read -r -d '' path; do
            if git ls-files --error-unmatch "$path" >/dev/null 2>&1; then
              old_md+=("$path")
            fi
          done < <(find "$OUTPUT_DIR" -maxdepth 1 -type f -name "*${OUTPUT_FORMAT}" -print0)
          find "$OUTPUT_DIR" -maxdepth 1 -type f -name "*${OUTPUT_FORMAT}" -delete
        fi

        mkdir -p "$OUTPUT_DIR" "$OUTPUT_DIR/health"
        rendered=("$DOCS_DIR"/*"$OUTPUT_FORMAT")
        if [ "${#rendered[@]}" -eq 0 ]; then
          echo "::error::No rendered docs found in $DOCS_DIR."
          exit 1
        fi
        cp "${rendered[@]}" "$OUTPUT_DIR/"
        cp "$ANALYSIS_DIR/analysis.json" "$OUTPUT_DIR/analysis.json"
        if [ -f "$ANALYSIS_DIR/static_analysis.pkl" ] && [ -f "$ANALYSIS_DIR/static_analysis.sha" ]; then
          cp "$ANALYSIS_DIR/static_analysis.pkl" "$OUTPUT_DIR/static_analysis.pkl"
          cp "$ANALYSIS_DIR/static_analysis.sha" "$OUTPUT_DIR/static_analysis.sha"
        else
          rm -f "$OUTPUT_DIR/static_analysis.pkl" "$OUTPUT_DIR/static_analysis.sha"
        fi
        if [ -f "$ANALYSIS_DIR/codeboarding_version.json" ]; then
          cp "$ANALYSIS_DIR/codeboarding_version.json" "$OUTPUT_DIR/codeboarding_version.json"
        fi
        if [ -f "$ANALYSIS_DIR/health/health_report.json" ]; then
          cp "$ANALYSIS_DIR/health/health_report.json" "$OUTPUT_DIR/health/health_report.json"
        fi
        if [ "$WRITE_ARCHITECTURE_MD" = "true" ]; then
          mkdir -p docs/development
          cp "$ARCHITECTURE_FILE" docs/development/architecture.md
        fi

        new_md=("$OUTPUT_DIR"/*"$OUTPUT_FORMAT")
        stage_paths=("$OUTPUT_DIR/analysis.json")
        add_if_present_or_tracked() {
          if [ -e "$1" ] || git ls-files --error-unmatch "$1" >/dev/null 2>&1; then
            stage_paths+=("$1")
          fi
        }
        add_if_present_or_tracked "$OUTPUT_DIR/static_analysis.pkl"
        add_if_present_or_tracked "$OUTPUT_DIR/static_analysis.sha"
        [ -f "$OUTPUT_DIR/codeboarding_version.json" ] && stage_paths+=("$OUTPUT_DIR/codeboarding_version.json")
        [ -f "$OUTPUT_DIR/health/health_report.json" ] && stage_paths+=("$OUTPUT_DIR/health/health_report.json")
        if [ "$WRITE_ARCHITECTURE_MD" = "true" ]; then
          stage_paths+=("docs/development/architecture.md")
        fi
        stage_paths+=("${old_md[@]}" "${new_md[@]}")
        git add -f -A -- "${stage_paths[@]}"

        if git diff --cached --quiet; then
          echo "::notice::Generated architecture is unchanged; nothing to commit."
          echo "files_written=${#new_md[@]}" >> "$GITHUB_OUTPUT"
          exit 0
        fi
        if git diff --cached --quiet -I '"generated_at"' -I '"timestamp"'; then
          git reset -q
          echo "::notice::Only volatile timestamp fields changed; skipping commit."
          echo "files_written=${#new_md[@]}" >> "$GITHUB_OUTPUT"
          exit 0
        fi

        git config user.name "codeboarding[bot]"
        git config user.email "codeboarding[bot]@users.noreply.github.com"
        git commit -m "$COMMIT_MESSAGE" >/dev/null

        # Push with fetch+rebase retries: another push may land on target_branch
        # while the analysis runs. Fail-open on final rejection — the next
        # repository change regenerates.
        AUTH_URL="https://x-access-token:${PUSH_TOKEN}@${SERVER_URL#https://}/${REPOSITORY}.git"
        for attempt in 1 2 3; do
          if git push "$AUTH_URL" "HEAD:refs/heads/${TARGET_BRANCH}"; then
            NEW_SHA="$(git rev-parse HEAD)"
            echo "committed=true" >> "$GITHUB_OUTPUT"
            echo "pushed_sha=$NEW_SHA" >> "$GITHUB_OUTPUT"
            echo "files_written=${#new_md[@]}" >> "$GITHUB_OUTPUT"
            echo "Committed architecture to ${TARGET_BRANCH} as ${NEW_SHA}."
            exit 0
          fi
          if [ "$attempt" -eq 3 ]; then
            echo "::warning::Could not push architecture to ${TARGET_BRANCH}; likely missing contents: write permission or branch protection rejected the bot."
            echo "files_written=${#new_md[@]}" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          echo "::warning::Push was rejected; fetching and rebasing before retry ${attempt}."
          # The checkout is credential-free (persist-credentials: false), so the
          # fetch must authenticate through the same URL as the push; on private
          # repos a bare `git fetch origin` would 403 and hard-fail the step.
          if ! git fetch "$AUTH_URL" "$TARGET_BRANCH"; then
            echo "::warning::Could not fetch ${TARGET_BRANCH} to rebase; skipping this push. The next repository change can regenerate."
            echo "files_written=${#new_md[@]}" >> "$GITHUB_OUTPUT"
            exit 0
          fi
          if ! git rebase FETCH_HEAD; then
            git rebase --abort || true
            echo "::warning::Could not rebase generated docs onto ${TARGET_BRANCH}; skipping this push. The next repository change can regenerate."
            echo "files_written=${#new_md[@]}" >> "$GITHUB_OUTPUT"
            exit 0
          fi
        done

    - name: Write sync summary
      if: always() && steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'sync'
      shell: bash
      env:
        START_TS: ${{ steps.guard.outputs.start_ts }}
        MODE: ${{ steps.sync_analyze.outputs.analysis_mode }}
        DEPTH: ${{ steps.resolve_depth.outputs.depth }}
        FILES_WRITTEN: ${{ steps.sync_commit.outputs.files_written }}
        COMMITTED: ${{ steps.sync_commit.outputs.committed }}
        PUSHED_SHA: ${{ steps.sync_commit.outputs.pushed_sha }}
      run: |
        set -euo pipefail
        NOW="$(date +%s)"
        # start_ts is missing when the guard hard-failed on input validation.
        if [ -n "${START_TS:-}" ]; then DURATION=$((NOW - START_TS)); else DURATION=0; fi
        {
          echo "### CodeBoarding Sync"
          echo ""
          echo "- Analysis mode: ${MODE:-unknown}"
          echo "- Depth: $DEPTH"
          echo "- Rendered markdown files: ${FILES_WRITTEN:-0}"
          echo "- Commit pushed: ${COMMITTED:-false}"
          if [ -n "${PUSHED_SHA:-}" ]; then
            echo "- Pushed SHA: $PUSHED_SHA"
          fi
          echo "- Duration: ${DURATION}s"
        } >> "$GITHUB_STEP_SUMMARY"

    # If any analysis step failed, replace the sticky comment with a short failure
    # note (same header) instead of leaving the PR with nothing / a stale diagram.
    # Distinguish a free-tier quota failure (engine_adapter dropped the sentinel)
    # from a generic failure, so the comment can tell the user how to get more.
    - name: Detect quota-exhausted failure
      if: failure() && steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review'
      id: quota
      shell: bash
      run: |
        if [ -f "${RUNNER_TEMP}/cb-quota-exhausted" ]; then
          echo "exhausted=true" >> "$GITHUB_OUTPUT"
        else
          echo "exhausted=false" >> "$GITHUB_OUTPUT"
        fi

    - name: Post quota-exhausted comment
      if: failure() && steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.quota.outputs.exhausted == 'true'
      continue-on-error: true
      uses: marocchino/sticky-pull-request-comment@v2
      with:
        header: ${{ steps.guard.outputs.sticky_header }}
        number: ${{ steps.guard.outputs.pr_number }}
        message: |
          ### ${{ inputs.comment_header }} · free tier limit reached

          This repository owner's **free weekly CodeBoarding usage** is used up, so the architecture diff couldn't be generated. It resets at the start of next week.

          For more (or unmetered) usage, add one of these repository secrets and pass it to the action:
          - **`OPENROUTER_API_KEY`** — your own [OpenRouter](https://openrouter.ai) key, passed via the action's `llm_api_key` input, or
          - **`CODEBOARDING_LICENSE`** — a [CodeBoarding license](https://codeboarding.org), passed via the action's `license_key` input.

          See the [setup guide](https://github.com/CodeBoarding/CodeBoarding-action#more-usage) for the exact workflow snippet.

          <sub>codeboarding-action · run ${{ github.run_id }}</sub>
        GITHUB_TOKEN: ${{ inputs.github_token }}

    - name: Post failure comment
      if: failure() && steps.guard.outputs.skip != 'true' && steps.guard.outputs.mode == 'review' && steps.quota.outputs.exhausted != 'true'
      continue-on-error: true
      uses: marocchino/sticky-pull-request-comment@v2
      with:
        header: ${{ steps.guard.outputs.sticky_header }}
        number: ${{ steps.guard.outputs.pr_number }}
        message: |
          ### ${{ inputs.comment_header }} · failed

          The architecture diff couldn't be generated for this run. See the [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.

          <sub>codeboarding-action · run ${{ github.run_id }}</sub>
        GITHUB_TOKEN: ${{ inputs.github_token }}