docs: add CONTRIBUTING.md + local dev guide

[mvanhorn]

Summary

Add CONTRIBUTING.md with a setup / migrations / embedding-server / troubleshooting guide that covers everything a first-time contributor needs between git clone and npm run dev. Every command documented was verified against package.json, docker-compose.yml, embedding-server/, and .env.example.

Why this matters

Issue #6 flagged the specific gap: a new contributor has to stitch together package.json, docker-compose.yml, and the prisma scripts by hand to get a working dev loop. The README covers the happy path at a high level but doesn't mention the embedding server's separate npm install, the Docker vs. host-API split, or any of the common first-run pitfalls (ECONNREFUSED from inside Docker, stale Prisma client after a branch switch, ports already in use).

Changes

• CONTRIBUTING.md (new, 144 lines):
  • Prerequisites (Node 20+ to match the Dockerfile, Docker Compose, npm)
  • Clone + install - root and embedding-server/ separately, matching their two package.json files
  • Environment - copy .env.example and fill the four keys shown there (EMBEDDING_API_URL, EMBEDDING_VERSION, EMAILOCTOPUS_API_KEY, EMAILOCTOPUS_LIST_ID)
  • Two Docker modes: full docker compose up --build, or docker compose up -d postgres + npm run dev when hot-reload matters
  • Prisma migrations: prisma:generate, prisma:migrate, prisma:push for rapid dev
  • Running the embedding server on port 3001 with a note on the deterministic mock-vector behaviour in embedding-server/index.js
  • npm run build / npm start for the production path
  • Troubleshooting: the four most likely first-run hits - host.docker.internal for cross-network calls, docker compose down -v to reset the Postgres volume when the DB doesn't exist, npm run prisma:generate after pulling (generated client isn't checked in), and port-in-use on 3000/3001

What was intentionally skipped

Issue #6 mentions a "Zoho OAuth" troubleshooting bullet. No Zoho integration exists in the repo yet (grep -rn "zoho" --include="*.ts" --include="*.md" returns nothing). Rather than fabricate setup steps for a feature that isn't there, this PR leaves that bullet out - the note can land alongside the Zoho feature when it merges.

Fixes #6

This contribution was developed with AI assistance (Claude Code).

[szverev]

Good structure and a welcome addition. Two issues would break a contributor's setup before they write any code — flagging those as blockers. The rest are minor corrections.

Blocking

1. DATABASE_URL in .env.example uses postgres as the hostname, which only resolves inside the Docker Compose network. Steps 3 (hybrid mode: docker compose up -d postgres + npm run dev on host) and 4 (running migrations on the host) both fail immediately with getaddrinfo ENOTFOUND postgres. The guide never instructs contributors to change the hostname to localhost for host-side commands.

2. The pure docker compose up --build path never applies migrations. The Dockerfile only runs prisma generate; CMD is npm run dev. Tables are never created inside the container, so every API call fails with relation does not exist. Either add prisma migrate deploy to the container startup, or add a clear note that migration must be run separately before the API is usable.

Minor

• Prerequisites say "Dockerfile targets node:20-alpine" — actual base image is FROM node:20 (Debian Bookworm).
• Step 2 prose says "fill the three API-key values" but the table has four rows.
• EMBEDDING_API_URL=http://localhost:3001 example is wrong for Docker mode (resolves to the container itself, not the host); host.docker.internal:3001 is needed. The troubleshooting section mentions this but only as a post-hoc fix.
• Troubleshooting describes prisma:migrate "hanging" — the actual failure on a bad DATABASE_URL is an immediate crash (ENOTFOUND), not a hang, which sends contributors down the wrong diagnostic path.

[mvanhorn]

Thanks — addressed both blockers and the four minors:

• Host-side commands now use a localhost DATABASE_URL (called out in steps 2, 3, and 4), so npm run dev and the Prisma commands don't hit getaddrinfo ENOTFOUND postgres.
• Added a note that Docker Compose doesn't auto-apply migrations, so step 4 must be run once on a fresh DB before the API endpoints work.
• Fixed the node:20 base image, the three→four values count, the EMBEDDING_API_URL host.docker.internal case for Docker mode, and the troubleshooting entry (immediate ENOTFOUND crash, not a hang).