diff --git a/README.md b/README.md
index 9056cb4..f5ae953 100644
--- a/README.md
+++ b/README.md
@@ -101,36 +101,36 @@ Sessions are stored via Symfony's filesystem cache by default (`config/packages/
 
 ## Appsmith app integration
 
-Create a shared module with this js:
+Create a shared module with this js. It stays generic — every app key and page name is passed in by the caller, so the same code can be dropped into every app unchanged:
 
 ```js
 export default {
     isLoggedIn() {
         return !!appsmith.store.sid;
     },
-    login(appKey) {
-        navigateTo(`https://bff.ep-reisen.net/auth/login?app=${appKey}`, {}, 'SAME_WINDOW');
+    login({ app }) {
+        navigateTo(`https://bff.ep-reisen.net/auth/login?app=${app}`, {}, 'SAME_WINDOW');
     },
-    async checkReturningFromLogin(loginPageName, protectedPageName) {
+    async checkReturningFromLogin({ loginPage, protectedPage }) {
         const sid = appsmith.URL.queryParams.sid;
         const error = appsmith.URL.queryParams.error;
         if (error === 'access_denied') {
             showAlert('You do not have access to this app.', 'error');
-            navigateTo(loginPageName, {}, 'SAME_WINDOW');
+            navigateTo(loginPage, {}, 'SAME_WINDOW');
             return;
         }
         if (sid) {
             await storeValue('sid', sid);
-            navigateTo(protectedPageName, {}, 'SAME_WINDOW');
+            navigateTo(protectedPage, {}, 'SAME_WINDOW');
         }
         if (appsmith.store.sid && !appsmith.store.user) {
             const profile = await Bff_Me.run();
             await storeValue('user', profile);
         }
     },
-    guardPage(loginPageName) {
+    guardPage({ loginPage }) {
         if (!this.isLoggedIn()) {
-            navigateTo(loginPageName, {}, 'SAME_WINDOW');
+            navigateTo(loginPage, {}, 'SAME_WINDOW');
         }
     },
     async logout() {
@@ -142,26 +142,35 @@ export default {
 }
 ```
 
+The per-page objects below are where an app's own configuration lives — page names and the app key. They can't be folded into the shared module: JS Objects are page-scoped and "Run on page load" applies to the page the object belongs to, so each page needs its own.
+
 On the login page add this js to be executed onLoad:
 
 ```js
 export default {
   onLoad() {
-    return Bff.checkReturningFromLogin('Login', 'ProtectedPage');
+    return Bff.checkReturningFromLogin({
+      loginPage: 'Login',
+      protectedPage: 'ProtectedPage',
+    });
   }
 }
 ```
 
+Bind the login button's onClick to `{{ Bff.login({ app: 'app-sandbox' }) }}` — the same app key the `Bff_Me` query sends as `?app=`.
+
 On the protected page add this js to be execute onLoad:
 
 ```js
 export default {
   onLoad() {
-    return Bff.guardPage('Login');
+    return Bff.guardPage({ loginPage: 'Login' });
   }
 }
 ```
 
+Note `guardPage` only checks that a `sid` exists, not that it's still valid — an expired session surfaces on the first API call's 401 handler.
+
 Login state can be used to toggle visibility of UI elements in Appsmith with
 
 ```js