chore: import upstream snapshot with attribution

.github/workflows/docs-preview.yml

@@ -0,0 +1,106 @@
+name: Docs Preview
+
+# Label-triggered docs preview. Adding `trigger:docs` to a PR dispatches a
+# preview build to pydantic/unified-docs; that repo builds the unified docs
+# against this PR's head SHA, deploys to a shared Cloudflare Worker, and
+# updates a comment on this PR with the preview URL.
+#
+# This workflow is purely a dispatcher — the build, deploy, and final
+# URL-comment all happen in the unified-docs repo. The `trigger:docs` label
+# is removed at the end so re-adding it re-runs the preview.
+
+on:
+  # zizmor: ignore[dangerous-triggers] -- pull_request_target is required so fork PRs can
+  # access the DOCS_APP credentials. The dispatch is gated on a maintainer adding the
+  # `trigger:docs` label, and this workflow does not check out or execute PR code.
+  pull_request_target:
+    types: [labeled]
+
+permissions: {}
+
+concurrency:
+  group: docs-preview-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  dispatch:
+    if: github.event.label.name == 'trigger:docs'
+    runs-on: ubuntu-latest
+    permissions:
+      # Needed to post the "queued" comment and to remove the trigger:docs label.
+      pull-requests: write
+
+    steps:
+      - name: Generate app token (for dispatching to unified-docs)
+        id: app-token
+        uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+        with:
+          app-id: ${{ vars.DOCS_APP_ID }}
+          private-key: ${{ secrets.DOCS_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+          repositories: unified-docs
+
+      - name: Dispatch preview build
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          REPO: ${{ github.repository }}
+        run: |
+          gh api repos/pydantic/unified-docs/dispatches \
+            --method POST \
+            -f event_type=docs-preview \
+            -f "client_payload[library]=ai" \
+            -f "client_payload[source_repo]=${REPO}" \
+            -f "client_payload[source_pr]=${PR_NUMBER}" \
+            -f "client_payload[source_sha]=${HEAD_SHA}"
+
+      - name: Acknowledge on PR
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          REPO: ${{ github.repository }}
+        run: |
+          sha7=$(echo "$HEAD_SHA" | cut -c1-7)
+          body=$(cat <<EOF
+          ## Docs Preview — queued
+
+          The preview build for commit \`${sha7}\` has been dispatched to [pydantic/unified-docs](https://github.com/pydantic/unified-docs/actions/workflows/docs-preview.yml). This comment will be updated with the preview URL once the build completes.
+          EOF
+          )
+
+          # Update an existing "Docs Preview" comment if present (covers re-runs); otherwise post a new one.
+          existing=$(gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" \
+            --jq '[.[] | select(.user.login == "github-actions[bot]" and (.body | startswith("## Docs Preview")))][0].url // empty')
+          if [ -n "$existing" ]; then
+            gh api -X PATCH "$existing" -f body="$body"
+          else
+            gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" -f body="$body"
+          fi
+
+      - name: Comment failure on PR
+        if: failure()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          body=$(cat <<EOF
+          ## Docs Preview — dispatch failed
+
+          The dispatch to pydantic/unified-docs failed. See [the workflow run](${RUN_URL}) for details.
+
+          <sub>Re-add the \`trigger:docs\` label to retry.</sub>
+          EOF
+          )
+          gh api "repos/${REPO}/issues/${PR_NUMBER}/comments" -f body="$body"
+
+      - name: Remove trigger:docs label
+        if: always()
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ github.event.pull_request.number }}
+          REPO: ${{ github.repository }}
+        run: gh api -X DELETE "repos/${REPO}/issues/${PR_NUMBER}/labels/trigger:docs" || true