# Specs, services, links, and credentials register

This is the handover register for the VEGA77 CS Agent. It lists the production specs, services, links, and credential fields that must be available before go-live.

Important: do not publish real secrets in this markdown file. Actual credential values must stay in the secure local handoff source (`client_docs/CLIENT-TRY-GUIDE.txt`), the private credential file (`secrets/CREDENTIALS.txt`), the production server `config/.env`, or the client's approved password manager.

---

## 1. Project summary

| Field | Value |
|-------|-------|
| Client | YAYBPO Enterprise |
| Brand | VEGA77 |
| System | AI customer service agent with RAG answers, LiveChat integration, Telegram escalation alerts, dashboard, and controlled BO/RPA lookup layer |
| Production channel | LiveChat widget or LiveChat direct link |
| Internal alert channel | Telegram groups |
| Human customer reply channel | LiveChat agent dashboard |
| Telegram limitation | Normal Telegram discussion is internal only; random Telegram messages do not reach customers |
| Telegram reply mode | Controlled `/reply <case_id> <message>` command can send approved customer-facing replies back to LiveChat |
| BO/RPA status | Read-only lookup layer is implemented; enable with `BO_LOOKUP_MODE=rpa` only after BO access/IP/device approval is confirmed |

## 2. Public and internal links

| Item | Link / value | Notes |
|------|--------------|-------|
| Production apex | `https://ikon168.com/` | Served by production stack when DNS and Caddy are active. |
| Agent hostname | `https://agent.ikon168.com/` | CS Agent web UI/API target when subdomain DNS is active. |
| Client docs hostname | `https://docs.ikon168.com/` | Static client documentation pack when configured. |
| Customer portal preview | `https://portal.ikon168.com/` | Static IKON168 Customer Portal with embedded LiveChat widget. |
| Health endpoint | `/health` | Public probe endpoint; expected body `{"status":"ok"}`. |
| Stats endpoint | `/stats` | Requires Basic Auth when `DASHBOARD_PASSWORD` is set. |
| Chat API endpoint | `/chat` | Used by web demo; LiveChat path uses connector. |
| Kill switch endpoint | `/killswitch` | Ops only. |
| Resume endpoint | `/resume` | Ops only. |
| LiveChat direct link | Confirm in secure handoff | Client supplied direct link; verify before go-live. |
| LiveChat developer docs | `https://developers.livechat.com/docs/messaging/agent-chat-api` | Agent Chat API reference. |
| BO URL | Confirm in secure handoff | Do not publish BO credentials. |
| GCP project / VM | Confirm in secure handoff | Keep server access details private. |

## 3. Technology specs

| Layer | Spec |
|-------|------|
| API server | FastAPI + Uvicorn on container port 8080 |
| Production reverse proxy | Caddy with automatic HTTPS |
| Container runtime | Docker Compose |
| Production compose | `deploy/docker-compose.production.yml` |
| App entrypoint | `src/main.py` |
| AI model | Google Gemini 3 Flash |
| Embedding model | Google Gemini Embedding 2 |
| Vector database | ChromaDB persisted under `data/chroma` |
| State database | SQLite persisted under `data/sqlite` |
| Knowledge sources | `knowledge/Vega77 Promo.xlsx`, `knowledge/CS-SOP (2).xlsx`, uploaded SOP text where applicable |
| LiveChat integration | LiveChat Agent API v3.6, polling + outbound reply |
| Telegram integration | Telegram Bot API through `python-telegram-bot` |
| BO/RPA | Controlled read-only Playwright headless Chromium lookup layer |
| Logging | `logs/` volume and Docker logs |

## 4. Required environment values

