docs: refresh database setup and env reference

.dockerignore

@@ -1,6 +1,6 @@
 # Never copy host-built artifacts into the image — they're built INSIDE the
-# Dockerfile. Critically, host node_modules carries darwin-arm64 native binaries
-# (better-sqlite3) that crash a linux container with "invalid ELF header".
+# Dockerfile. Host node_modules can carry platform-specific binaries that are
+# incompatible with the Linux container.
 node_modules
 **/node_modules
 .output

.env.example

@@ -16,6 +16,10 @@
 #     Both URLs must carry ?sslmode=require for Supabase/any remote Postgres (TLS).
 # DATABASE_URL=postgresql://USER:PASS@HOST.pooler.supabase.com:6543/postgres?sslmode=require
 # DIRECT_DATABASE_URL=postgresql://USER:PASS@HOST.supabase.com:5432/postgres?sslmode=require
+# Optional runtime pool-mode override for a transaction/session pooler on a
+# nonstandard port. Normally unset: :6543 is detected as transaction mode and
+# other ports as session mode. Set only when that heuristic is wrong.
+# LOOPANY_DB_POOL_MODE=transaction
 # LOOPANY_DB=pglite   # opt the BUILT server into the embedded tier (see tier 1)
 
 # --- data dir ---
@@ -59,6 +63,13 @@
 # Dev port (vite). Prod (nitro) reads PORT.
 LOOPANY_PORT=3000
 LOOPANY_LOG_LEVEL=info
+# Hosted-Postgres watchdog: pings the database and exits after a sustained wedge
+# so the process supervisor can restart it. ON by default with DATABASE_URL, OFF
+# for pglite/tests. Leave the tuning values unset unless the defaults need changing.
+# LOOPANY_DB_WATCHDOG=on
+# LOOPANY_DB_WATCHDOG_INTERVAL_MS=20000
+# LOOPANY_DB_WATCHDOG_TIMEOUT_MS=5000
+# LOOPANY_DB_WATCHDOG_FAILURES=3
 # Stuck-run reclaim: a claimed run that never reports is errored after this (ms).
 # LOOPANY_RUN_TIMEOUT_MS=1200000
 # Self-schedule cadence floors — enforced ONLY on the RUN self-schedule path (a

CONTRIBUTING.md

@@ -9,7 +9,8 @@ Loopany is a pnpm monorepo with two packages:
 
 - **`packages/server`** (`@loopany/server`, private) — the TanStack Start web app:
   UI + server functions + the in-process scheduler + machine/agent routes + Better
-  Auth + artifact storage. Drizzle/SQLite. Deployed on Fly.
+  Auth + artifact storage. Drizzle over Postgres (embedded pglite locally or an
+  external Postgres in production). Deployed on Fly.
 - **`packages/daemon`** (`@crewlet/loopany`, public on npm) — the machine-side
   daemon that runs on each user's own machine, polls the server for due runs, and
   executes them via the user's local coding agent (BYOA).
@@ -37,11 +38,14 @@ pnpm dev          # server on http://127.0.0.1:3000 (UI + scheduler + machine ro
 Copy `.env.example` to `packages/server/.env` if you need to configure auth,
 the artifact blob store, or other options. The app runs open (no auth) by default.
 
-> Changed `packages/server/src/db/schema.ts`? Generate and apply the migration
-> locally — dev does **not** auto-migrate:
+> Changed `packages/server/src/db/schema.ts` or `auth-schema.ts`? Generate the
+> migration before restarting the server. Embedded pglite applies generated
+> migrations automatically at boot; use `db:migrate` only when targeting an
+> external Postgres (with `DIRECT_DATABASE_URL` set when the runtime URL uses a
+> transaction pooler):
 > ```bash
 > pnpm --filter @loopany/server db:generate   # write the SQL + snapshot
-> pnpm --filter @loopany/server db:migrate     # apply to the dev DB
+> pnpm --filter @loopany/server db:migrate     # external Postgres only
 > ```
 
 ## Tests & typecheck