Harden MVP runtime and fix packaged desktop white screen

README.md

@@ -8,6 +8,75 @@ Quick links
 - Frontend: `frontend/`
 - Backend: `backend/`
 
+Dedicated ports list (single source of truth)
+
+This project keeps all port assignments in the root `.env` file so services do not get mixed with other projects:
+
+- `PORT_BACKEND` (API)
+- `PORT_FRONTEND_DEV` (Vite dev)
+- `PORT_FRONTEND_DEV_FALLBACK` (optional fallback)
+- `APP_URL`, `API_BASE`, `VITE_API_URL` (URL defaults tied to those ports)
+
+View the current dedicated map and whether each port is already in use:
+
+```bash
+npm run ports:list
+```
+
+Canonical MVP startup (from project root)
+
+1) Install dependencies
+
+```bash
+npm install
+npm install --prefix backend
+npm install --prefix frontend
+```
+
+2) Start backend API
+
+```bash
+docker compose up -d
+curl http://localhost:4000/health
+```
+
+3) Run web app (browser)
+
+```bash
+npm run dev --prefix frontend
+```
+
+Or run backend + web frontend together from the root:
+
+```bash
+npm run dev:web
+```
+
+Stop backend + web frontend from the root:
+
+```bash
+npm run dev:web:stop
+```
+
+4) Run desktop app (Electron + Vite)
+
+```bash
+npm run dev
+```
+
+For production-style desktop launch from built files:
+
+```bash
+npm run build:renderer
+npm run start
+```
+
+5) Build desktop app
+
+```bash
+npm run build:desktop
+```
+
 Development
 
 1) Backend (fast, using Docker):
@@ -155,4 +224,18 @@ npm run test:wiring
 Optional env vars for this test:
 
 - `API_BASE` (default `http://localhost:4000/api`)
-- `WRITE_API_KEY` (required if write endpoints are protected)
+- `WRITE_API_KEY` (required if write endpoints are protected)
+
+MVP readiness check
+
+Run one command to verify backend health, route wiring, and persistence:
+
+```bash
+npm run test:mvp
+```
+
+To also verify persistence across a backend restart:
+
+```bash
+npm run test:mvp:restart
+```