added setup docs, updated contributing.md

Author: chetanr25

CONTRIBUTING.md

@@ -39,25 +39,12 @@ If you have a great idea for FireForm, we'd love to hear it! Please open an issu
 4. Make sure your code lints.
 5. Issue that pull request!
 
-## 🛠️ Local Development Setup
-
-FireForm uses Docker and Docker Compose for the backend to ensure a consistent environment.
-
-### Prerequisites
+**Issues are not formally assigned.** You are free to pick any open issue, work on it, and raise a PR directly. If multiple PRs address the same issue, the first one that actually fixes it generally gets preference. To avoid duplicating someone else's work, coordinate with other contributors on our [Discord](https://discord.gg/nBv5b6kF68) before starting.
 
-- [Docker](https://docs.docker.com/get-docker/)
-- [Docker Compose](https://docs.docker.com/compose/install/)
-- `make` (optional, but recommended)
-- [Node.js](https://nodejs.org/) 20+ (only needed for the desktop app)
+## 💬 Community
 
-### Desktop App Development
+Join our Discord server to ask questions, discuss issues, and coordinate work with other contributors: https://discord.gg/nBv5b6kF68
 
-The frontend is a vanilla HTML/CSS/JS app wrapped in Electron. To run it locally:
-
-```bash
-cd frontend
-npm install    # one-time setup
-npm start      # launches the Electron desktop window
-```
+## 🛠️ Local Development Setup
 
-The backend (API + Ollama) must be running separately via Docker — see `make fireform`.
+See the [Setup Guide](docs/SETUP.md) for the full walkthrough: prerequisites, running the backend with Docker, testing endpoints via Swagger UI, day-to-day commands, and troubleshooting.

docs/SETUP.md

@@ -0,0 +1,98 @@
+# Setup Guide
+
+This guide gets the FireForm backend running locally with Docker. It assumes you are comfortable with git and a terminal, but new to this project.
+
+## Prerequisites
+
+- [Docker](https://docs.docker.com/get-docker/) **24 or newer**, with the Docker daemon running
+- Docker Compose v2 (bundled with Docker Desktop; verify with `docker compose version`)
+- `make`
+- ~3 GB of free disk space (Docker images + LLM model weights)
+
+## Setup
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/fireform-core/FireForm.git
+cd FireForm
+```
+
+### 2. Run first-time setup
+
+```bash
+make init
+```
+
+This will:
+
+1. Check that Docker meets the requirements above
+2. Create `docker/.env.dev` from `docker/.env.example` (gitignored; defaults work out of the box)
+3. Prompt you to pick an Ollama model (the default, `qwen2.5:1.5b`, is the smallest and fine for development)
+4. Offer to build and start everything answer `y`, or run `make fireform` later
+
+### 3. Build and start (if you skipped it in step 2)
+
+```bash
+make fireform
+```
+
+This builds the Docker images, starts the containers, waits for Ollama, and pulls the LLM model. The first run takes several minutes (image build + model download); later runs are fast.
+
+When it finishes you'll see:
+
+```
+FireForm is ready!
+   API:      http://localhost:8000
+   API Docs: http://localhost:8000/docs
+```
+
+### 4. Verify it works
+
+Open **http://localhost:8000/docs** in your browser. This is the interactive Swagger UI you can explore and test every API endpoint directly from there (expand an endpoint, click _Try it out_, then _Execute_).
+
+## Day-to-day commands
+
+| Command      | What it does                                                             |
+| ------------ | ------------------------------------------------------------------------ |
+| `make up`    | Start containers                                                         |
+| `make down`  | Stop containers (data is preserved)                                      |
+| `make logs`  | Stream all container logs (`make logs-app` / `make logs-ollama` for one) |
+| `make shell` | Open a shell inside the app container                                    |
+| `make test`  | Run the test suite                                                       |
+| `make help`  | List all commands                                                        |
+
+The dev container mounts the source code, so code changes reload automatically — no rebuild needed. Rebuild (`make build`) only when dependencies in `requirements.txt` or the Dockerfile change.
+
+## Frontend (optional)
+
+The desktop/web frontend lives in a separate repository:
+
+```bash
+git clone https://github.com/fireform-core/fireform-frontend.git
+```
+
+Follow the README in that repository to run it. The backend from this guide must be running for the frontend to work.
+
+## Troubleshooting
+
+**`make init` fails dependency checks**
+Docker isn't running or is too old. Start Docker Desktop (or the Docker daemon) and confirm `docker version` reports 24+.
+
+**Port 8000 already in use**
+Another process is bound to the port. Either stop it, or change `APP_PORT` in `docker/.env.dev` and run `make down && make up`.
+
+**Model pull is slow or times out**
+The first `make fireform` downloads the LLM weights (~1 GB for the default model). On a slow connection just wait, or re-run `make pull-model` it resumes safely.
+
+**Containers start but the API doesn't respond**
+Check `make logs-app` for the actual error. The entrypoint runs database migrations on startup, so the API takes a few seconds after the container starts.
+
+**Want a clean slate**
+`make super-clean` stops everything and **deletes all volumes** database, uploads, and downloaded model weights. Only use it when you intend to wipe all local data.
+
+## Where to go next
+
+- **Join our [Discord](https://discord.gg/nBv5b6kF68)** — ask questions and coordinate with other contributors
+- [CONTRIBUTING.md](../CONTRIBUTING.md) - how to contribute
+- [docker/README.md](../docker/README.md) - Docker layout, env vars, and volumes in detail