Add HOWTOUSE.md and docs/ for fast, error-free new setup

HOWTOUSE.md: per-service API endpoints + correct payloads + curl examples (key as
placeholder, never the real value). docs/: architecture, persistence, api-gateway,
deployment, troubleshooting — documents everything added on top of the base image so a
fresh HF or Docker deploy doesn't hit the errors we already solved.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

HOWTOUSE.md

@@ -0,0 +1,93 @@
+# How to use the API
+
+One base URL fronts all three services. Every `/gpt`, `/gemini`, `/flow` call needs the
+`API_KEY` as a Bearer token. The monitor UI (`/`) needs no key.
+
+- **Base URL:** `https://akash1313-selfapi.hf.space`
+- **Auth header:** `Authorization: Bearer YOUR_API_KEY`  *(your real key is in the gitignored `./api-key`)*
+
+> ⚠️ **You must be logged in** to ChatGPT / Gemini / Flow inside the browser
+> (`https://akash1313-selfapi.hf.space/`) for real responses. The servers reply even when
+> logged out, but with `extensionConnected:false` / empty data. Check first:
+> ```bash
+> curl -H "Authorization: Bearer YOUR_API_KEY" https://akash1313-selfapi.hf.space/gpt/health
+> ```
+> `extensionConnected:true` = ready.
+
+---
+
+## ChatGPT — `/gpt`
+
+| Endpoint | Method | Body |
+|----------|--------|------|
+| `/gpt/health` | GET | — |
+| `/gpt/api/chat` | POST | `{"prompt": "...", "wait_for_response": true}` |
+| `/gpt/api/chat/bulk` | POST | `{"prompts": ["...","..."], "delay_seconds": 2}` |
+| `/gpt/v1/chat/completions` | POST | OpenAI-compatible (see below) |
+
+```bash
+# Simple chat
+curl -X POST https://akash1313-selfapi.hf.space/gpt/api/chat \
+  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
+  -d '{"prompt":"Write a haiku about the sea","wait_for_response":true}'
+
+# OpenAI-compatible (drop-in for OpenAI SDKs — set base_url=.../gpt/v1)
+curl -X POST https://akash1313-selfapi.hf.space/gpt/v1/chat/completions \
+  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
+  -d '{"model":"gpt-5","messages":[{"role":"user","content":"hello"}],"stream":false}'
+```
+Optional fields: `"model"`, `"thinking_effort"`, `"conversation_id"` (continue a thread).
+
+---
+
+## Gemini — `/gemini`  (form-encoded, not JSON)
+
+| Endpoint | Method | Body |
+|----------|--------|------|
+| `/gemini/status` | GET | — |
+| `/gemini/chat` | POST (form) | `prompt`, `user_id`, `new_chat`, `stream` |
+| `/gemini/music` | POST (form) | `prompt` |
+| `/gemini/reset` | POST | — |
+| `/gemini/output/<file>` | GET | — (generated media) |
+
+```bash
+curl -X POST https://akash1313-selfapi.hf.space/gemini/chat \
+  -H "Authorization: Bearer YOUR_API_KEY" \
+  -d "prompt=Explain quantum entanglement simply&new_chat=true"
+```
+
+---
+
+## Flow (video / image) — `/flow`  (JSON)
+
+| Endpoint | Method | Body |
+|----------|--------|------|
+| `/flow/health` | GET | — |
+| `/flow/generate/video` | POST | `{"prompt":"...","aspect":"portrait","duration":10,"count":1}` |
+| `/flow/generate/image` | POST | `{"prompt":"...","aspect":"portrait","count":1}` |
+| `/flow/upload/image` · `/flow/upload/video` | POST | multipart file |
+| `/flow/download/<filename>` | GET | — |
+
+```bash
+# Text-to-video (aspect: portrait|landscape ; duration: 4,6,8,10)
+curl -X POST https://akash1313-selfapi.hf.space/flow/generate/video \
+  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
+  -d '{"prompt":"a cat surfing a wave, cinematic","aspect":"landscape","duration":8}'
+
+# Text-to-image
+curl -X POST https://akash1313-selfapi.hf.space/flow/generate/image \
+  -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" \
+  -d '{"prompt":"neon city at night","aspect":"square"}'
+```
+
+---
+
+## Auth errors
+
+| Code | Meaning |
+|------|---------|
+| `401` | Missing/wrong key |
+| `503` | `API_KEY` not set on the server (gateway disabled, fail-closed) |
+| `502` | Backend server not reachable (still booting / crashed — check `/chrome.log`) |
+
+Rotate the key anytime: change the `API_KEY` secret in the Space settings (auto-restarts).

docs/README.md

