archy/.planning/phases/09-botfights-platform-upgrade/09-CONTEXT.md

# Phase 9: BotFights Platform Upgrade — Context

**Source:** User-directed express path (2026-07-30 session; requirements stated verbatim by the user, equivalent to discuss-phase output)

## Domain

BotFights is a standalone app (separate repo) distributed to Archipelago nodes as a container app via the signed catalog. Users register AI bots that battle in trivia/arcade fights; humans can also fight via controllers. Today every node runs a fully isolated arena (own SQLite DB), login is an unauthenticated "trust the pubkey" POST, and bot setup requires hopping across four markdown docs.

**App source repo:** `/home/archipelago/Projects/botfight` — main repo is now `https://source.archipelago-foundation.org/lfg2025/botfights` (mirrored 2026-07-30 from git.tx1138.com/lfg2025/botfight with full history; remote `origin` = our Gitea, remote `tx1138` = old home). Stack: pnpm workspace, Vue 3 + Vite frontend, Hono/TypeScript server, SQLite via drizzle-orm, SSE fight streaming, Dockerfile → image published to vps2 registry `146.59.87.168:3000/lfg2025/botfights` (currently 1.1.0).

**Archy-side artifacts:** `apps/botfights/manifest.yml`, signed app-catalog (`app-catalog/catalog.json` + releases), app icon in neode-ui.

## Locked Decisions (user-stated)

1. **BOT-01 — Native nostr signer login.** Replace the bare-pubkey `POST /api/auth/login` trust model with a real signer flow: NIP-07 (`window.nostr` — browser extension / Amber on Android) + NIP-98 signed HTTP auth event verified server-side, per the design already written in the repo's `nostr-login-implementation.md`. The user never shares a private key with the app.
2. **BOT-02 — One self-contained AI bot-setup prompt.** The current DocsPage (BOTFIGHTS.md / BOTFIGHTS-EASY.md / BOTFIGHTS-POLLING.md / BOTFIGHTS-WEBHOOK.md + BOT_SETUP.md) is confusing. Replace with a single copy-paste prompt that contains EVERYTHING an AI agent needs to set up a working bot: registration, auth/secrets handling, webhook AND polling protocols, all API endpoints, response formats. "It all needs to be given inside the one prompt."
3. **BOT-03 — Shared public match endpoint on VPS2.** Every node's BotFights instance must use a public arena endpoint hosted on VPS2 (146.59.87.168, docker + nginx-proxy-manager; subdomains under `archipelago-foundation.org` available, pattern: new NPM proxy host + Let's Encrypt) **by default**, so all nodes see all fighters and battle across nodes. Node-local instance remains the runtime but match/fighter state is the shared public arena.
4. **BOT-04 — Registry/manifest update.** New app version: build + push new image to the vps2 registry, bump `apps/botfights/manifest.yml`, regenerate + re-sign + republish the signed catalog (catalog manifest overlay supremacy — disk edits don't apply to catalog-covered apps).

## Architecture Decision (user, 2026-07-30): Arena-as-relay

BOT-03 is built and DOCUMENTED as a decentralized "arena = nostr relay" model, per project philosophy:
- **Any node can host a public arena** — it is the same app image; a public arena is just a BotFights instance without `ARENA_UPSTREAM_URL` that others point at.
- **Each node chooses its arena community** via `ARENA_UPSTREAM_URL` (env/manifest); unset = standalone.
- **The Foundation's VPS2 arena is only the well-known default**, like the vps2 FIPS anchor — a rendezvous, not an authority. Nothing in the code hardcodes a center.
- **Canonical arena URL (updated 2026-07-30, supersedes the plain-IP decision): `https://botfights.archipelago-foundation.org`** — the user created the DNS A record + NPM proxy host + Let's Encrypt cert mid-execution. TLS is live and verified; `TRUSTED_PROXY=1` enabled on the arena. Raw fallback `http://146.59.87.168:9100` still works. `ARENA_UPSTREAM_URL` in the manifest (09-06) and all docs/prompt examples use the HTTPS domain.
- The game UI is always served from the user's own node; only match/fighter state lives on the chosen arena.
- The unified AI prompt + docs (BOT-02) and `docs/arena-deployment.md` MUST present it this way, including "how to host your own arena" as a first-class section.
- Later phase (roadmap note): nostr-event-based fighter/arena discovery across multiple arenas.

## Claude's Discretion

- Exact architecture for BOT-03 (thin-client mode vs sync/federation protocol) — chosen during planning based on research; bias toward the simplest thing that makes "all nodes see all fighters" true.
- JWT/session mechanics, token TTLs, migration path for existing registered bots (preserve existing bots — migrations never destroy data).
- Whether the unified prompt lives at a stable GET endpoint (e.g. `/api/docs/prompt` or `/prompt.md`) plus a copy button in the UI — recommended so the prompt is itself fetchable by AI agents.
- Version number for the release (suggest 1.2.0).

## Scope Fence

- IN: botfights repo changes (server + frontend + docs/prompt), VPS2 public arena deployment, archy manifest/catalog update, dev-pair verification.
- OUT: Lightning/cashu payment changes, arcade gameplay changes, tournament logic, companion app work, any archy core/orchestrator changes beyond the manifest/catalog.

## Hard Deadline / Demo Constraint (added 2026-07-30)

**The user demos this TOMORROW (2026-07-31) from archi-dev-box.** Everything must be deployed and verified working on archi-dev-box before end of this phase. Real bot testing will be done with a **cloud-hosted "openclaw" bot** — meaning: the VPS2 public arena must be internet-reachable with TLS, the unified AI bot-setup prompt must be sufficient for a cloud agent to register and fight using only that prompt, and webhook/polling must work from outside the LAN (cloud bot → public arena). Prioritize the demo-critical path over nice-to-haves.

## Constraints & Process Rules

- Rootless podman invariants on nodes; VPS2 uses docker + nginx-proxy-manager (this is host infra, not a node app).
- Commit + push every unit of work (botfights repo → origin = our Gitea main; archy → gitea-ai main).
- Deploy/verify on dev pair (archi-dev-box + x250-dev) before any OTA/catalog publish.
- Never commit secrets; catalog artifacts are signed offline by the user.
- Test the real user path before claiming fixed (signer login in a real browser, a real cross-node fight visible from two instances).