diff --git a/docs/oracle-vm-deployment.md b/docs/oracle-vm-deployment.md
new file mode 100644
index 0000000..363ae85
--- /dev/null
+++ b/docs/oracle-vm-deployment.md
@@ -0,0 +1,519 @@
+# Deploying the Adobe Sign → DocuSign Migrator to the Oracle Cloud VM
+
+_Last updated: 2026-04-21_
+
+This document explains:
+1. the **current live deployment setup** on the Oracle VM
+2. how to **deploy updated app code**
+3. how to **restart and verify** the site
+4. where the important config files live
+
+This is written so future-you does not have to rediscover the setup.
+
+---
+
+## 1. Current Live Deployment Setup
+
+### Server
+The app is currently deployed to an Oracle Cloud Ubuntu VM.
+
+### Live app directory
+```bash
+/home/ubuntu/projects/adobe-to-docusign-migrator
+```
+
+### Process manager
+The app is run by **systemd** as a service named:
+```bash
+adobe-migrator.service
+```
+
+### App server
+The service launches the FastAPI app with `uvicorn`:
+```bash
+/home/ubuntu/projects/adobe-to-docusign-migrator/venv/bin/uvicorn web.app:app --host 0.0.0.0 --port 8000
+```
+
+### Reverse proxy
+**nginx** listens on port 80 and proxies traffic to the app on port 8000.
+
+### Live hostname
+```text
+dstemplate.mooo.com
+```
+
+### Nginx site config
+```bash
+/etc/nginx/sites-available/dstemplate
+/etc/nginx/sites-enabled/dstemplate
+```
+
+### Systemd service file
+```bash
+/etc/systemd/system/adobe-migrator.service
+```
+
+---
+
+## 2. Current Service Configuration
+
+The current systemd service file is:
+
+```ini
+[Unit]
+Description=Adobe Sign to DocuSign Migrator
+After=network.target
+
+[Service]
+Type=simple
+User=ubuntu
+WorkingDirectory=/home/ubuntu/projects/adobe-to-docusign-migrator
+ExecStart=/home/ubuntu/projects/adobe-to-docusign-migrator/venv/bin/uvicorn web.app:app --host 0.0.0.0 --port 8000
+Restart=always
+RestartSec=5
+Environment=PATH=/home/ubuntu/projects/adobe-to-docusign-migrator/venv/bin
+
+[Install]
+WantedBy=multi-user.target
+```
+
+What this means:
+- the app runs as user `ubuntu`
+- the working directory is the project folder
+- it uses the project’s Python virtual environment
+- if the app crashes, systemd restarts it automatically
+
+---
+
+## 3. Current Nginx Configuration
+
+The live nginx site config is:
+
+```nginx
+server {
+    listen 80;
+    server_name dstemplate.mooo.com;
+
+    location / {
+        proxy_pass http://127.0.0.1:8000;
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection 'upgrade';
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_cache_bypass $http_upgrade;
+    }
+}
+```
+
+What this means:
+- visitors go to `http://dstemplate.mooo.com`
+- nginx receives the request on port 80
+- nginx forwards it to the FastAPI app on `127.0.0.1:8000`
+
+---
+
+## 4. Environment and Secrets on the VM
+
+The deployment relies on environment files stored in the app directory.
+
+Important files on the VM:
+```bash
+/home/ubuntu/projects/adobe-to-docusign-migrator/.env
+/home/ubuntu/projects/adobe-to-docusign-migrator/.env-adobe
+/home/ubuntu/projects/adobe-to-docusign-migrator/private.key
+```
+
+These should **not** be overwritten casually.
+They likely contain:
+- Adobe Sign credentials
+- DocuSign credentials
+- refresh tokens / secrets
+- app configuration
+
+Before a risky deploy, back them up.
+
+Example:
+```bash
+cd /home/ubuntu/projects/adobe-to-docusign-migrator
+cp .env .env.backup
+cp .env-adobe .env-adobe.backup
+cp private.key private.key.backup
+```
+
+---
+
+## 5. Current Git Situation
+
+### On local workstation
+The project currently exists at:
+```bash
+/home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
+```
+
+### On Oracle VM
+The deployed copy currently exists at:
+```bash
+/home/ubuntu/projects/adobe-to-docusign-migrator
+```
+
+### Important note
+At the time this doc was written:
+- local workspace branch: `ui-redesign`
+- Oracle VM branch: `master`
+
+So deployment should be done intentionally.
+Do not assume the VM is following your current local branch automatically.
+
+---
+
+## 6. Standard Deployment Procedure
+
+This is the recommended clean deployment flow.
+
+### Step 1: Review local changes
+On your local machine:
+
+```bash
+cd /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
+git status
+```
+
+Make sure you understand:
+- what changed
+- which branch you are on
+- whether the changes are ready to ship
+
+### Step 2: Run tests locally
+Before deploying, run the tests that matter.
+
+For the full test suite:
+
+```bash
+cd /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
+pytest tests/ -v
+```
+
+For a quicker smoke test:
+
+```bash
+pytest tests/test_api_health.py -v
+pytest tests/test_api_auth.py -v
+pytest tests/test_api_templates.py -v
+pytest tests/test_api_migrate.py -v
+```
+
+If you changed frontend files only, still run at least a small backend smoke test.
+
+### Step 3: Commit your changes locally
+```bash
+cd /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
+git add .
+git commit -m "Describe the deployment-worthy change"
+```
+
+### Step 4: Push to the remote repo
+```bash
+git push origin <branch-name>
+```
+
+If deploying from `master`:
+```bash
+git push origin master
+```
+
+If deploying from a feature branch:
+- either merge it first
+- or intentionally deploy that branch on the VM
+
+### Step 5: SSH into the Oracle VM
+```bash
+ssh ubuntu@<VM_PUBLIC_IP>
+```
+
+Or if DNS is set up and working:
+```bash
+ssh ubuntu@dstemplate.mooo.com
+```
+
+### Step 6: Go to the app directory on the VM
+```bash
+cd /home/ubuntu/projects/adobe-to-docusign-migrator
+```
+
+### Step 7: Check current branch and status
+```bash
+git branch --show-current
+git status
+```
+
+If the VM has local changes, stop and inspect before pulling.
+
+### Step 8: Pull the code you want to deploy
+If deploying `master`:
+```bash
+git checkout master
+git pull origin master
+```
+
+If deploying a feature branch intentionally:
+```bash
+git checkout <branch-name>
+git pull origin <branch-name>
+```
+
+### Step 9: Update Python dependencies
+Use the project virtual environment.
+
+```bash
+cd /home/ubuntu/projects/adobe-to-docusign-migrator
+source venv/bin/activate
+pip install -r requirements.txt
+```
+
+If requirements did not change, this is still safe to run.
+
+### Step 10: Restart the service
+```bash
+sudo systemctl restart adobe-migrator
+```
+
+### Step 11: Confirm the service is healthy
+```bash
+sudo systemctl status adobe-migrator --no-pager
+```
+
+You want to see:
+- `active (running)`
+
+### Step 12: Test locally on the VM
+```bash
+curl http://127.0.0.1:8000/health
+```
+
+and/or:
+
+```bash
+curl http://127.0.0.1/
+```
+
+If nginx is working, the second command should return HTML for the app.
+
+### Step 13: Test from a browser
+Open:
+```text
+http://dstemplate.mooo.com
+```
+
+Verify:
+- the page loads
+- CSS/JS load correctly
+- authentication buttons still work
+- the main workflow still renders
+
+---
+
+## 7. Fast Deploy Shortcut
+
+Once you are confident in the process, this is the shortest safe deploy sequence on the VM after code has been pushed:
+
+```bash
+cd /home/ubuntu/projects/adobe-to-docusign-migrator
+git checkout master
+git pull origin master
+source venv/bin/activate
+pip install -r requirements.txt
+sudo systemctl restart adobe-migrator
+sudo systemctl status adobe-migrator --no-pager
+```
+
+---
+
+## 8. How to Inspect the Current Live Deployment
+
+### Check service status
+```bash
+sudo systemctl status adobe-migrator --no-pager
+```
+
+### Restart service
+```bash
+sudo systemctl restart adobe-migrator
+```
+
+### Stop service
+```bash
+sudo systemctl stop adobe-migrator
+```
+
+### Start service
+```bash
+sudo systemctl start adobe-migrator
+```
+
+### View recent service logs
+```bash
+journalctl -u adobe-migrator -n 100 --no-pager
+```
+
+### Follow live logs
+```bash
+journalctl -u adobe-migrator -f
+```
+
+### Check nginx config
+```bash
+sudo nginx -t
+```
+
+### Reload nginx
+```bash
+sudo systemctl reload nginx
+```
+
+### Check which process is listening on port 8000
+```bash
+ss -ltnp | grep 8000
+```
+
+---
+
+## 9. Troubleshooting
+
+### Problem: service restarted but site still broken
+Check:
+```bash
+journalctl -u adobe-migrator -n 100 --no-pager
+```
+
+Common causes:
+- missing Python dependency
+- bad `.env` value
+- import error in code
+- startup crash in FastAPI app
+
+### Problem: nginx returns 502 Bad Gateway
+Usually means nginx cannot reach the app on port 8000.
+
+Check:
+```bash
+sudo systemctl status adobe-migrator --no-pager
+curl http://127.0.0.1:8000/health
+```
+
+If the health check fails, the app is not running correctly.
+
+### Problem: static files not loading
+Check:
+- app HTML returns successfully
+- browser dev tools for 404s on `/static/...`
+- FastAPI static mounting still exists
+
+### Problem: pulled wrong branch
+Check:
+```bash
+git branch --show-current
+git rev-parse HEAD
+```
+
+### Problem: secrets got overwritten
+Restore from backup if you made one:
+```bash
+cp .env.backup .env
+cp .env-adobe.backup .env-adobe
+cp private.key.backup private.key
+sudo systemctl restart adobe-migrator
+```
+
+---
+
+## 10. Manual One-Off Deploy Without Git Pull
+
+If for some reason you need to copy a local working tree directly instead of using Git:
+
+### From local machine
+```bash
+rsync -av --exclude '.git' --exclude 'venv' \
+  /home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator/ \
+  ubuntu@<VM_PUBLIC_IP>:/home/ubuntu/projects/adobe-to-docusign-migrator/
+```
+
+Then on the VM:
+```bash
+cd /home/ubuntu/projects/adobe-to-docusign-migrator
+source venv/bin/activate
+pip install -r requirements.txt
+sudo systemctl restart adobe-migrator
+```
+
+Use this carefully. Git-based deployment is cleaner.
+
+---
+
+## 11. Recommended Deployment Rules
+
+1. **Always know what branch you are deploying.**
+2. **Run tests before deploy.**
+3. **Commit before deploy.**
+4. **Prefer Git pull on the VM over manual file copying.**
+5. **Do not overwrite `.env`, `.env-adobe`, or `private.key` unless intended.**
+6. **Restart the systemd service after code changes.**
+7. **Smoke test both localhost and the public URL.**
+
+---
+
+## 12. Quick Reference
+
+### Local project path
+```bash
+/home/paulh/.openclaw/workspace/projects/adobe-to-docusign-migrator
+```
+
+### VM project path
+```bash
+/home/ubuntu/projects/adobe-to-docusign-migrator
+```
+
+### Service file
+```bash
+/etc/systemd/system/adobe-migrator.service
+```
+
+### Nginx site config
+```bash
+/etc/nginx/sites-available/dstemplate
+/etc/nginx/sites-enabled/dstemplate
+```
+
+### Restart app
+```bash
+sudo systemctl restart adobe-migrator
+```
+
+### Check app status
+```bash
+sudo systemctl status adobe-migrator --no-pager
+```
+
+### Check logs
+```bash
+journalctl -u adobe-migrator -n 100 --no-pager
+```
+
+### Public URL
+```text
+http://dstemplate.mooo.com
+```
+
+---
+
+## 13. Future Improvements
+
+Possible future upgrades for deployment:
+- HTTPS with Let’s Encrypt
+- deployment script (`deploy.sh`)
+- backup/rollback script
+- CI/CD from Gitea
+- separate staging environment
+- branch-based preview deploys