refactor: add staged next-account rotation and clarify ChatGPT config

README.md

@@ -1,24 +1,17 @@
 # megapt
 
-HTTP service that returns an active ChatGPT access token.
-
-The service can:
-- restore/refresh a saved token from `/data`
-- auto-register a new ChatGPT account when needed
-- get verification email from a disposable mail provider (`temp-mail.org`)
-- expose token and usage info via HTTP endpoint
-
+Service for issuing ChatGPT OAuth tokens via browser automation with disposable email.
 
 ## Endpoints
 
-- `GET /token` - legacy route (defaults to `chatgpt` provider)
-- `GET /chatgpt/token` - explicit provider route
+- `GET /chatgpt/token`
+- `GET /token` (legacy alias, same as chatgpt)
 
-Example response:
+Response shape:
 
 ```json
 {
-  "token": "<access_token>",
+  "token": "...",
   "limit": {
     "used_percent": 0,
     "remaining_percent": 100,
@@ -37,67 +30,47 @@ Example response:
 }
 ```
 
+## Environment Variables
 
-## Environment variables
+- `PORT` - HTTP server port (default: `8080`)
+- `DATA_DIR` - persistent data directory for tokens/screenshots (default: `./data`)
+- `CHATGPT_PREPARE_THRESHOLD` - usage threshold to prepare `next_account` (default: `85`)
+- `CHATGPT_SWITCH_THRESHOLD` - usage threshold to switch active account to `next_account` (default: `95`)
 
-See `.env.example`.
+Example config is in `.env.example`.
 
-- `PORT` - HTTP port for the service
-- `USAGE_REFRESH_THRESHOLD` - percent threshold to trigger background token rotation
-- `DATA_DIR` - directory for persistent data (`chatgpt_tokens.json`, screenshots, etc.)
+## Token Lifecycle
 
+- **active account** - currently served token.
+- **next account** - pre-created account/token stored for fast switch.
 
-## Local run
+Behavior:
 
-Requirements:
-- Python 3.14+
-- Playwright Chromium dependencies
+1. If active token is valid, service returns it immediately.
+2. If active token is expired, service tries refresh under a single write lock.
+3. If refresh fails or token is missing, service registers a new account (up to 4 attempts).
+4. When usage reaches `CHATGPT_PREPARE_THRESHOLD`, service prepares `next_account`.
+5. When usage reaches `CHATGPT_SWITCH_THRESHOLD`, service switches active account to `next_account`.
 
-Install and run:
+## Startup Behavior
+
+On startup, service:
+
+1. Ensures active token exists and is usable.
+2. Ensures `next_account` is prepared for ChatGPT.
+
+## Data Files
+
+- `DATA_DIR/chatgpt_tokens.json` - token state with `active` and `next_account`.
+- `DATA_DIR/screenshots/` - automation failure screenshots.
+
+## Run Locally
 
 ```bash
-uv sync --frozen --no-dev
-./.venv/bin/python -m playwright install --with-deps chromium
-PYTHONPATH=./src ./.venv/bin/python src/server.py
+PYTHONPATH=./src python src/server.py
 ```
 
-Then request token:
+## Docker Notes
 
-```bash
-curl http://127.0.0.1:8080/chatgpt/token
-```
-
-
-## Docker deployment
-
-Build image:
-
-```bash
-docker build -t megapt:latest .
-```
-
-Run container:
-
-```bash
-docker run -d \
-  --name megapt \
-  --restart unless-stopped \
-  --env-file .env \
-  -v ./data:/data \
-  -p 80:80 \
-  megapt:latest
-```
-
-Check logs:
-
-```bash
-docker logs -f megapt
-```
-
-
-## Notes
-
-- Service performs a startup token check and tries to recover token automatically.
-- Token write path is synchronized (single-writer lock) to avoid parallel re-registration.
-- Browser runs in virtual display (`Xvfb`) inside container.
-- Keep `/data` persistent between restarts.
+- Dockerfile sets `DATA_DIR=/data`.
+- `entrypoint.sh` starts Xvfb and runs `server.py`.