diff --git a/Cargo.lock b/Cargo.lock
index 8dc01a4..558cae2 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -320,7 +320,7 @@ checksum = "df3b46402a9d5adb4c86a0cf463f42e19994e3ee891101b1841f30a545cb49a9"
 
 [[package]]
 name = "hydra-codegen"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "hydra-core",
@@ -333,7 +333,7 @@ dependencies = [
 
 [[package]]
 name = "hydra-core"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "pretty_assertions",
@@ -344,7 +344,7 @@ dependencies = [
 
 [[package]]
 name = "hydra-mcp-stdio"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
  "serde",
  "serde_json",
@@ -466,7 +466,7 @@ dependencies = [
 
 [[package]]
 name = "notes-example"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "axum",
@@ -595,7 +595,7 @@ checksum = "94143f37725109f92c262ed2cf5e59bce7498c01bcc1502d7b9afe439a4e9f49"
 
 [[package]]
 name = "security-scan-example"
-version = "0.1.0"
+version = "0.2.2"
 dependencies = [
  "anyhow",
  "axum",
diff --git a/Cargo.toml b/Cargo.toml
index e931453..33eb7ff 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -9,7 +9,7 @@ members = [
 ]
 
 [workspace.package]
-version = "0.1.0"
+version = "0.2.2"
 edition = "2024"
 license = "MIT"
 repository = "https://github.com/TechGodHQ/hydra"
diff --git a/README.md b/README.md
index f15c49a..e780832 100644
--- a/README.md
+++ b/README.md
@@ -177,6 +177,29 @@ existed.
 - **Selective projection** via `surfaces: [http, mcp]` allowlists, with CLI
   command renames (`cli_command:`) when the public name should differ.
 
+## Releases & versioning
+
+**Status: v0.2.2 is proposed, not published.** The workspace manifests have been
+aligned to `0.2.2` in preparation; no tag, GitHub release, or crates.io
+publication exists yet. A separate task will publish it.
+
+- **Historical tags are immutable.** Tags `v0.1.0` … `v0.2.1` were cut from
+  commits whose workspace manifests still said `0.1.0`; they are reproducible
+  git pins and will never be moved or rewritten. From v0.2.2 onward the
+  manifest version will agree with the tag at the moment of tagging.
+- **What v0.2.2 covers:** merged PRs [#6](https://github.com/TechGodHQ/hydra/pull/6)
+  (DeepSec tracer example), [#7](https://github.com/TechGodHQ/hydra/pull/7)
+  (layered agent context), and [#8](https://github.com/TechGodHQ/hydra/pull/8)
+  (unary cursor pagination fixture) — release metadata, reference coverage,
+  and documentation/context changes. No production changes under `crates/*/src`.
+- **Consumers pin git tags, not crates.io.** hydra is not published to
+  crates.io. Consumers pin a tag and regenerate:
+  `hydra-core = { git = "https://github.com/TechGodHQ/hydra", tag = "v0.2.2" }`
+  (same shape for `hydra-codegen`), then re-run
+  `cargo run -p hydra-codegen -- write` in their own repo and commit the
+  regenerated surfaces. Tag-pin examples become valid **only after the
+  v0.2.2 tag is actually published** — until then pin `v0.2.1`.
+
 ## License
 
 MIT.