perf(app): reduce redundant data fetching

Share bounded database pools across API repositories, consolidate sync and chat queries, and make mobile refreshes cache-aware and foreground-aware.

Add focused regression coverage, client freshness documentation, and repository agent role configuration.

apps/api/.env.example

@@ -3,6 +3,14 @@ DATABASE_URL=postgresql://sauci:sauci_local_only@127.0.0.1:54320/sauci
 SUPABASE_AUTH_URL=https://your-project.supabase.co
 SUPABASE_AUTH_AUDIENCE=authenticated
 
+# Optional connection-pool bounds. The API process opens one pool and shares it
+# across every repository, so these are the process-wide limits, not per-domain
+# ones. Raising DATABASE_POOL_MAX raises the server connections this instance can
+# hold; keep the total across instances inside the database's own limit.
+# DATABASE_POOL_MAX=10
+# DATABASE_POOL_IDLE_TIMEOUT_MS=30000
+# DATABASE_POOL_CONNECTION_TIMEOUT_MS=10000
+
 # Server-only hosted Auth Admin credential. Used for account deletion and for
 # enriching admin user lists; it is never exposed to the browser or used as a
 # Supabase database client.