Add documentation clarifying deployment configuration and operational tradeoffs

Add documentation to `replit.md` to specify `artifact.toml` as the canonical deployment configuration and enhance comments in `routes/index.ts` to explain operational tradeoffs for stub mode.

Replit-Commit-Author: Agent
Replit-Commit-Session-Id: 90c7a60b-2c61-4699-b5c6-6a1ac7469a4d
Replit-Commit-Checkpoint-Type: full_checkpoint
Replit-Commit-Event-Id: f46cc2d3-95ce-4f2b-8ab1-d8cd41d10743
Replit-Commit-Screenshot-Url: https://storage.googleapis.com/screenshot-production-us-central1/9f85e954-647c-46a5-90a7-396e495a805a/90c7a60b-2c61-4699-b5c6-6a1ac7469a4d/G03TLre
Replit-Helium-Checkpoint-Created: true

artifacts/api-server/src/routes/index.ts

@@ -41,6 +41,11 @@ router.use(worldRouter);
 // confirmation, so we expose it whenever stub mode is active regardless of NODE_ENV.
 // In real production with a live LNbits backend, stubMode is false, so these
 // routes remain unexposed.
+//
+// OPERATIONAL TRADEOFF: Running the testkit against a live node with LNBITS_STUB=true
+// (e.g. for CI without a real Lightning backend) will expose dev routes in that
+// process. This is intentional — stub mode has no real funds, so the exposure
+// is harmless. Never set LNBITS_STUB=true on a node with a real LNbits backend.
 if (process.env.NODE_ENV !== "production" || lnbitsService.stubMode) {
   router.use(devRouter);
 }

replit.md

@@ -338,6 +338,53 @@ Get your token from Gitea → User Settings → Applications → Generate Token.
 - `replit/token-gated-economy` — TypeScript API server (this repo)
 - `perplexity/the-matrix` — Three.js 3D world frontend
 
+## Deployment
+
+### Canonical deployment config — artifact.toml (not .replit)
+
+The API server's authoritative deployment configuration lives in
+`artifacts/api-server/.replit-artifact/artifact.toml`. This file controls the
+production build command and the run command for the always-on VM deployment.
+
+```
+deploymentTarget = "vm"
+buildCommand     = "pnpm --filter @workspace/api-server run build"
+runCommand       = "node artifacts/api-server/dist/index.js"
+```
+
+The root `.replit` file may show an older `deploymentTarget = "autoscale"` and
+`run = "dist/index.cjs"` — these are legacy entries left from when Replit
+platform protection blocked agent edits. **artifact.toml is the source of
+truth**; `.replit` entries for this artifact should be ignored.
+
+### VPS deployment (hermes — 143.198.27.163)
+
+The production instance runs on the user's VPS via systemd, outside Replit:
+
+| Item | Value |
+|---|---|
+| URL | `http://143.198.27.163/` |
+| Service | `systemctl status timmy-tower` |
+| Deploy dir | `/opt/timmy-tower/` |
+| Env file | `/opt/timmy-tower/.env` |
+| DB | `postgres://timmy:...@localhost:5432/timmy_tower` |
+| Nostr npub | `npub1e3gu2j08t6hymjd5sz9dmy4u5pcl22mj5hl60avkpj5tdpaq3dasjax6tv` |
+| AI backend | OpenRouter (`https://openrouter.ai/api/v1`) via Anthropic SDK compat layer |
+
+To redeploy after a build:
+```bash
+# From Replit — rebuild and copy bundle
+pnpm --filter @workspace/api-server run build
+cat artifacts/api-server/dist/index.js | ssh root@143.198.27.163 "cat > /opt/timmy-tower/index.js"
+ssh root@143.198.27.163 "systemctl restart timmy-tower"
+```
+
+External packages that must be present in `/opt/timmy-tower/node_modules/`:
+- `nostr-tools` (^2.23.3)
+- `cookie-parser` (^1.4.7)
+
+These are externalized by esbuild (not in the allowlist in `build.ts`).
+
 ## Roadmap
 
 ### Nostr integration