docs: add backend and web READMEs so each product has a setup path

CONTRIBUTING.md

@@ -8,14 +8,16 @@ Questions: [Discord](https://discord.gg/ejRNvftDp9) or [Discussions](https://git
 
 ## Getting set up
 
-This repo holds four products. You can clone all of it, then only run the tree you are changing — that is usually enough for a first PR.
+This repo holds four products. Clone it once, then open the README for the product you want to change. You do not need to run the other three.
 
-| Tree | Setup |
-|------|--------|
-| [`surfsense_local/`](surfsense_local/README.md) | Desktop app |
-| [`surfsense_mcp/`](surfsense_mcp/README.md) | MCP server (often the lightest first PR) |
-| `surfsense_backend/` | Scraper API / self-host backend |
-| `surfsense_web/` | Self-host web UI (`pnpm`, not npm) |
+| If you want to work on | Open |
+|------------------------|------|
+| Desktop app | [`surfsense_local/README.md`](surfsense_local/README.md) |
+| MCP server | [`surfsense_mcp/README.md`](surfsense_mcp/README.md) |
+| API / scrapers | [`surfsense_backend/README.md`](surfsense_backend/README.md) |
+| Self-host web UI | [`surfsense_web/README.md`](surfsense_web/README.md) |
+
+The web UI needs the API running. Desktop does not. MCP talks to any backend over HTTP.
 
 ```bash
 git clone https://github.com/<you>/SurfSense.git

surfsense_backend/README.md

@@ -0,0 +1,54 @@
+# SurfSense backend
+
+FastAPI app: scraper API, knowledge base, auth, and the self-host server.
+
+This is not the desktop sidecar. Desktop Python lives in [`surfsense_local/backend/`](../surfsense_local/backend/).
+
+## You need
+
+- Python 3.12+ and [uv](https://docs.astral.sh/uv/)
+- PostgreSQL with [pgvector](https://github.com/pgvector/pgvector)
+- Redis (background jobs)
+
+The smallest way to get Postgres and Redis is from the repo root:
+
+```bash
+docker compose -f docker/docker-compose.deps-only.yml up -d db redis
+```
+
+## Run it
+
+```bash
+cp .env.example .env
+uv sync
+uv run alembic upgrade head
+uv run main.py --reload
+```
+
+API: http://localhost:8000  
+Docs: http://localhost:8000/docs
+
+`.env.example` is the config map. For local Docker Postgres the default `DATABASE_URL` already matches `deps-only`. Set `SECRET_KEY` to something of your own. Leave `SUNSET_MODE` unset.
+
+Uploads, connectors, and other background work need a worker in a second terminal:
+
+```bash
+uv run celery -A celery_worker.celery_app worker --loglevel=info --concurrency=1 --pool=solo --queues=surfsense,surfsense.connectors,surfsense.gateway
+```
+
+Scheduled jobs need beat as well (`uv run celery -A celery_worker.celery_app beat --loglevel=info`). Skip both until you touch that path.
+
+## Tests
+
+```bash
+uv run pytest -m unit
+AUTH_TYPE=LOCAL uv run pytest -m integration   # needs Postgres
+```
+
+More on the suite: [tests/README.md](tests/README.md).
+
+## UI
+
+The Next.js app is [`surfsense_web/`](../surfsense_web/README.md). It talks to this API. You do not need it for a backend-only change.
+
+Full stack, Google auth, ETL keys, and zero-cache: [manual installation](../surfsense_web/content/docs/manual-installation.mdx).

surfsense_web/README.md

@@ -0,0 +1,48 @@
+# SurfSense web
+
+Next.js UI for the self-host stack (App Router, `pnpm`).
+
+This is not the desktop UI. Desktop frontend lives in [`surfsense_local/frontend/`](../surfsense_local/frontend/).
+
+## You need
+
+- Node.js 20+ and [pnpm](https://pnpm.io/installation) (not npm)
+- The API in [`surfsense_backend/`](../surfsense_backend/README.md) on http://localhost:8000
+
+## Run it
+
+```bash
+cp .env.example .env
+```
+
+In `.env`, point at a backend on your machine (the example file uses Docker hostnames):
+
+```bash
+NEXT_PUBLIC_FASTAPI_BACKEND_URL=http://localhost:8000
+SURFSENSE_BACKEND_INTERNAL_URL=http://localhost:8000
+AUTH_TYPE=LOCAL
+ETL_SERVICE=DOCLING
+DEPLOYMENT_MODE=self-hosted
+```
+
+Then:
+
+```bash
+pnpm install
+pnpm dev
+```
+
+App: http://localhost:3000
+
+Match `AUTH_TYPE` with the backend. Leave `SUNSET_MODE` unset.
+
+Live document/chat updates need [zero-cache](content/docs/manual-installation.mdx). Most UI PRs can run without it; the page just will not refresh itself.
+
+## Tests
+
+```bash
+pnpm test:unit
+pnpm format
+```
+
+Playwright needs Postgres, Redis, the API, and a worker. See [tests/README.md](tests/README.md).