feat(samples): Personalized learning demo improvements

samples/personalized_learning/.env.template

@@ -43,3 +43,53 @@ AGENT_ENGINE_RESOURCE_ID=
 
 # GCS_CONTEXT_BUCKET=your-bucket-name
 # GCS_CONTEXT_PREFIX=learner_context/
+
+# =============================================================================
+# IMPORTANT - Access Control (you MUST configure this!)
+# =============================================================================
+#
+# By default, access is restricted to @google.com accounts, which means you
+# won't be able to access your own deployed application unless you work at Google!
+#
+# ⚠️  BEFORE DEPLOYING: Update these settings to allow YOUR email/domain.
+#
+# The server is the single source of truth for authorization. Both options below
+# are checked - a user is allowed if they match EITHER the domain OR the email list.
+#
+# -----------------------------------------------------------------------------
+
+# Option 1: Restrict to a specific email domain
+# Examples:
+#   VITE_ALLOWED_DOMAIN=yourcompany.com     (allows anyone@yourcompany.com)
+#   VITE_ALLOWED_DOMAIN=gmail.com           (allows any Gmail user - use with caution!)
+#   VITE_ALLOWED_DOMAIN=                    (disable domain restriction, use email list only)
+#
+VITE_ALLOWED_DOMAIN=google.com
+
+# Option 2: Whitelist specific email addresses (comma-separated)
+# These users are allowed regardless of domain setting above.
+# Examples:
+#   VITE_ALLOWED_EMAILS=you@gmail.com
+#   VITE_ALLOWED_EMAILS=alice@example.com,bob@partner.org,charlie@university.edu
+#
+# VITE_ALLOWED_EMAILS=
+
+# -----------------------------------------------------------------------------
+# Quick setup examples:
+#
+# Allow only yourself:
+#   VITE_ALLOWED_DOMAIN=
+#   VITE_ALLOWED_EMAILS=your.email@gmail.com
+#
+# Allow your whole company:
+#   VITE_ALLOWED_DOMAIN=yourcompany.com
+#   VITE_ALLOWED_EMAILS=
+#
+# Allow your company + a few external collaborators:
+#   VITE_ALLOWED_DOMAIN=yourcompany.com
+#   VITE_ALLOWED_EMAILS=external.collaborator@gmail.com,partner@othercorp.com
+#
+# Allow anyone with a Google account (public demo):
+#   VITE_ALLOWED_DOMAIN=
+#   VITE_ALLOWED_EMAILS=
+# -----------------------------------------------------------------------------

samples/personalized_learning/.gitignore

@@ -27,7 +27,7 @@ demo-message-log.json
 .DS_Store
 Thumbs.db
 
-# Large media assets (generate via NotebookLM - see NOTEBOOKLM_GUIDE.md)
+# Large media assets (generate via NotebookLM - see Quickstart.ipynb)
 public/assets/*.m4a
 public/assets/*.mp4
 
@@ -42,3 +42,9 @@ public/assets/*.mp4
 
 # Temporary A2UI copy for Cloud Run deployment
 a2ui-web-lib/
+
+# Tests (not part of the demo distribution)
+tests/
+
+# Linter cache
+.ruff_cache/

samples/personalized_learning/Quickstart.ipynb

@@ -523,30 +523,39 @@
    "source": [
     "### Access Control\n",
     "\n",
-    "By default, the demo restricts access to `@google.com` email addresses. This is configured in [`src/firebase-auth.ts`](src/firebase-auth.ts).\n",
+    "⚠️ **IMPORTANT: You must configure access control to use your deployed app!**\n",
     "\n",
-    "**To change the allowed domain:**\n",
-    "```typescript\n",
-    "// In src/firebase-auth.ts\n",
-    "const ALLOWED_DOMAIN = \"yourcompany.com\";  // Change to your domain\n",
-    "```\n",
+    "By default, access is restricted to `@google.com` accounts. If you don't work at Google, you'll be locked out of your own deployment.\n",
     "\n",
-    "**To allow specific external collaborators (whitelist):**\n",
-    "```typescript\n",
-    "// In src/firebase-auth.ts\n",
-    "const ALLOWED_EMAILS: string[] = [\n",
-    "  \"alice@example.com\",\n",
-    "  \"bob@partner.org\",\n",
-    "  \"charlie@university.edu\",\n",
-    "];\n",
-    "```\n",
+    "**Before deploying**, add these lines to your `.env` file:\n",
+    "\n",
+    "```bash\n",
+    "# Option 1: Allow a specific domain (your company)\n",
+    "VITE_ALLOWED_DOMAIN=yourcompany.com\n",
+    "\n",
+    "# Option 2: Allow specific email addresses (yourself + collaborators)\n",
+    "VITE_ALLOWED_DOMAIN=\n",
+    "VITE_ALLOWED_EMAILS=your.email@gmail.com,collaborator@example.com\n",
     "\n",
-    "**To allow anyone with a Google account:**\n",
-    "```typescript\n",
-    "const ALLOWED_DOMAIN = \"\";  // Disable domain restriction\n",
-    "const ALLOWED_EMAILS: string[] = [];  // Empty whitelist = allow all\n",
+    "# Option 3: Allow anyone with a Google account (public demo)\n",
+    "VITE_ALLOWED_DOMAIN=\n",
+    "VITE_ALLOWED_EMAILS=\n",
     "```\n",
     "\n",
+    "**How it works:**\n",
+    "\n",
+    "The server is the single source of truth for authorization. When a user signs in:\n",
+    "1. Firebase authenticates them (Google OAuth)\n",
+    "2. The client calls `/api/check-access` with the user's token\n",
+    "3. The server checks if their email matches `VITE_ALLOWED_DOMAIN` or `VITE_ALLOWED_EMAILS`\n",
+    "4. If not authorized, they're signed out and shown an error\n",
+    "\n",
+    "| Configuration | Who can access |\n",
+    "|--------------|----------------|\n",
+    "| `VITE_ALLOWED_DOMAIN=yourcompany.com` | Anyone with @yourcompany.com |\n",
+    "| `VITE_ALLOWED_EMAILS=you@gmail.com` | Only your email |\n",
+    "| Both empty | Anyone with a Google account |\n",
+    "\n",
     "> **Note:** After changing access control, rebuild and redeploy: `python deploy_hosting.py --project YOUR_PROJECT_ID`"
    ]
   },