chore: improve fresh instance onboarding experience

.env.example

@@ -1,53 +1,35 @@
-# Auth (run `node server/hash-password.js <your-password>` to generate)
-EA_PASSWORD_HASH=$2b$12$...
-EA_USER_ID=your-user-id
-
-# WebAuthn passkeys. Production requires all three and must use your HTTPS app origin.
-# Local dev defaults to Setpoint / localhost / http://localhost:5173 when unset.
-EA_WEBAUTHN_RP_NAME=Setpoint
-EA_WEBAUTHN_RP_ID=your-app-domain.com
-EA_WEBAUTHN_ORIGIN=https://your-app-domain.com
-
-# Playwright E2E auth (local only)
-PLAYWRIGHT_EA_PASSWORD=
-
-# EA Turso Database
+# Required production bootstrap. Render generates EA_ENCRYPTION_KEY; other hosts
+# must supply a 256-bit value encoded as 64 hex characters or standard base64.
 TURSO_DATABASE_URL=libsql://your-ea-db.turso.io
 TURSO_AUTH_TOKEN=
-
-# Encryption
 EA_ENCRYPTION_KEY=
+# Required only while claiming a fresh instance. Generate at least 32 random
+# characters and enter the same value on the first-run setup screen.
+EA_SETUP_TOKEN=
 
-# Anthropic (email triage and bill extraction)
+# Optional advanced host-managed provider sources. Normal setup stores these
+# write-only in Setpoint Settings; stored values take precedence over env values.
+# AI providers
 ANTHROPIC_API_KEY=
-
-# OpenAI (optional email AI, bill extraction, and inbox-search embeddings)
 OPENAI_API_KEY=
 
-# Opt-in only: run local dev against Turso/native vectors for inbox AI search
-# AI_SEARCH_VECTOR_ADAPTER=turso
-# EA_DEV_DB_ADAPTER=turso
-# EA_EMAIL_SEARCH_EMBEDDINGS_DISABLED=1
-
-# Dev: mock search analysis instead of calling Haiku
-# DEV_MOCK_SEARCH=1
-
 # Google OAuth (Gmail + Calendar)
 GOOGLE_CLIENT_ID=
 GOOGLE_CLIENT_SECRET=
-GOOGLE_REDIRECT_URI=https://your-app.onrender.com/api/ea/accounts/gmail/callback
 
-# Gmail Pub/Sub push ingestion
+# Calendar place enrichment and weather
+GOOGLE_PLACES_API_KEY=
+PIRATE_WEATHER_API_KEY=
+
+# Optional advanced Gmail real-time delivery
 GMAIL_PUBSUB_TOPIC=projects/your-project/topics/gmail-push
 GMAIL_PUBSUB_PUSH_TOKEN=
 
-# Todoist OAuth refresh + webhook verification (Todoist Developer app credentials).
-# Configure the public webhook callback URL in Todoist's app console:
-# https://your-app.onrender.com/api/todoist/webhook
+# Optional advanced Todoist OAuth + webhooks
 TODOIST_CLIENT_ID=
 TODOIST_CLIENT_SECRET=
 
-# Startup workers (optional). Production defaults delay workers 60-120s after
+# Optional operational tuning. Production defaults delay workers 60-120s after
 # listen, then add 2m before the passive indexer and 10m before backfill.
 EA_STARTUP_WORKER_DELAY_MS=
 EA_STARTUP_WORKER_JITTER_MS=
@@ -56,7 +38,23 @@ EA_STARTUP_BACKFILL_OFFSET_MS=
 EA_STARTUP_TODOIST_SYNC_OFFSET_MS=
 EA_EMAIL_BACKFILL_QUEUE_ON_STARTUP=
 
-# Actual Budget CLI (used by `npm run actual`; values mirror those stored encrypted in ea_settings)
+# Optional local-development switches
+# AI_SEARCH_VECTOR_ADAPTER=turso
+# EA_DEV_DB_ADAPTER=turso
+# EA_EMAIL_SEARCH_EMBEDDINGS_DISABLED=1
+# DEV_MOCK_SEARCH=1
+# PLAYWRIGHT_EA_PASSWORD=
+
+# Optional legacy compatibility for existing installations only. Fresh instances
+# create owner auth and confirm the canonical URL in the browser.
+# EA_PASSWORD_HASH=$2b$12$...
+# EA_USER_ID=your-user-id
+# EA_WEBAUTHN_RP_NAME=Setpoint
+# EA_WEBAUTHN_RP_ID=your-app-domain.com
+# EA_WEBAUTHN_ORIGIN=https://your-app-domain.com
+# GOOGLE_REDIRECT_URI=https://your-app.onrender.com/api/ea/accounts/gmail/callback
+
+# Actual Budget CLI only (`npm run actual`); runtime values live encrypted in Settings.
 ACTUAL_SERVER_URL=https://your-actual-server
 ACTUAL_PASSWORD=
 ACTUAL_SYNC_ID=

.github/workflows/ci.yml

@@ -38,8 +38,11 @@ jobs:
       - name: Lint
         run: npm run lint
 
-      - name: Test
-        run: npm test
+      - name: Test fast suite
+        run: npm run test:fast
+
+      - name: Test slow integrations
+        run: npm run test:slow
 
       - name: Check agent harness
         run: npm run check:harness

AGENTS.md

@@ -64,6 +64,14 @@ Prefer a layered Vitest structure. New behavior should usually start at the lowe
 
 When a broad test gets harder to maintain, extract the underlying rule into a named model/helper module before adding more cases. Good recent examples include `calendarModalInteractionModel`, `inboxCommandModel`, `dashboardShellModel`, `calendarRangeModel`, `currentDashboardModel`, `dashboardTaskProjection`, `inboxWorkItems`, and `snapshot-lifecycle`.
 
+### Test Suite Governance
+
+- Put new behavior at the lowest test layer that can express it; do not repeat shared policy as desktop, mobile, and page-level branch matrices.
+- Exact style or source-literal assertions require an adjacent explanation of the public compatibility contract they protect.
+- Every Vitest file must belong to exactly one project in `test-environment-partitions.mts`; pure tests use Node and DOM environments are explicit exceptions.
+- Test files above 600 lines require decomposition or a documented exception in `test-size-baseline.json`; grandfathered files may not grow past their allowance.
+- `npm run test:slow` remains required in CI and `npm test` remains the complete non-Playwright suite.
+
 ## Mechanical Checks
 
 - `npm run lint` - ESLint.