Local XP Token Refresh & Validation
===================================

Purpose
-------
Ensure the Windows XP helper (`MediLink_Gmail.py`) uses the newly generated OAuth desktop client and authorize the gmail.send scope without conflicts from cached credentials.

Prerequisites
-------------
- `MediLink/json/credentials.json` exists (created by `setup_gcp.sh`).
- `MediLink/MediLink_Gmail.py` is reachable on the XP host.
- Web app and Execution API redeployments completed (see `apps_script_link_and_redeploy.md`).

Steps
-----
1. **Transfer credentials to XP host**
   - Copy `MediLink/json/credentials.json` from the repo to the XP machine, overwriting the existing file in the MediLink installation directory.
   - Verify file encoding remains ASCII/UTF-8 (no BOM); size should match the generated JSON.

2. **Clear cached tokens**
   - Locate the existing `token.json` alongside `MediLink_Gmail.py` (if present).
   - Delete or rename it (example: `token.backup.json`).
   - Optional: remove `downloaded_emails.txt` or `pending_cleanup.json` if you intend to reprocess everything; otherwise leave them intact.

3. **Launch the local HTTPS helper**
   - Run `MediLink_Gmail.py` from a terminal (ensure Python 3.4.4 runtime is active).
   - The script will generate self-signed certificates if needed and start the HTTPS listener on `https://127.0.0.1:8000`.

4. **Perform OAuth consent**
   - When prompted in the console, a browser window opens to the Google consent screen.
   - Approve all requested scopes (Gmail send/read/modify, Drive, Apps Script).
   - Upon success, the script writes a fresh `token.json`. Confirm log output shows `Access token refreshed successfully` or similar.

5. **Trigger headless run**
   - Allow `MediLink_Gmail.py` to proceed with `run_headless_via_execution_api()`.
   - Monitor logs for Drive upload/download operations and ensure there are no `401` or `403` errors.

6. **Manual docx flow verification (optional)**
   - Start the Apps Script web app from the newly deployed URL.
   - Confirm the page loads without scope errors and that the `initializeDocxEmailListFlow()` completes (watch the local console for handshake messages).

7. **Archive the new token**
   - If policy requires, copy the fresh `token.json` to a secure location; otherwise keep it in place for future runs.

Troubleshooting
---------------
- **Consent screen shows wrong project:** Ensure `setup_gcp.sh` was run with the correct `PROJECT_ID` and that the Apps Script project is linked to the same Cloud project.
- **`invalid_grant` errors:** Delete `token.json`, re-run `MediLink_Gmail.py`, and redo consent. Confirm the user is in the same Workspace domain as the OAuth brand.
- **Local HTTPS errors:** Run `python MediLink_Gmail.py --reset-cert` (if a helper exists) or delete `server.cert` / `server.key` to regenerate them before restarting the script.

Next Steps
----------
- Once the local flow succeeds, proceed to end-to-end regression testing for both OTP and non-OTP flows, following any QA checklist maintained for MediLink.