@@ -0,0 +1,24 @@
+# docs/ — what's new & how to set it up fast
+
+Reference for everything added on top of the base Chrome Space, so a fresh deploy (HF **or**
+Docker) goes quick and error-free. Read in order:
+
+| File | Covers |
+|------|--------|
+| [architecture.md](architecture.md) | One container: Chrome + extensions + monitor/gateway + 3 servers. Ports. |
+| [persistence.md](persistence.md) | Staying logged in: Neon Postgres (HF) vs Docker volume (self-host). |
+| [api-gateway.md](api-gateway.md) | The single gateway, `/gpt /gemini /flow` routing, `API_KEY` auth. |
+| [deployment.md](deployment.md) | Deploy steps, required secrets, HF tokens, Docker build stages. |
+| [troubleshooting.md](troubleshooting.md) | Every error we hit and its fix. **Check here first.** |
+
+For **calling** the API see [`../HOWTOUSE.md`](../HOWTOUSE.md). For a quick start see
+[`../SETUP.md`](../SETUP.md).
+
+## Required secrets (set these or things silently break)
+
+| Secret | Where | Without it |
+|--------|-------|-----------|
+| `DATABASE_URL` | HF only (Neon Postgres) | Logins lost on every restart |
+| `API_KEY` | HF + Docker `.env` | All `/gpt /gemini /flow` return `503` |
+
+Local credential notes live in gitignored files: `hf-token`, `neon-db`, `api-key`.

docs/api-gateway.md

@@ -0,0 +1,37 @@
+# API gateway
+
+The `monitor` Go binary (port 3001) is also a reverse-proxy gateway. HF exposes only one public
+port, so all three backend APIs are reached under one base URL by path prefix.
+
+## Routing (`monitor/main.go`)
+
+| Public prefix | → forwards to | Prefix stripped |
+|---------------|---------------|-----------------|
+| `/gpt/…` | `127.0.0.1:9225` | `/gpt/api/chat` → `/api/chat` |
+| `/gemini/…` | `127.0.0.1:8000` | `/gemini/chat` → `/chat` |
+| `/flow/…` | `127.0.0.1:8101` | `/flow/generate/video` → `/generate/video` |
+
+`gatewayHandler(prefix, target)` builds one `httputil.ReverseProxy` whose `Director` rewrites the
+host and strips the prefix. The monitor's own routes (`/`, `/api/*`, `/chrome.log`) are untouched.
+
+## Auth — `API_KEY` (fail-closed)
+
+`authOK()` gates the three prefixes:
+- Reads `API_KEY` from env once at startup.
+- Requires `Authorization: Bearer <API_KEY>` (also accepts `?key=`).
+- **Unset `API_KEY` → every gateway call returns `503`** (so accounts are never accidentally open).
+- Wrong/missing key → `401`.
+- The monitor UI stays open (no key) so the live view keeps working.
+
+Set it: HF secret `API_KEY` (Settings) or Docker `.env` `API_KEY=…`. Use a long random string,
+e.g. `openssl rand -hex 24`.
+
+## Why not a separate Space for the servers?
+The extensions dial `ws://127.0.0.1:9225/9226/9227` — hardcoded localhost
+(`*/background.js`). A second Space is a different machine with a different `127.0.0.1`, so its
+servers could never receive the extension connections. Hence: one container, gateway out front.
+
+## Adding a new route
+1. Server listens on a new localhost port inside the container.
+2. Launch it in `start_hf.sh` (step 6a).
+3. Add `http.HandleFunc("/x/", gatewayHandler("/x", "http://127.0.0.1:PORT"))` in `monitor/main.go`.

docs/architecture.md

