Add docs/ covering configuration, storage, deployment, and operations

Mirrors TranslationUI's docs structure. Documents the shared-droplet
architecture specifically (same Caddy/oauth2-proxy as TranslationUI,
cookie-domain widened to cover both apps' subdomains) since that's the
part most likely to confuse someone debugging this app in isolation.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

README.md

@@ -73,3 +73,7 @@ the July Launch content pipeline (e.g. `Dharmakaya` → `Darmakaya`, `Phagmo`
 | `ELEVENLABS_API_KEY` | Yes | ElevenLabs synthesis calls. |
 | `HF_TOKEN` | Yes, to save/remove glossary entries | Write access to the `tts-glossary` dataset repo. Reads fall back to a local cache (or built-in defaults) without it. |
 | `GLOSSARY_DATASET_REPO` | No | Overrides the glossary dataset repo id. Defaults to `GarchenArchive/tts-glossary`. |
+
+## Docs
+
+This app also deploys to a DigitalOcean droplet (shared with TranslationUI), independent of the HF Space. See [docs/](docs/) for configuration, storage design, deployment, and operations.

docs/README.md

@@ -0,0 +1,15 @@
+# ArchiveAI-TTS docs
+
+ArchiveAI-TTS is a Gradio UI around the ElevenLabs API for interpreter audio synthesis — no local ML model, purely CPU. Deployed to two independent targets from the same `main` branch:
+
+- **HuggingFace Space** (`GarchenArchive/ArchiveAI-TTS`) — the original deployment, still live.
+- **DigitalOcean droplet** — shares the same droplet as TranslationUI (same Caddy instance, same Google-auth gate), on its own container/port/subdomain.
+
+Start here, then go deeper:
+
+- **[configuration.md](configuration.md)** — every environment variable the app reads.
+- **[storage.md](storage.md)** — how projects (including generated audio) and the glossary are stored, and why there are two backends.
+- **[deployment.md](deployment.md)** — how each target is built and deployed, and what "sharing a droplet with TranslationUI" actually means.
+- **[operations.md](operations.md)** — runbook and known gaps.
+
+Root-level [README.md](../README.md) covers the app's actual features (Turn Review, Quick Synthesize).

docs/configuration.md

@@ -0,0 +1,26 @@
+# Configuration
+
+## App-level environment variables
+
+| Variable | Required | Purpose |
+|---|---|---|
+| `ELEVENLABS_API_KEY` | Yes | Actual TTS synthesis — this app has no local model, everything goes through ElevenLabs. |
+| `GEMINI_API_KEY` | Yes (for AI-assisted turn generation) | Used by the turn-generation feature (`app.py`); raises a `gr.Error` if unset when that feature is used. |
+| `HF_TOKEN` | Only on the HF Space, and on DO (for the shared glossary — see below) | Selects the HF-dataset backend for project storage when `TTS_DATA_DIR` is unset. Independently, also used by `glossary.py` to sync pronunciation entries regardless of which project-storage backend is active. |
+| `TTS_DATA_DIR` | Only on DO | Root directory for local project/defaults storage. Set to `/data` on the droplet (the mounted volume subdirectory). Unset locally defaults to `data/tts_projects/` (repo-relative, git-ignored). |
+| `TTS_PROJECTS_DATASET_REPO` | No (has a default) | Overrides which HF dataset the HF backend uses for projects. Default: `GarchenArchive/tts-turn-projects`. |
+| `GLOSSARY_DATASET_REPO` | No (has a default) | Overrides which HF dataset the glossary syncs to. Default: `GarchenArchive/tts-glossary`. |
+
+## Infra-level secrets (DO deployment, not read by the app itself)
+
+Shared with TranslationUI's droplet — see [TranslationUI's configuration.md](../../TranslationUI/docs/configuration.md) for the Google OAuth / Caddy / oauth2-proxy secrets, which are identical here since it's the same auth layer.
+
+| Secret | Where it lives | Purpose |
+|---|---|---|
+| `DO_CI_TOKEN` | GitHub Actions secret (this repo) | Registry-only DO API token — same credential value as TranslationUI's, added separately here since it's a different GitHub repo. |
+| `DO_SSH_PRIVATE_KEY` | GitHub Actions secret (this repo) | Same droplet SSH key as TranslationUI's. |
+| `DO_DROPLET_HOST` | GitHub Actions variable (not secret) | The shared droplet's IP. |
+
+## Which backend runs where
+
+Same pattern as TranslationUI: `_use_local()` in `project_store.py` picks the local-file backend whenever `TTS_DATA_DIR` is set, the HF-dataset backend otherwise (if `HF_TOKEN` is set), local-file as the final fallback. See [storage.md](storage.md).

docs/deployment.md

@@ -0,0 +1,41 @@
+# Deployment
+
+Two independent targets, both built from `main`. Same pattern as TranslationUI: separate GitHub Actions workflows, neither edits the other.
+
+| | HF Space | DO droplet |
+|---|---|---|
+| Workflow | `.github/workflows/deploy.yml` | `.github/workflows/deploy-do.yml` |
+| Triggers | `workflow_dispatch` + nightly (00:00 UTC, skipped if unchanged) | Same |
+| Target | `huggingface.co/spaces/GarchenArchive/ArchiveAI-TTS` | The droplet shared with TranslationUI, via SSH |
+| Image registry | N/A | DO Container Registry, repo `garchen-archive/archiveai-tts` |
+| Public URL | The Space's own URL | `https://archiveai-tts.64-225-26-230.nip.io` |
+| Access control | HF's private-Space account whitelist | Google OAuth via oauth2-proxy, shared with TranslationUI |
+
+## Sharing a droplet with TranslationUI
+
+Both apps are CPU-only and lightweight enough to coexist on one droplet:
+
+- **Same droplet, separate containers**: `translationui-pilot` on internal port `7860`, `archiveai-tts-pilot` on `7861`, both bound to `127.0.0.1` only.
+- **Same Caddy instance**, routing by hostname — a second site block was added to the existing `/etc/caddy/Caddyfile` for `archiveai-tts.64-225-26-230.nip.io`, reverse-proxying to `127.0.0.1:7861`.
+- **Same oauth2-proxy, same Google OAuth app, same allowlist** — one login covers both apps. This required widening oauth2-proxy's cookie scope: `OAUTH2_PROXY_COOKIE_DOMAINS` and `OAUTH2_PROXY_WHITELIST_DOMAINS` were both set to `.64-225-26-230.nip.io` so the session cookie set on one subdomain is valid on the other. (nip.io is on the Public Suffix List at the `nip.io` level, not per-IP, so `.64-225-26-230.nip.io` is a valid single-site cookie scope — it doesn't leak across other unrelated nip.io users.)
+- **Same Volume, separate subdirectory**: TranslationUI's SQLite file lives at the volume root; TTS's project files live under `tts/` on the same volume, mounted into its container at `/data` (a different container path than TranslationUI's, but the same physical disk).
+- **Same DO Project** ("HF Migration"), same isolation-token approach as the rest of this migration.
+
+## CI/CD (`deploy-do.yml`)
+
+Same shape as TranslationUI's: build → push to `registry.digitalocean.com/garchen-archive/archiveai-tts` → SSH in → pull, stop/remove the old container, start the new one with:
+
+- `-p 127.0.0.1:7861:7860`
+- `-v /mnt/hfmigration_translationui_data/tts:/data`
+- `-e TTS_DATA_DIR=/data`
+- `--env-file /root/archiveai-tts.env` (holds `ELEVENLABS_API_KEY`, `GEMINI_API_KEY`, `HF_TOKEN` — never passed through CI logs or command args)
+
+Reuses the same `DO_CI_TOKEN`/`DO_SSH_PRIVATE_KEY` credential *values* as TranslationUI, added as this repo's own GitHub Actions secrets (a registry-scoped token isn't tied to a specific app, but GitHub secrets are per-repo, so it has to be added twice).
+
+## Manual deploy / debugging
+
+```bash
+ssh -i <hf-migration-do private key> root@<droplet-ip>
+docker ps --filter name=archiveai-tts-pilot
+docker logs archiveai-tts-pilot --tail 50
+```

