diff --git a/Agents.md b/Agents.md
index d21d466..9a15adc 100644
--- a/Agents.md
+++ b/Agents.md
@@ -544,6 +544,10 @@ Add keys to `Info.plist` that bridge xcconfig values to Swift:
 
 #### Step 5: Create Swift Interface
 
+**Why this is needed:** Swift code cannot read xcconfig files directly. The xcconfig values flow through Info.plist, and this Swift file provides a clean API to access them at runtime. Without this file, you'd have to call `Bundle.main.object(forInfoDictionaryKey:)` everywhere you need an identifier.
+
+**When to use:** Any Swift code that needs App Group identifiers, CloudKit containers, custom domains, or other configuration values must use `AppIdentifiers.*` instead of hardcoding strings.
+
 Create `Configuration/AppIdentifiers.swift`:
 
 ```swift