Add contributing guide

CONTRIBUTING.md

@@ -0,0 +1,90 @@
+# Contributing to Odysseus
+
+Thanks for helping. The project is moving quickly, so the best contributions are focused, easy to review, and easy to test.
+
+## Before You Start
+
+- Search existing issues and pull requests before opening a new one.
+- Prefer one bug fix or feature per pull request.
+- Avoid broad rewrites, formatting-only changes, or moving many files unless the issue is specifically about structure.
+- If you want to work on a large feature, open an issue first and describe the approach.
+
+## Setup
+
+Docker is the recommended path for normal testing:
+
+```bash
+git clone https://github.com/pewdiepie-archdaemon/odysseus.git
+cd odysseus
+cp .env.example .env
+docker compose up -d --build
+```
+
+Manual development uses Python 3.11+:
+
+```bash
+python3 -m venv venv
+source venv/bin/activate
+pip install -r requirements.txt
+python -m uvicorn app:app --host 0.0.0.0 --port 7000
+```
+
+Windows is not actively tested. Docker on Linux or a Linux/macOS manual install is the safer path for now.
+
+## Running Checks
+
+Run the smallest relevant checks for your change:
+
+```bash
+python -m pytest
+python -m py_compile app.py routes/*.py src/*.py
+node --check static/js/<file-you-changed>.js
+```
+
+For Docker-related changes:
+
+```bash
+docker compose config
+docker compose up -d --build
+docker compose logs --tail=120 odysseus
+```
+
+Mention what you ran in the pull request description. If you could not run a check, say so.
+
+## Pull Requests
+
+Good pull requests usually include:
+
+- A short explanation of the bug or feature.
+- The files or areas changed.
+- Manual test steps or automated test results.
+- Screenshots or short recordings for UI changes.
+- Links to related issues, for example `Fixes #123`.
+
+Please keep PRs small. Large PRs that mix unrelated cleanup, formatting, refactors, and behavior changes are much harder to review.
+
+## Issue Reports
+
+For bugs, include:
+
+- Install method: Docker, manual Python, WSL, etc.
+- OS, browser, and device if relevant.
+- Exact steps to reproduce.
+- Expected behavior and actual behavior.
+- Logs, screenshots, or terminal output.
+
+For model-serving issues, include:
+
+- Backend: Ollama, vLLM, SGLang, llama.cpp, LM Studio, etc.
+- Model name.
+- GPU/CPU and operating system.
+- Cookbook task logs or server logs.
+
+Issues with only "help", "does not work", or a screenshot without context may be closed as not actionable.
+
+## Security
+
+Do not post secrets, API keys, private logs, personal documents, or public IPs in issues or pull requests.
+
+For security reports, follow [SECURITY.md](SECURITY.md).
+

README.md

@@ -44,6 +44,9 @@ to override deployment-level things like `AUTH_ENABLED`, `DATABASE_URL`,
 or pre-seed `ODYSSEUS_ADMIN_PASSWORD` (otherwise an initial password is
 generated and printed on first boot).
 
+Contributing? See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and
+pull request guidelines.
+
 ### Option 1: Docker (recommended)
 ```bash
 git clone https://github.com/pewdiepie-archdaemon/odysseus.git