docs: clarify release workflow

CONTRIBUTING.md

@@ -10,6 +10,7 @@ Always check the project-wide guidelines and CI expectations:
 
 - `AGENTS.md`
 - `.github/workflows/python-app.yml`
+- `.github/workflows/docs.yml` (for docs / release-note changes)
 
 They define the required local checks and the order CI will run them.
 
@@ -38,22 +39,35 @@ Create an "Unreleased" section at the start of the cycle and update it as
 features land:
 
 ```text
-## 0.1.2 - Unreleased
+## Unreleased
 ```
 
-Finalize the content right before release.
+Right before the release, replace it with a dated heading such as:
+
+```text
+## 0.1.2 - YYYY-MM-DD
+```
 
 ## Standard Workflow (Simple)
 
 1. Create a release branch from `main`.
 2. Bump to a dev version once (e.g., `0.1.2.dev0`) and commit it.
 3. Merge feature PRs into the release branch.
-4. When ready:
+4. When ready for the final release, create a short-lived version-bump branch
+   from the release branch.
+5. On that version-bump branch:
    - finalize `RELEASE_NOTES.md`
-   - bump to the release version (e.g., `0.1.2`)
+   - run `poetry run python scripts/update_version.py 0.1.2`
    - run all required local checks
-   - merge into `main`
-   - tag the release and push the tag
+   - run `poetry run mkdocs build`
+6. Open a PR from the version-bump branch back into the release branch and
+   merge it after CI passes.
+7. Open a PR from the release branch into `main` and merge it.
+8. Create the final release tag (e.g., `v0.1.2`) from the commit now on
+   `main`, then push the tag.
+
+Do not tag a side branch or an unmerged release candidate commit. Tag the exact
+commit that now represents the released state on `main`.
 
 ## Publishing
 
@@ -67,12 +81,16 @@ Releases are published automatically by the CI release workflow
 | `v0.1.2.post1` | PyPI |
 | `v0.1.2a1`, `v0.1.2rc1` | Blocked by environment rule — manual decision |
 
+Additional `v0.1.2.devN` tags are optional. Create another dev release only if
+you want a fresh TestPyPI snapshot for validation before the final release.
+
 ```bash
 # Example: publish a dev build to TestPyPI
 git tag v0.1.2.dev1
 git push origin v0.1.2.dev1
 
-# Example: publish a release to PyPI
+# Example: after the release branch has been merged into main,
+# tag the main commit that now contains version 0.1.2
 git tag v0.1.2
 git push origin v0.1.2
 ```
@@ -83,8 +101,10 @@ See the comments at the top of `release.yml` for one-time setup steps.
 ## Required Local Checks
 
 Mirror CI locally. Run the exact commands listed in `AGENTS.md` and
-`.github/workflows/python-app.yml`, in the same order when relevant. Do not
-skip steps. If something cannot run, stop and document the blocker.
+`.github/workflows/python-app.yml`, in the same order when relevant. For docs
+and release-note changes, also mirror `.github/workflows/docs.yml` by running
+`poetry run mkdocs build`. Do not skip steps. If something cannot run, stop
+and document the blocker.
 
 ## Optional Eigen Build (C++ linear algebra)
 
@@ -108,6 +128,14 @@ Verify via:
 python -m ellphi --build-info
 ```
 
+## Docs CI and Deployment
+
+- `.github/workflows/docs.yml` runs `mkdocs build` on pull requests, on pushes
+  to `ellphi-*`, and via `workflow_dispatch`.
+- It deploys to `gh-pages` only on pushes to `main`.
+- `.github/workflows/python-app.yml` contains a `demo-install` job that checks
+  the demo dependency set; it is not the docs deployment workflow.
+
 ## Documentation
 
 ### Building and previewing