docs: document server app port configuration and fallback guidance

[khaira777]

What Changed

• Documented the server app port (3003, SERVER_APP_PORT) across README.md, AGENTS.md, CONTRIBUTING.md, frontend/README.md, and .env.example.
• Added guidance in CONTRIBUTING.md and informational logging in kill-ports.js explaining automatic port fallback behavior and custom port configuration.
• Updated dev-server.js to dynamically log the API health check URL using getServerPort().

Risk Assessment

✅ Low: The changes are well-bounded documentation updates and minor log message adjustments clarifying port configuration and fallback behavior.

Testing

Exercised dev tooling script unit tests, server port collision fallback tests, kill-ports process identity and non-Flo process conflict handling, and verified documentation and dev-server logging; all checks passed cleanly.

Evidence: Port Guidance & Conflict Verification Log

=== FloCafe Port Guidance & Conflict Verification === 1. Testing kill-ports.js on free ports: [kill-ports] Port 39123 is free. [kill-ports] Port 39124 is free. [kill-ports] Port 39125 is free. -> Pass 2. Testing kill-ports.js behavior with non-Flo process holding port: [kill-ports] Port 39876: SKIP — PID 8269 (...) is not a Flo process. [kill-ports] Port 39876: no Flo processes found. 1 other process(es) using this port. [kill-ports] Note: Non-Flo process is holding port 39876. FloCafe will attempt fallback ports automatically on startup, or you can configure custom ports (PORT, KDS_PORT, SERVER_APP_PORT) in .env. -> Pass (non-Flo process preserved and helpful guidance emitted) 3. Verifying documentation updates: [x] .env.example contains SERVER_APP_PORT=3003 [x] CONTRIBUTING.md documents ports 3001, 3002, 3003 and fallback guidance [x] README.md includes Server App port 3003 in architecture diagram [x] dev-server.js dynamically uses getServerPort() for health log -> All checks passed successfully!

=== FloCafe Port Guidance & Conflict Verification ===

1. Testing kill-ports.js on free ports:
[kill-ports] Port 39123 is free.
[kill-ports] Port 39124 is free.
[kill-ports] Port 39125 is free.
-> Pass

2. Testing kill-ports.js behavior with non-Flo process holding port:
[kill-ports] Port 39876: SKIP — PID 8269 (/opt/homebrew/Cellar/node/26.7.0/bin/node -e \012    const http = require("http");\012    const server = http.createServer((req, res) => res.end("mock-response"));\012    server.listen(39876, "127.0.0.1", () => {\012      console.log("READY");\012    });\012) is not a Flo process.
[kill-ports] Port 39876: no Flo processes found. 1 other process(es) using this port.
[kill-ports] Note: Non-Flo process is holding port 39876. FloCafe will attempt fallback ports automatically on startup, or you can configure custom ports (PORT, KDS_PORT, SERVER_APP_PORT) in .env.
-> Pass (non-Flo process preserved and helpful guidance emitted)

3. Verifying documentation updates:
  [x] .env.example contains SERVER_APP_PORT=3003
  [x] CONTRIBUTING.md documents ports 3001, 3002, 3003 and fallback guidance
  [x] README.md includes Server App port 3003 in architecture diagram
  [x] dev-server.js dynamically uses getServerPort() for health log

-> All checks passed successfully!

Pipeline

Updates from git push no-mistakes

⏭️ **intent** - skipped

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

✅ **Review** - passed

✅ No issues found.

✅ **Test** - passed

✅ No issues found.

• npx ts-node --transpile-only -P tests/tsconfig.json tests/dev-tooling-scripts.test.ts
• node tests/run-electron-node-test.cjs tests/server-port-collision.test.ts
• node kill-ports.js 3001 3002 3003
• Port conflict and documentation verification suite checking non-Flo port retention, fallback guidance logging, and documentation consistency

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.

[greptile-apps]

Greptile Summary

This PR clarifies development port configuration and improves the accuracy of startup output.

• Documents the Main API, KDS, and Server App ports and their environment-variable overrides.
• Adds guidance when non-Flo processes occupy default ports.
• Uses the active API port in the development-server health URL.
• Adds the Server App to architecture and development-command documentation.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains from the prior review scope.

Important Files Changed

Filename	Overview
.env.example	Documents the Server App port environment variable alongside the existing port settings.
CONTRIBUTING.md	Documents all three development ports, fallback behavior, and available overrides.
README.md	Adds the Server App server to the architecture overview.
dev-server.js	Updates the health-check log to display the dynamically selected API port.
kill-ports.js	Adds guidance about fallback ports and custom configuration when a third-party process owns a port.

_{Reviews (2): Last reviewed commit: "no-mistakes(document): Update agent guid..." | Re-trigger Greptile}