diff --git a/.env.example b/.env.example
new file mode 100644
index 0000000..7bf1f99
--- /dev/null
+++ b/.env.example
@@ -0,0 +1,80 @@
+# =============================================================================
+# TPMJS Environment Variables
+# =============================================================================
+# Copy this file to .env.local and fill in the values.
+# NEVER commit .env files with real secrets!
+#
+# Required variables are marked with [REQUIRED]
+# Optional variables are marked with [OPTIONAL]
+# =============================================================================
+
+# -----------------------------------------------------------------------------
+# Database [REQUIRED]
+# -----------------------------------------------------------------------------
+# Neon PostgreSQL connection string (get from https://console.neon.tech)
+DATABASE_URL="postgresql://user:password@host/database?sslmode=require"
+DATABASE_URL_UNPOOLED="postgresql://user:password@host/database?sslmode=require"
+
+# -----------------------------------------------------------------------------
+# Authentication [REQUIRED for auth features]
+# -----------------------------------------------------------------------------
+# Better Auth secret - generate with: openssl rand -base64 32
+BETTER_AUTH_SECRET="your-32-char-minimum-secret-here"
+# Base URL for auth callbacks (optional, auto-detected in most cases)
+BETTER_AUTH_URL="http://localhost:3000"
+
+# -----------------------------------------------------------------------------
+# Cron Jobs [REQUIRED for sync endpoints]
+# -----------------------------------------------------------------------------
+# Secret for authenticating Vercel Cron requests - generate with: openssl rand -hex 32
+CRON_SECRET="your-64-char-hex-secret-here"
+
+# -----------------------------------------------------------------------------
+# API Key Encryption [REQUIRED for API key features]
+# -----------------------------------------------------------------------------
+# Secret for encrypting user API keys - generate with: openssl rand -base64 32
+API_KEY_ENCRYPTION_SECRET="your-encryption-secret-here"
+
+# -----------------------------------------------------------------------------
+# External Services [OPTIONAL]
+# -----------------------------------------------------------------------------
+# Resend - for sending emails (https://resend.com)
+RESEND_API_KEY="re_your_resend_api_key"
+
+# OpenAI - for AI features (https://platform.openai.com)
+OPENAI_API_KEY="sk-your-openai-api-key"
+
+# Vercel KV - for rate limiting (auto-configured on Vercel)
+KV_REST_API_URL="https://your-kv-instance.kv.vercel-storage.com"
+KV_REST_API_TOKEN="your-kv-token"
+
+# -----------------------------------------------------------------------------
+# Executor Services [OPTIONAL]
+# -----------------------------------------------------------------------------
+# Railway executor for tool execution
+RAILWAY_EXECUTOR_URL="https://your-railway-service.up.railway.app"
+
+# -----------------------------------------------------------------------------
+# Discord Integration [OPTIONAL]
+# -----------------------------------------------------------------------------
+DISCORD_SUMMARY_AGENT_ID="your-agent-id"
+DISCORD_GUILD_ID="your-guild-id"
+DISCORD_SUMMARY_CHANNEL_ID="your-channel-id"
+
+# -----------------------------------------------------------------------------
+# Public Variables (safe to expose to browser)
+# -----------------------------------------------------------------------------
+NEXT_PUBLIC_APP_URL="http://localhost:3000"
+NEXT_PUBLIC_API_URL="http://localhost:3000/api"
+
+# -----------------------------------------------------------------------------
+# Development/Testing [OPTIONAL]
+# -----------------------------------------------------------------------------
+NODE_ENV="development"
+
+# Integration test credentials (only for test environment)
+# INTEGRATION_TEST_SESSION_TOKEN="test-session-token"
+# INTEGRATION_TEST_API_KEY="test-api-key"
+# INTEGRATION_TEST_USER_ID="test-user-id"
+# INTEGRATION_TEST_USERNAME="test-username"
+# TEST_BASE_URL="http://localhost:3000"
diff --git a/.gitignore b/.gitignore
index 8050b04..9353235 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,7 +15,6 @@ dist
 
 # misc
 .DS_Store
-*.pem
 
 # debug
 npm-debug.log*
@@ -23,12 +22,30 @@ yarn-debug.log*
 yarn-error.log*
 pnpm-debug.log*
 
-# local env files
-.env*.local
+# environment files - NEVER commit secrets
 .env
+.env.*
+!.env.example
+.env.local
+.env.development
+.env.development.local
+.env.test
+.env.test.local
 .env.production
+.env.production.local
+.env.staging
 .env.vercel*
 
+# secret files
+*.pem
+*.key
+*.p12
+*.pfx
+credentials.json
+secrets.json
+*_secret*
+*_credentials*
+
 # turbo
 .turbo
 
diff --git a/.gitsecrets b/.gitsecrets
new file mode 100644
index 0000000..adf4b3d
--- /dev/null
+++ b/.gitsecrets
@@ -0,0 +1,49 @@
+# Secret patterns for git-secrets
+# Run `git secrets --add-provider -- cat .gitsecrets` to load these patterns
+# Or manually add with `git secrets --add '<pattern>'`
+
+# =============================================================================
+# TPMJS-specific patterns
+# =============================================================================
+
+# TPMJS API keys (format: tpmjs_sk_<base64>)
+tpmjs_sk_[A-Za-z0-9_-]+
+
+# =============================================================================
+# Database credentials
+# =============================================================================
+
+# Neon database passwords (format: npg_<alphanumeric>)
+npg_[A-Za-z0-9]+
+
+# PostgreSQL connection strings with embedded passwords
+postgresql://[^:]+:[^@]+@.*neon
+
+# Generic database URLs with passwords
+DATABASE_URL=.*://[^:]+:[^@]+@
+
+# =============================================================================
+# Generic secret patterns
+# =============================================================================
+
+# Long hex strings (API keys, tokens) - 64 chars like CRON_SECRET
+[a-f0-9]{64}
+
+# JWT tokens (common format)
+eyJ[A-Za-z0-9_-]*\.eyJ[A-Za-z0-9_-]*\.[A-Za-z0-9_-]*
+
+# Generic API key patterns
+[Aa][Pp][Ii][-_]?[Kk][Ee][Yy].*['"][A-Za-z0-9_-]{20,}['"]
+
+# =============================================================================
+# Cloud provider patterns (via --register-aws)
+# =============================================================================
+# AWS patterns are automatically registered with `git secrets --register-aws`
+# - AWS Access Key IDs: AKIA[0-9A-Z]{16}
+# - AWS Secret Access Keys
+
+# =============================================================================
+# Allowed patterns (false positive exclusions)
+# =============================================================================
+# Add allowed patterns with: git secrets --add --allowed '<pattern>'
+# Example: git secrets --add --allowed 'example\.com'
diff --git a/lefthook.yml b/lefthook.yml
index f10b730..e6d061d 100644
--- a/lefthook.yml
+++ b/lefthook.yml
@@ -1,6 +1,12 @@
 pre-commit:
   parallel: true
   commands:
+    secrets:
+      # Scan for secrets before allowing commit - runs first
+      priority: 1
+      run: git secrets --scan --cached
+      fail_text: "🚨 Secrets detected! Remove sensitive data before committing."
+
     format:
       glob: "*.{ts,tsx,js,jsx,json,md}"
       run: pnpm biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}