diff --git a/internal/snapshot/manifest.go b/internal/snapshot/manifest.go
index 3e6e95d..b45f4a7 100644
--- a/internal/snapshot/manifest.go
+++ b/internal/snapshot/manifest.go
@@ -5,11 +5,13 @@
 // reject archives whose schemaVersion exceeds what they know.
 //
 // v2 (current): root identifiers are UUIDv7 (Crockford Base32). Entries
-// under metadata/<root>.json carry the flat string properties; the cids
-// and duplicates Redis SETs are NOT serialized yet — they are rebuilt
-// transparently on import because SetMetadataFlat / MergeMetadataFlat
-// auto-register reverse-index aliases for any cid_*/midhash256 field they
-// see (see internal/storage/cid_resolution.go).
+// under metadata/<root>.json carry the flat string properties; the cid
+// reverse-index and the duplicates SET are NOT serialized — they are rebuilt
+// transparently on import because the cids/<cid> key-set members ARE flat
+// properties, and SetMetadataFlat / MergeMetadataFlat auto-register a
+// reverse-index alias for every one they see (see
+// internal/storage/cid_resolution.go: cidFromKeysetField). The legacy flat
+// cid_*/midhash256 named fields are not recognised.
 //
 // v1 (legacy): roots were content-hash-typed tokens like "midhash256:abc".
 // v1 archives can no longer be imported — they would resurrect the
diff --git a/internal/storage/client.go b/internal/storage/client.go
index 127fd83..82c417e 100644
--- a/internal/storage/client.go
+++ b/internal/storage/client.go
@@ -192,8 +192,9 @@ func (c *Client) SetMetadataFlat(hashID string, metadata map[string]string) erro
 		return fmt.Errorf("sadd index failed: %w", err)
 	}
 
-	// Auto-register reverse-index aliases for any cid_* or midhash256 fields
-	// in the payload. See cid_resolution.go for the rules.
+	// Auto-register reverse-index aliases for any cids/<cid> key-set members in
+	// the payload. That is the ONLY shape recognised — the legacy flat cid_* /
+	// midhash256 named fields are not (see cid_resolution.go: cidFromKeysetField).
 	c.maybeAddAliasesFromMetadataLocked(ctx, hashID, metadata)
 
 	return nil
@@ -461,8 +462,9 @@ func (c *Client) MergeMetadataFlat(hashID string, metadata map[string]string) (i
 		return len(metadata), fmt.Errorf("sadd index failed: %w", err)
 	}
 
-	// Auto-register reverse-index aliases for any cid_* or midhash256 fields
-	// in the payload. See cid_resolution.go for the rules.
+	// Auto-register reverse-index aliases for any cids/<cid> key-set members in
+	// the payload. That is the ONLY shape recognised — the legacy flat cid_* /
+	// midhash256 named fields are not (see cid_resolution.go: cidFromKeysetField).
 	c.maybeAddAliasesFromMetadataLocked(ctx, hashID, metadata)
 
 	return len(metadata), nil