diff --git a/CHANGELOG.md b/CHANGELOG.md
index c54c518..b913e27 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.2.1] — Carousel polish (2026-02-28)
+
+### Added
+- CLI reference in `docs/API.md` for `git cas rotate` and `git cas vault rotate` flags.
+
+### Changed
+- Rotation helpers in `CasService` use native `#private` methods, matching the facade's style.
+- `VAULT_CONFLICT` and `VAULT_METADATA_INVALID` error code docs now list `rotateVaultPassphrase()`.
+
+### Fixed
+- `rotateVaultPassphrase` now honours `kdfOptions.algorithm` instead of silently using the old algorithm.
+- Rotation integration test no longer flaps under CI load (reduced test-only KDF iterations).
+
+## [5.2.0] — Carousel (2026-02-28)
+
+### Added
+- **Key rotation without re-encrypting data** — `CasService.rotateKey()` re-wraps the DEK with a new KEK, leaving data blobs untouched. Enables key compromise response without re-storing assets.
+- **`keyVersion` tracking** — manifest-level and per-recipient `keyVersion` counters track rotation history for audit compliance. Optional field, backward-compatible with existing manifests.
+- **`git cas rotate` CLI command** — rotate a recipient's key via `--slug` (vault round-trip) or `--oid` (manifest-only). Supports `--label` for targeted single-recipient rotation.
+- **`rotateVaultPassphrase()`** — rotate the vault-level encryption passphrase across all envelope-encrypted entries in a single atomic commit. Non-envelope entries are skipped with reporting.
+- **`git cas vault rotate` CLI command** — rotate vault passphrase from the command line with `--old-passphrase` and `--new-passphrase`.
+- **`ROTATION_NOT_SUPPORTED` error code** — thrown when `rotateKey()` is called on a manifest without envelope encryption (legacy/direct-key).
+- 27 new unit tests covering key rotation, schema validation, and vault passphrase rotation.
+
 ## [5.1.0] — Locksmith (2026-02-28)
 
 ### Added
diff --git a/COMPLETED_TASKS.md b/COMPLETED_TASKS.md
index 0e736e5..f8f5165 100644
--- a/COMPLETED_TASKS.md
+++ b/COMPLETED_TASKS.md
@@ -17,6 +17,19 @@ Task cards moved here from ROADMAP.md after completion. Organized by milestone.
 
 ---
 
+# M12 — Carousel (v5.2.0) ✅ CLOSED
+
+**Theme:** Key rotation without re-encrypting data. Rotate recipient keys or vault passphrases by re-wrapping the DEK, leaving data blobs untouched.
+
+**Completed:** v5.2.0 (2026-02-28)
+
+- **Task 12.1:** Key rotation workflow — `CasService.rotateKey({ manifest, oldKey, newKey, label? })` unwraps DEK with `oldKey`, re-wraps with `newKey`. Data blobs never accessed. `keyVersion` counter tracks rotation history. Legacy (non-envelope) manifests throw `ROTATION_NOT_SUPPORTED`.
+- **Task 12.2:** Key version tracking in manifest — `keyVersion` field (non-negative integer, default 0) at manifest-level and per-recipient. `rotateKey()` increments both counters. Old manifests without `keyVersion` treated as version 0 (backward compatible).
+- **Task 12.3:** CLI key rotation commands — `git cas rotate --slug <slug> --old-key-file <path> --new-key-file <path> [--label <label>]`. Also supports `--oid <tree-oid>` for manifest-only rotation without vault round-trip.
+- **Task 12.4:** Vault-level key rotation — `rotateVaultPassphrase({ oldPassphrase, newPassphrase, kdfOptions? })` re-wraps every envelope-encrypted entry's DEK in a single atomic commit. `git cas vault rotate` CLI command. CAS retry on `VAULT_CONFLICT`.
+
+---
+
 # M10 — Hydra (v5.0.0) ✅ CLOSED
 
 **Theme:** Content-defined chunking for dramatically better dedup on versioned files.
