diff --git a/DEVELOPER_HANDOFF.md b/DEVELOPER_HANDOFF.md
new file mode 100644
index 0000000..d6b1b3f
--- /dev/null
+++ b/DEVELOPER_HANDOFF.md
@@ -0,0 +1,199 @@
+# PoliticTalk Jitsi Developer Handoff
+
+This folder is the source of truth for the white-labeled PoliticTalk Jitsi setup served from:
+
+```text
+https://politictalk.parallelglobe.io
+```
+
+The PoliticTalk VPS still runs the real Jitsi services. Local changes are made in this repo, committed, pushed, pulled on the VPS, then copied into the live Jitsi install with the deploy script.
+
+## Main Files
+
+```text
+config/politictalk.parallelglobe.io-config.js
+  Jitsi meeting policy: toolbar, audio-only behavior, prejoin, E2EE, branding URLs.
+
+web/plugin.head.html
+  Injected CSS and JavaScript for most visible UI customizations.
+  This controls branding, mobile toolbar fixes, direct-access messaging,
+  participant tile styling, role colors, hidden Jitsi controls, and layout patches.
+
+web/title.html
+  Browser title, favicon, and page metadata template.
+
+web/manifest.json
+  Web manifest used by the deployed Jitsi web app.
+
+assets/public/politictalk/
+  Public images and branding JSON, including logos, favicon, and background assets.
+
+interface_config/politictalk-overrides.js
+  Overrides appended to Jitsi's interface_config.js.
+
+prosody-plugins/mod_politictalk_roles.lua
+  Server-side room policy: JWT role mapping, moderator/member handling,
+  host lifecycle, AV moderation, room inactive callback, and occupancy callback.
+
+nginx/politictalk.parallelglobe.io.conf
+  Nginx vhost and public asset routes for the PoliticTalk domain.
+
+scripts/deploy-vps.sh
+  Copies tracked files into the live Jitsi system paths and creates backups.
+```
+
+## Normal Change Flow
+
+Work locally from the Jitsi folder:
+
+```bash
+cd /Users/amardeep/work/pg/jitsi
+git status --short
+```
+
+Edit the relevant files. Most UI changes go in:
+
+```text
+web/plugin.head.html
+```
+
+Before committing, run quick checks:
+
+```bash
+git diff --check
+awk '/^<script>$/{inside=1; next} /^<\/script>$/{inside=0} inside{print}' web/plugin.head.html | node --check -
+```
+
+Then commit and push:
+
+```bash
+git add .
+git commit -m "Update PoliticTalk Jitsi UI"
+git push
+```
+
+Use a specific commit message for non-UI work, for example auth, Prosody, nginx, or config changes.
+
+## Deploy On VPS
+
+The current VPS checkout is expected at:
+
+```text
+/opt/politictalk-jitsi-config
+```
+
+SSH into the VPS, pull the latest code, and run the deploy script:
+
+```bash
+ssh ubuntu@politictalk
+cd /opt/politictalk-jitsi-config
+git status --short
+git pull --ff-only
+sudo ./scripts/deploy-vps.sh
+```
+
+If the nginx vhost changed, deploy nginx too:
+
+```bash
+sudo DEPLOY_NGINX=1 ./scripts/deploy-vps.sh
+```
+
+The deploy script creates a backup under:
+
+```text
+/root/jitsi-backups/YYYYMMDD-HHMMSS
+```
+
+It also reloads nginx automatically.
+
+## Restart Rules
+
+For most UI and asset changes, this is enough:
+
+```bash
+sudo ./scripts/deploy-vps.sh
+```
+
+Then hard-refresh the browser or open a new incognito window.
+
+For nginx changes:
+
+```bash
+sudo DEPLOY_NGINX=1 ./scripts/deploy-vps.sh
+```
+
+For Prosody plugin, JWT auth, moderator/participant policy, host lifecycle, or room callback changes, restart the Jitsi services after deploy:
+
+```bash
+sudo systemctl restart prosody
+sudo systemctl restart jicofo
+sudo systemctl restart jitsi-videobridge2
+```
+
+## Quick Verification
+
+Check that public assets are served:
+
+```bash
+curl -I https://politictalk.parallelglobe.io/images/politictalk/pgLogo.svg
+curl -I https://politictalk.parallelglobe.io/images/politictalk/politictalk_logo_text.svg
+```
+
+Check that the deployed config includes the expected PoliticTalk settings:
+
+```bash
+curl -s https://politictalk.parallelglobe.io/config.js \
+  | grep -E "startAudioOnly|toolbarButtons|dynamicBrandingUrl|defaultLogoUrl|prejoinConfig"
+```
+
+Manual smoke test from PgPlatform:
+
+```text
+1. Create or open a PoliticTalk room from the platform.
+2. Join as host and confirm the host is moderator.
+3. Join as participant and confirm the participant is not moderator.
+4. Confirm participant starts muted and cannot unmute without host action.
+5. Confirm chat, raise hand, polls, fullscreen, and noise suppression work.
+6. Confirm direct room access without platform/JWT shows the Parallel Globe account message.
+7. Confirm mobile toolbar, participant tiles, and branding render correctly.
+```
+
+## Rollback
+
+Every deploy prints the backup path. To roll back, copy the backed-up files from that folder back to their original system paths, then reload/restart the relevant services.
+
+Common live paths:
+
+```text
+/etc/jitsi/meet/politictalk.parallelglobe.io-config.js
+/etc/jitsi/meet/public/politictalk/
+/usr/share/jitsi-meet/images/politictalk/
+/usr/share/jitsi-meet/plugin.head.html
+/usr/share/jitsi-meet/title.html
+/usr/share/jitsi-meet/manifest.json
+/usr/share/jitsi-meet/interface_config.js
+/usr/share/jitsi-meet/prosody-plugins/mod_politictalk_roles.lua
+/etc/nginx/sites-available/politictalk.parallelglobe.io.conf
+```
+
+After rollback:
+
+```bash
+sudo systemctl reload nginx
+```
+
+If Prosody/JWT logic was rolled back:
+
+```bash
+sudo systemctl restart prosody
+sudo systemctl restart jicofo
+sudo systemctl restart jitsi-videobridge2
+```
+
+## Important Notes
+
+- Do not edit the live Jitsi files manually on the VPS except for an emergency. Those changes will be overwritten by the next deploy.
+- Do not commit secrets, JWT secrets, Prosody passwords, or generated Docker `.env` files.
+- Public visual assets should go in `assets/public/politictalk/`.
+- Keep `plugin.head.html` changes scoped and well-commented. Jitsi is a React app with generated class names, so prefer stable selectors such as IDs, aria labels, known wrapper classes, and classes that our script adds.
+- The platform and PgApi are responsible for room creation, user validation, invite links, and Jitsi JWT generation. The Jitsi VPS validates the token and enforces in-room behavior.
diff --git a/README.md b/README.md
index 8b34d51..a16cd12 100644
--- a/README.md
+++ b/README.md
@@ -8,6 +8,10 @@ https://politictalk.parallelglobe.io
 
 The VPS still runs the actual Jitsi services. Changes should be made here first, committed to Git, pulled on the VPS, then deployed into the system Jitsi paths with the deploy script.
 
+## Developer Handoff
+
+For the day-to-day edit, deploy, verify, and rollback workflow, see [DEVELOPER_HANDOFF.md](./DEVELOPER_HANDOFF.md).
+
 ## Structure
 
 ```text