Automatically open PR for documentation changes when code merged to main #1105

Description

When code is merged to main and its behavior changes the documentation, automatically prepare the corresponding documentation changes and open a pull request for review. The issue currently supplies no proposed generation mechanism, source-to-page mapping, or examples of missed documentation; those details need to be chosen during implementation.

Current state

.github/workflows/deploy-docs.yml builds and deploys the VitePress site when documentation changes land on main (or when manually dispatched). It does not prepare documentation edits or open a PR after a code merge. The documentation refresh design records implementation sources and their reader-facing guides as the sources of truth for documentation updates.

Expected behavior

A code merge that requires a documentation update results in a reviewable PR containing the proposed documentation diff. Reviewers can see which merged change the proposal addresses and validate the prose before it lands. A merge that yields no documentation diff should not create a PR.

Done when

• An automated path examines code merged to main, prepares documentation changes when needed, and opens a PR rather than committing those changes directly to main.
• The PR identifies the merged change it documents and contains a reviewable diff.
• No PR is opened for an empty documentation diff; retrying the same merged change does not create duplicate PRs.
• The resulting documentation passes the repository's docs formatting and build checks before the PR is offered for review.

Design decisions to resolve

• Which code changes require documentation, and which pages are in scope?
• How will the proposed prose be produced and checked against the merged code?
• How should overlapping or sequential merges update an existing documentation PR?

Relevant files

• .github/workflows/deploy-docs.yml
• docs/superpowers/specs/2026-08-19-documentation-refresh-design.md