docs: improve contributing and environment setup guidance

Author: IamCoder18

.env.local.example

@@ -12,6 +12,11 @@ NEXTAUTH_URL=http://localhost:3000
 POSTGRES_URL=postgresql://postgres:postgres@localhost:5432/postgres
 POSTGRES_CONNECT_TIMEOUT=10000
 POSTGRES_MAX_QUERY_TIME=20000
+# Callback token secret (generate: openssl rand -base64 32)
+CALLBACK_TOKEN_SECRET=changeme
+# BYOK encryption key (generate: openssl rand -base64 32)
+# Used for Bring-Your-Own-Key encryption of sensitive app data.
+BYOK_ENCRYPTION_KEY=
 # ============================================================================
 # REQUIRED - Security & Turnstile
 # ============================================================================
@@ -131,7 +136,6 @@ SENTRY_ORG=
 SENTRY_PROJECT=
 NEXT_PUBLIC_SENTRY_DSN=
 # Encryption keys (generate if needed)
-BYOK_ENCRYPTION_KEY=
 CREDIT_CATEGORIES_ENCRYPTION_KEY=
 # Connected GitHub user token envelope encryption (dedicated RSA public key only in Web)
 USER_GITHUB_APP_TOKEN_ACTIVE_KEY_ID=

CONTRIBUTING.md

@@ -35,13 +35,35 @@ pnpm install
 
 ### 2. Set up environment variables
 
-If you do not have Vercel access, copy `.env.local.example` to `.env.local` and set at least:
+Copy `.env.local.example` to `.env.local` and adjust URLs as needed:
 
-- `NEXTAUTH_SECRET`: `openssl rand -base64 32`
-- `INTERNAL_API_SECRET`: `openssl rand -base64 32`
+- `NEXTAUTH_URL` — auth redirect URL (defaults to `http://localhost:3000`)
+- `POSTGRES_URL` — database connection (defaults to `postgres://postgres:postgres@localhost:5432/postgres`)
+
+Then generate secrets and add Stripe test keys:
+
+```bash
+openssl rand -base64 32   # NEXTAUTH_SECRET
+openssl rand -base64 32   # INTERNAL_API_SECRET
+openssl rand -base64 32   # CALLBACK_TOKEN_SECRET
+openssl rand -base64 32   # BYOK_ENCRYPTION_KEY
+```
+
+Get Stripe test keys from https://dashboard.stripe.com/test/apikeys.
+
+Required in `.env.local`:
+
+- `NEXTAUTH_SECRET`
+- `INTERNAL_API_SECRET`
+- `CALLBACK_TOKEN_SECRET`
+- `BYOK_ENCRYPTION_KEY`
+- `STRIPE_SECRET_KEY`
+- `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`
 
 Then run `pnpm dev:env` to derive worker `.dev.vars` files from `.env.local`.
 
+For the full list of environment variables, see [ENVIRONMENT.md](./ENVIRONMENT.md).
+
 ### 3. Start the database
 
 ```bash

ENVIRONMENT.md

@@ -65,6 +65,7 @@ This document lists all environment variables used in the Kilo Code cloud monore
 - `STYTCH_PROJECT_SECRET` - Stytch project secret. `[SECRET]`
 - `STYTCH_PUBLIC_TOKEN` - Stytch legacy public token alias used in some test fixtures. [PUBLIC]
 - `INTERNAL_API_SECRET` - Shared secret for internal API calls between services; used in `apps/web/src/lib/kiloclaw/cli-runs.test.ts`, `kiloclaw-router.test.ts`, dev seed scripts, and other service routers. `[SECRET]`
+- `CALLBACK_TOKEN_SECRET` - Secret for signing callback tokens. Required for local development. `[SECRET]`
 - `INTERNAL_SECRET` - Alias/fallback for `INTERNAL_API_SECRET`; used in KiloClaw E2E scripts (`services/kiloclaw/e2e/`). `[SECRET]`
 
 ### Social OAuth Clients
@@ -342,7 +343,6 @@ This document lists all environment variables used in the Kilo Code cloud monore
 
 - `DOCKER_SOCKET` - Path or URL for the Docker daemon socket; used by `services/cloud-agent-next/scripts/docker-privileged-proxy.mjs`. [SERVER]
 - `DOCKER_PROXY_SOCKET` - Path to the Docker privileged proxy socket. [SERVER]
-- `CALLBACK_TOKEN_SECRET` - Secret for signing callback tokens. `[SECRET]`
 - `SECRET` - Generic secret env var used in `services/kiloclaw/src/auth/sandbox-id-adversarial.test.ts` for sandbox auth tests. `[SECRET]`
 
 ## Mobile
@@ -376,5 +376,3 @@ This document lists all environment variables used in the Kilo Code cloud monore
 - `E2E_MODEL` - Model identifier string for E2E inference tests (e.g. a fake/small model name). [SERVER]
 - `KILOCLAW_USER_LOCATION` - User location parameter for lifecycle tests of the morning briefing plugin. [SERVER]
 - `KILOCLAW_USER_TIMEZONE` - User timezone parameter for lifecycle tests of the morning briefing plugin. [SERVER]
-
-