Publish the documentation from a stable branch

[gustavosbarreto]

The documentation site is published continuously from master. A page written for
a feature that has not shipped yet becomes visible the moment it is merged, so
writing documentation alongside the feature means publishing it early.

This splits the site in two. The docs/stable branch becomes the production
branch of the Cloudflare Pages project and is the only one that publishes to the
site; it is moved to the release tag when a version is cut. Master and open pull
requests land on preview URLs, so documentation can be merged together with the
feature it describes without reaching readers.

A build that does not come from docs/stable carries a banner saying it is
built from master and may describe features that are not in any release yet,
linking to the documentation for the released version.

robots.txt is left alone: it still disallows everything, which is correct
while the site is served from docsv2. When it takes over the published address,
that file becomes the knob that lets the stable build be indexed and keeps the
builds from master out.

Manual steps

Merging this is not enough. After it lands, in this order:

1. Create the branch from the tag of the current release and push it:

   git branch docs/stable "$(git describe --tags --abbrev=0 origin/master)"
   git push origin docs/stable
   

2. Wait for Docs CD to finish publishing that branch.

3. In the Cloudflare Pages project shellhub-docs, change the production branch
   to docs/stable.

4. Run Docs CD on master again, from the Actions tab. Until master stops being
   the production branch it publishes to the root of the project and has no
   branch alias, so this run is what creates
   master.shellhub-docs.pages.dev and puts the unreleased documentation there.

Doing 3 before 1 leaves the project without a production branch.

Cutting a release

Moving the published documentation to a new version is one command:

git branch -f docs/stable <tag> && git push -f origin docs/stable

A fix to the published documentation has to land on master first and be
cherry-picked to docs/stable. A commit that exists only on docs/stable is
discarded by the next release.

[github-actions]

Claude finished @gustavosbarreto's task in 1m 22s —— View job

---

Code Review Complete

Reviewed 5 files across code quality, security, testing, language patterns, and architecture — no new issues found. The code looks good as-is.

The channel logic is consistent end to end: github.ref_name == 'docs/stable' in the build env (docs-cd.yml:57) drives PUBLIC_DOCS_CHANNEL, which the banner gates on (UnreleasedBanner.astro:6), and the deploy --branch (docs-cd.yml:71) routes only docs/stable to the production branch while master and PRs land on previews. Dropping the push path filter is correctly justified by the force-push release model, and the interim docsv2.shellhub.io link is an explicitly documented choice.

---

To request another review round, comment /review.
· docs/publish-from-stable-branch

[github-actions]

Documentation preview: https://0446152d.shellhub-docs.pages.dev

[github-actions]

Documentation preview: https://9c8504d0.shellhub-docs.pages.dev

[github-actions]

Documentation preview: https://bd34b899.shellhub-docs.pages.dev

[github-actions]

Documentation preview: https://185eea78.shellhub-docs.pages.dev