@@ -0,0 +1,44 @@
+# Architecture — one container, everything inside
+
+Everything runs in **one container** built from the root `Dockerfile`. The extensions inside
+Chrome dial their servers on hardcoded `127.0.0.1` ports, so the servers **must** share Chrome's
+localhost — a separate machine/Space can never reach them. That's why there's a single image, not
+microservices.
+
+```
+            https://…hf.space   (only port 3001 is public)
+                     │
+            ┌────────▼─────────┐
+            │ monitor :3001     │  UI + API gateway (one Go binary)
+            │  /  /chrome.log   │  (open, no key)
+            │  /gpt /gemini /flow│  (API-key gated → localhost)
+            └──┬──────┬──────┬──┘
+       9225 ───┘   8000│      └─── 8101
+   (chatgpt)      (gemini)        (flow)
+        │             │             │
+   ws 9225       ws 9226       ws 9227     ◄── extensions dial in (localhost)
+        └──────── Chrome (headless) + 3 unpacked extensions ────────┘
+              CDP 9222  ·  socat proxy 9223  ·  profile in /home/chrome/data
+```
+
+## Port map (all on the container's 127.0.0.1)
+
+| Port | Who | Purpose |
+|------|-----|---------|
+| 3001 | monitor | UI + API gateway (**only published port**) |
+| 9222 | Chrome | DevTools Protocol (CDP) |
+| 9223 | socat | CDP proxied for external tools |
+| 9225 | chatgpt server | HTTP API **and** extension WS (same port) |
+| 8000 / 9226 | gemini server | HTTP API / extension cookie-WS |
+| 8101 / 8100 / 9227 | flow server | HTTP API / ext-callback / extension WS |
+
+## What starts it
+`start_hf.sh` (the container entrypoint) in order: restore profile from Postgres → clean profile →
+start monitor (3001) → CDP proxy → **start the 3 backend servers** (step 6a) → launch Chrome with
+the 3 extensions. Each server logs to `/home/chrome/{chatgpt,gemini,flow}.log`.
+
+## Components added on top of the base image
+- `monitor/` — Go UI, now also the **reverse-proxy gateway** (`gatewayHandler`, `authOK`).
+- `profilesync/` — Go tool, Chrome profile ⇄ Postgres snapshot.
+- `chatgpt-free-api/`, `free-gemini-api/` (Go) + `flow-agent/` (Python/FastAPI) — the 3 servers,
+  built/installed into the image by the `Dockerfile`.

docs/deployment.md

@@ -0,0 +1,46 @@
+# Deployment
+
+## Hugging Face (this repo == the Space)
+
+1. **Push** to `main` → HF auto-rebuilds:
+   ```bash
+   git push origin main
+   ```
+2. **Set secrets** once (Settings → Variables and secrets):
+   - `DATABASE_URL` — Neon Postgres (persistence). See [persistence.md](persistence.md).
+   - `API_KEY` — gateway auth. See [api-gateway.md](api-gateway.md).
+3. After build → **log in** to ChatGPT/Gemini/Flow in the monitor UI once.
+
+### HF git auth (important)
+The `origin` remote embeds a token: `https://<user>:<hf_token>@huggingface.co/spaces/<user>/<space>`.
+- The token **must belong to the Space owner** (`akash1313`) with `repo.write`. A token from a
+  different account → `pre-receive hook declined: You are not authorized to push`.
+- Rotate/replace the token in the URL with:
+  `git remote set-url origin https://akash1313:<NEW_TOKEN>@huggingface.co/spaces/akash1313/selfapi`
+- Local token files (`hf-token`, `neon-db`, `api-key`) are gitignored — never commit them.
+
+### Watch the build
+```bash
+curl -s -H "Authorization: Bearer <hf_token>" \
+  https://huggingface.co/api/spaces/akash1313/selfapi/runtime
+# stage: RUNNING_BUILDING → RUNNING_APP_STARTING → RUNNING   (errors: BUILD_ERROR / RUNTIME_ERROR)
+```
+
+## Self-host Docker
+```bash
+echo "API_KEY=$(openssl rand -hex 24)" > .env     # gateway auth (DATABASE_URL not needed)
+docker compose up --build -d
+```
+Only the `chrome` service exists — it bakes in all 3 servers. Open `http://localhost:3001`.
+
+## Dockerfile build stages (what gets built)
+| Stage | Image | Output |
+|-------|-------|--------|
+| `monitor-build` | golang:1.22 | `/monitor` (UI + gateway) |
+| `profilesync-build` | golang:1.22 | `/profilesync` |
+| `chatgpt-build` | golang:1.26 | `/agent` (+ `config.json`) |
+| `gemini-build` | golang:1.26 | `/free-gemini-api` |
+| final (on `akashyadav758/chrome`) | — | copies binaries, `pip install` flow deps, installs Chrome-for-Testing, perms |
+
+> If you bump a server's `go.mod` Go version, bump its build-stage image too, or the build pulls a
+> toolchain at build time.

docs/persistence.md

