.env.example

# Copy this file to .env.local and fill in what you need.
#
# You do NOT need every variable below to run this locally. The two biggest
# shortcuts (both dev-only, both already built into the app):
#
#   1. Leave KV_REST_API_URL / KV_REST_API_TOKEN blank. The app automatically
#      falls back to storing everything as JSON files under data/kv/ — full
#      functionality, zero Redis/Upstash account needed. See lib/kv.ts.
#
#   2. Set GITHUB_CLIENT_ID=ADMIN below. This skips the real GitHub OAuth
#      flow entirely and logs you in using your own GITHUB_TOKEN instead —
#      no OAuth App to register. This is hard-blocked in production (see
#      app/api/auth/github/route.ts), so it only works with `npm run dev`.
#
# With those two shortcuts, the only thing you actually need is a GitHub
# Personal Access Token (no special scopes — a token with no scopes at all
# works fine for public repo search): https://github.com/settings/tokens

# A GitHub Personal Access Token. Used for two things: raising the GitHub
# Search/REST API rate limit far above the ~60/hr unauthenticated limit, and
# (only if GITHUB_CLIENT_ID=ADMIN, see above) logging you in locally.
GITHUB_TOKEN=

# Password for the /admin dashboard. Pick anything for local dev.
ADMIN_PASSWORD=

# GitHub OAuth App credentials, for the real "Sign in with GitHub" flow.
# Not needed locally if you use the GITHUB_CLIENT_ID=ADMIN shortcut above.
# To register a real OAuth App instead: https://github.com/settings/developers
# (callback URL http://localhost:3000/api/auth/github/callback)
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=

# Shared secret the cron refresh workflow sends as the x-cron-secret header.
# Needed to run `npm run bootstrap-data` (populates real GitHub data into your
# local setup — see README.md "Seeing real data"); pick any random string.
CRON_SECRET=

# Upstash Redis REST credentials (upstash.com, free tier). Leave all three
# blank to use the on-disk fallback instead — see shortcut #1 above. If you
# do set these, use your OWN Upstash database, never the production one.
KV_REST_API_URL=
KV_REST_API_TOKEN=
KV_REST_API_READ_ONLY_TOKEN=

# AI assistant (POST /api/assistant + site-wide widget). Any
# OpenAI-compatible chat-completions endpoint works. Groq default shown;
# Cerebras: LLM_BASE_URL=https://api.cerebras.ai/v1
# Get a key: Groq https://console.groq.com/keys (free tier: 30 req/min),
# Cerebras https://cloud.cerebras.ai. Server-only — never NEXT_PUBLIC_.
LLM_BASE_URL=https://api.groq.com/openai/v1
LLM_API_KEY=
LLM_MODEL=openai/gpt-oss-20b
# Tool-using agent model for POST /api/agent (larger, tool-call capable).
# LLM_AGENT_MODEL=openai/gpt-oss-120b

# Emergency off-switch for the assistant (503s the route, widget shows the
# error). Set to 1 without redeploying to stop all LLM spend.
ASSISTANT_DISABLED=

# ---- Shared AI budget ----
# Measured against the Groq free tier (response headers, both models, one key):
#   x-ratelimit-limit-requests: 1000  -> per DAY
#   x-ratelimit-limit-tokens:   8000  -> per MINUTE
# One agent run costs up to MAX_ITERATIONS provider calls. These ceilings are
# global and apply on top of per-user limits, so no number of GitHub accounts
# can drain the day's quota. Defaults: 800 calls/day, 30 runs/min.
#
# SIZE THESE FOR THE KEY YOU DEPLOY WITH. On Groq's free tier (30 req/min per
# model, 200k tokens/day) 30 runs/min is already optimistic; on a paid or
# higher-tier key it can go up. A launch where 30-40 people test at once
# needs LLM_MINUTE_BUDGET of at least the number of testers.
# LLM_DAILY_BUDGET=800
# LLM_MINUTE_BUDGET=30

# Per-student agent limits, in runs. Defaults: 6/min, 40/day.
# AGENT_USER_BURST=6
# AGENT_USER_DAILY=40

# Output ceiling for one agent answer, in tokens. Default 1400 — a structured
# answer with headings, a code block, sources and a next step. Lower it on a
# provider with a tight tokens-per-minute wall.
# LLM_AGENT_MAX_TOKENS=1400

# Global daily cap on GitHub sign-in validations that miss the session cache.
# Default 5000. Raise only if legitimate students start seeing "we could not
# reach GitHub" during normal use.
# AUTH_CHECK_DAILY_BUDGET=5000

# ---- Rust agent sidecar (optional) ----
# When set, /api/agent proxies to the agent-rs service (BM25 RAG + tool loop
# in Rust; start it with `npm run agent`). Unset = pure TypeScript loop.
# The URL must be loopback and AGENT_SHARED_SECRET must be set: the caller's
# own GitHub OAuth token is forwarded in the request body, so anything else
# is refused and the request falls back to the in-process TypeScript loop.
# RUST_AGENT_URL=http://127.0.0.1:8787
# Shared secret both sides must agree on (any long random string).
# AGENT_SHARED_SECRET=

# --- Kairi agent: outbound knowledge services ---------------------------------
# Both are hosted, keyless and free — there is nothing to obtain or rotate.
#
#   web_search / read_url -> https://search.parallel.ai/mcp
#   explain_repo / repo_overview -> https://mcp.deepwiki.com/mcp
#
# Every web page the agent reads is fetched BY the search provider, never by
# this server. That is deliberate: a server-side fetch of a model-composed URL
# is an SSRF primitive into the cluster, and it cannot be fully closed in Node
# (validating a hostname and then calling fetch resolves DNS twice, so a
# rebinding attack passes the check and connects elsewhere). Routing through
# the provider means this process only ever connects to one fixed host.
#
# Set either to 1 to turn the dependency off; the agent degrades to its
# GitHub- and site-only tools rather than failing.
# WEB_SEARCH_DISABLED=1
# DEEPWIKI_DISABLED=1