pipecatcloud 1.2.0__tar.gz → 1.3.0__tar.gz

pipecatcloud-1.3.0/.claude/skills/update-docs/SOURCE_DOC_MAPPING.md

@@ -0,0 +1,201 @@
+# Source-to-Doc Mapping — pipecatcloud
+
+The profile for the shared `update-docs` skill, which lives in
+`pipecat-ai/pipecat` at `.claude/skills/update-docs/SKILL.md` and is published
+through the `pipecat-dev-skills` marketplace. `PROFILE_CONTRACT.md` beside it
+describes what this file has to provide.
+
+Most of what this package ships is a **command-line surface**, so the mapping is
+dominated by command-group-to-page rules rather than the class-to-page rules a
+library profile would use.
+
+## Scope
+
+Every `.py` file under `src/pipecatcloud/` is in scope. The package ships two
+public surfaces — the `pipecat cloud` CLI and the Python SDK — and both are
+documented.
+
+Exclude only:
+
+- `tests/**`
+- `__pycache__/`, `*.pyc`, `py.typed`
+- `src/pipecatcloud/__version__.py`
+
+Changes outside `src/pipecatcloud/` — examples, CI config, the docs directory —
+don't trigger doc updates on their own.
+
+Note that `src/pipecatcloud/__init__.py` is **not** excluded despite being a
+re-export file. Its `__all__` is the definition of the SDK's public surface, so
+a name added or removed there is a documentation change even when the
+implementation moved not at all.
+
+## Skip list
+
+| File | Why |
+| --- | --- |
+| `_utils/async_utils.py` | `synchronizer` plumbing that turns async commands into blocking ones. No observable surface. |
+| `api.py`, `cli/api.py` | The HTTP client. The class is `_API`, underscore-private, and the REST reference is generated from a hand-maintained `openapi.json` in the docs repo with no upstream to diff against. A change here that implies a REST contract change should be **reported as an unmapped finding** rather than edited into the REST pages blind. |
+| `cli/__init__.py` | Holds `PIPECAT_CLI_NAME`. Reaches users only through message text already documented elsewhere. |
+
+Nothing else is internal. In particular `_utils/` is not a skip zone — most of
+this package's documented behavior lives there.
+
+## Base classes
+
+`pipecatcloud` has no service base classes. Its analogue is the shared console
+layer, which every command's output and exit behavior passes through.
+
+| File | Pages to check |
+| --- | --- |
+| `_utils/console_utils.py` | `api-reference/cli/cloud/output.mdx` first — it defines `OutputMode`, the rich/plain/json rendering, `output_json`, and `require_interactive`, which is where the exit-2-on-no-TTY contract comes from. A change to the table or listing shape also affects every command page that shows example output. |
+| `_utils/auth_utils.py` | `api-reference/cli/cloud/output.mdx` (exit behavior when unauthenticated), `pipecat-cloud/guides/personal-access-tokens.mdx` |
+
+## Non-standard locations
+
+| File | Page |
+| --- | --- |
+| `cli/entry_point.py` | `api-reference/cli/cloud/output.mdx` — global options (`--output`, `--show-cli-config`) and their resolution order |
+| `cli/config.py`, `config.py` | `api-reference/cli/cloud/output.mdx` — `PIPECAT_`-prefixed environment variables and config-file keys. `PIPECAT_TOKEN` also appears in `pipecat-cloud/guides/personal-access-tokens.mdx` and `guides/cloud-builds.mdx`. |
+| `_utils/deploy_utils.py` | `api-reference/cli/cloud/deploy.mdx` — the `pcc-deploy.toml` reference. `DeployConfigParams` and its nested config classes are the source of truth for every accepted key. |
+| `_utils/build_utils.py` | `pipecat-cloud/guides/cloud-builds.mdx` — `DEFAULT_EXCLUSIONS` is enumerated on that page |
+| `_utils/github_utils.py` | `api-reference/cli/cloud/github.mdx`, `pipecat-cloud/guides/deploy-from-github.mdx` |
+| `_utils/regions.py` | `api-reference/cli/cloud/regions.mdx`, `pipecat-cloud/guides/regions.mdx` |
+| `constants.py` | Depends on the constant. Krisp values → `pipecat-cloud/guides/krisp-viva.mdx`. Grep the value itself. |
+| `exception.py` | `api-reference/pipecat-cloud/sdk-reference/exceptions.mdx` **and** `pipecat-cloud/fundamentals/error-codes.mdx`. The first documents the classes, the second the `PCC-` codes they carry. |
+| `session.py` | `api-reference/pipecat-cloud/sdk-reference/sessions.mdx`, and `api-reference/pipecat-cloud/sdk-reference/examples.mdx` — its first sample constructs a `Session` |
+| `agent.py` | `api-reference/pipecat-cloud/sdk-reference/session-arguments.mdx`, and `api-reference/pipecat-cloud/sdk-reference/examples.mdx` — two of its three samples are `bot()` entry points |
+| `smallwebrtc/session_manager.py` | `api-reference/pipecat-cloud/sdk-reference/sessions.mdx` |
+| `__init__.py` | `api-reference/pipecat-cloud/sdk-reference/overview.mdx` — its Key Components list should name everything in `__all__` |
+
+## Pattern matching
+
+`src/pipecatcloud/cli/commands/<group>.py` →
+`api-reference/cli/cloud/<group>.mdx`, with underscores becoming hyphens.
+
+| Source | Page |
+| --- | --- |
+| `cli/commands/agent.py` | `api-reference/cli/cloud/agent.mdx` |
+| `cli/commands/auth.py` | `api-reference/cli/cloud/auth.mdx` |
+| `cli/commands/build.py` | `api-reference/cli/cloud/build.mdx` |
+| `cli/commands/deploy.py` | `api-reference/cli/cloud/deploy.mdx` |
+| `cli/commands/docker.py` | `api-reference/cli/cloud/docker.mdx` |
+| `cli/commands/github.py` | `api-reference/cli/cloud/github.mdx` |
+| `cli/commands/organizations.py` | `api-reference/cli/cloud/organizations.mdx` |
+| `cli/commands/regions.py` | `api-reference/cli/cloud/regions.mdx` |
+| `cli/commands/secrets.py` | `api-reference/cli/cloud/secrets.mdx` |
+| `cli/commands/spend_limit.py` | `api-reference/cli/cloud/spend-limit.mdx` |
+
+A command group's page is not the whole story. Flags that change how a deploy
+behaves usually also appear in a guide — check `pipecat-cloud/fundamentals/` and
+`pipecat-cloud/guides/` per Step 7.
+
+### Self-hosted regions — currently being documented separately
+
+`cli/commands/agent_profiles.py` and `cli/commands/registry_keys.py`, and the
+self-hosted subcommands within `regions.py` and `secrets.py`
+(`regions register|show|delete|enroll-token`, `secrets reference`), have **no
+page yet**. They are covered by an in-flight docs PR adding
+`pipecat-cloud/self-hosted/`.
+
+Report changes to these as unmapped findings rather than creating pages for
+them, until that section exists and this table names it.
+
+## Search
+
+When the tables come up empty, grep `DOCS_PATH` for:
+
+- **CLI files** — the literal command name as the page heading spells it
+  (`## agent link`, `### keys revoke`), then the flag string with its dashes
+  (`--no-credentials`). Flags are the most reliable anchor: a page that
+  documents a command documents its flags.
+- **SDK files** — the class name (`AgentStartError`, `SessionParams`).
+- **TOML keys** — the bare key (`websocket_auth`, `min_agents`) across
+  `api-reference/cli/cloud/deploy.mdx` and the guides.
+
+## Section vocabulary
+
+Two page shapes, and they do not share a vocabulary.
+
+**CLI reference pages** — one `##` heading per subcommand, then:
+
+| Section | Built from | Form |
+| --- | --- | --- |
+| Usage | the command's argument and option signature | fenced `shell` block |
+| Arguments | `typer.Argument(...)` declarations | `<ParamField>` entries |
+| Options | `typer.Option(...)` declarations | `<ParamField>` entries, with both long and short forms in `path` (`--organization / -o`) |
+
+A `<ParamField>` `default` must be the Typer default, not what the help text or
+spinner displays. `agent logs --level` was documented as defaulting to `ALL`
+because that is what the spinner prints; the real default is `None`, and `ALL`
+is not a valid value.
+
+**SDK reference pages** — one `##` heading per class, then Constructor
+Parameters (`<ParamField>`), Methods (`<ResponseField>`), and Properties.
+Exceptions a method raises belong in its `<ResponseField>`.
+
+**`pcc-deploy.toml` keys** live in `api-reference/cli/cloud/deploy.mdx` under
+Configuration Options, as `<ParamField>` entries carrying a short TOML example
+each. Top-level keys go under Optional Fields; a `[section]` gets its own
+`####` heading.
+
+## Guide directories
+
+- `pipecat-cloud/fundamentals/` — deploy, scaling, secrets, active sessions, agent images, error codes, health checks, logging, accounts
+- `pipecat-cloud/guides/` — cloud builds, GitHub deploys, CI, telephony, container registries, websockets, regions, Krisp
+- `pipecat-cloud/security/` — security and compliance, HIPAA
+- `pipecat-cloud/introduction.mdx` — the section landing page; only changes when a whole capability arrives or leaves
+
+These carry a lot of copy-pasteable commands, and a renamed flag breaks every
+one of them silently. When a flag changes, grep all three directories for the
+old spelling before finishing.
+
+## New pages
+
+### Location and template
+
+A new command group goes at `DOCS_PATH/api-reference/cli/cloud/<group>.mdx`:
+
+````
+---
+title: "pipecat cloud <group>"
+sidebarTitle: "<group>"
+description: "pipecat cloud <group> ..., 110-140 chars naming what it manages"
+---
+
+[One or two sentences on what the group is for, and when to reach for it.]
+
+## <subcommand>
+
+[What it does.]
+
+**Usage:**
+
+```shell
+pipecat cloud <group> <subcommand> [ARGS] [OPTIONS]
+```
+
+**Arguments:**
+
+<ParamField path="arg-name" type="string" required>
+  [From the typer.Argument help text, expanded.]
+</ParamField>
+
+**Options:**
+
+<ParamField path="--flag / -f" type="string">
+  [From the typer.Option help text, expanded.]
+</ParamField>
+
+[Behavior worth stating: what prompts, what is required in CI, what the command
+refuses to do.]
+````
+
+### Registration
+
+Add the path, without `.mdx`, to `DOCS_PATH/docs.json` under the CLI tab's
+`cloud` group. There is no support-matrix page to update — unlike pipecat, this
+is the only registration step.
+
+The group's pages are ordered roughly by workflow rather than alphabetically
+(`output` first as the cross-cutting one, then auth, build, deploy, and so on).
+Place a new page where a reader would look for it.

