docs: add .env.example and centralised Google setup guide

[Govindaroraaa]

Summary

Onboarding for the framework's required env vars was previously buried in the middle of the README and the Google client steps had to be reverse-engineered from the connector source. Closes #21.

• New .env.example at repo root, grouped by feature, every key commented and linking to its setup doc. Un-ignored in .gitignore so it stays tracked.
• New docs/setup/google.md lifting the existing Google Cloud Console walkthrough out of README.md (with prod vs local notes preserved).
• README.md quickstart now points at .env.example and the long Google block is replaced with a short stub linking to the setup doc.
• packages/@boringos/connector-google/README.md gains a "Setup" paragraph linking to the same doc.
• docs/INDEX.md adds the new setup doc.

Test plan

• cp .env.example .env.local, fill values, pnpm dev boots and Connectors → Google works.
• All new doc links resolve (README, connector-google README, docs/INDEX.md).

Made with Cursor

[parag]

Thanks — the structure of this is right (single .env.example, dedicated setup doc, README stub). The problem is that the docs claim a lot of things the code doesn't actually do, and the headline Google walkthrough has a port bug that means anyone following it via pnpm dev will hit redirect_uri_mismatch at the end. Requesting changes — most fixes are mechanical once you audit each entry against git grep process.env.

Blocking — OAuth setup will fail for any user following the README quickstart

scripts/dev-server.mjs:26 runs the backend on PORT (default 3030) and the shell on 5174 (vite.config.ts:201). The OAuth callback is built from the backend origin in connector-routes.ts:132:

${callerOrigin}/api/connectors/oauth/${kind}/callback

So under pnpm dev, Google needs to be registered with:

• Authorized JavaScript origins: http://localhost:5174 (where the shell lives) and/or http://localhost:3030 (where the OAuth start endpoint redirects from)
• Authorized redirect URIs: http://localhost:3030/api/connectors/oauth/google/callback

The new docs/setup/google.md lines 32–34 tell the user to register http://localhost:3000 everywhere — that's the legacy app.listen(3000) example port, not the pnpm dev port. Following the doc end-to-end produces an OAuth flow that fails. The README quickstart you point users at uses pnpm dev, so the doc has to match that path or it's broken on the golden path.

Also: README L210 still says "Then open http://localhost:3000" — that was wrong before this PR but the rest of this PR's content makes it more confusing, so worth fixing in the same change. The shell opens at 5174 under pnpm dev.

Fix options:

