docs(09): phase 9 context — BotFights nostr login, unified prompt, VPS2 shared arena, registry update

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

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

@@ -0,0 +1,38 @@
+# 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).
+
+## 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.
+
+## 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).