pipecatcloud-1.3.0/.github/workflows/tests.yml

@@ -0,0 +1,75 @@
+name: tests
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - '**'
+
+concurrency:
+  group: build-test-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: 'Unit Tests'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: 'latest'
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: |
+          uv sync --group dev
+
+      - name: Run tests
+        run: |
+          uv run pytest -v
+
+  # The job above runs the agent session-argument types against the pipecat-ai
+  # in uv.lock. These legs run them against releases before MOQRunnerArguments
+  # gained relay_url, where pipecatcloud.agent must still import and refuse only
+  # MOQSessionArguments: 1.11.0 has the class without the field, 1.5.0 has no
+  # class at all.
+  agent-types:
+    name: 'Agent types on pipecat-ai ${{ matrix.pipecat-ai }}'
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        pipecat-ai: ['1.11.0', '1.5.0']
+    steps:
+      - name: Checkout repo
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+        with:
+          version: 'latest'
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install dependencies
+        run: |
+          uv sync --group dev
+
+      # `python -m pytest`: a bare `pytest` can resolve to the locked
+      # environment's entry point instead of the layered one. The tests check,
+      # in their own process, that they run on the version this leg names.
+      - name: Run the agent type tests
+        env:
+          PCC_EXPECTED_PIPECAT_AI: ${{ matrix.pipecat-ai }}
+        run: |
+          uv run --with "pipecat-ai==${{ matrix.pipecat-ai }}" python -m pytest -v tests/test_agent_args.py

