diff --git a/docs/README.md b/docs/README.md
index dc41d7b..089f4e4 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -125,6 +125,12 @@ npm run apk:release   # releases/xenia-waiter-<ver>.apk, signed, AND copied to p
   - first run shows only the pairing screen
 - `android/local.properties` (SDK path) is gitignored. Recreate it on a new machine: `sdk.dir=C:/Users/<you>/AppData/Local/Android/Sdk`.
 
+- **UI bundles (plan step 8):** every waiter image also publishes the native UI bundle (`scripts/pack-bundle.mjs` → `/downloads/waiter-bundle.json` + zip). Phones run their venue's bundle via `@capgo/capacitor-updater` (manual mode, no Capgo cloud), driven by `src/native/bundles.js`.
+
+**CS-10. `MIN_SHELL_BUILD` guards native compatibility.**
+When web code starts relying on something new in `android/` (a plugin, a Java class, a manifest change), bump `MIN_SHELL_BUILD` in `src/native/shell.js` **and** `versionCode`, in the same commit. Phones with an older APK then keep their current UI and show "update the app", instead of loading a UI that calls missing native code.
+Every bundle must call `markBundleReady()` at start (`BundleSync` does this); otherwise it is rolled back after 15 s.
+
 **CS-9. Anything a native build needs must survive `npx cap sync`.**
 `android/app/src/main/assets/public` and the generated configs are rebuilt on every sync, so never edit them. Native changes go in `android/app/src/main/**` (manifest, res, java) or `capacitor.config.json`.