From 765d2f63428654e299ede561ce155f12a68f385a Mon Sep 17 00:00:00 2001
From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com>
Date: Wed, 8 Jul 2026 16:59:25 -0400
Subject: [PATCH 1/2] ci: run the docs pipeline only when the API spec changes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add .github/workflows/docs-pipeline.yml. It triggers on pushes to main that
touch the API spec (openapi.yaml/json, voice.asyncapi.yaml/json) — plus manual
workflow_dispatch. No schedule/cron: a spec change is the sole automatic entry
point. Runs `pipeline/run.py generate`, which chains
detect → generate → evaluate → review → promote → ship → post_review and opens a
docs PR (ship gets --yes automatically). Requires an ANTHROPIC_API_KEY secret.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 .github/workflows/docs-pipeline.yml | 78 +++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)
 create mode 100644 .github/workflows/docs-pipeline.yml

diff --git a/.github/workflows/docs-pipeline.yml b/.github/workflows/docs-pipeline.yml
new file mode 100644
index 00000000..fb1530cb
--- /dev/null
+++ b/.github/workflows/docs-pipeline.yml
@@ -0,0 +1,78 @@
+name: Docs Pipeline
+
+# Kick off the agentic docs pipeline ONLY when the API spec changes on main.
+# A spec change is the signal that the docs may now be missing or stale, so the
+# pipeline detects gaps, drafts + reviews the missing content, and opens a PR.
+# There is deliberately no schedule/cron trigger — spec change is the only
+# automatic entry point. (workflow_dispatch is a manual escape hatch.)
+on:
+  push:
+    branches: [main]
+    paths:
+      - "api-reference/openapi.yaml"
+      - "api-reference/openapi.json"
+      - "api-reference/voice/voice.asyncapi.yaml"
+      - "api-reference/voice/voice.asyncapi.json"
+  workflow_dispatch:
+    inputs:
+      section:
+        description: "Limit to one product family (optional, e.g. voice)"
+        required: false
+        default: ""
+      dry_run:
+        description: "Rehearse: run every step but do not open a PR"
+        type: boolean
+        default: false
+
+# Two pipeline runs at once would race on branches and PRs.
+concurrency:
+  group: docs-pipeline
+  cancel-in-progress: false
+
+permissions:
+  contents: write # create the branch + commit the drafts
+  pull-requests: write # open the PR
+
+jobs:
+  run:
+    name: Detect gaps, generate, review, open PR
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0 # ship.py branches off main; needs history
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: pip install anthropic pyyaml
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Run the docs pipeline
+        env:
+          # Required — add this secret in repo Settings → Secrets → Actions.
+          # The pipeline can't call Claude without it.
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+          # ship.py / post_review.py use the gh CLI, which reads GH_TOKEN.
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          ARGS="generate"
+          if [ -n "${{ github.event.inputs.section }}" ]; then
+            ARGS="$ARGS --section ${{ github.event.inputs.section }}"
+          fi
+          if [ "${{ github.event.inputs.dry_run }}" = "true" ]; then
+            ARGS="$ARGS --dry-run"
+          fi
+          echo "Running: python pipeline/run.py $ARGS"
+          # run.py chains detect→generate→evaluate→review→promote→ship→post_review
+          # and auto-passes --yes to ship (non-dry-run), so this opens a PR.
+          python pipeline/run.py $ARGS

From d19db440e1957d6a0f5605e41c62e2f995943e66 Mon Sep 17 00:00:00 2001
From: Shir Goldberg <3937986+shirgoldbird@users.noreply.github.com>
Date: Wed, 8 Jul 2026 17:03:46 -0400
Subject: [PATCH 2/2] ci: watch only the YAML specs (JSON is generated from
 them)

The .json specs are auto-generated from the .yaml sources on the PR and merge
in the same commit, so watching the YAML sources alone catches every spec
change without any chance of a double trigger.
---
 .github/workflows/docs-pipeline.yml | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/docs-pipeline.yml b/.github/workflows/docs-pipeline.yml
index fb1530cb..a21b98e8 100644
--- a/.github/workflows/docs-pipeline.yml
+++ b/.github/workflows/docs-pipeline.yml
@@ -8,11 +8,12 @@ name: Docs Pipeline
 on:
   push:
     branches: [main]
+    # Watch only the YAML sources. The .json specs are auto-generated from these
+    # (see update_openapi_json.yml) and merge in the same commit, so watching the
+    # YAML alone catches every real spec change and can't double-fire.
     paths:
       - "api-reference/openapi.yaml"
-      - "api-reference/openapi.json"
       - "api-reference/voice/voice.asyncapi.yaml"
-      - "api-reference/voice/voice.asyncapi.json"
   workflow_dispatch:
     inputs:
       section: