docs(contributing): fix stale DB driver and dev-migration claims

[rhzs]

Doc Maintainer sweep 2026-07-16

First scheduled docs sweep. Reviewed the user-facing documentation at `origin/main` (`752755d`) against the implementation and found two materially stale claims in `CONTRIBUTING.md`. No other user-facing docs (README, daemon README, `docs/`, package scripts, CLI help) drifted.

Finding 1 — wrong database driver: `Drizzle/SQLite`

Claim (CONTRIBUTING.md, Repo layout): `Drizzle/SQLite. Deployed on Fly.`

Evidence it's wrong:

• `packages/server/drizzle.config.ts` → `dialect: "postgresql"`.
• `packages/server/src/db/index.ts` tiers between embedded pglite (WASM Postgres, when `DATABASE_URL` is unset) and postgres-js over external Postgres (when set). There is no SQLite anywhere.
• `README.md` already describes it correctly as "embedded, file-backed pglite Postgres" / "Postgres + object store for production".

Fix: `Drizzle over Postgres (embedded pglite for local dev, external Postgres in production).`

Finding 2 — wrong dev-migration guidance: "dev does not auto-migrate"

Claim (CONTRIBUTING.md, Run the server locally): `Generate and apply the migration locally — dev does not auto-migrate` with `db:migrate` described as "apply to the dev DB".

Evidence it's wrong:

• `packages/server/src/server/boot.ts` → `ensureServer()` calls `runMigrations()` on every boot.
• `packages/server/src/db/index.ts` `runMigrations()`: for the pglite driver it runs `drizzle-orm/pglite/migrator` in-process; it is a no-op only for the hosted Postgres driver. So `pnpm dev` (pglite tier) does auto-apply generated migrations at boot.
• `packages/server/drizzle.config.ts` comment: "The embedded pglite tier migrates in-process (`db/index.ts runMigrations`), not via this CLI." `db:migrate` (drizzle-kit CLI) targets a real Postgres over the direct `:5432` URL and errors on an empty `DATABASE_URL` — it does not apply to the pglite dev DB.
• `README.md` already says pglite "migrates itself at boot".

Fix: `db:generate` authors the SQL (no DB needed); the default embedded pglite dev tier auto-applies it at boot, so restart `pnpm dev`. `db:migrate` is scoped to real-Postgres development (`DATABASE_URL`/`DIRECT_DATABASE_URL`).

Changes

• `CONTRIBUTING.md`: corrected the DB driver line and rewrote the schema-change migration note (9 insertions, 4 deletions).

Verification

• Inspected the owning implementation for each claim (`db/index.ts`, `boot.ts`, `drizzle.config.ts`, `env.ts`) rather than editing from memory.
• Confirmed no other `SQLite`/`websocket`/`auto-migrate` drift in user-facing docs (README, daemon README, `docs/`, CLI help are accurate).
• No code changed; documentation-only.

Follow-up

• Optional (not in this PR): `packages/server/package.json` `description` still says "machine WS gateway" — the transport is HTTP long-poll, not WebSocket. Left out of this PR as it is private-package metadata, not user-facing doc prose. Worth a one-line cleanup in a future sweep.