No Threading/Deployment Safety Documentation

[bradjin8]

Repository: cppa-cursor-browser
Assignee: Brad @bradjin8
Severity: Medium

Problem

The project's 15 HTTP endpoints are described informally in the README without threading caveats, and no standalone API reference or deployment guide exists. A deployer adding --threads 2 to gunicorn receives no signal from any layer — code, configuration, or documentation — that this will produce a data race on _workspace_path_override. The Flask app does not constrain its WSGI threading model, and the absence of a documented threading contract removes the last non-code mechanism that could warn about the safety constraint. Even after the race condition is fixed (item 2), deployers need guidance on supported configurations.

Acceptance Criteria

• A DEPLOYMENT.md (or a "Deployment" section in README) documents supported WSGI configurations and threading constraints
• The document explicitly states whether threaded deployment is supported and under what conditions
• The document covers: recommended WSGI servers (Werkzeug dev server, gunicorn, waitress), supported concurrency models (single-thread, multi-thread, multi-process), and any known limitations
• If the race condition from item 2 is fixed, document the threading guarantee; if not yet fixed, document the single-threaded-only constraint with a clear warning
• The document includes a quick-start deployment example for at least one production WSGI server
• The WORKSPACE_PATH environment variable's trust boundary is documented (already partially covered in README — consolidate)

Implementation Notes

This item should be sequenced after item 2 (thread-safety fix) so the documentation reflects the actual safety guarantees. If item 2 is not yet merged, write the documentation with a "single-threaded only" constraint and a TODO to update after the race is fixed. Cover: (a) why the default flask run is single-threaded and safe, (b) what breaks under --threads (if the race is unfixed), (c) recommended production setup (gunicorn with --workers but --threads 1), and (d) the pywebview desktop mode's threading model. Keep it concise — one page, not a deployment manual.

References

• Eval finding: test 16
• Cluster: threading-deployment-undocumented
• Related files: README.md, utils/workspace_path.py, app.py (Flask app factory / run configuration)
• Compounds: COMPOUND-B (race condition + missing documentation), COMPOUND-E (undocumented API + race condition)