docs: additive-v2 propagation + optional-GC finalize; bump 0.7.0.0 (EGB-712)

README.md

@@ -173,7 +173,20 @@ secrets clear
 | `secrets verify --all` | Decrypt-test every blob in every project — a store-wide integrity sweep |
 | `secrets migrate [--dry-run]` | Copy-forward this project's encrypted blobs to store format v2 (non-destructive; manifest-free; `--dry-run` previews) |
 | `secrets migrate --status` | Survey every project's v2 readiness; exits non-zero until the whole store is finalize-ready |
-| `secrets migrate --finalize` | Drop the old v1 blobs and mark the store v2 — runs once, store-wide, after `verify` is green and every machine is upgraded |
+| `secrets migrate --finalize` | **Optional GC** — drop the old v1 blobs and mark the store pure v2. Never required: upgraded clients dual-write and read-fall-back, so not finalizing never cuts anyone off |
+
+### Upgrading: do teammates on an older `secrets` get new secrets?
+
+Store-format v2 is **additive** — an upgraded client reads either blob suffix and keeps the old (v1) suffix alive for externals that already existed, so you almost never have to coordinate an upgrade:
+
+| Secret type | Old client gets it? |
+|---|---|
+| `.env` / `.env.*` / `.dev.vars` | **Yes, always** (blob name is identical across formats) |
+| whole-file external (`file`) | **Yes, always** |
+| `properties` external that already existed | **Yes** (dual-written so old clients stay fresh) |
+| brand-new `properties` external | **No — must upgrade `secrets`** (the gentle forcing function) |
+
+"Upgrade your secrets" = `git pull` the tool clone (binary ≥ 0.6.0.0) and/or `secrets migrate` the store. A read-only teammate only needs the tool `git pull`.
 
 ### Automatic project detection