build(layer2+3): propagate .build/+dist/ to Docker/Electron/CI; codify light deploy; docs

Layer 3: Dockerfile COPY .next/standalone -> .build/next/standalone (+cache mount);
electron stage -> .build/electron-standalone + extraResources; CI asserts dist/server.js;
eslint ignores .build/**+dist/**. Layer 2: deploy-vps-* skills use build:release + rsync(dist)
-> remote app/ + pm2 restart + BUILD_SHA verify (drop npm-i-g/legacy-peer-deps/manual-wreq).
Docs (RELEASE_CHECKLIST/CONTRIBUTING/AGENTS/CHANGELOG) describe src/+.build/+dist/ layout.
Verified: docker build exit 0 + health 200; electron stage OK; no stale build-output refs.

CONTRIBUTING.md

@@ -59,13 +59,40 @@ These settings are stored in the database and persist across restarts, overridin
 npm run dev
 
 # Production build
-npm run build
+npm run build    # next build → .build/next/ then assembleStandalone → dist/
 npm run start
 
+# Release build (clean rebuild + HEAD sentinel — required for deploy)
+npm run build:release   # rm -rf .build dist && build + writes dist/BUILD_SHA
+
 # Common port configuration
 PORT=20128 NEXT_PUBLIC_BASE_URL=http://localhost:20128 npm run dev
 ```
 
+### Build Output Layout
+
+| Directory  | Contents                                    | Tracked |
+| ---------- | ------------------------------------------- | ------- |
+| `src/`     | Application source (TypeScript / TSX)       | Yes     |
+| `.build/`  | Intermediates — `next build` output (gitignored, `distDir = .build/next`) | No |
+| `dist/`    | Shippable bundle — assembled by `assembleStandalone` (gitignored) | No |
+
+The build pipeline is a single pass:
+
+```
+npm run build
+  └─ next build → .build/next/standalone  (Next.js output)
+  └─ assembleStandalone()                 (copies standalone + static + public + native assets)
+       └─ output: dist/                   (server.js, .next/static/, public/, node_modules/)
+```
+
+`npm run build:release` additionally cleans both directories first and writes
+`dist/BUILD_SHA` (= `git rev-parse --short HEAD`) as a deploy integrity sentinel.
+
+> **VPS deploy note:** the remote image directory `/usr/lib/node_modules/omniroute/app/`
+> is unchanged. The deploy skills rsync the contents of `dist/` into it.
+> Only the in-repo build output path moved (`app/` → `dist/`).
+
 Default URLs:
 
 - **Dashboard**: `http://localhost:20128/dashboard`
@@ -314,6 +341,10 @@ Write unit tests in `tests/unit/` covering at minimum:
 
 Releases are managed via the `/generate-release` workflow. When a new GitHub Release is created, the package is **automatically published to npm** via GitHub Actions.
 
+For VPS deploys, use `npm run build:release` (not `npm run build`) — it performs a clean
+rebuild, assembles the bundle into `dist/`, and writes the `dist/BUILD_SHA` sentinel.
+Then use the `/deploy-vps-*-cc` skills which rsync `dist/` to the remote `app/` directory.
+
 ---
 
 ## Getting Help