code-documentation.yml

# Flamingo Code Documentation
# =============================================================================
# Installed into a target repository by the multi-platform hub ("Setup
# Workflow"). The hub dispatches it to generate this repository's
# documentation and open a pull request with the result.
#
# Jobs
#   code-graph    Deterministic code graph (no model call). Runs on pushes to
#                 the default branch, on the hub's `flamingo-code-graph`
#                 re-dispatch, and on a manual run with graph_only=true.
#   doc-pipeline  The documentation run, dispatched by the hub:
#                   Stage 0  code graph (same build as the code-graph job)
#                   Stage 1  inline docs, one hidden .md beside each source file
#                   Stage 2  reference docs: CodeWiki, or the Claude
#                            architecture analysis where CodeWiki cannot parse
#                            the primary language
#                   Stage 3  tutorials (getting started, development)
#                   Stage 4  repository docs: README, CONTRIBUTING, docs index
#
# Stages 2 (Claude), 3 and 4 follow the code reviewer's agentic pattern
# (templates/scripts/code-documentation-lib.mjs): the hub serves this
# repository's settings, the script packs the material, ONE hub call writes
# ONE document (forced `emit_document`; the hub's read tools once the
# repository's visibility is resolved), a deterministic gate checks every
# repository path it names, and the script, never the model, picks where each
# document is written.
#
# Fleet contracts (renaming any of these needs a fleet-wide re-push): the
# installed path .github/workflows/code-documentation.yml (the setup PR
# hard-deletes the old doc-orchestrator.yml), the repository_dispatch type
# `code-documentation`, the secrets below, and the script file names the hub serves.
#
# Repository secrets (Settings > Secrets and variables > Actions)
#   FLAMINGO_HUB_SECRET      Required. Authenticates every hub call.
#   ANTHROPIC_API_KEY        CodeWiki (stage 2) only; every other stage calls
#                            Claude through the hub.
#   OPENAI_API_KEY           CodeWiki (stage 2).
#   YOUTUBE_API_KEY          Optional. YouTube embeds in stages 3 and 4.

name: 🦩 Flamingo Code Documentation

on:
  # Push trigger — two things ride it. It registers the workflow with GitHub
  # Actions (required for the workflow_dispatch API), and on the repository's
  # DEFAULT branch it runs the `code-graph` job below, which re-indexes the
  # code graph the hub serves to the code reviewer and to the documentation
  # stages. The documentation pipeline itself NEVER runs on push (see its
  # `if:`). Documentation and markdown are ignored on purpose: a docs PR
  # merging must not rebuild a graph that only source files can change.
  push:
    paths-ignore:
      - 'docs/**'
      - '**.md'

  # Multi-repo change sets, LIVE: every pull request event (a `Depends-On:` line
  # added, a push, a merge) asks the hub to refresh its change sets at once, and
  # the same run builds the PR's overlay when the hub says it is a member whose
  # overlay is missing or stale. ONLY the code-graph job runs on this event (see
  # both jobs' `if:`); no path filter, because a description edit is the event.
  pull_request:
    types: [opened, reopened, edited, synchronize, ready_for_review, closed]

  repository_dispatch:
    # `code-documentation` (CODE_DOCUMENTATION_DISPATCH_EVENT_TYPE) runs the
    # documentation pipeline. `flamingo-code-graph`
    # (CODE_GRAPH_DISPATCH_EVENT_TYPE in lib/config/code-graph-workflow.ts)
    # runs ONLY the graph job; the hub's reconcile job sends it when a
    # repository's graph is missing or stale.
    types: [code-documentation, flamingo-code-graph]

  workflow_dispatch:
    # ═══════════════════════════════════════════════════════════════════════════
    # GENERATED FROM SINGLE SOURCE OF TRUTH: lib/config/code-documentation-params.ts
    # This section is auto-generated at runtime when creating workflow PRs
    # ═══════════════════════════════════════════════════════════════════════════
    inputs:
      # Individual parameters
      run_id:
        description: 'Unique execution ID'
        required: true
      repo_id:
        description: 'Repository ID from database'
        required: true
      hub_base_url:
        description: 'Hub base URL (e.g., https://product-hub.flamingo.so)'
        required: true
      stages:
        description: 'Pipeline stages to execute'
        required: true
      dependencies:
        description: 'Comma-separated dependency repos'
        required: false
        default: ''
      source_branch:
        description: 'Branch to analyze code from'
        required: true
      source_files_limit:
        description: 'Max source files to process (0 = unlimited)'
        required: true
      claude_model:
        description: 'Claude model ID for Stage 1/3/4 + Stage 2 Claude-arch fallback (SSOT from hub)'
        required: true
      codewiki_config:
        description: 'Complete CodeWiki configuration (per-phase models, engine, stages, depth)'
        required: true
      output_paths:
        description: 'Output paths configuration'
        required: true
      timeout:
        description: 'Timeout in hours'
        required: true
      youtube_config:
        description: 'YouTube integration configuration (channels only - API key in secrets)'
        required: true
      readme_config:
        description: 'README logo configuration'
        required: true
      custom_repo_instructions:
        description: 'Custom AI instructions'
        required: false
        default: ''
      external_repos:
        description: 'External repos JSON'
        required: false
        default: '[]'
      stage_count:
        description: 'Total number of pipeline stages'
        required: false
        default: '4'
      graph_only:
        description: 'true = run only the code-graph job (no documentation run)'
        required: false
        default: 'false'
    # ═══════════════════════════════════════════════════════════════════════════
    # END GENERATED SECTION
    # ═══════════════════════════════════════════════════════════════════════════

env:
  # SECURITY: Only NON-SENSITIVE variables in job-level env
  # Secrets are passed per-step to avoid exposure in job setup logs
  # Run configuration (non-sensitive)
  RUN_ID: ${{ github.event.client_payload.run_id || github.event.inputs.run_id || github.run_id }}
  REPO_ID: ${{ github.event.client_payload.repo_id || github.event.inputs.repo_id || '' }}
  # A push event carries no payload, so the graph job falls back to the org
  # Actions variable — the same fallback the code-review workflow uses.
  HUB_BASE_URL: ${{ github.event.client_payload.hub_base_url || github.event.inputs.hub_base_url || vars.FLAMINGO_HUB_BASE_URL || '' }}
  # 'true' = run only the code-graph job (a manual workflow_dispatch; the hub's
  # own documentation dispatches always send 'false').
  GRAPH_ONLY: ${{ github.event.client_payload.graph_only || github.event.inputs.graph_only || 'false' }}
  # No literal fallback: the stage list lives in CODE_DOCUMENTATION_STAGES on the
  # hub and is lifted into the payload per repo. A literal here would silently
  # restore all four stages on a payload gap, and "Remove docs this run
  # regenerates" would already have wiped the docs tree: the run would delete
  # docs and regenerate nothing.
  STAGES: ${{ github.event.client_payload.stages || github.event.inputs.stages || '' }}
  DEPENDENCIES: ${{ github.event.client_payload.dependencies || github.event.inputs.dependencies || '' }}
  STAGE_COUNT: ${{ github.event.client_payload.stage_count || github.event.inputs.stage_count || '4' }}
  # Branch to checkout for code analysis (github_branch from repo config)
  SOURCE_BRANCH: ${{ github.event.client_payload.source_branch || github.event.inputs.source_branch || 'main' }}
  # Debug/testing: limit total source files to analyze (0=unlimited)
  # Files beyond this limit are DELETED - all stages then process remaining files
  SOURCE_FILES_LIMIT: ${{ github.event.client_payload.source_files_limit || github.event.inputs.source_files_limit || '0' }}
  # Claude model SSOT: the hub's CODE_DOCUMENTATION_DEFAULT_MODEL
  # (lib/constants/ai-models.ts). The stage 1, 3 and 4 generators and the
  # stage 2 Claude analysis all read this variable; no shipped script holds a
  # literal model id, and every one throws if CLAUDE_MODEL is empty. Re-run
  # "Setup Workflow" after bumping the hub-side constant to propagate it.
  # There is deliberately NO companion request-shape variable: every stage
  # except CodeWiki calls Claude through the hub (/api/ci/claude), which
  # resolves the model's request shape itself.
  CLAUDE_MODEL: ${{ github.event.client_payload.claude_model || github.event.inputs.claude_model || '' }}
  # =============================================================================
  # JSON-grouped parameters to stay under GitHub Actions 25-parameter limit
  # These are parsed early in the workflow to extract individual values
  # =============================================================================
  # NOTE: these fall back to EMPTY, not '{}'. An empty-object default made the
  # `[ -z ... ]` presence checks below unreachable, so a missing payload silently
  # produced `null` for every jq lookup and propagated as `--cluster-model null`.
  # The hub always sends a complete, deep-merged blob (buildPayloadFromRepo).
  CODEWIKI_CONFIG_JSON: ${{ github.event.client_payload.codewiki_config || github.event.inputs.codewiki_config || '' }}
  OUTPUT_PATHS_JSON: ${{ github.event.client_payload.output_paths || github.event.inputs.output_paths || '' }}
  # Stage timeouts (in hours) — single source of truth, downstream steps reference
  # `env.STAGE_TIMEOUT_HOURS` directly. Stage 4 is the exception (1h vs 24h cap).
  STAGE_TIMEOUT_HOURS: ${{ github.event.client_payload.timeout || github.event.inputs.timeout || '24' }}
  # Aliases preserved for downstream step env: keys (they reference these names
  # by string). All resolve to the same single source.
  STAGE1_TIMEOUT_HOURS: ${{ github.event.client_payload.timeout || github.event.inputs.timeout || '24' }}
  # Stage 1 incremental push: commit + push the PR branch every N generated inline
  # docs. A 24h stage that gets cancelled used to lose ALL of its work because the
  # only commit happened after the generator returned. Bound the loss to N files.
  STAGE1_PUSH_INTERVAL: ${{ github.event.client_payload.stage1_push_interval || '100' }}
  STAGE2_TIMEOUT_HOURS: ${{ github.event.client_payload.timeout || github.event.inputs.timeout || '24' }}
  STAGE3_TIMEOUT_HOURS: ${{ github.event.client_payload.timeout || github.event.inputs.timeout || '24' }}
  # Stage 4: Repository Documentation
  TEMPLATE_REPO: ${{ github.event.client_payload.template_repo || 'flamingo-stack/openframe-oss-tenant' }}
  TEMPLATE_BRANCH: ${{ github.event.client_payload.template_branch || 'main' }}
  STAGE4_TIMEOUT_HOURS: ${{ github.event.client_payload.stage4_timeout || '1' }}
  # YouTube Integration (Stage 3 + Stage 4) - JSONB configuration (API key from secrets)
  YOUTUBE_CONFIG_JSON: ${{ github.event.client_payload.youtube_config || github.event.inputs.youtube_config || '' }}
  # README Configuration - JSONB configuration for logo branding
  README_CONFIG_JSON: ${{ github.event.client_payload.readme_config || github.event.inputs.readme_config || '' }}
  # Custom AI Instructions (All Stages) - Repository-specific instructions for AI generation
  CUSTOM_REPO_INSTRUCTIONS: ${{ github.event.client_payload.custom_repo_instructions || github.event.inputs.custom_repo_instructions || '' }}
  # External Repositories - JSON array of external repo configurations
  EXTERNAL_REPOS: ${{ github.event.client_payload.external_repos || github.event.inputs.external_repos || '[]' }}
  # ========================================================================
  # Repository Context - CRITICAL for preventing AI URL hallucinations
  # These values are passed to ALL AI prompts to ensure correct GitHub URLs
  # ========================================================================
  GITHUB_REPOSITORY: ${{ github.repository }}              # e.g., "flamingo-stack/openframe-oss-tenant"
  GITHUB_REPOSITORY_OWNER: ${{ github.repository_owner }}  # e.g., "flamingo-stack"
  GITHUB_SERVER_URL: ${{ github.server_url }}              # e.g., "https://github.com"
  # Analysis Exclusions - Complete array of glob patterns to exclude from repository analysis
  # (build artifacts, dependencies, the hub's own checkout, cloned dependency repos)
  EXCLUDED_PATHS: '**/node_modules/**,**/.git/**,**/target/**,**/dist/**,**/build/**,**/.next/**,**/out/**,**/coverage/**,**/vendor/**,**/.yalc/**,**/.turbo/**,**/.gradle/**,**/__pycache__/**,**/.terraform/**,**/.venv/**,**/venv/**,**/multi-platform-hub/**,**/deps-*/**'
  # The documentation pull request's branch prefix (CODE_DOCUMENTATION_BRANCH_PREFIX, written by npm run workflows:sync)
  DOCS_BRANCH_PREFIX: 'code-documentation/'
  README_LOGO_ALT: 'OpenFrame Logo'