@@ -0,0 +1,37 @@
+# Persistence — staying logged in
+
+The Chrome profile (cookies/logins) lives in `/home/chrome/data`. How it survives a restart
+depends on where you run.
+
+## Hugging Face → Neon Postgres (required)
+
+HF free `cpu-basic` Spaces have **no persistent disk** — the filesystem is wiped on every
+restart/rebuild. So the profile is snapshotted to an external Postgres DB by the `profilesync` tool:
+
+- **Boot:** `profilesync restore` pulls the last snapshot.
+- **Every 5 min + on shutdown:** `profilesync backup` saves it.
+- Stored as one row: `chrome_profile(id, updated_at, data bytea)` (auto-created).
+- **Gated on `DATABASE_URL`.** Not set → restore/backup skipped → logins lost on restart.
+
+### Setup
+1. Free DB at [neon.tech](https://neon.tech) → copy the connection string
+   (`postgresql://user:pass@host.neon.tech/db?sslmode=require`).
+2. HF Space → Settings → Variables and secrets → secret **`DATABASE_URL`** = that string.
+3. Saving auto-restarts the Space. **Log in once** after that → first backup within 5 min → survives
+   all future restarts.
+
+### Verify a backup landed
+```sql
+SELECT id, updated_at, octet_length(data) FROM chrome_profile;
+```
+A row with non-zero size = persisted. (Profile stays small — junk/cache is stripped each boot;
+typically 0.5–2 MB. Neon free = 512 MB, so it's ~0.1% used.)
+
+## Self-host Docker → named volume (no DB needed)
+
+`docker-compose.yml` mounts the `chrome-profile` named volume at `/home/chrome/data`, so logins
+survive `docker compose down/up` and reboots automatically. **`DATABASE_URL` is not needed** for
+Docker. To wipe the profile: `docker compose down -v`.
+
+> Important: setting a new secret on HF forces a restart. If you log in *before* `DATABASE_URL` is
+> set, that login is lost on the restart the secret triggers — log in again afterward.

docs/troubleshooting.md

@@ -0,0 +1,41 @@
+# Troubleshooting — check here first
+
+Every issue we actually hit, and the fix.
+
+## Deploy / build
+
+| Symptom | Cause → Fix |
+|---------|-------------|
+| `pre-receive hook declined: You are not authorized to push` | The token in the `origin` URL isn't the Space owner's. Use an `akash1313` token with `repo.write` (see [deployment.md](deployment.md)). |
+| `Repository not found` on push | Remote points to a Space that doesn't exist. `git remote -v` and fix the name (we deploy to `akash1313/selfapi`). |
+| Build `BUILD_ERROR` after bumping a server | `go.mod` Go version > build-stage image. Raise the `FROM golang:X` in the Dockerfile. |
+| Python `externally-managed-environment` during pip | Debian 12 PEP-668. We use `pip3 install --break-system-packages` (already in Dockerfile). |
+| Frequent restarts | Normal: **every `git push` and every secret change rebuilds.** Batch edits into one push. Not a CPU/RAM issue (cpu-basic = 2 vCPU / 16 GB; usage ~1–2 GB). |
+
+## API gateway
+
+| Symptom | Cause → Fix |
+|---------|-------------|
+| All `/gpt /gemini /flow` return `503` | `API_KEY` not set on the server. Set the secret (fail-closed by design). |
+| `401` | Missing/wrong `Authorization: Bearer <key>`. |
+| `502 backend unavailable` | That server is still booting or crashed. Check its log `/home/chrome/{chatgpt,gemini,flow}.log`. |
+| `404` through the gateway | Path forwarded but wrong on the backend — check the route in [../HOWTOUSE.md](../HOWTOUSE.md). |
+
+## Runtime / browser
+
+| Symptom | Cause → Fix |
+|---------|-------------|
+| Login lost after restart | `DATABASE_URL` unset or DB unreachable (HF). Set the Neon secret; verify a row in `chrome_profile`. |
+| ChatGPT Cloudflare "verify you are human" loops | UA/OS mismatch. The UA **must be Linux** (the Space runs Linux) — it's set in `start_hf.sh` and `chatgpt-free-api/cookies.go` (Chrome 145). If it still loops, it's the datacenter IP (HF=AWS) → use a residential `--proxy-server`. |
+| `extensionConnected:false` / `has_flow_key:false` on `/…/health` | The in-Chrome extension hasn't connected to its server yet. It connects when (a) Chrome has loaded the extension and (b) **you're logged in** to that service. Open the monitor UI, log in, wait. Extensions auto-retry (~5 s reconnect alarm). |
+| `chrome://extensions/` empty, no error | Branded Chrome ignoring `--load-extension` → must use Chrome for Testing (already in Dockerfile). |
+| `Failed to connect to the bus` / `DidStartWorkerFail` in `chrome.log` | Harmless container warnings — not a crash. |
+| "Restore pages?" popup | Handled by the `exit_type=Normal` Preferences injection in `start_hf.sh`. |
+
+## Self-host Docker
+
+| Symptom | Cause → Fix |
+|---------|-------------|
+| Port collision on 9225/8000/8101 | Don't add separate server containers — the `chrome` image already runs all 3. `docker-compose.yml` has only the `chrome` service by design. |
+| APIs return `503` locally | Add `API_KEY=…` to `.env` (compose passes it to the chrome service). |
+| Profile not persisting | Don't use `down -v` (that deletes the `chrome-profile` volume). |