ci: replace docs/v* branches with tags for versioned docs deployment

[marc0olo]

What and why

Replaces docs/v* branches with docs/v* tags as the mechanism for controlling versioned documentation deployments, and adds automation to keep them in sync after every release.

The problem with branches

Both v* release tags and docs/v* branches triggered the same publish-versioned-docs job and deployed to the same /X.Y/ folder. Branches drift silently — a routine push to a stale docs/v0.2 branch overwrites the live docs with older content, with no warning. This happened in practice: docs/v0.2 sat at its March 30 state while the live /0.2/ was correctly deployed from the April 8 v0.2.3 tag. Automating a branch-based sync (PR #510) required branch protection bypass configuration and still produced merge conflicts.

Why tags

Tags are immutable by convention. Moving one requires a deliberate git push --force — it cannot happen accidentally. No branch protection rules apply, so no bypass configuration is needed.

---

How versioned docs work after this PR

Triggers (changed)

Event	Before	After
v0.2.3 release tag pushed	Deploys /0.2/	Deploys /0.2/ (unchanged)
docs/v0.2 branch pushed	Deploys /0.2/	No longer triggers deployment
docs/v0.2 tag pushed or force-moved	No effect	Deploys /0.2/

Automatic sync on every release

Two workflows run concurrently when a release tag is pushed:

v0.2.3 pushed
  ├─ docs.yml → publish-versioned-docs
  │    └─ Builds and deploys /0.2/ from the v0.2.3 commit ✓
  │
  └─ sync-docs-tag.yml  ← new
       └─ Creates or force-moves docs/v0.2 tag to v0.2.3 commit
            └─ Uses GITHUB_TOKEN → does NOT re-trigger docs.yml ✓

GitHub prevents recursive workflow runs from GITHUB_TOKEN pushes by design, so the tag move never causes a second deployment.

Doing a docs-only fix between releases

The rule: always merge the fix to main first. The docs/vX.Y tag is only for immediate deployment — when the next patch is released, sync-docs-tag.yml resets docs/vX.Y to the release commit. Any commit that exists only on the tag (not in main) will be lost at that point.

Workflow for an immediate re-deploy of /0.2/:

# 1. Merge the fix to main via a normal PR  (required — do this first)

# 2. Immediately deploy the fix to /0.2/ without waiting for a release:
git fetch --tags
git checkout -b temp/docs-fix-v0.2 docs/v0.2   # start from current tag state
git cherry-pick <merged-commit-sha>              # the commit already in main

git tag -f docs/v0.2 HEAD
git push origin refs/tags/docs/v0.2 --force     # triggers re-deploy of /0.2/

git branch -D temp/docs-fix-v0.2                # local branch; not pushed

The commits remain reachable via the tag — no remote branch is ever pushed.

---

Files changed

File	Change
.github/workflows/docs.yml	Trigger: docs/v* branch → tag (+ !docs/v*-*); version extraction and job condition updated to refs/tags/docs/v
.github/workflows/sync-docs-tag.yml	New. Creates or force-moves docs/vX.Y tag to the release commit after each release tag push
docs-site/README.md	Triggers section updated; docs-only fix workflow and GITHUB_TOKEN behavior explained
.claude/docs-guidelines.md	New section: "Docs-Only Fixes for Released Versions" — the merge-to-main-first rule, full workflow, and why commits must be in main before the next release
.claude/skills/release/task6-docs.md	Documents both automated workflows (docs.yml + sync-docs-tag.yml); cross-references docs guidelines
.claude/skills/release/rollback.md	Task 2 rollback: steps to revert docs/vX.Y tag; Task 6 rollback: clarified that tag cleanup belongs to Task 2

---

Migration: after this PR merges

Two docs/v* branches currently exist (docs/v0.1, docs/v0.2). Neither will trigger deployments after this merges. Tag each at its current branch tip, then delete the branches:

git fetch origin

# docs/v0.1
git tag docs/v0.1 origin/docs/v0.1
git push origin refs/tags/docs/v0.1
git push origin --delete docs/v0.1
git branch -D docs/v0.1 2>/dev/null || true

# docs/v0.2
git tag docs/v0.2 origin/docs/v0.2
git push origin refs/tags/docs/v0.2
git push origin --delete docs/v0.2
git branch -D docs/v0.2 2>/dev/null || true

The live /0.1/ and /0.2/ docs are unaffected — already correctly deployed on docs-deployment.

---

Test plan

• Merge this PR, then run the migration steps above for docs/v0.1 and docs/v0.2
• On next release tag push: verify sync-docs-tag.yml runs and moves docs/vX.Y to the release commit
• Verify docs.yml is not re-triggered by the sync-docs-tag.yml tag move
• Manually force-move docs/v0.2 to a test commit and verify docs.yml is triggered and redeploys /0.2/
• Verify docs/v* branch pushes no longer trigger publish-versioned-docs