docs(ci): Publish to libtmux.org alongside git-pull.com

[tony]

Stacked on #755 — review that one first. This branch is #755 plus the deploy work.

Additive: libtmux.git-pull.com keeps publishing exactly as it does today, and libtmux.org is added alongside it. Nothing stops updating when this merges.

Summary

• Add a second publish, to libtmux.org under en/py/latest/, through libtmux/docs's shared reusable-deploy.yml — the same workflow every port calls, which writes only that port's own prefix.
• Build twice. The two destinations need different bytes, not one artifact published to both.
• Keep libtmux.git-pull.com's publish byte-for-byte as it is on master, running inside its own build job.
• Separate the secrets: LIBTMUX_ORG_* for the new destination, LIBTMUX_DOCS_* left meaning exactly what it means today.
• Move the paths-filter gate into its own job, so one output feeds both publishes instead of the condition being repeated on every step.

Why two builds and not one artifact twice

	libtmux.git-pull.com	libtmux.org
Served at	bucket root	en/py/latest/
/_shell/shell.js	nothing there	the site's chrome
/search/	this build's own search page	the site-wide Pagefind search
Build	LIBTMUX_DOCS_STANDALONE=1	flag unset

One artifact published to both is wrong in one direction or the other: set the flag and libtmux.org gets an unskinned nested site with the wrong search; unset it and git-pull.com gets a /search/ that redirects to itself. tests/test_docs_conf.py pins both shapes, including the empty-string form the matrix passes.

The git-pull.com sync stays inside its build job rather than moving behind an artifact. It is a live site, and upload-artifact does not preserve the symlinks that sync is explicitly told to follow.

Secrets

Set, and verified present on the repository — three for each destination:

Secret	Destination
LIBTMUX_ORG_ROLE_ARN, LIBTMUX_ORG_BUCKET, LIBTMUX_ORG_DISTRIBUTION	libtmux.org
LIBTMUX_DOCS_ROLE_ARN, LIBTMUX_DOCS_BUCKET, LIBTMUX_DOCS_DISTRIBUTION	libtmux.git-pull.com, untouched

The role trusts repo:tmux-python/libtmux:environment:docs — the name-only subject, which this repo can use because it predates GitHub's 2026-07-15 immutable-subject cutoff.

Still unset, and worth doing before or soon after this merges: the docs environment has no protection rules. A deployment branch-and-tag policy (master, v*) is what actually restricts which refs may publish, since environment: rewrites the OIDC sub claim to drop any ref: clause.

Verification, and its limit

docs.yml triggers only on push to master, so no PR check exercises any of this. First execution is the merge. What I could check instead:

• The four git-pull.com publish steps are byte-equivalent to master's — compared as parsed YAML, not by eye
• path-prefix: py/latest publishes to en/py/latest — reusable-deploy.yml prepends $locale/ whenever port is set, so passing en/py/latest would double it
• py/latest passes that workflow's own prefix validation: unrooted, no .., not a bare reserved top-level name
• Every required input and secret is supplied, checked against the workflow_call block rather than against the example
• version-kind: trunk is one of the kinds it accepts
• The artifact lands where it expects: it downloads to dist/ and syncs dist/, so the tree must be at the artifact root — path: docs/_build/html gives that
• The pinned commit's reusable-deploy.yml parses identically to the previously pinned one — its diff is comments only, compared as parsed YAML rather than read
• concurrency.queue is valid despite actionlint 1.7.12 rejecting it: it is in GitHub's published workflow schema, and deploy-shell.yml in libtmux/docs uses it with successful runs. That is actionlint lagging, and it is the only diagnostic it reports on this file
• Either deploy, end to end. Not observable before merge

One departure from the documented recipe

reusable-deploy.yml's header asks callers to pin a tag. This pins a commit, with the release named in a trailing comment — the form Dependabot reads to offer a bump.

libtmux/docs has cut and deleted v1 and v2, and its replacement is a 0.x prerelease series documented as moving. This uses: runs another repository's workflow inside this one, with id-token: write and a role that can write the bucket, so a ref that can be repointed means what executes here changes with no diff in this repository and no review. A commit cannot be repointed. The pinned commit is the one the deleted v2 pointed at, and its reusable-deploy.yml is byte-identical to every other candidate.

This is deliberately unlike the rest of the file, which pins moving majors (actions/checkout@v7, actions/cache@v6). Those are first-party actions running with this workflow's own permissions; this one runs a third party's workflow with id-token: write and bucket-write credentials, which is the case the pinning guidance is actually about.

Note the trailing comment is documentation here, not automation: this repository has no .github/dependabot.yml, so nothing will offer the bump. Bumping is manual until one exists.

The Cloudflare purge stays, unlike the previous revision of this branch — it fronts libtmux.git-pull.com, which is still being published.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 52.45%. Comparing base (1aae8a6) to head (16ec75d).

Additional details and impacted files

@@              Coverage Diff              @@
##           docs-site     #756      +/-   ##
=============================================
+ Coverage      52.37%   52.45%   +0.08%     
=============================================
  Files             26       26              
  Lines           3729     3729              
  Branches         747      747              
=============================================
+ Hits            1953     1956       +3     
+ Misses          1472     1469       -3     
  Partials         304      304              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.