pipecatcloud-1.3.0/.github/workflows/update-docs.yml

@@ -0,0 +1,375 @@
+# Opens a documentation PR against pipecat-ai/docs when a change to this
+# package's public API merges. The skill it follows is shared, published from
+# pipecat-ai/pipecat through the pipecat-dev-skills marketplace; the mapping it
+# applies is this repo's own .claude/skills/update-docs/SOURCE_DOC_MAPPING.md.
+#
+# Requires three repository secrets, none of which exist here yet:
+#   DOCS_BOT_APP_ID, DOCS_BOT_PRIVATE_KEY  — the same GitHub App pipecat uses
+#   ANTHROPIC_API_KEY                      — for the agent that writes the docs
+#
+# This repo is in daily-co while the docs repo is in pipecat-ai, so the App
+# token is minted for owner pipecat-ai and scoped to `docs` alone. Reading this
+# repo's own PRs uses the default GITHUB_TOKEN, which needs no extra grant. The
+# App therefore needs no installation on daily-co — only the credentials.
+#
+# Until those secrets are set, the workflow will fail at its first step rather
+# than run and do nothing.
+
+name: Update Documentation on PR Merge
+
+on:
+  pull_request_target:
+    types: [closed]
+    branches: [main]
+    # Everything shipped in the package is in scope, named as exclusions so a new
+    # directory is covered the day it appears rather than when someone remembers
+    # to list it.
+    paths:
+      - "src/pipecatcloud/**"
+      - "!src/pipecatcloud/tests/**"
+  workflow_dispatch:
+    inputs:
+      pr_number:
+        description: "PR number to generate docs for"
+        required: true
+        type: string
+
+jobs:
+  update-docs:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      # write so a run that fails can say so on the PR that triggered it;
+      # issues: write covers the label, which goes through the issues API
+      pull-requests: write
+      issues: write
+      id-token: write
+    steps:
+      - name: Generate app token
+        id: app-token
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.DOCS_BOT_APP_ID }}
+          private-key: ${{ secrets.DOCS_BOT_PRIVATE_KEY }}
+          owner: pipecat-ai
+          repositories: |
+            docs
+
+      - name: Checkout pipecat-cloud
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Checkout docs
+        uses: actions/checkout@v4
+        with:
+          repository: pipecat-ai/docs
+          token: ${{ steps.app-token.outputs.token }}
+          path: _docs
+
+      # The update-docs skill is shared and lives in pipecat-ai/pipecat, published
+      # through the pipecat-dev-skills marketplace. Only the directory holding it
+      # is fetched; this repo supplies the profile beside it.
+      - name: Checkout the shared update-docs skill
+        uses: actions/checkout@v4
+        with:
+          repository: pipecat-ai/pipecat
+          sparse-checkout: .claude/skills/update-docs
+          sparse-checkout-cone-mode: false
+          path: _skill
+          fetch-depth: 1
+
+      - name: Record docs baseline
+        id: docs-base
+        working-directory: _docs
+        # The commit the docs branch builds on, used to scope formatting to the
+        # pages this run touches.
+        run: echo "sha=$(git rev-parse HEAD)" >> "$GITHUB_OUTPUT"
+
+      - name: Resolve PR number
+        id: pr
+        run: |
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            echo "number=${{ inputs.pr_number }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "number=${{ github.event.pull_request.number }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Determine assignee
+        id: assignee
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          PR_AUTHOR=$(gh pr view ${{ steps.pr.outputs.number }} \
+            --repo daily-co/pipecat-cloud --json author --jq '.author.login')
+
+          # Assign the PR author only if they're a maintainer (== member of the
+          # pipecat-ai org). Org members all have at least read access to the docs
+          # repo, so they're assignable there; the assignees probe guards against
+          # future access changes. Otherwise leave the PR unassigned for triage.
+          ASSIGNEE=""
+          if gh api "orgs/pipecat-ai/members/$PR_AUTHOR" --silent 2>/dev/null \
+            && gh api "repos/pipecat-ai/docs/assignees/$PR_AUTHOR" --silent 2>/dev/null; then
+            ASSIGNEE="$PR_AUTHOR"
+          fi
+
+          echo "login=$ASSIGNEE" >> "$GITHUB_OUTPUT"
+          if [ -n "$ASSIGNEE" ]; then
+            echo "Docs PR will be assigned to: $ASSIGNEE"
+          else
+            echo "PR author is not an org member; docs PR will be left unassigned."
+          fi
+
+      - name: Update documentation
+        uses: anthropics/claude-code-action@v1
+        env:
+          DOCS_TOKEN: ${{ steps.app-token.outputs.token }}
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          prompt: |
+            You are updating documentation for the pipecat-ai/docs repository based on
+            changes merged in PR #${{ steps.pr.outputs.number }} of daily-co/pipecat-cloud.
+
+            ## Setup
+
+            1. Read the shared skill instructions at `_skill/.claude/skills/update-docs/SKILL.md`
+            2. Read this repo's profile at `.claude/skills/update-docs/SOURCE_DOC_MAPPING.md`
+            3. The docs repository is checked out at `./_docs/`
+
+            ## Get the diff
+
+            Run `gh pr diff ${{ steps.pr.outputs.number }}` to see what changed in the PR.
+            Also run `gh pr diff ${{ steps.pr.outputs.number }} --name-only` to get the list of changed files.
+            Filter to source files matching the profile's Scope section (SKILL.md Step 3).
+
+            If no relevant source files were changed, exit with "No documentation changes needed."
+
+            ## Follow the skill instructions
+
+            Apply the SKILL.md workflow (Steps 3-10) with these adaptations for automation:
+
+            ### Docs path
+            Use `./_docs/` — it's already checked out. Do not ask for a path.
+
+            ### Branch management
+            - Branch name: `docs/cloud-pr-${{ steps.pr.outputs.number }}`
+            - Work inside `./_docs/` for all doc edits and git operations
+            - Check if the branch already exists on the remote:
+              ```bash
+              cd _docs && git fetch origin docs/cloud-pr-${{ steps.pr.outputs.number }} 2>/dev/null
+              ```
+              - If it exists: check it out (supports workflow re-runs)
+              - If not: create it from main
+
+            ### Git config
+            Before committing in `_docs`, set:
+            ```bash
+            git config user.name "github-actions[bot]"
+            git config user.email "github-actions[bot]@users.noreply.github.com"
+            ```
+
+            ### No interactive questions
+            Do not ask questions. If you encounter gaps (unmapped files, missing sections,
+            ambiguous changes), note them in the PR body under "## Gaps identified".
+
+            ### Creating the docs PR
+            After committing all changes in `_docs`, push and create a PR:
+            ```bash
+            cd _docs
+            git push -u origin docs/cloud-pr-${{ steps.pr.outputs.number }}
+            GH_TOKEN=$DOCS_TOKEN gh pr create \
+              --repo pipecat-ai/docs \
+              --label auto-docs \
+              --label pipecat-cloud \
+              --title "docs: update for pipecat PR #${{ steps.pr.outputs.number }}" \
+              --body "$(cat <<'BODY'
+            Automated documentation update for [pipecat-cloud PR #${{ steps.pr.outputs.number }}](https://github.com/daily-co/pipecat-cloud/pull/${{ steps.pr.outputs.number }}).
+
+            ## Changes
+            <summarize each doc page updated and what changed>
+
+            ## Gaps identified
+            <any unmapped files, missing doc pages, or missing sections — or "None">
+            BODY
+            )"
+            ```
+
+            ### Re-run handling
+            If `gh pr create` fails because a PR from that branch already exists,
+            push the updated commits and use `gh pr edit` to update the body instead.
+
+            ### Recording the outcome
+            Every run must leave a one-line verdict at
+            `$RUNNER_TEMP/docs-update-outcome.txt`, written before you finish:
+
+            - `PR: <url>` — a docs PR was created or updated
+            - `NOOP: <reason>` — no docs change was needed, naming the specific
+              reason (e.g. "only internal wiring in pipeline/task_manager.py changed;
+              no public API affected")
+
+            A bare "no changes needed" is not a reason. This file is how a reader
+            later tells a deliberate no-op from a run that quietly fell short, so
+            write it even when the answer seems obvious.
+
+            ### No-op
+            If after analyzing the diff you determine no documentation changes are needed
+            (e.g., only skip-listed files changed, or changes don't affect public API docs),
+            write the `NOOP:` line described above and exit cleanly without creating a
+            branch or PR.
+
+            A file being a base class or a shared module is NOT by itself a reason to
+            skip it. Public constructor parameters, event handlers, and behavior belong
+            in the docs wherever they live — see the mapping file's Skip list for the
+            short set of genuinely internal files.
+
+            ### Formatting and llms.txt
+            Skip SKILL.md Step 9. A later workflow step runs Prettier over the pages
+            this branch touches and regenerates `llms.txt` / `llms-full.txt`, so leave
+            both to it rather than running them yourself.
+
+            ## Important rules
+            - Only modify files inside `./_docs/` — never modify pipecat source code
+            - Follow the conservative editing rules from SKILL.md Step 6
+            - Read each doc page fully before editing (SKILL.md Guidelines)
+            - Use `GH_TOKEN=$DOCS_TOKEN` for all `gh` commands targeting pipecat-ai/docs
+          claude_args: |
+            --model claude-sonnet-5-5
+            --max-turns 90
+            --allowedTools "Read,Write,Edit,Glob,Grep,Bash"
+
+      # Pinned from the docs repo's own .nvmrc rather than left to whatever the
+      # runner image ships, so formatting and generated files match what
+      # contributors produce.
+      - name: Set up Node
+        if: always()
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: _docs/.nvmrc
+
+      - name: Format docs and regenerate llms.txt
+        if: always()
+        working-directory: _docs
+        run: |
+          BRANCH="docs/cloud-pr-${{ steps.pr.outputs.number }}"
+          if [ "$(git rev-parse --abbrev-ref HEAD)" != "$BRANCH" ]; then
+            echo "No docs branch checked out; nothing to do."
+            exit 0
+          fi
+
+          # Format only the pages this branch touches, so the docs PR diff stays
+          # limited to the changes under review.
+          CHANGED=$(mktemp)
+          git diff --name-only --diff-filter=d -z \
+            "${{ steps.docs-base.outputs.sha }}" HEAD > "$CHANGED"
+          if [ ! -s "$CHANGED" ]; then
+            echo "No doc changes to format."
+            exit 0
+          fi
+
+          # The docs repo pins Prettier, so this matches what its pre-commit hook
+          # produces. `--ignore-unknown` skips files Prettier has no parser for.
+          npm ci --no-audit --no-fund
+          xargs -0 npx prettier --ignore-unknown --write < "$CHANGED"
+
+          # The docs repo checks in llms.txt and llms-full.txt, and its metadata
+          # lint fails when either is stale. llms-full.txt embeds page bodies
+          # verbatim, so generation runs after Prettier has settled them.
+          node scripts/gen-llms-txt.mjs
+
+          if git diff --quiet; then
+            echo "Doc changes are already formatted and llms.txt is current."
+            exit 0
+          fi
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git commit -am "chore: format docs and regenerate llms.txt"
+          git push origin "$BRANCH"
+
+      - name: Assign docs PR
+        if: always()
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          ASSIGNEE="${{ steps.assignee.outputs.login }}"
+          if [ -z "$ASSIGNEE" ]; then
+            echo "No assignee resolved; leaving docs PR unassigned."
+            exit 0
+          fi
+          PR_URL=$(gh pr list --repo pipecat-ai/docs \
+            --head docs/cloud-pr-${{ steps.pr.outputs.number }} \
+            --state open --json url --jq '.[0].url')
+          if [ -z "$PR_URL" ]; then
+            echo "No open docs PR for branch docs/cloud-pr-${{ steps.pr.outputs.number }}; nothing to assign."
+            exit 0
+          fi
+          gh pr edit "$PR_URL" --add-assignee "$ASSIGNEE"
+          echo "Assigned $PR_URL to $ASSIGNEE"
+
+      # The run summary states the outcome either way, so a run that documented
+      # nothing is distinguishable from one that produced a docs PR.
+      - name: Record outcome
+        if: always()
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: |
+          PR_NUMBER="${{ steps.pr.outputs.number }}"
+          DOCS_PR=$(gh pr list --repo pipecat-ai/docs \
+            --head "docs/cloud-pr-$PR_NUMBER" --state all \
+            --json url --jq '.[0].url' 2>/dev/null || true)
+
+          {
+            echo "## Docs automation for pipecat-cloud PR #$PR_NUMBER"
+            echo
+            if [ -n "$DOCS_PR" ]; then
+              echo "Docs PR: $DOCS_PR"
+            elif [ -f "$RUNNER_TEMP/docs-update-outcome.txt" ]; then
+              echo "No docs PR. Reported outcome:"
+              echo
+              echo '```'
+              cat "$RUNNER_TEMP/docs-update-outcome.txt"
+              echo '```'
+            else
+              echo "No docs PR and no recorded outcome — the run did not reach the"
+              echo "point of stating one. Treat this PR as undocumented."
+            fi
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      # Nothing outside the Actions tab surfaces a failed run, so it is reported
+      # on the PR that triggered it.
+      - name: Report failure on the source PR
+        if: failure() && steps.pr.outputs.number != ''
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PR_NUMBER: ${{ steps.pr.outputs.number }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          gh label create docs-automation-failed \
+            --repo daily-co/pipecat-cloud \
+            --color B60205 \
+            --description "The update-docs workflow failed for this PR" \
+            2>/dev/null || true
+
+          gh pr edit "$PR_NUMBER" --repo daily-co/pipecat-cloud \
+            --add-label docs-automation-failed 2>/dev/null || true
+
+          gh pr comment "$PR_NUMBER" --repo daily-co/pipecat-cloud --body "$(cat <<BODY
+          **Docs automation failed for this PR — its documentation is missing.**
+
+          The \`update-docs\` workflow did not produce a docs PR: [run log]($RUN_URL)
+
+          Re-run it once the cause is addressed:
+
+          \`\`\`
+          gh workflow run update-docs.yml -f pr_number=$PR_NUMBER --repo daily-co/pipecat-cloud
+          \`\`\`
+
+          If this PR genuinely needs no documentation, remove the
+          \`docs-automation-failed\` label.
+          BODY
+          )"