diff --git a/artifacts/api-server/src/routes/index.ts b/artifacts/api-server/src/routes/index.ts
index 34e15ab..1e1c604 100644
--- a/artifacts/api-server/src/routes/index.ts
+++ b/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);
 }
diff --git a/replit.md b/replit.md
index 7737209..c44d22c 100644
--- a/replit.md
+++ b/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