| Env var | Purpose | Required for go-live? | Secure source |
|---------|---------|-----------------------|---------------|
| `GOOGLE_AI_API_KEY` | Gemini LLM and embedding access | Yes | Secure handoff / server `config/.env` |
| `LIVECHAT_ACCOUNT_ID` | LiveChat API account ID | Yes for LiveChat | Secure handoff / server `config/.env` |
| `LIVECHAT_PAT` | LiveChat Personal Access Token | Yes for LiveChat | Secure handoff / server `config/.env` |
| `TG_BOT_TOKEN` | Telegram bot token | Yes | Secure handoff / server `config/.env` |
| `TG_PAYMENT_GROUP_ID` | Payment alert group | Yes | Secure handoff / server `config/.env` |
| `TG_TECH_GROUP_ID` | Tech/CS alert group | Yes | Secure handoff / server `config/.env` |
| `TG_ADMIN_GROUP_ID` | Admin/compliance alert group | Yes | Secure handoff / server `config/.env` |
| `TG_REPLY_ALLOWED_USERNAMES` | Optional comma-separated allowlist for Telegram users who can use `/reply` and `/resolve` | Recommended for two-way Telegram | Secure handoff / server `config/.env` |
| `DASHBOARD_USERNAME` | Dashboard Basic Auth user | Yes for public dashboard | Secure handoff / server `config/.env` |
| `DASHBOARD_PASSWORD` | Dashboard Basic Auth password | Yes for public dashboard | Secure handoff / server `config/.env` |
| `BO_URL` | Backoffice login URL | Required only if BO/RPA is in scope | Secure handoff / server `config/.env` |
| `BO_USERNAME` | Backoffice username | Required only if BO/RPA is in scope | Secure handoff / server `config/.env` |
| `BO_PASSWORD` | Backoffice password | Required only if BO/RPA is in scope | Secure handoff / server `config/.env` |
| `BO_LOOKUP_MODE` | `off` or `rpa`; enables controlled read-only BO lookup when set to `rpa` | Required for AI-assisted BO checking | Server `config/.env` |
| `BO_LOOKUP_TIMEOUT_SECONDS` | Max BO lookup time before fallback | Optional override | Server `config/.env` |
| `ESCALATION_TIMEOUT_SECONDS` | Escalation nudge timing | Optional override | Server `config/.env` |
| `ROUTER_CONFIDENCE_THRESHOLD` | Router confidence threshold | Optional override | Server `config/.env` |

## 5. Service ownership

| Service | Owner to confirm | Access needed |
|---------|------------------|---------------|
| Namecheap DNS | RR / authorised domain owner | Ability to update A records |
| GCP VM / infrastructure | Zev / client technical owner | SSH or deployment access |
| LiveChat | Client CS/Ops | Admin access, API credentials, agent dashboard users |
| Telegram bot and groups | Client Ops / Zev | Bot token owner, group admins, group IDs |
| Google Gemini API | Zev / client technical owner | API key and billing/quota ownership |
| BO / SuperBO | Client Ops | Login, IP/device approval, RPA permission if used |
| Dashboard Basic Auth | Zev / client Ops | Username/password in password manager |

## 6. DNS and firewall values

| Item | Required value |
|------|----------------|
| DNS provider | Namecheap |
| Host records | `@`, `agent`, `docs` as A records if all hostnames are used |
| A record target | Current production VM public IPv4 from secure infrastructure handoff |
| Firewall inbound | TCP 80 and 443 for HTTPS; SSH restricted; avoid public 8080 in production |
| TLS | Caddy / Let's Encrypt |

## 7. Credential handover rules

| Rule | Requirement |
|------|-------------|
| Real secrets | Keep out of git and public static docs. |
| Secure source of truth | Use client password manager, server `config/.env`, and local gitignored handoff files. |
| Chat-shared passwords | Rotate before production if they were shared in normal chat and client requires tighter security. |
| Client ownership | Client must have access to dashboard, DNS, LiveChat, Telegram, BO, and infrastructure emergency contacts. |
| Updates | When any password/token changes, update the secure handoff file and server `config/.env` together. |

## 8. Final handover acceptance

| Check | Status |
|-------|--------|
| Client has production URLs. | Todo |
| Client has dashboard credentials through secure channel. | Todo |
| Client has LiveChat access and knows where to reply to customers. | Todo |
| Client understands normal Telegram chat is internal only, and only explicit `/reply` commands are customer-facing. | Todo |
| Client has escalation ownership table. | Todo |
| Client has rollback and kill-switch instructions. | Todo |

## 9. BO API check

The current repo does not contain official BO API credentials, tokens, or a documented BO API base URL. The BO web frontend references internal authenticated endpoints such as `/api/sbo/...`, `/member/api/v2/s/sbo/`, `/wallet/api/v2/s/sbo/`, and report/campaign/provider service paths, but those are browser-session endpoints from the BO application, not yet an approved external API contract.

Current implementation uses the controlled RPA lookup path. If the client/vendor can provide official BO API documentation, auth method, IP whitelist rules, and sample requests/responses, the lookup layer can switch from RPA to direct API without changing the agent behavior.