diff --git a/CHANGELOG.md b/CHANGELOG.md
index cca06f4..dfc0ffd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,8 @@ All notable changes to the TypeScript package will be documented in this file.
 
 ## [Unreleased]
 
+## [0.21.0] - 2026-05-11
+
 ### Changed
 
 - **Context-pack value scoring and diagnostics**: `selection_strategy: 'value-per-token'` now scores optional candidates with deterministic evidence-aware signals instead of candidate order, and compiled packs can carry `selection_diagnostics` with per-candidate score, density, reasons, and penalties.
diff --git a/README.md b/README.md
index 631b4a1..95e9ba3 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ cd your-project
 graphify-ts generate .          # builds graphify-out/graph.json (no API key, no cloud)
 graphify-ts claude install      # wires Claude Code to use it via MCP
 
-# Or use the opt-in v0.20 SPI pipeline for framework-aware metadata + disk cache:
+# Or use the opt-in SPI pipeline for framework-aware metadata + disk cache:
 graphify-ts generate . --spi
 ```
 
@@ -139,7 +139,7 @@ Full-profile additions: `context_pack`, `context_expand`, `context_prompt`, `con
 
 ```bash
 graphify-ts generate .                          # build the graph
-graphify-ts generate . --spi                    # v0.20 SPI pipeline (framework metadata + disk cache)
+graphify-ts generate . --spi                    # opt-in SPI pipeline (framework metadata + disk cache)
 graphify-ts watch .                             # rebuild on file change
 graphify-ts pack "how does auth work?" --task explain          # compact CLI context payload
 graphify-ts prompt "how does auth work?" --provider claude     # provider-ready compiled prompt
diff --git a/docs/benchmarks/2026-05-11-spi-vs-legacy/README.md b/docs/benchmarks/2026-05-11-spi-vs-legacy/README.md
index e061320..7936f2e 100644
--- a/docs/benchmarks/2026-05-11-spi-vs-legacy/README.md
+++ b/docs/benchmarks/2026-05-11-spi-vs-legacy/README.md
@@ -1,6 +1,6 @@
 # 2026-05-11 — `graphify-ts generate --spi` vs legacy `extract()`
 
-> **Tracking issues:** [#130](https://github.com/mohanagy/graphify-ts/issues/130) and the v0.20 context-compiler payoff follow-up.
+> **Tracking issues:** [#130](https://github.com/mohanagy/graphify-ts/issues/130) and the v0.21 context-compiler payoff follow-up.
 
 ## TL;DR (latest measured run: `results/2026-05-11T163843Z/`)
 
@@ -12,7 +12,7 @@
 | Node count | 29 | 30 | +1 |
 | Total explain-pack tokens (7 prompts, budget 2000) | 330 | 378 | **+14.5%** |
 
-The current v0.20 runtime changes do **not** reduce total explain-pack tokens on this bundled fixture. The benchmark still shows two concrete payoffs:
+The current v0.21 runtime changes do **not** reduce total explain-pack tokens on this bundled fixture. The benchmark still shows two concrete payoffs:
 
 1. `--spi` keeps returning the structurally correct substrate for framework-shaped prompts (`prisma_client`, `trpc_procedure_*`) while legacy still misroutes some of them.
 2. `retrieval_level` is now operational: the same prompt expands from tight seed-only packs at level 1 to materially broader cross-module packs at level 4.
diff --git a/package-lock.json b/package-lock.json
index 06fbb99..d8f0458 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
     "name": "@mohammednagy/graphify-ts",
-    "version": "0.13.3",
+    "version": "0.21.0",
     "lockfileVersion": 3,
     "requires": true,
     "packages": {
         "": {
             "name": "@mohammednagy/graphify-ts",
-            "version": "0.13.3",
+            "version": "0.21.0",
             "hasInstallScript": true,
             "license": "MIT",
             "dependencies": {
diff --git a/package.json b/package.json
index ab6fd89..f144bea 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@mohammednagy/graphify-ts",
-    "version": "0.20.0",
+    "version": "0.21.0",
     "description": "Local context plane and context compiler for AI coding agents. Turn TypeScript/Node workspaces and PR diffs into compact, verifiable context packs for Claude Code, Codex, Copilot, Cursor, and other agents.",
     "license": "MIT",
     "author": "mohanagy",
diff --git a/tests/unit/package-metadata.test.ts b/tests/unit/package-metadata.test.ts
index 0998ac0..0d80f6d 100644
--- a/tests/unit/package-metadata.test.ts
+++ b/tests/unit/package-metadata.test.ts
@@ -10,12 +10,22 @@ interface PackageManifest {
   keywords?: string[]
   license?: string
   overrides?: Record<string, string>
+  version?: string
+}
+
+interface PackageLock {
+  version?: string
+  packages?: Record<string, { version?: string }>
 }
 
 function loadPackageManifest(): PackageManifest {
   return JSON.parse(readFileSync(join(process.cwd(), 'package.json'), 'utf8')) as PackageManifest
 }
 
+function loadPackageLock(): PackageLock {
+  return JSON.parse(readFileSync(join(process.cwd(), 'package-lock.json'), 'utf8')) as PackageLock
+}
+
 function loadDependabotConfig(): string {
   return readFileSync(join(process.cwd(), '.github', 'dependabot.yml'), 'utf8')
 }
@@ -97,6 +107,14 @@ describe('package metadata', () => {
     expect(loadContributingGuide()).toContain("licensed under this project's MIT license")
   })
 
+  it('keeps package.json and package-lock.json on the same release version', () => {
+    const manifest = loadPackageManifest()
+    const packageLock = loadPackageLock()
+
+    expect(packageLock.version).toBe(manifest.version)
+    expect(packageLock.packages?.['']?.version).toBe(manifest.version)
+  })
+
   it('positions package metadata around the context plane and context compiler surface', () => {
     const manifest = loadPackageManifest()
     const readme = loadReadme().toLowerCase()