docs/operations.md

@@ -0,0 +1,41 @@
+# Operations
+
+## Redeploying
+
+- **HF Space**: run the `Deploy to HF Space` workflow (`workflow_dispatch`), or wait for the nightly run.
+- **DO droplet**: run the `Deploy to DO` workflow (`workflow_dispatch`), or wait for the nightly run.
+
+Both skip themselves on the nightly schedule if `main` hasn't changed since the last deploy.
+
+## Checking on the DO droplet
+
+```bash
+ssh -i <hf-migration-do private key> root@<droplet-ip>
+
+docker ps --filter name=archiveai-tts-pilot
+docker logs archiveai-tts-pilot --tail 50
+
+# Shared with TranslationUI — check these if auth or routing seems broken,
+# not just this app's own container:
+systemctl status caddy
+docker logs oauth2-proxy --tail 50
+```
+
+## Rotating secrets
+
+| Secret | How |
+|---|---|
+| `ELEVENLABS_API_KEY` / `GEMINI_API_KEY` | Edit `/root/archiveai-tts.env` on the droplet, then restart the container (or redeploy). |
+| `HF_TOKEN` | Same file — remember this one also gates glossary sync, not just an unused leftover. |
+| `DO_CI_TOKEN`, `DO_SSH_PRIVATE_KEY`, Google OAuth credentials | Shared with TranslationUI — see that repo's `docs/operations.md`. Rotating them there also affects this app, since it's the same droplet/auth layer. |
+
+## Managing the oauth2-proxy allowlist
+
+Shared with TranslationUI — same file (`/root/oauth2-proxy/authenticated-emails.txt` on the droplet), same restart command (`docker restart oauth2-proxy`). Adding someone there grants access to both apps at once.
+
+## Known gaps
+
+- **No automated backup of local project data.** TranslationUI's nightly-cron-to-HF-dataset pattern is the template to reuse here; not yet done.
+- **No staging slot, single droplet, no HA** — same acknowledged tradeoffs as TranslationUI, for the same reason (expected usage is a handful of internal users).
+- **No real domain** — same `nip.io` placeholder as TranslationUI.
+- **Not yet burned in.** Just stood up; hasn't run in parallel with the HF Space long enough to build confidence before any cutover conversation.

