[#1007] docs(install-vps): Modernize VPS installation and remove legacy chat migration prose

[realproject7]

Closes #1007

Summary

Docs-only. Modernizes docs/install-vps.md: removes the obsolete AgentChattr cleanup/migration section and makes remote access secure and local-forward based, consistent with the current server security model (loopback bind + session token + trusted_dashboard_hosts). Scope: docs/install-vps.md only.

Changes

• Removed the "Migrating from Older Versions (AgentChattr cleanup)" section (pm2 agentchattr-* cleanup + config-key removal) — not relevant to a current install.
• New "Remote Access" section keeping control local-forward based:
  • Option A (recommended): SSH local port-forward ssh -L 8400:127.0.0.1:8400 quadwork → browse http://127.0.0.1:8400. Nothing published; the SSH key is the only credential; works with zero extra server config (request is loopback).
  • Option B: persistent public dashboard via nginx+SSL — now correctly documents that it requires trusted_dashboard_hosts in ~/.quadwork/config.json ([#968 regression] Reverse-proxy dashboard locked out of terminal WS — /api/session-token 403s the proxied Host #988) and Step 10 basic auth. Without the allowlist the proxied Host/Origin is rejected and every terminal WS dies (the previous guide was broken against current code).
  • Explicit warning: the server binds loopback only; never expose the raw control port unauthenticated.
• Port aligned to the current default 8400 (was 3000): dropped the port-3000 pre-create config; nginx proxy_pass → 127.0.0.1:8400.
• Multi-model parity: optional Gemini CLI install/auth alongside Claude/Codex; noted per-role backend choice; marked auth steps operator-required and interactive.
• Refreshed the Quick Reference to match.

EPIC Alignment

• Batch 24 ticket docs(install-vps): Modernize VPS installation and remove legacy chat migration prose #1007 owns only docs/install-vps.md. This diff touches exactly that file.
• Ticket requirements met: obsolete AgentChattr migration prose removed; remote control kept local-forward based; no unauthenticated control port; operator-required auth clearly separated.
• Out of scope, untouched: runtime code, package versions, tests, legacy cleanup/migration implementation, and quadwork-web.

Self-Verification

• Loopback bind: server/index.js:2324 → server.listen(PORT, "127.0.0.1", …). Default port 8400: bin/quadwork.js:253,864,911; init prompts port with default "8400" (bin/quadwork.js:864).
• Session token + proxy allowlist model: server/index.js:30-39 (auto-generated session_token), :102-113 (/api/session-token local-only, exception = isTrustedProxyRequest), :43-53 + :161-173 (trusted_dashboard_hosts, loopback-socket + allowlisted Host/Origin only), :180-193 (isLocalTokenRequest requires loopback IP+Host+Origin — SSH-forward satisfies this, so Option A needs no allowlist).
• pm2 process name quadwork: pm2 restart quadwork matches pm2 start … --name quadwork in Step 8.
• Multi-model: backends Claude/Codex/Gemini (src/components/SetupWizard.tsx:188-192, src/lib/agentModels.ts).
• Residual scan: rg -in "3000|agentchattr" docs/install-vps.md → no matches. Anchor #remote-access resolves to ## Remote Access.
• Scope: git diff --stat → docs/install-vps.md only.
• CI: pending on push.

Acceptance criteria

• Current Node, CLI, authentication, quadwork init, pm2, restart, remote-access, and file-chat guidance verified
• Obsolete AgentChattr cleanup/migration section removed
• Remote control local-forward based; no unauthenticated QuadWork control port exposed
• Operator-required authentication steps clearly separated
• No edits to legacy cleanup code, tests, or other files

[project7-interns]

Verdict: APPROVE

Epic Alignment: PASS

The one-file VPS guide advances #1007 by replacing obsolete migration prose with current, secure remote-access guidance and preserves #1008’s troubleshooting boundary.

Checked (evidence)

• Scope: live gh pr diff 1015 → only docs/install-vps.md; legacy cleanup code and tests are untouched.
• Security model: server/index.js:30-53,102-113,161-193,2324 confirms session-token gating, loopback-only bind, and allowlisted on-box authenticated proxy behavior.
• Lifecycle/port claims: bin/quadwork.js:850-870,947-1000 confirms default port 8400, init configuration, and PID-based start/stop behavior.
• Riskiest part of this diff: remote access; Option A retains loopback-only SSH forwarding, and Option B expressly requires both nginx basic auth and trusted_dashboard_hosts.
• Kill-list: scanned all new diff ranges — clean.
• CI: gh pr checks 1015 → test pass (52s).

Findings

• None.

Decision

The revised guide accurately describes current CLI/authentication, lifecycle, file-chat-era operation, and the security controls required for remote access.

[realproject7]

@re2 Independent Review — APPROVE ✅ (head c388f47)

Checked (evidence)

• Remote control stays local-forward based; no unauthenticated control port — Option A is SSH local-forward (ssh -L 8400:127.0.0.1:8400, nothing published). Option B correctly requires both an authenticating proxy (Step 10 basic auth) and the trusted_dashboard_hosts allowlist. Verified against isTrustedProxyRequest (server/index.js:161): empty allowlist → return false (no-op default); if (!isLocalhost(ip)) return false means it only applies to an on-box loopback proxy and never admits a direct remote connection; Host+Origin must both be allowlisted. The doc's framing ("takes effect only via the on-box loopback proxy… never lets a direct remote connection through… not a substitute for basic auth — configure both") is exactly accurate. ✓
• "WebSockets die without the allowlist" claim — matches the code comment at server/index.js:155-161: a foreign Host/Origin fails isTrustedProxyRequest → 403 / rejected upgrade. ✓
• Port aligned to 8400 — server binds 127.0.0.1:8400 (server/index.js:2324); quadwork init default 8400 (bin/quadwork.js:253/864/868); nginx proxy_pass → 8400. Stale port:3000 pre-create config dropped. ✓
• Obsolete AgentChattr migration prose removed — git show <head>:docs/install-vps.md | grep -inE "3000|agentchattr" → no matches. ✓
• Multi-model + operator auth — optional Gemini CLI install/auth added; per-role backend note; auth steps marked operator-required/interactive. Consistent with src/components/SetupWizard.tsx BACKENDS + src/lib/agentModels.ts. ✓
• Scope — docs/install-vps.md only (+68/−32); git diff --name-only origin/main → single file; no runtime/tests/package/legacy-cleanup/quadwork-web changes. ✓
• CI — gh pr checks 1015 → test pass (52s). ✓

Verdict: APPROVE on c388f47. (Recorded as a comment; shared bot account cannot self-approve on GitHub.)