feat: onboard to dotenvx for env loading

.env.example

@@ -0,0 +1,14 @@
+# BetterAuth session signing key — `openssl rand -base64 32`
+BETTER_AUTH_SECRET=
+BETTER_AUTH_URL=http://localhost:3000
+
+# GitHub OAuth app — https://github.com/settings/developers
+GITHUB_CLIENT_ID=
+GITHUB_CLIENT_SECRET=
+
+# Postgres (matches docker-compose.yaml)
+DATABASE_URL=postgresql://skeleton:skeleton@localhost:5432/skeleton
+
+# Sentry Spotlight for local error/trace inspection
+SENTRY_SPOTLIGHT=1
+NEXT_PUBLIC_SENTRY_SPOTLIGHT=1

.gitignore

@@ -35,8 +35,13 @@ yarn-debug.log*
 yarn-error.log*
 .pnpm-debug.log*
 
-# env files
+# env files — dotenvx: commit .env.example and encrypted .env files; never commit decryption keys or local overrides
 .env*
+!.env.example
+!.env.vault
+.env.keys
+.env.local
+.env.*.local
 
 # vercel
 .vercel

CLAUDE.md

@@ -10,6 +10,8 @@ pnpm workspaces + Turborepo. Key commands:
 - `pnpm test` — run tests with coverage
 - `pnpm codegen:openapi` — generate OpenAPI spec from API routes
 
+Env vars are loaded via [dotenvx](https://dotenvx.com). `.env.local` at the repo root is the single source of truth — `pnpm dev` injects it into every task, so per-package `.env.local` files are not required. Use `pnpm exec dotenvx set KEY value -f .env.<env>` to commit encrypted secrets; decryption keys live in `.env.keys` (gitignored).
+
 ## Structure
 
 | Path                  | Role                                             |

README.md

@@ -56,7 +56,7 @@ Requires [VS Code](https://code.visualstudio.com/) with the [Dev Containers exte
 1. [Create a GitHub OAuth app](https://github.com/settings/developers) with callback URL `http://localhost:3000/api/auth/callback/github`
 2. Open VS Code and run **Dev Containers: Clone Repository in Container Volume** from the command palette
 3. Paste the repo URL and let the container build
-4. The container generates `.env.local` with sensible defaults. Fill in your GitHub OAuth credentials:
+4. The container generates `.env.local` with sensible defaults (template lives at `.env.example`). Fill in your GitHub OAuth credentials:
 
 ```bash
 GITHUB_CLIENT_ID=<your-client-id>
@@ -65,6 +65,22 @@ GITHUB_CLIENT_SECRET=<your-client-secret>
 
 5. Run `pnpm dev` and you're up
 
+### Environment variables
+
+Secrets are loaded through [dotenvx](https://dotenvx.com) — `pnpm dev` injects `.env.local` into every workspace task, so a single file at the repo root feeds the API, web, and Prisma. Use `.env.example` as the checked-in template.
+
+To commit secrets for a non-local environment, encrypt them first:
+
+```bash
+# set an encrypted value (creates .env.production if needed; keys go to .env.keys)
+pnpm exec dotenvx set GITHUB_CLIENT_SECRET "<value>" -f .env.production
+
+# run with a specific encrypted file
+pnpm exec dotenvx run -f .env.production -- pnpm start
+```
+
+`.env.local` and `.env.keys` are always gitignored. Encrypted files like `.env.production` are safe to commit — the decryption key stays in `.env.keys` (or a `DOTENV_PRIVATE_KEY_*` env var in production).
+
 ### What `pnpm dev` starts
 
 Open http://localhost:3000 to access the app. The other services are available from the admin sidebar after signing in:

apps/api/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "dev": "NODE_ENV=development tsx watch --env-file=.env.local src/index.ts",
+    "dev": "NODE_ENV=development dotenvx run --quiet -f ../../.env.local -- tsx watch src/index.ts",
     "build": "tsup src/index.ts --format esm",
     "start": "node dist/index.js",
     "lint": "tsc --noEmit",

package.json

@@ -3,24 +3,25 @@
   "private": true,
   "license": "MIT",
   "scripts": {
-    "dev": "bash .devcontainer/check-env.sh && (spotlight server & turbo dev test:ui)",
+    "dev": "bash .devcontainer/check-env.sh && dotenvx run --quiet --convention=nextjs -- bash -c 'spotlight server & turbo dev test:ui'",
     "build": "turbo build",
     "lint": "turbo lint",
     "format": "prettier --write .",
     "format:check": "prettier --check .",
     "codegen:openapi": "turbo codegen:openapi",
     "db:generate": "turbo db:generate",
-    "db:push": "turbo db:push",
+    "db:push": "dotenvx run --quiet --convention=nextjs -- turbo db:push",
     "test": "vitest run --coverage",
     "test:e2e": "pnpm --filter @skeleton/web test:e2e",
-    "test:ui": "vitest --ui --open false --changed",
-    "db:studio": "pnpm --filter @skeleton/db studio",
+    "test:ui": "dotenvx run --quiet --convention=nextjs -- vitest --ui --open false --changed",
+    "db:studio": "dotenvx run --quiet --convention=nextjs -- pnpm --filter @skeleton/db studio",
     "docker:up": "docker compose up -d",
     "docker:down": "docker compose down",
     "clean": "find . -name node_modules -o -name .turbo -o -name .next -o -name .pnpm-store | xargs rm -rf",
     "reset": "pnpm clean && pnpm install && pnpm build && pnpm dev"
   },
   "devDependencies": {
+    "@dotenvx/dotenvx": "^1.62.0",
     "@spotlightjs/spotlight": "^4.11.3",
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.5",

packages/db/package.json

@@ -9,10 +9,10 @@
     ".": "./src/index.ts"
   },
   "scripts": {
-    "dev": "prisma studio --port 5555 --browser none",
+    "dev": "dotenvx run --quiet -f ../../.env.local -- prisma studio --port 5555 --browser none",
     "db:generate": "prisma generate",
-    "db:push": "prisma db push",
-    "studio": "prisma studio"
+    "db:push": "dotenvx run --quiet -f ../../.env.local -- prisma db push",
+    "studio": "dotenvx run --quiet -f ../../.env.local -- prisma studio"
   },
   "dependencies": {
     "@prisma/adapter-pg": "^7.8.0",