docs: add /next-version-preview/ subpath via gh-pages branch

[adamziel]

Summary

Lets us host two docs slots side by side on a single Pages site:

URL	Source
https://wordpress.github.io/php-toolkit/	trunk (rebuilt on every push to `trunk`)
https://wordpress.github.io/php-toolkit/next-version-preview/	latest manual preview build (whatever branch you point at it)

How it works

• `docs.yml` (modified) drops `actions/upload-pages-artifact` + `actions/deploy-pages` (they replace the entire Pages site on every deploy) and switches to `peaceiris/actions-gh-pages@v4` pushing to a long-lived `gh-pages` branch with `keep_files: true`. Trunk owns the root; `next-version-preview/` is left alone.
• `docs-preview.yml` (new) has two triggers:
  • `workflow_dispatch` with a `ref` input (any branch / tag / SHA). Use the Actions UI's "Run workflow" button to preview an in-flight branch on demand.
  • `push` to `preview/*`. `git push origin HEAD:preview/foo` and the preview goes live without ever opening a PR.
• The workflow rebuilds docs from the chosen ref, then `peaceiris` publishes to `gh-pages:/next-version-preview/` with `destination_dir` scoping so only that subfolder is replaced. Trunk content at the root is preserved.
• If the previewed ref has an open PR, the workflow leaves a comment on it with the preview URL.

Concurrency group `gh-pages` is shared between both workflows so two deploys can't race for the same branch (`cancel-in-progress: false` queues rather than drops).

After merge: flip the Pages source

The repo currently has Pages source set to "GitHub Actions". Once this PR's first `docs.yml` run pushes content to the new `gh-pages` branch, the source needs to flip to "Deploy from a branch — `gh-pages` / (root)". I'll do that via the Pages API immediately after the first push lands so there's no visible downtime. Manual fallback: Settings → Pages → Source → Deploy from a branch → `gh-pages` / `/`.

Tradeoff

• We lose the "Deploy via GitHub Actions" deployment lineage shown on the Environments tab. We gain a long-lived `gh-pages` branch (good for auditing what's deployed and adding more subpaths later — `pr-NNN/` previews if we ever want them).
• One race window: between the first `gh-pages` push and the source flip, the live site briefly serves the old workflow-deployed content (which is still cached on Pages anyway, so users won't notice).

Test plan

• After merge, `docs.yml` runs on trunk, creates `gh-pages` branch, populates root.
• Pages source flipped via API; site stays up.
• Manually trigger `docs-preview.yml` against this PR's branch (`pages-preview-subpath`). `/next-version-preview/` should serve the preview build.
• Confirm a subsequent push to `trunk` does not wipe `/next-version-preview/` (the `keep_files: true` invariant).

🤖 Generated with Claude Code

[adamziel]

Closing — for now, in-flight previews are being rendered via adamziel/experiments (https://adamziel.github.io/experiments/php-toolkit/), which is enough for the current docs-iteration cadence. Switching the WordPress org repo's Pages source from "GitHub Actions" to a gh-pages branch (and accepting the brief downtime + the lost "deployed via Actions" environment view) isn't worth it without a stronger signal that we want per-PR previews on the canonical URL. Reopen if that signal appears.