jobs:
  # ===========================================================================
  # CODE GRAPH: deterministic, no model call. Tags every public symbol,
  # import and manifest of the checkout (code-graph-build.mjs) and uploads the
  # result to the hub, which promotes a default-branch snapshot to `live` and
  # serves it to the code reviewer (consumers of a symbol a PR removes) and to
  # the documentation stages (the derived ecosystem.md). Runs on every push to
  # the default branch, on the hub's `flamingo-code-graph` re-dispatch, and on
  # a manual workflow_dispatch with graph_only=true. There is no webhook
  # callback: the upload IS the report. The same build also runs as stage 0 of
  # a full documentation run (inside doc-pipeline, below).
  # ===========================================================================
  code-graph:
    runs-on: ubuntu-latest
    timeout-minutes: 20
    permissions:
      contents: read
    # THREE groups, so no two kinds of run ever cancel each other:
    #  - a `pull_request` event runs in `-pr-<n>`, and NEVER cancels a running one
    #    (`cancel-in-progress` is false for it): a newer event QUEUES behind the run
    #    in progress (GitHub keeps one pending run per group, replacing an older
    #    pending one, so the newest event still runs). Cancelling would kill an
    #    overlay build the hub already recorded as this PR's own (a description
    #    edit or the merge seconds after a push), and nothing would rebuild that
    #    head until the retry window passed;
    #  - an OVERLAY build the hub's `code-change-sets` job dispatches
    #    (overlay_pr / overlay_head_sha in the payload) runs in `-overlay-<n>`: a
    #    newer dispatch for the same PR supersedes the older one;
    #  - everything else (the default branch's rebuild) keeps the repository group.
    # A dispatched build and the PR's own run may build the same head at once;
    # that is harmless: the hub upserts an overlay on (repo, pr, head, generator).
    # A bot's own description edit (the hub writing its block) is excluded by the
    # `if:` below, but a job may join its concurrency group before that `if:` is
    # evaluated: it gets a group of its own (`-bot-<run id>`), so it can never
    # cancel the PR's run that is building the overlay the same refresh asked for.
    concurrency:
      group: flamingo-code-graph-${{ github.repository }}${{ github.event.client_payload.overlay_pr && format('-overlay-{0}', github.event.client_payload.overlay_pr) || github.event.pull_request.number && format('-pr-{0}', github.event.pull_request.number) || '' }}${{ (github.event.action == 'edited' && github.event.sender.type == 'Bot') && format('-bot-{0}', github.run_id) || '' }}
      cancel-in-progress: ${{ github.event_name != 'pull_request' }}
    if: >-
      (github.event_name == 'push' && github.ref == format('refs/heads/{0}', github.event.repository.default_branch))
      || github.event.action == 'flamingo-code-graph'
      || (github.event_name == 'workflow_dispatch' && github.event.inputs.graph_only == 'true')
      || (github.event_name == 'pull_request'
          && github.event.pull_request.head.repo.full_name == github.repository
          && !startsWith(github.event.pull_request.head.ref, 'ai-fix/')
          && !startsWith(github.event.pull_request.head.ref, 'setup/')
          && !startsWith(github.event.pull_request.head.ref, 'code-documentation/')
          && !(github.event.action == 'edited' && github.event.sender.type == 'Bot'))
    # The overlay coordinates, spelled ONCE: the hub's dispatch payload, or this PR's own event (the steps
    # below build only after the live refresh answered `build`). Both empty on a default-branch rebuild.
    env:
      OVERLAY_PR: ${{ github.event.client_payload.overlay_pr || github.event.pull_request.number || '' }}
      OVERLAY_HEAD_SHA: ${{ github.event.client_payload.overlay_head_sha || github.event.pull_request.head.sha || '' }}

    steps:
      # Fail LOUD, not silent: a push on a repo whose org never set
      # FLAMINGO_HUB_BASE_URL would otherwise curl an empty origin and die with
      # an unrelated error. Also normalizes a trailing slash ONCE.
      - name: Validate configuration
        id: config
        # A pull_request event must never turn a PR check red: the refresh is advisory
        # (the hub's webhook path and schedule are the net), so a missing hub URL or
        # secret on a PR only skips it.
        continue-on-error: ${{ github.event_name == 'pull_request' }}
        run: |
          if [ -z "$HUB_BASE_URL" ]; then
            echo "::error title=Hub URL missing::HUB_BASE_URL is empty. Set the organization Actions variable FLAMINGO_HUB_BASE_URL, or pass hub_base_url in the dispatch payload."
            exit 1
          fi
          echo "HUB_BASE_URL=${HUB_BASE_URL%/}" >> "$GITHUB_ENV"
          echo "Hub: ${HUB_BASE_URL%/}"

      # The shared script bootstrap (byte-mirrored from workflow-scripts-bootstrap.ts,
      # asserted by the build gate). BOTH graph scripts are downloaded: the builder
      # imports ./code-graph-lib.mjs from its own directory.
      - name: Download graph scripts
        id: scripts
        if: github.event_name != 'pull_request' || steps.config.outcome == 'success'
        continue-on-error: ${{ github.event_name == 'pull_request' }}
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
        run: |

          # Function to download and verify script
          SCRIPT_MANIFEST=/tmp/flamingo-script-manifest.json
          # WEBHOOK_SECRET reaches curl through a 0600 config file, never argv — see
          # curlAuthPreamble, which always traps the removal.
          CURL_CFG=$(mktemp) && chmod 600 "$CURL_CFG"
          trap 'rm -f "$CURL_CFG"' EXIT
          printf 'header = "Authorization: Bearer %s"\n' "$WEBHOOK_SECRET" > "$CURL_CFG"
          # The scripts surface. load_script_manifest pins SCRIPTS_BASE_URL to it.
          CI_SCRIPTS_URL="${HUB_BASE_URL%/}/api/ci/scripts"

          # _try_manifest <base> — 0 loaded, 1 no manifest surface there, 2 fatal.
          # The manifest is asked for ONE group: its keys are the files to download.
          _try_manifest() {
            local base="$1" code
            code=$(curl -sS -w '%{http_code}' -o "$SCRIPT_MANIFEST" \
              -K "$CURL_CFG" \
              "$base/manifest.json?group=$SCRIPT_GROUP") || code="000"

            if [ "$code" = "404" ]; then rm -f "$SCRIPT_MANIFEST"; return 1; fi
            if [ "$code" != "200" ]; then
              echo "❌ manifest request to $base failed (HTTP $code)"
              rm -f "$SCRIPT_MANIFEST"
              return 2
            fi
            # The digests are the TOP-LEVEL object. successResponse is the standard
            # emitter but it does NOT add a wrapper — it is NextResponse.json(data)
            # plus the no-store header — so there is no .data to reach through.
            # A 200 that is not a manifest is how a hub which does not serve this path
            # answers (the proxy rewrites unknown routes and returns HTML), so it
            # means "wrong surface", not "corrupt".
            if ! jq -e 'type == "object" and length > 0 and (to_entries | all(.value | type == "string"))' "$SCRIPT_MANIFEST" >/dev/null 2>&1; then
              rm -f "$SCRIPT_MANIFEST"
              return 1
            fi
            return 0
          }

          # load_script_manifest <group>
          load_script_manifest() {
            SCRIPT_GROUP="$1"
            # "cmd; rc=$?" dies under the set -euo pipefail these steps run with —
            # errexit fires before rc is read and the step ends with NO output. And
            # "if ! cmd; then rc=$?" is worse: inside the branch $? is the status of
            # the NEGATION (0), so every failure reads as success. "|| rc=$?" is the
            # one form that both suppresses errexit and preserves the real code.
            local rc=0
            _try_manifest "$CI_SCRIPTS_URL" || rc=$?
            if [ "$rc" = "0" ]; then
              SCRIPTS_BASE_URL="$CI_SCRIPTS_URL"
              echo "✅ script manifest loaded ($(jq -r 'length' "$SCRIPT_MANIFEST") scripts)"
              return 0
            fi
            if [ "$rc" = "2" ]; then exit 1; fi

            # No manifest on the scripts surface: a hub older than the manifest
            # itself. The manifest is the file list, so there is nothing to download.
            echo "❌ no script manifest on this hub ($HUB_BASE_URL): it cannot name the $SCRIPT_GROUP scripts. Redeploy the hub."
            exit 1
          }

          # download_script_group <group> — the hub names the files, this workflow
          # names only the group. Downloads every script of the group, in served order.
          download_script_group() {
            load_script_manifest "$1"
            local name
            # The loop runs in THIS shell (no pipe), so a failed download exits the step.
            while IFS= read -r name; do
              download_and_verify "$name"
            done < <(jq -r 'keys_unsorted[]' "$SCRIPT_MANIFEST")
          }

          download_and_verify() {
            local script_name="$1"
            local output_path="/tmp/$script_name"

            local expected_hash
            expected_hash=$(jq -r --arg n "$script_name" '.[$n] // empty' "$SCRIPT_MANIFEST")
            if [ -z "$expected_hash" ]; then
              echo "❌ $script_name is not in the server's script manifest!"
              echo "   The hub serves no such script, or it failed to read on the server."
              exit 1
            fi
            if ! printf '%s' "$expected_hash" | grep -Eq '^[0-9a-f]{64}$'; then
              echo "❌ the manifest entry for $script_name is not a SHA-256 digest — refusing to run it."
              exit 1
            fi

            curl -fsSL "$SCRIPTS_BASE_URL/$script_name" \
              -K "$CURL_CFG" \
              -o "$output_path"

            local actual_hash=$(shasum -a 256 "$output_path" | cut -d' ' -f1)

            if [ "$actual_hash" != "$expected_hash" ]; then
              echo "❌ HASH MISMATCH for $script_name!"
              echo "   Expected: $expected_hash"
              echo "   Actual:   $actual_hash"
              echo "   The download was corrupted in transit — both values come from the same deployment."
              exit 1
            fi

            # Make shell scripts executable
            if [[ "$script_name" == *.sh ]]; then
              chmod +x "$output_path"
            fi

            echo "✅ $script_name verified (hash: ${actual_hash:0:16}...)"
          }

          # Digests AND the file list come from the deployment serving the bytes,
          # not from this file: the step names a group (SCRIPT_GROUPS in the hub's
          # lib/config/ci-script-catalog.ts) and downloads what the hub lists for it.
          download_script_group "code-graph"

      # LIVE change sets (a `pull_request` event): ask the hub to refresh NOW and
      # whether this run builds the PR's overlay (`build`). Never fails the run.
      # A fork has no secrets and is excluded by the job's `if:`, as are the hub
      # tools' own branches (TOOL_BRANCH_PREFIXES); a bot's own description edit
      # (the hub writing its block) is excluded too, or every hub write would
      # start another run.
      - name: Refresh the change set
        id: refresh
        if: github.event_name == 'pull_request' && steps.scripts.outcome == 'success'
        # A hub that cannot answer never fails the pull request's check: the schedule links the set.
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          CODE_GRAPH_REFRESH_PR: ${{ github.event.pull_request.number }}
          # The head of THIS event: the hub answers `build` only while it is still the PR's live head.
          CODE_GRAPH_REFRESH_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
          # The event's action: the hub runs its job only for one that can change a set (CHANGE_SET_REFRESH_ACTIONS).
          CODE_GRAPH_REFRESH_ACTION: ${{ github.event.action }}
          # The event's sender type: the hub refuses a bot's own description edit too, not only this job's `if:`.
          CODE_GRAPH_REFRESH_SENDER_TYPE: ${{ github.event.sender.type }}
        run: node /tmp/code-graph-build.mjs

      # FULL history, blobless. `collectFileFacts` derives per-file ownership
      # (last commit, recent commits, commits in the window) from one
      # `git log --no-merges --no-renames` walk, which a depth-1 checkout
      # cannot answer — it would report every file as owned by one commit.
      # `filter: blob:none` keeps the clone cheap: the walk reads commit
      # metadata and name-only paths, never file contents, which is also why
      # the walk passes `--no-renames` (rename detection would fetch blobs).
      # A shallow checkout still degrades gracefully: ownership is omitted and
      # `coverage.ownership` is false rather than the job failing.
      # In overlay mode the checkout is the PR HEAD, with every blob: the
      # overlay diffs it against the live snapshot commit with rename
      # detection, which reads contents a blob:none clone cannot fetch here.
      #
      # The four build steps below share one `if:` (a PR event builds only when the refresh answered
      # `build`) and one `continue-on-error` (a pull request's check never goes red on the overlay: the
      # graph lane and the schedule rebuild it). Actions has no step group, so each step states both.
      - name: Check out repository
        if: github.event_name != 'pull_request' || steps.refresh.outputs.build == 'true'
        continue-on-error: ${{ github.event_name == 'pull_request' }}
        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          ref: ${{ env.OVERLAY_HEAD_SHA }}
          fetch-depth: 0
          # `!x && 'blob:none' || ''` — never `x && '' || …`: '' is falsy in an expression, so that form always yields blob:none.
          filter: ${{ !env.OVERLAY_PR && 'blob:none' || '' }}
          persist-credentials: false

      - name: Set up Node.js
        if: github.event_name != 'pull_request' || steps.refresh.outputs.build == 'true'
        continue-on-error: ${{ github.event_name == 'pull_request' }}
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '22'
          # v5+ caches automatically when it finds a package manager; this job never did.
          package-manager-cache: false

      # The command is CODE_GRAPH_INSTALL_COMMAND (lib/config/code-graph-workflow.ts),
      # the one spelling both workflows use: pinned wasm tree-sitter + grammars +
      # yaml into an isolated tree under RUNNER_TEMP, exported as CODE_GRAPH_DEPS_DIR.
      - name: Install graph dependencies
        if: github.event_name != 'pull_request' || steps.refresh.outputs.build == 'true'
        continue-on-error: ${{ github.event_name == 'pull_request' }}
        run: mkdir -p "$RUNNER_TEMP/code-graph-deps" && cd "$RUNNER_TEMP/code-graph-deps" && printf '%s' '{"name":"code-graph-deps","version":"1.0.0","private":true,"dependencies":{"web-tree-sitter":"0.27.0","@vscode/tree-sitter-wasm":"0.3.1","yaml":"2.9.1"}}' > package.json && printf '%s' '{"name":"code-graph-deps","version":"1.0.0","lockfileVersion":3,"requires":true,"packages":{"":{"name":"code-graph-deps","version":"1.0.0","dependencies":{"web-tree-sitter":"0.27.0","@vscode/tree-sitter-wasm":"0.3.1","yaml":"2.9.1"}},"node_modules/web-tree-sitter":{"version":"0.27.0","resolved":"https://registry.npmjs.org/web-tree-sitter/-/web-tree-sitter-0.27.0.tgz","integrity":"sha512-XK08gj6RwTMQatAG7uVRP8MunqotL/XC19vHgkSPKmELgbGPBj4ECvB8haHOUnyj6ls2B8t42UTro14zxGgAHg=="},"node_modules/@vscode/tree-sitter-wasm":{"version":"0.3.1","resolved":"https://registry.npmjs.org/@vscode/tree-sitter-wasm/-/tree-sitter-wasm-0.3.1.tgz","integrity":"sha512-RJFoomET6FajjG511fmQxeBQfU6M24a0aFZPqpid+ttIxanWf1VGytBG0UmsGjt07qmIPJS8U31D+aecuCucsQ=="},"node_modules/yaml":{"version":"2.9.1","resolved":"https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz","integrity":"sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw=="}}}' > package-lock.json && npm ci --ignore-scripts --no-audit --no-fund && echo "CODE_GRAPH_DEPS_DIR=$RUNNER_TEMP/code-graph-deps" >> "$GITHUB_ENV" || { echo "::warning::graph dependencies failed their lockfile-enforced install; continuing without them"; rm -rf "$RUNNER_TEMP/code-graph-deps"; exit 1; }

      # Overlay mode posts the PR's overlay INSTEAD of a snapshot (code-graph-build.mjs `overlayMain`).
      - name: Build and upload the code graph
        id: graph
        if: github.event_name != 'pull_request' || steps.refresh.outputs.build == 'true'
        continue-on-error: ${{ github.event_name == 'pull_request' }}
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          CODE_GRAPH_DEPS_DIR: ${{ env.CODE_GRAPH_DEPS_DIR }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          # Overlay mode: the job's overlay coordinates (empty outside it).
          CODE_GRAPH_OVERLAY_PR: ${{ env.OVERLAY_PR }}
          CODE_GRAPH_OVERLAY_HEAD_SHA: ${{ env.OVERLAY_HEAD_SHA }}
          # An overlay run names a NON-default branch, so a hub or builder that predates overlay mode lands
          # the PR head as a `branch` snapshot, never as the repository's live graph (the e2e run found an
          # older builder promoting an unmerged PR's head live). Empty outside overlay mode.
          CODE_GRAPH_BRANCH: ${{ env.OVERLAY_PR && format('overlay/pr-{0}', env.OVERLAY_PR) || '' }}
        run: node /tmp/code-graph-build.mjs

  # ===========================================================================
  # DOCUMENTATION PIPELINE: stages 0 to 4, one pull request per run. Every
  # stage commits and pushes its own output as it finishes, so a timeout or a
  # cancellation loses at most the stage in flight.
  # ===========================================================================
  doc-pipeline:
    runs-on: ubuntu-latest
    timeout-minutes: 720  # 12 hours for large repositories with many files
    # contents: push the docs branch. pull-requests: open and update the pull
    # request. issues: `gh label create` for the documentation / automated /
    # in-progress labels; without it a repository that lacks them answers 403
    # on the label and then 422 on `gh pr create --label`.
    permissions:
      contents: write
      pull-requests: write
      issues: write
    # Never on push (a push registers the workflow and runs the code-graph job
    # only), never on the graph-only re-dispatch, never on a graph-only manual
    # run. This is what lets workflow_dispatch API calls work on feature branches.
    if: github.event_name != 'push' && github.event_name != 'pull_request' && github.event.action != 'flamingo-code-graph' && github.event.inputs.graph_only != 'true'

    steps:
      # =========================================================================
      # REPORT CAPABILITY FIRST (shared failure-net standard with the code-review
      # workflow): workflow-helpers.sh — which carries send_webhook and the
      # report/stage-callback helpers — downloads in its OWN step before anything
      # else, so a failure in the main script download below can still be pinged
      # and reported home instead of leaving a phantom pending/running row.
      # =========================================================================
      - name: Download report helpers
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
        run: |

          # Function to download and verify script
          SCRIPT_MANIFEST=/tmp/flamingo-script-manifest.json
          # WEBHOOK_SECRET reaches curl through a 0600 config file, never argv — see
          # curlAuthPreamble, which always traps the removal.
          CURL_CFG=$(mktemp) && chmod 600 "$CURL_CFG"
          trap 'rm -f "$CURL_CFG"' EXIT
          printf 'header = "Authorization: Bearer %s"\n' "$WEBHOOK_SECRET" > "$CURL_CFG"
          # The scripts surface. load_script_manifest pins SCRIPTS_BASE_URL to it.
          CI_SCRIPTS_URL="${HUB_BASE_URL%/}/api/ci/scripts"

          # _try_manifest <base> — 0 loaded, 1 no manifest surface there, 2 fatal.
          # The manifest is asked for ONE group: its keys are the files to download.
          _try_manifest() {
            local base="$1" code
            code=$(curl -sS -w '%{http_code}' -o "$SCRIPT_MANIFEST" \
              -K "$CURL_CFG" \
              "$base/manifest.json?group=$SCRIPT_GROUP") || code="000"

            if [ "$code" = "404" ]; then rm -f "$SCRIPT_MANIFEST"; return 1; fi
            if [ "$code" != "200" ]; then
              echo "❌ manifest request to $base failed (HTTP $code)"
              rm -f "$SCRIPT_MANIFEST"
              return 2
            fi
            # The digests are the TOP-LEVEL object. successResponse is the standard
            # emitter but it does NOT add a wrapper — it is NextResponse.json(data)
            # plus the no-store header — so there is no .data to reach through.
            # A 200 that is not a manifest is how a hub which does not serve this path
            # answers (the proxy rewrites unknown routes and returns HTML), so it
            # means "wrong surface", not "corrupt".
            if ! jq -e 'type == "object" and length > 0 and (to_entries | all(.value | type == "string"))' "$SCRIPT_MANIFEST" >/dev/null 2>&1; then
              rm -f "$SCRIPT_MANIFEST"
              return 1
            fi
            return 0
          }

          # load_script_manifest <group>
          load_script_manifest() {
            SCRIPT_GROUP="$1"
            # "cmd; rc=$?" dies under the set -euo pipefail these steps run with —
            # errexit fires before rc is read and the step ends with NO output. And
            # "if ! cmd; then rc=$?" is worse: inside the branch $? is the status of
            # the NEGATION (0), so every failure reads as success. "|| rc=$?" is the
            # one form that both suppresses errexit and preserves the real code.
            local rc=0
            _try_manifest "$CI_SCRIPTS_URL" || rc=$?
            if [ "$rc" = "0" ]; then
              SCRIPTS_BASE_URL="$CI_SCRIPTS_URL"
              echo "✅ script manifest loaded ($(jq -r 'length' "$SCRIPT_MANIFEST") scripts)"
              return 0
            fi
            if [ "$rc" = "2" ]; then exit 1; fi

            # No manifest on the scripts surface: a hub older than the manifest
            # itself. The manifest is the file list, so there is nothing to download.
            echo "❌ no script manifest on this hub ($HUB_BASE_URL): it cannot name the $SCRIPT_GROUP scripts. Redeploy the hub."
            exit 1
          }

          # download_script_group <group> — the hub names the files, this workflow
          # names only the group. Downloads every script of the group, in served order.
          download_script_group() {
            load_script_manifest "$1"
            local name
            # The loop runs in THIS shell (no pipe), so a failed download exits the step.
            while IFS= read -r name; do
              download_and_verify "$name"
            done < <(jq -r 'keys_unsorted[]' "$SCRIPT_MANIFEST")
          }

          download_and_verify() {
            local script_name="$1"
            local output_path="/tmp/$script_name"

            local expected_hash
            expected_hash=$(jq -r --arg n "$script_name" '.[$n] // empty' "$SCRIPT_MANIFEST")
            if [ -z "$expected_hash" ]; then
              echo "❌ $script_name is not in the server's script manifest!"
              echo "   The hub serves no such script, or it failed to read on the server."
              exit 1
            fi
            if ! printf '%s' "$expected_hash" | grep -Eq '^[0-9a-f]{64}$'; then
              echo "❌ the manifest entry for $script_name is not a SHA-256 digest — refusing to run it."
              exit 1
            fi

            curl -fsSL "$SCRIPTS_BASE_URL/$script_name" \
              -K "$CURL_CFG" \
              -o "$output_path"

            local actual_hash=$(shasum -a 256 "$output_path" | cut -d' ' -f1)

            if [ "$actual_hash" != "$expected_hash" ]; then
              echo "❌ HASH MISMATCH for $script_name!"
              echo "   Expected: $expected_hash"
              echo "   Actual:   $actual_hash"
              echo "   The download was corrupted in transit — both values come from the same deployment."
              exit 1
            fi

            # Make shell scripts executable
            if [[ "$script_name" == *.sh ]]; then
              chmod +x "$output_path"
            fi

            echo "✅ $script_name verified (hash: ${actual_hash:0:16}...)"
          }

          # Digests AND the file list come from the deployment serving the bytes, not from this file.
          download_script_group "doc-helpers"

      # =========================================================================
      # REPORT RUN STARTED: the early "the workflow actually started" ping.
      # Deliberately BEFORE the main script download: it stamps workflow_run_id +
      # status 'running' on the hub's run row, which is what lets the hub's tiered
      # reaper tell "dispatch accepted but nothing ran" (never pinged, failed
      # fast) from "started and then crashed" (pinged, longer deadline).
      # =========================================================================
      - name: Report run started
        if: env.HUB_BASE_URL != ''
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
        run: |
          source /tmp/workflow-helpers.sh

          CALLBACK_URL="${HUB_BASE_URL}/api/code-documentation/webhook"
          echo "Reporting run start to $CALLBACK_URL"

          PAYLOAD="{
            \"run_id\": \"$RUN_ID\",
            \"repo_id\": \"$REPO_ID\",
            \"status\": \"running\",
            \"workflow_run_id\": ${{ github.run_id }},
            \"workflow_url\": \"${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}\",
            \"current_stage\": \"inline-docs\"
          }"

          HTTP_CODE=$(send_webhook "$CALLBACK_URL" "$WEBHOOK_SECRET" "$PAYLOAD" "/tmp/webhook_start_response.txt") || HTTP_CODE="failed"

          if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ]; then
            echo "Hub acknowledged the run start (HTTP $HTTP_CODE)"
          else
            echo "::warning title=Run start not reported::The hub answered HTTP $HTTP_CODE to the start callback. The run continues; the hub learns its status from the stage callbacks."
          fi

      # =========================================================================
      # DOWNLOAD PIPELINE SCRIPTS
      # Every script a documentation run uses, from the hub's authenticated
      # /api/ci/scripts surface (workflow-helpers.sh arrived in "Download report
      # helpers"), plus the source vocabulary and the Markdown guidelines.
      # =========================================================================
      - name: Download pipeline scripts
        id: helpers
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          # No HASH_* pins: the digests come from manifest.json on the same
          # endpoint that serves the scripts, so a hash in this file can never
          # be a different ref's than the bytes it checks.
        run: |
          echo "::group::Download the doc-pipeline script group"

          # Function to download and verify script
          SCRIPT_MANIFEST=/tmp/flamingo-script-manifest.json
          # WEBHOOK_SECRET reaches curl through a 0600 config file, never argv — see
          # curlAuthPreamble, which always traps the removal.
          CURL_CFG=$(mktemp) && chmod 600 "$CURL_CFG"
          trap 'rm -f "$CURL_CFG"' EXIT
          printf 'header = "Authorization: Bearer %s"\n' "$WEBHOOK_SECRET" > "$CURL_CFG"
          # The scripts surface. load_script_manifest pins SCRIPTS_BASE_URL to it.
          CI_SCRIPTS_URL="${HUB_BASE_URL%/}/api/ci/scripts"

          # _try_manifest <base> — 0 loaded, 1 no manifest surface there, 2 fatal.
          # The manifest is asked for ONE group: its keys are the files to download.
          _try_manifest() {
            local base="$1" code
            code=$(curl -sS -w '%{http_code}' -o "$SCRIPT_MANIFEST" \
              -K "$CURL_CFG" \
              "$base/manifest.json?group=$SCRIPT_GROUP") || code="000"

            if [ "$code" = "404" ]; then rm -f "$SCRIPT_MANIFEST"; return 1; fi
            if [ "$code" != "200" ]; then
              echo "❌ manifest request to $base failed (HTTP $code)"
              rm -f "$SCRIPT_MANIFEST"
              return 2
            fi
            # The digests are the TOP-LEVEL object. successResponse is the standard
            # emitter but it does NOT add a wrapper — it is NextResponse.json(data)
            # plus the no-store header — so there is no .data to reach through.
            # A 200 that is not a manifest is how a hub which does not serve this path
            # answers (the proxy rewrites unknown routes and returns HTML), so it
            # means "wrong surface", not "corrupt".
            if ! jq -e 'type == "object" and length > 0 and (to_entries | all(.value | type == "string"))' "$SCRIPT_MANIFEST" >/dev/null 2>&1; then
              rm -f "$SCRIPT_MANIFEST"
              return 1
            fi
            return 0
          }

          # load_script_manifest <group>
          load_script_manifest() {
            SCRIPT_GROUP="$1"
            # "cmd; rc=$?" dies under the set -euo pipefail these steps run with —
            # errexit fires before rc is read and the step ends with NO output. And
            # "if ! cmd; then rc=$?" is worse: inside the branch $? is the status of
            # the NEGATION (0), so every failure reads as success. "|| rc=$?" is the
            # one form that both suppresses errexit and preserves the real code.
            local rc=0
            _try_manifest "$CI_SCRIPTS_URL" || rc=$?
            if [ "$rc" = "0" ]; then
              SCRIPTS_BASE_URL="$CI_SCRIPTS_URL"
              echo "✅ script manifest loaded ($(jq -r 'length' "$SCRIPT_MANIFEST") scripts)"
              return 0
            fi
            if [ "$rc" = "2" ]; then exit 1; fi

            # No manifest on the scripts surface: a hub older than the manifest
            # itself. The manifest is the file list, so there is nothing to download.
            echo "❌ no script manifest on this hub ($HUB_BASE_URL): it cannot name the $SCRIPT_GROUP scripts. Redeploy the hub."
            exit 1
          }

          # download_script_group <group> — the hub names the files, this workflow
          # names only the group. Downloads every script of the group, in served order.
          download_script_group() {
            load_script_manifest "$1"
            local name
            # The loop runs in THIS shell (no pipe), so a failed download exits the step.
            while IFS= read -r name; do
              download_and_verify "$name"
            done < <(jq -r 'keys_unsorted[]' "$SCRIPT_MANIFEST")
          }

          download_and_verify() {
            local script_name="$1"
            local output_path="/tmp/$script_name"

            local expected_hash
            expected_hash=$(jq -r --arg n "$script_name" '.[$n] // empty' "$SCRIPT_MANIFEST")
            if [ -z "$expected_hash" ]; then
              echo "❌ $script_name is not in the server's script manifest!"
              echo "   The hub serves no such script, or it failed to read on the server."
              exit 1
            fi
            if ! printf '%s' "$expected_hash" | grep -Eq '^[0-9a-f]{64}$'; then
              echo "❌ the manifest entry for $script_name is not a SHA-256 digest — refusing to run it."
              exit 1
            fi

            curl -fsSL "$SCRIPTS_BASE_URL/$script_name" \
              -K "$CURL_CFG" \
              -o "$output_path"

            local actual_hash=$(shasum -a 256 "$output_path" | cut -d' ' -f1)

            if [ "$actual_hash" != "$expected_hash" ]; then
              echo "❌ HASH MISMATCH for $script_name!"
              echo "   Expected: $expected_hash"
              echo "   Actual:   $actual_hash"
              echo "   The download was corrupted in transit — both values come from the same deployment."
              exit 1
            fi

            # Make shell scripts executable
            if [[ "$script_name" == *.sh ]]; then
              chmod +x "$output_path"
            fi

            echo "✅ $script_name verified (hash: ${actual_hash:0:16}...)"
          }

          # Every script a documentation run uses, stage 0 (the code graph) included.
          # Digests AND the file list come from the deployment serving the bytes,
          # not from this file: the hub lists the group in download order (a helper
          # a generator require()s at load comes before it).
          download_script_group "doc-pipeline"
          echo "::endgroup::"

          # ONE vocabulary read for the whole run: every later step (language
          # detection, source discovery, the generators, the graph build) reads this
          # file, so none of them needs the secret for it.
          node /tmp/ci-source.mjs vocabulary /tmp/ci-vocabulary.json || { echo "::error title=Source vocabulary unavailable::Could not read the source vocabulary from the hub."; exit 1; }
          echo "CODE_GRAPH_VOCABULARY_FILE=/tmp/ci-vocabulary.json" >> $GITHUB_ENV

          echo "Pipeline scripts and source vocabulary downloaded and verified"

          # Export paths for all stages (use os.tmpdir() compatible paths)
          echo "VALIDATION_RULES_PATH=/tmp/markdown-validation-rules.md" >> $GITHUB_ENV
          echo "GUIDELINES_PATH=/tmp/flamingo-markdown-guidelines.md" >> $GITHUB_ENV
          echo "STAGE3_FILES_TRACKER=/tmp/stage3-files.txt" >> $GITHUB_ENV
          echo "STAGE3_STATS_FILE=/tmp/.doc-stage3-stats.json" >> $GITHUB_ENV
          echo "STAGE4_FILES_TRACKER=/tmp/stage4-files.txt" >> $GITHUB_ENV

          # Flamingo Markdown guidelines (their own endpoint). REQUIRED: the
          # Markdown validation and the CodeWiki prompts both read them.
          GUIDELINES_URL="${HUB_BASE_URL}/api/code-documentation/guidelines"
          # Same 0600 config file the download block above set up.
          HTTP_CODE=$(curl -fsSL -w "%{http_code}" \
            "$GUIDELINES_URL" \
            -K "$CURL_CFG" \
            -o "/tmp/flamingo-markdown-guidelines.md" 2>/dev/null) || HTTP_CODE="failed"

          if [ "$HTTP_CODE" = "200" ]; then
            GUIDELINES_SIZE=$(wc -c < /tmp/flamingo-markdown-guidelines.md | tr -d ' ')
            if [ "$GUIDELINES_SIZE" -lt 100 ]; then
              echo "::error title=Markdown guidelines invalid::The guidelines file is $GUIDELINES_SIZE bytes, which is an error response, not guidelines. Its body follows."
              cat /tmp/flamingo-markdown-guidelines.md
              exit 1
            fi
            echo "Markdown guidelines downloaded ($GUIDELINES_SIZE bytes)"
          else
            echo "::error title=Markdown guidelines unavailable::GET $GUIDELINES_URL answered HTTP $HTTP_CODE. The Markdown validation and the CodeWiki prompts require them; check that the hub serves the guidelines endpoint."
            rm -f /tmp/flamingo-markdown-guidelines.md
            exit 1
          fi

      # (The run-started report sits ABOVE the main script download; see the
      # report-capability step ordering at the top of the job.)

      - name: Check out repository
        # v5 = the Node 24 drop-in (v4 targets EOL Node 20 and warns on every run).
        uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09 # v5.1.0
        with:
          fetch-depth: 0
          token: ${{ secrets.GITHUB_TOKEN }}
          ref: ${{ env.SOURCE_BRANCH }}

      # The SOURCE head, before the PR branch and the docs-removal commit move
      # HEAD: the stage-0 graph build tags this commit (the code being
      # documented), never the docs branch it is sitting on.
      - name: Record source head
        run: echo "SOURCE_HEAD_SHA=$(git rev-parse HEAD)" >> "$GITHUB_ENV"

      # =========================================================================
      # DEPENDENCY REPOSITORIES (when configured): cloned beside the checkout as
      # context for every stage.
      # =========================================================================
      - name: Clone dependency repositories
        if: env.DEPENDENCIES != ''
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          # Authenticates the clone-token request to the hub (masked by the runner).
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
        run: |
          source /tmp/workflow-helpers.sh

          echo "Cloning dependency repositories: $DEPENDENCIES"
          ensure_directory "../deps"

          # The clone credential is minted by the hub for THIS run: read-only,
          # scoped to exactly this repository's dependencies, valid one hour.
          # A stored repository secret cannot hold it (an installation token
          # expires an hour after it is written).
          CLONE_TOKEN=""
          TOKEN_FILE=$(mktemp) && chmod 600 "$TOKEN_FILE"
          HTTP_CODE=$(node /tmp/ci-hub.mjs get "/api/ci/code-documentation/clone-token?github=${GITHUB_REPOSITORY}" "$TOKEN_FILE") || HTTP_CODE="000"
          if [ "$HTTP_CODE" = "200" ]; then
            CLONE_TOKEN=$(jq -r '.token // empty' "$TOKEN_FILE")
          fi
          rm -f "$TOKEN_FILE"
          if [ -n "$CLONE_TOKEN" ]; then
            echo "::add-mask::$CLONE_TOKEN"
            echo "Credential: a read-only token the hub minted for this run's dependencies"
          else
            echo "::warning title=No clone token::The hub did not mint a clone token (HTTP $HTTP_CODE); using GITHUB_TOKEN, which reads public repositories only."
            CLONE_TOKEN="$GH_TOKEN"
          fi

          # The credential applies to THESE clones only (`git -c`), never globally:
          # the token reads the dependencies and nothing else, so a global URL
          # rewrite would also send this job's own pushes through it.
          IFS=',' read -ra DEPS <<< "$DEPENDENCIES"
          for dep in "${DEPS[@]}"; do
            repo_name=$(basename $dep)
            echo "::group::Clone $dep into ../deps/$repo_name"
            if git -c "url.https://x-access-token:${CLONE_TOKEN}@github.com/.insteadOf=https://github.com/" \
                clone --depth 1 "https://github.com/$dep.git" "../deps/$repo_name" 2>&1; then
              git -C "../deps/$repo_name" remote set-url origin "https://github.com/$dep.git"
              file_count=$(node /tmp/ci-source.mjs count "../deps/$repo_name" 2>/dev/null || echo "?")
              echo "Cloned $dep ($file_count source files)"
            else
              echo "::warning title=Dependency not cloned::Could not clone $dep."
            fi
            echo "::endgroup::"
          done

          echo "::group::Dependency directories"
          ls -la ../deps/ 2>/dev/null || echo "No dependencies cloned"
          echo "::endgroup::"
          echo "Dependency source files available as context: $(node /tmp/ci-source.mjs count ../deps 2>/dev/null || echo '?')"

      # =========================================================================
      # PRIMARY LANGUAGE (before every stage, so all of them agree): picks the
      # stage 2 engine and filters stages 1 to 3.
      # =========================================================================
      - name: Detect primary language
        id: detect_language
        run: |
          source /tmp/workflow-helpers.sh

          # This step is the FIRST reader of CODEWIKI_CONFIG_JSON — it runs before
          # "Validate and parse run configuration", so the emptiness guard lives here,
          # ahead of the first jq, rather than in the later validation step.
          if [ -z "$CODEWIKI_CONFIG_JSON" ]; then
            echo "::error title=Missing configuration::CODEWIKI_CONFIG_JSON is empty; language detection needs it."
            exit 1
          fi

          echo "Detecting the primary language across the repository (.) and its dependencies (../deps/)"

          # ONE detection, from the vocabulary the hub serves (ci-source.mjs): which
          # languages are source, their extensions, and which of them CodeWiki can
          # parse are rows in the hub's language table. This step used to carry nine
          # hand-typed `find` counts, a positional helper and a six-way threshold
          # test, each with its own idea of the extensions and the exclusions.
          DETECTION=$(node /tmp/ci-source.mjs detect) || { echo "::error title=Language detection failed::ci-source.mjs detect exited non-zero."; exit 1; }
          PRIMARY_LANG=$(echo "$DETECTION" | jq -r '.primary')
          MAX_COUNT=$(echo "$DETECTION" | jq -r '.max')
          CODEWIKI_SUPPORTED=$(echo "$DETECTION" | jq -r '.codewiki_supported')

          echo "::group::Source files by language (tests and never-source directories excluded)"
          echo "$DETECTION" | jq -r '.counts | to_entries[] | select(.value > 0) | "  \(.key): \(.value)"'
          echo "::endgroup::"
          echo "Primary language: $PRIMARY_LANG ($MAX_COUNT files)"
          if [ "$CODEWIKI_SUPPORTED" = "true" ]; then
            echo "CodeWiki can parse it: yes"
          else
            echo "CodeWiki can parse it: no (stage 2 uses the Claude architecture analysis)"
          fi

          # Per-repo engine override.
          #
          # The detection above cannot see mixed repos: it counts `.` AND `../deps`, so
          # a Rust or Go product with a TypeScript dependency clones its way past the
          # >=10 threshold and runs CodeWiki over a codebase whose analyzers do not
          # exist — which yields synthetic module_1/module_2/... docs that look like a
          # successful run. `engine` pins the choice.
          #
          # Applied here, before set_output, so all five downstream gates keep reading
          # one value and need no change. It cannot live in the `if:` conditions:
          # GitHub Actions expressions have no ternary.
          CODEWIKI_ENGINE=$(require_json_key "$CODEWIKI_CONFIG_JSON" '.engine' 'codewiki engine') || exit 1
          case "$CODEWIKI_ENGINE" in
            claude)
              CODEWIKI_SUPPORTED="false"
              echo "Stage 2 engine: claude (pinned by the repository configuration)"
              ;;
            codewiki)
              CODEWIKI_SUPPORTED="true"
              echo "Stage 2 engine: codewiki (pinned by the repository configuration)"
              ;;
            auto)
              echo "Stage 2 engine: auto (CodeWiki supported: $CODEWIKI_SUPPORTED)"
              ;;
            *)
              echo "::error title=Invalid stage 2 engine::engine is '$CODEWIKI_ENGINE'; expected auto, codewiki or claude."
              exit 1
              ;;
          esac

          # Output for use by subsequent steps
          set_output "primary_language" "$PRIMARY_LANG"
          set_output "codewiki_supported" "$CODEWIKI_SUPPORTED"
          set_output "file_count" "$MAX_COUNT"

      # =========================================================================
      # VALIDATE AND PARSE THE RUN CONFIGURATION
      # 1. Every required parameter is present
      # 2. Each JSON configuration is parsed into individual variables (the JSON
      #    grouping keeps the dispatch under GitHub's 25-input limit)
      # 3. The parsed values are valid, then exported to GITHUB_ENV
      # =========================================================================
      - name: Validate and parse run configuration
        run: |
          # 1. Required parameters -------------------------------------------
          VALIDATION_FAILED=0

          # Core parameters
          [ -z "$RUN_ID" ] && echo "::error title=Missing parameter::RUN_ID" && VALIDATION_FAILED=1
          [ -z "$REPO_ID" ] && echo "::error title=Missing parameter::REPO_ID" && VALIDATION_FAILED=1
          [ -z "$HUB_BASE_URL" ] && echo "::error title=Missing parameter::HUB_BASE_URL" && VALIDATION_FAILED=1

          [ -z "$STAGES" ] && echo "::error title=Missing parameter::STAGES" && VALIDATION_FAILED=1
          [ -z "$CLAUDE_MODEL" ] && echo "::error title=Missing parameter::CLAUDE_MODEL" && VALIDATION_FAILED=1

          # JSON parameters
          [ -z "$CODEWIKI_CONFIG_JSON" ] && echo "::error title=Missing parameter::CODEWIKI_CONFIG_JSON" && VALIDATION_FAILED=1
          [ -z "$OUTPUT_PATHS_JSON" ] && echo "::error title=Missing parameter::OUTPUT_PATHS_JSON" && VALIDATION_FAILED=1
          [ -z "$README_CONFIG_JSON" ] && echo "::error title=Missing parameter::README_CONFIG_JSON" && VALIDATION_FAILED=1
          [ -z "$YOUTUBE_CONFIG_JSON" ] && echo "::error title=Missing parameter::YOUTUBE_CONFIG_JSON" && VALIDATION_FAILED=1

          if [ $VALIDATION_FAILED -eq 1 ]; then
            echo "::error title=Invalid run configuration::Required parameters are missing (annotated above). The hub sends every one of them; re-run \"Setup Workflow\" if this repository's workflow is out of date."
            exit 1
          fi

          echo "Required parameters: present"

          # 2a. CodeWiki configuration (nested JSON) ---------------------------
          echo "::group::CodeWiki configuration"

          # Only the keys with a real consumer are extracted here — the per-phase
          # base_url / api_version / temperature / temperature_supported are read
          # directly from CODEWIKI_CONFIG_JSON by configure_codewiki_from_json, which
          # is the single place that builds the `codewiki config set` command. They
          # used to be parsed here as well and exported to $GITHUB_ENV, where nothing
          # read them.
          #
          # No `// default` fallbacks anywhere below. The hub deep-merges every JSON
          # param against the params SSOT before dispatch, so an absent key is a real
          # bug — and a fallback here would silently win over the SSOT, which is how
          # docs/architecture and docs/reference/architecture drifted apart.
          # `require_json_key` / `optional_json_key` come from workflow-helpers.sh.
          source /tmp/workflow-helpers.sh
          CW_JSON="$CODEWIKI_CONFIG_JSON"

          # Parse nested cluster config
          CODEWIKI_CLUSTER_PROVIDER=$(require_json_key "$CW_JSON" '.cluster.provider' 'cluster provider') || exit 1
          CODEWIKI_CLUSTER_MODEL=$(require_json_key "$CW_JSON" '.cluster.model' 'cluster model') || exit 1
          CODEWIKI_CLUSTER_MAX_TOKENS=$(require_json_key "$CW_JSON" '.cluster.max_tokens' 'cluster max_tokens') || exit 1
          CODEWIKI_CLUSTER_MAX_TOKEN_FIELD=$(require_json_key "$CW_JSON" '.cluster.max_token_field' 'cluster max_token_field') || exit 1
          # Nullable by design: api_version is null for every OpenAI model.

          # Parse nested generation config
          CODEWIKI_GENERATION_PROVIDER=$(require_json_key "$CW_JSON" '.generation.provider' 'generation provider') || exit 1
          CODEWIKI_GENERATION_MODEL=$(require_json_key "$CW_JSON" '.generation.model' 'generation model') || exit 1
          CODEWIKI_GENERATION_MAX_TOKENS=$(require_json_key "$CW_JSON" '.generation.max_tokens' 'generation max_tokens') || exit 1
          CODEWIKI_GENERATION_MAX_TOKEN_FIELD=$(require_json_key "$CW_JSON" '.generation.max_token_field' 'generation max_token_field') || exit 1

          # Parse nested fallback config
          CODEWIKI_FALLBACK_PROVIDER=$(require_json_key "$CW_JSON" '.fallback.provider' 'fallback provider') || exit 1
          CODEWIKI_FALLBACK_MODEL=$(require_json_key "$CW_JSON" '.fallback.model' 'fallback model') || exit 1
          CODEWIKI_FALLBACK_MAX_TOKENS=$(require_json_key "$CW_JSON" '.fallback.max_tokens' 'fallback max_tokens') || exit 1
          CODEWIKI_FALLBACK_MAX_TOKEN_FIELD=$(require_json_key "$CW_JSON" '.fallback.max_token_field' 'fallback max_token_field') || exit 1

          # Parse top-level config.
          # max_files_per_module is LIVE: this value reaches CodeWiki through the
          # job-scoped $GITHUB_ENV write below, and upstream reads it in its
          # empty-module-tree branch — the branch Go/Rust/HCL repos land in.
          CODEWIKI_MAX_FILES_PER_MODULE=$(require_json_key "$CW_JSON" '.max_files_per_module' 'max_files_per_module') || exit 1
          CODEWIKI_MAX_DEPTH=$(require_json_key "$CW_JSON" '.max_depth' 'max_depth') || exit 1
          CODEWIKI_REPO=$(require_json_key "$CW_JSON" '.repo' 'codewiki repo url') || exit 1

          echo "Cluster (phase 2):     $CODEWIKI_CLUSTER_PROVIDER / $CODEWIKI_CLUSTER_MODEL (${CODEWIKI_CLUSTER_MAX_TOKEN_FIELD}, ${CODEWIKI_CLUSTER_MAX_TOKENS} tokens)"
          echo "Generation (phase 3+): $CODEWIKI_GENERATION_PROVIDER / $CODEWIKI_GENERATION_MODEL (${CODEWIKI_GENERATION_MAX_TOKEN_FIELD}, ${CODEWIKI_GENERATION_MAX_TOKENS} tokens)"
          echo "Fallback:              $CODEWIKI_FALLBACK_PROVIDER / $CODEWIKI_FALLBACK_MODEL (${CODEWIKI_FALLBACK_MAX_TOKEN_FIELD}, ${CODEWIKI_FALLBACK_MAX_TOKENS} tokens)"
          echo "Max depth:             $CODEWIKI_MAX_DEPTH"
          echo "Max files per module:  $CODEWIKI_MAX_FILES_PER_MODULE"
          echo "::endgroup::"

          # 2b. YouTube configuration ------------------------------------------
          echo "::group::YouTube configuration"

          # Parse YouTube config from JSONB (channels only - API key from secrets)
          # channels is legitimately optional: no channels == feature off
          YOUTUBE_CHANNELS=$(echo "$YOUTUBE_CONFIG_JSON" | jq -c '.channels // []')

          # YouTube is enabled if channels array has items
          YOUTUBE_ENABLED=$(echo "$YOUTUBE_CHANNELS" | jq -r 'if length > 0 then "true" else "false" end')

          echo "Enabled:  $YOUTUBE_ENABLED (from the channel count)"
          echo "Channels: $YOUTUBE_CHANNELS"
          echo "API key:  secrets.YOUTUBE_API_KEY (never stored on the hub)"
          echo "::endgroup::"

          # 2c. README logo configuration --------------------------------------
          echo "::group::README logo configuration"

          # Parse README config from JSONB
          README_LOGO_DARK=$(optional_json_key "$README_CONFIG_JSON" '.logo_dark')
          README_LOGO_LIGHT=$(optional_json_key "$README_CONFIG_JSON" '.logo_light')
          README_LOGO_ALT=$(require_json_key "$README_CONFIG_JSON" '.logo_alt' 'readme logo alt') || exit 1

          echo "Dark logo:  ${README_LOGO_DARK:-'(not set)'}"
          echo "Light logo: ${README_LOGO_LIGHT:-'(not set)'}"
          echo "Alt text:   $README_LOGO_ALT"
          echo "::endgroup::"

          # 2d. Output paths ---------------------------------------------------
          echo "::group::Output paths"

          # Same fail-loud contract as the codewiki block. These fallbacks were the
          # last surviving copy of the five paths, and `.reference` still said
          # docs/architecture while the SSOT said docs/reference/architecture — the
          # very drift the SSOT was created to end.
          OP_JSON="$OUTPUT_PATHS_JSON"
          DOCS_OUTPUT_PATH=$(require_json_key "$OP_JSON" '.docs' 'docs output path') || exit 1
          REFERENCE_OUTPUT_PATH=$(require_json_key "$OP_JSON" '.reference' 'reference output path') || exit 1
          DIAGRAMS_OUTPUT_PATH=$(require_json_key "$OP_JSON" '.diagrams' 'diagrams output path') || exit 1
          GETTING_STARTED_OUTPUT_PATH=$(require_json_key "$OP_JSON" '.getting_started' 'getting-started output path') || exit 1
          DEVELOPMENT_OUTPUT_PATH=$(require_json_key "$OP_JSON" '.development' 'development output path') || exit 1

          echo "Docs root:       $DOCS_OUTPUT_PATH"
          echo "Reference:       $REFERENCE_OUTPUT_PATH"
          echo "Diagrams:        $DIAGRAMS_OUTPUT_PATH"
          echo "Getting started: $GETTING_STARTED_OUTPUT_PATH"
          echo "Development:     $DEVELOPMENT_OUTPUT_PATH"
          echo "::endgroup::"

          # 2e. Custom instructions and external repositories ------------------
          echo "::group::Custom instructions and external repositories"

          # Repository context (prevents invented GitHub URLs in every prompt)
          # Extract repository information from GitHub context
          GITHUB_REPO="${{ github.repository }}"
          GITHUB_OWNER="${{ github.repository_owner }}"
          GITHUB_SERVER="${{ github.server_url }}"
          GITHUB_REPO_NAME=$(echo "$GITHUB_REPO" | cut -d'/' -f2)
          GITHUB_REPO_URL="${GITHUB_SERVER}/${GITHUB_REPO}"

          # Build repository context section (injected into ALL AI prompts)
          # Use printf for multi-line string (avoids YAML parsing issues with heredoc)
          printf -v REPOSITORY_CONTEXT '%s\n' \
            '## REPOSITORY CONTEXT - GROUND TRUTH' \
            '' \
            '**CRITICAL:** This section provides the ACTUAL repository information. You MUST use these exact values when constructing GitHub URLs.' \
            '' \
            "- **Repository:** ${GITHUB_REPO}" \
            "- **Owner:** ${GITHUB_OWNER}" \
            "- **Repository Name:** ${GITHUB_REPO_NAME}" \
            "- **Repository URL:** ${GITHUB_REPO_URL}" \
            "- **Server:** ${GITHUB_SERVER}" \
            '' \
            '**MANDATORY RULES FOR GITHUB URLS:**' \
            "1. ALWAYS use the exact repository path: \`${GITHUB_REPO}\`" \
            '2. NEVER use placeholder URLs like "your-org", "example-org", or "mycompany"' \
            '3. NEVER infer repository owner from file contents or dependencies' \
            '4. NEVER use upstream/parent repository URLs (if this is a fork, use the fork URL)' \
            "5. When linking to code: \`${GITHUB_REPO_URL}/blob/main/path/to/file\`" \
            "6. When linking to clone: \`git clone ${GITHUB_REPO_URL}.git\`" \
            "7. When linking to issues/PRs: \`${GITHUB_REPO_URL}/issues\` or \`${GITHUB_REPO_URL}/pulls\`" \
            "8. When linking to releases: \`${GITHUB_REPO_URL}/releases\`" \
            '' \
            '**If you find yourself writing a GitHub URL, verify it matches the Repository URL above.**' \
            "**ESPECIALLY IN README.md and tutorials - All GitHub URLs MUST use ${GITHUB_REPO}**" \
            '' \
            '---'

          echo "Repository:     $GITHUB_REPO"
          echo "Repository URL: $GITHUB_REPO_URL"

          # Repository context goes in front of the custom instructions
          # Custom instructions come as plain text from user
          # Read from the environment rather than interpolating into single quotes.
          # GitHub Actions expression substitution runs BEFORE bash parses the line, so a
          # single apostrophe anywhere in an admin's instructions used to terminate the
          # string and kill the step with a syntax error. NOTE: never write a literal
          # empty GitHub expression in this run block, even inside a comment — Actions
          # evaluates it pre-bash and the whole workflow fails to parse.
          USER_CUSTOM_INSTRUCTIONS="$CUSTOM_REPO_INSTRUCTIONS"

          # Combine repository context + user custom instructions
          # Repository context goes FIRST (highest priority in prompts)
          if [ -n "$USER_CUSTOM_INSTRUCTIONS" ]; then
            CUSTOM_INSTRUCTIONS="${REPOSITORY_CONTEXT}"$'\n\n'"${USER_CUSTOM_INSTRUCTIONS}"
          else
            CUSTOM_INSTRUCTIONS="$REPOSITORY_CONTEXT"
          fi

          # External repos come as separate JSON array parameter

          EXTERNAL_REPOS_COUNT=$(echo "$EXTERNAL_REPOS" | jq '. | length' 2>/dev/null || echo "0")
          echo "Repository context:  ${#REPOSITORY_CONTEXT} chars"
          echo "Custom instructions: ${#USER_CUSTOM_INSTRUCTIONS} chars"
          echo "Combined prompt block: ${#CUSTOM_INSTRUCTIONS} chars"
          echo "External repositories: $EXTERNAL_REPOS_COUNT"
          echo "Combined prompt block, first 300 chars:"
          echo "${CUSTOM_INSTRUCTIONS:0:300}..."
          echo "::endgroup::"

          # 3. Parsed values ---------------------------------------------------

          # Validate providers
          if [[ ! "$CODEWIKI_CLUSTER_PROVIDER" =~ ^(anthropic|openai)$ ]]; then
            echo "::error title=Invalid CodeWiki configuration::cluster provider is '$CODEWIKI_CLUSTER_PROVIDER'; expected anthropic or openai."
            exit 1
          fi

          if [[ ! "$CODEWIKI_GENERATION_PROVIDER" =~ ^(anthropic|openai)$ ]]; then
            echo "::error title=Invalid CodeWiki configuration::generation provider is '$CODEWIKI_GENERATION_PROVIDER'; expected anthropic or openai."
            exit 1
          fi

          if [[ ! "$CODEWIKI_FALLBACK_PROVIDER" =~ ^(anthropic|openai)$ ]]; then
            echo "::error title=Invalid CodeWiki configuration::fallback provider is '$CODEWIKI_FALLBACK_PROVIDER'; expected anthropic or openai."
            exit 1
          fi

          # Model names are not empty
          [ -z "$CODEWIKI_CLUSTER_MODEL" ] && echo "::error title=Invalid CodeWiki configuration::cluster model is empty." && exit 1
          [ -z "$CODEWIKI_GENERATION_MODEL" ] && echo "::error title=Invalid CodeWiki configuration::generation model is empty." && exit 1
          [ -z "$CODEWIKI_FALLBACK_MODEL" ] && echo "::error title=Invalid CodeWiki configuration::fallback model is empty." && exit 1

          # Numeric values
          [[ ! "$CODEWIKI_CLUSTER_MAX_TOKENS" =~ ^[0-9]+$ ]] && echo "::error title=Invalid CodeWiki configuration::cluster max_tokens is '$CODEWIKI_CLUSTER_MAX_TOKENS', not a number." && exit 1
          [[ ! "$CODEWIKI_GENERATION_MAX_TOKENS" =~ ^[0-9]+$ ]] && echo "::error title=Invalid CodeWiki configuration::generation max_tokens is '$CODEWIKI_GENERATION_MAX_TOKENS', not a number." && exit 1
          [[ ! "$CODEWIKI_FALLBACK_MAX_TOKENS" =~ ^[0-9]+$ ]] && echo "::error title=Invalid CodeWiki configuration::fallback max_tokens is '$CODEWIKI_FALLBACK_MAX_TOKENS', not a number." && exit 1
          [[ ! "$CODEWIKI_MAX_DEPTH" =~ ^[0-9]+$ ]] && echo "::error title=Invalid CodeWiki configuration::max_depth is '$CODEWIKI_MAX_DEPTH', not a number." && exit 1
          [[ ! "$CODEWIKI_MAX_FILES_PER_MODULE" =~ ^[0-9]+$ ]] && echo "::error title=Invalid CodeWiki configuration::max_files_per_module is '$CODEWIKI_MAX_FILES_PER_MODULE', not a number." && exit 1

          echo "Parsed values: valid"

          # 4. Export to GITHUB_ENV (every later step reads these) -------------

          # CodeWiki config (31 vars: cluster=9, generation=10, fallback=9, shared=3)
          echo "CODEWIKI_CLUSTER_PROVIDER=$CODEWIKI_CLUSTER_PROVIDER" >> $GITHUB_ENV
          echo "CODEWIKI_CLUSTER_MODEL=$CODEWIKI_CLUSTER_MODEL" >> $GITHUB_ENV
          echo "CODEWIKI_CLUSTER_MAX_TOKENS=$CODEWIKI_CLUSTER_MAX_TOKENS" >> $GITHUB_ENV
          echo "CODEWIKI_CLUSTER_MAX_TOKEN_FIELD=$CODEWIKI_CLUSTER_MAX_TOKEN_FIELD" >> $GITHUB_ENV
          echo "CODEWIKI_GENERATION_PROVIDER=$CODEWIKI_GENERATION_PROVIDER" >> $GITHUB_ENV
          echo "CODEWIKI_GENERATION_MODEL=$CODEWIKI_GENERATION_MODEL" >> $GITHUB_ENV
          echo "CODEWIKI_GENERATION_MAX_TOKENS=$CODEWIKI_GENERATION_MAX_TOKENS" >> $GITHUB_ENV
          echo "CODEWIKI_GENERATION_MAX_TOKEN_FIELD=$CODEWIKI_GENERATION_MAX_TOKEN_FIELD" >> $GITHUB_ENV
          echo "CODEWIKI_FALLBACK_PROVIDER=$CODEWIKI_FALLBACK_PROVIDER" >> $GITHUB_ENV
          echo "CODEWIKI_FALLBACK_MODEL=$CODEWIKI_FALLBACK_MODEL" >> $GITHUB_ENV
          echo "CODEWIKI_FALLBACK_MAX_TOKENS=$CODEWIKI_FALLBACK_MAX_TOKENS" >> $GITHUB_ENV
          echo "CODEWIKI_FALLBACK_MAX_TOKEN_FIELD=$CODEWIKI_FALLBACK_MAX_TOKEN_FIELD" >> $GITHUB_ENV
          echo "CODEWIKI_MAX_FILES_PER_MODULE=$CODEWIKI_MAX_FILES_PER_MODULE" >> $GITHUB_ENV
          echo "CODEWIKI_MAX_DEPTH=$CODEWIKI_MAX_DEPTH" >> $GITHUB_ENV
          echo "CODEWIKI_REPO=$CODEWIKI_REPO" >> $GITHUB_ENV

          # YouTube config (2 vars - API key from secrets, not exported here)
          echo "YOUTUBE_ENABLED=$YOUTUBE_ENABLED" >> $GITHUB_ENV
          echo "YOUTUBE_CHANNELS=$YOUTUBE_CHANNELS" >> $GITHUB_ENV

          # README config (3 vars)
          echo "README_LOGO_DARK=$README_LOGO_DARK" >> $GITHUB_ENV
          echo "README_LOGO_LIGHT=$README_LOGO_LIGHT" >> $GITHUB_ENV
          echo "README_LOGO_ALT=$README_LOGO_ALT" >> $GITHUB_ENV

          # Output paths (5 vars)
          echo "DOCS_OUTPUT_PATH=$DOCS_OUTPUT_PATH" >> $GITHUB_ENV
          echo "REFERENCE_OUTPUT_PATH=$REFERENCE_OUTPUT_PATH" >> $GITHUB_ENV
          echo "DIAGRAMS_OUTPUT_PATH=$DIAGRAMS_OUTPUT_PATH" >> $GITHUB_ENV
          echo "GETTING_STARTED_OUTPUT_PATH=$GETTING_STARTED_OUTPUT_PATH" >> $GITHUB_ENV
          echo "DEVELOPMENT_OUTPUT_PATH=$DEVELOPMENT_OUTPUT_PATH" >> $GITHUB_ENV

          # Custom instructions (2 vars)
          echo "CUSTOM_INSTRUCTIONS<<EOF" >> $GITHUB_ENV
          echo "$CUSTOM_INSTRUCTIONS" >> $GITHUB_ENV
          echo "EOF" >> $GITHUB_ENV
          echo "EXTERNAL_REPOS=$EXTERNAL_REPOS" >> $GITHUB_ENV

          echo "Run configuration validated and exported: 15 CodeWiki, 2 YouTube, 3 README, 5 output paths, 2 instruction values"

      # =========================================================================
      # SOURCE FILE DISCOVERY (the one list every stage reads)
      # Discovers SOURCE CODE files and optionally DELETES everything else.
      # When SOURCE_FILES_LIMIT > 0:
      #   1. Keeps only N source files (.ts, .java, .py, etc.)
      #   2. DELETES ALL other files in the repo (aggressive cleanup)
      # Generated docs (inline .md) are created AFTER this step, so not affected.
      # =========================================================================
      - name: Discover source files
        id: discover_files
        env:
          SOURCE_FILES_LIMIT: ${{ env.SOURCE_FILES_LIMIT }}
          # DOCS_OUTPUT_PATH is needed below so the find can exclude the
          # generated docs tree (deleted by the docs-removal step that runs
          # AFTER discovery but BEFORE Stage 1 — source-extension files
          # under docs/ would otherwise be enumerated, then deleted, then
          # cause ENOENT in Stage 1).
          DOCS_OUTPUT_PATH: ${{ env.DOCS_OUTPUT_PATH }}
        run: |
          source /tmp/workflow-helpers.sh

          echo "Discovering source files in the repository (.) and its dependencies (../deps/)"

          # File paths (all in /tmp to avoid accidental commits)
          SOURCE_FILES_LIST="/tmp/.code-documentation-source-files.txt"
          ALL_SOURCE_TEMP="/tmp/all_source_files_discovered.txt"
          ALL_FILES_TEMP="/tmp/all_files_in_repo.txt"
          FILES_TO_DELETE="/tmp/files_to_delete.txt"

          # 1. Find SOURCE CODE files only (with standard exclusions)
          # IMPORTANT: exclude $DOCS_OUTPUT_PATH/* — the docs-removal step below
          # does `rm -rf $DOCS_OUTPUT_PATH` BEFORE Stage 1 reads this list. If
          # any source-extension file lives under the docs tree (Doxygen's
          # `docs/doxygen/documentation.h`, Sphinx `_extensions/*.py`, etc.),
          # it would be enumerated here, then deleted, then Stage 1 hits
          # ENOENT trying to read it. This is the source-discovery /
          # docs-removal / Stage-1 ordering bug — exclusion is the targeted fix.
          # The list comes from ci-source.mjs: the served source extensions, the
          # served never-source directories, tests skipped by name — the same rule
          # the language detection above counted with.
          node /tmp/ci-source.mjs list "$ALL_SOURCE_TEMP" --exclude "./$DOCS_OUTPUT_PATH" > /dev/null || { echo "::error title=Source discovery failed::ci-source.mjs list exited non-zero."; exit 1; }

          TOTAL_SOURCE=$(wc -l < "$ALL_SOURCE_TEMP" | tr -d ' ')
          FILE_LIMIT="${SOURCE_FILES_LIMIT:-0}"

          echo "Source files found: $TOTAL_SOURCE"

          # Apply limit: keep N source files, DELETE EVERYTHING ELSE
          if [ "$FILE_LIMIT" -gt 0 ]; then
            echo "::warning title=Source file limit active::SOURCE_FILES_LIMIT=$FILE_LIMIT. Keeping $FILE_LIMIT source files and deleting every other file in the checkout (a debugging setting)."
            echo "::group::Apply the source file limit"

            # Keep first N source files
            head -n "$FILE_LIMIT" "$ALL_SOURCE_TEMP" > "$SOURCE_FILES_LIST"
            KEEPING=$(wc -l < "$SOURCE_FILES_LIST" | tr -d ' ')

            # 2. Find ALL files in the repo (except .git and workflow temp files)
            find . ../deps 2>/dev/null -type f \
              -not -path "*/.git/*" \
              -not -path "*/.git" \
              -not -name ".code-documentation-*" \
              -not -name ".doc-stage*" \
            | sort > "$ALL_FILES_TEMP"

            TOTAL_FILES=$(wc -l < "$ALL_FILES_TEMP" | tr -d ' ')
            echo "Files in the checkout: $TOTAL_FILES"

            # Build delete list: ALL files EXCEPT the ones we're keeping
            # Also preserve workflow temp files (.code-documentation-*, .doc-stage*)
            > "$FILES_TO_DELETE"
            while IFS= read -r file; do
              # Skip workflow temp files we need to preserve
              case "$file" in
                ./.code-documentation-*|./.doc-stage*) continue ;;
              esac
              # Check if this file is in our keep list
              if ! grep -qxF "$file" "$SOURCE_FILES_LIST" 2>/dev/null; then
                echo "$file" >> "$FILES_TO_DELETE"
              fi
            done < "$ALL_FILES_TEMP"

            DELETE_COUNT=$(wc -l < "$FILES_TO_DELETE" | tr -d ' ')
            echo "Files to delete: $DELETE_COUNT"

            # Delete all files NOT in the keep list
            DELETED_COUNT=0
            while IFS= read -r file_to_delete; do
              if [ -f "$file_to_delete" ]; then
                rm -f "$file_to_delete"
                DELETED_COUNT=$((DELETED_COUNT + 1))
              fi
            done < "$FILES_TO_DELETE"

            echo "Kept $KEEPING source files, deleted $DELETED_COUNT files"

            rm -f "$FILES_TO_DELETE" "$ALL_FILES_TEMP"

            # Aggressively prune directories (including those with only dotfiles)
            PRUNED_COUNT=0

            # First, delete all dotfiles except in .git and workflow temp files (they prevent dir deletion)
            find . -type f -name ".*" \
              -not -path "*/.git/*" \
              -not -name ".code-documentation-*" \
              -not -name ".doc-stage*" \
              -delete 2>/dev/null || true

            # Multiple passes to handle nested empty directories
            for i in 1 2 3 4 5 6 7 8 9 10; do
              PASS_COUNT=0
              while IFS= read -r empty_dir; do
                if [ -d "$empty_dir" ] && [ -z "$(ls -A "$empty_dir" 2>/dev/null)" ]; then
                  rmdir "$empty_dir" 2>/dev/null && PASS_COUNT=$((PASS_COUNT + 1))
                fi
              done < <(find . -type d -empty 2>/dev/null | grep -v "^.$" | grep -v ".git")
              PRUNED_COUNT=$((PRUNED_COUNT + PASS_COUNT))
              [ "$PASS_COUNT" -eq 0 ] && break
            done

            if [ "$PRUNED_COUNT" -gt 0 ]; then
              echo "Pruned $PRUNED_COUNT empty directories"
            fi

            # Show what's left
            echo "Remaining directories (first 20):"
            find . -type d -not -path "*/.git/*" -not -path "*/.git" | head -20
            echo "::endgroup::"
          else
            # No limit - keep all source files
            cp "$ALL_SOURCE_TEMP" "$SOURCE_FILES_LIST"
          fi

          # Cleanup temp file
          rm -f "$ALL_SOURCE_TEMP"

          # Count remaining files
          FILE_COUNT=$(count_source_files "$SOURCE_FILES_LIST")
          MAIN_COUNT=$(count_main_repo_files "$SOURCE_FILES_LIST")
          DEPS_COUNT=$(count_dependency_files "$SOURCE_FILES_LIST")

          echo "Source files to document: $FILE_COUNT ($MAIN_COUNT in this repository, $DEPS_COUNT in dependencies)"

          echo "::group::Source files by language"
          node /tmp/ci-source.mjs breakdown "$SOURCE_FILES_LIST" | sed 's/^/  /'
          echo "::endgroup::"

          echo "::group::Sample source files (first 20)"
          head -20 "$SOURCE_FILES_LIST" | sed 's/^/  /'
          echo "::endgroup::"

          # Output for use by subsequent steps
          set_output "source_file_count" "$FILE_COUNT"
          set_output "source_files_list" "$SOURCE_FILES_LIST"

      # =========================================================================
      # PULL REQUEST FIRST (progressive pull request)
      # The branch and the pull request exist before any stage runs, so each
      # stage commits its results the moment it finishes. A timeout loses at
      # most the stage in flight.
      # =========================================================================
      - name: Derive branch name
        id: branch-name-early
        run: |
          source /tmp/workflow-helpers.sh
          # Replace colons and other invalid chars with hyphens for git branch name
          SAFE_RUN_ID=$(echo "$RUN_ID" | sed 's/[:]/-/g' | sed 's/[^a-zA-Z0-9._-]/-/g')
          set_output "safe_run_id" "$SAFE_RUN_ID"
          echo "Run ID for the branch name: $SAFE_RUN_ID"

      - name: Create docs branch
        id: create-pr-branch
        run: |
          source /tmp/workflow-helpers.sh

          # Use sanitized run ID for branch name. Branch, PR title, status file and
          # commit messages all carry the product name: 🦩 Flamingo Code Documentation.
          SAFE_RUN_ID="${{ steps.branch-name-early.outputs.safe_run_id }}"
          BRANCH_NAME="${DOCS_BRANCH_PREFIX}$SAFE_RUN_ID"

          # Configure git
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"

          # Create and push empty branch
          git checkout -b "$BRANCH_NAME"

          # Create initial commit to enable PR creation
          echo "# 🦩 Flamingo Code Documentation: Started" > .flamingo-ai-technical-writer-status.md
          echo "" >> .flamingo-ai-technical-writer-status.md
          echo "Run ID: $SAFE_RUN_ID" >> .flamingo-ai-technical-writer-status.md
          echo "Status: In Progress" >> .flamingo-ai-technical-writer-status.md
          echo "Started: $(date -u +"%Y-%m-%d %H:%M:%S UTC")" >> .flamingo-ai-technical-writer-status.md
          # -f: the status file is a hidden dot-md that many target repos' .gitignore
          # patterns (e.g. `.*` / `*status*`) cover — without -f, `git add` fails the
          # step. It's removed again in "Clean up temporary files" before the PR.
          git add -f .flamingo-ai-technical-writer-status.md
          git commit -m "docs: Initialize 🦩 Flamingo Code Documentation run [skip ci]"
          git push -u origin "$BRANCH_NAME"

          # Store branch name for later steps
          set_output "branch_name" "$BRANCH_NAME"

          echo "Docs branch pushed: $BRANCH_NAME"

      - name: Ensure pull request labels exist
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          # Labels used for 🦩 Flamingo Code Documentation PRs
          LABELS=(
            "documentation:A label for documentation-related PRs:#0075ca"
            "automated:PRs created by automation/bots:#ededed"
            "in-progress:Work in progress - not ready for merge:#fbca04"
          )

          for LABEL_DEF in "${LABELS[@]}"; do
            LABEL_NAME=$(echo "$LABEL_DEF" | cut -d: -f1)
            LABEL_DESC=$(echo "$LABEL_DEF" | cut -d: -f2)
            LABEL_COLOR=$(echo "$LABEL_DEF" | cut -d: -f3 | sed 's/#//')

            # Check if label exists
            if gh label list --json name --jq '.[].name' | grep -q "^${LABEL_NAME}$"; then
              echo "Label exists: $LABEL_NAME"
            else
              echo "Creating label: $LABEL_NAME"
              gh label create "$LABEL_NAME" \
                --description "$LABEL_DESC" \
                --color "$LABEL_COLOR" || true
            fi
          done

      - name: Open pull request
        id: create-initial-pr
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          RUN_ID_VAR: ${{ env.RUN_ID }}
          REPO_NAME: ${{ github.repository }}
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
        run: |
          source /tmp/workflow-helpers.sh

          # Create PR body in a temp file (avoiding YAML parsing issues)
          {
            echo "🦩 Flamingo Code Documentation: In Progress"
            echo ""
            echo "Run ID: $RUN_ID_VAR"
            echo "Status: Running..."
            echo ""
            echo "This PR will be updated as each documentation stage completes."
            echo ""
            echo "Progress"
            echo "- Stage 1 Inline Documentation - Starting..."
            echo "- Stage 2 Architecture Analysis - Pending"
            echo "- Stage 3 Tutorial Generation - Pending"
            echo "- Stage 4 Repository Documentation - Pending"
            echo ""
            echo "Generated by 🦩 Flamingo Code Documentation"
          } > /tmp/pr-body.md

          # Create PR with gh CLI (works with existing branches)
          PR_URL=$(gh pr create \
            --base "$DEFAULT_BRANCH" \
            --head "$BRANCH_NAME" \
            --title "[IN PROGRESS] 🦩 Flamingo Code Documentation" \
            --body-file /tmp/pr-body.md \
            --label "documentation,automated,in-progress")

          # Extract PR number from URL
          PR_NUMBER=$(echo "$PR_URL" | grep -oE '[0-9]+$')

          echo "Pull request #$PR_NUMBER opened: $PR_URL"

          # Set outputs for later steps
          set_output "pull-request-url" "$PR_URL"
          set_output "pull-request-number" "$PR_NUMBER"

      # =========================================================================
      # REMOVE DOCS THIS RUN REGENERATES
      # Deletes the documentation the configured stages own before they run, so
      # the result carries no orphaned files. A subtree whose stage then
      # produces nothing is put back by "Restore docs no stage regenerated".
      # =========================================================================
      - name: Remove docs this run regenerates
        env:
          DOCS_OUTPUT_PATH: ${{ env.DOCS_OUTPUT_PATH }}
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
          GETTING_STARTED_OUTPUT_PATH: ${{ env.GETTING_STARTED_OUTPUT_PATH }}
          DEVELOPMENT_OUTPUT_PATH: ${{ env.DEVELOPMENT_OUTPUT_PATH }}
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
        run: |
          source /tmp/workflow-helpers.sh

          # Recorded so a stage that ends up producing nothing can restore what was
          # deleted on its behalf. Without it, a skipped stage turns the pull request
          # into a net DELETION of existing documentation.
          PRE_CLEAN_SHA=$(git rev-parse HEAD)
          echo "PRE_CLEAN_SHA=$PRE_CLEAN_SHA" >> $GITHUB_ENV
          echo "Commit before removal: $PRE_CLEAN_SHA"

          # SCOPED TO THE CONFIGURED STAGES.
          #
          # This used to `rm -rf $DOCS_OUTPUT_PATH` unconditionally. That was safe only
          # while every repo ran all four stages. With per-repo `stages`, wiping the
          # whole tree when Stage 2 is disabled means the reference architecture and
          # diagrams are deleted and never rebuilt — the pull request becomes a net
          # DELETION of existing documentation.
          CLEAN_TARGETS=()
          if [[ "$STAGES" == *"codewiki"* ]]; then
            CLEAN_TARGETS+=("$REFERENCE_OUTPUT_PATH" "$DIAGRAMS_OUTPUT_PATH")
          fi
          if [[ "$STAGES" == *"tutorials"* ]]; then
            CLEAN_TARGETS+=("$GETTING_STARTED_OUTPUT_PATH" "$DEVELOPMENT_OUTPUT_PATH")
          fi

          # DELETE_TARGETS is what actually gets rm -rf'd; CLEAN_TARGETS is what the
          # restore step keys PER-STAGE. They differ only for a full wipe: we delete
          # the whole tree (so orphaned files from a previous layout — e.g. synthetic
          # module_N dirs left by an earlier clustering-failure run — cannot survive)
          # but still RECORD the per-stage subtrees, so the restore leaves each
          # subtree deleted iff its OWN stage produced output.
          #
          # Recording the blanket DOCS_OUTPUT_PATH instead (the old behaviour) made the
          # restore treat docs/ as a single unit that is "safe to leave deleted" only
          # once ALL FOUR stages complete — but the restore runs right after Stage 2,
          # so Stage 3/4 are never 'completed' yet, and it restored the ENTIRE pre-clean
          # tree every time, undoing the wipe and resurrecting the orphaned module_N docs.
          DELETE_TARGETS=("${CLEAN_TARGETS[@]}")
          FULL_WIPE=false
          SELECTED_COUNT=$(echo "$STAGES" | tr ',' '\n' | grep -c .)
          if [ "$SELECTED_COUNT" -ge "${STAGE_COUNT:-4}" ]; then
            FULL_WIPE=true
            DELETE_TARGETS=("$DOCS_OUTPUT_PATH")
            # Record every stage-owned subtree (NOT the blanket docs/) so the restore
            # keys each subtree on its own stage instead of the all-four AND.
            CLEAN_TARGETS=("$REFERENCE_OUTPUT_PATH" "$DIAGRAMS_OUTPUT_PATH" "$GETTING_STARTED_OUTPUT_PATH" "$DEVELOPMENT_OUTPUT_PATH")
          fi

          echo "Stages:    $STAGES"
          echo "Full wipe: $FULL_WIPE"
          echo "Targets:   ${CLEAN_TARGETS[*]:-(none)}"

          # Recorded so the restore step iterates exactly what was removed — the
          # stage -> subtree map has ONE home, here.
          {
            echo "CLEAN_TARGETS_RECORD<<__EOT__"
            for t in ${CLEAN_TARGETS[@]+"${CLEAN_TARGETS[@]}"}; do echo "$t"; done
            echo "__EOT__"
          } >> $GITHUB_ENV

          # Count files before deletion (for reporting). Iterate DELETE_TARGETS —
          # the actual rm list (blanket docs/ on a full wipe, per-stage subtrees
          # otherwise) — not the restore-record CLEAN_TARGETS.
          DELETED_FILES=0
          for target in ${DELETE_TARGETS[@]+"${DELETE_TARGETS[@]}"}; do
            if [ -d "$target" ]; then
              TARGET_FILES=$(find "$target" -type f | wc -l | tr -d ' ')
              DELETED_FILES=$((DELETED_FILES + TARGET_FILES))
              echo "Removing $target ($TARGET_FILES files)"
              rm -rf "$target"
            else
              echo "Skipping $target (does not exist)"
            fi
          done
          if [ ${#DELETE_TARGETS[@]} -eq 0 ]; then
            echo "No configured stage owns a docs subtree; nothing to remove"
          fi

          # Recreate base directory
          mkdir -p "$DOCS_OUTPUT_PATH"

          # Commit the deletion to git (so it shows in PR)
          if [ "$DELETED_FILES" -gt 0 ]; then
            git add -A

            # Check if there are staged changes
            STAGED_COUNT=$(git diff --cached --name-only | wc -l | tr -d ' ')

            if [ "$STAGED_COUNT" -gt 0 ]; then
              git commit -m "chore(docs): Clean slate - remove all documentation ($DELETED_FILES files) [skip ci]"
              git push origin "$BRANCH_NAME"
              echo "Committed the removal of $STAGED_COUNT files"
            else
              echo "Nothing to commit (the docs were already absent)"
            fi
          fi

      - name: Set up Node.js
        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
        with:
          node-version: '22'
          # v5+ caches automatically when it finds a package manager; this job never did.
          package-manager-cache: false

      # =========================================================================
      # STAGE 0: CODE GRAPH (same build as the standalone code-graph job above)
      # Tags the SOURCE branch head so the hub can render this run's
      # ecosystem.md from the snapshot of the commit being documented. The hub
      # promotes to `live` only when the source branch is the default branch.
      # Never fatal: a graph failure costs cross-repo facts, not the docs run.
      # =========================================================================
      # The command is CODE_GRAPH_INSTALL_COMMAND (lib/config/code-graph-workflow.ts).
      - name: Install graph dependencies
        continue-on-error: true
        run: mkdir -p "$RUNNER_TEMP/code-graph-deps" && cd "$RUNNER_TEMP/code-graph-deps" && printf '%s' '{"name":"code-graph-deps","version":"1.0.0","private":true,"dependencies":{"web-tree-sitter":"0.27.0","@vscode/tree-sitter-wasm":"0.3.1","yaml":"2.9.1"}}' > package.json && printf '%s' '{"name":"code-graph-deps","version":"1.0.0","lockfileVersion":3,"requires":true,"packages":{"":{"name":"code-graph-deps","version":"1.0.0","dependencies":{"web-tree-sitter":"0.27.0","@vscode/tree-sitter-wasm":"0.3.1","yaml":"2.9.1"}},"node_modules/web-tree-sitter":{"version":"0.27.0","resolved":"https://registry.npmjs.org/web-tree-sitter/-/web-tree-sitter-0.27.0.tgz","integrity":"sha512-XK08gj6RwTMQatAG7uVRP8MunqotL/XC19vHgkSPKmELgbGPBj4ECvB8haHOUnyj6ls2B8t42UTro14zxGgAHg=="},"node_modules/@vscode/tree-sitter-wasm":{"version":"0.3.1","resolved":"https://registry.npmjs.org/@vscode/tree-sitter-wasm/-/tree-sitter-wasm-0.3.1.tgz","integrity":"sha512-RJFoomET6FajjG511fmQxeBQfU6M24a0aFZPqpid+ttIxanWf1VGytBG0UmsGjt07qmIPJS8U31D+aecuCucsQ=="},"node_modules/yaml":{"version":"2.9.1","resolved":"https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz","integrity":"sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw=="}}}' > package-lock.json && npm ci --ignore-scripts --no-audit --no-fund && echo "CODE_GRAPH_DEPS_DIR=$RUNNER_TEMP/code-graph-deps" >> "$GITHUB_ENV" || { echo "::warning::graph dependencies failed their lockfile-enforced install; continuing without them"; rm -rf "$RUNNER_TEMP/code-graph-deps"; exit 1; }

      - name: Build and upload the code graph
        id: graph
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          CODE_GRAPH_DEPS_DIR: ${{ env.CODE_GRAPH_DEPS_DIR }}
          GITHUB_REPOSITORY: ${{ github.repository }}
          CODE_GRAPH_BRANCH: ${{ env.SOURCE_BRANCH }}
          CODE_GRAPH_COMMIT_SHA: ${{ env.SOURCE_HEAD_SHA }}
        run: node /tmp/code-graph-build.mjs

      # =========================================================================
      # STAGE 1: INLINE DOCS
      # One hidden .md beside each source file, over the discovered file list.
      # =========================================================================
      - name: Install stage 1 dependencies
        if: contains(env.STAGES, 'inline-docs')
        # Install generator deps in an ISOLATED tree under RUNNER_TEMP, NOT the target
        # repo. npm resolves against an empty package.json here, so a target repo's own
        # peer conflicts (e.g. react-accessible-accordion vs react 18) can never make this
        # fail. No --legacy-peer-deps / --no-save band-aids. Generators find these via the
        # NODE_PATH set on the generate step (RUNNER_TEMP/doc-orch-deps/node_modules).
        run: |
          mkdir -p "$RUNNER_TEMP/doc-orch-deps" && cd "$RUNNER_TEMP/doc-orch-deps"
          npm init -y >/dev/null 2>&1
          npm install @anthropic-ai/sdk@0.115.0 zod@3.25.76 glob@13.0.6

      - name: Generate inline docs (stage 1)
        id: stage1
        if: contains(env.STAGES, 'inline-docs')
        env:
          # SECURITY: Pass secrets per-step with inline masking.
          # No ANTHROPIC_API_KEY — this stage calls Claude through the hub
          # (/api/ci/claude), which the WEBHOOK_SECRET below authenticates.
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          # Claude model SSOT — see workflow env CLAUDE_MODEL block
          CLAUDE_MODEL: ${{ env.CLAUDE_MODEL }}
          DOCS_OUTPUT_PATH: ${{ env.DOCS_OUTPUT_PATH }}
          # Stage timeout (in hours)
          STAGE1_TIMEOUT_HOURS: ${{ env.STAGE1_TIMEOUT_HOURS }}
          # Incremental commit + push every N generated docs (see workflow env)
          STAGE1_PUSH_INTERVAL: ${{ env.STAGE1_PUSH_INTERVAL }}
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          STAGE1_PUSH_MARKER: /tmp/stage1-progress-pushes
          # Unified file discovery result (single source of truth)
          SOURCE_FILES_LIST: ${{ steps.discover_files.outputs.source_files_list }}
          SOURCE_FILE_COUNT: ${{ steps.discover_files.outputs.source_file_count }}
          # NODE_PATH to find modules from /tmp/ scripts
          NODE_PATH: ${{ runner.temp }}/doc-orch-deps/node_modules
          # Custom AI Instructions (All Stages)
          CUSTOM_REPO_INSTRUCTIONS: ${{ env.CUSTOM_INSTRUCTIONS }}
          # External Repositories
          EXTERNAL_REPOS: ${{ env.EXTERNAL_REPOS }}
        run: |
          source /tmp/workflow-helpers.sh

          echo "Source files: $SOURCE_FILE_COUNT (from $SOURCE_FILES_LIST)"
          echo "Progress push: every $STAGE1_PUSH_INTERVAL generated docs, to $BRANCH_NAME"

          # Fresh marker: the generator appends one line per progress push, and the
          # commit step below reads it to know work was already pushed.
          rm -f "$STAGE1_PUSH_MARKER"

          # Script already downloaded to /tmp/ in setup step. run_stage records
          # the outcome as stage1_status — see its note in workflow-helpers.sh.
          run_stage "Stage 1" "$STAGE1_TIMEOUT_HOURS" stage1_status node /tmp/generate-inline-docs.cjs

          # Count generated files (hidden .*.md files)
          INLINE_DOCS=$(find . -name ".*.md" -newer .git -type f -not -path "./node_modules/*" -not -path "./.git/*" | wc -l)
          set_output "stage1_files" "$INLINE_DOCS"

      # =========================================================================
      # COMMIT STAGE 1 RESULTS (progressive pull request)
      # =========================================================================
      # `!= ''`, not `== 'completed'`: runs on a FAILED stage too — see run_stage
      # in workflow-helpers.sh (partial output is worth committing; the status
      # is what reports the truth home). The build gate holds every run_stage
      # commit step to this predicate.
      - name: Commit and push stage 1 results
        if: always() && steps.stage1.outputs.stage1_status != ''
        id: commit-stage1
        env:
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          STAGE_FILES: ${{ steps.stage1.outputs.stage1_files }}
          STAGE1_PUSH_MARKER: /tmp/stage1-progress-pushes
        run: |
          source /tmp/workflow-helpers.sh

          # The generator already commits + pushes every N docs (STAGE1_PUSH_INTERVAL).
          # Report how much landed that way; what's left here is the final partial batch.
          if [ -s "$STAGE1_PUSH_MARKER" ]; then
            PUSHED_BATCHES=$(wc -l < "$STAGE1_PUSH_MARKER" | tr -d ' ')
            PUSHED_FILES=$(awk '{ sum += $1 } END { print sum + 0 }' "$STAGE1_PUSH_MARKER")
            echo "Already pushed during generation: $PUSHED_FILES files in $PUSHED_BATCHES batches"
          fi

          # Push any commits the generator made but could not push (transient push failure)
          git push origin "HEAD:refs/heads/$BRANCH_NAME" 2>/dev/null || true

          # Stage all .md files generated by Stage 1 (hidden inline docs)
          find . -name ".*.md" -type f \
            -not -path "./node_modules/*" \
            -not -path "./.git/*" \
            -exec git add -f {} \; 2>/dev/null || true

          # Check if there are changes
          STAGED_COUNT=$(git diff --cached --name-only | wc -l)

          if [ "$STAGED_COUNT" -gt 0 ]; then
            # Commit and push
            git commit -m "docs: Stage 1 - Inline documentation ($STAGE_FILES files) [skip ci]"
            git push origin "$BRANCH_NAME"

            echo "Committed and pushed $STAGED_COUNT stage 1 files"
            set_output "committed" "true"
          elif [ -s "$STAGE1_PUSH_MARKER" ]; then
            # Everything already landed via the incremental progress pushes
            echo "Nothing left to commit: every stage 1 file was pushed during generation"
            set_output "committed" "true"
          else
            echo "::warning title=Stage 1 produced nothing::No inline docs to commit."
            set_output "committed" "false"
          fi

      # =========================================================================
      # ORPHANED INLINE DOCS
      # Right after stage 1: removes each hidden .*.md whose source file is gone.
      # =========================================================================
      # `== 'completed'` HERE IS DELIBERATE, unlike the commit steps: deleting
      # "orphaned" docs after a stage that FAILED would delete docs whose
      # sources were never re-examined.
      - name: Remove orphaned inline docs
        if: always() && steps.stage1.outputs.stage1_status == 'completed'
        id: orphan-detection-inline
        env:
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
        run: |
          source /tmp/workflow-helpers.sh

          # Run orphan detection script
          bash /tmp/detect-orphans.sh || true

          # Check if orphans were deleted (script writes list to /tmp/orphaned-inline-files.txt)
          DELETED_FILES_LIST="/tmp/orphaned-inline-files.txt"

          if [ -f "$DELETED_FILES_LIST" ] && [ -s "$DELETED_FILES_LIST" ]; then
            DELETED_COUNT=$(wc -l < "$DELETED_FILES_LIST" | tr -d ' ')
            echo "Orphaned inline docs removed: $DELETED_COUNT"

            # Only add the specific files that were deleted by the script
            while IFS= read -r deleted_file; do
              git add "$deleted_file" 2>/dev/null || true
            done < "$DELETED_FILES_LIST"

            # Verify we have staged changes
            STAGED_COUNT=$(git diff --cached --name-only | wc -l | tr -d ' ')

            if [ "$STAGED_COUNT" -gt 0 ]; then
              git commit -m "chore(docs): Remove $DELETED_COUNT orphaned inline files [skip ci]"
              git push origin "$BRANCH_NAME"
              echo "Committed $STAGED_COUNT orphan removals"
              set_output "orphans_deleted" "$STAGED_COUNT"
            else
              echo "Nothing to commit (the files were already absent)"
              set_output "orphans_deleted" "0"
            fi
          else
            echo "No orphaned inline docs"
            set_output "orphans_deleted" "0"
          fi

      - name: Update pull request with stage 1 progress
        if: always() && steps.commit-stage1.outputs.committed == 'true' && steps.create-initial-pr.outputs.pull-request-number
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files }}
          RUN_ID_VAR: ${{ env.RUN_ID }}
          REPO_NAME: ${{ github.repository }}
        run: |
          source /tmp/workflow-helpers.sh

          # Update PR body
          PR_BODY="## 🦩 Flamingo Code Documentation: In Progress

          **Run ID:** \`$RUN_ID_VAR\`
          **Status:** 🔄 Running...

          This PR is being updated as each documentation stage completes.

          ### Progress
          - ✅ Stage 1: Inline Documentation - Completed ($STAGE1_FILES files)
          - ⏳ Stage 2: Architecture Analysis - Running...
          - ⏱️ Stage 3: Tutorial Generation - Pending
          - ⏱️ Stage 4: Repository Documentation - Pending

          ---
          🦩 Generated by [Flamingo Code Documentation](https://flamingo.run)"

          gh pr edit "$PR_NUMBER" --body "$PR_BODY"

          echo "Pull request #$PR_NUMBER updated with stage 1 progress"

      - name: Report stage 1 progress
        if: always() && contains(env.STAGES, 'inline-docs') && env.HUB_BASE_URL != ''
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          WORKFLOW_RUN_ID: ${{ github.run_id }}
          WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status || 'skipped' }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          PR_URL: ${{ steps.create-initial-pr.outputs.pull-request-url }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
        run: |
          source /tmp/workflow-helpers.sh

          CALLBACK_URL="${HUB_BASE_URL}/api/code-documentation/webhook"
          echo "Reporting stage 1 (inline docs): $STAGE1_STATUS, $STAGE1_FILES files"
          report_stage_progress "$CALLBACK_URL" "$WEBHOOK_SECRET" "$RUN_ID" "$REPO_ID" \
            "$WORKFLOW_RUN_ID" "$WORKFLOW_URL" "codewiki" \
            "$STAGE1_STATUS" "$STAGE1_FILES" "" "0" "" "0" "" "0" \
            "$PR_URL" "$PR_NUMBER"

      # =========================================================================
      # ECOSYSTEM FACTS — derived by the hub from the code graph, never written
      # by a model. Two renderings of the same live snapshot: ecosystem.md
      # (committed under the reference tree and fed to the Stage 2/3/4 prompts
      # as ground truth for the Dependencies sections) and the marker-delimited
      # AGENTS.md block (upserted in place, idempotent). A repo with no graph
      # yet is a notice, not a failure.
      # =========================================================================
      - name: Fetch ecosystem facts
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
        run: |
          source /tmp/workflow-helpers.sh

          # Through ci-hub.mjs, the shell's way into the ONE hub transport
          # (code-review-lib.mjs): it checks the destination before the secret
          # leaves, keeps the secret in a header, and writes the body only on a
          # 2xx. It prints the status and exits 0 whenever the hub ANSWERED — a 404
          # is an answer ("no graph yet"), not a failure.
          REPO_PARAM=$(printf '%s' "$GITHUB_REPOSITORY" | sed 's|/|%2F|g')
          ECOSYSTEM_PATH="/api/ci/code-graph/ecosystem.md?repo=${REPO_PARAM}"

          HTTP_CODE=$(node /tmp/ci-hub.mjs get "$ECOSYSTEM_PATH" /tmp/ecosystem.md) || HTTP_CODE="000"
          if [ "$HTTP_CODE" = "404" ]; then
            echo "::notice title=No code graph yet::The hub has no code graph for $GITHUB_REPOSITORY yet; the docs are written without ecosystem facts."
            rm -f /tmp/ecosystem.md
            exit 0
          fi
          if [ "$HTTP_CODE" != "200" ]; then
            echo "::warning title=Ecosystem facts unavailable::The hub answered HTTP $HTTP_CODE; the Dependencies sections are written without cross-repository facts."
            rm -f /tmp/ecosystem.md
            exit 0
          fi
          # Kept in /tmp ONLY until Stage 2 has run. The reference directory is
          # CodeWiki's output directory, and CodeWiki asks "already contains
          # documentation. Overwrite?" when it finds a .md file there — a prompt
          # a runner cannot answer, so Stage 2 aborted on every CodeWiki repo
          # (CodeWiki run 35293807658). The Stage 2 commit step copies the file
          # into place, after either engine has written its own output.
          echo "Fetched ecosystem.md ($(wc -c < /tmp/ecosystem.md | tr -d ' ') bytes); it is copied to $REFERENCE_OUTPUT_PATH after stage 2"

          HTTP_CODE=$(node /tmp/ci-hub.mjs get "${ECOSYSTEM_PATH}&format=agents" /tmp/ecosystem-agents.md) || HTTP_CODE="000"
          if [ "$HTTP_CODE" = "200" ]; then
            upsert_marker_block AGENTS.md /tmp/ecosystem-agents.md
            # Claude Code reads CLAUDE.md, and AGENTS.md only when a folder has NO CLAUDE.md
            # (native fallback since 2.1.277). A repository that keeps a CLAUDE.md therefore gets
            # ONE marker-delimited `@AGENTS.md` import, so its agents load the block above (the
            # ecosystem facts and the multi-repo change-set rule). Skipped when CLAUDE.md already
            # imports AGENTS.md itself; never creates a CLAUDE.md.
            IMPORT_START='<!-- flamingo-agents-import:start -->'
            IMPORT_END='<!-- flamingo-agents-import:end -->'
            if [ -f CLAUDE.md ] && { grep -qF "$IMPORT_START" CLAUDE.md || ! grep -qE '(^|[[:space:]])@AGENTS\.md' CLAUDE.md; }; then
              printf '%s\n' "$IMPORT_START" '@AGENTS.md' "$IMPORT_END" > /tmp/claude-agents-import.md
              upsert_marker_block CLAUDE.md /tmp/claude-agents-import.md "$IMPORT_START" "$IMPORT_END"
            fi
          else
            echo "::warning title=AGENTS.md block unavailable::The hub answered HTTP $HTTP_CODE; AGENTS.md is left untouched."
            rm -f /tmp/ecosystem-agents.md
          fi

      # =========================================================================
      # STAGE 2: REFERENCE DOCS
      # Architecture overview, module tree and diagrams. CodeWiki where it can
      # parse the primary language ("Detect primary language" decided, before
      # stage 1), otherwise the Claude architecture analysis.
      # =========================================================================

      - name: Set up Python 3.12
        if: contains(env.STAGES, 'codewiki') && steps.detect_language.outputs.codewiki_supported == 'true'
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: '3.12'

      - name: Install CodeWiki
        id: codewiki_install
        if: contains(env.STAGES, 'codewiki') && steps.detect_language.outputs.codewiki_supported == 'true'
        continue-on-error: true
        env:
          CODEWIKI_MAX_FILES_PER_MODULE: ${{ env.CODEWIKI_MAX_FILES_PER_MODULE }}
          CODEWIKI_REPO: ${{ env.CODEWIKI_REPO }}
        run: |
          # Install keyrings.alt for headless keyring support in CI environments
          # Install ipython to suppress "Mermaidjs magic function not available" warning
          # Install colorama for CodeWiki colored terminal output
          pip install keyrings.alt ipython colorama

          # Clone CodeWiki directly (no pip caching issues)
          # Fixes baked into fork:
          #   - retries=3 for Pydantic AI agents (prevents "Tool exceeded max retries count of 1")
          #   - Synthetic module creation when clustering returns 0 modules (prevents context overflow)
          #   - 'children' key fix for synthetic modules
          #   - module_tree.json path fix (commit c1dfe5c) - loads from base docs dir, not nested module dir
          # See: https://github.com/flamingo-stack/CodeWiki
          # Extract repo URL from CODEWIKI_REPO (strip git+ prefix and @branch/commit suffix)
          REPO_URL=$(echo "$CODEWIKI_REPO" | sed 's|^git+||' | sed 's|@[^@]*$||')
          REF=$(echo "$CODEWIKI_REPO" | grep -o '@[^@]*$' | sed 's|^@||' || echo "main")
          echo "📦 Cloning CodeWiki from: $REPO_URL (ref: ${REF:-main})"
          rm -rf /tmp/CodeWiki

          # Clone and checkout - handle both branches and commit hashes
          if [[ "${REF}" =~ ^[0-9a-f]{7,40}$ ]]; then
            # Commit hash - clone full repo and checkout specific commit
            git clone "$REPO_URL" /tmp/CodeWiki
            cd /tmp/CodeWiki && git checkout "${REF}" && cd -
          else
            # Branch name - shallow clone
            git clone --depth 1 --branch "${REF:-main}" "$REPO_URL" /tmp/CodeWiki
          fi

          echo "   Commit: $(cd /tmp/CodeWiki && git rev-parse --short HEAD)"

          # Install from local clone (reliable, no caching)
          echo "📦 Installing CodeWiki from local clone..."
          pip install --no-cache-dir /tmp/CodeWiki

          source /tmp/workflow-helpers.sh
          set_output "codewiki_installed" "true"

      - name: Configure CodeWiki
        id: codewiki_config
        if: contains(env.STAGES, 'codewiki') && steps.detect_language.outputs.codewiki_supported == 'true' && steps.codewiki_install.outputs.codewiki_installed == 'true'
        continue-on-error: true
        env:
          # SECURITY: Pass secrets per-step with inline masking
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          # Set keyring backend via env var (must be set before any keyring operations)
          PYTHON_KEYRING_BACKEND: keyrings.alt.file.PlaintextKeyring
          # Flamingo Markdown Guidelines path (needed for module import during config/validate)
          FLAMINGO_MARKDOWN_GUIDELINES_PATH: /tmp/flamingo-markdown-guidelines.md
          # OSS Tenant Structure: Stage 2 outputs (for clean slate deletion)
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
        run: |
          source /tmp/workflow-helpers.sh

          # === KEYRING CONFIGURATION FOR CI ===
          # CodeWiki stores API keys in system keyring. In CI (no GUI), we must:
          # 1. Create keyring config to specify PlaintextKeyring backend
          # 2. Create data directory for credential storage
          # See: https://github.com/FSoft-AI4Code/CodeWiki - uses keyring.set_password()

          echo "🔑 Setting up keyring for headless CI environment..."

          # Create keyring configuration directory and config file
          mkdir -p ~/.config/python_keyring
          cat > ~/.config/python_keyring/keyringrc.cfg << 'KEYRING_CFG'
          [backend]
          default-keyring=keyrings.alt.file.PlaintextKeyring
          KEYRING_CFG

          # Ensure keyring data directory exists with proper permissions
          mkdir -p ~/.local/share/python_keyring
          chmod 700 ~/.local/share/python_keyring

          # Debug: Verify keyring is properly configured
          echo "📋 Keyring backend verification:"
          python3 -c "import keyring; print(f'  Active backend: {keyring.get_keyring()}')"

          # Configure CodeWiki with separate cluster and generation providers/models
          # CodeWiki calls provider APIs directly via --base-url
          # Model names should match the provider's API format (no LiteLLM prefix needed)
          # OpenAI: gpt-4o, gpt-4-turbo, gpt-4o-mini
          # Provider ids come from MODEL_METADATA in lib/constants/ai-models.ts
          # See: https://github.com/FSoft-AI4Code/CodeWiki

          echo "🔧 Configuring CodeWiki..."
          echo "   Cluster (Phase 2): $CODEWIKI_CLUSTER_PROVIDER / $CODEWIKI_CLUSTER_MODEL"
          echo "   Generation (Phase 3+): $CODEWIKI_GENERATION_PROVIDER / $CODEWIKI_GENERATION_MODEL"

          # Source helper functions for configuration
          source /tmp/workflow-helpers.sh

          # Determine API keys for each provider (cluster, generation/main, fallback)
          # Each provider can use a different AI service (OpenAI, Anthropic, etc.)
          if [ "$CODEWIKI_CLUSTER_PROVIDER" = "anthropic" ]; then
            CLUSTER_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
            echo "   Cluster: Using Anthropic API key"
          else
            CLUSTER_API_KEY="${{ secrets.OPENAI_API_KEY }}"
            echo "   Cluster: Using OpenAI API key"
          fi

          if [ "$CODEWIKI_GENERATION_PROVIDER" = "anthropic" ]; then
            MAIN_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
            echo "   Generation: Using Anthropic API key"
          else
            MAIN_API_KEY="${{ secrets.OPENAI_API_KEY }}"
            echo "   Generation: Using OpenAI API key"
          fi

          if [ "$CODEWIKI_FALLBACK_PROVIDER" = "anthropic" ]; then
            FALLBACK_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
            echo "   Fallback: Using Anthropic API key"
          else
            FALLBACK_API_KEY="${{ secrets.OPENAI_API_KEY }}"
            echo "   Fallback: Using OpenAI API key"
          fi

          # Configure CodeWiki from CODEWIKI_CONFIG_JSON (single extractor: configure_codewiki_from_json)
          # Pass per-provider API keys for mixed provider configurations
          configure_codewiki_from_json "$CODEWIKI_CONFIG_JSON" "$CLUSTER_API_KEY" "$MAIN_API_KEY" "$FALLBACK_API_KEY"

          if [ $? -ne 0 ]; then
            echo "❌ CodeWiki configuration failed"
            exit 1
          fi

          # Set environment variables for backward compatibility with run-codewiki-analysis.sh
          export MAIN_MODEL="$CODEWIKI_GENERATION_MODEL"
          export FALLBACK_MODEL_1="$CODEWIKI_FALLBACK_MODEL"
          if [ "$PRIMARY_PROVIDER" = "anthropic" ]; then
            export ANTHROPIC_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
          else
            export OPENAI_API_KEY="${{ secrets.OPENAI_API_KEY }}"
          fi

          # Verify configuration was saved
          echo ""
          echo "📋 CodeWiki configuration:"
          python -m codewiki config show

          echo ""
          echo "✅ Validating configuration..."
          python -m codewiki config validate

          echo ""
          set_output "codewiki_configured" "true"

      - name: Generate reference docs with CodeWiki (stage 2)
        id: stage2
        if: contains(env.STAGES, 'codewiki') && steps.detect_language.outputs.codewiki_supported == 'true' && steps.codewiki_config.outputs.codewiki_configured == 'true'
        continue-on-error: false
        env:
          # Keyring backend for CI (must match config step)
          PYTHON_KEYRING_BACKEND: keyrings.alt.file.PlaintextKeyring
          # API keys for both providers (CodeWiki will use the one configured)
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          # OSS Tenant Structure: Stage 2 outputs
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
          # Stage timeout
          STAGE2_TIMEOUT_HOURS: ${{ env.STAGE2_TIMEOUT_HOURS }}
          # CodeWiki JSON configuration (required for unified function)
          CODEWIKI_CONFIG_JSON: ${{ env.CODEWIKI_CONFIG_JSON }}
          # CodeWiki model configuration (cluster, generation, fallback)
          CODEWIKI_CLUSTER_PROVIDER: ${{ env.CODEWIKI_CLUSTER_PROVIDER }}
          CODEWIKI_CLUSTER_MODEL: ${{ env.CODEWIKI_CLUSTER_MODEL }}
          CODEWIKI_CLUSTER_MAX_TOKENS: ${{ env.CODEWIKI_CLUSTER_MAX_TOKENS }}
          CODEWIKI_CLUSTER_MAX_TOKEN_FIELD: ${{ env.CODEWIKI_CLUSTER_MAX_TOKEN_FIELD }}
          CODEWIKI_GENERATION_PROVIDER: ${{ env.CODEWIKI_GENERATION_PROVIDER }}
          CODEWIKI_GENERATION_MODEL: ${{ env.CODEWIKI_GENERATION_MODEL }}
          CODEWIKI_GENERATION_MAX_TOKENS: ${{ env.CODEWIKI_GENERATION_MAX_TOKENS }}
          CODEWIKI_GENERATION_MAX_TOKEN_FIELD: ${{ env.CODEWIKI_GENERATION_MAX_TOKEN_FIELD }}
          CODEWIKI_FALLBACK_PROVIDER: ${{ env.CODEWIKI_FALLBACK_PROVIDER }}
          CODEWIKI_FALLBACK_MODEL: ${{ env.CODEWIKI_FALLBACK_MODEL }}
          CODEWIKI_FALLBACK_MAX_TOKENS: ${{ env.CODEWIKI_FALLBACK_MAX_TOKENS }}
          CODEWIKI_FALLBACK_MAX_TOKEN_FIELD: ${{ env.CODEWIKI_FALLBACK_MAX_TOKEN_FIELD }}
          CODEWIKI_MAX_DEPTH: ${{ env.CODEWIKI_MAX_DEPTH }}
          # Flamingo Markdown Guidelines path for CodeWiki prompts
          FLAMINGO_MARKDOWN_GUIDELINES_PATH: /tmp/flamingo-markdown-guidelines.md
          # Markdown Validation Rules (injected into all prompts)
          VALIDATION_RULES_PATH: ${{ env.VALIDATION_RULES_PATH }}
          # Custom AI Instructions (All Stages)
          CUSTOM_REPO_INSTRUCTIONS: ${{ env.CUSTOM_INSTRUCTIONS }}
          # External Repositories
          EXTERNAL_REPOS: ${{ env.EXTERNAL_REPOS }}
          # Dependencies (for CodeWiki multi-path support)
          DEPENDENCIES: ${{ env.DEPENDENCIES }}
        run: |
          # Determine per-provider API keys (same logic as Configure step)
          if [ "$CODEWIKI_CLUSTER_PROVIDER" = "anthropic" ]; then
            export CLUSTER_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
          else
            export CLUSTER_API_KEY="${{ secrets.OPENAI_API_KEY }}"
          fi

          if [ "$CODEWIKI_GENERATION_PROVIDER" = "anthropic" ]; then
            export MAIN_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
          else
            export MAIN_API_KEY="${{ secrets.OPENAI_API_KEY }}"
          fi

          if [ "$CODEWIKI_FALLBACK_PROVIDER" = "anthropic" ]; then
            export FALLBACK_API_KEY="${{ secrets.ANTHROPIC_API_KEY }}"
          else
            export FALLBACK_API_KEY="${{ secrets.OPENAI_API_KEY }}"
          fi

          # Verify dependencies directory before CodeWiki runs
          echo ""
          echo "🔍 Pre-CodeWiki Dependency Verification:"
          echo "   Current directory: $(pwd)"
          echo "   Absolute path: $(realpath .)"
          echo ""

          if [ -d "./deps" ]; then
            echo "   ✅ ./deps EXISTS"
            echo "      Contents: $(ls -1 ./deps 2>/dev/null | wc -l) repositories"
            ls -la ./deps 2>/dev/null | head -5
          else
            echo "   ❌ ./deps NOT FOUND"
          fi

          if [ -d "../deps" ]; then
            echo "   ✅ ../deps EXISTS"
            echo "      Absolute: $(realpath ../deps)"
            echo "      Contents: $(ls -1 ../deps 2>/dev/null | wc -l) repositories"
            ls -la ../deps 2>/dev/null | head -5
          else
            echo "   ❌ ../deps NOT FOUND"
          fi

          echo "   DEPENDENCIES env: ${DEPENDENCIES:-<empty>}"
          echo ""

          # Run externalized CodeWiki analysis script
          /tmp/run-codewiki-analysis.sh

      # The alternative for any language CodeWiki cannot parse.
      - name: Generate reference docs with Claude (stage 2)
        id: stage2_alt
        if: contains(env.STAGES, 'codewiki') && steps.detect_language.outputs.codewiki_supported == 'false'
        env:
          # No ANTHROPIC_API_KEY — this stage calls Claude through the hub
          # (/api/ci/claude), which the WEBHOOK_SECRET below authenticates.
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          # SSOT — see workflow env CLAUDE_MODEL block
          CLAUDE_MODEL: ${{ env.CLAUDE_MODEL }}
          PRIMARY_LANGUAGE: ${{ steps.detect_language.outputs.primary_language }}
          # OSS Tenant Structure: Stage 2 outputs
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
          # Unified file discovery result (single source of truth)
          SOURCE_FILES_LIST: ${{ steps.discover_files.outputs.source_files_list }}
          SOURCE_FILE_COUNT: ${{ steps.discover_files.outputs.source_file_count }}
          # Custom AI Instructions (All Stages)
          CUSTOM_REPO_INSTRUCTIONS: ${{ env.CUSTOM_INSTRUCTIONS }}
          # External Repositories
          EXTERNAL_REPOS: ${{ env.EXTERNAL_REPOS }}
          # Dependencies (for consistency with other stages)
          DEPENDENCIES: ${{ env.DEPENDENCIES }}
        run: |
          # Run externalized Claude architecture analysis script
          /tmp/run-claude-architecture-analysis.sh

      # =========================================================================
      # RESTORE DOCS NO STAGE REGENERATED
      # The docs removal took the reference/diagrams trees because `codewiki` was in
      # STAGES. If neither Stage-2 variant then completed — a repo with no
      # discoverable source, an install failure, a skip — the deletion would be the
      # only Stage-2 change in the pull request, i.e. a net removal of documentation
      # nobody asked to remove. Put it back.
      # =========================================================================
      - name: Restore docs no stage regenerated
        if: always()
        env:
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status }}
          STAGE2_STATUS: ${{ steps.stage2.outputs.stage2_status }}
          STAGE2_ALT_STATUS: ${{ steps.stage2_alt.outputs.stage2_status }}
        run: |
          # The docs removal deleted whatever the configured stages own, and committed that
          # deletion. Any owned subtree whose stage then produced nothing must be put
          # back — otherwise the pull request is a net REMOVAL of documentation nobody
          # asked to remove. Iterates the exact list the removal recorded, so the
          # stage -> subtree map has one home.
          if [ -z "$CLEAN_TARGETS_RECORD" ]; then
            echo "Nothing was removed; nothing to restore"
            exit 0
          fi

          STAGE2_OK=false
          [ "$STAGE2_STATUS" = "completed" ] && STAGE2_OK=true
          [ "$STAGE2_ALT_STATUS" = "completed" ] && STAGE2_OK=true

          # CodeWiki leaves multi-GB scratch behind on a failed run; never let it near
          # the index.
          rm -rf "$REFERENCE_OUTPUT_PATH/temp" "$DIAGRAMS_OUTPUT_PATH/temp" 2>/dev/null || true

          RESTORED=0
          while IFS= read -r target; do
            [ -n "$target" ] || continue
            # A target is safe to leave deleted only if something regenerated it.
            case "$target" in
              "$REFERENCE_OUTPUT_PATH"|"$DIAGRAMS_OUTPUT_PATH")
                [ "$STAGE2_OK" = true ] && continue ;;
              "$GETTING_STARTED_OUTPUT_PATH"|"$DEVELOPMENT_OUTPUT_PATH")
                [ "$STAGE3_STATUS" = "completed" ] && continue ;;
              "$DOCS_OUTPUT_PATH")
                # Full wipe: only fully safe when every stage delivered.
                if [ "$STAGE1_STATUS" = "completed" ] && [ "$STAGE2_OK" = true ] && \
                   [ "$STAGE3_STATUS" = "completed" ] && [ "$STAGE4_STATUS" = "completed" ]; then
                  continue
                fi ;;
            esac
            if git checkout "$PRE_CLEAN_SHA" -- "$target" 2>/dev/null; then
              echo "::notice title=Docs restored::$target restored from $PRE_CLEAN_SHA; no stage regenerated it."
              RESTORED=1
            fi
          done <<< "$CLEAN_TARGETS_RECORD"

          # `git checkout -- <path>` already stages exactly those paths. Deliberately NO
          # `git add -A`: at this point the workspace holds npm install output from
          # Stage 1 and, on a failed CodeWiki run, its scratch trees.
          if [ "$RESTORED" -eq 1 ] && [ -n "$(git diff --cached --name-only)" ]; then
            git commit -m "chore(docs): restore documentation no stage regenerated [skip ci]"
            git push origin "$BRANCH_NAME"
            echo "Restore committed and pushed"
          else
            echo "Nothing to restore"
          fi

      # =========================================================================
      # COMMIT STAGE 2 RESULTS (progressive pull request)
      # =========================================================================
      - name: Commit and push stage 2 results
        if: always() && (steps.stage2.outputs.stage2_status == 'completed' || steps.stage2_alt.outputs.stage2_status == 'completed')
        id: commit-stage2
        env:
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files }}
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
        run: |
          source /tmp/workflow-helpers.sh

          # Remove CodeWiki scratch from every output directory
          rm -rf "$REFERENCE_OUTPUT_PATH/temp" 2>/dev/null || echo "::warning::Could not remove $REFERENCE_OUTPUT_PATH/temp"
          rm -rf "$DIAGRAMS_OUTPUT_PATH/temp" 2>/dev/null || echo "::warning::Could not remove $DIAGRAMS_OUTPUT_PATH/temp"

          # Verify cleanup
          if [ -d "$REFERENCE_OUTPUT_PATH/temp" ]; then
            echo "::error title=Scratch not removed::$REFERENCE_OUTPUT_PATH/temp is still present; refusing to commit it."
            ls -la "$REFERENCE_OUTPUT_PATH/temp"
            exit 1
          fi

          # .gitignore in each output directory keeps CodeWiki scratch out of commits
          for output_dir in "$REFERENCE_OUTPUT_PATH" "$DIAGRAMS_OUTPUT_PATH"; do
            if [ -d "$output_dir" ]; then
              {
                echo "# CodeWiki temp files (dependency graphs can be 7GB+)"
                echo "temp/"
                echo "dependency_graphs/"
                echo ""
                echo "# JSON intermediate files (except schema/config)"
                echo "*.json"
                echo "!*-schema.json"
                echo "!*-config.json"
              } > "$output_dir/.gitignore"
              echo "Wrote $output_dir/.gitignore"
            fi
          done

          echo "::group::Stage 2 output before staging"
          echo "Reference directory ($REFERENCE_OUTPUT_PATH):"
          if [ -d "$REFERENCE_OUTPUT_PATH" ]; then
            find "$REFERENCE_OUTPUT_PATH" -type f \( -name "*.md" -o -name "*.mmd" -o -name ".gitignore" \) | head -20
            FILE_COUNT=$(find "$REFERENCE_OUTPUT_PATH" -type f \( -name "*.md" -o -name "*.mmd" \) | wc -l | tr -d ' ')
            echo ".md/.mmd files: $FILE_COUNT"
          else
            echo "(directory does not exist)"
          fi
          echo "Diagrams directory ($DIAGRAMS_OUTPUT_PATH):"
          if [ -d "$DIAGRAMS_OUTPUT_PATH" ]; then
            find "$DIAGRAMS_OUTPUT_PATH" -type f \( -name "*.md" -o -name "*.mmd" -o -name ".gitignore" \) | head -20
            FILE_COUNT=$(find "$DIAGRAMS_OUTPUT_PATH" -type f \( -name "*.md" -o -name "*.mmd" \) | wc -l | tr -d ' ')
            echo ".md/.mmd files: $FILE_COUNT"
          else
            echo "(directory does not exist)"
          fi
          echo "::endgroup::"

          # The hub-rendered ecosystem.md joins the reference directory only NOW,
          # after the engine has run: placed earlier it makes CodeWiki prompt for
          # an overwrite (see "Fetch ecosystem facts").
          if [ -f /tmp/ecosystem.md ]; then
            mkdir -p "$REFERENCE_OUTPUT_PATH"
            cp /tmp/ecosystem.md "$REFERENCE_OUTPUT_PATH/ecosystem.md"
            echo "Added ecosystem.md to $REFERENCE_OUTPUT_PATH/"
          fi

          # Stage all .md, .mmd, and .gitignore files from Stage 2 output directories
          # CRITICAL: Use git add on full paths to preserve nested directory structure
          # This ensures Backend/Authentication/JWT/JWT.md keeps its full path in git

          # Add only .md, .mmd, .gitignore, and allowed JSON files (*-schema.json, *-config.json)
          # This excludes CodeWiki intermediate files: module_tree.json, first_module_tree.json, metadata.json
          if [ -d "$REFERENCE_OUTPUT_PATH" ]; then
            find "$REFERENCE_OUTPUT_PATH" -type f \( \
              -name "*.md" -o -name "*.mmd" -o -name ".gitignore" \
              -o -name "*-schema.json" -o -name "*-config.json" \
            \) -exec git add {} \; 2>/dev/null || true
            echo "Staged .md/.mmd/.gitignore/*-schema.json/*-config.json under $REFERENCE_OUTPUT_PATH/"
          fi

          if [ -d "$DIAGRAMS_OUTPUT_PATH" ]; then
            find "$DIAGRAMS_OUTPUT_PATH" -type f \( \
              -name "*.md" -o -name "*.mmd" -o -name ".gitignore" \
              -o -name "*-schema.json" -o -name "*-config.json" \
            \) -exec git add {} \; 2>/dev/null || true
            echo "Staged .md/.mmd/.gitignore/*-schema.json/*-config.json under $DIAGRAMS_OUTPUT_PATH/"
          fi

          # AGENTS.md carries the hub-rendered ecosystem block ("Fetch ecosystem
          # facts" upserts it just before this stage). It sits at the repository
          # root, outside every output directory staged above, so it is staged by
          # name: the first production run wrote the block and no commit ever
          # picked the file up (openframe-cli#383).
          if [ -f AGENTS.md ]; then
            git add -f AGENTS.md
            echo "Staged AGENTS.md (ecosystem block)"
          fi
          # CLAUDE.md carries the `@AGENTS.md` import the same step keeps (only when it changed).
          if [ -f CLAUDE.md ] && ! git diff --quiet -- CLAUDE.md; then
            git add -f CLAUDE.md
            echo "   Added CLAUDE.md (@AGENTS.md import)"
          fi

          # Check if there are changes
          STAGED_COUNT=$(git diff --cached --name-only | wc -l)
          echo "Staged files: $STAGED_COUNT"

          if [ "$STAGED_COUNT" -gt 0 ]; then
            echo "::group::Staged stage 2 files (first 30)"
            git diff --cached --name-only | head -30
            echo "::endgroup::"
          fi

          if [ "$STAGED_COUNT" -gt 0 ]; then
            # Commit and push
            git commit -m "docs: Stage 2 - Architecture analysis ($STAGE2_FILES files) [skip ci]"
            git push origin "$BRANCH_NAME"

            echo "Committed and pushed $STAGED_COUNT stage 2 files"
            set_output "committed" "true"
          else
            echo "::error title=Stage 2 output not staged::Stage 2 reported $STAGE2_FILES files but none were staged; the files were generated outside the reference and diagrams directories, or not at all."
            set_output "committed" "false"
          fi

      - name: Update pull request with stage 2 progress
        if: always() && steps.commit-stage2.outputs.committed == 'true' && steps.create-initial-pr.outputs.pull-request-number
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          RUN_ID_VAR: ${{ env.RUN_ID }}
          REPO_NAME: ${{ github.repository }}
        run: |
          source /tmp/workflow-helpers.sh

          # Update PR body
          PR_BODY="## 🦩 Flamingo Code Documentation: In Progress

          **Run ID:** \`$RUN_ID_VAR\`
          **Status:** 🔄 Running...

          This PR is being updated as each documentation stage completes.

          ### Progress
          - ✅ Stage 1: Inline Documentation - Completed ($STAGE1_FILES files)
          - ✅ Stage 2: Architecture Analysis - Completed ($STAGE2_FILES files)
          - ⏳ Stage 3: Tutorial Generation - Running...
          - ⏱️ Stage 4: Repository Documentation - Pending

          ---
          🦩 Generated by [Flamingo Code Documentation](https://flamingo.run)"

          gh pr edit "$PR_NUMBER" --body "$PR_BODY"

          echo "Pull request #$PR_NUMBER updated with stage 2 progress"

      - name: Report stage 2 progress
        if: always() && contains(env.STAGES, 'codewiki') && env.HUB_BASE_URL != ''
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          WORKFLOW_RUN_ID: ${{ github.run_id }}
          WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status || 'skipped' }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          # Use outputs from either CodeWiki (stage2) or Claude alternative (stage2_alt)
          STAGE2_STATUS: ${{ steps.stage2.outputs.stage2_status || steps.stage2_alt.outputs.stage2_status || 'skipped' }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          PR_URL: ${{ steps.create-initial-pr.outputs.pull-request-url }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
        run: |
          source /tmp/workflow-helpers.sh

          CALLBACK_URL="${HUB_BASE_URL}/api/code-documentation/webhook"
          echo "Reporting stage 2 (reference docs): $STAGE2_STATUS, $STAGE2_FILES files"
          report_stage_progress "$CALLBACK_URL" "$WEBHOOK_SECRET" "$RUN_ID" "$REPO_ID" \
            "$WORKFLOW_RUN_ID" "$WORKFLOW_URL" "tutorials" \
            "$STAGE1_STATUS" "$STAGE1_FILES" "$STAGE2_STATUS" "$STAGE2_FILES" "" "0" "" "0" \
            "$PR_URL" "$PR_NUMBER"

      # =========================================================================
      # STAGE 3: TUTORIALS
      # Getting-started guides and how-to tutorials, written by the Code
      # Documentation lane (code-documentation-lib.mjs): one hub call per
      # tutorial with the forced `emit_document` tool and, once the repository's
      # visibility is resolved, the hub's read tools (the code graph and the
      # rules, scoped to what THIS repository may see). No model key here.
      # Generates 4 tutorials: user/getting-started, user/common-use-cases,
      #                        dev/getting-started-dev, dev/architecture-overview-dev
      # =========================================================================
      - name: Install tutorial and repository docs dependencies
        # Stage 3 AND Stage 4 (generate-repo-docs.cjs) share this tree. Gated
        # on either: a repository configured with inline-docs + repo-docs and no
        # tutorials reached Stage 4 with no dependencies at all, run 35302244804.
        if: contains(env.STAGES, 'tutorials') || contains(env.STAGES, 'repo-docs')
        # Isolated deps tree (see Stage 1) - no reconciliation with the target repo.
        # No model SDK: both stages call Claude through the hub.
        run: |
          mkdir -p "$RUNNER_TEMP/doc-orch-deps" && cd "$RUNNER_TEMP/doc-orch-deps"
          npm init -y >/dev/null 2>&1
          npm install zod@3.25.76 glob@13.0.6

      - name: Generate tutorials (stage 3)
        id: stage3
        if: contains(env.STAGES, 'tutorials')
        env:
          # No ANTHROPIC_API_KEY — this stage calls Claude through the hub
          # (/api/ci/claude), which the WEBHOOK_SECRET below authenticates.
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          # Pass through output paths from workflow env (OSS Tenant Structure)
          DOCS_OUTPUT_PATH: ${{ env.DOCS_OUTPUT_PATH }}
          # Stage 2 outputs (for context)
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
          # Stage 3 outputs
          GETTING_STARTED_OUTPUT_PATH: ${{ env.GETTING_STARTED_OUTPUT_PATH }}
          DEVELOPMENT_OUTPUT_PATH: ${{ env.DEVELOPMENT_OUTPUT_PATH }}
          # Claude model SSOT — see workflow env CLAUDE_MODEL block
          CLAUDE_MODEL: ${{ env.CLAUDE_MODEL }}
          # Stage timeout
          STAGE3_TIMEOUT_HOURS: ${{ env.STAGE3_TIMEOUT_HOURS }}
          # Unified file discovery result (same files as Stage 1 and 2)
          SOURCE_FILES_LIST: ${{ steps.discover_files.outputs.source_files_list }}
          # NODE_PATH to find modules from /tmp/ scripts
          NODE_PATH: ${{ runner.temp }}/doc-orch-deps/node_modules
          # YouTube Integration - SECURITY: API key from secrets, NOT dispatch payload
          YOUTUBE_ENABLED: ${{ env.YOUTUBE_ENABLED }}
          YOUTUBE_CHANNELS: ${{ env.YOUTUBE_CHANNELS }}
          YOUTUBE_API_KEY: ${{ secrets.YOUTUBE_API_KEY }}
          # Markdown Validation Rules (injected into prompts)
          VALIDATION_RULES_PATH: ${{ env.VALIDATION_RULES_PATH }}
          # Flamingo Markdown Guidelines (optional)
          GUIDELINES_PATH: ${{ env.GUIDELINES_PATH }}
          # Stage 3 tracking files (configurable paths)
          STAGE3_FILES_TRACKER: ${{ env.STAGE3_FILES_TRACKER }}
          STAGE3_STATS_FILE: ${{ env.STAGE3_STATS_FILE }}
          # Custom AI Instructions (All Stages)
          CUSTOM_REPO_INSTRUCTIONS: ${{ env.CUSTOM_INSTRUCTIONS }}
          # Analysis Exclusions
          EXCLUDED_PATHS: ${{ env.EXCLUDED_PATHS }}
          # External Repositories
          EXTERNAL_REPOS: ${{ env.EXTERNAL_REPOS }}
        run: |
          source /tmp/workflow-helpers.sh

          # Script already downloaded to /tmp/ in setup step. run_stage records
          # the outcome as stage3_status — see its note in workflow-helpers.sh.
          run_stage "Stage 3" "$STAGE3_TIMEOUT_HOURS" stage3_status node /tmp/generate-tutorials-voltagent.cjs

          # Count files from both OSS Tenant Structure directories
          GETTING_STARTED_FILES=$(count_markdown_files "${GETTING_STARTED_OUTPUT_PATH}")
          DEVELOPMENT_FILES=$(count_markdown_files "${DEVELOPMENT_OUTPUT_PATH}")
          TUTORIAL_FILES=$((GETTING_STARTED_FILES + DEVELOPMENT_FILES))
          echo "Tutorials written: $TUTORIAL_FILES ($GETTING_STARTED_FILES getting started, $DEVELOPMENT_FILES development)"
          set_output "stage3_files" "$TUTORIAL_FILES"

      # =========================================================================
      # COMMIT STAGE 3 RESULTS (progressive pull request)
      # =========================================================================
      # `!= ''` — the run_stage commit rule, stated once at Stage 1.
      - name: Commit and push stage 3 results
        if: always() && steps.stage3.outputs.stage3_status != ''
        id: commit-stage3
        env:
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files }}
          GETTING_STARTED_OUTPUT_PATH: ${{ env.GETTING_STARTED_OUTPUT_PATH }}
          DEVELOPMENT_OUTPUT_PATH: ${{ env.DEVELOPMENT_OUTPUT_PATH }}
        run: |
          source /tmp/workflow-helpers.sh

          # .gitignore in each tutorial output directory
          for output_dir in "$GETTING_STARTED_OUTPUT_PATH" "$DEVELOPMENT_OUTPUT_PATH"; do
            if [ -d "$output_dir" ]; then
              {
                echo "# VoltAgent temp files"
                echo "temp/"
                echo ""
                echo "# JSON intermediate files (except schema/config)"
                echo "*.json"
                echo "!*-schema.json"
                echo "!*-config.json"
              } > "$output_dir/.gitignore"
              echo "Wrote $output_dir/.gitignore"
            fi
          done

          # Stage all .md and .gitignore files from Stage 3 output directories
          find "$GETTING_STARTED_OUTPUT_PATH" "$DEVELOPMENT_OUTPUT_PATH" -type f \( -name "*.md" -o -name ".gitignore" \) \
            -exec git add -f {} \; 2>/dev/null || true

          # Check if there are changes
          STAGED_COUNT=$(git diff --cached --name-only | wc -l)

          if [ "$STAGED_COUNT" -gt 0 ]; then
            # Commit and push
            git commit -m "docs: Stage 3 - Tutorial generation ($STAGE3_FILES files) [skip ci]"
            git push origin "$BRANCH_NAME"

            echo "Committed and pushed $STAGED_COUNT stage 3 files"
            set_output "committed" "true"
          else
            echo "::warning title=Stage 3 produced nothing::No tutorials to commit."
            set_output "committed" "false"
          fi

      - name: Update pull request with stage 3 progress
        if: always() && steps.commit-stage3.outputs.committed == 'true' && steps.create-initial-pr.outputs.pull-request-number
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files || 0 }}
          RUN_ID_VAR: ${{ env.RUN_ID }}
          REPO_NAME: ${{ github.repository }}
        run: |
          source /tmp/workflow-helpers.sh

          # Update PR body
          PR_BODY="## 🦩 Flamingo Code Documentation: In Progress

          **Run ID:** \`$RUN_ID_VAR\`
          **Status:** 🔄 Running...

          This PR is being updated as each documentation stage completes.

          ### Progress
          - ✅ Stage 1: Inline Documentation - Completed ($STAGE1_FILES files)
          - ✅ Stage 2: Architecture Analysis - Completed ($STAGE2_FILES files)
          - ✅ Stage 3: Tutorial Generation - Completed ($STAGE3_FILES files)
          - ⏳ Stage 4: Repository Documentation - Running...

          ---
          🦩 Generated by [Flamingo Code Documentation](https://flamingo.run)"

          gh pr edit "$PR_NUMBER" --body "$PR_BODY"

          echo "Pull request #$PR_NUMBER updated with stage 3 progress"

      - name: Report stage 3 progress
        if: always() && contains(env.STAGES, 'tutorials') && env.HUB_BASE_URL != ''
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          WORKFLOW_RUN_ID: ${{ github.run_id }}
          WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status || 'skipped' }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          STAGE2_STATUS: ${{ steps.stage2.outputs.stage2_status || steps.stage2_alt.outputs.stage2_status || 'skipped' }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          STAGE3_STATUS: ${{ steps.stage3.outputs.stage3_status || 'skipped' }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files || 0 }}
          PR_URL: ${{ steps.create-initial-pr.outputs.pull-request-url }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
        run: |
          source /tmp/workflow-helpers.sh

          CALLBACK_URL="${HUB_BASE_URL}/api/code-documentation/webhook"
          echo "Reporting stage 3 (tutorials): $STAGE3_STATUS, $STAGE3_FILES files"
          report_stage_progress "$CALLBACK_URL" "$WEBHOOK_SECRET" "$RUN_ID" "$REPO_ID" \
            "$WORKFLOW_RUN_ID" "$WORKFLOW_URL" "repo-docs" \
            "$STAGE1_STATUS" "$STAGE1_FILES" "$STAGE2_STATUS" "$STAGE2_FILES" "$STAGE3_STATUS" "$STAGE3_FILES" "" "0" \
            "$PR_URL" "$PR_NUMBER"

      # =========================================================================
      # STAGE 4: REPOSITORY DOCS
      # Copies LICENSE.md, SECURITY.md from template repo
      # Generates/updates README.md, CONTRIBUTING.md and the docs index through
      # the Code Documentation lane (one hub call per document, no model key)
      # =========================================================================
      - name: Generate repository docs (stage 4)
        id: stage4
        if: contains(env.STAGES, 'repo-docs')
        env:
          # No ANTHROPIC_API_KEY — this stage calls Claude through the hub.
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          TEMPLATE_REPO: ${{ env.TEMPLATE_REPO }}
          TEMPLATE_BRANCH: ${{ env.TEMPLATE_BRANCH }}
          DOCS_OUTPUT_PATH: ${{ env.DOCS_OUTPUT_PATH }}
          # OSS Tenant Structure: All output paths for docs/README.md navigation
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
          GETTING_STARTED_OUTPUT_PATH: ${{ env.GETTING_STARTED_OUTPUT_PATH }}
          DEVELOPMENT_OUTPUT_PATH: ${{ env.DEVELOPMENT_OUTPUT_PATH }}
          # Claude model SSOT — see workflow env CLAUDE_MODEL block
          CLAUDE_MODEL: ${{ env.CLAUDE_MODEL }}
          STAGE4_TIMEOUT_HOURS: ${{ env.STAGE4_TIMEOUT_HOURS }}
          # NODE_PATH to find modules from /tmp/ scripts
          NODE_PATH: ${{ runner.temp }}/doc-orch-deps/node_modules
          # YouTube Integration - SECURITY: API key from secrets, NOT dispatch payload
          YOUTUBE_ENABLED: ${{ env.YOUTUBE_ENABLED }}
          YOUTUBE_CHANNELS: ${{ env.YOUTUBE_CHANNELS }}
          YOUTUBE_API_KEY: ${{ secrets.YOUTUBE_API_KEY }}
          # Markdown Validation Rules (injected into prompts)
          VALIDATION_RULES_PATH: ${{ env.VALIDATION_RULES_PATH }}
          # Flamingo Markdown Guidelines (optional)
          GUIDELINES_PATH: ${{ env.GUIDELINES_PATH }}
          # Stage 4 tracking files (configurable paths)
          STAGE4_FILES_TRACKER: ${{ env.STAGE4_FILES_TRACKER }}
          # Custom AI Instructions (All Stages)
          CUSTOM_REPO_INSTRUCTIONS: ${{ env.CUSTOM_INSTRUCTIONS }}
          # Analysis Exclusions
          EXCLUDED_PATHS: ${{ env.EXCLUDED_PATHS }}
          # External Repositories
          EXTERNAL_REPOS: ${{ env.EXTERNAL_REPOS }}
          # README Branding
          README_LOGO_DARK: ${{ env.README_LOGO_DARK }}
          README_LOGO_LIGHT: ${{ env.README_LOGO_LIGHT }}
          README_LOGO_ALT: ${{ env.README_LOGO_ALT }}
        run: |
          source /tmp/workflow-helpers.sh

          echo "Template repository: $TEMPLATE_REPO@$TEMPLATE_BRANCH"

          RAW_URL="https://raw.githubusercontent.com/$TEMPLATE_REPO/$TEMPLATE_BRANCH"

          # 1. LICENSE.md and SECURITY.md from the template repository
          if curl -fsSL "$RAW_URL/LICENSE.md" -o LICENSE.md 2>/dev/null; then
            echo "Copied LICENSE.md from the template repository"
          else
            echo "::notice title=LICENSE.md not copied::The template repository $TEMPLATE_REPO@$TEMPLATE_BRANCH has no LICENSE.md."
          fi

          if curl -fsSL "$RAW_URL/SECURITY.md" -o SECURITY.md 2>/dev/null; then
            echo "Copied SECURITY.md from the template repository"
          else
            echo "::notice title=SECURITY.md not copied::The template repository $TEMPLATE_REPO@$TEMPLATE_BRANCH has no SECURITY.md."
          fi

          # 2. The existing README is context for the new one
          if [ -f "README.md" ]; then
            README_SIZE=$(wc -c < README.md | tr -d ' ')
            echo "Existing README.md: $README_SIZE bytes (used as context)"
          else
            echo "Existing README.md: none"
          fi

          # 3. README, CONTRIBUTING and the docs index, one hub call each.
          # Script already downloaded to /tmp/ in "Download pipeline scripts"
          # run_stage records the outcome as stage4_status — see its note in
          # workflow-helpers.sh. The file count below is REPORTING, not a
          # status: inferring "completed" from it meant a crashed run that left
          # a previous commit's README standing reported success.
          run_stage "Stage 4" "$STAGE4_TIMEOUT_HOURS" stage4_status node /tmp/generate-repo-docs.cjs

          # 4. Count results
          REPO_DOCS=0
          for f in README.md CONTRIBUTING.md LICENSE.md SECURITY.md; do
            if [ -f "$f" ]; then
              SIZE=$(wc -c < "$f" | tr -d ' ')
              echo "$f: $SIZE bytes"
              REPO_DOCS=$((REPO_DOCS + 1))
            fi
          done

          set_output "stage4_files" "$REPO_DOCS"
          if [ "$REPO_DOCS" -gt 0 ]; then
            echo "Repository docs present: $REPO_DOCS"
          else
            echo "::warning title=Stage 4 produced nothing::No repository docs (README.md, CONTRIBUTING.md, LICENSE.md, SECURITY.md) are present."
          fi

      # =========================================================================
      # COMMIT STAGE 4 RESULTS (progressive pull request)
      # =========================================================================
      # `!= ''` — the run_stage commit rule, stated once at Stage 1.
      - name: Commit and push stage 4 results
        if: always() && steps.stage4.outputs.stage4_status != ''
        id: commit-stage4
        env:
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          STAGE4_FILES: ${{ steps.stage4.outputs.stage4_files }}
        run: |
          source /tmp/workflow-helpers.sh

          # .gitignore in each stage 4 managed directory
          for managed_dir in docs/api docs/deployment docs/operations docs/cli; do
            if [ -d "$managed_dir" ]; then
              {
                echo "# VoltAgent temp files"
                echo "temp/"
                echo ""
                echo "# JSON intermediate files (except schema/config)"
                echo "*.json"
                echo "!*-schema.json"
                echo "!*-config.json"
              } > "$managed_dir/.gitignore"
              echo "Wrote $managed_dir/.gitignore"
            fi
          done

          # Stage repository documentation files
          # AGENTS.md (and CLAUDE.md's @AGENTS.md import) are here as the backstop for a run whose Stage 2 commit did not happen.
          for f in README.md CONTRIBUTING.md LICENSE.md SECURITY.md AGENTS.md CLAUDE.md; do
            if [ -f "$f" ]; then
              git add -f "$f"
            fi
          done

          # Stage Stage 4 managed directories
          for managed_dir in docs/api docs/deployment docs/operations docs/cli; do
            if [ -d "$managed_dir" ]; then
              git add -f "$managed_dir/" 2>/dev/null || true
            fi
          done

          # Stage docs/README.md if exists
          if [ -f "docs/README.md" ]; then
            git add -f "docs/README.md"
          fi

          # Check if there are changes
          STAGED_COUNT=$(git diff --cached --name-only | wc -l)

          if [ "$STAGED_COUNT" -gt 0 ]; then
            # Commit and push
            git commit -m "docs: Stage 4 - Repository documentation ($STAGE4_FILES files) [skip ci]"
            git push origin "$BRANCH_NAME"

            echo "Committed and pushed $STAGED_COUNT stage 4 files"
            set_output "committed" "true"
          else
            echo "No stage 4 changes to commit"
            set_output "committed" "false"
          fi

      - name: Update pull request with stage 4 progress
        if: always() && steps.commit-stage4.outputs.committed == 'true' && steps.create-initial-pr.outputs.pull-request-number
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files || 0 }}
          STAGE4_FILES: ${{ steps.stage4.outputs.stage4_files || 0 }}
          RUN_ID_VAR: ${{ env.RUN_ID }}
          REPO_NAME: ${{ github.repository }}
        run: |
          source /tmp/workflow-helpers.sh

          # Update PR body
          PR_BODY="## 🦩 Flamingo Code Documentation: In Progress

          **Run ID:** \`$RUN_ID_VAR\`
          **Status:** 🔄 Running...

          This PR is being updated as each documentation stage completes.

          ### Progress
          - ✅ Stage 1: Inline Documentation - Completed ($STAGE1_FILES files)
          - ✅ Stage 2: Architecture Analysis - Completed ($STAGE2_FILES files)
          - ✅ Stage 3: Tutorial Generation - Completed ($STAGE3_FILES files)
          - ✅ Stage 4: Repository Documentation - Completed ($STAGE4_FILES files)

          ---
          🦩 Generated by [Flamingo Code Documentation](https://flamingo.run)"

          gh pr edit "$PR_NUMBER" --body "$PR_BODY"

          echo "Pull request #$PR_NUMBER updated with stage 4 progress"

      # =========================================================================
      # VALIDATE GENERATED MARKDOWN
      # Warn-only validation (never blocks the pull request)
      # =========================================================================
      - name: Validate generated Markdown
        if: always()
        continue-on-error: true  # NEVER block PR - validation is warn-only
        env:
          DOCS_OUTPUT_DIR: ${{ env.DOCS_OUTPUT_PATH }}
          # OSS Tenant Structure paths for validation
          REFERENCE_OUTPUT_PATH: ${{ env.REFERENCE_OUTPUT_PATH }}
          DIAGRAMS_OUTPUT_PATH: ${{ env.DIAGRAMS_OUTPUT_PATH }}
          GETTING_STARTED_OUTPUT_PATH: ${{ env.GETTING_STARTED_OUTPUT_PATH }}
          DEVELOPMENT_OUTPUT_PATH: ${{ env.DEVELOPMENT_OUTPUT_PATH }}
          NODE_PATH: ${{ runner.temp }}/doc-orch-deps/node_modules
        run: |
          # Warn-only: findings are logged per directory and never fail the run.
          echo "::group::Validate $DOCS_OUTPUT_DIR"
          node /tmp/validate-markdown.js "$DOCS_OUTPUT_DIR" 2>&1 || true
          echo "::endgroup::"
          # Validate OSS Tenant Structure outputs
          echo "::group::Validate $REFERENCE_OUTPUT_PATH"
          node /tmp/validate-markdown.js "$REFERENCE_OUTPUT_PATH" 2>&1 || true
          echo "::endgroup::"
          echo "::group::Validate $GETTING_STARTED_OUTPUT_PATH"
          node /tmp/validate-markdown.js "$GETTING_STARTED_OUTPUT_PATH" 2>&1 || true
          echo "::endgroup::"
          echo "::group::Validate $DEVELOPMENT_OUTPUT_PATH"
          node /tmp/validate-markdown.js "$DEVELOPMENT_OUTPUT_PATH" 2>&1 || true
          echo "::endgroup::"

      - name: Report stage 4 progress
        if: always() && env.HUB_BASE_URL != ''
        continue-on-error: true
        env:
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          WORKFLOW_RUN_ID: ${{ github.run_id }}
          WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status || 'skipped' }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          STAGE2_STATUS: ${{ steps.stage2.outputs.stage2_status || steps.stage2_alt.outputs.stage2_status || 'skipped' }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          STAGE3_STATUS: ${{ steps.stage3.outputs.stage3_status || 'skipped' }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files || 0 }}
          STAGE4_STATUS: ${{ steps.stage4.outputs.stage4_status || 'skipped' }}
          STAGE4_FILES: ${{ steps.stage4.outputs.stage4_files || 0 }}
          PR_URL: ${{ steps.create-initial-pr.outputs.pull-request-url }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
        run: |
          source /tmp/workflow-helpers.sh

          CALLBACK_URL="${HUB_BASE_URL}/api/code-documentation/webhook"
          echo "Reporting stage 4 (repository docs): $STAGE4_STATUS, $STAGE4_FILES files"
          report_stage_progress "$CALLBACK_URL" "$WEBHOOK_SECRET" "$RUN_ID" "$REPO_ID" \
            "$WORKFLOW_RUN_ID" "$WORKFLOW_URL" "creating-pr" \
            "$STAGE1_STATUS" "$STAGE1_FILES" "$STAGE2_STATUS" "$STAGE2_FILES" "$STAGE3_STATUS" "$STAGE3_FILES" \
            "$STAGE4_STATUS" "$STAGE4_FILES" "$PR_URL" "$PR_NUMBER"

      # =========================================================================
      # FINALIZE THE PULL REQUEST
      # =========================================================================
      - name: Clean up temporary files
        run: |
          source /tmp/workflow-helpers.sh

          # Remove stats files
          cleanup_path ".doc-stage1-stats.json"
          cleanup_path ".doc-stage3-stats.json"

          # Remove run status file (created for the initial PR).
          # Legacy name kept so branches started before the rename still clean up.
          cleanup_path ".flamingo-ai-technical-writer-status.md"
          cleanup_path ".doc-pipeline-status.md"

          # Note: .code-documentation-source-files.txt is now in /tmp/ (auto-cleanup)

          # Remove npm artifacts (installed for scripts)
          cleanup_path "node_modules"
          cleanup_path "package.json"
          cleanup_path "package-lock.json"

          # NOTE: /tmp/workflow-helpers.sh is removed by "Report run result"

      - name: Stage remaining docs and detect changes
        id: stage-docs
        run: |
          source /tmp/workflow-helpers.sh
          echo "Docs root: $DOCS_OUTPUT_PATH"
          echo "Stage 2:   $REFERENCE_OUTPUT_PATH (reference), $DIAGRAMS_OUTPUT_PATH (diagrams)"
          echo "Stage 3:   $GETTING_STARTED_OUTPUT_PATH (getting started), $DEVELOPMENT_OUTPUT_PATH (development)"

          # Count untracked/modified files before staging
          BEFORE_COUNT=$(git status --porcelain | wc -l)
          echo "Changed files in the working tree: $BEFORE_COUNT"

          # Stage ALL .md and .mmd files anywhere in the repo (for inline docs generated next to source files)
          # This catches Stage 1 inline docs (hidden: .FileName.md), Stage 2 reference/diagrams, Stage 3 tutorials, and Stage 4 repo docs
          # Find all .md and .mmd files recursively, including hidden files (.*.md)
          # Includes README.md, CONTRIBUTING.md, LICENSE.md, SECURITY.md from Stage 4
          # Includes .mmd Mermaid diagram files from Stage 2 (CodeWiki/Claude architecture)
          find . \( -name "*.md" -o -name ".*.md" -o -name "*.mmd" \) -type f \
            -not -path "./node_modules/*" \
            -not -path "./.git/*" \
            -not -name "CHANGELOG.md" \
            -exec git add -f {} \; 2>/dev/null || true

          echo "::group::Markdown and Mermaid files in the checkout (first 100)"
          find . \( -name "*.md" -o -name ".*.md" -o -name "*.mmd" \) -type f \
            -not -path "./node_modules/*" \
            -not -path "./.git/*" \
            -not -name "CHANGELOG.md" | head -100
          echo "::endgroup::"

          # Count staged files
          STAGED_COUNT=$(git diff --cached --name-only | wc -l)
          echo "Staged files: $STAGED_COUNT"
          set_output "staged_count" "$STAGED_COUNT"

          echo "::group::Staged files (first 50)"
          git diff --cached --name-only | head -50
          echo "::endgroup::"

          # "Changes" means the BRANCH differs from the documented source head, not
          # that this final sweep found something left to stage: every stage commits
          # its own output as it goes, so a run whose stages all committed (inline
          # docs, README) left nothing here and was reported as no_changes while its
          # pull request held twenty files (openframe-saas-mobile run 35302244804).
          # The status file is the run's own bookkeeping, never a documentation change.
          if [ "$STAGED_COUNT" -eq "0" ] && git diff --quiet "$SOURCE_HEAD_SHA" HEAD -- . ':!.flamingo-ai-technical-writer-status.md'; then
            echo "::notice title=No documentation changes::Nothing left to stage, and the branch holds no documentation change against the source head."
            set_output "has_changes" "false"
          else
            set_output "has_changes" "true"
          fi

      - name: Mark pull request complete
        if: steps.create-initial-pr.outputs.pull-request-number
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number }}
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status || 'skipped' }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          STAGE2_STATUS: ${{ steps.stage2.outputs.stage2_status || steps.stage2_alt.outputs.stage2_status || 'skipped' }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          STAGE3_STATUS: ${{ steps.stage3.outputs.stage3_status || 'skipped' }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files || 0 }}
          STAGE4_STATUS: ${{ steps.stage4.outputs.stage4_status || 'skipped' }}
          STAGE4_FILES: ${{ steps.stage4.outputs.stage4_files || 0 }}
          RUN_ID_VAR: ${{ env.RUN_ID }}
          REPO_NAME: ${{ github.repository }}
        run: |
          source /tmp/workflow-helpers.sh

          # Remove "in-progress" label
          gh pr edit "$PR_NUMBER" --remove-label "in-progress" || true

          # Update title to remove [IN PROGRESS]
          gh pr edit "$PR_NUMBER" --title "🦩 Flamingo Code Documentation"

          # Update body with final results
          PR_BODY="## 🦩 Flamingo Code Documentation: Complete

          **Run ID:** \`$RUN_ID_VAR\`

          ### Stage 1: Inline Documentation
          - Status: $STAGE1_STATUS
          - Files generated: $STAGE1_FILES
          - Generated .md files next to source classes explaining their purpose

          ### Stage 2: Architecture Analysis
          - Status: $STAGE2_STATUS
          - Files generated: $STAGE2_FILES
          - Architecture overview and module documentation

          ### Stage 3: AI Tutorial Generator
          - Status: $STAGE3_STATUS
          - Files generated: $STAGE3_FILES
          - Getting started guides and how-to tutorials

          ### Stage 4: Repository Documentation
          - Status: $STAGE4_STATUS
          - Files generated: $STAGE4_FILES
          - README.md, CONTRIBUTING.md, LICENSE.md, SECURITY.md

          ---

          **Review checklist:**
          - [ ] Check generated inline docs for accuracy
          - [ ] Review architecture documentation
          - [ ] Test code examples in tutorials
          - [ ] Review README.md and CONTRIBUTING.md updates

          ---
          🦩 Generated by [Flamingo Code Documentation](https://flamingo.run)"

          gh pr edit "$PR_NUMBER" --body "$PR_BODY"

          echo "Pull request #$PR_NUMBER marked complete"

      # =========================================================================
      # REPORT RUN RESULT: the terminal callback. Never reports "running".
      # =========================================================================
      - name: Report run result
        if: always() && env.HUB_BASE_URL != ''
        continue-on-error: true  # Don't fail the workflow if callback fails
        env:
          # SECURITY: Pass secret per-step with inline masking
          WEBHOOK_SECRET: ${{ secrets.FLAMINGO_HUB_SECRET }}
          WORKFLOW_RUN_ID: ${{ github.run_id }}
          WORKFLOW_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
          HAS_CHANGES: ${{ steps.stage-docs.outputs.has_changes }}
          JOB_STATUS: ${{ job.status }}
          PR_URL: ${{ steps.create-initial-pr.outputs.pull-request-url }}
          PR_NUMBER: ${{ steps.create-initial-pr.outputs.pull-request-number || 'null' }}
          SAFE_RUN_ID: ${{ steps.branch-name-early.outputs.safe_run_id }}
          # Single source of truth for the branch name (was rebuilt by hand below,
          # which silently drifted from "Create docs branch" on every rename)
          BRANCH_NAME: ${{ steps.create-pr-branch.outputs.branch_name }}
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status || 'skipped' }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || 0 }}
          # Stage 2: Check both CodeWiki and Claude alternative, mark as failed if step failed
          STAGE2_STATUS: ${{ steps.stage2.outcome == 'failure' && 'failed' || steps.stage2_alt.outcome == 'failure' && 'failed' || steps.stage2.outputs.stage2_status || steps.stage2_alt.outputs.stage2_status || 'skipped' }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || 0 }}
          STAGE3_STATUS: ${{ steps.stage3.outputs.stage3_status || 'skipped' }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files || 0 }}
          STAGE4_STATUS: ${{ steps.stage4.outputs.stage4_status || 'skipped' }}
          STAGE4_FILES: ${{ steps.stage4.outputs.stage4_files || 0 }}
          # Track if critical steps failed (continue-on-error: false steps)
          STAGE2_OUTCOME: ${{ steps.stage2.outcome || 'skipped' }}
          CODEWIKI_INSTALL_OUTCOME: ${{ steps.codewiki_install.outcome || 'skipped' }}
          CODEWIKI_CONFIG_OUTCOME: ${{ steps.codewiki_config.outcome || 'skipped' }}
        run: |
          # Bootstrap-failure fallback (shared failure-net standard with the
          # code-review workflow): if workflow-helpers.sh never downloaded, no
          # helper exists to report the failure — a minimal guarded curl posts
          # it so the hub's run row fails NOW instead of waiting for the reaper.
          if [ ! -f /tmp/workflow-helpers.sh ]; then
            echo "::error title=Script bootstrap failed::workflow-helpers.sh was never downloaded from the hub; reporting the failure with a minimal callback."
            # The bearer goes through a 0600 config file, never argv — see
            # curlAuthPreamble in lib/config/workflow-scripts-bootstrap.ts.
            CURL_CFG=$(mktemp) && chmod 600 "$CURL_CFG"
            trap 'rm -f "$CURL_CFG"' EXIT
            printf 'header = "Authorization: Bearer %s"\n' "$WEBHOOK_SECRET" > "$CURL_CFG"
            curl -sS --max-time 30 -K "$CURL_CFG" -X POST "${HUB_BASE_URL}/api/code-documentation/webhook" \
              -H "Content-Type: application/json" \
              -d "{\"run_id\":\"$RUN_ID\",\"repo_id\":\"$REPO_ID\",\"status\":\"failure\",\"workflow_run_id\":$WORKFLOW_RUN_ID,\"workflow_url\":\"$WORKFLOW_URL\",\"error\":\"Script bootstrap failed: workflow-helpers.sh never downloaded from the hub.\"}" || true
            exit 1
          fi
          source /tmp/workflow-helpers.sh

          CALLBACK_URL="${HUB_BASE_URL}/api/code-documentation/webhook"

          echo "::group::Inputs to the final status"
          echo "JOB_STATUS=$JOB_STATUS"
          echo "HAS_CHANGES=$HAS_CHANGES"
          echo "STAGE2_OUTCOME=$STAGE2_OUTCOME"
          echo "CODEWIKI_INSTALL_OUTCOME=$CODEWIKI_INSTALL_OUTCOME"
          echo "CODEWIKI_CONFIG_OUTCOME=$CODEWIKI_CONFIG_OUTCOME"
          echo "::endgroup::"

          # CRITICAL: Determine final status - NEVER return "running"
          # Default to failure, only set success if everything checks out
          STATUS="failure"

          # Check for cancelled job first
          if [ "$JOB_STATUS" = "cancelled" ]; then
            STATUS="cancelled"
            REASON="the workflow run was cancelled"
          # Check if critical stage 2 (CodeWiki) failed - this has continue-on-error: false
          elif [ "$STAGE2_OUTCOME" = "failure" ]; then
            STATUS="failure"
            REASON="the CodeWiki stage failed"
          # Check if CodeWiki installation failed
          elif [ "$CODEWIKI_INSTALL_OUTCOME" = "failure" ]; then
            STATUS="failure"
            REASON="the CodeWiki installation failed"
          # Check if CodeWiki configuration failed
          elif [ "$CODEWIKI_CONFIG_OUTCOME" = "failure" ]; then
            STATUS="failure"
            REASON="the CodeWiki configuration failed"
          # Check overall job status
          elif [ "$JOB_STATUS" != "success" ]; then
            STATUS="failure"
            REASON="the job status is $JOB_STATUS"
          # A requested stage that FAILED fails the run, whatever the others wrote:
          # a run whose stages 3 and 4 wrote nothing used to report success because
          # stage 2 had committed reference docs.
          elif FAILED_STAGES=$(for n in 1 2 3 4; do v="STAGE${n}_STATUS"; [ "${!v}" = "failed" ] && printf 'stage %s, ' "$n"; done) && [ -n "$FAILED_STAGES" ]; then
            STATUS="failure"
            REASON="${FAILED_STAGES%, } failed"
          # Check if we have any documentation changes
          elif [ "$HAS_CHANGES" != "true" ]; then
            STATUS="no_changes"
            REASON="no documentation changed"
          else
            STATUS="success"
            REASON="documentation generated"
          fi

          # SAFETY CHECK: Ensure status is NEVER "running"
          if [ "$STATUS" = "running" ] || [ -z "$STATUS" ]; then
            echo "::warning::Computed status '$STATUS' is not terminal; reporting failure instead."
            STATUS="failure"
            REASON="no terminal status could be determined"
          fi

          case "$STATUS" in
            success)    echo "Final status: success ($REASON)" ;;
            no_changes) echo "::notice title=Code Documentation: no changes::Final status: no_changes ($REASON)." ;;
            cancelled)  echo "::warning title=Code Documentation: cancelled::Final status: cancelled ($REASON)." ;;
            *)          echo "::error title=Code Documentation: $STATUS::Final status: $STATUS ($REASON)." ;;
          esac

          # Branch actually created by "Create docs branch". Falls back to the same
          # formula only when that step never ran (this step is `if: always()`).
          SAFE_BRANCH="${BRANCH_NAME:-${DOCS_BRANCH_PREFIX}$SAFE_RUN_ID}"

          # Send final webhook using helper function
          report_final_status "$CALLBACK_URL" "$WEBHOOK_SECRET" "$RUN_ID" "$REPO_ID" \
            "$WORKFLOW_RUN_ID" "$WORKFLOW_URL" "$STATUS" "$PR_URL" "$PR_NUMBER" "$SAFE_BRANCH" \
            "$STAGE1_STATUS" "$STAGE1_FILES" "$STAGE2_STATUS" "$STAGE2_FILES" "$STAGE3_STATUS" "$STAGE3_FILES" \
            "$STAGE4_STATUS" "$STAGE4_FILES"

          # Final cleanup: remove workflow helpers file
          cleanup_path "/tmp/workflow-helpers.sh"

      # The run's job summary (the Actions run page). Values reach the script
      # through env, never inline expressions.
      - name: Write job summary
        if: always()
        env:
          STAGE1_STATUS: ${{ steps.stage1.outputs.stage1_status || 'skipped' }}
          STAGE1_FILES: ${{ steps.stage1.outputs.stage1_files || '0' }}
          STAGE2_STATUS: ${{ steps.stage2.outputs.stage2_status || steps.stage2_alt.outputs.stage2_status || 'skipped' }}
          STAGE2_FILES: ${{ steps.stage2.outputs.stage2_files || steps.stage2_alt.outputs.stage2_files || '0' }}
          STAGE2_ENGINE: ${{ steps.detect_language.outputs.codewiki_supported == 'true' && 'CodeWiki' || steps.detect_language.outputs.codewiki_supported == 'false' && 'Claude' || 'engine not chosen' }}
          STAGE3_STATUS: ${{ steps.stage3.outputs.stage3_status || 'skipped' }}
          STAGE3_FILES: ${{ steps.stage3.outputs.stage3_files || '0' }}
          STAGE4_STATUS: ${{ steps.stage4.outputs.stage4_status || 'skipped' }}
          STAGE4_FILES: ${{ steps.stage4.outputs.stage4_files || '0' }}
          GRAPH_OUTCOME: ${{ steps.graph.outcome || 'skipped' }}
          PRIMARY_LANGUAGE: ${{ steps.detect_language.outputs.primary_language }}
          PR_URL: ${{ steps.create-initial-pr.outputs.pull-request-url }}
        run: |
          {
            echo "## 🦩 Flamingo Code Documentation"
            echo ""
            echo "Run \`$RUN_ID\` · source branch \`$SOURCE_BRANCH\` · primary language ${PRIMARY_LANGUAGE:-unknown}"
            echo ""
            echo "| Stage | Status | Files |"
            echo "|-------|--------|-------|"
            echo "| 0 · Code graph | $GRAPH_OUTCOME | – |"
            echo "| 1 · Inline docs | $STAGE1_STATUS | $STAGE1_FILES |"
            echo "| 2 · Reference docs ($STAGE2_ENGINE) | $STAGE2_STATUS | $STAGE2_FILES |"
            echo "| 3 · Tutorials | $STAGE3_STATUS | $STAGE3_FILES |"
            echo "| 4 · Repository docs | $STAGE4_STATUS | $STAGE4_FILES |"
            echo ""
            if [ -n "$PR_URL" ]; then
              echo "**Pull request:** $PR_URL"
            else
              echo "No pull request was opened."
            fi
          } >> "$GITHUB_STEP_SUMMARY"