diff --git a/GUIDE.md b/GUIDE.md
index 5a898e7..be6ea26 100644
--- a/GUIDE.md
+++ b/GUIDE.md
@@ -20,6 +20,7 @@ along from first principles to full mastery.
 9. [Observability](#9-observability)
 10. [Compression](#10-compression)
 11. [Passphrase Encryption (KDF)](#11-passphrase-encryption-kdf)
+11b. [Multi-Recipient Encryption & Key Rotation](#11b-multi-recipient-encryption--key-rotation)
 12. [Merkle Manifests](#12-merkle-manifests)
 13. [Vault](#13-vault)
 14. [Architecture](#14-architecture)
@@ -912,6 +913,73 @@ const manifest = await cas.storeFile({
 
 ---
 
+## 11b. Multi-Recipient Encryption & Key Rotation
+
+*New in v5.1.0 (recipients), v5.2.0 (rotation).*
+
+### Envelope Encryption
+
+Instead of encrypting with a single key, you can encrypt for multiple recipients. A random DEK encrypts the data; each recipient's KEK wraps the DEK:
+
+```javascript
+const manifest = await cas.store({
+  source, slug: 'shared', filename: 'shared.bin',
+  recipients: [
+    { label: 'alice', key: aliceKey },
+    { label: 'bob', key: bobKey },
+  ],
+});
+```
+
+Any recipient can restore independently:
+
+```javascript
+const { buffer } = await cas.restore({ manifest, encryptionKey: bobKey });
+```
+
+### Key Rotation
+
+When a key is compromised, rotate it without re-encrypting data:
+
+```javascript
+const rotated = await cas.rotateKey({
+  manifest, oldKey: aliceOldKey, newKey: aliceNewKey, label: 'alice',
+});
+// Persist the updated manifest
+const treeOid = await cas.createTree({ manifest: rotated });
+```
+
+The `keyVersion` counter increments with each rotation:
+
+```javascript
+console.log(rotated.encryption.keyVersion);           // 1
+console.log(rotated.encryption.recipients[0].keyVersion); // 1
+```
+
+### Vault Passphrase Rotation
+
+Rotate the master passphrase for all vault entries at once:
+
+```javascript
+const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase({
+  oldPassphrase: 'old-secret', newPassphrase: 'new-secret',
+});
+```
+
+Non-envelope entries (direct-key encryption) are skipped — they require manual re-store.
+
+### CLI
+
+```bash
+# Rotate a single recipient's key
+git cas rotate --slug shared --old-key-file old.key --new-key-file new.key --label alice
+
+# Rotate vault passphrase
+git cas vault rotate --old-passphrase old-secret --new-passphrase new-secret
+```
+
+---
+
 ## 12. Merkle Manifests
 
 *New in v2.0.0.*
diff --git a/README.md b/README.md
index 27dc658..af478f5 100644
--- a/README.md
+++ b/README.md
@@ -22,6 +22,7 @@ We use the object database.
 - **Chunked storage** big files become stable, reusable blobs. Fixed-size or content-defined chunking (CDC).
 - **Optional AES-256-GCM encryption** store secrets without leaking plaintext into the ODB.
 - **Multi-recipient encryption** envelope model (DEK/KEK) — add/remove access without re-encrypting data.
+- **Key rotation** rotate keys without re-encrypting data blobs. Respond to compromise in seconds.
 - **Compression** gzip before encryption — smaller blobs, same round-trip.
 - **Passphrase encryption** derive keys from passphrases via PBKDF2 or scrypt — no raw key management.
 - **Merkle manifests** large files auto-split into sub-manifests for scalability.
@@ -37,6 +38,32 @@ We use the object database.
 
 <img src="./docs/demo.gif" alt="git-cas demo" />
 
+## What's new in v5.2.0
+
+**Key rotation without re-encrypting data** — Rotate a recipient's key by re-wrapping the DEK. Data blobs are never touched. Respond to key compromise in seconds, not hours.
+
+```js
+// Rotate a single recipient's key
+const rotated = await cas.rotateKey({
+  manifest, oldKey: aliceOldKey, newKey: aliceNewKey, label: 'alice',
+});
+
+// Rotate the vault passphrase (all entries, atomic commit)
+const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase({
+  oldPassphrase: 'old-secret', newPassphrase: 'new-secret',
+});
+```
+
+```bash
+# Rotate a recipient key
+git cas rotate --slug prod-secrets --old-key-file old.key --new-key-file new.key
+
+# Rotate vault passphrase
+git cas vault rotate --old-passphrase old-secret --new-passphrase new-secret
+```
+
+See [CHANGELOG.md](./CHANGELOG.md) for the full list of changes.
+
 ## What's new in v5.1.0
 
 **Multi-recipient envelope encryption** — Each file is encrypted with a random DEK; recipient KEKs wrap the DEK. Add or remove team members without re-encrypting data.
@@ -225,6 +252,13 @@ git cas recipient list shared
 git cas recipient add shared --label carol --key-file ./keys/carol.key --existing-key-file ./keys/alice.key
 git cas recipient remove shared --label bob
 
+# Key rotation (no re-encryption)
+git cas rotate --slug shared --old-key-file old.key --new-key-file new.key
+git cas rotate --slug shared --old-key-file old.key --new-key-file new.key --label alice
+
+# Vault passphrase rotation
+git cas vault rotate --old-passphrase old-secret --new-passphrase new-secret
+
 # Encrypted vault round-trip (passphrase via env var or --vault-passphrase flag)
 export GIT_CAS_PASSPHRASE="secret"
 git cas vault init
@@ -254,7 +288,7 @@ That's git-cas. The orphan branch gives you none of:
 
 | | Orphan branch | git-cas |
 |---|---|---|
-| **Encryption** | None — plaintext forever in history | AES-256-GCM + passphrase KDF + multi-recipient |
+| **Encryption** | None — plaintext forever in history | AES-256-GCM + passphrase KDF + multi-recipient + key rotation |
 | **Large files** | Bloats `git clone` for everyone | Chunked, restored on demand |
 | **Dedup** | None | Chunk-level content addressing |
 | **Integrity** | Git SHA-1 | SHA-256 per chunk + GCM auth tag |
diff --git a/ROADMAP.md b/ROADMAP.md
index a42a8aa..cdf9173 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -138,29 +138,29 @@ Return and throw semantics for every public method (current and planned).
 - **Throws:** `CasError('MISSING_KEY')` if encrypted and no key provided.
 - **Memory:** O(chunkSize) — never buffers full file.
 
-### `rotateKey({ manifest, oldKey, newKey, label? })` *(planned — Task 12.1)*
+### `rotateKey({ manifest, oldKey, newKey, label? })` *(implemented — v5.2.0)*
 - **Returns:** `Promise<Manifest>` — updated manifest with re-wrapped DEK and incremented `keyVersion`.
 - **Throws:** `CasError('DEK_UNWRAP_FAILED')` if `oldKey` cannot unwrap the DEK.
 - **Throws:** `CasError('ROTATION_NOT_SUPPORTED')` if manifest uses legacy (non-envelope) encryption.
 - **Side effects:** None. Caller must persist via `createTree()`.
 
-### `addRecipient({ manifest, existingKey, newRecipientKey, label })` *(planned — Task 11.2)*
+### `addRecipient({ manifest, existingKey, newRecipientKey, label })` *(implemented — v5.1.0)*
 - **Returns:** `Promise<Manifest>` — updated manifest with additional recipient entry.
 - **Throws:** `CasError('DEK_UNWRAP_FAILED')` if `existingKey` is wrong.
 - **Throws:** `CasError('RECIPIENT_ALREADY_EXISTS')` if `label` already exists.
 - **Side effects:** None. Caller must persist.
 
-### `removeRecipient({ manifest, label })` *(planned — Task 11.2)*
+### `removeRecipient({ manifest, label })` *(implemented — v5.1.0)*
 - **Returns:** `Promise<Manifest>` — updated manifest without the named recipient.
 - **Throws:** `CasError('RECIPIENT_NOT_FOUND')` if `label` not in recipient list.
 - **Throws:** `CasError('CANNOT_REMOVE_LAST_RECIPIENT')` if only 1 recipient remains.
 
-### CLI: `git cas verify --oid <tree-oid> | --slug <slug>` *(planned — Task 9.2)*
+### CLI: `git cas verify --oid <tree-oid> | --slug <slug>` *(implemented — v4.0.1)*
 - **Output:** `ok` on success, `fail` on failure.
 - **Exit 0:** All chunks verified.
 - **Exit 1:** Verification failed or error.
 
-### CLI: `git cas rotate --slug <slug> --old-key-file <path> --new-key-file <path>` *(planned — Task 12.3)*
+### CLI: `git cas rotate --slug <slug> --old-key-file <path> --new-key-file <path>` *(implemented — v5.2.0)*
 - **Output:** New tree OID on success.
 - **Exit 0:** Rotation succeeded, vault updated.
 - **Exit 1:** Wrong old key, unsupported manifest, or vault error.
@@ -191,7 +191,7 @@ Return and throw semantics for every public method (current and planned).
 | v3.1.0  | M13       | Bijou    | TUI dashboard & progress | ✅ |
 | v5.0.0  | M10       | Hydra    | Content-defined chunking | ✅ |
 | v5.1.0  | M11       | Locksmith | Multi-recipient encryption | ✅ |
-| v5.2.0  | M12       | Carousel | Key rotation | |
+| v5.2.0  | M12       | Carousel | Key rotation | ✅ |
 
 ---
 
@@ -205,7 +205,7 @@ M8 Spit Shine + M9 Cockpit (v4.0.1) ✅
 
 M10 Hydra ──────────── ✅ v5.0.0
 M11 Locksmith ──────── ✅ v5.1.0
-  └──► M12 Carousel ── (ready)
+  └──► M12 Carousel ── ✅ v5.2.0
 ```
 
 ---
@@ -222,7 +222,7 @@ M11 Locksmith ──────── ✅ v5.1.0
 | M9 | Cockpit       | CLI improvements           | v4.0.1  | 4     | ~190   | ~5h   | ✅ CLOSED |
 | M10| Hydra         | Content-defined chunking   | v5.0.0  | 4     | ~690   | ~22h  | ✅ CLOSED |
 | M11| Locksmith     | Multi-recipient encryption | v5.1.0  | 4     | ~580   | ~20h  | ✅ CLOSED |
-| M12| Carousel      | Key rotation               | v5.2.0  | 4     | ~400   | ~13h  | open |
+| M12| Carousel      | Key rotation               | v5.2.0  | 4     | ~400   | ~13h  | ✅ CLOSED |
 
 Completed task cards are in [COMPLETED_TASKS.md](./COMPLETED_TASKS.md). Superseded tasks are in [GRAVEYARD.md](./GRAVEYARD.md).
 
@@ -256,223 +256,9 @@ All tasks completed (11.1–11.4). See [COMPLETED_TASKS.md](./COMPLETED_TASKS.md
 
 ---
 
-# M12 — Carousel (v5.2.0)
-**Theme:** Key rotation without re-encrypting data. The DEK/KEK model from M11 makes this possible — rotating a key means re-wrapping the DEK, not re-encrypting blobs. Includes vault-level rotation for changing the master passphrase.
+# M12 — Carousel (v5.2.0) ✅ CLOSED
 
----
-
-## Task 12.1: Key rotation workflow
-
-**User Story**
-As an operator, I want to rotate encryption keys without re-encrypting the actual data, so key compromise doesn't require re-storing all assets.
-
-**Requirements**
-- R1: Add `CasService.rotateKey({ manifest, oldKey, newKey, label? })`.
-- R2: Unwrap DEK using `oldKey`, re-wrap with `newKey`, update recipient entry (or all entries if no label specified).
-- R3: Return updated Manifest. Caller must persist via `createTree()` + vault update.
-- R4: Data blobs are never re-read or re-encrypted — only the DEK wrapping changes.
-- R5: Track rotation with `keyVersion` counter in manifest encryption metadata.
-- R6: If the manifest uses legacy (non-envelope) encryption, throw `ROTATION_NOT_SUPPORTED` with hint to re-store using envelope encryption.
-
-**Acceptance Criteria**
-- AC1: rotateKey → restore with new key succeeds, old key fails.
-- AC2: `keyVersion` increments after rotation.
-- AC3: Data blobs are never accessed during rotation (spy: zero readBlob calls).
-- AC4: Legacy manifest → `ROTATION_NOT_SUPPORTED` error.
-
-**Scope**
-- In scope: Key rotation method + key version tracking.
-- Out of scope: Automatic vault-wide rotation (Task 12.4), key version history/audit log, scheduled rotation policies.
-
-**Est. Complexity (LoC)**
-- Prod: ~80 (rotation logic + version tracking)
-- Tests: ~60 (round-trip, old-key-fails, version increment, legacy error)
-- Total: ~140
-
-**Est. Human Working Hours**
-- ~5h
-
-**Test Plan**
-- Golden path:
-  - Store → rotateKey → restore with new key → byte-compare original.
-  - Verify old key no longer works after rotation.
-  - Verify keyVersion incremented.
-- Failures:
-  - rotateKey with wrong oldKey → DEK_UNWRAP_FAILED.
-  - rotateKey on legacy manifest → ROTATION_NOT_SUPPORTED.
-- Edges:
-  - Rotate twice → keyVersion = 2, both old keys fail.
-  - Rotate with label → only that recipient updated, others unchanged.
-- Fuzz/stress:
-  - 20 sequential rotations → final key works, all 19 previous keys fail, keyVersion = 20.
-
-**Definition of Done**
-- DoD1: rotateKey implemented and exposed via facade.
-- DoD2: keyVersion tracking in manifest.
-- DoD3: Legacy manifest guard in place.
-- DoD4: Security implications documented in SECURITY.md.
-
-**Blocking**
-- Blocks: Task 12.3, Task 12.4
-
-**Blocked By**
-- Blocked by: Task 11.1
-
----
-
-## Task 12.2: Key version tracking in manifest
-
-**User Story**
-As a security auditor, I want to see which key version was used for each recipient so I can verify rotation compliance.
-
-**Requirements**
-- R1: Add `keyVersion` field (non-negative integer, default 0) to manifest `encryption` metadata.
-- R2: Each recipient entry carries `keyVersion` indicating which KEK version was used to wrap the DEK.
-- R3: `rotateKey()` increments manifest-level `keyVersion` and updates the rotated recipient's `keyVersion`.
-- R4: Extend ManifestSchema `EncryptionSchema` to include optional `keyVersion` field.
-- R5: Old manifests without `keyVersion` treated as version 0 (backward compatible).
-
-**Acceptance Criteria**
-- AC1: New manifests include `keyVersion: 0` by default (or omit for backward compat).
-- AC2: After rotation, manifest `keyVersion` increments.
-- AC3: Each recipient's `keyVersion` reflects when their wrapping was last updated.
-- AC4: Old manifests without `keyVersion` read correctly (treated as 0).
-
-**Scope**
-- In scope: Schema extension + version tracking logic.
-- Out of scope: Version history/audit log, policy enforcement (e.g., "rotate after N days"), automated compliance checks.
-
-**Est. Complexity (LoC)**
-- Prod: ~30 (schema + version logic in rotateKey)
-- Tests: ~40 (version increment, backward compat, per-recipient version)
-- Total: ~70
-
-**Est. Human Working Hours**
-- ~2h
-
-**Test Plan**
-- Golden path:
-  - Store → keyVersion 0. Rotate → keyVersion 1.
-- Failures:
-  - Manually set negative keyVersion → schema rejects.
-- Edges:
-  - Old manifest with no keyVersion → treated as 0.
-  - Multi-recipient: rotate one recipient → only that recipient's keyVersion changes.
-- Fuzz/stress:
-  - 100 sequential version increments → correct final version value.
-
-**Definition of Done**
-- DoD1: keyVersion in schema and runtime.
-- DoD2: Version tracking tested.
-- DoD3: Backward compatibility verified.
-
-**Blocking**
-- Blocks: None
-
-**Blocked By**
-- Blocked by: Task 11.1 (needs recipients in schema)
-
----
-
-## Task 12.3: CLI key rotation commands
-
-**User Story**
-As an operator, I want to rotate keys from the command line so I can perform routine key maintenance without writing scripts.
-
-**Requirements**
-- R1: Add `git cas rotate --slug <slug> --old-key-file <path> --new-key-file <path> [--label <label>]`.
-- R2: Reads manifest from vault, calls `rotateKey()`, persists updated manifest (createTree + vault update with `--force`).
-- R3: Prints new tree OID on success.
-- R4: Add `--oid <tree-oid>` as alternative to `--slug` (prints updated manifest, doesn't touch vault).
-
-**Acceptance Criteria**
-- AC1: `git cas rotate --slug myfile --old-key-file old.key --new-key-file new.key` → vault updated.
-- AC2: Subsequent restore with new key succeeds; old key fails.
-- AC3: keyVersion printed or included in JSON output.
-
-**Scope**
-- In scope: `rotate` CLI command.
-- Out of scope: Interactive key generation, passphrase-based rotation (use `vault rotate` for that).
-
-**Est. Complexity (LoC)**
-- Prod: ~50 (new subcommand)
-- Tests: ~30
-- Total: ~80
-
-**Est. Human Working Hours**
-- ~2h
-
-**Test Plan**
-- Golden path:
-  - Store → rotate via CLI → restore with new key → success.
-- Failures:
-  - Wrong old key → exit 1 with DEK_UNWRAP_FAILED.
-  - Legacy (non-envelope) manifest → exit 1 with ROTATION_NOT_SUPPORTED.
-- Edges:
-  - Rotate with --label → only named recipient updated.
-- Fuzz/stress:
-  - None (thin wrapper over tested API).
-
-**Definition of Done**
-- DoD1: `rotate` command added.
-- DoD2: Full CLI round-trip tested.
-
-**Blocking**
-- Blocks: None
-
-**Blocked By**
-- Blocked by: Task 12.1
-
----
-
-## Task 12.4: Vault-level key rotation
-
-**User Story**
-As an operator, I want to rotate the vault passphrase so a compromised passphrase can be revoked without re-storing all assets.
-
-**Requirements**
-- R1: Add `ContentAddressableStore.rotateVaultPassphrase({ oldPassphrase, newPassphrase, kdfOptions? })`.
-- R2: Derive old KEK from `oldPassphrase` + stored KDF params. Derive new KEK from `newPassphrase` (new salt, optionally new algorithm).
-- R3: For each vault entry with envelope encryption: unwrap DEK with old KEK, re-wrap with new KEK.
-- R4: Update vault metadata with new KDF params (new salt, potentially new algorithm/iterations).
-- R5: Atomic: all entries rotated in a single vault commit. CAS retry on conflict.
-- R6: Add `git cas vault rotate --old-passphrase <old> --new-passphrase <new> [--algorithm <alg>]` CLI command.
-
-**Acceptance Criteria**
-- AC1: After rotation, all entries restorable with new passphrase.
-- AC2: Old passphrase no longer works for any entry.
-- AC3: Vault metadata updated with new KDF params.
-- AC4: Atomic: partial rotation never committed (all-or-nothing).
-
-**Scope**
-- In scope: Vault-level rotation API + CLI command.
-- Out of scope: Per-entry passphrase rotation (use Task 12.1), online rotation (vault is locked during rotation), rollback on failure.
-
-**Est. Complexity (LoC)**
-- Prod: ~60 (rotation logic + CLI command)
-- Tests: ~50 (round-trip, atomicity, backward compat)
-- Total: ~110
-
-**Est. Human Working Hours**
-- ~4h
-
-**Test Plan**
-- Golden path:
-  - Init vault with passphrase A → store 3 entries → rotate to passphrase B → restore all 3 with B.
-- Failures:
-  - Wrong old passphrase → exit 1 with DEK_UNWRAP_FAILED.
-  - Concurrent vault update during rotation → CAS retry or VAULT_CONFLICT.
-- Edges:
-  - Vault with no encrypted entries → metadata updated, no DEK rotation needed.
-  - Vault with 1 entry → atomic commit with single rotation.
-- Fuzz/stress:
-  - Rotate 10 times sequentially → final passphrase works, all 9 prior fail.
-
-**Definition of Done**
-- DoD1: Vault rotation implemented and exposed via facade.
-- DoD2: CLI command added.
-- DoD3: Atomicity verified (no partial rotations).
-- DoD4: SECURITY.md updated with vault rotation guidance.
+All tasks completed (12.1–12.4). See [COMPLETED_TASKS.md](./COMPLETED_TASKS.md).
 
 ---
 
@@ -512,8 +298,8 @@ Competitive landscape for content-addressed storage, encrypted binary assets, an
 | Client-side encryption | ✅ AES-256-GCM | — | ❌ | ✅ GPG | ✅ AES-256-CTR + Poly1305 | ✅ ChaCha20-Poly1305 | ❌ | Protect data at rest in untrusted storage | git-cas is the only Git-native tool with integrated encryption | — |
 | Authenticated encryption (AEAD) | ✅ GCM auth tag | — | ❌ | ⚠️ GPG signature optional | ✅ Poly1305 | ✅ Poly1305 | ❌ | Tamper detection + confidentiality | GCM and Poly1305 both provide authentication. GPG can but doesn't by default | — |
 | Per-chunk encryption | ✅ Streaming | — | ❌ | ❌ Whole-file | ❌ Per-pack | ✅ 64 KiB chunks | ❌ | Encrypt without buffering full file | git-cas and Age both stream; Restic encrypts packed blobs | — |
-| Multi-recipient encryption | ❌ | ✅ M11 Locksmith | ❌ | ✅ Multiple GPG keys | ✅ Multiple passwords | ✅ Multiple X25519 | ❌ | Team access without sharing a single key | Envelope encryption (DEK/KEK model). ~220 LoC, ~8h (Task 11.1) | DEK/KEK model + recipient management. ~580 LoC total, ~20h (M11) |
-| Key rotation (no re-encrypt) | ❌ | 🗓 M12 Carousel | N/A | ⚠️ Can add keys; revoke requires re-encrypt | ✅ Re-wrap master key | ❌ | N/A | Respond to key compromise without re-storing data | Requires DEK/KEK model. Re-wraps DEK, data blobs untouched | Depends on M11. rotateKey + vault rotation. ~400 LoC, ~13h (M12) |
+| Multi-recipient encryption | ✅ M11 Locksmith | — | ❌ | ✅ Multiple GPG keys | ✅ Multiple passwords | ✅ Multiple X25519 | ❌ | Team access without sharing a single key | Envelope encryption (DEK/KEK model) | — |
+| Key rotation (no re-encrypt) | ✅ M12 Carousel | — | N/A | ⚠️ Can add keys; revoke requires re-encrypt | ✅ Re-wrap master key | ❌ | N/A | Respond to key compromise without re-storing data | Re-wraps DEK, data blobs untouched | — |
 | KDF / passphrase keys | ✅ PBKDF2, scrypt | — | ❌ | ✅ GPG S2K | ✅ scrypt | ✅ scrypt | ❌ | Derive keys from passwords instead of managing raw bytes | git-cas supports both PBKDF2 (100k iterations) and scrypt | — |
 | Argon2 KDF | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | ❌ | Memory-hard KDF resists GPU/ASIC attacks | No tool in this space supports Argon2 yet. Would require native/WASM addon | ~80 LoC + native dep. ~4h. Low priority — scrypt is adequate |
 | Hardware security (YubiKey/HSM) | ❌ | ❌ | ❌ | ✅ GPG smartcard | ❌ | ✅ age-plugin-yubikey | ❌ | Keys never leave hardware token | Would require plugin system or GPG integration | Plugin architecture + PIV applet integration. ~300 LoC, ~16h. Low priority |
@@ -568,9 +354,9 @@ Competitive landscape for content-addressed storage, encrypted binary assets, an
 | Multi-runtime support | ✅ Node, Bun, Deno | — | ❌ Go only | ❌ Haskell only | ❌ Go only | ✅ Go, Rust, JS, Java, Python | ❌ Python only | Same library works across JS runtimes | Only git-cas and Age support multiple runtimes | — |
 | Progress events (structured) | ✅ ObservabilityPort (metric/log/span) | — | ✅ Transfer protocol | ⚠️ Terminal bars | ✅ JSON Lines | ❌ | ⚠️ Terminal bars | Build progress bars, logging, monitoring | git-cas emits typed metrics per chunk via ObservabilityPort (v4.0.0) | — |
 | CLI progress feedback | ✅ Animated (bijou) | — | ✅ | ✅ | ✅ | ❌ | ✅ | Users know operations are working | Implemented in v3.1.0 (M13 Bijou) | — |
-| Structured output (--json) | ❌ | 🗓 M9 Cockpit | ❌ | ❌ | ✅ `--json` | ❌ | ✅ `--json` | CI/CD pipeline integration | Restic is the gold standard here (JSON Lines for all output) | Global `--json` flag. ~50 LoC, ~1.5h (Task 9.3) |
-| CLI `verify` command | ❌ API only | 🗓 M9 Cockpit | ✅ Implicit on checkout | ✅ `annex fsck` | ✅ `restic check` | ❌ | ✅ `dvc check-ignore` | Audit integrity without restoring | API exists (`verifyIntegrity`); CLI just needs to expose it | 25 LoC, ~1h (Task 9.2) |
-| Actionable error messages | ❌ Generic `err.message` | 🗓 M9 Cockpit | ⚠️ | ⚠️ | ✅ | ❌ | ✅ | Users know what went wrong and what to do next | Error codes exist but CLI doesn't show hints | Error handler + hint map. ~45 LoC, ~1h (Task 9.4) |
+| Structured output (--json) | ✅ `--json` | — | ❌ | ❌ | ✅ `--json` | ❌ | ✅ `--json` | CI/CD pipeline integration | Global `--json` flag on all commands | — |
+| CLI `verify` command | ✅ `git cas verify` | — | ✅ Implicit on checkout | ✅ `annex fsck` | ✅ `restic check` | ❌ | ✅ `dvc check-ignore` | Audit integrity without restoring | Per-chunk SHA-256 verification | — |
+| Actionable error messages | ✅ Hints | — | ⚠️ | ⚠️ | ✅ | ❌ | ✅ | Users know what went wrong and what to do next | Error codes + actionable hint map | — |
 
 ---
 
@@ -593,7 +379,7 @@ Competitive landscape for content-addressed storage, encrypted binary assets, an
 |---|---|---|---|---|---|---|
 | **Core identity** | Git-native CAS with encryption | Git large file offloading | Distributed file management | Encrypted backup with dedup | File encryption primitive | ML data version control |
 | **Strongest at** | Git ODB integration, pluggable codecs, Merkle manifests, vault | Simplicity, file locking, ecosystem adoption | Backend diversity, location tracking, metadata views | CDC dedup, retention policies, FUSE mount | Multi-recipient, HSM, multi-language, simplicity | ML pipelines, experiment tracking, Python ecosystem |
-| **Weakest at** | No multi-backend, single-key encryption, gzip only, no CDC | No encryption, no compression, requires server | Complexity, Haskell-only, no CDC | No Git integration, no library API | Not a storage system | No encryption, no chunking, no streaming |
+| **Weakest at** | No multi-backend, gzip only | No encryption, no compression, requires server | Complexity, Haskell-only, no CDC | No Git integration, no library API | Not a storage system | No encryption, no chunking, no streaming |
 | **Server required** | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
 | **Best use case** | Encrypted binary assets in Git repos | Large files in GitHub/GitLab repos | Distributed archive management | Encrypted backups of filesystems | Encrypting files for recipients | ML model/data versioning |
 
diff --git a/bin/actions.js b/bin/actions.js
index 444b0c8..c4d58ec 100644
--- a/bin/actions.js
+++ b/bin/actions.js
@@ -13,6 +13,7 @@ const HINTS = {
   RECIPIENT_NOT_FOUND: 'No recipient with that label exists in the manifest',
   RECIPIENT_ALREADY_EXISTS: 'A recipient with that label already exists',
   CANNOT_REMOVE_LAST_RECIPIENT: 'At least one recipient must remain in the manifest',
+  ROTATION_NOT_SUPPORTED: 'Key rotation requires envelope encryption — store with --recipient first',
 };
 
 /**
diff --git a/bin/git-cas.js b/bin/git-cas.js
index 3ef0491..f572745 100755
--- a/bin/git-cas.js
+++ b/bin/git-cas.js
@@ -18,7 +18,7 @@ const getJson = () => program.opts().json;
 program
   .name('git-cas')
   .description('Content Addressable Storage backed by Git')
-  .version('5.0.0')
+  .version('5.2.1')
   .option('-q, --quiet', 'Suppress progress output')
   .option('--json', 'Output results as JSON');
 
@@ -429,6 +429,40 @@ vault
     }
   }, getJson));
 
+// ---------------------------------------------------------------------------
+// vault rotate
+// ---------------------------------------------------------------------------
+vault
+  .command('rotate')
+  .description('Rotate vault-level encryption passphrase')
+  .requiredOption('--old-passphrase <pass>', 'Current vault passphrase')
+  .requiredOption('--new-passphrase <pass>', 'New vault passphrase')
+  .option('--algorithm <alg>', 'KDF algorithm (pbkdf2 or scrypt)')
+  .option('--cwd <dir>', 'Git working directory', '.')
+  .action(runAction(async (opts) => {
+    const cas = createCas(opts.cwd);
+    const rotateOpts = {
+      oldPassphrase: opts.oldPassphrase,
+      newPassphrase: opts.newPassphrase,
+    };
+    if (opts.algorithm) {
+      rotateOpts.kdfOptions = { algorithm: opts.algorithm };
+    }
+    const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase(rotateOpts);
+    const json = program.opts().json;
+    if (json) {
+      process.stdout.write(`${JSON.stringify({ commitOid, rotatedSlugs, skippedSlugs })}\n`);
+    } else {
+      process.stdout.write(`${commitOid}\n`);
+      if (rotatedSlugs.length) {
+        process.stderr.write(`rotated: ${rotatedSlugs.join(', ')}\n`);
+      }
+      if (skippedSlugs.length) {
+        process.stderr.write(`skipped: ${skippedSlugs.join(', ')}\n`);
+      }
+    }
+  }, getJson));
+
 // ---------------------------------------------------------------------------
 // vault dashboard
 // ---------------------------------------------------------------------------
@@ -442,6 +476,48 @@ vault
     await launchDashboard(cas);
   }, getJson));
 
+// ---------------------------------------------------------------------------
+// rotate
+// ---------------------------------------------------------------------------
+program
+  .command('rotate')
+  .description('Rotate an encryption key without re-encrypting data')
+  .option('--slug <slug>', 'Resolve tree OID from vault slug')
+  .option('--oid <tree-oid>', 'Direct tree OID')
+  .requiredOption('--old-key-file <path>', 'Path to current 32-byte key file')
+  .requiredOption('--new-key-file <path>', 'Path to new 32-byte key file')
+  .option('--label <label>', 'Rotate only the named recipient')
+  .option('--cwd <dir>', 'Git working directory', '.')
+  .action(runAction(async (opts) => {
+    validateRestoreFlags(opts);
+    const cas = createCas(opts.cwd);
+    const treeOid = opts.oid || await cas.resolveVaultEntry({ slug: opts.slug });
+    const manifest = await cas.readManifest({ treeOid });
+
+    const oldKey = readKeyFile(opts.oldKeyFile);
+    const newKey = readKeyFile(opts.newKeyFile);
+
+    const rotateOpts = { manifest, oldKey, newKey };
+    if (opts.label) { rotateOpts.label = opts.label; }
+
+    const updated = await cas.rotateKey(rotateOpts);
+    const json = program.opts().json;
+
+    if (opts.slug) {
+      const newTreeOid = await cas.createTree({ manifest: updated });
+      await cas.addToVault({ slug: opts.slug, treeOid: newTreeOid, force: true });
+      if (json) {
+        process.stdout.write(`${JSON.stringify({ treeOid: newTreeOid, keyVersion: updated.encryption.keyVersion })}\n`);
+      } else {
+        process.stdout.write(`${newTreeOid}\n`);
+      }
+    } else if (json) {
+      process.stdout.write(`${JSON.stringify(updated.toJSON())}\n`);
+    } else {
+      process.stdout.write(`${JSON.stringify(updated.toJSON(), null, 2)}\n`);
+    }
+  }, getJson));
+
 // ---------------------------------------------------------------------------
 // recipient add / remove / list
 // ---------------------------------------------------------------------------
diff --git a/docs/API.md b/docs/API.md
index dcbf5a8..a55f02e 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -465,6 +465,72 @@ Decrypts a buffer using AES-256-GCM.
 const decrypted = await cas.decrypt({ buffer: buf, key, meta });
 ```
 
+#### rotateKey
+
+```javascript
+await cas.rotateKey({ manifest, oldKey, newKey, label })
+```
+
+Rotates a recipient's encryption key without re-encrypting data blobs. Unwraps the DEK with `oldKey`, re-wraps with `newKey`, and increments `keyVersion` counters.
+
+**Parameters:**
+
+- `manifest` (required): `Manifest` - Envelope-encrypted manifest
+- `oldKey` (required): `Buffer` - Current 32-byte KEK
+- `newKey` (required): `Buffer` - New 32-byte KEK
+- `label` (optional): `string` - If provided, only rotate the named recipient
+
+**Returns:** `Promise<Manifest>` - Updated manifest with re-wrapped DEK and incremented `keyVersion`
+
+**Throws:**
+
+- `CasError` with code `ROTATION_NOT_SUPPORTED` if manifest has no recipients (legacy/unencrypted)
+- `CasError` with code `RECIPIENT_NOT_FOUND` if `label` doesn't exist
+- `CasError` with code `DEK_UNWRAP_FAILED` if `oldKey` doesn't match the recipient
+- `CasError` with code `NO_MATCHING_RECIPIENT` if no label is provided and `oldKey` matches no entry
+
+**Example:**
+
+```javascript
+const rotated = await cas.rotateKey({
+  manifest, oldKey: aliceOldKey, newKey: aliceNewKey, label: 'alice',
+});
+const treeOid = await cas.createTree({ manifest: rotated });
+await cas.addToVault({ slug: 'my-asset', treeOid, force: true });
+```
+
+#### rotateVaultPassphrase
+
+```javascript
+await cas.rotateVaultPassphrase({ oldPassphrase, newPassphrase, kdfOptions })
+```
+
+Rotates the vault-level encryption passphrase. Re-wraps every envelope-encrypted entry's DEK with a new KEK derived from `newPassphrase`. Non-envelope entries are skipped.
+
+**Parameters:**
+
+- `oldPassphrase` (required): `string` - Current vault passphrase
+- `newPassphrase` (required): `string` - New vault passphrase
+- `kdfOptions` (optional): `Object` - KDF options for new passphrase (e.g., `{ algorithm: 'scrypt' }`)
+
+**Returns:** `Promise<{ commitOid: string, rotatedSlugs: string[], skippedSlugs: string[] }>`
+
+**Throws:**
+
+- `CasError` with code `VAULT_METADATA_INVALID` if vault is not encrypted
+- `CasError` with code `DEK_UNWRAP_FAILED` or `NO_MATCHING_RECIPIENT` if old passphrase is wrong
+- `CasError` with code `VAULT_CONFLICT` if concurrent vault updates exhaust retries
+
+**Example:**
+
+```javascript
+const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase({
+  oldPassphrase: 'old-secret', newPassphrase: 'new-secret',
+});
+console.log(`Rotated: ${rotatedSlugs.join(', ')}`);
+console.log(`Skipped: ${skippedSlugs.join(', ')}`);
+```
+
 ### Properties
 
 #### chunkSize
@@ -716,8 +782,46 @@ git cas vault info <slug>                        # Show slug + tree OID
 git cas vault remove <slug>                      # Remove an entry
 git cas vault history                            # Show commit history
 git cas vault history -n 10                      # Last N commits
+git cas vault rotate --old-passphrase "old" --new-passphrase "new"
+git cas vault rotate --old-passphrase "old" --new-passphrase "new" --algorithm scrypt
 ```
 
+### CLI Key Rotation Commands
+
+```bash
+# Rotate a single asset's key (by vault slug)
+git cas rotate --slug demo/hello \
+  --old-key-file old.key --new-key-file new.key
+
+# Rotate a single asset's key (by tree OID)
+git cas rotate --oid <tree-oid> \
+  --old-key-file old.key --new-key-file new.key
+
+# Rotate only a named recipient
+git cas rotate --slug demo/hello \
+  --old-key-file old.key --new-key-file new.key --label alice
+```
+
+#### `git cas rotate` flags
+
+| Flag | Description |
+|------|-------------|
+| `--slug <slug>` | Resolve tree OID from vault slug (updates vault entry) |
+| `--oid <tree-oid>` | Direct tree OID (outputs updated manifest) |
+| `--old-key-file <path>` | Path to current 32-byte key file (required) |
+| `--new-key-file <path>` | Path to new 32-byte key file (required) |
+| `--label <label>` | Only rotate the named recipient entry |
+| `--cwd <dir>` | Git working directory (default: `.`) |
+
+#### `git cas vault rotate` flags
+
+| Flag | Description |
+|------|-------------|
+| `--old-passphrase <pass>` | Current vault passphrase (required) |
+| `--new-passphrase <pass>` | New vault passphrase (required) |
+| `--algorithm <alg>` | KDF algorithm for new passphrase (`pbkdf2` or `scrypt`) |
+| `--cwd <dir>` | Git working directory (default: `.`) |
+
 ### Vault History
 
 The vault maintains a full commit history via `refs/cas/vault`. Each mutation (add, remove, init) creates a new commit. Use `vault history` (or `git log refs/cas/vault`) to inspect the audit trail.
@@ -1380,9 +1484,15 @@ new CasError(message, code, meta)
 | `INVALID_SLUG` | Slug fails validation (empty, control chars, `..` segments, etc.) | `addToVault()` |
 | `VAULT_ENTRY_NOT_FOUND` | Slug does not exist in vault | `removeFromVault()`, `resolveVaultEntry()` |
 | `VAULT_ENTRY_EXISTS` | Slug already exists (use `force` to overwrite) | `addToVault()` |
-| `VAULT_CONFLICT` | Concurrent vault update detected (CAS failure after retries) | `addToVault()`, `removeFromVault()`, `initVault()` |
-| `VAULT_METADATA_INVALID` | `.vault.json` malformed, unknown version, or missing required fields | `readState()` |
+| `VAULT_CONFLICT` | Concurrent vault update detected (CAS failure after retries) | `addToVault()`, `removeFromVault()`, `initVault()`, `rotateVaultPassphrase()` |
+| `VAULT_METADATA_INVALID` | `.vault.json` malformed, unknown version, or missing required fields | `readState()`, `rotateVaultPassphrase()` |
 | `VAULT_ENCRYPTION_ALREADY_CONFIGURED` | Cannot reconfigure encryption without key rotation | `initVault()` |
+| `NO_MATCHING_RECIPIENT` | No recipient entry matches the provided KEK | `restore()`, `rotateKey()` |
+| `DEK_UNWRAP_FAILED` | Failed to unwrap DEK with the provided KEK | `addRecipient()`, `rotateKey()` |
+| `RECIPIENT_NOT_FOUND` | Recipient label not found in manifest | `removeRecipient()`, `rotateKey()` |
+| `RECIPIENT_ALREADY_EXISTS` | Recipient label already exists | `addRecipient()` |
+| `CANNOT_REMOVE_LAST_RECIPIENT` | Cannot remove the last recipient | `removeRecipient()` |
+| `ROTATION_NOT_SUPPORTED` | Key rotation requires envelope encryption (recipients) | `rotateKey()` |
 
 ### Error Handling
 
diff --git a/docs/SECURITY.md b/docs/SECURITY.md
index 68cf5dd..b626c26 100644
--- a/docs/SECURITY.md
+++ b/docs/SECURITY.md
@@ -32,7 +32,7 @@ git-cas provides defense against the following threat scenarios:
 
 git-cas does NOT provide protection in the following scenarios:
 
-1. **Key management**: git-cas does not store, manage, or rotate encryption keys. Key storage and lifecycle management are entirely the caller's responsibility.
+1. **Key management**: git-cas does not store or manage encryption keys. Key storage and lifecycle management are entirely the caller's responsibility. Key rotation is supported for envelope-encrypted content via `rotateKey()` (v5.2.0+).
 
 2. **Access control**: git-cas does not implement access control lists or authorization policies. If an attacker can access the Git repository and has the encryption key, they can read all content.
 
@@ -50,7 +50,7 @@ git-cas does NOT provide protection in the following scenarios:
 
 7. **Deletion guarantees**: Logical deletion from the manifest does not physically remove data from Git's object database. See [Git Object Immutability](#git-object-immutability).
 
-8. **Concurrent key rotation**: There is no support for re-encrypting content with a different key while maintaining availability.
+8. **Concurrent key rotation**: Envelope-encrypted content supports key rotation without re-encryption (v5.2.0+). Legacy (non-envelope) encrypted content still requires manual re-store.
 
 ---
 
@@ -117,7 +117,7 @@ git-cas **does not store encryption keys**. All key management responsibilities
 1. **Key generation**: The caller must generate cryptographically secure 256-bit (32-byte) keys.
 2. **Key storage**: The caller must securely store keys (e.g., in environment variables, key management systems, hardware security modules).
 3. **Key distribution**: If keys need to be shared across systems, the caller must implement secure key distribution.
-4. **Key rotation**: The caller must implement key rotation policies. git-cas does not support re-encrypting content with a new key.
+4. **Key rotation**: For envelope-encrypted content (v5.2.0+), use `rotateKey()` to re-wrap the DEK with a new KEK without touching data blobs. For vault-wide rotation, use `rotateVaultPassphrase()`. Legacy (non-envelope) content requires manual re-store with a new key.
 
 ### Key Validation
 
@@ -398,20 +398,18 @@ let buffer = Buffer.concat(chunks);
 
 **Future improvement**: Investigate chunked AEAD modes or encrypt-then-MAC schemes that allow incremental authentication.
 
-### 3. No Key Rotation
+### 3. Key Rotation (v5.2.0+)
 
-**Issue**: git-cas does not support re-encrypting content with a new key while maintaining the same manifest structure.
+**Envelope-encrypted content** supports key rotation without re-encrypting data blobs:
 
-**Impact**:
-- If a key is compromised, all content encrypted with that key must be manually re-encrypted by:
-  1. Restoring content with the old key.
-  2. Storing content again with the new key.
-  3. Updating all references to the old manifest tree to the new manifest tree.
+- `rotateKey({ manifest, oldKey, newKey, label? })` — unwraps the DEK with `oldKey`, re-wraps with `newKey`, increments `keyVersion`. Data blobs are never read.
+- `rotateVaultPassphrase({ oldPassphrase, newPassphrase })` — rotates all envelope-encrypted vault entries atomically.
 
-**Workaround**:
-- Implement application-level key rotation by maintaining a key version identifier alongside each manifest.
+**Limitations**:
+- **Legacy (non-envelope) encrypted content** does not support rotation. You must restore with the old key and re-store with envelope encryption.
+- **Rotation does not invalidate old ciphertext**: The encrypted data blobs remain unchanged in the Git object database. An attacker who has both the old wrapped DEK (from a prior manifest commit) and the old KEK can still decrypt. To fully revoke access, the old manifest commits must be unreachable (e.g., via vault history squash + `git gc`).
 
-**Future improvement**: Add a `reencrypt()` method that re-encrypts content with a new key without requiring full restore.
+**Best practice**: Track `keyVersion` in manifests to audit rotation compliance. Rotate keys after suspected compromise, on personnel changes, or on a regular schedule (e.g., every 90 days).
 
 ### 4. Nonce Collision Risk After 2^32 Operations
 
@@ -610,7 +608,7 @@ git-cas provides strong at-rest encryption and integrity guarantees through AES-
 
 - **Key management is entirely your responsibility**. git-cas does not store or manage keys.
 - **Encrypted restore is not streaming**. Large encrypted files may cause memory issues.
-- **No key rotation support**. Re-encrypting content requires manual restore/store cycles.
+- **Key rotation supported for envelope encryption** (v5.2.0+). Legacy (non-envelope) content still requires manual restore/store cycles.
 - **Metadata is not encrypted**. File structure and sizes are visible to anyone with repository access.
 - **Logical deletion does not physically remove data**. Use `git gc` to prune unreferenced objects.
 
diff --git a/index.d.ts b/index.d.ts
index c867427..afd1e4d 100644
--- a/index.d.ts
+++ b/index.d.ts
@@ -365,6 +365,13 @@ export default class ContentAddressableStore {
 
   listRecipients(manifest: Manifest): Promise<string[]>;
 
+  rotateKey(options: {
+    manifest: Manifest;
+    oldKey: Buffer;
+    newKey: Buffer;
+    label?: string;
+  }): Promise<Manifest>;
+
   // Vault — delegates to VaultService
 
   static VAULT_REF: string;
@@ -389,4 +396,14 @@ export default class ContentAddressableStore {
   resolveVaultEntry(options: { slug: string }): Promise<string>;
 
   getVaultMetadata(): Promise<VaultMetadata | null>;
+
+  rotateVaultPassphrase(options: {
+    oldPassphrase: string;
+    newPassphrase: string;
+    kdfOptions?: Omit<DeriveKeyOptions, "passphrase">;
+  }): Promise<{
+    commitOid: string;
+    rotatedSlugs: string[];
+    skippedSlugs: string[];
+  }>;
 }
diff --git a/index.js b/index.js
index 33f3a20..c545867 100644
--- a/index.js
+++ b/index.js
@@ -9,6 +9,7 @@ import { Readable, Transform } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import CasService from './src/domain/services/CasService.js';
 import VaultService from './src/domain/services/VaultService.js';
+import CasError from './src/domain/errors/CasError.js';
 import GitPersistenceAdapter from './src/infrastructure/adapters/GitPersistenceAdapter.js';
 import GitRefAdapter from './src/infrastructure/adapters/GitRefAdapter.js';
 import NodeCryptoAdapter from './src/infrastructure/adapters/NodeCryptoAdapter.js';
@@ -464,6 +465,20 @@ export default class ContentAddressableStore {
     return service.listRecipients(manifest);
   }
 
+  /**
+   * Rotates a recipient's key without re-encrypting data blobs.
+   * @param {Object} options
+   * @param {import('./src/domain/value-objects/Manifest.js').default} options.manifest
+   * @param {Buffer} options.oldKey - Current KEK of the recipient to rotate.
+   * @param {Buffer} options.newKey - New KEK to wrap the DEK with.
+   * @param {string} [options.label] - If provided, only rotate the named recipient.
+   * @returns {Promise<import('./src/domain/value-objects/Manifest.js').default>}
+   */
+  async rotateKey(options) {
+    const service = await this.#getService();
+    return await service.rotateKey(options);
+  }
+
   // ---------------------------------------------------------------------------
   // Vault — delegates to VaultService
   // ---------------------------------------------------------------------------
@@ -505,4 +520,123 @@ export default class ContentAddressableStore {
     const vault = await this.#getVault();
     return vault.getVaultMetadata();
   }
+
+  // ---------------------------------------------------------------------------
+  // Key rotation — orchestrates CasService + VaultService
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Rotates the vault-level passphrase. Re-wraps every envelope-encrypted
+   * entry's DEK with a new KEK derived from `newPassphrase`. Entries using
+   * direct-key encryption are skipped.
+   *
+   * @param {Object} options
+   * @param {string} options.oldPassphrase - Current vault passphrase.
+   * @param {string} options.newPassphrase - New vault passphrase.
+   * @param {Object} [options.kdfOptions] - KDF options for new passphrase.
+   * @returns {Promise<{ commitOid: string, rotatedSlugs: string[], skippedSlugs: string[] }>}
+   */
+  async rotateVaultPassphrase({ oldPassphrase, newPassphrase, kdfOptions }) {
+    const service = await this.#getService();
+    const vault = await this.#getVault();
+
+    const MAX_RETRIES = 3;
+    const RETRY_BASE_MS = 50;
+
+    for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+      const state = await vault.readState();
+      if (!state.metadata?.encryption) {
+        throw new CasError('Vault is not encrypted — nothing to rotate', 'VAULT_METADATA_INVALID');
+      }
+
+      const { kdf } = state.metadata.encryption;
+      const oldKek = await ContentAddressableStore.#deriveKekFromKdf(service, oldPassphrase, kdf);
+      const { key: newKek, salt: newSalt, params: newParams } = await service.deriveKey({
+        passphrase: newPassphrase, ...kdfOptions, algorithm: kdfOptions?.algorithm || kdf.algorithm,
+      });
+
+      const result = await ContentAddressableStore.#rotateEntries({ service, entries: state.entries, oldKek, newKek });
+      const newMetadata = ContentAddressableStore.#buildRotatedMetadata(state.metadata, newSalt, newParams);
+
+      try {
+        const { commitOid } = await vault.writeCommit({
+          entries: result.updatedEntries,
+          metadata: newMetadata,
+          parentCommitOid: state.parentCommitOid,
+          message: `vault: rotate passphrase (${result.rotatedSlugs.length} rotated, ${result.skippedSlugs.length} skipped)`,
+        });
+        return { commitOid, rotatedSlugs: result.rotatedSlugs, skippedSlugs: result.skippedSlugs };
+      } catch (err) {
+        if (err instanceof CasError && err.code === 'VAULT_CONFLICT' && attempt < MAX_RETRIES - 1) {
+          await new Promise((r) => setTimeout(r, RETRY_BASE_MS * (2 ** attempt)));
+          continue;
+        }
+        throw err;
+      }
+    }
+    /* c8 ignore next 2 */
+    throw new CasError('Vault CAS retries exhausted', 'VAULT_CONFLICT');
+  }
+
+  /**
+   * Derives a KEK from a passphrase using stored KDF params.
+   * @private
+   */
+  static async #deriveKekFromKdf(service, passphrase, kdf) {
+    const { key } = await service.deriveKey({
+      passphrase,
+      salt: Buffer.from(kdf.salt, 'base64'),
+      algorithm: kdf.algorithm,
+      iterations: kdf.iterations,
+      cost: kdf.cost,
+      blockSize: kdf.blockSize,
+      parallelization: kdf.parallelization,
+    });
+    return key;
+  }
+
+  /**
+   * Iterates vault entries, rotating envelope-encrypted ones and skipping others.
+   * @private
+   */
+  static async #rotateEntries({ service, entries, oldKek, newKek }) {
+    const rotatedSlugs = [];
+    const skippedSlugs = [];
+    const updatedEntries = new Map(entries);
+
+    for (const [slug, treeOid] of entries) {
+      const manifest = await service.readManifest({ treeOid });
+      if (!manifest.encryption?.recipients?.length) {
+        skippedSlugs.push(slug);
+        continue;
+      }
+      const rotated = await service.rotateKey({ manifest, oldKey: oldKek, newKey: newKek });
+      updatedEntries.set(slug, await service.createTree({ manifest: rotated }));
+      rotatedSlugs.push(slug);
+    }
+
+    return { updatedEntries, rotatedSlugs, skippedSlugs };
+  }
+
+  /**
+   * Builds updated vault metadata with new KDF params.
+   * @private
+   */
+  static #buildRotatedMetadata(metadata, newSalt, newParams) {
+    return {
+      ...metadata,
+      encryption: {
+        cipher: metadata.encryption.cipher,
+        kdf: {
+          algorithm: newParams.algorithm,
+          salt: newSalt.toString('base64'),
+          ...('iterations' in newParams && { iterations: newParams.iterations }),
+          ...('cost' in newParams && { cost: newParams.cost }),
+          ...('blockSize' in newParams && { blockSize: newParams.blockSize }),
+          ...('parallelization' in newParams && { parallelization: newParams.parallelization }),
+          keyLength: newParams.keyLength,
+        },
+      },
+    };
+  }
 }
diff --git a/jsr.json b/jsr.json
index 7411b43..354a84c 100644
--- a/jsr.json
+++ b/jsr.json
@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-cas",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "exports": {
     ".": "./index.js",
     "./service": "./src/domain/services/CasService.js",
diff --git a/package.json b/package.json
index 331a620..c3341ff 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@git-stunts/git-cas",
-  "version": "5.1.0",
+  "version": "5.2.1",
   "description": "Content-addressed storage backed by Git's object database, with optional encryption and pluggable codecs",
   "type": "module",
   "main": "index.js",
diff --git a/src/domain/schemas/ManifestSchema.d.ts b/src/domain/schemas/ManifestSchema.d.ts
index 23d7c7a..637557f 100644
--- a/src/domain/schemas/ManifestSchema.d.ts
+++ b/src/domain/schemas/ManifestSchema.d.ts
@@ -31,6 +31,7 @@ export declare const RecipientSchema: z.ZodObject<{
   nonce: z.ZodString;
   tag: z.ZodString;
   kekType: z.ZodOptional<z.ZodString>;
+  keyVersion: z.ZodOptional<z.ZodNumber>;
 }>;
 
 /** Validates the encryption metadata attached to an encrypted manifest. */
@@ -41,6 +42,7 @@ export declare const EncryptionSchema: z.ZodObject<{
   encrypted: z.ZodDefault<z.ZodBoolean>;
   kdf: z.ZodOptional<typeof KdfSchema>;
   recipients: z.ZodOptional<z.ZodArray<typeof RecipientSchema>>;
+  keyVersion: z.ZodOptional<z.ZodNumber>;
 }>;
 
 /** Validates compression metadata. */
diff --git a/src/domain/schemas/ManifestSchema.js b/src/domain/schemas/ManifestSchema.js
index 9db4b8f..b5212a2 100644
--- a/src/domain/schemas/ManifestSchema.js
+++ b/src/domain/schemas/ManifestSchema.js
@@ -31,6 +31,7 @@ export const RecipientSchema = z.object({
   nonce: z.string().min(1),
   tag: z.string().min(1),
   kekType: z.string().optional(),
+  keyVersion: z.number().int().min(0).optional(),
 });
 
 /** Validates the encryption metadata attached to an encrypted manifest. */
@@ -41,6 +42,7 @@ export const EncryptionSchema = z.object({
   encrypted: z.boolean().default(true),
   kdf: KdfSchema.optional(),
   recipients: z.array(RecipientSchema).min(1).optional(),
+  keyVersion: z.number().int().min(0).optional(),
 });
 
 /** Validates compression metadata. */
diff --git a/src/domain/services/CasService.d.ts b/src/domain/services/CasService.d.ts
index 6c44ee0..890ea49 100644
--- a/src/domain/services/CasService.d.ts
+++ b/src/domain/services/CasService.d.ts
@@ -153,6 +153,13 @@ export default class CasService {
 
   listRecipients(manifest: Manifest): string[];
 
+  rotateKey(options: {
+    manifest: Manifest;
+    oldKey: Buffer;
+    newKey: Buffer;
+    label?: string;
+  }): Promise<Manifest>;
+
   verifyIntegrity(manifest: Manifest): Promise<boolean>;
 
   deriveKey(options: DeriveKeyOptions): Promise<DeriveKeyResult>;
diff --git a/src/domain/services/CasService.js b/src/domain/services/CasService.js
index 4499a54..86d78a3 100644
--- a/src/domain/services/CasService.js
+++ b/src/domain/services/CasService.js
@@ -976,6 +976,94 @@ export default class CasService {
     return (manifest.encryption?.recipients || []).map((r) => r.label);
   }
 
+  /**
+   * Rotates a recipient's key without re-encrypting data blobs.
+   *
+   * Re-wraps the DEK with `newKey` for the matched recipient entry.
+   * Increments `keyVersion` at both manifest-level and recipient-level.
+   *
+   * @param {Object} options
+   * @param {import('../value-objects/Manifest.js').default} options.manifest
+   * @param {Buffer} options.oldKey - Current KEK of the recipient to rotate.
+   * @param {Buffer} options.newKey - New KEK to wrap the DEK with.
+   * @param {string} [options.label] - If provided, only rotate the named recipient.
+   * @returns {Promise<import('../value-objects/Manifest.js').default>}
+   * @throws {CasError} ROTATION_NOT_SUPPORTED if manifest has no recipients.
+   * @throws {CasError} RECIPIENT_NOT_FOUND if label doesn't exist.
+   * @throws {CasError} DEK_UNWRAP_FAILED if oldKey doesn't match the recipient.
+   * @throws {CasError} NO_MATCHING_RECIPIENT if no label and oldKey matches no entry.
+   */
+  async rotateKey({ manifest, oldKey, newKey, label }) {
+    const recipients = manifest.encryption?.recipients;
+    if (!recipients || recipients.length === 0) {
+      throw new CasError(
+        'Key rotation requires envelope encryption (recipients)',
+        'ROTATION_NOT_SUPPORTED',
+      );
+    }
+
+    this.crypto._validateKey(oldKey);
+    this.crypto._validateKey(newKey);
+
+    const { matchIndex, dek } = label
+      ? await this.#findRecipientByLabel(recipients, label, oldKey)
+      : await this.#findRecipientByKey(recipients, oldKey);
+
+    return this.#buildRotatedManifest({ manifest, recipients, matchIndex, dek, newKey });
+  }
+
+  /**
+   * Finds a recipient by label and unwraps the DEK.
+   */
+  async #findRecipientByLabel(recipients, label, oldKey) {
+    const matchIndex = recipients.findIndex((r) => r.label === label);
+    if (matchIndex === -1) {
+      throw new CasError(`Recipient "${label}" not found`, 'RECIPIENT_NOT_FOUND', { label });
+    }
+    const dek = await this._unwrapDek(recipients[matchIndex], oldKey);
+    return { matchIndex, dek };
+  }
+
+  /**
+   * Finds the first recipient whose DEK can be unwrapped with the given key.
+   */
+  async #findRecipientByKey(recipients, oldKey) {
+    for (let i = 0; i < recipients.length; i++) {
+      try {
+        const dek = await this._unwrapDek(recipients[i], oldKey);
+        return { matchIndex: i, dek };
+      } catch (err) {
+        if (!(err instanceof CasError && err.code === 'DEK_UNWRAP_FAILED')) { throw err; }
+      }
+    }
+    throw new CasError(
+      'No recipient entry could be unwrapped with the provided key',
+      'NO_MATCHING_RECIPIENT',
+    );
+  }
+
+  /**
+   * Builds a new Manifest with the rotated recipient entry and updated keyVersions.
+   */
+  async #buildRotatedManifest({ manifest, recipients, matchIndex, dek, newKey }) {
+    const newWrapped = await this._wrapDek(dek, newKey);
+    const manifestKeyVersion = (manifest.encryption.keyVersion || 0) + 1;
+    const recipientKeyVersion = (recipients[matchIndex].keyVersion || 0) + 1;
+
+    const json = manifest.toJSON();
+    const updatedRecipients = recipients.map((r, i) => {
+      if (i === matchIndex) {
+        return { ...r, ...newWrapped, keyVersion: recipientKeyVersion };
+      }
+      return { ...r };
+    });
+
+    return new Manifest({
+      ...json,
+      encryption: { ...json.encryption, recipients: updatedRecipients, keyVersion: manifestKeyVersion },
+    });
+  }
+
   /**
    * Verifies the integrity of a stored file by re-hashing its chunks.
    * @param {import('../value-objects/Manifest.js').default} manifest
diff --git a/src/domain/value-objects/Manifest.d.ts b/src/domain/value-objects/Manifest.d.ts
index 2247fbe..56d2b63 100644
--- a/src/domain/value-objects/Manifest.d.ts
+++ b/src/domain/value-objects/Manifest.d.ts
@@ -18,6 +18,7 @@ export interface RecipientEntry {
   nonce: string;
   tag: string;
   kekType?: string;
+  keyVersion?: number;
 }
 
 /** AES-256-GCM encryption metadata attached to an encrypted manifest. */
@@ -28,6 +29,7 @@ export interface EncryptionMeta {
   encrypted: boolean;
   kdf?: KdfParams;
   recipients?: RecipientEntry[];
+  keyVersion?: number;
 }
 
 /** Compression metadata. */
diff --git a/test/integration/vault-cli.test.js b/test/integration/vault-cli.test.js
index af4d232..603f4b7 100644
--- a/test/integration/vault-cli.test.js
+++ b/test/integration/vault-cli.test.js
@@ -188,6 +188,80 @@ describe('vault CLI — encrypted workflow', () => {
   });
 });
 
+// ---------------------------------------------------------------------------
+// rotate CLI — envelope encryption key rotation
+// ---------------------------------------------------------------------------
+describe('vault CLI — rotate', () => { // eslint-disable-line max-lines-per-function
+  let rotateRepoDir;
+  let rotateInputFile;
+  let rotateInputDir;
+  const rotateOriginal = randomBytes(2048);
+  let oldKeyFile;
+  let newKeyFile;
+  let keyDir;
+
+  beforeAll(() => {
+    rotateRepoDir = mkdtempSync(path.join(os.tmpdir(), 'cas-cli-rotate-integ-'));
+    execSync('git init --bare', { cwd: rotateRepoDir, stdio: 'ignore' });
+    ({ filePath: rotateInputFile, dir: rotateInputDir } = tempFile(rotateOriginal));
+
+    keyDir = mkdtempSync(path.join(os.tmpdir(), 'cas-cli-keys-'));
+    const oldKey = randomBytes(32);
+    const newKey = randomBytes(32);
+    oldKeyFile = path.join(keyDir, 'old.key');
+    newKeyFile = path.join(keyDir, 'new.key');
+    writeFileSync(oldKeyFile, oldKey);
+    writeFileSync(newKeyFile, newKey);
+  });
+
+  afterAll(() => {
+    if (rotateRepoDir) { rmSync(rotateRepoDir, { recursive: true, force: true }); }
+    if (rotateInputDir) { rmSync(rotateInputDir, { recursive: true, force: true }); }
+    if (keyDir) { rmSync(keyDir, { recursive: true, force: true }); }
+  });
+
+  it('vault init + store with recipient', () => {
+    cli('vault init', rotateRepoDir);
+    const oid = cli(
+      `store ${rotateInputFile} --tree --slug rotate/asset --recipient alice:${oldKeyFile}`,
+      rotateRepoDir,
+    );
+    expect(oid).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('rotate --slug rotates key and updates vault', () => {
+    const oid = cli(
+      `rotate --slug rotate/asset --old-key-file ${oldKeyFile} --new-key-file ${newKeyFile}`,
+      rotateRepoDir,
+    );
+    expect(oid).toMatch(/^[0-9a-f]{40}$/);
+  });
+
+  it('restore with new key succeeds after rotation', () => {
+    const outDir = mkdtempSync(path.join(os.tmpdir(), 'cas-cli-rotate-out-'));
+    const outPath = path.join(outDir, 'restored.bin');
+    cli(
+      `restore --slug rotate/asset --out ${outPath} --key-file ${newKeyFile}`,
+      rotateRepoDir,
+    );
+    const restored = readFileSync(outPath);
+    expect(restored.equals(rotateOriginal)).toBe(true);
+    rmSync(outDir, { recursive: true, force: true });
+  });
+
+  it('restore with old key fails after rotation', () => {
+    const outDir = mkdtempSync(path.join(os.tmpdir(), 'cas-cli-rotate-fail-'));
+    const outPath = path.join(outDir, 'restored.bin');
+    expect(() => {
+      cli(
+        `restore --slug rotate/asset --out ${outPath} --key-file ${oldKeyFile}`,
+        rotateRepoDir,
+      );
+    }).toThrow();
+    rmSync(outDir, { recursive: true, force: true });
+  });
+});
+
 // ---------------------------------------------------------------------------
 // CLI restore --oid with Merkle manifests
 // ---------------------------------------------------------------------------
diff --git a/test/unit/domain/schemas/ManifestSchema.keyVersion.test.js b/test/unit/domain/schemas/ManifestSchema.keyVersion.test.js
new file mode 100644
index 0000000..1540506
--- /dev/null
+++ b/test/unit/domain/schemas/ManifestSchema.keyVersion.test.js
@@ -0,0 +1,108 @@
+import { describe, it, expect } from 'vitest';
+import { RecipientSchema, EncryptionSchema, ManifestSchema } from '../../../../src/domain/schemas/ManifestSchema.js';
+
+const validRecipient = (overrides = {}) => ({
+  label: 'alice',
+  wrappedDek: 'AAAA',
+  nonce: 'BBBB',
+  tag: 'CCCC',
+  ...overrides,
+});
+
+const baseEncryption = (overrides = {}) => ({
+  algorithm: 'aes-256-gcm',
+  nonce: 'bm9uY2U=',
+  tag: 'dGFn',
+  encrypted: true,
+  ...overrides,
+});
+
+// ---------------------------------------------------------------------------
+// RecipientSchema — keyVersion
+// ---------------------------------------------------------------------------
+describe('RecipientSchema — keyVersion', () => {
+  it('accepts keyVersion: 0', () => {
+    const result = RecipientSchema.safeParse(validRecipient({ keyVersion: 0 }));
+    expect(result.success).toBe(true);
+    expect(result.data.keyVersion).toBe(0);
+  });
+
+  it('accepts keyVersion: 5', () => {
+    const result = RecipientSchema.safeParse(validRecipient({ keyVersion: 5 }));
+    expect(result.success).toBe(true);
+    expect(result.data.keyVersion).toBe(5);
+  });
+
+  it('rejects keyVersion: -1', () => {
+    expect(RecipientSchema.safeParse(validRecipient({ keyVersion: -1 })).success).toBe(false);
+  });
+
+  it('rejects keyVersion: 1.5 (non-integer)', () => {
+    expect(RecipientSchema.safeParse(validRecipient({ keyVersion: 1.5 })).success).toBe(false);
+  });
+
+  it('omitted keyVersion parses cleanly', () => {
+    const result = RecipientSchema.safeParse(validRecipient());
+    expect(result.success).toBe(true);
+    expect(result.data.keyVersion).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// EncryptionSchema — keyVersion
+// ---------------------------------------------------------------------------
+describe('EncryptionSchema — keyVersion', () => {
+  it('accepts keyVersion: 0', () => {
+    const result = EncryptionSchema.safeParse(baseEncryption({ keyVersion: 0 }));
+    expect(result.success).toBe(true);
+    expect(result.data.keyVersion).toBe(0);
+  });
+
+  it('accepts keyVersion: 5', () => {
+    const result = EncryptionSchema.safeParse(baseEncryption({ keyVersion: 5 }));
+    expect(result.success).toBe(true);
+    expect(result.data.keyVersion).toBe(5);
+  });
+
+  it('rejects keyVersion: -1', () => {
+    expect(EncryptionSchema.safeParse(baseEncryption({ keyVersion: -1 })).success).toBe(false);
+  });
+
+  it('rejects keyVersion: 1.5 (non-integer)', () => {
+    expect(EncryptionSchema.safeParse(baseEncryption({ keyVersion: 1.5 })).success).toBe(false);
+  });
+
+  it('omitted keyVersion parses cleanly', () => {
+    const result = EncryptionSchema.safeParse(baseEncryption());
+    expect(result.success).toBe(true);
+    expect(result.data.keyVersion).toBeUndefined();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// ManifestSchema — full round-trip with keyVersion on both levels
+// ---------------------------------------------------------------------------
+describe('ManifestSchema — keyVersion round-trip', () => {
+  it('round-trips keyVersion on both encryption and recipient levels', () => {
+    const manifest = {
+      version: 1,
+      slug: 'rotation-test',
+      filename: 'secret.bin',
+      size: 1024,
+      chunks: [{ index: 0, size: 1024, digest: 'a'.repeat(64), blob: 'b'.repeat(40) }],
+      encryption: {
+        ...baseEncryption({ keyVersion: 3 }),
+        recipients: [
+          validRecipient({ keyVersion: 2 }),
+          validRecipient({ label: 'bob', keyVersion: 3 }),
+        ],
+      },
+    };
+
+    const result = ManifestSchema.safeParse(manifest);
+    expect(result.success).toBe(true);
+    expect(result.data.encryption.keyVersion).toBe(3);
+    expect(result.data.encryption.recipients[0].keyVersion).toBe(2);
+    expect(result.data.encryption.recipients[1].keyVersion).toBe(3);
+  });
+});
diff --git a/test/unit/domain/services/CasService.rotateKey.test.js b/test/unit/domain/services/CasService.rotateKey.test.js
new file mode 100644
index 0000000..6b55b02
--- /dev/null
+++ b/test/unit/domain/services/CasService.rotateKey.test.js
@@ -0,0 +1,303 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { randomBytes } from 'node:crypto';
+import CasService from '../../../../src/domain/services/CasService.js';
+import { getTestCryptoAdapter } from '../../../helpers/crypto-adapter.js';
+import JsonCodec from '../../../../src/infrastructure/codecs/JsonCodec.js';
+import SilentObserver from '../../../../src/infrastructure/adapters/SilentObserver.js';
+import CasError from '../../../../src/domain/errors/CasError.js';
+
+const testCrypto = await getTestCryptoAdapter();
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function setup() {
+  const crypto = testCrypto;
+  const blobStore = new Map();
+
+  const mockPersistence = {
+    writeBlob: async (content) => {
+      const buf = Buffer.isBuffer(content) ? content : Buffer.from(content);
+      const oid = await crypto.sha256(buf);
+      blobStore.set(oid, buf);
+      return oid;
+    },
+    writeTree: async () => 'mock-tree-oid',
+    readBlob: async (oid) => {
+      const buf = blobStore.get(oid);
+      if (!buf) { throw new Error(`Blob not found: ${oid}`); }
+      return buf;
+    },
+  };
+
+  const service = new CasService({
+    persistence: mockPersistence,
+    crypto,
+    codec: new JsonCodec(),
+    chunkSize: 1024,
+    observability: new SilentObserver(),
+  });
+
+  return { service, blobStore, crypto, mockPersistence };
+}
+
+async function* bufferSource(buf) {
+  yield buf;
+}
+
+// ---------------------------------------------------------------------------
+// rotateKey — golden path
+// ---------------------------------------------------------------------------
+describe('CasService – rotateKey', () => { // eslint-disable-line max-lines-per-function
+  let service;
+  let mockPersistence;
+  beforeEach(() => { ({ service, mockPersistence } = setup()); });
+
+  it('store → rotateKey → restore with newKey works, oldKey fails', async () => {
+    const alice = randomBytes(32);
+    const aliceNew = randomBytes(32);
+    const original = Buffer.from('rotate me');
+
+    const manifest = await service.store({
+      source: bufferSource(original),
+      slug: 'rotate',
+      filename: 'rotate.bin',
+      recipients: [{ label: 'alice', key: alice }],
+    });
+
+    const rotated = await service.rotateKey({ manifest, oldKey: alice, newKey: aliceNew });
+
+    // New key works
+    const { buffer } = await service.restore({ manifest: rotated, encryptionKey: aliceNew });
+    expect(buffer.equals(original)).toBe(true);
+
+    // Old key fails
+    try {
+      await service.restore({ manifest: rotated, encryptionKey: alice });
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err.code).toBe('NO_MATCHING_RECIPIENT');
+    }
+  });
+
+  it('keyVersion increments correctly (manifest-level and recipient-level)', async () => {
+    const key1 = randomBytes(32);
+    const key2 = randomBytes(32);
+
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('data')),
+      slug: 'ver',
+      filename: 'ver.bin',
+      recipients: [{ label: 'alice', key: key1 }],
+    });
+
+    // First rotation
+    const r1 = await service.rotateKey({ manifest, oldKey: key1, newKey: key2 });
+    expect(r1.encryption.keyVersion).toBe(1);
+    expect(r1.encryption.recipients[0].keyVersion).toBe(1);
+
+    // Second rotation
+    const key3 = randomBytes(32);
+    const r2 = await service.rotateKey({ manifest: r1, oldKey: key2, newKey: key3 });
+    expect(r2.encryption.keyVersion).toBe(2);
+    expect(r2.encryption.recipients[0].keyVersion).toBe(2);
+  });
+
+  it('zero readBlob calls during rotation', async () => {
+    const alice = randomBytes(32);
+    const aliceNew = randomBytes(32);
+
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('data')),
+      slug: 'spy',
+      filename: 'spy.bin',
+      recipients: [{ label: 'alice', key: alice }],
+    });
+
+    const readSpy = vi.spyOn(mockPersistence, 'readBlob');
+    await service.rotateKey({ manifest, oldKey: alice, newKey: aliceNew });
+    expect(readSpy).not.toHaveBeenCalled();
+    readSpy.mockRestore();
+  });
+
+  it('with label: only named recipient updated, others unchanged', async () => {
+    const alice = randomBytes(32);
+    const bob = randomBytes(32);
+    const aliceNew = randomBytes(32);
+    const original = Buffer.from('multi-recipient');
+
+    const manifest = await service.store({
+      source: bufferSource(original),
+      slug: 'multi',
+      filename: 'multi.bin',
+      recipients: [
+        { label: 'alice', key: alice },
+        { label: 'bob', key: bob },
+      ],
+    });
+
+    const rotated = await service.rotateKey({
+      manifest, oldKey: alice, newKey: aliceNew, label: 'alice',
+    });
+
+    // Alice's new key works
+    const { buffer: buf1 } = await service.restore({ manifest: rotated, encryptionKey: aliceNew });
+    expect(buf1.equals(original)).toBe(true);
+
+    // Bob's key still works (unchanged)
+    const { buffer: buf2 } = await service.restore({ manifest: rotated, encryptionKey: bob });
+    expect(buf2.equals(original)).toBe(true);
+
+    // Bob's entry is byte-identical
+    expect(rotated.encryption.recipients[1].wrappedDek).toBe(manifest.encryption.recipients[1].wrappedDek);
+    expect(rotated.encryption.recipients[1].nonce).toBe(manifest.encryption.recipients[1].nonce);
+    expect(rotated.encryption.recipients[1].tag).toBe(manifest.encryption.recipients[1].tag);
+  });
+
+  it('without label: auto-detects matched entry', async () => {
+    const alice = randomBytes(32);
+    const bob = randomBytes(32);
+    const aliceNew = randomBytes(32);
+
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('auto')),
+      slug: 'auto',
+      filename: 'auto.bin',
+      recipients: [
+        { label: 'alice', key: alice },
+        { label: 'bob', key: bob },
+      ],
+    });
+
+    const rotated = await service.rotateKey({ manifest, oldKey: alice, newKey: aliceNew });
+
+    // Alice's new key works
+    const { buffer } = await service.restore({ manifest: rotated, encryptionKey: aliceNew });
+    expect(buffer.equals(Buffer.from('auto'))).toBe(true);
+  });
+
+  it('wrong oldKey → NO_MATCHING_RECIPIENT', async () => {
+    const alice = randomBytes(32);
+    const wrong = randomBytes(32);
+
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('data')),
+      slug: 'wrong',
+      filename: 'wrong.bin',
+      recipients: [{ label: 'alice', key: alice }],
+    });
+
+    try {
+      await service.rotateKey({ manifest, oldKey: wrong, newKey: randomBytes(32) });
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CasError);
+      expect(err.code).toBe('NO_MATCHING_RECIPIENT');
+    }
+  });
+
+  it('wrong oldKey with label → DEK_UNWRAP_FAILED', async () => {
+    const alice = randomBytes(32);
+    const wrong = randomBytes(32);
+
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('data')),
+      slug: 'wrong-label',
+      filename: 'wrong-label.bin',
+      recipients: [{ label: 'alice', key: alice }],
+    });
+
+    try {
+      await service.rotateKey({ manifest, oldKey: wrong, newKey: randomBytes(32), label: 'alice' });
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CasError);
+      expect(err.code).toBe('DEK_UNWRAP_FAILED');
+    }
+  });
+
+  it('nonexistent label → RECIPIENT_NOT_FOUND', async () => {
+    const alice = randomBytes(32);
+
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('data')),
+      slug: 'no-label',
+      filename: 'no-label.bin',
+      recipients: [{ label: 'alice', key: alice }],
+    });
+
+    try {
+      await service.rotateKey({ manifest, oldKey: alice, newKey: randomBytes(32), label: 'eve' });
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CasError);
+      expect(err.code).toBe('RECIPIENT_NOT_FOUND');
+    }
+  });
+
+  it('legacy manifest (no recipients) → ROTATION_NOT_SUPPORTED', async () => {
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('data')),
+      slug: 'legacy',
+      filename: 'legacy.bin',
+      encryptionKey: randomBytes(32),
+    });
+
+    try {
+      await service.rotateKey({ manifest, oldKey: randomBytes(32), newKey: randomBytes(32) });
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CasError);
+      expect(err.code).toBe('ROTATION_NOT_SUPPORTED');
+    }
+  });
+
+  it('unencrypted manifest → ROTATION_NOT_SUPPORTED', async () => {
+    const manifest = await service.store({
+      source: bufferSource(Buffer.from('data')),
+      slug: 'plain',
+      filename: 'plain.bin',
+    });
+
+    try {
+      await service.rotateKey({ manifest, oldKey: randomBytes(32), newKey: randomBytes(32) });
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err).toBeInstanceOf(CasError);
+      expect(err.code).toBe('ROTATION_NOT_SUPPORTED');
+    }
+  });
+
+  it('20 sequential rotations → keyVersion=20, only final key works', async () => {
+    let currentKey = randomBytes(32);
+    const original = Buffer.from('sequential rotation');
+
+    let manifest = await service.store({
+      source: bufferSource(original),
+      slug: 'seq',
+      filename: 'seq.bin',
+      recipients: [{ label: 'alice', key: currentKey }],
+    });
+
+    for (let i = 0; i < 20; i++) {
+      const nextKey = randomBytes(32);
+      manifest = await service.rotateKey({ manifest, oldKey: currentKey, newKey: nextKey });
+      currentKey = nextKey;
+    }
+
+    expect(manifest.encryption.keyVersion).toBe(20);
+    expect(manifest.encryption.recipients[0].keyVersion).toBe(20);
+
+    // Final key works
+    const { buffer } = await service.restore({ manifest, encryptionKey: currentKey });
+    expect(buffer.equals(original)).toBe(true);
+
+    // A random older key fails
+    try {
+      await service.restore({ manifest, encryptionKey: randomBytes(32) });
+      expect.unreachable('should have thrown');
+    } catch (err) {
+      expect(err.code).toBe('NO_MATCHING_RECIPIENT');
+    }
+  });
+});
diff --git a/test/unit/facade/ContentAddressableStore.rotation.test.js b/test/unit/facade/ContentAddressableStore.rotation.test.js
new file mode 100644
index 0000000..7222dca
--- /dev/null
+++ b/test/unit/facade/ContentAddressableStore.rotation.test.js
@@ -0,0 +1,197 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+import os from 'node:os';
+import { execSync } from 'node:child_process';
+import GitPlumbing from '@git-stunts/plumbing';
+import ContentAddressableStore from '../../../index.js';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function createRepo() {
+  const dir = mkdtempSync(path.join(os.tmpdir(), 'cas-rotation-'));
+  execSync('git init --bare', { cwd: dir, stdio: 'ignore' });
+  execSync('git config user.name "test"', { cwd: dir, stdio: 'ignore' });
+  execSync('git config user.email "test@test"', { cwd: dir, stdio: 'ignore' });
+  return dir;
+}
+
+function createCas(repoDir) {
+  const plumbing = GitPlumbing.createDefault({ cwd: repoDir });
+  return new ContentAddressableStore({ plumbing, chunkSize: 1024 });
+}
+
+async function* bufferSource(buf) {
+  yield buf;
+}
+
+async function storeEnvelope({ cas, slug, data, passphrase }) {
+  const metadata = await cas.getVaultMetadata();
+  const { key } = await cas.deriveKey({
+    passphrase,
+    salt: Buffer.from(metadata.encryption.kdf.salt, 'base64'),
+    algorithm: metadata.encryption.kdf.algorithm,
+    iterations: metadata.encryption.kdf.iterations,
+  });
+  const manifest = await cas.store({
+    source: bufferSource(data),
+    slug,
+    filename: `${slug}.bin`,
+    recipients: [{ label: 'vault', key }],
+  });
+  const treeOid = await cas.createTree({ manifest });
+  await cas.addToVault({ slug, treeOid, force: true });
+  return treeOid;
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('ContentAddressableStore – rotateVaultPassphrase', () => { // eslint-disable-line max-lines-per-function
+  let repoDir;
+  let cas;
+
+  beforeEach(() => {
+    repoDir = createRepo();
+    cas = createCas(repoDir);
+  });
+
+  afterEach(() => {
+    if (repoDir) { rmSync(repoDir, { recursive: true, force: true }); }
+  });
+
+  it('3 envelope entries → rotate → all restorable with new passphrase', async () => {
+    const oldPass = 'old-pass';
+    const newPass = 'new-pass';
+    await cas.initVault({ passphrase: oldPass, kdfOptions: { iterations: 1 } });
+
+    const originals = {};
+    for (const name of ['alpha', 'beta', 'gamma']) {
+      const data = randomBytes(256);
+      originals[name] = data;
+      await storeEnvelope({ cas, slug: name, data, passphrase: oldPass });
+    }
+
+    const { commitOid, rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase({
+      oldPassphrase: oldPass, newPassphrase: newPass,
+    });
+
+    expect(commitOid).toMatch(/^[0-9a-f]{40}$/);
+    expect(rotatedSlugs.sort()).toEqual(['alpha', 'beta', 'gamma']);
+    expect(skippedSlugs).toEqual([]);
+
+    // Verify all restorable with new passphrase
+    const newMeta = await cas.getVaultMetadata();
+    const { key: newKey } = await cas.deriveKey({
+      passphrase: newPass,
+      salt: Buffer.from(newMeta.encryption.kdf.salt, 'base64'),
+      algorithm: newMeta.encryption.kdf.algorithm,
+      iterations: newMeta.encryption.kdf.iterations,
+    });
+
+    for (const name of ['alpha', 'beta', 'gamma']) {
+      const treeOid = await cas.resolveVaultEntry({ slug: name });
+      const manifest = await cas.readManifest({ treeOid });
+      const { buffer } = await cas.restore({ manifest, encryptionKey: newKey });
+      expect(buffer.equals(originals[name])).toBe(true);
+    }
+  });
+
+  it('mixed: 2 envelope + 1 non-envelope → 2 rotated, 1 skipped', async () => {
+    const oldPass = 'old-pass';
+    const newPass = 'new-pass';
+    await cas.initVault({ passphrase: oldPass, kdfOptions: { iterations: 1 } });
+
+    // 2 envelope entries
+    await storeEnvelope({ cas, slug: 'env1', data: randomBytes(128), passphrase: oldPass });
+    await storeEnvelope({ cas, slug: 'env2', data: randomBytes(128), passphrase: oldPass });
+
+    // 1 non-envelope (direct key from vault passphrase)
+    const metadata = await cas.getVaultMetadata();
+    const { key: directKey } = await cas.deriveKey({
+      passphrase: oldPass,
+      salt: Buffer.from(metadata.encryption.kdf.salt, 'base64'),
+      algorithm: metadata.encryption.kdf.algorithm,
+      iterations: metadata.encryption.kdf.iterations,
+    });
+    const plainManifest = await cas.store({
+      source: bufferSource(randomBytes(128)),
+      slug: 'direct',
+      filename: 'direct.bin',
+      encryptionKey: directKey,
+    });
+    const plainTree = await cas.createTree({ manifest: plainManifest });
+    await cas.addToVault({ slug: 'direct', treeOid: plainTree });
+
+    const { rotatedSlugs, skippedSlugs } = await cas.rotateVaultPassphrase({
+      oldPassphrase: oldPass, newPassphrase: newPass,
+    });
+
+    expect(rotatedSlugs.sort()).toEqual(['env1', 'env2']);
+    expect(skippedSlugs).toEqual(['direct']);
+  });
+
+  it('wrong old passphrase → error', async () => {
+    const oldPass = 'old-pass';
+    await cas.initVault({ passphrase: oldPass, kdfOptions: { iterations: 1 } });
+    await storeEnvelope({ cas, slug: 'asset', data: randomBytes(128), passphrase: oldPass });
+
+    await expect(
+      cas.rotateVaultPassphrase({ oldPassphrase: 'wrong', newPassphrase: 'new' }),
+    ).rejects.toThrow();
+  });
+
+  it('vault not encrypted → VAULT_METADATA_INVALID', async () => {
+    await cas.initVault();
+    // Store unencrypted entry
+    const manifest = await cas.store({
+      source: bufferSource(randomBytes(64)),
+      slug: 'plain',
+      filename: 'plain.bin',
+    });
+    const tree = await cas.createTree({ manifest });
+    await cas.addToVault({ slug: 'plain', treeOid: tree });
+
+    await expect(
+      cas.rotateVaultPassphrase({ oldPassphrase: 'any', newPassphrase: 'new' }),
+    ).rejects.toMatchObject({ code: 'VAULT_METADATA_INVALID' });
+  });
+
+  it('kdfOptions.algorithm overrides existing algorithm', async () => {
+    const oldPass = 'old-pass';
+    const newPass = 'new-pass';
+    // Init with default algorithm (pbkdf2)
+    await cas.initVault({ passphrase: oldPass, kdfOptions: { iterations: 1 } });
+    await storeEnvelope({ cas, slug: 'asset', data: randomBytes(128), passphrase: oldPass });
+
+    const oldMeta = await cas.getVaultMetadata();
+    expect(oldMeta.encryption.kdf.algorithm).toBe('pbkdf2');
+
+    await cas.rotateVaultPassphrase({
+      oldPassphrase: oldPass,
+      newPassphrase: newPass,
+      kdfOptions: { algorithm: 'scrypt' },
+    });
+
+    const newMeta = await cas.getVaultMetadata();
+    expect(newMeta.encryption.kdf.algorithm).toBe('scrypt');
+  });
+
+  it('metadata updated with new KDF salt', async () => {
+    const oldPass = 'old-pass';
+    const newPass = 'new-pass';
+    await cas.initVault({ passphrase: oldPass, kdfOptions: { iterations: 1 } });
+    await storeEnvelope({ cas, slug: 'asset', data: randomBytes(128), passphrase: oldPass });
+
+    const oldMeta = await cas.getVaultMetadata();
+    const oldSalt = oldMeta.encryption.kdf.salt;
+
+    await cas.rotateVaultPassphrase({ oldPassphrase: oldPass, newPassphrase: newPass });
+
+    const newMeta = await cas.getVaultMetadata();
+    expect(newMeta.encryption.kdf.salt).not.toBe(oldSalt);
+    expect(newMeta.encryption.kdf.algorithm).toBe(oldMeta.encryption.kdf.algorithm);
+  });
+});