diff --git a/AGENTS.md b/AGENTS.md
index b09f4a9..dab6e35 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -48,6 +48,15 @@ Domain docs (reference, do not paste into PRs):
 8. **Every bug fix includes a regression test** at the lowest layer that catches it.
 9. After code changes, run the **relevant** checks in [Build and test](#build-and-test)
    and fix failures before finishing.
+10. **`localization/strings.json` is the single source of truth for all localized
+    strings.** The KMP Compose resources (`shared/src/commonMain/composeResources/
+    values*/strings.xml`) and the Apple catalog + accessors
+    (`apple/VniDrop/Resources/Localizable.xcstrings`, `apple/VniDrop/Generated/
+    L10n.swift`) are **generated** by the loc CLI (`cd localization && bun run
+    src/cli.ts generate`) — never hand-edit them. To add/change a string: edit
+    `strings.json` (set `targets` to `kmp`, `apple`, or omit for both), then
+    regenerate. A key referenced in code but only present in a generated file will
+    be silently dropped the next time generation runs.
 
 ---
 
@@ -291,6 +300,8 @@ branch from updated `master`.
 - Flaky multi-minute sleeps in tests
 - Unsigned commits when signing is required
 - Force-push or secret commits without explicit user direction
+- Hand-editing generated localization files (`values*/strings.xml`,
+  `Localizable.xcstrings`, `L10n.swift`) instead of `localization/strings.json`
 
 ---
 
diff --git a/shared/AGENTS.md b/shared/AGENTS.md
index 6add30a..ab70c02 100644
--- a/shared/AGENTS.md
+++ b/shared/AGENTS.md
@@ -32,7 +32,7 @@ lists, animation, accessibility:
 | Architecture | Keep **MVVM-style** ViewModels: immutable `*State`, `StateFlow`, **named methods**. Do not force MVI `onEvent` sealed hierarchies unless asked. |
 | Structure | Feature packages under `com.vnidrop.app.feature.*`; thin route/wiring + screen/composables. |
 | Theme | Only `LocalVniDropColors` / `VniDropThemeTokens` (`ui/theme/VniDropTheme.kt`). Brand primary light ≈ `#A855F7` (HSL 271, 91%, 65%). |
-| Strings | CMP composeResources / `Res.string.*` — not Android `R` in `commonMain`. |
+| Strings | CMP composeResources / `Res.string.*` — not Android `R` in `commonMain`. `values*/strings.xml` are **generated** from `localization/strings.json` (source of truth) via the loc CLI — add/edit keys there, never in the XML. |
 | DI | Follow existing `AppGraph` construction; no unprompted Hilt/Koin migration. |
 | Platform | `androidMain` / `jvmMain` for pickers, SAF, NFC/QR, and desktop integration. |
 | Dependencies | Before adding Jetpack/AndroidX to `commonMain`, verify multiplatform artifacts for all targets. |