ci(docs): open documentation PRs when public API changes

[markbackman]

Installs the docs automation this repo has never had. Builds on the profile merged in #201.

Why

Five docs PRs swept this package against v1.2.0 and found twelve commands that fail when run, six false statements, and an entire undocumented command group. That wasn't neglect — it accumulated because nothing here opens a docs PR when public API changes. The correlation across the org is exact: repos with this workflow stayed in sync, repos without it drifted.

Not a rewrite

This is pipecat's workflow with four adaptations, so everything it has accumulated carries over intact:

• the 90-turn cap that fixed a ~40% silent-drop rate (the version in pipecat-flows is still at 30)
• formatting before llms.txt generation — the reverse order leaves both files stale and fails the docs repo's lint
• outcome recording to the run summary, so a run that documented nothing is distinguishable from one that produced a PR
• failure reporting back onto the source PR, with a label and a re-run command

The four adaptations:

Scope	src/pipecatcloud/**, excluding tests
Branch names	docs/cloud-pr-N, not docs/pr-N
Token scope	App token minted for owner: pipecat-ai, scoped to docs alone
Source repo refs	every gh call targets daily-co/pipecat-cloud

Two things that aren't obvious

Branch namespacing. pipecat already uses docs/pr-N. Two repos each numbering from one will eventually both want docs/pr-412 in the docs repo, and the second would push onto the first's branch. Prefixing here avoids it. pipecat-flows has the same latent collision with pipecat today, though it's about to be archived so it will resolve itself.

Cross-org token. This repo is in daily-co; the docs repo is in pipecat-ai. The app-token step can only mint for one owner, so it's scoped to pipecat-ai / docs — used for checking out docs and opening the PR there. Reading this repo's PRs uses the default GITHUB_TOKEN, which needs no extra grant.

Prerequisite — this needs three secrets before it works

None of these exist in this repo today:

Secret	What it is
DOCS_BOT_APP_ID	The GitHub App pipecat already uses
DOCS_BOT_PRIVATE_KEY	Its private key
ANTHROPIC_API_KEY	For the agent that writes the docs

The App needs no new installation. The token is minted for owner: pipecat-ai scoped to docs, and the App is already installed there — only the credentials have to be present in this repo.

(I could not check for org-level secrets, which need admin access to list. If any of these are set org-wide and inherited, fewer are needed here.)

Until they are, the workflow fails at its first step rather than running and silently doing nothing — which is the failure mode you want, since a red run is visible and a quiet no-op isn't. There's a header comment in the file saying so.

Honest caveat

The shared skill this follows has been verified statically — the profile's nine contract sections are present, all 78 cloud doc pages are reachable by a rule, the YAML parses with 12 steps — but it has not been run end to end since being refactored. The first real merged PR here will be its first live exercise.

That's a deliberate tradeoff: this repo ships every ~3 weeks, so feedback comes soon, and the blast radius of a failure is a missing docs PR (visible via the failure label) rather than a wrong one. If you'd rather see it green first, a workflow_dispatch run on pipecat against a known-good merged PR is the test.

🤖 Generated with Claude Code