• Pick one path (the pnpm dev path, since that's what the quickstart uses) and write the doc against it: register http://localhost:3030/... as the redirect URI, open http://localhost:5174 to use the shell.
• If you want to keep the legacy 3000 example for create-boringos-scaffolded hosts, add a small "Which port?" callout that distinguishes pnpm dev (3030) from a user-scaffolded host (app.listen(<your-port>)).

Blocking — half of .env.example is aspirational, not real

I grepped process.env.* across all packages. Several entries the PR documents are never actually read by the framework or by scripts/dev-server.mjs:

Documented in .env.example	Read in code?	Reality
DATABASE_URL	✗	DB config is BoringOS({ database: { embedded, port, dataDir } }). No code path reads process.env.DATABASE_URL.
AUTH_SECRET	✗	config.auth.secret, not env. Never read from env.
HEBBS_ENDPOINT / HEBBS_API_KEY / HEBBS_WORKSPACE	✗	No references. Would need to be wired through a Hebbs memory provider config.
REDIS_URL	✗	BullMQ adapter takes { redis: string } as a config arg (packages/@boringos/pipeline/src/bullmq.ts:5), not an env var.
SLACK_SIGNING_SECRET / SLACK_BOT_TOKEN	✗ in framework, ✓ in create-boringos template only	scripts/dev-server.mjs calls createSlackModule directly with no signing-secret plumbing. These vars only do anything for a user-scaffolded host. Documenting them as framework env vars in the repo-root .env.example is misleading.

Vars that do work as documented: PORT, PG_PORT, BORINGOS_SHELL_URL, GOOGLE_CLIENT_ID/SECRET (via the dynamic ${KIND}_CLIENT_ID pattern in oauth.ts:68), RESEND_API_KEY, NOTIFICATION_FROM_EMAIL, HEBBS_DEV_MODULES, HEBBS_MODULE_PUBLISHERS, MODULES_STORE_DIR, BORINGOS_DEMO_FAKE_AI/_REPLY.

Missing from .env.example but actually read:

• BORINGOS_API_TARGET (shell vite config — lets a dev point the SPA at a non-default backend; useful for staging dev)
• TZ (current-time provider)

Two reasonable paths to fix:

(a) Wire the env vars into scripts/dev-server.mjs so the doc is accurate — read DATABASE_URL, AUTH_SECRET, REDIS_URL, HEBBS_*, SLACK_* and pass them through to the BoringOS({...}) config. This is the better product decision: users expect "drop secrets in .env.local and it works." Probably half a day of plumbing.

(b) Trim .env.example to reality. Remove every entry that isn't read, add a short note that scaffolded hosts (create-boringos) have their own .env.example listing the host-side vars. Faster.

I'd recommend (a) — the docs are downstream of the truth, and right now the truth is "you have to edit code to pass external Postgres." That's friction the framework should remove anyway. But (b) is acceptable.

Smaller things

• .env.example L39: SLACK_SIGNING_SECRET= (uncommented, empty) while everything else around it is commented. Either commit to commented-defaults everywhere, or commit to uncommented-with-empty-value. Mixing is confusing — empty SLACK_SIGNING_SECRET= is what Node sees as an empty string, which can trip code that checks if (process.env.X) differently than absent.
• docs/setup/google.md "Troubleshooting → redirect_uri_mismatch" — good addition, but the example interpolation <BORINGOS_SHELL_URL or http://localhost:3000> is wrong twice over: the redirect URI uses the backend origin (where the OAuth start endpoint runs), not BORINGOS_SHELL_URL (which is the SPA). Update to reflect actual behavior: the URL is built from the host the /api/connectors/oauth/<kind>/start request lands on (publicOrigin(c, baseUrl) in connector-routes.ts:70).
• docs/setup/google.md "Production hosts" — worth mentioning that production needs AUTH_SECRET set (once you wire it up) and HEBBS_MODULE_PUBLISHERS if running with signed modules. Right now those are framework-wide gotchas that get skipped.
• .gitignore: the !.env.example un-ignore pattern is correct. ✓

Test-plan note

The PR's test plan says "pnpm dev boots and Connectors → Google works." That can't have actually exercised the new doc end-to-end — the doc-as-written would have failed with redirect_uri_mismatch unless your existing Cloud Console OAuth client already had the correct port registered from before. Worth re-running the test by deleting and re-creating the OAuth client per the new doc, on a fresh checkout — that catches port bugs of exactly this kind. Same goes for following the .env.example-driven flow with DATABASE_URL set: it won't connect to your external Postgres because nothing reads that var.

Verdict

Docs PR with the right shape, blocked on correctness. Once the ports match pnpm dev reality and the .env.example either gets wired up or trimmed to truth, this is a clear improvement and merges easily. Push fixes to this branch and I'll re-review.

[AnishRane]

Nice to see .env.example landing. Two required vars are missing that I hit while testing connectors on a fresh setup:

1. BORINGOS_ENCRYPTION_KEY (critical). Every connector encrypts its OAuth tokens (AES-256-GCM) before writing to connector_accounts (@boringos/db crypto.ts → loadKey()). If it's unset, the callback throws BORINGOS_ENCRYPTION_KEY not set after a successful OAuth exchange, the account is never stored, and the UI just shows "Not connected" with no visible error. It silently broke both Google and Microsoft connect for me until I set it. It needs a 32-byte key, e.g.:

   # 32-byte key, hex or base64. Generate: openssl rand -hex 32
   BORINGOS_ENCRYPTION_KEY=
   

2. Microsoft connector vars (from feat(connector-microsoft): vendor in-tree as workspace package #64):

   MICROSOFT_CLIENT_ID=
   MICROSOFT_CLIENT_SECRET=
   

Since the file says it "documents every env var the framework reads," BORINGOS_ENCRYPTION_KEY is the most important one to include — it's effectively required for any connector to work.