docs/storage.md

@@ -0,0 +1,39 @@
+# Storage: two backends for projects, one shared store for the glossary
+
+## Turn Review projects (`tts/core/project_store.py`)
+
+Two backends, auto-selected by `_use_local()`:
+
+- **Local files** — used whenever `TTS_DATA_DIR` is set (the DO droplet). Same relative layout as the HF backend, rooted at `TTS_DATA_DIR`:
+  ```
+  {root}/index.json
+  {root}/projects/{id}/project.json
+  {root}/projects/{id}/turns.json
+  {root}/projects/{id}/captions.*
+  {root}/projects/{id}/audio/turn_{NN}.mp3
+  {root}/defaults.json
+  ```
+  Plain files, not a database — most of what's stored here is generated audio (mp3s), which fits a filesystem far more naturally than database rows. This is a deliberate difference from TranslationUI's SQLite approach, made because this store's data is mostly binary media, not small JSON records.
+- **HF dataset** — used when only `HF_TOKEN` is set and no `TTS_DATA_DIR` is given (the HF Space, which has no persistent disk of its own).
+
+**Why two backends exist at all**: same reason as TranslationUI — both deploy targets build from the same `main` branch, so a local-only rewrite would have silently broken the HF Space's persistence on its next deploy.
+
+A project save overwrites the previous save for that `id` — it's a single in-progress document, not versioned history. `turns_json_bytes`/`captions_bytes` are only written on the initial save (right after upload); routine autosaves don't rewrite them. A process-level lock (`_SAVE_LOCK`) serializes the index read-modify-write in both backends, since autosaves fire frequently and several sessions can share one process.
+
+Every function fails open (`None` / `[]` / `False`, logged warning) if its backend can't be reached.
+
+## Pronunciation glossary (`tts/core/glossary.py`) — intentionally shared, not dual-backend
+
+Unlike project storage, the glossary was **not** rewritten. It already had the right shape: a local cache file (at `/data/glossary_cache.json` if `/data` exists, else a repo-relative path) plus a best-effort sync to a shared HF dataset (`GarchenArchive/tts-glossary`) — reads prefer the Hub, fall back to the local cache, then to hardcoded seed defaults if neither is available.
+
+**Decision: DO and the HF Space share this same glossary dataset.** Low-risk (it's just pronunciation substitutions, not user data) and keeps both deployments producing identical pronunciations. This means the DO container needs `HF_TOKEN` set even though it also has `TTS_DATA_DIR` set for local project storage — the two env vars serve different, independent purposes here (`TTS_DATA_DIR` controls where *projects* live; `HF_TOKEN` controls whether the *glossary* syncs anywhere beyond its local cache).
+
+Mounting the shared Volume at `/data` in the container gives the glossary a persistent cache location for free, with zero code changes — it was already written to look for `/data` if present.
+
+## Migrating data between backends
+
+No standing migration tooling in the repo — the one-time HF-to-local migration (3 projects, all their audio) was done with a throwaway script, not committed. If this needs to happen again, `project_store.save_project()` / `save_turn_audio()` are the safest way to write into the local backend from a migration script, since they guarantee the on-disk layout matches what the running app writes.
+
+## Known gap
+
+No automated backup of the local project data yet — see [operations.md](operations.md#known-gaps). TranslationUI's nightly HF-dataset backup pattern (see its own docs) is the natural template to reuse here, adapted for a directory tree instead of a single file.