fix: address review — migration comment, link ring buffer constants (#170)

docs/ENVIRONMENT.md

@@ -0,0 +1,99 @@
+# ENVIRONMENT.md — Local Dev Stack
+
+How to start, stop, and verify the harb development environment.
+
+## Stack Overview
+
+Docker Compose services (in startup order):
+
+| Service | Purpose | Port | Health Check |
+|---------|---------|------|-------------|
+| **anvil** | Local Ethereum fork (Base Sepolia) | 8545 | JSON-RPC response |
+| **postgres** | Ponder database | 5432 | pg_isready |
+| **bootstrap** | Deploys contracts to anvil | — | One-shot, exits 0 |
+| **ponder** | On-chain indexer + GraphQL API | 42069 | HTTP /ready or GraphQL |
+| **landing** | Landing page (Vue 3 + Vite) | 5174 | HTTP response |
+| **webapp** | Staking app (Vue 3) | 5173 | HTTP response |
+| **txn-bot** | Automated recenter/tx bot | — | Process alive |
+| **caddy** | Reverse proxy / TLS | 80/443 | — |
+| **otterscan** | Block explorer | 5100 | — |
+
+## Quick Start
+
+```bash
+cd /home/debian/harb
+
+# Start everything
+docker compose up -d
+
+# Wait for bootstrap (deploys contracts, ~60-90s)
+docker compose logs -f bootstrap
+
+# Check all healthy
+docker compose ps
+```
+
+## Verify Stack Health
+
+```bash
+# Anvil (local chain)
+curl -s http://localhost:8545 -X POST -H 'Content-Type: application/json' \
+  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' | jq .result
+
+# Ponder (indexer + GraphQL)
+curl -s http://localhost:42069/graphql -X POST \
+  -H 'Content-Type: application/json' \
+  -d '{"query":"{ stats { id } }"}' | jq .
+
+# Landing page
+curl -sf http://localhost:5174 | head -5
+
+# Staking app
+curl -sf http://localhost:5173 | head -5
+```
+
+## Container Network
+
+Services communicate on `harb-network` Docker bridge.
+Internal hostnames match service names (e.g., `ponder:42069`).
+
+Landing page container IP (for Playwright testing): check with
+```bash
+docker inspect landing --format '{{.NetworkSettings.Networks.harb_harb-network.IPAddress}}'
+```
+
+## Common URLs (for testing/review)
+
+- **Landing:** `http://172.18.0.6:5174` (container IP) or `http://localhost:5174`
+- **Staking app:** `http://localhost:5173/app/`
+- **Ponder GraphQL:** `http://localhost:42069/graphql`
+- **Anvil RPC:** `http://localhost:8545`
+
+## Resource Notes
+
+- 8GB VPS — running full stack uses ~4-5GB RAM
+- npm install inside containers can OOM with all services running
+- Landing container takes ~2min to restart (npm install + vite startup)
+- 4GB swap is essential for CI + stack concurrency
+
+## Staking App Passwords
+
+For testing login: `lobsterDao`, `test123`, `lobster-x010syqe?412!`
+(defined in `web-app/src/views/LoginView.vue`)
+
+## Contract Addresses
+
+After bootstrap, addresses are in `/home/debian/harb/tmp/containers/contracts.env`.
+Landing sources this file on startup for `VITE_KRAIKEN_ADDRESS` and `VITE_STAKE_ADDRESS`.
+
+## Playwright Testing
+
+```bash
+# Chromium path
+/home/debian/.cache/ms-playwright/chromium-1209/chrome-linux64/chrome
+
+# Run against landing (block fonts for speed)
+NODE_PATH=$(npm root -g) node test-script.cjs
+```
+
+See `tmp/user-test-r4.cjs` for the most recent test script pattern.