diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 78eb67d..8e93c4f 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -91,6 +91,24 @@ PRs with invalid commit messages will fail the `commitlint` check.
 See [docs/RELEASING.md](docs/RELEASING.md) for how these commits become tagged
 releases.
 
+## Versioning
+
+The `version` field in `package.json` is intentionally pinned to `0.0.0` and is
+**not** the repository version — **do not edit it by hand**. The source of truth
+for the released version is the latest `vX.Y.Z` git tag together with
+[`.release-please-manifest.json`](.release-please-manifest.json).
+
+Versioning is automated by [release-please](https://github.com/googleapis/release-please).
+The [Conventional Commit](#commit-message-format) types above drive the semver
+bump; release-please opens a **Release PR** that updates the manifest and
+`CHANGELOG.md`, and merging that PR creates the `vX.Y.Z` tag and GitHub Release.
+Because the project uses release-please's `simple` release type, the bump is
+recorded in `.release-please-manifest.json` rather than `package.json` — which
+is exactly why `package.json` stays at `0.0.0`.
+
+See [docs/RELEASING.md](docs/RELEASING.md) for the full flow, the version-bump
+rules, and overrides (e.g. the `Release-As:` footer).
+
 ## Coding Standards
 
 - Follow [WordPress PHP Coding Standards](https://developer.wordpress.org/coding-standards/wordpress-coding-standards/php/)
diff --git a/README.md b/README.md
index 7c6067d..8f9d38d 100644
--- a/README.md
+++ b/README.md
@@ -75,6 +75,8 @@ Site at http://localhost:8080 · Admin at /wp-admin · Database UI at :8081.
 
 **More docs:** [docs/QUICK-START.md](docs/QUICK-START.md) · [LOCAL-DEVELOPMENT.md](LOCAL-DEVELOPMENT.md) · [docs/docker-troubleshooting.md](docs/docker-troubleshooting.md)
 
+> **Versioning:** `package.json` declares `0.0.0` on purpose — the real version lives in git tags + `.release-please-manifest.json`. See [Versioning](CONTRIBUTING.md#versioning) in CONTRIBUTING.md.
+
 <details>
 <summary>Alternative: use as a wp-content directory in an existing WordPress install</summary>