Notify pantheon-systems/documentation on release

[EdwardAngert]

Summary

pantheon-systems/documentation maintains commands.json and terminusReleases.json — reference data for the Terminus docs pages (command reference, changelog), regenerated from this repo's list --format=json output and the releases API. That data was found stale during a docs audit (three releases behind, missing real commands) and the docs repo now has automation to keep it fresh: pantheon-systems/documentation#10177.

That automation polls weekly by default, which means up to a week of staleness after every Terminus release. This PR adds a step to the existing release job — right after the GitHub Release is created (so terminus.phar is actually available to download) — that fires a repository_dispatch to the docs repo so it can refresh the same day instead of waiting for the next poll.

Requires

A DOCS_DISPATCH_TOKEN secret in this repo, scoped only to sending repository_dispatch events to pantheon-systems/documentation — see #2899 for that ask. Deliberately not linked as a closing keyword: merging this PR doesn't provision the secret, an admin has to do that separately, so this PR shouldn't auto-close that issue. This PR is safe to merge before that secret exists: the step is continue-on-error: true, and curl without -f doesn't fail on an HTTP auth error, so it's a harmless no-op until the secret is added.

Alternative design considered: push the data directly instead of notifying

This PR has terminus notify the docs repo, which then re-fetches terminus.phar and the releases API itself to regenerate its own files. An alternative would have terminus's release job write commands.json/terminusReleases.json directly (it already builds terminus.phar in this same job, so no re-download needed) and open the PR against pantheon-systems/documentation itself, instead of just dispatching a notification.

Went with notify-only for now, but the case for it is thinner than it might look, worth a reviewer's judgment call rather than treating as settled:

• Not really a security argument. Both designs require a human to review and merge the PR before anything lands in documentation's main — neither lets this repo push to main directly. A contents: write token scoped to documentation would be needed either way (GitHub's dispatches endpoint itself currently requires that same permission on a fine-grained PAT, even for a notify-only token), so the permission grant isn't meaningfully narrower in the notify-only design; what differs is that this step's code path is a single fixed API call with no attacker-influenceable payload, vs. a push built from job output. A minor hardening, not a structural one.
• Coupling is real but small. The direct-push design means this repo's workflow needs to know documentation's two file paths. Given both files are verbatim passthroughs (this repo's own list --format=json output and the raw GitHub releases response, no transform), that's not much schema knowledge to duplicate — a path, not a data model.
• Efficiency favors the direct-push design. documentation's workflow currently re-downloads terminus.phar from the public release right after this job already built the same file as an artifact. Pushing directly would skip that round-trip.

If a maintainer here would rather own the push logic directly, that's a reasonable call and I can rework this PR for it — flagging now rather than assuming the current split is the only reasonable shape.

Test plan

• Validated the workflow YAML with actionlint — no new findings (one pre-existing shellcheck warning at line 42, unrelated to this change)
• Confirmed the new step only runs as part of the existing release job's conditions (startsWith(github.ref, 'refs/tags/') && github.repository == 'pantheon-systems/terminus') — no new gating needed
• Confirm the dispatch actually reaches pantheon-systems/documentation's workflow once the token secret is added (that workflow already listens for repository_dispatch: types: [terminus-release])

Built with docs-agent-plugin

🤖 Generated with Claude Code