feat: automate OpenAPI sync with Bee releases

[yjkellyjoo]

What does this PR resolve? 🚀

Automates keeping the docs in sync with ethersphere/bee releases, replacing the manual copy-and-find/replace process.

• Adds .github/workflows/update-openapi.yaml — daily (and manual) job that detects the latest stable Bee tag, pulls openapi/Swarm.yaml + SwarmCommon.yaml from it, bumps Bee version strings in the install docs, and opens/updates a PR labelled openapi-auto-update.
• Adds .github/workflows/tag-on-openapi-merge.yaml — on merge of that PR, tags the merge commit vX.Y.Z, triggering the existing gh-pages.yaml deploy.
• Documents the automation in README.md and tracks a new CLAUDE.md (un-ignored from .gitignore).
• Adds a repo PR template.

Details 📝

• Stable-only: tags are filtered to ^v[0-9]+\.[0-9]+\.[0-9]+$, so all prereleases (-rc*, -beta, v2.7.1a, v2.5.0-v8) are skipped.
• Version detection: latest Bee tag via git ls-remote (no auth); current docs version read from the TAG=vX.Y.Z anchor in quick-start.md (avoids needing a version source-of-truth and dodges the v4.0.1 tag anomaly).
• Version-string bump: literal substring sed swap across 7 fixed doc files — deliberately rewrites the vX.Y.Z, bee:X.Y.Z, and X.Y.Z-<hash> forms while leaving the unrelated openapi apiVersion: 7.3.0 untouched (verified with a v2.7.0 dry-run). Best-effort; the PR body flags it for human review.
• BOT_PAT required: both workflows need a BOT_PAT repository secret (classic PAT with public_repo, or fine-grained with contents + pull-requests write). They fail loudly if it's missing/expired.
• CLAUDE.md now tracked: previously gitignored; un-ignored and committed so contributor/agent guidance ships with the repo.
• Not validated in CI here: workflows couldn't be actionlint-checked locally (tool unavailable) — embedded shell was bash -n-checked and the substitution behavior tested manually.

Checklist ✅

• Merged latest master and resolved conflicts
• npm run build succeeds
• Links checked (npm run check:links) where relevant
• static/llms.txt updated if pages were added / renamed / deleted
• Content follows CODING.md conventions (wrap long lines, Swarm vs swarm)
• Self-reviewed the diff
• Commits are signed off (git commit -s)

[netlify]

✅ Deploy Preview for test-twitter-preview-testing-3 ready!

Name	Link
🔨 Latest commit	b494409
🔍 Latest deploy log	https://app.netlify.com/projects/test-twitter-preview-testing-3/deploys/6a3d1ee6b6af870008ffdcd8
😎 Deploy Preview	https://deploy-preview-820--test-twitter-preview-testing-3.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[crtahlin]

Approving — solid, well-documented automation that replaces the manual find/replace. The design is sound: stable-only filtering, human-gated version bump, BOT_PAT fail-loud, scoped permissions:, concurrency control, and defense-in-depth re-validation of the tag before pushing. Verified the assumptions against master — the TAG=vX.Y.Z anchor in quick-start.md, all 7 target doc files, and both openapi/*.yaml specs exist. CI build is green.

A couple of should-fix hardening items (non-blocking):

1. update-openapi.yaml — "Resolve latest stable Bee tag" step: route the dispatch input through env: and validate it.
${{ github.event.inputs.tag }} is interpolated directly into the run: shell (both the if [ -n ... ] test and the NEW_TAG= assignment). Two issues:

• Injection: this is the pattern GitHub's hardening guidance warns against. Only workflow_dispatch-privileged users can reach it, so severity is low — but it's inconsistent with the rest of the PR, which correctly uses env: everywhere else, and the resulting NEW_VER later feeds a sed delimiter where a / or & would misbehave.
• Validation bypass: the ^v[0-9]+\.[0-9]+\.[0-9]+$ stable filter only applies to the auto-detected git ls-remote path. A forced dispatch tag (e.g. v2.9.0-rc1) skips it entirely, contradicting the "prereleases are skipped" guarantee.

One fix closes both: pass via env: INPUT_TAG: ${{ github.event.inputs.tag }}, reference "$INPUT_TAG", and run it through the same regex guard already used in tag-on-openapi-merge.yaml.

2. update-openapi.yaml — pin the third-party action to a SHA.
peter-evans/create-pull-request@v6 runs with contents/pull-requests: write plus BOT_PAT. Consider pinning to a full commit SHA (@<sha> # v6.x) for supply-chain hardening. First-party actions/checkout@v4 is lower risk.

Nit: tag-on-openapi-merge.yaml tags base.ref at current HEAD, so an unrelated commit landing on master between merge and run would shift the tag target — low likelihood given the gating, fine as-is.

Nice touches: the triple-gated if: on the merge workflow, the documented sed-scope reasoning, and dropping the duplicate CLAUDE.md line in .gitignore.