Docs: OSS contribution guide and sample local database story

[kingRayhan]

Summary

Add a first-class open-source contribution guide so new contributors can clone the repo, get a working local environment (including a realistic or minimal database), and understand expectations before opening a PR.

Today, onboarding is spread across README.md and CLAUDE.md. There is no CONTRIBUTING.md, and there is no official sample/seed database or documented path to populate data for local UI testing.

Goals

1. CONTRIBUTING.md (or docs/contributing.md + link from README) covering:

   • Fork / branch / PR conventions (link to any existing style if applicable).
   • How to start the project end-to-end: Bun install, .env.local, bun run dev, expected URL.
   • Database setup: create DB, bun run db:push (and when to use db:generate), relationship to Drizzle vs SQLKit (high level).
   • Environment variables: what is strictly required to boot bun run dev vs optional (analytics/ClickHouse, Inngest, etc.) — today src/env.ts validates many vars; document minimal viable .env.local or track a follow-up to relax dev defaults.
   • Optional services: Meilisearch, WorkOS vs GitHub OAuth, R2/Cloudinary, Pusher/Soketi — what breaks if omitted and acceptable stubs for local-only hacking.
   • Quality bar: no automated tests; bun run play, bun run lint, bun run build as appropriate before PR.

2. Sample database story (pick one or combine; document the chosen approach):

   • Option A — Seed script: e.g. bun run db:seed (or documented play recipe) that inserts minimal users, one published article, tags, etc., with obvious fake emails and handles.
   • Option B — SQL fixture: checked-in anonymized dump or migrations/seed.sql applied after schema push, with clear warnings (never production data).
   • Option C — Docker Compose: postgres (+ optionally meilisearch) with documented DATABASE_URL and one-command up; seed optional.
   • Option D — Document “empty DB”: if we stay empty-only, explain how to register/login locally (WorkOS/GitHub) to create first user and content.

3. Cross-links: README “Contributing” section should point to the new guide; mention migrations/create-tables.sql / Drizzle only if it helps (avoid duplication).

Acceptance criteria

• New contributors can follow the doc from zero to running app + schema applied without asking in Discord for secret steps.
• Explicit answer to: “How do I get sample data?” (seed, fixture, compose, or auth-only path).
• Security: no real secrets in docs; reference .env.example if we add one.

Context

• Schema push: bun run db:push (see README).
• Resource analytics / ClickHouse: optional; see docs/resource-analytics-plan.md and migrations/clickhouse-schema.sql — not required for core blogging flows.

Labels suggestion

documentation, good first issue (for the writing task), or enhancement for maintainers to scope seed vs docs-only.