diff --git a/docs/how-to/install-heph.md b/docs/how-to/install-heph.md
index 820146b..fa69e02 100644
--- a/docs/how-to/install-heph.md
+++ b/docs/how-to/install-heph.md
@@ -27,6 +27,11 @@ cargo install --locked \
 Re-run with `--tag vX.Y.Z` once a release is cut. This needs forge SSH access
 (an unlocked 1Password / ssh-agent key).
 
+`heph --version` / `hephd --version` report `X.Y.Z (<git-sha>)` for a tagged
+install and `0.0.0 (<git-sha>)` for a branch/dev install — the release version
+is baked into the tag's manifest (`main` itself stays `0.0.0`), and the short
+SHA is captured at build time so any build is traceable to its commit.
+
 The **installed** daemon owns the default paths — socket
 `$XDG_RUNTIME_DIR/heph/hephd.sock`, DB `$XDG_DATA_HOME/heph/heph.db` — i.e. your
 real data.
diff --git a/docs/reference/reference.md b/docs/reference/reference.md
index 8e4743e..a6eed8f 100644
--- a/docs/reference/reference.md
+++ b/docs/reference/reference.md
@@ -39,11 +39,12 @@ Technical reference material for the repository tooling that ships with this pro
 - Triggered manually via `workflow_dispatch`
 - Accepts `BUMP_PATCH`, `BUMP_MINOR`, `BUMP_MAJOR`, or `SPECIFIC_VERSION`
 - Resolves the next version from the latest Forgejo release tag
-- Builds `CHANGELOG.md` with towncrier when fragment files exist
+- Builds `CHANGELOG.md` with towncrier when fragment files exist, and commits the consumed fragments back to `main`
+- Bumps the workspace version (`Cargo.toml` + `Cargo.lock`) to the release version in a commit that **only the release tag points at** — `main` deliberately stays at `0.0.0`, so `cargo install --git --tag vX.Y.Z` reports the real version while branch/dev installs report `0.0.0`
+- Tags that bump commit `vX.Y.Z` and pushes the tag itself (the workflow tags manually rather than letting the release API create the tag)
 - Builds `docs-<version>.tar.gz` via `dagger call build-docs --src=. --version=<version>`
 - Executes `.forgejo/scripts/release <version>` if present to stage extra files under `release-assets/`
-- Creates the Forgejo release and uploads the docs tarball plus any extra assets
-- Commits generated changelog updates back to `main` when fragments were consumed
+- Creates the Forgejo release for the pushed tag and uploads the docs tarball plus any extra assets
 
 ## Mise Tasks